@yanlinglabs/winter-agent-runtime 0.0.29 → 0.0.30

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

@@ -0,0 +1,85 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import { type HostRequestSender } from "../provider/host-credentials.js";
+import { type McpOAuthClientRecord, type McpOAuthTokenRecord } from "./records.js";
+export interface McpOAuthStore {
+    read(account: string): Promise<string | null>;
+    write(account: string, value: string): Promise<void>;
+    remove(account: string): Promise<void>;
+}
+/** A process-local store, for tests and for a host that keeps sign-ins only for its own lifetime. */
+export declare function createMemoryMcpOAuthStore(initial?: Record<string, string>): McpOAuthStore & {
+    readonly entries: Map<string, string>;
+};
+/**
+ * The macOS Keychain, one service. `service` is the host's own (its brand's `keychainService`, per
+ * profile); absent, the SDK's `DEFAULT_KEYCHAIN_SERVICE`.
+ */
+export declare function createKeychainMcpOAuthStore(service?: string): McpOAuthStore;
+/** Reads and validates a token record; `null` when there is no item. A malformed item throws typed. */
+export declare function readTokenRecord(store: McpOAuthStore, account: string): Promise<McpOAuthTokenRecord | null>;
+/** Reads and validates a client record; `null` when there is no item. */
+export declare function readClientRecord(store: McpOAuthStore, account: string): Promise<McpOAuthClientRecord | null>;
+export declare function writeTokenRecord(store: McpOAuthStore, account: string, record: McpOAuthTokenRecord): Promise<void>;
+export declare function writeClientRecord(store: McpOAuthStore, account: string, record: McpOAuthClientRecord): Promise<void>;
+/**
+ * Reads a token record, answering `null` for a MALFORMED one as well as an absent one -- for the paths
+ * where a broken item must behave as "not signed in" (the session's read, a refresh) rather than fail
+ * the connection with a codec error. A NEWER record version is still thrown: acting as "not signed in"
+ * on it would send the user to sign in again and overwrite what the newer Winter wrote.
+ */
+export declare function readTokenRecordLenient(store: McpOAuthStore, account: string): Promise<McpOAuthTokenRecord | null>;
+/**
+ * TEST-ONLY: a JSON file of `{ account: value }`, re-read on every read so a second process's write
+ * (a fake host's refresh) is seen. Selected ONLY by `mcpOAuthTestStoreEnvName(brand)` from the original process env (see `resolveSessionMcpOAuthStore`), the same
+ * named-test-seam posture as `WINTER_TEST_PROVIDER`: the compiled-binary gate (`verify:mcp-oauth`) must
+ * hand a spawned `winter` the fixture's sign-ins without the Keychain, which would prompt for an item a
+ * different binary wrote. It writes the fixture's throwaway tokens to a temp file -- which is exactly why
+ * nothing but that variable selects it.
+ */
+export declare function createTestFileMcpOAuthStore(path: string): McpOAuthStore & {
+    readonly testFile: string;
+};
+/**
+ * The env name of the test seam above, BRAND-DERIVED (`<envPrefix>TEST_MCP_OAUTH_STORE_FILE`;
+ * `WINTER_TEST_MCP_OAUTH_STORE_FILE` for Winter). Every settings tier's `env` block refuses it
+ * (`settings/env-filter.ts`'s `ALL_TIER_REFUSED_ENV`): a trusted project that could set it would move the
+ * session's sign-ins into a file it controls.
+ */
+export declare function mcpOAuthTestStoreEnvName(brand: Pick<BrandProfile, "envPrefix">): string;
+/** Winter's spelling of the name, for the gates that set it. */
+export declare const MCP_OAUTH_TEST_STORE_ENV: string;
+/**
+ * The store a SESSION reads its sign-ins from: the session's own Keychain service (the brand's, as for
+ * every other `{ kind: "keychain" }` credential), or the test seam's file.
+ *
+ * The seam is honoured only when ALL of these hold, so no configuration path can reach it:
+ *   - `testStoreFile` came from the ORIGINAL process environment (the caller reads it before any
+ *     settings tier's `env` is merged -- production-wiring captures it first, and the tiers refuse the
+ *     name anyway);
+ *   - the session names a Keychain service explicitly, and it is NEITHER the SDK's default production
+ *     service (`DEFAULT_KEYCHAIN_SERVICE`, the dist profile's) NOR its `.dev` twin: a gate names its own throwaway
+ *     service, a production session never can without also changing where its real credentials live.
+ */
+export declare function resolveSessionMcpOAuthStore(opts: {
+    keychainService: string | undefined;
+    testStoreFile: string | undefined;
+}): McpOAuthStore;
+/**
+ * What a session sees in place of an MCP sign-in's refresh token when its host holds the real one: a
+ * non-secret marker that says "a refresh is possible -- ask the host". The session provider only ever
+ * tests a record's `refreshToken` for PRESENCE, so this keeps §1.2's startup rules exact (expired WITH a
+ * refresh token -> ask the host; WITHOUT -> needs-auth) while no refresh token enters the session.
+ */
+export declare const MCP_OAUTH_HOST_HELD_REFRESH_TOKEN = "host-held";
+/**
+ * For the HOST answering `credential_resolve` for an `mcp-oauth:<id>` account: the stored record's JSON
+ * with its refresh token replaced by `MCP_OAUTH_HOST_HELD_REFRESH_TOKEN` (and nothing else changed).
+ * Validates on the way (a malformed or newer record is thrown typed, like every read).
+ */
+export declare function toSessionMcpTokenRecord(raw: string): string;
+/**
+ * A host-brokered session's MCP token store: `read` is one `credential_resolve` for the account; there is
+ * no Keychain read in this process at all. `write`/`remove` refuse typed -- the host is the only writer
+ * (it refreshes on `mcp_oauth_refresh`, and signs in and out on its own doors).
+ */
+export declare function createHostBrokeredMcpOAuthStore(sender: HostRequestSender): McpOAuthStore;

package/dist/mcp-auth/test-fixture-as.d.ts

@@ -0,0 +1,72 @@
+export interface FixtureAsOptions {
+    /** false: the legacy variant -- no protected-resource metadata and no RFC 8414 document. Default true. */
+    metadata?: boolean;
+    /** Advertise `registration_endpoint` and accept RFC 7591 registrations. Default true. */
+    dcr?: boolean;
+    /** Advertise `client_id_metadata_document_supported`. Default false. */
+    cimd?: boolean;
+    /** Client ID Metadata Documents by their URL (the client_id). */
+    cimdDocuments?: Record<string, {
+        client_id: string;
+        redirect_uris: string[];
+        [k: string]: unknown;
+    }>;
+    /** Pre-registered clients; each redirect URI must match exactly (port included). */
+    preregistered?: Array<{
+        clientId: string;
+        clientSecret?: string;
+        redirectUris: string[];
+    }>;
+    /** Access token lifetime in seconds; `null` issues no `expires_in` at all. Default 3600. */
+    accessTokenTtlSec?: number | null;
+    /** Issue refresh tokens. Default true. */
+    refreshTokens?: boolean;
+    /** `scopes_supported` on both documents, and the scope a sign-in gets when it asks for none. Default ["read"]. */
+    scopesSupported?: string[];
+    /** The scope the `step_up` tool demands (403 insufficient_scope without it). Default "admin". */
+    stepUpScope?: string;
+    /** Send RFC 9207 `iss` on the redirect and advertise it. Default true. */
+    issParameter?: boolean;
+    /** Advertise `revocation_endpoint`. Default true. */
+    revocation?: boolean;
+    /** Delay every `/token` answer by this many ms (a test ends a sign-in DURING its code exchange). */
+    tokenDelayMs?: number;
+    /** Publish the protected resource as the bare ORIGIN (no path) -- the RFC 8707 indicator form a URL round trip would change. */
+    pathlessResource?: boolean;
+}
+export interface FixtureAs {
+    readonly origin: string;
+    readonly issuer: string;
+    /** The protected MCP endpoint. */
+    readonly mcpUrl: string;
+    /** Every request, in order: `METHOD /path`. */
+    readonly log: string[];
+    /** Every POST to `/token`, by grant type, in order. */
+    readonly tokenPosts: string[];
+    /** The `resource` form parameter of every POST to `/token`, in order (`null` when absent). */
+    readonly tokenResources: Array<string | null>;
+    /** Every request that reached `/mcp` (answered or 401). */
+    readonly mcpRequests: number;
+    /** Registered DCR clients, in order. */
+    readonly registrations: Array<{
+        clientId: string;
+        redirectUris: string[];
+    }>;
+    /** The redirect URIs `/authorize` was asked to use, in order. */
+    readonly authorizeRedirects: string[];
+    /** Families revoked by refresh-token reuse. */
+    readonly reuseRevokedFamilies: string[];
+    /** Tokens revoked through `/revoke`. */
+    readonly revokedViaEndpoint: string[];
+    /** The browser: GET the authorize URL (auto-approved), then follow its 302 to the loopback callback. Returns the callback's status. */
+    approve(authUrl: string): Promise<{
+        callbackStatus: number;
+        location: string;
+    }>;
+    /** Forgets every DCR registration, as an authorization server that expired its dynamic clients does. */
+    forgetRegistrations(): void;
+    /** Makes every access token issued so far invalid at `/mcp` (401), as an expiry would. */
+    expireAllAccessTokens(): void;
+    close(): void;
+}
+export declare function startFixtureAs(opts?: FixtureAsOptions): FixtureAs;

package/dist/mcp-auth.d.ts

@@ -0,0 +1,14 @@
+export { canonicalMcpServerUrl, clientAccountForTokenAccount, isMcpOAuthTokenAccount, mcpOAuthAccountId, mcpOAuthClientAccount, mcpOAuthClientSecretAccount, mcpOAuthTokenAccount, MCP_OAUTH_CLIENT_ACCOUNT_PREFIX, MCP_OAUTH_TOKEN_ACCOUNT_PREFIX, } from "./mcp-auth/account.js";
+export { McpOAuthError, type McpOAuthErrorCode } from "./mcp-auth/errors.js";
+export { validateMcpOAuthConfig } from "./mcp-auth/config.js";
+export { evaluateMcpAuthUrl } from "./mcp-auth/fetch-policy.js";
+export { decodeMcpOAuthClientRecord, decodeMcpOAuthClientSecretItem, encodeMcpOAuthClientSecretItem, type McpOAuthClientSecretItem, decodeMcpOAuthTokenRecord, encodeMcpOAuthClientRecord, encodeMcpOAuthTokenRecord, sameIssuer, type McpOAuthClientRecord, type McpOAuthTokenRecord, } from "./mcp-auth/records.js";
+export { discoverMcpOAuthIssuer, type DiscoverMcpOAuthIssuerOptions, type McpOAuthIssuerInfo } from "./mcp-auth/discovery.js";
+export { createKeychainMcpOAuthStore, createMemoryMcpOAuthStore, MCP_OAUTH_HOST_HELD_REFRESH_TOKEN, toSessionMcpTokenRecord, type McpOAuthStore } from "./mcp-auth/store.js";
+export { MCP_OAUTH_CALLBACK_PATH, MCP_OAUTH_EXPIRY_SKEW_MS, MCP_OAUTH_LOGIN_TIMEOUT_MS, MCP_OAUTH_SESSION_CACHE_MS, WINTER_MCP_CLIENT_METADATA_URL, } from "./mcp-auth/constants.js";
+export { startMcpOAuthLogin, type McpOAuthLogin, type McpOAuthLoginOutcome, type StartMcpOAuthLoginOptions } from "./mcp-auth/login.js";
+export { refreshMcpOAuthToken, type RefreshMcpOAuthTokenOptions, type RefreshMcpOAuthTokenResult } from "./mcp-auth/refresh.js";
+export { revokeMcpOAuth, type RevokeMcpOAuthOptions } from "./mcp-auth/revoke.js";
+export { CREDENTIAL_RESOLVE_SUBTYPE, type CredentialResolveAnswer, type CredentialResolveRequest, MCP_OAUTH_REFRESH_SUBTYPE, type McpOAuthConfig, type McpOAuthRefreshAnswer, type McpOAuthRefreshRequest, type McpOAuthSecretRef } from "@yanlinglabs/winter-agent-sdk";
+/** The status string `mcp_status` / `system/init.mcp_servers` report for a server that needs sign-in. */
+export declare const MCP_STATUS_NEEDS_AUTH = "needs-auth";

package/dist/mcp-auth.js

@@ -0,0 +1,493 @@
+import {
+  McpOAuthError2,
+  boundedReason,
+  MCP_OAUTH_TOKEN_ACCOUNT_PREFIX2,
+  MCP_OAUTH_CLIENT_ACCOUNT_PREFIX2,
+  canonicalMcpServerUrl2,
+  mcpOAuthAccountId2,
+  mcpOAuthTokenAccount2,
+  mcpOAuthClientAccount2,
+  mcpOAuthClientSecretAccount2,
+  isMcpOAuthTokenAccount2,
+  clientAccountForTokenAccount2,
+  WINTER_MCP_CLIENT_METADATA_URL2,
+  MCP_OAUTH_CALLBACK_PATH2,
+  MCP_OAUTH_EXPIRY_SKEW_MS2,
+  MCP_OAUTH_SESSION_CACHE_MS2,
+  MCP_OAUTH_LOGIN_TIMEOUT_MS2,
+  MCP_OAUTH_STATE_BYTES,
+  evaluateMcpAuthUrl2,
+  isLoopbackMcpServer,
+  createMcpAuthFetch,
+  decodeMcpOAuthTokenRecord2,
+  decodeMcpOAuthClientRecord2,
+  encodeMcpOAuthTokenRecord2,
+  encodeMcpOAuthClientRecord2,
+  decodeMcpOAuthClientSecretItem2,
+  encodeMcpOAuthClientSecretItem2,
+  sameIssuer2,
+  fetchAuthorizationServerMetadataDocument,
+  loadAuthorizationServer,
+  discoverMcpOAuthIssuer2,
+  createMemoryMcpOAuthStore2,
+  createKeychainMcpOAuthStore2,
+  readClientRecord,
+  writeTokenRecord,
+  writeClientRecord,
+  readTokenRecordLenient,
+  MCP_OAUTH_HOST_HELD_REFRESH_TOKEN2,
+  toSessionMcpTokenRecord2,
+  refreshMcpOAuthToken2
+} from "./index-z6s3r4xm.js";
+import {
+  validateMcpOAuthConfig2
+} from "./index-bgeqc7ax.js";
+// src/mcp-auth/login.ts
+import { auth, computeScopeUnion, exchangeAuthorization, OAuthError, OAuthErrorCode } from "@modelcontextprotocol/client";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+var activeFlows = new Map;
+var CLIENT_NAME = "Winter";
+function portOf(redirectUri) {
+  try {
+    const url = new URL(redirectUri);
+    return url.hostname === "127.0.0.1" && url.port !== "" ? Number(url.port) : undefined;
+  } catch {
+    return;
+  }
+}
+function sameState(a, b) {
+  if (a === null)
+    return false;
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+function reasonOf(err) {
+  if (err instanceof McpOAuthError2)
+    return err.code;
+  if (err instanceof OAuthError)
+    return `oauth_error:${err.code}`;
+  return err instanceof Error ? err.name : "failed";
+}
+var LISTENER_HEADERS = { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", connection: "close" };
+function page(title, status) {
+  const body = `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:-apple-system,sans-serif;padding:3em"><h2>${title}</h2><p>You can close this window.</p></body>`;
+  return new Response(body, { status, headers: LISTENER_HEADERS });
+}
+async function readSecret(opts, account) {
+  let secret;
+  try {
+    secret = opts.readClientSecret !== undefined ? await opts.readClientSecret(account) : await opts.store.read(account);
+  } catch {
+    throw new McpOAuthError2("client_secret_unavailable", `the client secret at Keychain account "${account}" could not be read`);
+  }
+  if (secret === null || secret === "")
+    throw new McpOAuthError2("client_secret_unavailable", `no client secret is stored at Keychain account "${account}"`);
+  return secret;
+}
+function originOf(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return "an unparseable issuer";
+  }
+}
+function bindListener(port, handler) {
+  return Bun.serve({ hostname: "127.0.0.1", port, fetch: handler });
+}
+async function startMcpOAuthLogin(opts) {
+  const serverVerdict = evaluateMcpAuthUrl2(opts.serverUrl, { allowLoopback: true });
+  if (!serverVerdict.ok)
+    throw new McpOAuthError2("policy_refused", `the MCP server URL is refused: ${serverVerdict.reason}`);
+  const account = mcpOAuthTokenAccount2(opts.serverUrl);
+  const clientAccount = mcpOAuthClientAccount2(opts.serverUrl);
+  const now = opts.now ?? Date.now;
+  const oauth = opts.oauth ?? {};
+  const clientMetadataUrl = opts.clientMetadataUrl ?? WINTER_MCP_CLIENT_METADATA_URL2;
+  const allowLoopback = isLoopbackMcpServer(opts.serverUrl);
+  const fetchFn = createMcpAuthFetch({ ...opts.fetch !== undefined ? { fetch: opts.fetch } : {}, allowLoopback });
+  let supersededEarly = false;
+  let finishLive;
+  const supersede = (reason) => {
+    if (finishLive !== undefined)
+      finishLive({ ok: false, reason });
+    else
+      supersededEarly = true;
+  };
+  activeFlows.get(account)?.("login_superseded");
+  activeFlows.set(account, supersede);
+  const checkpoint = () => {
+    if (supersededEarly)
+      throw new McpOAuthError2("login_superseded", "a newer sign-in for this server started");
+  };
+  const release = () => {
+    if (activeFlows.get(account) === supersede)
+      activeFlows.delete(account);
+  };
+  let server;
+  let onCallback = async () => page("Not ready", 503);
+  let codeVerifier;
+  let discovery;
+  let authUrl;
+  let clientDecision;
+  let lastClientInfo;
+  let forgetExisting = false;
+  let redirectUri = "";
+  let existingClient = null;
+  let requestedScope;
+  let recordFor;
+  let preSecretItem;
+  let preSecret;
+  const state = randomBytes(MCP_OAUTH_STATE_BYTES).toString("base64url");
+  try {
+    preSecretItem = oauth.clientId !== undefined && oauth.clientSecretRef !== undefined ? decodeMcpOAuthClientSecretItem2(await readSecret(opts, mcpOAuthClientSecretAccount2(opts.serverUrl))) : undefined;
+    preSecret = preSecretItem?.secret;
+    checkpoint();
+    existingClient = await readClientRecord(opts.store, clientAccount).catch(() => null);
+    checkpoint();
+    const handler = (req) => {
+      const url = new URL(req.url);
+      if (req.method !== "GET" || url.pathname !== MCP_OAUTH_CALLBACK_PATH2)
+        return new Response("not found", { status: 404, headers: { connection: "close" } });
+      return onCallback(req);
+    };
+    let reuseRegistration = false;
+    if (oauth.callbackPort !== undefined) {
+      try {
+        server = bindListener(oauth.callbackPort, handler);
+      } catch {
+        throw new McpOAuthError2("callback_port_unavailable", `the sign-in callback port ${oauth.callbackPort} (oauth.callbackPort) is in use`);
+      }
+    } else {
+      const persistedPort = existingClient?.registeredVia === "dcr" && oauth.clientId === undefined ? portOf(existingClient.redirectUri) : undefined;
+      if (persistedPort !== undefined) {
+        try {
+          server = bindListener(persistedPort, handler);
+          reuseRegistration = true;
+        } catch {}
+      }
+      server ??= bindListener(0, handler);
+    }
+    redirectUri = `http://127.0.0.1:${server.port}${MCP_OAUTH_CALLBACK_PATH2}`;
+    if (oauth.authServerMetadataUrl !== undefined) {
+      try {
+        const metadata = await fetchAuthorizationServerMetadataDocument(oauth.authServerMetadataUrl, fetchFn);
+        discovery = { authorizationServerUrl: metadata.issuer, authorizationServerMetadata: metadata };
+      } catch (err) {
+        if (err instanceof McpOAuthError2 && (err.code === "metadata_issuer_mismatch" || err.code === "policy_refused"))
+          throw err;
+        throw new McpOAuthError2("login_failed", `the configured authorization server metadata (oauth.authServerMetadataUrl) could not be read: ${boundedReason(err)}`);
+      }
+      checkpoint();
+    }
+    requestedScope = computeScopeUnion(oauth.scopes !== undefined && oauth.scopes.length > 0 ? oauth.scopes.join(" ") : undefined, existingClient?.stepUpScope);
+    const existing = existingClient;
+    const clientRecordFor = (info, issuer) => {
+      const via = oauth.clientId !== undefined && info.client_id === oauth.clientId ? "preregistered" : info.client_id === clientMetadataUrl ? "cimd" : "dcr";
+      const secret = via === "preregistered" ? preSecret : info.client_secret;
+      const stepUpScope = existing !== null && existing.issuer === issuer ? existing.stepUpScope : undefined;
+      return {
+        v: 1,
+        kind: "mcp-oauth-client",
+        serverUrl: opts.serverUrl,
+        issuer,
+        clientId: info.client_id,
+        ...secret !== undefined ? { clientSecret: secret } : {},
+        registeredVia: via,
+        redirectUri,
+        ...discovery?.resourceMetadataUrl !== undefined ? { resourceMetadataUrl: discovery.resourceMetadataUrl } : {},
+        ...oauth.authServerMetadataUrl !== undefined ? { authorizationServerUrl: oauth.authServerMetadataUrl } : discovery?.authorizationServerUrl !== undefined ? { authorizationServerUrl: String(discovery.authorizationServerUrl) } : {},
+        ...stepUpScope !== undefined ? { stepUpScope } : {}
+      };
+    };
+    recordFor = clientRecordFor;
+    const clientInformation = (ctx) => {
+      if (clientDecision !== undefined)
+        return clientDecision;
+      if (oauth.clientId !== undefined) {
+        if (preSecretItem !== undefined) {
+          const bound = preSecretItem.issuer ?? (existing?.registeredVia === "preregistered" ? existing.issuer : undefined);
+          if (ctx === undefined || bound !== undefined && !sameIssuer2(bound, ctx.issuer)) {
+            throw new McpOAuthError2("client_secret_issuer_mismatch", `the pre-registered client secret for this server belongs to ${bound !== undefined ? originOf(bound) : "another authorization server"}, but this sign-in's authorization server is ${ctx !== undefined ? originOf(ctx.issuer) : "unknown"}; it is not sent`);
+          }
+        }
+        const stamp = ctx?.issuer;
+        return { client_id: oauth.clientId, ...preSecret !== undefined ? { client_secret: preSecret } : {}, ...stamp !== undefined ? { issuer: stamp } : {} };
+      }
+      if (forgetExisting || existing === null || ctx === undefined || existing.issuer !== ctx.issuer)
+        return;
+      if (existing.registeredVia === "dcr" && reuseRegistration && existing.redirectUri === redirectUri) {
+        return { client_id: existing.clientId, ...existing.clientSecret !== undefined ? { client_secret: existing.clientSecret } : {}, issuer: existing.issuer };
+      }
+      if (existing.registeredVia === "cimd" && existing.clientId === clientMetadataUrl) {
+        return { client_id: existing.clientId, issuer: existing.issuer };
+      }
+      return;
+    };
+    const provider = {
+      get redirectUrl() {
+        return redirectUri;
+      },
+      ...oauth.clientId === undefined ? { clientMetadataUrl } : {},
+      get clientMetadata() {
+        return {
+          client_name: CLIENT_NAME,
+          redirect_uris: [redirectUri],
+          grant_types: ["authorization_code", "refresh_token"],
+          response_types: ["code"],
+          token_endpoint_auth_method: "none",
+          ...requestedScope !== undefined ? { scope: requestedScope } : {}
+        };
+      },
+      state: () => state,
+      clientInformation(ctx) {
+        const info = clientInformation(ctx);
+        if (info !== undefined)
+          lastClientInfo = info;
+        return info;
+      },
+      async saveClientInformation(info, ctx) {
+        clientDecision = info;
+        lastClientInfo = info;
+        const issuer = info.issuer ?? ctx?.issuer;
+        if (issuer === undefined)
+          return;
+        await writeClientRecord(opts.store, clientAccount, clientRecordFor(info, issuer));
+      },
+      tokens: () => {
+        return;
+      },
+      saveTokens: () => {
+        throw new McpOAuthError2("login_failed", "the sign-in's first leg does not receive tokens");
+      },
+      redirectToAuthorization(url) {
+        authUrl = url;
+      },
+      saveCodeVerifier(verifier) {
+        codeVerifier = verifier;
+      },
+      codeVerifier() {
+        if (codeVerifier === undefined)
+          throw new McpOAuthError2("login_failed", "no code verifier was recorded for this sign-in");
+        return codeVerifier;
+      },
+      saveDiscoveryState(next) {
+        discovery = next;
+      },
+      discoveryState: () => discovery,
+      async invalidateCredentials(scope) {
+        if (scope === "all" || scope === "client") {
+          clientDecision = undefined;
+          forgetExisting = true;
+        }
+        if (scope === "all" || scope === "discovery")
+          discovery = oauth.authServerMetadataUrl !== undefined ? discovery : undefined;
+        if (scope === "all" || scope === "verifier")
+          codeVerifier = undefined;
+      }
+    };
+    let result;
+    try {
+      result = await auth(provider, { serverUrl: opts.serverUrl, ...requestedScope !== undefined ? { scope: requestedScope } : {}, fetchFn });
+    } catch (err) {
+      if (err instanceof McpOAuthError2)
+        throw err;
+      throw new McpOAuthError2("login_failed", `the sign-in could not start: ${boundedReason(err)}`);
+    }
+    checkpoint();
+    if (result !== "REDIRECT" || authUrl === undefined)
+      throw new McpOAuthError2("login_failed", "the authorization server did not produce an authorization URL");
+    const verdict = evaluateMcpAuthUrl2(authUrl, { allowLoopback });
+    if (!verdict.ok)
+      throw new McpOAuthError2("policy_refused", `the authorization URL is refused: ${verdict.reason}`);
+  } catch (err) {
+    server?.stop(true);
+    release();
+    throw err;
+  }
+  const liveServer = server;
+  const authorizeUrl = authUrl;
+  const metadata = discovery?.authorizationServerMetadata;
+  const authorizationServerUrl = discovery?.authorizationServerUrl !== undefined ? String(discovery.authorizationServerUrl) : new URL("/", opts.serverUrl).toString();
+  const issuer = metadata?.issuer ?? authorizationServerUrl;
+  const issuerOrigin = new URL(issuer).origin;
+  const resource = discovery?.resourceMetadata?.resource;
+  const client = clientDecision ?? lastClientInfo;
+  const usedDcrRegistration = client !== undefined && oauth.clientId === undefined && client.client_id !== clientMetadataUrl;
+  let settle;
+  const done = new Promise((resolve) => {
+    settle = resolve;
+  });
+  let finished = false;
+  let redeeming = false;
+  const timeoutMs = opts.timeoutMs ?? MCP_OAUTH_LOGIN_TIMEOUT_MS2;
+  const finish = (outcome) => {
+    if (finished)
+      return;
+    finished = true;
+    clearTimeout(timer);
+    release();
+    liveServer.stop();
+    settle(outcome);
+  };
+  const timer = setTimeout(() => finish({ ok: false, reason: "login_timeout" }), timeoutMs);
+  timer.unref?.();
+  finishLive = finish;
+  onCallback = async (req) => {
+    if (finished || redeeming)
+      return page("This sign-in has already finished", 410);
+    const params = new URL(req.url).searchParams;
+    if (!sameState(params.get("state"), state))
+      return page("Sign-in failed: the request did not come from this sign-in", 400);
+    const error = params.get("error");
+    if (error !== null) {
+      const code = /^[a-z_]{1,64}$/.test(error) ? error : "unknown";
+      finish({ ok: false, reason: `authorization_denied:${code}` });
+      return page("Sign-in was not approved", 400);
+    }
+    const code = params.get("code");
+    if (code === null || code === "")
+      return page("Sign-in failed: no authorization code", 400);
+    if (client === undefined || codeVerifier === undefined) {
+      finish({ ok: false, reason: "token_exchange_failed:login_failed" });
+      return page("Sign-in failed", 400);
+    }
+    redeeming = true;
+    try {
+      const iss = params.get("iss");
+      const tokens = await exchangeAuthorization(authorizationServerUrl, {
+        ...metadata !== undefined ? { metadata } : {},
+        clientInformation: client,
+        authorizationCode: code,
+        ...iss !== null ? { iss } : {},
+        codeVerifier,
+        redirectUri,
+        ...resource !== undefined ? { resource } : {},
+        fetchFn
+      });
+      if (finished)
+        return page("This sign-in has already finished", 410);
+      const previous = await readTokenRecordLenient(opts.store, account).catch(() => null);
+      if (finished)
+        return page("This sign-in has already finished", 410);
+      await writeTokenRecord(opts.store, account, {
+        v: 1,
+        kind: "mcp-oauth",
+        serverUrl: opts.serverUrl,
+        issuer,
+        accessToken: tokens.access_token,
+        ...tokens.refresh_token !== undefined ? { refreshToken: tokens.refresh_token } : {},
+        ...typeof tokens.expires_in === "number" ? { expiresAt: now() + tokens.expires_in * 1000 } : {},
+        ...tokens.scope !== undefined ? { scope: tokens.scope } : {},
+        generation: (previous?.generation ?? 0) + 1
+      });
+      if (recordFor !== undefined)
+        await writeClientRecord(opts.store, clientAccount, recordFor(client, issuer));
+      if (finished)
+        return page("This sign-in has already finished", 410);
+      if (preSecretItem !== undefined && preSecretItem.issuer === undefined && opts.readClientSecret === undefined) {
+        await opts.store.write(mcpOAuthClientSecretAccount2(opts.serverUrl), encodeMcpOAuthClientSecretItem2(preSecretItem.secret, issuer)).catch(() => {});
+      }
+      finish({ ok: true });
+      return page("Signed in to the MCP server", 200);
+    } catch (err) {
+      if (err instanceof OAuthError && (err.code === OAuthErrorCode.InvalidClient || err.code === OAuthErrorCode.UnauthorizedClient) && usedDcrRegistration) {
+        await opts.store.remove(clientAccount).catch(() => {});
+      }
+      finish({ ok: false, reason: `token_exchange_failed:${reasonOf(err)}` });
+      return page("Sign-in failed", 400);
+    }
+  };
+  return {
+    authUrl: authorizeUrl.toString(),
+    issuer,
+    issuerOrigin,
+    authorizeOrigin: authorizeUrl.origin,
+    done,
+    cancel: () => finish({ ok: false, reason: "login_cancelled" })
+  };
+}
+// src/mcp-auth/revoke.ts
+async function revokeMcpOAuth(opts) {
+  const clientAccount = clientAccountForTokenAccount2(opts.account);
+  try {
+    await revokeRemotely(opts, clientAccount);
+  } catch {
+    console.error(`winter: mcp-auth: revocation for ${opts.account} did not complete; the local sign-out proceeds`);
+  }
+  await opts.store.remove(opts.account);
+  if (opts.forgetClient === true)
+    await opts.store.remove(clientAccount);
+}
+async function revokeRemotely(opts, clientAccount) {
+  const record = await readTokenRecordLenient(opts.store, opts.account);
+  if (record === null)
+    return;
+  const client = await readClientRecord(opts.store, clientAccount).catch(() => null);
+  if (client === null || client.issuer !== record.issuer)
+    return;
+  const fetchFn = createMcpAuthFetch({ ...opts.fetch !== undefined ? { fetch: opts.fetch } : {}, allowLoopback: isLoopbackMcpServer(record.serverUrl) });
+  const server = await loadAuthorizationServer({ authorizationServerUrl: client.authorizationServerUrl ?? record.issuer, expectedIssuer: record.issuer, fetchFn });
+  const endpoint = server.metadata?.revocation_endpoint;
+  if (typeof endpoint !== "string")
+    return;
+  const tokens = [];
+  if (record.refreshToken !== undefined)
+    tokens.push([record.refreshToken, "refresh_token"]);
+  tokens.push([record.accessToken, "access_token"]);
+  for (const [token, hint] of tokens)
+    await revokeOne(fetchFn, endpoint, token, hint, client.clientId, client.clientSecret, opts.account);
+}
+async function revokeOne(fetchFn, endpoint, token, hint, clientId, clientSecret, account) {
+  const body = new URLSearchParams({ token, token_type_hint: hint });
+  const headers = new Headers({ "content-type": "application/x-www-form-urlencoded" });
+  if (clientSecret !== undefined)
+    headers.set("authorization", `Basic ${btoa(`${encodeURIComponent(clientId)}:${encodeURIComponent(clientSecret)}`)}`);
+  else
+    body.set("client_id", clientId);
+  const response = await fetchFn(endpoint, { method: "POST", headers, body });
+  await response.text().catch(() => {});
+  if (!response.ok)
+    console.error(`winter: mcp-auth: revocation for ${account} (${hint}) answered HTTP ${response.status}`);
+}
+
+// src/mcp-auth.ts
+import { CREDENTIAL_RESOLVE_SUBTYPE, MCP_OAUTH_REFRESH_SUBTYPE } from "@yanlinglabs/winter-agent-sdk";
+var MCP_STATUS_NEEDS_AUTH = "needs-auth";
+export {
+  CREDENTIAL_RESOLVE_SUBTYPE,
+  MCP_OAUTH_CALLBACK_PATH2 as MCP_OAUTH_CALLBACK_PATH,
+  MCP_OAUTH_CLIENT_ACCOUNT_PREFIX2 as MCP_OAUTH_CLIENT_ACCOUNT_PREFIX,
+  MCP_OAUTH_EXPIRY_SKEW_MS2 as MCP_OAUTH_EXPIRY_SKEW_MS,
+  MCP_OAUTH_HOST_HELD_REFRESH_TOKEN2 as MCP_OAUTH_HOST_HELD_REFRESH_TOKEN,
+  MCP_OAUTH_LOGIN_TIMEOUT_MS2 as MCP_OAUTH_LOGIN_TIMEOUT_MS,
+  MCP_OAUTH_REFRESH_SUBTYPE,
+  MCP_OAUTH_SESSION_CACHE_MS2 as MCP_OAUTH_SESSION_CACHE_MS,
+  MCP_OAUTH_TOKEN_ACCOUNT_PREFIX2 as MCP_OAUTH_TOKEN_ACCOUNT_PREFIX,
+  MCP_STATUS_NEEDS_AUTH,
+  McpOAuthError2 as McpOAuthError,
+  WINTER_MCP_CLIENT_METADATA_URL2 as WINTER_MCP_CLIENT_METADATA_URL,
+  canonicalMcpServerUrl2 as canonicalMcpServerUrl,
+  clientAccountForTokenAccount2 as clientAccountForTokenAccount,
+  createKeychainMcpOAuthStore2 as createKeychainMcpOAuthStore,
+  createMemoryMcpOAuthStore2 as createMemoryMcpOAuthStore,
+  decodeMcpOAuthClientRecord2 as decodeMcpOAuthClientRecord,
+  decodeMcpOAuthClientSecretItem2 as decodeMcpOAuthClientSecretItem,
+  decodeMcpOAuthTokenRecord2 as decodeMcpOAuthTokenRecord,
+  discoverMcpOAuthIssuer2 as discoverMcpOAuthIssuer,
+  encodeMcpOAuthClientRecord2 as encodeMcpOAuthClientRecord,
+  encodeMcpOAuthClientSecretItem2 as encodeMcpOAuthClientSecretItem,
+  encodeMcpOAuthTokenRecord2 as encodeMcpOAuthTokenRecord,
+  evaluateMcpAuthUrl2 as evaluateMcpAuthUrl,
+  isMcpOAuthTokenAccount2 as isMcpOAuthTokenAccount,
+  mcpOAuthAccountId2 as mcpOAuthAccountId,
+  mcpOAuthClientAccount2 as mcpOAuthClientAccount,
+  mcpOAuthClientSecretAccount2 as mcpOAuthClientSecretAccount,
+  mcpOAuthTokenAccount2 as mcpOAuthTokenAccount,
+  refreshMcpOAuthToken2 as refreshMcpOAuthToken,
+  revokeMcpOAuth,
+  sameIssuer2 as sameIssuer,
+  startMcpOAuthLogin,
+  toSessionMcpTokenRecord2 as toSessionMcpTokenRecord,
+  validateMcpOAuthConfig2 as validateMcpOAuthConfig
+};