perplexity-user-mcp 0.8.39 → 0.8.44

package/dist/daemon/oauth-consent-cache.d.ts

@@ -0,0 +1,86 @@
+/**
+ * OAuth consent cache — remembers per-(clientId, redirectUri, resource)
+ * consents so the user isn't prompted every time Claude Desktop / Cursor /
+ * Cline refreshes an access token (which happens on a ~1h cycle).
+ *
+ * Storage: <configDir>/oauth-consent.json, 0600.
+ * Entries carry an absolute `expiresAt` (ms since epoch). On each check
+ * we lazily prune expired entries. Deleting a record is synchronous and
+ * best-effort (if the file is locked we lose the mutation; next write
+ * will overwrite it).
+ *
+ * Key structure: `(clientId, redirectUri, resource)`. After Phase 8.2 H12
+ * the OAuth `resource` parameter (RFC 8707) is part of the audience binding,
+ * so a consent granted for `https://tunnel-a.example/mcp` must NOT
+ * auto-approve a new authorize request for `https://tunnel-b.example/mcp`
+ * even though the clientId + redirectUri match. `resource === undefined` is
+ * a distinct key from any bound resource string — unbound consents (legacy
+ * / loopback clients that don't send the `resource` param) don't
+ * auto-approve bound-resource consents and vice-versa.
+ *
+ * Revoking a consent entry does NOT invalidate already-issued access
+ * tokens — those live 1h anyway; revoking the CLIENT (see
+ * oauth-provider.revokeClient) is the way to invalidate outstanding
+ * tokens. Phase 8.2's dashboard panel composes these two.
+ */
+export interface ConsentEntry {
+    clientId: string;
+    redirectUri: string;
+    approvedAt: string;
+    expiresAt: number;
+    /**
+     * RFC 8707 resource binding. `undefined` = unbound (legacy / loopback
+     * clients that don't send the `resource` param at /authorize). Two entries
+     * with the same (clientId, redirectUri) but different `resource` values
+     * (including undefined-vs-string) are DISTINCT cache keys.
+     */
+    resource?: string;
+}
+export interface ConsentCacheOptions {
+    cachePath?: string;
+    now?: () => number;
+    /**
+     * Resource the authorize request targets. Must match `ConsentEntry.resource`
+     * exactly for a check hit (undefined matches undefined; a string matches
+     * the same string; any mismatch is a miss).
+     */
+    resource?: string;
+}
+export declare function getConsentCachePath(configDir?: string): string;
+/**
+ * Record an approval for (clientId, redirectUri, resource). Overwrites any
+ * prior entry for the SAME triple only — entries that share clientId +
+ * redirectUri but have a different `resource` (including bound-vs-unbound)
+ * are preserved as separate consents.
+ */
+export declare function record(clientId: string, redirectUri: string, ttlMs: number, options?: ConsentCacheOptions): ConsentEntry;
+/**
+ * Returns true iff a non-expired consent exists for the full triple
+ * (clientId, redirectUri, resource). `resource === undefined` is a distinct
+ * key from any bound resource string. Expired entries are pruned from disk
+ * as a side effect.
+ */
+export declare function check(clientId: string, redirectUri: string, options?: ConsentCacheOptions): boolean;
+/**
+ * Returns all non-expired consents. Expired entries are pruned on read.
+ */
+export declare function list(options?: ConsentCacheOptions): ConsentEntry[];
+/**
+ * Revoke consent entries. Filter hierarchy:
+ *   - `{}` (no filter)                                   → revoke everything
+ *   - `{ clientId }`                                     → revoke every entry for that client (all redirects, all resources)
+ *   - `{ clientId, redirectUri }`                        → revoke every entry for that (client, redirect) (all resources)
+ *   - `{ clientId, redirectUri, resource }`              → revoke only the exact triple
+ *   - `{ clientId, resource }`                           → revoke every entry for that client scoped to the given resource
+ *
+ * A `resource` filter value of `undefined` means "do not filter by resource"
+ * (NOT "match unbound entries"). To revoke only unbound entries for a client,
+ * enumerate via `list()` + call revoke per-entry — the filter API deliberately
+ * treats `resource === undefined` as "any" to match pre-H12 callers.
+ *
+ * Returns the number of entries removed.
+ */
+export declare function revoke(options?: ConsentCacheOptions & {
+    clientId?: string;
+    redirectUri?: string;
+}): number;

package/dist/daemon/oauth-provider.d.ts

@@ -0,0 +1,132 @@
+/**
+ * OAuth 2.1 authorization-server provider for the Perplexity MCP daemon.
+ *
+ * Implements the MCP SDK's `OAuthServerProvider` interface. Plugs into
+ * `mcpAuthRouter()` to expose `/authorize`, `/token`, `/register`, `/revoke`
+ * and the `/.well-known/*` metadata endpoints.
+ *
+ * Design:
+ *   - Clients are persisted in `<configDir>/oauth-clients.json` (0600).
+ *   - Authorization codes are in-memory, 2-min TTL, single-use.
+ *   - Access tokens are in-memory, 1-hour TTL.
+ *   - Refresh tokens rotate on each exchange.
+ *   - `verifyAccessToken` accepts either a valid OAuth access token OR the
+ *     daemon's static bearer, so existing loopback callers (extension host
+ *     + CLI) keep working with no changes.
+ *   - `authorize()` defers to a caller-supplied `requestConsent` callback
+ *     which the daemon wires to the VS Code extension's modal. Until the
+ *     user approves or the 2-min timeout elapses, the HTTP response is
+ *     held open.
+ */
+import type { Response } from "express";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { OAuthRegisteredClientsStore } from "@modelcontextprotocol/sdk/server/auth/clients.js";
+import type { AuthorizationParams, OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { OAuthClientInformationFull, OAuthTokenRevocationRequest, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import * as consentCache from "./oauth-consent-cache.js";
+export interface OAuthProviderOptions {
+    configDir: string;
+    /**
+     * Invoked when a browser hits `/authorize`. Must resolve to `true`
+     * (approve) or `false` (deny). The daemon wires this to the VS Code
+     * modal via an SSE-based consent coordinator.
+     *
+     * `resource` is the RFC 8707 resource the authorize request targets
+     * (post-H12). The consent UI MUST display this value so users can spot
+     * cross-resource replay attempts. `undefined` means the client did not
+     * send a `resource` param (legacy / loopback flow).
+     */
+    requestConsent: (info: {
+        clientId: string;
+        clientName: string;
+        redirectUri: string;
+        consentId: string;
+        resource?: string;
+    }) => Promise<boolean>;
+    /** Live getter so rotate-token stays supported. */
+    getStaticBearer: () => string;
+    /**
+     * Live getter for the consent-cache TTL in ms. `0` disables the cache
+     * (modal fires every time). Read live per-authorize so toggling the
+     * setting takes effect on the next request without restarting the
+     * provider.
+     */
+    getConsentCacheTtlMs?: () => number;
+    /**
+     * Fires just before the authorize response is sent when the provider
+     * decided to auto-approve from the consent cache. server.ts uses this
+     * to flip the request's audit tag from `none` to `oauth-cached` so
+     * the audit log records the cache hit distinctly.
+     */
+    onConsentCacheHit?: (info: {
+        clientId: string;
+        redirectUri: string;
+        res: Response;
+    }) => void;
+}
+export interface AuthorizedClientSummary {
+    clientId: string;
+    clientName?: string;
+    registeredAt: number;
+    lastUsedAt?: string;
+    consentLastApprovedAt?: string;
+    activeTokens: number;
+}
+export declare class PerplexityOAuthProvider implements OAuthServerProvider {
+    private readonly options;
+    private codes;
+    private tokens;
+    private clients;
+    private clientsPath;
+    private consentCachePath;
+    constructor(options: OAuthProviderOptions);
+    get clientsStore(): OAuthRegisteredClientsStore;
+    authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
+    private issueAuthorizationCode;
+    challengeForAuthorizationCode(_client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;
+    exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string, codeVerifier?: string, redirectUri?: string, resource?: URL | string): Promise<OAuthTokens>;
+    exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[], resource?: URL | string): Promise<OAuthTokens>;
+    verifyAccessToken(token: string, source?: "loopback" | "tunnel", expectedResource?: string): Promise<AuthInfo>;
+    revokeToken(_client: OAuthClientInformationFull, request: OAuthTokenRevocationRequest): Promise<void>;
+    listClients(): AuthorizedClientSummary[];
+    revokeClient(clientId: string): boolean;
+    /**
+     * Revoke every registered OAuth client and invalidate all outstanding
+     * access/refresh tokens. Returns the count of clients that were removed.
+     * Cached consents for every revoked client are also purged so a
+     * future registration with a colliding id cannot silently inherit them.
+     */
+    revokeAllClients(): number;
+    listConsents(): consentCache.ConsentEntry[];
+    revokeConsent(clientId?: string, redirectUri?: string): number;
+    private issueTokenPair;
+    private loadClients;
+    private persistClients;
+}
+/**
+ * Coordinator for /authorize ↔ /daemon/oauth-consent round-trip.
+ *
+ * `request()` starts a new pending consent and returns a Promise that resolves
+ * when the extension host POSTs `/daemon/oauth-consent` with the matching id.
+ * Times out after the given ms (denying by default).
+ */
+export declare class ConsentCoordinator {
+    private pending;
+    request(options: {
+        id: string;
+        clientId: string;
+        clientName: string;
+        redirectUri: string;
+        resource?: string;
+        timeoutMs: number;
+        onRequest: () => void;
+    }): Promise<boolean>;
+    resolve(id: string, approved: boolean): boolean;
+    list(): Array<{
+        id: string;
+        clientId: string;
+        clientName: string;
+        redirectUri: string;
+        resource?: string;
+    }>;
+}

package/dist/daemon/public-pages.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unauthenticated pages served on the daemon's HTTP surface.
+ *
+ * Deliberately minimal — no version, uptime, or tool-list leakage. The homepage
+ * is what a human lands on if they hit the tunnel URL in a browser. Everything
+ * actionable lives in the VS Code dashboard behind bearer auth.
+ */
+export declare function getHomepageHtml(): string;
+export declare function getRobotsTxt(): string;

package/dist/daemon/security.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Security middleware for the daemon HTTP surface.
+ *
+ * Ships in Phase 6a — everything runs BEFORE the bearer check so that both
+ * authenticated and unauthenticated requests are rate-limited / blocklisted.
+ *
+ * Components:
+ *   1. IP/UA extraction into req._pplx (typed).
+ *   2. Per-IP rate limit for unauthenticated requests (credentials often missing
+ *      from /register, /authorize, public pages — bearer-rate-limit kicks in
+ *      once authenticated).
+ *   3. Per-bearer rate limit (60 rpm default). Loopback-sourced requests exempt.
+ *   4. User-Agent blocklist — known scanners.
+ *   5. 401-burst tripwire — 20 401s in 60s on the tunnel fires a callback so
+ *      the launcher can auto-disable the tunnel.
+ *   6. Slow-401 — every 401 response is delayed a fixed 150ms to defeat
+ *      bearer-brute-force timing probes.
+ */
+export interface SecurityOptions {
+    ratelimitRpm?: number;
+    tripwireWindowMs?: number;
+    tripwireThreshold?: number;
+    slow401Ms?: number;
+    uaBlocklist?: RegExp[];
+    onTripwireTriggered?: (info: {
+        source: "loopback" | "tunnel";
+        failures: number;
+        windowMs: number;
+        ip: string | null;
+    }) => void | Promise<void>;
+}
+export interface SecurityMiddlewareResult {
+    middleware: (req: any, res: any, next: any) => void;
+    record401: (info: {
+        source: "loopback" | "tunnel";
+        ip: string | null;
+    }) => void;
+    snapshot: () => SecurityDiagnostics;
+}
+export interface SecurityDiagnostics {
+    tripwireFailures: number;
+    tripwireWindowMs: number;
+    tripwireThreshold: number;
+    rateLimitedBearers: number;
+    blockedUas: number;
+}
+/**
+ * Create the security middleware stack. Call once per daemon instance.
+ */
+export declare function createSecurity(options?: SecurityOptions): SecurityMiddlewareResult;
+/** Reset the tripwire latch — called after an auto-disable so future attacks re-trip. */
+export declare function resetTripwire(security: SecurityMiddlewareResult): void;

package/dist/daemon/server.d.ts

@@ -1,87 +1,17 @@
-import { RequestLike } from 'express';
-import { PerplexityClient } from '../client.js';
-import { readAuditTail } from './audit.js';
-import { DaemonTokenRecord } from './token.js';
-import '../config.js';
-import 'patchright';
-
-/**
- * OAuth consent cache — remembers per-(clientId, redirectUri, resource)
- * consents so the user isn't prompted every time Claude Desktop / Cursor /
- * Cline refreshes an access token (which happens on a ~1h cycle).
- *
- * Storage: <configDir>/oauth-consent.json, 0600.
- * Entries carry an absolute `expiresAt` (ms since epoch). On each check
- * we lazily prune expired entries. Deleting a record is synchronous and
- * best-effort (if the file is locked we lose the mutation; next write
- * will overwrite it).
- *
- * Key structure: `(clientId, redirectUri, resource)`. After Phase 8.2 H12
- * the OAuth `resource` parameter (RFC 8707) is part of the audience binding,
- * so a consent granted for `https://tunnel-a.example/mcp` must NOT
- * auto-approve a new authorize request for `https://tunnel-b.example/mcp`
- * even though the clientId + redirectUri match. `resource === undefined` is
- * a distinct key from any bound resource string — unbound consents (legacy
- * / loopback clients that don't send the `resource` param) don't
- * auto-approve bound-resource consents and vice-versa.
- *
- * Revoking a consent entry does NOT invalidate already-issued access
- * tokens — those live 1h anyway; revoking the CLIENT (see
- * oauth-provider.revokeClient) is the way to invalidate outstanding
- * tokens. Phase 8.2's dashboard panel composes these two.
- */
-interface ConsentEntry {
-    clientId: string;
-    redirectUri: string;
-    approvedAt: string;
-    expiresAt: number;
-    /**
-     * RFC 8707 resource binding. `undefined` = unbound (legacy / loopback
-     * clients that don't send the `resource` param at /authorize). Two entries
-     * with the same (clientId, redirectUri) but different `resource` values
-     * (including undefined-vs-string) are DISTINCT cache keys.
-     */
-    resource?: string;
-}
-
-/**
- * OAuth 2.1 authorization-server provider for the Perplexity MCP daemon.
- *
- * Implements the MCP SDK's `OAuthServerProvider` interface. Plugs into
- * `mcpAuthRouter()` to expose `/authorize`, `/token`, `/register`, `/revoke`
- * and the `/.well-known/*` metadata endpoints.
- *
- * Design:
- *   - Clients are persisted in `<configDir>/oauth-clients.json` (0600).
- *   - Authorization codes are in-memory, 2-min TTL, single-use.
- *   - Access tokens are in-memory, 1-hour TTL.
- *   - Refresh tokens rotate on each exchange.
- *   - `verifyAccessToken` accepts either a valid OAuth access token OR the
- *     daemon's static bearer, so existing loopback callers (extension host
- *     + CLI) keep working with no changes.
- *   - `authorize()` defers to a caller-supplied `requestConsent` callback
- *     which the daemon wires to the VS Code extension's modal. Until the
- *     user approves or the 2-min timeout elapses, the HTTP response is
- *     held open.
- */
-
-interface AuthorizedClientSummary {
-    clientId: string;
-    clientName?: string;
-    registeredAt: number;
-    lastUsedAt?: string;
-    consentLastApprovedAt?: string;
-    activeTokens: number;
-}
-
+import { type RequestLike } from "express";
+import { PerplexityClient } from "../client.js";
+import { readAuditTail } from "./audit.js";
+import { type AuthorizedClientSummary } from "./oauth-provider.js";
+import type { ConsentEntry } from "./oauth-consent-cache.js";
+import { type DaemonTokenRecord } from "./token.js";
 type EventPayload = Record<string, unknown>;
-interface DaemonTunnelHealth {
+export interface DaemonTunnelHealth {
     status: "disabled" | "starting" | "enabled" | "crashed";
     url: string | null;
     pid?: number | null;
     error?: string | null;
 }
-interface StartDaemonServerOptions {
+export interface StartDaemonServerOptions {
     host?: string;
     port?: number;
     uuid?: string;
@@ -120,7 +50,7 @@ interface StartDaemonServerOptions {
     /** When tunnel is enabled we advertise this as the OAuth issuer. */
     getTunnelUrl?: () => string | null;
 }
-interface StartedDaemonServer {
+export interface StartedDaemonServer {
     host: string;
     port: number;
     url: string;
@@ -147,13 +77,12 @@ interface StartedDaemonServer {
         redirectUri?: string;
     }) => number;
 }
-declare function startDaemonServer(options?: StartDaemonServerOptions): Promise<StartedDaemonServer>;
+export declare function startDaemonServer(options?: StartDaemonServerOptions): Promise<StartedDaemonServer>;
 /**
  * Canonicalize the expected resource identifier (RFC 8707) for this
  * request. Returns `<scheme>://<host>/mcp` with no trailing slash so the
  * PRM endpoint, the /authorize→/token binding, and verifyAccessToken's
  * expectedResource all agree on a single form.
  */
-declare function resolveRequestResource(req: RequestLike, fallback?: URL): string;
-
-export { type DaemonTunnelHealth, type StartDaemonServerOptions, type StartedDaemonServer, resolveRequestResource, startDaemonServer };
+export declare function resolveRequestResource(req: RequestLike, fallback?: URL): string;
+export {};

package/dist/daemon/server.mjs

@@ -1,18 +1,18 @@
 import {
   resolveRequestResource,
   startDaemonServer
-} from "../chunk-T6ARJK2P.mjs";
-import "../chunk-V4U3JM4R.mjs";
-import "../chunk-TDXETAQT.mjs";
-import "../chunk-2FPGJKCA.mjs";
-import "../chunk-C3HPFFTD.mjs";
-import "../chunk-DQQISMYN.mjs";
-import "../chunk-B65IJQZJ.mjs";
-import "../chunk-D254EFYB.mjs";
-import "../chunk-U7QPUNRH.mjs";
-import "../chunk-S677V2JU.mjs";
+} from "../chunk-2B5OQUXR.mjs";
+import "../chunk-TSLRTZYR.mjs";
+import "../chunk-DKEJZ4FI.mjs";
+import "../chunk-2EE7MNP2.mjs";
+import "../chunk-WHVJ724K.mjs";
+import "../chunk-V4LHDNWJ.mjs";
+import "../chunk-6E6XTHTG.mjs";
+import "../chunk-GBI2U336.mjs";
+import "../chunk-DXR6EEZH.mjs";
+import "../chunk-C5I7KXHK.mjs";
 import "../chunk-MTDFKNXX.mjs";
-import "../chunk-HJIXH6CL.mjs";
+import "../chunk-E3GRJXXJ.mjs";
 import "../chunk-4UEJOM6W.mjs";
 export {
   resolveRequestResource,

package/dist/daemon/token.d.ts

@@ -1,17 +1,15 @@
-interface DaemonTokenRecord {
+export interface DaemonTokenRecord {
     bearerToken: string;
     version: number;
     createdAt: string;
     rotatedAt: string;
 }
-interface TokenOptions {
+export interface TokenOptions {
     tokenPath?: string;
     now?: () => string;
 }
-declare function getTokenPath(configDir?: string): string;
-declare function generateBearerToken(): string;
-declare function readToken(options?: TokenOptions): DaemonTokenRecord | null;
-declare function ensureToken(options?: TokenOptions): DaemonTokenRecord;
-declare function rotateToken(options?: TokenOptions): DaemonTokenRecord;
-
-export { type DaemonTokenRecord, type TokenOptions, ensureToken, generateBearerToken, getTokenPath, readToken, rotateToken };
+export declare function getTokenPath(configDir?: string): string;
+export declare function generateBearerToken(): string;
+export declare function readToken(options?: TokenOptions): DaemonTokenRecord | null;
+export declare function ensureToken(options?: TokenOptions): DaemonTokenRecord;
+export declare function rotateToken(options?: TokenOptions): DaemonTokenRecord;

package/dist/daemon/token.mjs

@@ -4,9 +4,9 @@ import {
   getTokenPath,
   readToken,
   rotateToken
-} from "../chunk-TDXETAQT.mjs";
+} from "../chunk-DKEJZ4FI.mjs";
 import "../chunk-MTDFKNXX.mjs";
-import "../chunk-HJIXH6CL.mjs";
+import "../chunk-E3GRJXXJ.mjs";
 import "../chunk-4UEJOM6W.mjs";
 export {
   ensureToken,

package/dist/daemon/tunnel-providers/cloudflared-named-setup.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Cloudflared named-tunnel setup helpers.
+ *
+ * Wraps the `cloudflared` CLI to drive a persistent (named) tunnel. Named
+ * tunnels require an origin cert (`~/.cloudflared/cert.pem`), a tunnel UUID
+ * + credentials file, and a YAML config that maps a hostname -> local port.
+ *
+ * This module ships the setup primitives only; provider registration lives in
+ * cloudflared-named.ts (Phase 8.4.2). The dashboard/CLI call these helpers
+ * during the one-time setup flow.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+/**
+ * Minimal spawn signature we rely on — matches the three-arg overload of
+ * `node:child_process.spawn` used for piping stdio and collecting output.
+ * Declared as a type alias so tests can inject a fake implementation.
+ */
+type SpawnFn = typeof nodeSpawn;
+export interface CloudflaredLoginResult {
+    ok: boolean;
+    certPath: string;
+    stderr?: string;
+}
+export interface NamedTunnelSummary {
+    /** cloudflared's tunnel UUID. */
+    uuid: string;
+    /** Human-readable name. */
+    name: string;
+    createdAt?: string;
+    connections?: number;
+}
+export interface CreatedTunnel extends NamedTunnelSummary {
+    /** Path to the credentials JSON cloudflared wrote. */
+    credentialsPath: string;
+}
+export interface NamedTunnelConfig {
+    uuid: string;
+    /** e.g. "mcp.example.com" */
+    hostname: string;
+    /** Local daemon HTTP port. */
+    port: number;
+    /** Full path to the written .yml. */
+    configPath: string;
+    credentialsPath: string;
+}
+export interface DeletedNamedTunnel {
+    uuid: string;
+}
+export type DeleteNamedTunnelFailureReason = "active-connections" | "unknown";
+export declare class DeleteNamedTunnelError extends Error {
+    readonly reason: DeleteNamedTunnelFailureReason;
+    constructor(message: string, reason: DeleteNamedTunnelFailureReason);
+}
+/**
+ * Runs `cloudflared tunnel login`. Opens a browser. Blocks until the cert
+ * lands at `~/.cloudflared/cert.pem` (or throws on timeout / abort). The
+ * login subprocess is best-effort terminated on resolve/reject.
+ */
+export declare function runCloudflaredLogin(options: {
+    configDir: string;
+    binaryPath?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Override the cert watch location (defaults to `$HOME/.cloudflared/cert.pem`). */
+    certPath?: string;
+    /**
+     * When true, pipe the cloudflared child's stderr AND stdout to the parent
+     * process's stderr so CLI users see the "open this URL in your browser"
+     * prompt (some cloudflared builds emit it on stdout, others on stderr).
+     * Never forwards to parent stdout — the CLI reserves stdout for --json
+     * machine-readable output. Default false (test hermeticity + dashboard
+     * flow that wraps output in notifications instead).
+     */
+    forwardOutput?: boolean;
+    /** Test-only dependency injection seam. */
+    dependencies?: {
+        spawn?: SpawnFn;
+    };
+}): Promise<CloudflaredLoginResult>;
+/**
+ * Runs `cloudflared tunnel list --output=json` and parses. Returns [] on
+ * "no tunnels" (exit 0 + empty list). Throws on binary/cert problems.
+ */
+export declare function listNamedTunnels(options: {
+    configDir: string;
+    binaryPath?: string;
+    dependencies?: {
+        spawn?: SpawnFn;
+    };
+}): Promise<NamedTunnelSummary[]>;
+/**
+ * Runs `cloudflared tunnel create <name>`, parses the UUID + credentials
+ * path out of stdout, then runs `cloudflared tunnel route dns <uuid>
+ * <hostname>` to install the CNAME record.
+ */
+export declare function createNamedTunnel(options: {
+    configDir: string;
+    name: string;
+    hostname: string;
+    binaryPath?: string;
+    signal?: AbortSignal;
+    dependencies?: {
+        spawn?: SpawnFn;
+    };
+}): Promise<CreatedTunnel>;
+/**
+ * Deletes a remote Cloudflare named tunnel. This is intentionally separate
+ * from clearNamedTunnelConfig(): remote delete can fail even with --force
+ * when DNS still routes traffic and active connections keep the tunnel alive.
+ */
+export declare function deleteNamedTunnel(options: {
+    configDir: string;
+    uuid: string;
+    binaryPath?: string;
+    signal?: AbortSignal;
+    dependencies?: {
+        spawn?: SpawnFn;
+    };
+}): Promise<DeletedNamedTunnel>;
+export declare function isActiveConnectionDeleteFailure(output: string): boolean;
+export declare function getNamedTunnelConfigPath(configDir: string): string;
+/**
+ * Writes `<configDir>/cloudflared-named.yml` describing the tunnel ->
+ * localhost mapping. Uses the temp-file + rename pattern from ngrok-config.ts
+ * and locks file mode to 0600 (POSIX) / user-only ACL (Windows).
+ */
+export declare function writeTunnelConfig(options: {
+    configDir: string;
+    uuid: string;
+    hostname: string;
+    port: number;
+    credentialsPath: string;
+}): NamedTunnelConfig;
+/**
+ * Reads + validates the config written by writeTunnelConfig. Returns null
+ * if absent or malformed.
+ */
+export declare function readNamedTunnelConfig(configDir: string): NamedTunnelConfig | null;
+export declare function clearNamedTunnelConfig(configDir: string): boolean;
+export {};

package/dist/daemon/tunnel-providers/cloudflared-named.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Cloudflared named-tunnel provider.
+ *
+ * Runs a persistent Cloudflare tunnel that routes a user-owned hostname
+ * (e.g. https://mcp.example.com) to the local daemon HTTP port. Unlike
+ * cloudflared-quick, the URL is stable across restarts.
+ *
+ * Setup (one-time, handled by 8.4.3 UI + 8.4.4 CLI) produces:
+ *   - ~/.cloudflared/cert.pem              (origin cert from `cloudflared login`)
+ *   - ~/.cloudflared/<uuid>.json           (tunnel credentials, written by create)
+ *   - <configDir>/cloudflared-named.yml    (managed ingress config we serialize)
+ *
+ * Port-drift rewrite (load-bearing): the managed YAML embeds the daemon's
+ * loopback port. The daemon picks a fresh OS-assigned port on most restarts,
+ * so the persisted port is almost always stale by the time start() runs. We
+ * rewrite the managed YAML with the current port on every start() — idempotent
+ * atomic writes are cheap, forgetting the rewrite routes cloudflared to a
+ * dead port.
+ *
+ * The managed YAML is treated as provider-owned — hand-edits to add extra
+ * ingress rules WILL be silently dropped on the next start() because we
+ * serialize only the four canonical keys (tunnel / credentials-file /
+ * hostname / service). Warning on drift is deferred to 8.4.3.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import type { TunnelProvider } from "./types.js";
+type SpawnFn = typeof nodeSpawn;
+interface ProviderDependencies {
+    spawn?: SpawnFn;
+    homedir?: () => string;
+}
+/**
+ * Build a provider bound to a specific dependency set. The exported
+ * singleton uses node defaults; tests construct a one-off via
+ * createCloudflaredNamedProvider({ dependencies: { spawn: fakeSpawn } }).
+ */
+export declare function createCloudflaredNamedProvider(options?: {
+    dependencies?: ProviderDependencies;
+}): TunnelProvider;
+/**
+ * Default singleton wired to node's real spawn. Registered in the provider
+ * registry; tests use createCloudflaredNamedProvider() for DI.
+ */
+export declare const cloudflaredNamedProvider: TunnelProvider;
+export {};

package/dist/daemon/tunnel-providers/cloudflared-quick.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cloudflare Quick Tunnel provider — wraps the existing binary-based flow.
+ *
+ * Ephemeral subdomain on *.trycloudflare.com. Zero configuration required
+ * beyond installing the binary (handled via `daemon install-tunnel`).
+ */
+import type { TunnelProvider } from "./types.js";
+export declare const cloudflaredQuickProvider: TunnelProvider;