@yanlinglabs/winter-agent-runtime 0.0.29 → 0.0.30

package/dist/index.js

@@ -53,8 +53,10 @@ import {
   DEFAULT_CLASSIFIER_TIMEOUT_MS2,
   createModelClassifier2,
   selectClassifierRoute2
-} from "./index-jz5d90c6.js";
-import"./index-8jgwp1px.js";
+} from "./index-51673qbw.js";
+import"./index-9s68t0pd.js";
+import"./index-z6s3r4xm.js";
+import"./index-bgeqc7ax.js";
 import"./index-bef62z3r.js";
 import {
   createInMemoryChannel2

package/dist/mcp/client.d.ts

@@ -1,6 +1,8 @@
+import { InsufficientScopeError } from "@modelcontextprotocol/client";
 import type { McpServerConfigForProcessTransport, McpVersionNegotiation } from "@yanlinglabs/winter-agent-sdk";
 import { type InProcessMcpServer } from "./transports/sdk.js";
 import { type ElicitationAsker } from "./elicitation.js";
+import { type McpSessionAuthProvider } from "../mcp-auth/session-provider.js";
 /**
  * WHY a connection attempt failed -- a category, not a message (the message is for humans; this is what
  * the state board's `errorCode`, the web search backend and the `'auto'` legacy retry read).
@@ -16,7 +18,7 @@ import { type ElicitationAsker } from "./elicitation.js";
  * A probe that went unanswered is `timeout` and a probe answered with an HTTP error keeps
  * `handshake_failed` plus its `httpStatus`, as before.
  */
-export type McpConnectErrorCode = "timeout" | "spawn_failed" | "handshake_failed" | "version_mismatch" | "transport_closed" | "needs_auth" | "unknown";
+export type McpConnectErrorCode = "timeout" | "spawn_failed" | "handshake_failed" | "version_mismatch" | "transport_closed" | "needs_auth" | "auth_refresh_failed" | "unknown";
 export declare class McpConnectError extends Error {
     readonly code: McpConnectErrorCode;
     /**
@@ -113,8 +115,25 @@ export interface ConnectMcpServerOptions {
      * notifications would have nothing to update.
      */
     onToolListChanged?: () => void;
+    /**
+     * WS-25 (MCP OAuth): the session's read-only bearer provider for THIS server (`http`/`sse` only;
+     * mcp-auth/session-provider.ts). Its `preflight()` runs before the transport exists -- a stored sign-in
+     * that is already dead is `needs_auth` with no request sent (spec §1.2) -- and the transport then reads
+     * the bearer from it per request, with every redirect refused. Absent: no `Authorization` beyond the
+     * config's own headers, exactly as before.
+     */
+    auth?: McpSessionAuthProvider;
 }
 export declare function resolveVersionNegotiation(config: McpServerConfigForProcessTransport): McpVersionNegotiation;
 export declare const AUTO_PROBE_TIMEOUT_CAP_MS = 5000;
 export declare const MANUAL_LIST_MAX_PAGES = 64;
 export declare function connectMcpServer(opts: ConnectMcpServerOptions): Promise<ConnectedMcpClient>;
+/** A `403 insufficient_scope` challenge, found directly or as the cause the v2 client wrapped it in. */
+export declare function insufficientScopeOf(err: unknown): InsufficientScopeError | undefined;
+/**
+ * What an error from a LIVE connection's request says about its sign-in: `needs_auth` (the sign-in is
+ * gone -- a 401 the provider could not recover, or the provider's own verdict), `insufficient_scope` (a
+ * 403 step-up this one call needs), or `undefined` (anything else: an ordinary tool failure). Walks a few
+ * `cause` links, since the v2 client wraps some transport failures.
+ */
+export declare function classifyMcpAuthFailure(err: unknown): "needs_auth" | "insufficient_scope" | undefined;

package/dist/mcp/lifecycle.d.ts

@@ -3,6 +3,7 @@ import type { McpServerStateSource } from "./state.js";
 import type { McpControlSeam } from "./control-seam.js";
 import type { McpEnvConfig } from "./env.js";
 import { type McpToolInfo, type ConnectedMcpClient } from "./client.js";
+import { type McpSessionOAuth } from "../mcp-auth/session-provider.js";
 import type { ElicitationAsker } from "./elicitation.js";
 import type { InProcessMcpServer } from "./transports/sdk.js";
 export type McpConfigSourceOrigin = "explicit" | "settings" | "project" | "plugin" | "dynamic";
@@ -110,6 +111,13 @@ export interface McpLifecycleDeps {
     reservedServerName?: string;
     /** WS-23: the session cwd every stdio server of this lifecycle is spawned in (see `ConnectMcpServerOptions.cwd`). */
     cwd?: string;
+    /**
+     * WS-25 (MCP OAuth): the session's sign-ins -- the token store (read-only), the host's refresh door and
+     * the sign-in hint. Present, every `http`/`sse` server WITHOUT a static `Authorization` header connects
+     * through a read-only bearer provider (`sessionAuthFor`); a server that answers 401 then lands in
+     * `needsAuth` with its tools unregistered. Absent: no provider anywhere, byte-identical to before.
+     */
+    oauth?: McpSessionOAuth;
 }
 export type RefreshServerToolsResult = {
     ok: true;

package/dist/mcp/transports/http.d.ts

@@ -1,5 +1,14 @@
-import { type Transport } from "@modelcontextprotocol/client";
+import { type AuthProvider, type Transport } from "@modelcontextprotocol/client";
 import type { McpHttpServerConfig } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * WS-25: the network an AUTHENTICATED transport (one with an `authProvider`) uses -- the platform `fetch`
+ * with every redirect REFUSED. A bearer token rides the `Authorization` header, which fetch strips on a
+ * cross-origin hop, but the MCP request BODY (tool arguments drawn from the conversation) does not get
+ * stripped, and a server that redirects an authenticated MCP connection is not one to follow. Read at call
+ * time, so a test's network guard (which wraps the global) still sees every request.
+ */
+export declare const refusingRedirectsFetch: typeof fetch;
 export declare function buildHttpTransport(cfg: McpHttpServerConfig, opts?: {
     refuseRedirects?: boolean;
+    authProvider?: AuthProvider;
 }): Transport;

package/dist/mcp/transports/sse.d.ts

@@ -1,3 +1,5 @@
-import { type Transport } from "@modelcontextprotocol/client";
+import { type AuthProvider, type Transport } from "@modelcontextprotocol/client";
 import type { McpSSEServerConfig } from "@yanlinglabs/winter-agent-sdk";
-export declare function buildSseTransport(cfg: McpSSEServerConfig): Transport;
+export declare function buildSseTransport(cfg: McpSSEServerConfig, opts?: {
+    authProvider?: AuthProvider;
+}): Transport;

package/dist/mcp-auth/account.d.ts

@@ -0,0 +1,33 @@
+/** The token item's account prefix: `mcp-oauth:<id>`. Sessions read it; the host writes it. */
+export declare const MCP_OAUTH_TOKEN_ACCOUNT_PREFIX = "mcp-oauth:";
+/** The client-registration item's account prefix: `mcp-oauth-client:<id>`. Only the host reads it. */
+export declare const MCP_OAUTH_CLIENT_ACCOUNT_PREFIX = "mcp-oauth-client:";
+/**
+ * The canonical form of an MCP server URL: lower-cased scheme and host (the URL parser does both), the
+ * scheme's default port dropped (likewise), the path KEPT (two servers under one origin are two servers),
+ * no query, no fragment, and trailing slashes removed (`https://x/mcp/` and `https://x/mcp` are the same
+ * server; `https://x/` and `https://x` both become `https://x`).
+ *
+ * Refused, typed (`invalid_server_url`): an unparseable URL, a non-http(s) scheme, and userinfo -- a
+ * credential in a URL is never a key, and never silently dropped into one either.
+ */
+export declare function canonicalMcpServerUrl(serverUrl: string): string;
+/** `sha256(canonicalMcpServerUrl(serverUrl))`, first 16 hex characters. The ONE key derivation. */
+export declare function mcpOAuthAccountId(serverUrl: string): string;
+/** The token item's full account name for a server URL: `mcp-oauth:<id>`. This is the `account` every door takes. */
+export declare function mcpOAuthTokenAccount(serverUrl: string): string;
+/** The client-registration item's full account name for a server URL: `mcp-oauth-client:<id>`. */
+export declare function mcpOAuthClientAccount(serverUrl: string): string;
+/** The pre-registered client secret's account prefix: `mcp-oauth-client-secret:<id>`. Only the host reads it. */
+export declare const MCP_OAUTH_CLIENT_SECRET_ACCOUNT_PREFIX = "mcp-oauth-client-secret:";
+/**
+ * The ONE Keychain account a pre-registered client's secret is read from: `mcp-oauth-client-secret:<id>`,
+ * DERIVED from the server URL and never named by a config (see `McpOAuthSecretRef`: a config-named
+ * account could point the sign-in at a provider API key and hand it to an attacker's authorization
+ * server). The host writes the secret here (a masked prompt, a secure field); the sign-in reads it here.
+ */
+export declare function mcpOAuthClientSecretAccount(serverUrl: string): string;
+/** True for a well-formed token account name (`mcp-oauth:` + 16 lower-case hex). */
+export declare function isMcpOAuthTokenAccount(account: string): boolean;
+/** The client item's account for a TOKEN account -- the prefix swap. Refuses anything that is not a token account. */
+export declare function clientAccountForTokenAccount(account: string): string;

package/dist/mcp-auth/config.d.ts

@@ -0,0 +1,6 @@
+/** `undefined` when `oauth` is a valid `McpOAuthConfig`; otherwise why not (prose naming the field, never quoting a secret). */
+/**
+ * `serverUrl` is the server config's own `url`: an `authServerMetadataUrl` may name a loopback address
+ * only when the server itself is on loopback (fix round 1 M4). Absent, loopback is refused.
+ */
+export declare function validateMcpOAuthConfig(oauth: unknown, serverUrl?: string): string | undefined;

package/dist/mcp-auth/constants.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Winter's Client ID Metadata Document (CIMD, draft-ietf-oauth-client-id-metadata-document; MCP spec
+ * 2025-11-25's preferred registration): an authorization server that advertises
+ * `client_id_metadata_document_supported` fetches THIS URL as Winter's client id, and no per-server
+ * registration exists at all.
+ *
+ * CONFIRMED by the user (2026-09-27, spec §1.5): the permanent URL on the user's Cloudflare domain
+ * `yanlinglabs.com`. Publishing the document there is a separate controller step. It is ONE constant,
+ * and every door that uses it takes a `clientMetadataUrl` override (tests pass their own).
+ *
+ * THE DOCUMENT'S REDIRECT URIS (spec §4.2, settled): `["http://127.0.0.1/callback"]` -- a loopback IP
+ * literal with NO port. A CIMD document is global, so it cannot name the port one machine's listener
+ * got; RFC 8252 §7.3 obliges an authorization server to "allow any port to be specified at the time of
+ * the request for loopback IP redirect URIs", which is exactly how a native client with an ephemeral
+ * port registers once. Winter binds `127.0.0.1` (never `localhost`, RFC 8252 §8.3) on the config's
+ * `callbackPort` or an ephemeral port, and sends that exact URI. An authorization server that ignores
+ * §7.3 fails at its own consent page; the fallback is a pre-registered client (`oauth.clientId`) with a
+ * fixed `oauth.callbackPort`.
+ */
+export declare const WINTER_MCP_CLIENT_METADATA_URL = "https://yanlinglabs.com/winter/oauth-client.json";
+/** The loopback redirect's path. The CIMD document registers `http://127.0.0.1/callback` with it. */
+export declare const MCP_OAUTH_CALLBACK_PATH = "/callback";
+/** A token within this many ms of `expiresAt` counts as expired: it is refreshed before a request can fail with it (spec §1.2). */
+export declare const MCP_OAUTH_EXPIRY_SKEW_MS = 60000;
+/** How long a session trusts its last Keychain read of a token before re-reading it (spec §3, "~30 s"). */
+export declare const MCP_OAUTH_SESSION_CACHE_MS = 30000;
+/** An interactive sign-in's whole budget: the listener closes and `done` settles `login_timeout` after it. */
+export declare const MCP_OAUTH_LOGIN_TIMEOUT_MS: number;
+/** The `state` parameter's entropy: 32 random bytes, base64url. */
+export declare const MCP_OAUTH_STATE_BYTES = 32;

package/dist/mcp-auth/discovery.d.ts

@@ -0,0 +1,72 @@
+import { type AuthorizationServerMetadata } from "@modelcontextprotocol/client";
+import type { McpOAuthConfig } from "@yanlinglabs/winter-agent-sdk";
+import { type McpAuthFetch } from "./fetch-policy.js";
+/** True when `url` names a metadata DOCUMENT (the config's `oauth.authServerMetadataUrl`) rather than an issuer. */
+export declare function isMetadataDocumentUrl(url: string): boolean;
+export declare function fetchAuthorizationServerMetadataDocument(url: string, fetchFn: McpAuthFetch): Promise<AuthorizationServerMetadata>;
+export interface LoadedAuthorizationServer {
+    /** What the token-endpoint helpers take as `authorizationServerUrl` (the legacy `/token` fallback's base). */
+    authorizationServerUrl: string;
+    /** Absent for the legacy variant (no RFC 8414 document anywhere): the helpers then use `/token` on the base. */
+    metadata?: AuthorizationServerMetadata;
+}
+/**
+ * The authorization server a stored sign-in belongs to. `expectedIssuer` is the token record's: a
+ * document that now names another issuer is refused (tokens are bound to the issuer that minted them,
+ * SEP-2352) rather than sent a refresh token it never issued.
+ */
+export declare function loadAuthorizationServer(opts: {
+    authorizationServerUrl: string;
+    expectedIssuer: string;
+    fetchFn: McpAuthFetch;
+}): Promise<LoadedAuthorizationServer>;
+/**
+ * The RFC 8707 `resource` a token request names: the protected-resource metadata's own `resource`
+ * string, VERBATIM (the MCP client's `auth()` sends it that way, #1968), when the document exists and
+ * matches the server; absent for a server that publishes none (the legacy variant).
+ */
+export declare function resolveResourceIndicator(opts: {
+    serverUrl: string;
+    resourceMetadataUrl?: string;
+    fetchFn: McpAuthFetch;
+}): Promise<string | undefined>;
+export interface DiscoverMcpOAuthIssuerOptions {
+    /** The MCP server's URL (the protected resource) -- the same value `startMcpOAuthLogin` takes. */
+    serverUrl: string;
+    /** The server config's `oauth` block, when it has one (only `authServerMetadataUrl` matters here). */
+    oauth?: McpOAuthConfig;
+    /** The network under the auth-HTTP policy (tests; a host that must go through its own dispatcher). */
+    fetch?: typeof fetch;
+}
+export interface McpOAuthIssuerInfo {
+    /** The full verified issuer string -- identical to what a sign-in on this config would store/return. */
+    issuer: string;
+    /** `issuer`'s origin, for display only (compare tenants by `issuer`/`sameIssuer`, never this). */
+    issuerOrigin: string;
+    /** The origin the authorize request would load in a browser -- usually the issuer's. */
+    authorizeOrigin: string;
+}
+/**
+ * WS-25, additive: finds a server's authorization server WITHOUT signing in -- no registration, no code
+ * exchange, no loopback listener, no store read or write, no client secret ever touched. For a caller that
+ * must know a server's issuer before (or without) starting an interactive sign-in: the daemon's own
+ * authorization-server bookkeeping, which compares SERVERS, not origins (an origin can host many issuers
+ * behind tenant paths -- `https://host/tenant/a` and `https://host/tenant/b` are two authorization servers
+ * on the same origin, and a comparison that stopped at `issuerOrigin` would treat them as one).
+ *
+ * MIRRORS `startMcpOAuthLogin`'s own discovery leg exactly, so this door's `issuer` is PROVABLY the same
+ * string a sign-in on the same config would store (`flow.test.ts` pins the equality against the fixture):
+ *   - `oauth.authServerMetadataUrl` set: `fetchAuthorizationServerMetadataDocument` (login.ts's seeded
+ *     path, `startMcpOAuthLogin` line ~252-261) -- the SAME RFC 8414 issuer-location check
+ *     (`fetchedFromIssuersOwnLocation`, above), refusing `metadata_issuer_mismatch` on a document a
+ *     config's `authServerMetadataUrl` did not actually come from.
+ *   - absent: `discoverOAuthServerInfo` (RFC 9728 PRM -> RFC 8414 / OIDC discovery) -- the exact function
+ *     the MCP client package's own `auth()` calls for a fresh (uncached) flow, so an unseeded sign-in's
+ *     issuer is this door's issuer too, not a second implementation of the same two steps.
+ *
+ * `authorizeOrigin` is derived without ever building a real authorize URL (that needs a registered
+ * client, which this door never creates): a metadata document's own `authorization_endpoint`, or --
+ * the legacy variant, no document anywhere -- `startAuthorization`'s own fallback, `/authorize` on the
+ * authorization server's base URL (same origin either way).
+ */
+export declare function discoverMcpOAuthIssuer(opts: DiscoverMcpOAuthIssuerOptions): Promise<McpOAuthIssuerInfo>;

package/dist/mcp-auth/engine-wiring.d.ts

@@ -0,0 +1,52 @@
+import { type AttachmentPayload } from "../context/attachments.js";
+import type { ProviderMessage } from "../engine.js";
+import type { McpServerState } from "../mcp/state.js";
+import { type McpSessionOAuth } from "./session-provider.js";
+import type { McpOAuthStore } from "./store.js";
+/** How long a session waits for its host to refresh a sign-in before treating the ask as transient. */
+export declare const MCP_OAUTH_HOST_REFRESH_TIMEOUT_MS = 60000;
+/** The narrow view of the session's control bridge this needs (the runtime's `RpcBridge` satisfies it). */
+export interface McpOAuthHostSender {
+    request<T = unknown>(subtype: string, payload: unknown, opts?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+}
+/**
+ * The session's sign-in wiring. `askHost` answers `"unhandled"` ONLY for the host's own "no handler
+ * registered" reply -- the standalone case, which refreshes in-process. Every other failure of the round
+ * trip (a timeout, a dead transport, a malformed answer) is `transient`: a host that HAS a handler must
+ * never be bypassed by a session that then posts the refresh itself.
+ */
+export declare function createSessionMcpOAuth(opts: {
+    store: McpOAuthStore;
+    sender: McpOAuthHostSender;
+    brand: {
+        homeDirName: string;
+        productName: string;
+    };
+    hostOwnsRefresh?: boolean;
+}): McpSessionOAuth;
+/** The servers in `needsAuth`, sorted: the notice's subject and the hint's lookup. */
+export declare function needsAuthServers(states: readonly McpServerState[] | undefined): string[];
+/**
+ * The hint a call to a tool of a server that needs sign-in gets, appended to "No such tool available"
+ * (spec §1.3: the call answers with the door, never a browser and never a model-callable auth tool).
+ * Matched on the `mcp__<server>__` prefix of each needs-auth server by NAME, not by splitting the tool
+ * name (a server name may itself contain `__`).
+ */
+export declare function needsAuthToolHint(states: readonly McpServerState[] | undefined, toolName: string, brand: {
+    homeDirName: string;
+    productName: string;
+}): string;
+export interface McpNeedsAuthAttachment extends AttachmentPayload {
+    type: "mcp_needs_auth";
+    /** The servers that need sign-in now (sorted); empty means "none any more". */
+    servers: string[];
+    /** The door, captured at production time for the `<server>` placeholder (a renderer has no brand). */
+    door: string;
+}
+/** The notice to append now, or `undefined` when the needs-auth set is what the history already says. */
+export declare function mcpNeedsAuthAttachment(states: readonly McpServerState[] | undefined, messages: readonly ProviderMessage[], brand: {
+    homeDirName: string;
+    productName: string;
+}): McpNeedsAuthAttachment | undefined;

package/dist/mcp-auth/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * - `malformed_record` / `unsupported_record_version` -- a Keychain item that is not a record this SDK
+ *   wrote (bad JSON, a missing field, the wrong `kind`), or one from a NEWER record version (`v`), which
+ *   is refused rather than guessed at.
+ * - `invalid_server_url` -- not an absolute http(s) URL, or one carrying userinfo.
+ * - `invalid_account` -- not an `mcp-oauth:<16 hex>` token account name.
+ * - `policy_refused` -- the auth-HTTP policy refused a URL (plain http off loopback, a literal private or
+ *   link-local address, a cross-origin redirect, an oversized answer).
+ * - `network` -- an auth request never got an answer (a refused connection, a timeout): retry later.
+ * - `login_superseded` / `login_cancelled` / `login_timeout` -- the interactive sign-in ended without a
+ *   callback (a newer sign-in for the same server, `cancel()`, the 5-minute bound).
+ * - `state_mismatch` -- the loopback callback carried a `state` this flow never issued.
+ * - `authorization_denied` -- the authorization server redirected back with `error=...`.
+ * - `client_secret_unavailable` -- a pre-registered client's `clientSecretRef` could not be read.
+ * - `callback_port_unavailable` -- the configured `oauth.callbackPort` is taken.
+ * - `metadata_issuer_mismatch` -- a configured authorization server metadata document names an issuer it
+ *   was not published under (RFC 8414 §3.3).
+ * - `client_secret_issuer_mismatch` -- a pre-registered client secret would go to an authorization server
+ *   other than the one it is bound to (its stamped/expected issuer, or an existing registration's).
+ * - `login_failed` -- discovery, registration or the code exchange failed (the message says which step,
+ *   and on the exchange never quotes the authorization server).
+ * - `not_implemented` -- a contract stub (WS-25 lands its types first).
+ */
+export type McpOAuthErrorCode = "malformed_record" | "unsupported_record_version" | "invalid_server_url" | "invalid_account" | "policy_refused" | "network" | "login_superseded" | "login_cancelled" | "login_timeout" | "state_mismatch" | "authorization_denied" | "client_secret_unavailable" | "callback_port_unavailable" | "client_secret_issuer_mismatch" | "metadata_issuer_mismatch" | "login_failed" | "not_implemented";
+export declare class McpOAuthError extends Error {
+    readonly code: McpOAuthErrorCode;
+    constructor(code: McpOAuthErrorCode, message: string);
+}
+/**
+ * Error text safe to hand a host: an `McpOAuthError`'s own message (already bounded and code-shaped by its
+ * throw site), an `OAuthError`'s code alone, or a bounded, control-free NAME + message -- never an
+ * authorization server's raw response body (a token endpoint that echoes its request would put a refresh
+ * token or a client secret in it). Shared by every `mcp-auth` door that wraps a step it did not throw
+ * itself (login's discovery/registration leg, this file's discovery-only door) so the bound lives in ONE
+ * place rather than one copy per door drifting apart.
+ */
+export declare function boundedReason(err: unknown): string;

package/dist/mcp-auth/fetch-policy.d.ts

@@ -0,0 +1,33 @@
+/** The MCP client package's `FetchLike`: what `auth()`, `refreshAuthorization()` and friends call. */
+export type McpAuthFetch = (url: string | URL, init?: RequestInit) => Promise<Response>;
+export declare const MCP_AUTH_FETCH_TIMEOUT_MS = 30000;
+/** Metadata documents, a registration answer and a token answer are all small; 1 MiB is generous. */
+export declare const MCP_AUTH_FETCH_MAX_BODY_BYTES: number;
+export interface McpAuthFetchOptions {
+    /** The network. Absent: provider-runtime's `boundedFetch`. See this file's header for what changes when it is injected. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    maxBodyBytes?: number;
+    /** Whether a literal loopback address may be reached at all: true only when the MCP server itself is loopback. Default false. */
+    allowLoopback?: boolean;
+}
+export type McpAuthUrlVerdict = {
+    ok: true;
+    origin: string;
+    loopback: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The URL rules (1, 2 and 5 of the header), for ONE absolute URL. Exported because the sign-in applies
+ * the same rules to URLs it never fetches: the authorize URL a browser opens, and the MCP server URL
+ * itself.
+ */
+export declare function evaluateMcpAuthUrl(raw: string | URL, opts?: {
+    allowLoopback?: boolean;
+}): McpAuthUrlVerdict;
+/** True when the MCP server URL is itself a literal loopback address -- the one case its auth URLs may be too. */
+export declare function isLoopbackMcpServer(serverUrl: string): boolean;
+/** Builds THE auth fetch. Every `mcp-auth` door builds one per operation from its own `fetch?` option. */
+export declare function createMcpAuthFetch(opts?: McpAuthFetchOptions): McpAuthFetch;

package/dist/mcp-auth/login.d.ts

@@ -0,0 +1,59 @@
+import type { McpOAuthConfig } from "@yanlinglabs/winter-agent-sdk";
+import { type McpOAuthStore } from "./store.js";
+export interface StartMcpOAuthLoginOptions {
+    /** The MCP server's URL (the protected resource). Its canonical form keys the Keychain items. */
+    serverUrl: string;
+    /** The server config's `oauth` block, when it has one. */
+    oauth?: McpOAuthConfig;
+    /** Where the sign-in lands: the token item and the client registration. */
+    store: McpOAuthStore;
+    /** Overrides `WINTER_MCP_CLIENT_METADATA_URL` (tests; a host that publishes its own CIMD document). */
+    clientMetadataUrl?: string;
+    /** The network under the auth-HTTP policy (tests pass the fixture's). The policy is applied on top, always. */
+    fetch?: typeof fetch;
+    /** The clock (tests). Epoch ms. */
+    now?: () => number;
+    /**
+     * WS-25, additive: reads a pre-registered client's secret when the config marks one
+     * (`oauth.clientSecretRef: { kind: "keychain" }`). It is called with the ONE account the secret may live
+     * at -- `mcpOAuthClientSecretAccount(serverUrl)`, derived, never config-named (fix round 1) -- and a
+     * host passes it only to read that account from somewhere other than `store`. Absent: `store` is read
+     * at that account.
+     */
+    readClientSecret?: (account: string) => Promise<string | null>;
+    /** WS-25, additive: the whole sign-in's budget in ms (default `MCP_OAUTH_LOGIN_TIMEOUT_MS`, 5 minutes). */
+    timeoutMs?: number;
+}
+export type McpOAuthLoginOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface McpOAuthLogin {
+    /** The authorization server's authorize URL, for the HOST to open in a browser. HTTPS (or literal loopback). */
+    authUrl: string;
+    /**
+     * The FULL verified issuer string this sign-in used -- RFC 8414 `issuer` when the server published
+     * metadata, else the authorization server URL discovery landed on (the legacy variant). Two tenants
+     * behind one reverse proxy (`https://host/tenant/a`, `https://host/tenant/b`) share an ORIGIN but never
+     * this string: a caller that must tell them apart (the daemon's own authorization-server bookkeeping)
+     * compares THIS, with `sameIssuer` (`records.ts`), never `issuerOrigin`.
+     */
+    issuer: string;
+    /** The authorization server's issuer ORIGIN, to show the user before the browser opens. */
+    issuerOrigin: string;
+    /**
+     * WS-25 fix round 1, additive: the ORIGIN of `authUrl` itself -- the page the browser will actually load.
+     * Usually the issuer's; a host shows both when they differ (metadata may place the authorize endpoint on
+     * another host).
+     */
+    authorizeOrigin: string;
+    /** Settles once: the callback arrived and the tokens are stored, or the sign-in ended without them. */
+    done: Promise<McpOAuthLoginOutcome>;
+    /** Ends the sign-in now (closes the listener); `done` settles `{ ok: false }`. Idempotent. */
+    cancel(): void;
+}
+export declare function startMcpOAuthLogin(opts: StartMcpOAuthLoginOptions): Promise<McpOAuthLogin>;
+/** Test seam: how many sign-in flows are waiting for a callback. */
+export declare function activeMcpOAuthLoginCount(): number;

package/dist/mcp-auth/records.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The sign-in a SESSION reads (`mcp-oauth:<id>`). `generation` counts writes: every refresh and every new
+ * sign-in bumps it, and the `mcp_oauth_refresh` request carries the generation the session last read, so a
+ * host that already refreshed past it answers without posting again.
+ *
+ * `expiresAt` is epoch MILLISECONDS, absent when the token endpoint gave no `expires_in` -- such a token is
+ * treated as valid until the server answers 401 (spec §1.2).
+ */
+export interface McpOAuthTokenRecord {
+    v: 1;
+    kind: "mcp-oauth";
+    serverUrl: string;
+    issuer: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+    generation: number;
+}
+/**
+ * The client registration only the HOST reads (`mcp-oauth-client:<id>`): which client Winter is to this
+ * server's authorization server, how it got that identity, and where the sign-in's callback listens.
+ *
+ * - `registeredVia` -- `"preregistered"` (the config's `oauth.clientId`), `"cimd"` (the client id IS the
+ *   Client ID Metadata Document's URL) or `"dcr"` (RFC 7591 Dynamic Client Registration).
+ * - `redirectUri` -- the exact loopback redirect this client registered or last used,
+ *   `http://127.0.0.1:<port>/callback`. For DCR it is the registration's own, and its port is reused on
+ *   the next sign-in (spec §1.6).
+ * - `resourceMetadataUrl` / `authorizationServerUrl` -- where discovery found the RFC 9728 and RFC 8414
+ *   documents, so a refresh re-reads them without a probe of the MCP server.
+ * - `stepUpScope` -- a scope a `403 insufficient_scope` asked for; the next sign-in requests it.
+ */
+export interface McpOAuthClientRecord {
+    v: 1;
+    kind: "mcp-oauth-client";
+    serverUrl: string;
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    registeredVia: "dcr" | "cimd" | "preregistered";
+    redirectUri: string;
+    resourceMetadataUrl?: string;
+    authorizationServerUrl?: string;
+    stepUpScope?: string;
+}
+export declare function decodeMcpOAuthTokenRecord(raw: string): McpOAuthTokenRecord;
+export declare function decodeMcpOAuthClientRecord(raw: string): McpOAuthClientRecord;
+/** Serialises a token record (re-validated, so an in-memory object built by hand cannot store garbage). */
+export declare function encodeMcpOAuthTokenRecord(record: McpOAuthTokenRecord): string;
+/** Serialises a client record (re-validated, like `encodeMcpOAuthTokenRecord`). */
+export declare function encodeMcpOAuthClientRecord(record: McpOAuthClientRecord): string;
+/**
+ * The item at `mcp-oauth-client-secret:<id>`. A secret is only ever sent to the authorization server it
+ * belongs to: a config source that can redeclare the server (a trusted project overriding the user's
+ * scope) could otherwise point `authServerMetadataUrl` at its own token endpoint and have a Sign in click
+ * post the user's secret there.
+ *
+ * - `issuer` present: the secret goes to that issuer only (the host set it when the user knew it --
+ *   `encodeMcpOAuthClientSecretItem(secret, expectedIssuer)`, or the sign-in stamped it, below).
+ * - `issuer` absent: TRUST ON FIRST USE -- the first SUCCESSFUL pre-registered sign-in stamps the issuer it
+ *   used, and every later sign-in must match it (so does an existing pre-registered client record's).
+ *
+ * A bare string (a secret a host wrote before this shape) reads as `{ secret, issuer: undefined }`.
+ */
+export interface McpOAuthClientSecretItem {
+    secret: string;
+    issuer?: string;
+}
+export declare function decodeMcpOAuthClientSecretItem(raw: string): McpOAuthClientSecretItem;
+/** What a host writes at `mcpOAuthClientSecretAccount(serverUrl)`; `expectedIssuer` binds it up front. */
+export declare function encodeMcpOAuthClientSecretItem(secret: string, expectedIssuer?: string): string;
+/** Issuer equality as the MCP client compares it: exact, or differing only by one trailing slash. */
+export declare function sameIssuer(a: string, b: string): boolean;

package/dist/mcp-auth/refresh.d.ts

@@ -0,0 +1,34 @@
+import { type McpOAuthStore } from "./store.js";
+export interface RefreshMcpOAuthTokenOptions {
+    /** The token item's FULL account name, `mcp-oauth:<id>`. The client item is its prefix swap. */
+    account: string;
+    store: McpOAuthStore;
+    /** The network under the auth-HTTP policy (tests). The policy is applied on top, always. */
+    fetch?: typeof fetch;
+    /** The clock (tests). Epoch ms. */
+    now?: () => number;
+    /**
+     * WS-25, additive: the generation the ASKING session last read (`McpOAuthRefreshRequest.generation`).
+     * When the stored record has already moved past it, another caller refreshed first: the answer is
+     * `{ ok: true }` with the stored generation, and nothing is posted.
+     */
+    generation?: number;
+    /**
+     * WS-25, additive: a scope a `403 insufficient_scope` asked for (`McpOAuthRefreshRequest.stepUpScope`).
+     * A refresh cannot widen a grant (RFC 6749 §6), so it is recorded on the client registration for the
+     * next sign-in and the answer is `needs_auth`.
+     */
+    stepUpScope?: string;
+}
+export type RefreshMcpOAuthTokenResult = {
+    ok: true;
+    generation: number;
+} | {
+    ok: false;
+    reason: "needs_auth" | "transient";
+};
+/**
+ * Refreshes ONE sign-in (see this file's header). Pass the SAME `store` instance on every call in a process:
+ * the single-flight is per store object.
+ */
+export declare function refreshMcpOAuthToken(opts: RefreshMcpOAuthTokenOptions): Promise<RefreshMcpOAuthTokenResult>;

package/dist/mcp-auth/revoke.d.ts

@@ -0,0 +1,15 @@
+import { type McpOAuthStore } from "./store.js";
+export interface RevokeMcpOAuthOptions {
+    /** The token item's FULL account name, `mcp-oauth:<id>`. */
+    account: string;
+    store: McpOAuthStore;
+    /** The network under the auth-HTTP policy (tests). The policy is applied on top, always. */
+    fetch?: typeof fetch;
+    /**
+     * WS-25, additive (`winter mcp logout --forget-client`): also remove the client registration. Absent, it
+     * is KEPT (spec §1.6) -- re-registering on every sign-in would be DCR spam, and a pre-registered or CIMD
+     * client has nothing to re-register.
+     */
+    forgetClient?: boolean;
+}
+export declare function revokeMcpOAuth(opts: RevokeMcpOAuthOptions): Promise<void>;

package/dist/mcp-auth/session-provider.d.ts

@@ -0,0 +1,55 @@
+import type { McpOAuthRefreshAnswer, McpOAuthRefreshRequest } from "@yanlinglabs/winter-agent-sdk";
+import { type McpOAuthStore } from "./store.js";
+/** The host's answer, or `"unhandled"` when the host registered no `mcp_oauth_refresh` handler. */
+export type McpOAuthHostAsk = (request: McpOAuthRefreshRequest) => Promise<McpOAuthRefreshAnswer | "unhandled">;
+/** What a session hands every remote server's connection. */
+export interface McpSessionOAuth {
+    /** The Keychain (the session's own service), read-only unless the in-process fallback refreshes. */
+    store: McpOAuthStore;
+    /** Asks the host to refresh. Absent: always in-process. */
+    askHost?: McpOAuthHostAsk;
+    /**
+     * WS-25 §7: the host OWNS renewal (a host-brokered session: `store` is read-only, and no refresh token
+     * is in this process). A host answer of "unhandled" is then `transient`, never the in-process refresh.
+     */
+    hostOwnsRefresh?: boolean;
+    /** The sign-in door, for a server name -- the text a `needs-auth` error names (e.g. `winter mcp login linear`). */
+    signInHint: (serverName: string) => string;
+    /** The clock (tests). Epoch ms. */
+    now?: () => number;
+    /** The network the in-process fallback refreshes over (tests). */
+    fetch?: typeof fetch;
+}
+/** The server needs a (new) sign-in. Classified `needs_auth` wherever it surfaces. */
+export declare class McpNeedsAuthError extends Error {
+    readonly serverName: string;
+    constructor(serverName: string, why: string, hint: string);
+}
+/** A refresh that could not complete right now (the network, the authorization server's 5xx). */
+export declare class McpAuthRefreshUnavailableError extends Error {
+    constructor(serverName: string);
+}
+export interface McpSessionAuthProvider {
+    /** The MCP client's `AuthProvider.token()`: the bearer for the next request, or none. */
+    token(): Promise<string | undefined>;
+    /** The MCP client's `AuthProvider.onUnauthorized()`: make the next `token()` valid, or throw. */
+    onUnauthorized(): Promise<void>;
+    /** Before the transport exists: throws `McpNeedsAuthError` when the stored sign-in is already dead (spec §1.2). */
+    preflight(): Promise<void>;
+    /** A `403 insufficient_scope`: the host records the scope for the next sign-in (the answer is not awaited for anything). */
+    reportInsufficientScope(scope: string | undefined): Promise<void>;
+}
+export declare function createSessionAuthProvider(opts: {
+    serverName: string;
+    serverUrl: string;
+    oauth: McpSessionOAuth;
+}): McpSessionAuthProvider;
+/**
+ * The sign-in door a `needs-auth` error names, for a brand: `<cli> mcp login <server>` and the app's MCP
+ * settings. The CLI name is the home directory's token (the dot-dir without its dot), the one brand field that
+ * IS the command a user types.
+ */
+export declare function mcpSignInHint(brand: {
+    homeDirName: string;
+    productName: string;
+}, serverName: string): string;