@yanlinglabs/winter-agent-runtime 0.0.29 → 0.0.31

package/dist/index-z6s3r4xm.js

@@ -0,0 +1,903 @@
+// src/mcp-auth/errors.ts
+import { OAuthError } from "@modelcontextprotocol/client";
+
+class McpOAuthError2 extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "McpOAuthError";
+    this.code = code;
+  }
+}
+function boundedReason(err) {
+  if (err instanceof McpOAuthError2)
+    return err.message.slice(0, 300);
+  if (err instanceof OAuthError)
+    return `oauth_error:${err.code}`;
+  if (err instanceof Error)
+    return `${err.name}: ${err.message.replace(/[\u0000-\u001f\u007f]+/g, " ").slice(0, 200)}`;
+  return "failed";
+}
+
+// src/mcp-auth/account.ts
+import { createHash } from "node:crypto";
+var MCP_OAUTH_TOKEN_ACCOUNT_PREFIX2 = "mcp-oauth:";
+var MCP_OAUTH_CLIENT_ACCOUNT_PREFIX2 = "mcp-oauth-client:";
+function canonicalMcpServerUrl2(serverUrl) {
+  let url;
+  try {
+    url = new URL(serverUrl);
+  } catch {
+    throw new McpOAuthError2("invalid_server_url", "an MCP server URL must be an absolute http(s) URL");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new McpOAuthError2("invalid_server_url", `an MCP server URL must be http(s), not "${url.protocol}"`);
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw new McpOAuthError2("invalid_server_url", `the MCP server URL for ${url.origin} carries userinfo -- a credential never rides a server URL`);
+  }
+  return `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}`;
+}
+function mcpOAuthAccountId2(serverUrl) {
+  return createHash("sha256").update(canonicalMcpServerUrl2(serverUrl)).digest("hex").slice(0, 16);
+}
+function mcpOAuthTokenAccount2(serverUrl) {
+  return `${MCP_OAUTH_TOKEN_ACCOUNT_PREFIX2}${mcpOAuthAccountId2(serverUrl)}`;
+}
+function mcpOAuthClientAccount2(serverUrl) {
+  return `${MCP_OAUTH_CLIENT_ACCOUNT_PREFIX2}${mcpOAuthAccountId2(serverUrl)}`;
+}
+var MCP_OAUTH_CLIENT_SECRET_ACCOUNT_PREFIX = "mcp-oauth-client-secret:";
+function mcpOAuthClientSecretAccount2(serverUrl) {
+  return `${MCP_OAUTH_CLIENT_SECRET_ACCOUNT_PREFIX}${mcpOAuthAccountId2(serverUrl)}`;
+}
+var ACCOUNT_SHAPE = /^mcp-oauth:[0-9a-f]{16}$/;
+function isMcpOAuthTokenAccount2(account) {
+  return ACCOUNT_SHAPE.test(account);
+}
+function clientAccountForTokenAccount2(account) {
+  if (!isMcpOAuthTokenAccount2(account)) {
+    throw new McpOAuthError2("invalid_account", `"${account}" is not an MCP sign-in account (expected mcp-oauth:<16 hex>)`);
+  }
+  return `${MCP_OAUTH_CLIENT_ACCOUNT_PREFIX2}${account.slice(MCP_OAUTH_TOKEN_ACCOUNT_PREFIX2.length)}`;
+}
+
+// src/mcp-auth/constants.ts
+var WINTER_MCP_CLIENT_METADATA_URL2 = "https://yanlinglabs.com/winter/oauth-client.json";
+var MCP_OAUTH_CALLBACK_PATH2 = "/callback";
+var MCP_OAUTH_EXPIRY_SKEW_MS2 = 60000;
+var MCP_OAUTH_SESSION_CACHE_MS2 = 30000;
+var MCP_OAUTH_LOGIN_TIMEOUT_MS2 = 5 * 60000;
+var MCP_OAUTH_STATE_BYTES = 32;
+
+// src/mcp-auth/fetch-policy.ts
+import { boundedFetch, classifyAddress, DEFAULT_MAX_REDIRECTS, ProviderBodyLimitError, ProviderRequestError } from "@yanlinglabs/winter-provider-runtime";
+import { isIP } from "node:net";
+var MCP_AUTH_FETCH_TIMEOUT_MS = 30000;
+var MCP_AUTH_FETCH_MAX_BODY_BYTES = 1024 * 1024;
+function stripBrackets(host) {
+  return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+function evaluateMcpAuthUrl2(raw, opts = {}) {
+  let url;
+  try {
+    url = new URL(String(raw));
+  } catch {
+    return { ok: false, reason: "an auth URL is not a parseable absolute URL" };
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:")
+    return { ok: false, reason: `${url.protocol} is not an auth URL scheme (https only)` };
+  if (url.username !== "" || url.password !== "")
+    return { ok: false, reason: `the auth URL for ${url.origin} carries userinfo` };
+  const host = stripBrackets(url.hostname);
+  const family = isIP(host);
+  const cls = family !== 0 ? classifyAddress(host, family) : host.toLowerCase() === "localhost" ? "loopback" : undefined;
+  if (cls !== undefined && cls !== "loopback" && cls !== "public") {
+    return { ok: false, reason: `${url.origin} is a literal ${cls} address, which an auth request never reaches` };
+  }
+  const loopback = cls === "loopback";
+  if (loopback && opts.allowLoopback !== true)
+    return { ok: false, reason: `${url.origin} is a loopback address, which an auth request reaches only for an MCP server that is itself on loopback` };
+  if (url.protocol === "http:" && !loopback)
+    return { ok: false, reason: `${url.origin} uses plain http; auth requests are https-only except to a literal loopback address` };
+  return { ok: true, origin: url.origin, loopback };
+}
+function isLoopbackMcpServer(serverUrl) {
+  const verdict = evaluateMcpAuthUrl2(serverUrl, { allowLoopback: true });
+  return verdict.ok && verdict.loopback;
+}
+function refusal(reason) {
+  return new McpOAuthError2("policy_refused", `auth request refused: ${reason}`);
+}
+function sameOriginOnlyPolicy(origin, loopback, allowLoopback) {
+  return {
+    origin,
+    local: loopback,
+    generated: false,
+    evaluateRedirect(target) {
+      const verdict = evaluateMcpAuthUrl2(target, { allowLoopback });
+      if (!verdict.ok)
+        return { ok: false, reason: verdict.reason };
+      if (verdict.origin !== origin)
+        return { ok: false, reason: `a redirect from ${origin} to ${verdict.origin} (auth requests never follow a cross-origin redirect)` };
+      return { ok: true, origin: verdict.origin, sameOrigin: true };
+    }
+  };
+}
+function headersOf(init) {
+  return new Headers(init?.headers ?? {});
+}
+function capResponse(response, maxBodyBytes) {
+  if (response.body === null)
+    return response;
+  const reader = response.body.getReader();
+  let seen = 0;
+  const body = new ReadableStream({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        controller.close();
+        return;
+      }
+      seen += value.byteLength;
+      if (seen > maxBodyBytes) {
+        reader.cancel().catch(() => {});
+        controller.error(new ProviderBodyLimitError(maxBodyBytes));
+        return;
+      }
+      controller.enqueue(value);
+    },
+    cancel(reason) {
+      reader.cancel(reason).catch(() => {});
+    }
+  });
+  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+function createMcpAuthFetch(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? MCP_AUTH_FETCH_TIMEOUT_MS;
+  const maxBodyBytes = opts.maxBodyBytes ?? MCP_AUTH_FETCH_MAX_BODY_BYTES;
+  const allowLoopback = opts.allowLoopback === true;
+  return async (input, init) => {
+    const target = String(input);
+    const verdict = evaluateMcpAuthUrl2(target, { allowLoopback });
+    if (!verdict.ok)
+      throw refusal(verdict.reason);
+    const { redirect: _redirect, signal, ...rest } = init ?? {};
+    const deadline = new AbortController;
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    timer.unref?.();
+    const combined = signal !== undefined && signal !== null ? AbortSignal.any([deadline.signal, signal]) : deadline.signal;
+    if (opts.fetch !== undefined) {
+      try {
+        const response = await opts.fetch(target, { ...rest, headers: headersOf(init), redirect: "error", signal: combined });
+        return capResponse(response, maxBodyBytes);
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof McpOAuthError2)
+          throw err;
+        throw new McpOAuthError2("network", `the auth request to ${verdict.origin} failed (${err instanceof Error ? err.name : "error"}); redirects are refused on an injected network`);
+      }
+    }
+    try {
+      return await boundedFetch(target, {
+        ...rest,
+        headers: headersOf(init),
+        timeoutMs,
+        maxBodyBytes,
+        maxRedirects: DEFAULT_MAX_REDIRECTS,
+        policy: sameOriginOnlyPolicy(verdict.origin, verdict.loopback, allowLoopback),
+        signal: combined
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof ProviderRequestError && err.code === "capability")
+        throw refusal(err.message);
+      throw new McpOAuthError2("network", `the auth request to ${verdict.origin} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
+}
+
+// src/mcp-auth/records.ts
+var REGISTERED_VIA = new Set(["dcr", "cimd", "preregistered"]);
+function parseObject(raw, what) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new McpOAuthError2("malformed_record", `the ${what} record is not valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new McpOAuthError2("malformed_record", `the ${what} record is not a JSON object`);
+  }
+  return parsed;
+}
+function checkEnvelope(o, kind, what) {
+  if (o.v !== 1) {
+    throw new McpOAuthError2(typeof o.v === "number" ? "unsupported_record_version" : "malformed_record", `the ${what} record has ${typeof o.v === "number" ? `version ${o.v}, which this Winter does not read` : "no version"}`);
+  }
+  if (o.kind !== kind)
+    throw new McpOAuthError2("malformed_record", `the ${what} record is not of kind "${kind}"`);
+}
+function requireString(o, key, what) {
+  const value = o[key];
+  if (typeof value !== "string" || value.length === 0)
+    throw new McpOAuthError2("malformed_record", `the ${what} record has no "${key}"`);
+  return value;
+}
+function optionalString(o, key, what) {
+  const value = o[key];
+  if (value === undefined)
+    return;
+  if (typeof value !== "string")
+    throw new McpOAuthError2("malformed_record", `the ${what} record's "${key}" is not a string`);
+  return value;
+}
+function decodeMcpOAuthTokenRecord2(raw) {
+  const what = "MCP sign-in";
+  const o = parseObject(raw, what);
+  checkEnvelope(o, "mcp-oauth", what);
+  const generation = o.generation;
+  if (typeof generation !== "number" || !Number.isInteger(generation) || generation < 0) {
+    throw new McpOAuthError2("malformed_record", `the ${what} record's "generation" is not a non-negative integer`);
+  }
+  const expiresAt = o.expiresAt;
+  if (expiresAt !== undefined && (typeof expiresAt !== "number" || !Number.isFinite(expiresAt))) {
+    throw new McpOAuthError2("malformed_record", `the ${what} record's "expiresAt" is not a number`);
+  }
+  const refreshToken = optionalString(o, "refreshToken", what);
+  const scope = optionalString(o, "scope", what);
+  return {
+    v: 1,
+    kind: "mcp-oauth",
+    serverUrl: requireString(o, "serverUrl", what),
+    issuer: requireString(o, "issuer", what),
+    accessToken: requireString(o, "accessToken", what),
+    ...refreshToken !== undefined && refreshToken !== "" ? { refreshToken } : {},
+    ...expiresAt !== undefined ? { expiresAt } : {},
+    ...scope !== undefined ? { scope } : {},
+    generation
+  };
+}
+function decodeMcpOAuthClientRecord2(raw) {
+  const what = "MCP client registration";
+  const o = parseObject(raw, what);
+  checkEnvelope(o, "mcp-oauth-client", what);
+  const registeredVia = o.registeredVia;
+  if (typeof registeredVia !== "string" || !REGISTERED_VIA.has(registeredVia)) {
+    throw new McpOAuthError2("malformed_record", `the ${what} record's "registeredVia" is not dcr, cimd or preregistered`);
+  }
+  const clientSecret = optionalString(o, "clientSecret", what);
+  const resourceMetadataUrl = optionalString(o, "resourceMetadataUrl", what);
+  const authorizationServerUrl = optionalString(o, "authorizationServerUrl", what);
+  const stepUpScope = optionalString(o, "stepUpScope", what);
+  return {
+    v: 1,
+    kind: "mcp-oauth-client",
+    serverUrl: requireString(o, "serverUrl", what),
+    issuer: requireString(o, "issuer", what),
+    clientId: requireString(o, "clientId", what),
+    ...clientSecret !== undefined && clientSecret !== "" ? { clientSecret } : {},
+    registeredVia,
+    redirectUri: requireString(o, "redirectUri", what),
+    ...resourceMetadataUrl !== undefined ? { resourceMetadataUrl } : {},
+    ...authorizationServerUrl !== undefined ? { authorizationServerUrl } : {},
+    ...stepUpScope !== undefined && stepUpScope !== "" ? { stepUpScope } : {}
+  };
+}
+function encodeMcpOAuthTokenRecord2(record) {
+  const text = JSON.stringify(record);
+  decodeMcpOAuthTokenRecord2(text);
+  return text;
+}
+function encodeMcpOAuthClientRecord2(record) {
+  const text = JSON.stringify(record);
+  decodeMcpOAuthClientRecord2(text);
+  return text;
+}
+function decodeMcpOAuthClientSecretItem2(raw) {
+  if (raw.startsWith("{")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = undefined;
+    }
+    if (typeof parsed === "object" && parsed !== null && parsed.kind === "mcp-oauth-client-secret") {
+      const o = parsed;
+      if (o.v !== 1)
+        throw new McpOAuthError2(typeof o.v === "number" ? "unsupported_record_version" : "malformed_record", "the MCP client secret record has an unreadable version");
+      if (typeof o.secret !== "string" || o.secret === "")
+        throw new McpOAuthError2("malformed_record", 'the MCP client secret record has no "secret"');
+      if (o.issuer !== undefined && (typeof o.issuer !== "string" || o.issuer === ""))
+        throw new McpOAuthError2("malformed_record", `the MCP client secret record's "issuer" is not a string`);
+      return { secret: o.secret, ...typeof o.issuer === "string" ? { issuer: o.issuer } : {} };
+    }
+  }
+  return { secret: raw };
+}
+function encodeMcpOAuthClientSecretItem2(secret, expectedIssuer) {
+  if (secret === "")
+    throw new McpOAuthError2("malformed_record", "an MCP client secret cannot be empty");
+  return JSON.stringify({ v: 1, kind: "mcp-oauth-client-secret", secret, ...expectedIssuer !== undefined ? { issuer: expectedIssuer } : {} });
+}
+function sameIssuer2(a, b) {
+  return a === b || a === `${b}/` || `${a}/` === b;
+}
+
+// src/mcp-auth/discovery.ts
+import { buildDiscoveryUrls, checkResourceAllowed, discoverAuthorizationServerMetadata, discoverOAuthProtectedResourceMetadata, discoverOAuthServerInfo, resourceUrlFromServerUrl } from "@modelcontextprotocol/client";
+function isMetadataDocumentUrl(url) {
+  try {
+    return new URL(url).pathname.includes("/.well-known/");
+  } catch {
+    return false;
+  }
+}
+function fetchedFromIssuersOwnLocation(fetchUrl, issuer) {
+  let fetched;
+  try {
+    fetched = new URL(fetchUrl);
+    new URL(issuer);
+  } catch {
+    return false;
+  }
+  if (fetched.search !== "" || fetched.hash !== "")
+    return false;
+  return buildDiscoveryUrls(issuer).some((candidate) => candidate.url.href === fetched.href);
+}
+async function fetchAuthorizationServerMetadataDocument(url, fetchFn) {
+  const response = await fetchFn(url, { headers: { accept: "application/json" } });
+  if (!response.ok) {
+    await response.text().catch(() => {});
+    throw new Error(`the authorization server metadata document answered HTTP ${response.status}`);
+  }
+  const doc = await response.json();
+  for (const key of ["issuer", "authorization_endpoint", "token_endpoint"]) {
+    if (typeof doc[key] !== "string")
+      throw new Error(`the authorization server metadata document has no "${key}"`);
+  }
+  if (!Array.isArray(doc.response_types_supported))
+    throw new Error('the authorization server metadata document has no "response_types_supported"');
+  if (!fetchedFromIssuersOwnLocation(url, doc.issuer)) {
+    throw new McpOAuthError2("metadata_issuer_mismatch", `the authorization server metadata document at ${new URL(url).origin} names an issuer it was not published under (RFC 8414 §3.3); it is refused`);
+  }
+  return doc;
+}
+async function loadAuthorizationServer(opts) {
+  const { authorizationServerUrl, expectedIssuer, fetchFn } = opts;
+  const metadata = isMetadataDocumentUrl(authorizationServerUrl) ? await fetchAuthorizationServerMetadataDocument(authorizationServerUrl, fetchFn) : await discoverAuthorizationServerMetadata(authorizationServerUrl, { fetchFn });
+  if (metadata !== undefined && !sameIssuer2(metadata.issuer, expectedIssuer)) {
+    throw new Error("the authorization server now names a different issuer than the one this sign-in came from");
+  }
+  const base = isMetadataDocumentUrl(authorizationServerUrl) && metadata !== undefined ? metadata.issuer : authorizationServerUrl;
+  return { authorizationServerUrl: base, ...metadata !== undefined ? { metadata } : {} };
+}
+async function resolveResourceIndicator(opts) {
+  let resource;
+  try {
+    const prm = await discoverOAuthProtectedResourceMetadata(opts.serverUrl, opts.resourceMetadataUrl !== undefined ? { resourceMetadataUrl: new URL(opts.resourceMetadataUrl) } : undefined, opts.fetchFn);
+    resource = prm.resource;
+  } catch {
+    return;
+  }
+  if (!checkResourceAllowed({ requestedResource: resourceUrlFromServerUrl(opts.serverUrl), configuredResource: resource })) {
+    throw new Error("the protected-resource metadata names a resource that is not this MCP server");
+  }
+  return resource;
+}
+async function discoverMcpOAuthIssuer2(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 oauth = opts.oauth ?? {};
+  const allowLoopback = isLoopbackMcpServer(opts.serverUrl);
+  const fetchFn = createMcpAuthFetch({ ...opts.fetch !== undefined ? { fetch: opts.fetch } : {}, allowLoopback });
+  let issuer;
+  let authorizeEndpoint;
+  try {
+    if (oauth.authServerMetadataUrl !== undefined) {
+      const metadata = await fetchAuthorizationServerMetadataDocument(oauth.authServerMetadataUrl, fetchFn);
+      issuer = metadata.issuer;
+      authorizeEndpoint = metadata.authorization_endpoint;
+    } else {
+      const info = await discoverOAuthServerInfo(opts.serverUrl, { fetchFn });
+      issuer = info.authorizationServerMetadata?.issuer ?? info.authorizationServerUrl;
+      authorizeEndpoint = info.authorizationServerMetadata?.authorization_endpoint ?? new URL("/authorize", info.authorizationServerUrl).toString();
+    }
+  } catch (err) {
+    if (err instanceof McpOAuthError2)
+      throw err;
+    throw new McpOAuthError2("login_failed", `mcp-auth issuer discovery failed: ${boundedReason(err)}`);
+  }
+  const authorizeVerdict = evaluateMcpAuthUrl2(authorizeEndpoint, { allowLoopback });
+  if (!authorizeVerdict.ok)
+    throw new McpOAuthError2("policy_refused", `the authorization endpoint is refused: ${authorizeVerdict.reason}`);
+  return { issuer, issuerOrigin: new URL(issuer).origin, authorizeOrigin: authorizeVerdict.origin };
+}
+
+// src/mcp-auth/store.ts
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { DEFAULT_KEYCHAIN_SERVICE as DEFAULT_KEYCHAIN_SERVICE2, envName, WINTER_BRAND } from "@yanlinglabs/winter-agent-sdk";
+
+// src/provider/keychain-store.ts
+import { CredentialResolutionError, redactRef } from "@yanlinglabs/winter-provider-runtime";
+import { DEFAULT_KEYCHAIN_SERVICE } from "@yanlinglabs/winter-agent-sdk";
+function defaultSecretsBackend() {
+  const secrets = globalThis.Bun?.secrets;
+  if (secrets === undefined) {
+    throw new CredentialResolutionError("unsupported", "the Keychain credential store requires Bun.secrets, which is unavailable in this runtime");
+  }
+  return secrets;
+}
+function createKeychainCredentialStore(service = DEFAULT_KEYCHAIN_SERVICE, opts = {}) {
+  const backend = () => opts.secrets ?? defaultSecretsBackend();
+  return {
+    async get(ref) {
+      if (ref.kind !== "keychain")
+        return null;
+      let raw;
+      try {
+        raw = await backend().get({ service: ref.service ?? service, name: ref.account });
+      } catch (err) {
+        if (err instanceof CredentialResolutionError)
+          throw err;
+        throw new CredentialResolutionError("io", `keychain lookup failed for ${redactRef(ref)}`);
+      }
+      if (raw === null)
+        return null;
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        throw new CredentialResolutionError("malformed", `the keychain record for ${redactRef(ref)} is not valid JSON credential material`);
+      }
+      const material = coerceMaterial(parsed);
+      if (material === undefined)
+        throw new CredentialResolutionError("malformed", `the keychain record for ${redactRef(ref)} is not a recognized credential material shape`);
+      return material;
+    },
+    async set(ref, material) {
+      try {
+        await backend().set({ service: ref.service ?? service, name: ref.account, value: JSON.stringify(material) });
+      } catch (err) {
+        if (err instanceof CredentialResolutionError)
+          throw err;
+        throw new CredentialResolutionError("io", `keychain write failed for ${redactRef(ref)}`);
+      }
+    },
+    async delete(ref) {
+      try {
+        await backend().delete({ service: ref.service ?? service, name: ref.account });
+      } catch (err) {
+        if (err instanceof CredentialResolutionError)
+          throw err;
+        throw new CredentialResolutionError("io", `keychain delete failed for ${redactRef(ref)}`);
+      }
+    }
+  };
+}
+function createKeychainSecretReader(service = DEFAULT_KEYCHAIN_SERVICE, opts = {}) {
+  const backend = () => opts.secrets ?? defaultSecretsBackend();
+  return async (ref) => {
+    try {
+      return await backend().get({ service: ref.service ?? service, name: ref.account });
+    } catch (err) {
+      if (err instanceof CredentialResolutionError)
+        throw err;
+      throw new CredentialResolutionError("io", `keychain lookup failed for ${redactRef(ref)}`);
+    }
+  };
+}
+function createKeychainRawStore(service = DEFAULT_KEYCHAIN_SERVICE, opts = {}) {
+  const backend = () => opts.secrets ?? defaultSecretsBackend();
+  const failure = (what, account) => new CredentialResolutionError("io", `keychain ${what} failed for account ${JSON.stringify(account)}`);
+  return {
+    async read(account) {
+      try {
+        return await backend().get({ service, name: account });
+      } catch (err) {
+        if (err instanceof CredentialResolutionError)
+          throw err;
+        throw failure("lookup", account);
+      }
+    },
+    async write(account, value) {
+      try {
+        await backend().set({ service, name: account, value });
+      } catch (err) {
+        if (err instanceof CredentialResolutionError)
+          throw err;
+        throw failure("write", account);
+      }
+    },
+    async remove(account) {
+      try {
+        await backend().delete({ service, name: account });
+      } catch (err) {
+        if (err instanceof CredentialResolutionError)
+          throw err;
+        throw failure("delete", account);
+      }
+    }
+  };
+}
+function keychainAccountName(providerId, accountId) {
+  return `${providerId}:${accountId}`;
+}
+function parseStoredCredentialMaterial(raw, ref) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CredentialResolutionError("malformed", `the credential record for ${redactRef(ref)} is not valid JSON credential material`);
+  }
+  const material = coerceMaterial(parsed);
+  if (material === undefined)
+    throw new CredentialResolutionError("malformed", `the credential record for ${redactRef(ref)} is not a recognized credential material shape`);
+  return material;
+}
+var MATERIAL_KINDS = new Set(["api-key", "bearer", "oauth", "aws", "gcp-service-account", "gcp-access-token"]);
+function coerceMaterial(value) {
+  if (typeof value !== "object" || value === null)
+    return;
+  const v = value;
+  if (typeof v.kind !== "string" || !MATERIAL_KINDS.has(v.kind))
+    return;
+  switch (v.kind) {
+    case "api-key":
+      return typeof v.key === "string" ? { kind: "api-key", key: v.key } : undefined;
+    case "bearer":
+      return typeof v.token === "string" ? { kind: "bearer", token: v.token, ...typeof v.expiresAt === "number" ? { expiresAt: v.expiresAt } : {} } : undefined;
+    case "oauth":
+      return typeof v.accessToken === "string" ? {
+        kind: "oauth",
+        accessToken: v.accessToken,
+        ...typeof v.refreshToken === "string" ? { refreshToken: v.refreshToken } : {},
+        ...typeof v.expiresAt === "number" ? { expiresAt: v.expiresAt } : {},
+        ...typeof v.accountId === "string" ? { accountId: v.accountId } : {},
+        ...typeof v.idToken === "string" ? { idToken: v.idToken } : {}
+      } : undefined;
+    case "aws":
+      return typeof v.accessKeyId === "string" && typeof v.secretAccessKey === "string" ? { kind: "aws", accessKeyId: v.accessKeyId, secretAccessKey: v.secretAccessKey, ...typeof v.sessionToken === "string" ? { sessionToken: v.sessionToken } : {} } : undefined;
+    case "gcp-service-account":
+      return typeof v.clientEmail === "string" && typeof v.privateKeyPem === "string" && typeof v.tokenUri === "string" ? { kind: "gcp-service-account", clientEmail: v.clientEmail, privateKeyPem: v.privateKeyPem, tokenUri: v.tokenUri } : undefined;
+    case "gcp-access-token":
+      return typeof v.token === "string" ? { kind: "gcp-access-token", token: v.token } : undefined;
+    default:
+      return;
+  }
+}
+
+// src/provider/host-credentials.ts
+import { CREDENTIAL_RESOLVE_SUBTYPE } from "@yanlinglabs/winter-agent-sdk";
+import { CredentialResolutionError as CredentialResolutionError2, redactRef as redactRef2 } from "@yanlinglabs/winter-provider-runtime";
+var HOST_CREDENTIAL_TIMEOUT_MS = 60000;
+var HOST_CREDENTIAL_BIND_TIMEOUT_MS = 30000;
+function createHostCredentialChannel(opts = {}) {
+  let sender;
+  const waiters = [];
+  const bound = () => {
+    if (sender !== undefined)
+      return Promise.resolve(sender);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new CredentialResolutionError2("io", "the host credential channel was never bound to the session's control bridge")), opts.bindTimeoutMs ?? HOST_CREDENTIAL_BIND_TIMEOUT_MS);
+      timer.unref?.();
+      waiters.push((s) => {
+        clearTimeout(timer);
+        resolve(s);
+      });
+    });
+  };
+  return {
+    bind(next) {
+      sender = next;
+      for (const wake of waiters.splice(0))
+        wake(next);
+    },
+    async request(subtype, payload, requestOpts) {
+      return (await bound()).request(subtype, payload, requestOpts);
+    }
+  };
+}
+function isAnswer(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const v = value;
+  if (v.ok === true)
+    return typeof v.material === "string" && typeof v.generation === "number";
+  return v.ok === false && typeof v.reason === "string";
+}
+async function resolveFromHost(sender, ref, minGeneration) {
+  const request = { ref: { kind: "keychain", account: ref.account, ...ref.service !== undefined ? { service: ref.service } : {} }, ...minGeneration !== undefined ? { minGeneration } : {} };
+  let answer;
+  try {
+    answer = await sender.request(CREDENTIAL_RESOLVE_SUBTYPE, request, { timeoutMs: HOST_CREDENTIAL_TIMEOUT_MS });
+  } catch (err) {
+    if (err instanceof CredentialResolutionError2)
+      throw err;
+    throw new CredentialResolutionError2("io", `the host did not resolve ${redactRef2(ref)} (${err instanceof Error ? err.name : "error"})`);
+  }
+  if (!isAnswer(answer))
+    throw new CredentialResolutionError2("io", `the host answered ${redactRef2(ref)} with a malformed credential_resolve answer`);
+  if (!answer.ok) {
+    if (answer.reason === "not_found")
+      return null;
+    throw new CredentialResolutionError2("io", `the host refused ${redactRef2(ref)}: ${answer.reason}`);
+  }
+  return { material: answer.material, generation: answer.generation, ...answer.expiresAt !== undefined ? { expiresAt: answer.expiresAt } : {} };
+}
+function withoutRefreshToken(material) {
+  if (material.kind !== "oauth" || material.refreshToken === undefined)
+    return material;
+  const { refreshToken: _dropped, ...rest } = material;
+  return rest;
+}
+function createHostBrokeredCredentialStore(sender) {
+  const generations = new Map;
+  const key = (ref) => `${ref.service ?? ""}\x00${ref.account}`;
+  const noWrites = (ref) => new CredentialResolutionError2("unsupported", `a host-brokered session never persists credentials (${redactRef2(ref)}); its host renews them`);
+  return {
+    async get(ref) {
+      if (ref.kind !== "keychain")
+        throw new CredentialResolutionError2("unsupported", `the host-brokered credential store does not serve ${ref.kind} refs`);
+      const resolved = await resolveFromHost(sender, ref);
+      if (resolved === null)
+        return null;
+      generations.set(key(ref), resolved.generation);
+      return withoutRefreshToken(parseStoredCredentialMaterial(resolved.material, ref));
+    },
+    async set(ref) {
+      throw noWrites(ref);
+    },
+    async delete(ref) {
+      throw noWrites(ref);
+    },
+    async refresh(ref) {
+      const minGeneration = (generations.get(key(ref)) ?? 0) + 1;
+      const resolved = await resolveFromHost(sender, ref, minGeneration);
+      if (resolved === null)
+        throw new CredentialResolutionError2("io", `the host holds no credential for ${redactRef2(ref)} any more; sign in again`);
+      generations.set(key(ref), resolved.generation);
+      return withoutRefreshToken(parseStoredCredentialMaterial(resolved.material, ref));
+    }
+  };
+}
+function createHostBrokeredSecretReader(sender) {
+  return async (ref) => (await resolveFromHost(sender, ref))?.material ?? null;
+}
+
+// src/mcp-auth/store.ts
+function createMemoryMcpOAuthStore2(initial = {}) {
+  const entries = new Map(Object.entries(initial));
+  return {
+    entries,
+    async read(account) {
+      return entries.get(account) ?? null;
+    },
+    async write(account, value) {
+      entries.set(account, value);
+    },
+    async remove(account) {
+      entries.delete(account);
+    }
+  };
+}
+function createKeychainMcpOAuthStore2(service) {
+  return service === undefined ? createKeychainRawStore() : createKeychainRawStore(service);
+}
+async function readTokenRecord(store, account) {
+  const raw = await store.read(account);
+  return raw === null ? null : decodeMcpOAuthTokenRecord2(raw);
+}
+async function readClientRecord(store, account) {
+  const raw = await store.read(account);
+  return raw === null ? null : decodeMcpOAuthClientRecord2(raw);
+}
+async function writeTokenRecord(store, account, record) {
+  await store.write(account, encodeMcpOAuthTokenRecord2(record));
+}
+async function writeClientRecord(store, account, record) {
+  await store.write(account, encodeMcpOAuthClientRecord2(record));
+}
+async function readTokenRecordLenient(store, account) {
+  try {
+    return await readTokenRecord(store, account);
+  } catch (err) {
+    if (err instanceof McpOAuthError2 && err.code === "malformed_record")
+      return null;
+    throw err;
+  }
+}
+function createTestFileMcpOAuthStore(path) {
+  const load = () => {
+    try {
+      return JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      return {};
+    }
+  };
+  const save = (entries) => {
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(entries), { mode: 384 });
+    renameSync(tmp, path);
+  };
+  return {
+    testFile: path,
+    async read(account) {
+      return load()[account] ?? null;
+    },
+    async write(account, value) {
+      save({ ...load(), [account]: value });
+    },
+    async remove(account) {
+      const entries = load();
+      delete entries[account];
+      save(entries);
+    }
+  };
+}
+function mcpOAuthTestStoreEnvName(brand) {
+  return envName(brand, "TEST_MCP_OAUTH_STORE_FILE");
+}
+var MCP_OAUTH_TEST_STORE_ENV = mcpOAuthTestStoreEnvName(WINTER_BRAND);
+function resolveSessionMcpOAuthStore(opts) {
+  const { keychainService, testStoreFile } = opts;
+  if (testStoreFile !== undefined && testStoreFile !== "" && keychainService !== undefined && keychainService !== DEFAULT_KEYCHAIN_SERVICE2 && keychainService !== `${DEFAULT_KEYCHAIN_SERVICE2}.dev`) {
+    return createTestFileMcpOAuthStore(testStoreFile);
+  }
+  return createKeychainMcpOAuthStore2(keychainService);
+}
+var MCP_OAUTH_HOST_HELD_REFRESH_TOKEN2 = "host-held";
+function toSessionMcpTokenRecord2(raw) {
+  const record = decodeMcpOAuthTokenRecord2(raw);
+  return encodeMcpOAuthTokenRecord2(record.refreshToken === undefined ? record : { ...record, refreshToken: MCP_OAUTH_HOST_HELD_REFRESH_TOKEN2 });
+}
+function createHostBrokeredMcpOAuthStore(sender) {
+  const refuse = (account) => new McpOAuthError2("invalid_account", `a host-brokered session never writes its MCP sign-ins (${account}); its host does`);
+  return {
+    async read(account) {
+      const material = (await resolveFromHost(sender, { kind: "keychain", account }))?.material;
+      if (material === undefined)
+        return null;
+      try {
+        return toSessionMcpTokenRecord2(material);
+      } catch {
+        return material;
+      }
+    },
+    async write(account) {
+      throw refuse(account);
+    },
+    async remove(account) {
+      throw refuse(account);
+    }
+  };
+}
+
+// src/mcp-auth/refresh.ts
+import { computeScopeUnion, InsecureTokenEndpointError, OAuthError as OAuthError2, OAuthErrorCode, refreshAuthorization } from "@modelcontextprotocol/client";
+var inflight = new WeakMap;
+var SIGN_IN_AGAIN = new Set([OAuthErrorCode.InvalidGrant, OAuthErrorCode.InvalidClient, OAuthErrorCode.UnauthorizedClient, OAuthErrorCode.InvalidScope, OAuthErrorCode.UnsupportedGrantType]);
+function log(account, what) {
+  console.error(`winter: mcp-auth: refresh for ${account}: ${what}`);
+}
+async function refreshMcpOAuthToken2(opts) {
+  const clientAccount = clientAccountForTokenAccount2(opts.account);
+  let perStore = inflight.get(opts.store);
+  if (perStore === undefined) {
+    perStore = new Map;
+    inflight.set(opts.store, perStore);
+  }
+  const running = perStore.get(opts.account);
+  if (running !== undefined)
+    return running;
+  const run = refreshOnce(opts, clientAccount).finally(() => {
+    perStore.delete(opts.account);
+  });
+  perStore.set(opts.account, run);
+  return run;
+}
+async function refreshOnce(opts, clientAccount) {
+  const { account, store } = opts;
+  const now = opts.now ?? Date.now;
+  let record;
+  try {
+    record = await readTokenRecordLenient(store, account);
+  } catch (err) {
+    log(account, err instanceof McpOAuthError2 ? err.code : "unreadable");
+    return { ok: false, reason: "transient" };
+  }
+  if (record === null)
+    return { ok: false, reason: "needs_auth" };
+  if (opts.generation !== undefined && record.generation !== opts.generation)
+    return { ok: true, generation: record.generation };
+  if (opts.stepUpScope !== undefined && opts.stepUpScope.trim() !== "") {
+    await recordStepUp(store, clientAccount, opts.stepUpScope);
+    return { ok: false, reason: "needs_auth" };
+  }
+  if (record.refreshToken === undefined)
+    return { ok: false, reason: "needs_auth" };
+  if (record.refreshToken === MCP_OAUTH_HOST_HELD_REFRESH_TOKEN2) {
+    log(account, "the record holds the host-held marker, not a refresh token (a session's view, not the host's store)");
+    return { ok: false, reason: "needs_auth" };
+  }
+  let client;
+  try {
+    client = await readClientRecord(store, clientAccount);
+  } catch {
+    client = null;
+  }
+  if (client === null || client.issuer !== record.issuer) {
+    log(account, "no client registration for this sign-in's issuer");
+    return { ok: false, reason: "needs_auth" };
+  }
+  const fetchFn = createMcpAuthFetch({ ...opts.fetch !== undefined ? { fetch: opts.fetch } : {}, allowLoopback: isLoopbackMcpServer(record.serverUrl) });
+  try {
+    const server = await loadAuthorizationServer({ authorizationServerUrl: client.authorizationServerUrl ?? record.issuer, expectedIssuer: record.issuer, fetchFn });
+    const resource = await resolveResourceIndicator({ serverUrl: record.serverUrl, ...client.resourceMetadataUrl !== undefined ? { resourceMetadataUrl: client.resourceMetadataUrl } : {}, fetchFn });
+    const fresh = await readTokenRecordLenient(store, account);
+    if (fresh === null)
+      return { ok: false, reason: "needs_auth" };
+    if (fresh.generation !== record.generation)
+      return { ok: true, generation: fresh.generation };
+    const tokens = await refreshAuthorization(server.authorizationServerUrl, {
+      ...server.metadata !== undefined ? { metadata: server.metadata } : {},
+      clientInformation: { client_id: client.clientId, ...client.clientSecret !== undefined ? { client_secret: client.clientSecret } : {} },
+      refreshToken: record.refreshToken,
+      ...resource !== undefined ? { resource } : {},
+      fetchFn
+    });
+    const generation = record.generation + 1;
+    const refreshToken = tokens.refresh_token ?? record.refreshToken;
+    const scope = tokens.scope ?? record.scope;
+    await writeTokenRecord(store, account, {
+      v: 1,
+      kind: "mcp-oauth",
+      serverUrl: record.serverUrl,
+      issuer: record.issuer,
+      accessToken: tokens.access_token,
+      ...refreshToken !== undefined ? { refreshToken } : {},
+      ...typeof tokens.expires_in === "number" ? { expiresAt: now() + tokens.expires_in * 1000 } : {},
+      ...scope !== undefined ? { scope } : {},
+      generation
+    });
+    return { ok: true, generation };
+  } catch (err) {
+    if (err instanceof OAuthError2) {
+      if (err.code === OAuthErrorCode.InvalidGrant) {
+        log(account, `${err.code}; the sign-in is cleared`);
+        await store.remove(account).catch(() => {});
+        return { ok: false, reason: "needs_auth" };
+      }
+      if (err.code === OAuthErrorCode.InvalidClient || err.code === OAuthErrorCode.UnauthorizedClient) {
+        log(account, `${err.code}; the client registration is cleared`);
+        await store.remove(clientAccount).catch(() => {});
+        return { ok: false, reason: "needs_auth" };
+      }
+      log(account, err.code);
+      return { ok: false, reason: SIGN_IN_AGAIN.has(err.code) ? "needs_auth" : "transient" };
+    }
+    if (err instanceof InsecureTokenEndpointError || err instanceof McpOAuthError2 && err.code === "policy_refused") {
+      log(account, "the token endpoint is refused by the auth-HTTP policy");
+      return { ok: false, reason: "needs_auth" };
+    }
+    log(account, err instanceof McpOAuthError2 ? err.code : "transient failure");
+    return { ok: false, reason: "transient" };
+  }
+}
+async function recordStepUp(store, clientAccount, scope) {
+  let client;
+  try {
+    client = await readClientRecord(store, clientAccount);
+  } catch {
+    return;
+  }
+  if (client === null)
+    return;
+  const stepUpScope = computeScopeUnion(client.stepUpScope, scope);
+  if (stepUpScope === undefined || stepUpScope === client.stepUpScope)
+    return;
+  await writeClientRecord(store, clientAccount, { ...client, stepUpScope });
+}
+
+export { 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, createKeychainCredentialStore, createKeychainSecretReader, keychainAccountName, createHostCredentialChannel, createHostBrokeredCredentialStore, createHostBrokeredSecretReader, createMemoryMcpOAuthStore2, createKeychainMcpOAuthStore2, readClientRecord, writeTokenRecord, writeClientRecord, readTokenRecordLenient, mcpOAuthTestStoreEnvName, resolveSessionMcpOAuthStore, MCP_OAUTH_HOST_HELD_REFRESH_TOKEN2, toSessionMcpTokenRecord2, createHostBrokeredMcpOAuthStore, refreshMcpOAuthToken2 };