@code-yeongyu/senpi 2026.11.10-1 → 2026.11.10-2

package/dist/core/extensions/builtin/mcp/auth/oauth-grant.d.ts

@@ -0,0 +1,43 @@
+import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { McpAuthorizationProof, McpClientRegistration, McpStoredAuth } from "./token-store.ts";
+export type McpGrantRecord = Pick<McpStoredAuth, "accessToken" | "refreshToken" | "issuer" | "resource" | "scope" | "refreshScope"> & {
+    readonly authorization?: unknown;
+    readonly clientInfo?: Pick<McpClientRegistration, "client_id" | "client_secret" | "token_endpoint_auth_method" | "issuer">;
+    readonly discoveryState?: {
+        readonly authorizationServerUrl?: string | URL;
+    };
+};
+export interface McpGrantContext {
+    readonly serverName: string;
+    readonly serverUrl: string;
+    readonly agentDir: string;
+    readonly clientId?: string;
+    readonly clientMetadataUrl?: string;
+}
+export declare function storedGrantIssuer(record: McpGrantRecord | undefined): string | undefined;
+export declare function freezeGrantAttribution(record: McpStoredAuth | undefined): McpStoredAuth;
+export declare function storedAuthToTokens(record: McpStoredAuth | undefined, now?: number): OAuthTokens | undefined;
+/** Maps one response; the caller decides which preceding fields it is entitled to inherit. */
+export declare function mergeTokensIntoStoredAuth(current: McpStoredAuth, tokens: OAuthTokens): McpStoredAuth;
+export interface McpTokenResponse {
+    readonly tokens: OAuthTokens;
+    readonly resource: string;
+    readonly fresh: boolean;
+    readonly presented?: McpStoredAuth;
+    readonly clientInfo?: McpClientRegistration;
+}
+/** An SDK response has no locked predecessor; only explicit fresh acquisition can establish its initial proof. */
+export declare function mergeOAuthTokenResponse(current: McpStoredAuth, context: McpGrantContext, response: McpTokenResponse): McpStoredAuth;
+/** Active binding excludes pending registrations and display/redirect metadata. */
+export declare function grantBinding(record: McpGrantRecord, context: McpGrantContext): {
+    issuer: string | undefined;
+    resource: string | undefined;
+    clientIdentity: string | undefined;
+    scope: string | undefined;
+    refreshScope: string | undefined;
+};
+export declare function validGrantProof(record: McpGrantRecord, context: McpGrantContext): McpAuthorizationProof | undefined;
+/** Only the refresh transaction passes a predecessor, read while holding its existing token-store lock. */
+export declare function withGrantAuthorization(record: McpStoredAuth, context: McpGrantContext, previous?: McpStoredAuth): McpStoredAuth;
+export declare function oauthGrantIdentity(record: McpGrantRecord, context: McpGrantContext): string;
+//# sourceMappingURL=oauth-grant.d.ts.map

package/dist/core/extensions/builtin/mcp/auth/oauth-grant.js

@@ -0,0 +1,196 @@
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+import { isEphemeralIdentity, keyedIdentity } from "../config-identity-key.js";
+import { canonicalAuthorizationServerIssuer } from "./oauth-issuer.js";
+const authorizationSchema = Type.Object({
+    version: Type.Literal(1),
+    id: Type.String({ pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }),
+    proof: Type.Optional(Type.Object({
+        credentialIdentity: Type.String({ pattern: "^[0-9a-f]{64}$" }),
+        previousCredentialIdentity: Type.Optional(Type.String({ pattern: "^[0-9a-f]{64}$" })),
+        issuer: Type.String({ minLength: 1 }),
+        resource: Type.String({ minLength: 1 }),
+        clientIdentity: Type.String({ pattern: "^[0-9a-f]{64}$" }),
+        scope: Type.String({ minLength: 1 }),
+        refreshScope: Type.Optional(Type.String({ minLength: 1 })),
+    })),
+});
+const epochSchema = Type.Object({
+    version: Type.Literal(1),
+    id: authorizationSchema.properties.id,
+});
+function authorizationEpoch(record) {
+    const authorization = record.authorization;
+    return Check(epochSchema, authorization) ? authorization.id : undefined;
+}
+function normalizeGrantedScope(scope) {
+    if (scope === undefined || !/^[\x21\x23-\x5b\x5d-\x7e]+(?: +[\x21\x23-\x5b\x5d-\x7e]+)*$/.test(scope))
+        return undefined;
+    return [...new Set(scope.split(" "))].filter(Boolean).sort().join(" ");
+}
+export function storedGrantIssuer(record) {
+    return record?.issuer ?? record?.discoveryState?.authorizationServerUrl?.toString();
+}
+export function freezeGrantAttribution(record) {
+    const next = { ...(record ?? {}) };
+    if (next.issuer !== undefined || (next.accessToken === undefined && next.refreshToken === undefined))
+        return next;
+    const issuer = storedGrantIssuer(next);
+    if (issuer !== undefined)
+        next.issuer = issuer;
+    else
+        delete next.refreshToken;
+    return next;
+}
+export function storedAuthToTokens(record, now = Date.now()) {
+    if (record?.accessToken === undefined || record.accessToken.length === 0)
+        return undefined;
+    const expiresIn = record.expiresAt === undefined ? undefined : Math.max(0, Math.ceil((record.expiresAt - now) / 1000));
+    const issuer = storedGrantIssuer(record);
+    return {
+        access_token: record.accessToken,
+        refresh_token: issuer === undefined ? undefined : record.refreshToken,
+        token_type: "Bearer",
+        scope: normalizeGrantedScope(record.scope),
+        ...(expiresIn === undefined ? {} : { expires_in: expiresIn }),
+        ...(issuer === undefined ? {} : { issuer }),
+    };
+}
+/** Maps one response; the caller decides which preceding fields it is entitled to inherit. */
+export function mergeTokensIntoStoredAuth(current, tokens) {
+    return {
+        ...current,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token ?? current.refreshToken,
+        scope: normalizeGrantedScope(tokens.scope),
+        expiresAt: tokens.expires_in === undefined ? undefined : Date.now() + tokens.expires_in * 1000,
+        issuer: tokens.issuer ?? current.issuer,
+    };
+}
+/** An SDK response has no locked predecessor; only explicit fresh acquisition can establish its initial proof. */
+export function mergeOAuthTokenResponse(current, context, response) {
+    const { tokens, resource, fresh, presented, clientInfo } = response;
+    // Attribute a response to the client selected before the request, never to a later store writer.
+    const active = {
+        ...current,
+        clientInfo,
+        pendingClientInfo: current.pendingClientInfo?.client_id === clientInfo?.client_id ? undefined : current.pendingClientInfo,
+    };
+    const binding = grantBinding({ ...active, issuer: tokens.issuer, resource }, context);
+    const canInherit = !fresh &&
+        presented !== undefined &&
+        JSON.stringify(grantBinding(presented, context)) === JSON.stringify(grantBinding(current, context)) &&
+        JSON.stringify(grantBinding(presented, context)) === JSON.stringify(binding) &&
+        presented.accessToken === current.accessToken &&
+        presented.refreshToken === current.refreshToken &&
+        presented.authorization?.id === current.authorization?.id;
+    const base = {
+        ...active,
+        issuer: tokens.issuer,
+        resource,
+        refreshToken: canInherit ? presented.refreshToken : undefined,
+        scope: undefined,
+        refreshScope: undefined,
+        authorization: undefined,
+    };
+    const next = mergeTokensIntoStoredAuth(base, tokens);
+    return fresh
+        ? withGrantAuthorization({ ...next, refreshScope: next.scope }, context)
+        : { ...next, authorization: { version: 1, id: randomUUID() } };
+}
+/** Active binding excludes pending registrations and display/redirect metadata. */
+export function grantBinding(record, context) {
+    const issuer = storedGrantIssuer(record);
+    const registration = record.clientInfo;
+    const clientId = context.clientId ?? context.clientMetadataUrl ?? registration?.client_id;
+    const configured = context.clientId !== undefined || context.clientMetadataUrl !== undefined;
+    const clientIssuer = configured ? issuer : (registration?.issuer ?? issuer);
+    const clientIdentity = clientId === undefined
+        ? undefined
+        : keyedIdentity(context.agentDir, JSON.stringify([
+            "mcp-oauth-client-v1",
+            clientId,
+            configured ? null : (registration?.client_secret ?? null),
+            configured ? null : (registration?.token_endpoint_auth_method ?? null),
+            clientIssuer === undefined ? null : canonicalAuthorizationServerIssuer(clientIssuer),
+        ]));
+    return {
+        issuer: issuer === undefined ? undefined : canonicalAuthorizationServerIssuer(issuer),
+        resource: record.resource,
+        clientIdentity,
+        scope: normalizeGrantedScope(record.scope),
+        refreshScope: normalizeGrantedScope(record.refreshScope),
+    };
+}
+function credentialCommitment(record, context, id) {
+    const binding = grantBinding(record, context);
+    return keyedIdentity(context.agentDir, JSON.stringify([
+        "mcp-oauth-credential-v1",
+        context.serverName,
+        context.serverUrl,
+        id ?? null,
+        record.accessToken ?? null,
+        record.refreshToken ?? null,
+        binding.issuer ?? null,
+        binding.resource ?? null,
+        binding.clientIdentity ?? null,
+        binding.scope ?? null,
+        binding.refreshScope ?? null,
+    ]));
+}
+export function validGrantProof(record, context) {
+    const authorization = record.authorization;
+    if (!Check(authorizationSchema, authorization) || authorization.proof === undefined)
+        return undefined;
+    const proof = authorization.proof;
+    const binding = grantBinding(record, context);
+    if (Object.entries(binding).some(([key, value]) => Reflect.get(proof, key) !== value))
+        return undefined;
+    return proof.credentialIdentity === credentialCommitment(record, context, authorization.id) ? proof : undefined;
+}
+/** Only the refresh transaction passes a predecessor, read while holding its existing token-store lock. */
+export function withGrantAuthorization(record, context, previous) {
+    const predecessor = previous === undefined ? undefined : validGrantProof(previous, context);
+    const binding = grantBinding(record, context);
+    const sameBinding = predecessor !== undefined &&
+        Object.entries(binding).every(([key, value]) => Reflect.get(predecessor, key) === value);
+    const id = sameBinding && previous?.authorization !== undefined ? previous.authorization.id : randomUUID();
+    const credentialIdentity = credentialCommitment(record, context, id);
+    const proof = binding.issuer !== undefined &&
+        binding.resource !== undefined &&
+        binding.clientIdentity !== undefined &&
+        binding.scope !== undefined &&
+        !isEphemeralIdentity(credentialIdentity)
+        ? {
+            ...binding,
+            issuer: binding.issuer,
+            resource: binding.resource,
+            clientIdentity: binding.clientIdentity,
+            scope: binding.scope,
+            credentialIdentity,
+            previousCredentialIdentity: previous === undefined
+                ? undefined
+                : credentialCommitment(previous, context, authorizationEpoch(previous)),
+        }
+        : undefined;
+    return { ...record, authorization: { version: 1, id, proof } };
+}
+export function oauthGrantIdentity(record, context) {
+    const epoch = authorizationEpoch(record);
+    const proof = validGrantProof(record, context);
+    return proof === undefined
+        ? keyedIdentity(context.agentDir, JSON.stringify(["mcp-oauth-opaque-v1", credentialCommitment(record, context, epoch)]))
+        : keyedIdentity(context.agentDir, JSON.stringify([
+            "mcp-oauth-authorization-v1",
+            context.serverName,
+            context.serverUrl,
+            epoch,
+            proof.issuer,
+            proof.resource,
+            proof.clientIdentity,
+            proof.scope,
+            proof.refreshScope ?? null,
+        ]));
+}
+//# sourceMappingURL=oauth-grant.js.map

package/dist/core/extensions/builtin/mcp/auth/oauth-provider.d.ts

@@ -1,8 +1,8 @@
 import type { OAuthClientProvider, OAuthDiscoveryState } from "@modelcontextprotocol/sdk/client/auth.js";
 import type { OAuthClientInformationFull, OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
 import type { McpLogger } from "../log.ts";
-import type { McpStoredAuth, McpTokenStore } from "./token-store.ts";
-export declare const REFRESH_LEEWAY_MS: number;
+import { type McpGrantContext } from "./oauth-grant.ts";
+import type { McpTokenStore } from "./token-store.ts";
 export interface McpOAuthProviderOptions {
     serverName: string;
     serverUrl: string;
@@ -16,21 +16,6 @@ export interface McpOAuthProviderOptions {
     logger?: McpLogger;
     onRedirect?: (url: URL) => void | Promise<void>;
 }
-export declare function tokenExpiresAt(tokens: OAuthTokens, now?: number): number | undefined;
-/**
- * The authorization server a stored grant belongs to (senpi#2940, GHSA-6qxp-vccf-f47h): its `issuer` stamp, or
- * for a record saved before the stamp existed, the authorization server its sign-in discovered. A record with
- * neither cannot be attributed, so its refresh token is never presented anywhere.
- */
-export declare function storedGrantIssuer(record: McpStoredAuth | undefined): string | undefined;
-/**
- * Fixes who an unstamped grant belongs to before the discovery record it falls back to is replaced (senpi#2940).
- * A later discovery reflects what the MCP server advertises now, not where the grant was issued, so it must never
- * attribute an existing grant: the grant keeps the server it was attributed to, or loses its refresh token.
- */
-export declare function freezeGrantAttribution(record: McpStoredAuth | undefined): McpStoredAuth;
-export declare function storedAuthToTokens(record: McpStoredAuth | undefined, now?: number): OAuthTokens | undefined;
-export declare function mergeTokensIntoStoredAuth(current: McpStoredAuth | undefined, tokens: OAuthTokens, serverUrl: string, issuer?: string): McpStoredAuth;
 export declare class McpOAuthProvider implements OAuthClientProvider {
     #private;
     constructor(options: McpOAuthProviderOptions);
@@ -47,6 +32,7 @@ export declare class McpOAuthProvider implements OAuthClientProvider {
     saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
     discoveryState(): OAuthDiscoveryState | undefined;
     tokens(): OAuthTokens | undefined;
+    withFreshAuthorization<T>(exchange: () => Promise<T>): Promise<T>;
     saveTokens(tokens: OAuthTokens): Promise<void>;
     saveCodeVerifier(codeVerifier: string): Promise<void>;
     codeVerifier(): string;
@@ -57,5 +43,6 @@ export declare class McpOAuthProvider implements OAuthClientProvider {
     get serverUrl(): string;
     get store(): McpTokenStore;
     get scopes(): string[] | undefined;
+    get grantContext(): McpGrantContext;
 }
 //# sourceMappingURL=oauth-provider.d.ts.map

package/dist/core/extensions/builtin/mcp/auth/oauth-provider.js

@@ -2,72 +2,9 @@ import { randomBytes } from "node:crypto";
 import { oauthBrandName } from "@earendil-works/pi-ai/utils/oauth-page";
 import { fingerprintSecret } from "../log.js";
 import { OAuthFlowError } from "./oauth-errors.js";
+import { freezeGrantAttribution, grantBinding, mergeOAuthTokenResponse, storedAuthToTokens, storedGrantIssuer, } from "./oauth-grant.js";
 import { canonicalAuthorizationServerIssuer, credentialsMatchIssuer, discoveryNamesItsServer, validatedAuthorizationServerIssuer, } from "./oauth-issuer.js";
 import { grantForFlow, registrationForFlow, withPromotedRegistration, withRegistration, } from "./registered-redirect.js";
-// Buffer before absolute token expiry at which a refresh is considered due.
-export const REFRESH_LEEWAY_MS = 5 * 60 * 1000;
-export function tokenExpiresAt(tokens, now = Date.now()) {
-    if (tokens.expires_in === undefined)
-        return undefined;
-    return now + tokens.expires_in * 1000;
-}
-/**
- * The authorization server a stored grant belongs to (senpi#2940, GHSA-6qxp-vccf-f47h): its `issuer` stamp, or
- * for a record saved before the stamp existed, the authorization server its sign-in discovered. A record with
- * neither cannot be attributed, so its refresh token is never presented anywhere.
- */
-export function storedGrantIssuer(record) {
-    return record?.issuer ?? record?.discoveryState?.authorizationServerUrl?.toString();
-}
-/**
- * Fixes who an unstamped grant belongs to before the discovery record it falls back to is replaced (senpi#2940).
- * A later discovery reflects what the MCP server advertises now, not where the grant was issued, so it must never
- * attribute an existing grant: the grant keeps the server it was attributed to, or loses its refresh token.
- */
-export function freezeGrantAttribution(record) {
-    const next = { ...(record ?? {}) };
-    if (next.issuer !== undefined || (next.accessToken === undefined && next.refreshToken === undefined))
-        return next;
-    const issuer = storedGrantIssuer(next);
-    if (issuer !== undefined)
-        next.issuer = issuer;
-    else
-        delete next.refreshToken;
-    return next;
-}
-export function storedAuthToTokens(record, now = Date.now()) {
-    if (record?.accessToken === undefined || record.accessToken.length === 0)
-        return undefined;
-    const expiresIn = record.expiresAt === undefined ? undefined : Math.max(0, Math.ceil((record.expiresAt - now) / 1000));
-    const issuer = storedGrantIssuer(record);
-    return {
-        access_token: record.accessToken,
-        // An unattributed refresh token is withheld: the SDK would post it to whichever server it discovers.
-        refresh_token: issuer === undefined ? undefined : record.refreshToken,
-        token_type: "Bearer",
-        ...(expiresIn === undefined ? {} : { expires_in: expiresIn }),
-        ...(issuer === undefined ? {} : { issuer }),
-    };
-}
-export function mergeTokensIntoStoredAuth(current, tokens, serverUrl, issuer) {
-    const next = {
-        ...(current ?? {}),
-        accessToken: tokens.access_token,
-        resource: current?.resource ?? serverUrl,
-    };
-    const refreshToken = tokens.refresh_token ?? current?.refreshToken;
-    if (refreshToken !== undefined)
-        next.refreshToken = refreshToken;
-    const expiresAt = tokenExpiresAt(tokens);
-    if (expiresAt !== undefined)
-        next.expiresAt = expiresAt;
-    else
-        delete next.expiresAt;
-    const stamp = tokens.issuer ?? issuer;
-    if (stamp !== undefined)
-        next.issuer = stamp;
-    return next;
-}
 // Implements the SDK OAuthClientProvider backed by the URL-bound token store.
 // All persistence goes through the store so tokens survive process restarts and
 // stay lockable across processes.
@@ -75,6 +12,10 @@ export class McpOAuthProvider {
     #options;
     #expectedState;
     #lastAuthorizationUrl;
+    #freshAuthorization = false;
+    #resource;
+    #presentedGrant;
+    #selectedClient;
     constructor(options) {
         this.#options = options;
     }
@@ -121,14 +62,23 @@ export class McpOAuthProvider {
             return { client_id: this.#options.clientId };
         if (this.#options.clientMetadataUrl !== undefined)
             return { client_id: this.#options.clientMetadataUrl };
-        return registrationForFlow(this.#store.read(), this.#options);
+        this.#selectedClient = registrationForFlow(this.#store.read(), this.#options);
+        return this.#selectedClient;
     }
     async saveClientInformation(info) {
         const discovery = this.discoveryState();
         const issuer = discovery === undefined
             ? info.issuer && canonicalAuthorizationServerIssuer(info.issuer)
             : validatedAuthorizationServerIssuer(discovery, this.serverName);
-        await this.#store.update((current) => withRegistration(current, { ...info, issuer }, this.#options));
+        const saved = await this.#store.update((current) => {
+            const next = withRegistration(current, { ...info, issuer }, this.#options);
+            return current !== undefined &&
+                JSON.stringify(grantBinding(current, this.grantContext)) !==
+                    JSON.stringify(grantBinding(next, this.grantContext))
+                ? { ...next, scope: undefined, refreshScope: undefined, authorization: undefined }
+                : next;
+        });
+        this.#selectedClient = registrationForFlow(saved, this.#options);
     }
     async saveDiscoveryState(state) {
         const issuer = validatedAuthorizationServerIssuer(state, this.serverName);
@@ -171,16 +121,37 @@ export class McpOAuthProvider {
         return state;
     }
     tokens() {
-        return storedAuthToTokens(grantForFlow(this.#store.read(), this.#options));
+        const grant = grantForFlow(this.#store.read(), this.#options);
+        this.#presentedGrant = withPromotedRegistration(grant, this.#options);
+        return storedAuthToTokens(grant);
+    }
+    async withFreshAuthorization(exchange) {
+        const previous = this.#freshAuthorization;
+        this.#freshAuthorization = true;
+        try {
+            return await exchange();
+        }
+        finally {
+            this.#freshAuthorization = previous;
+        }
     }
     async saveTokens(tokens) {
         const discovery = this.discoveryState();
-        const issuer = discovery === undefined
-            ? tokens.issuer && canonicalAuthorizationServerIssuer(tokens.issuer)
-            : validatedAuthorizationServerIssuer(discovery, this.serverName);
+        // SDK results carry the exchange's issuer. Never restamp a late response from a newer file snapshot.
+        const issuer = tokens.issuer !== undefined
+            ? canonicalAuthorizationServerIssuer(tokens.issuer)
+            : this.#freshAuthorization && discovery !== undefined
+                ? validatedAuthorizationServerIssuer(discovery, this.serverName)
+                : storedGrantIssuer(this.#presentedGrant);
         // A flow's staged registration replaces the signed-in client in the same write as its tokens (senpi#6327).
-        const stamped = { ...tokens, issuer };
-        await this.#store.update((current) => mergeTokensIntoStoredAuth(withPromotedRegistration(current, this.#options), stamped, this.serverUrl));
+        const response = {
+            tokens: { ...tokens, issuer },
+            resource: this.#resource ?? new URL(this.serverUrl).href,
+            fresh: this.#freshAuthorization,
+            presented: this.#presentedGrant,
+            clientInfo: this.#selectedClient ?? this.#presentedGrant?.clientInfo,
+        };
+        this.#presentedGrant = await this.#store.update((current) => mergeOAuthTokenResponse(current ?? {}, this.grantContext, response));
         this.#logFingerprint("saveTokens", tokens.access_token);
     }
     async saveCodeVerifier(codeVerifier) {
@@ -201,7 +172,9 @@ export class McpOAuthProvider {
     }
     // RFC 8707: bind the token to this MCP resource.
     validateResourceURL(serverUrl, resource) {
-        return Promise.resolve(new URL(resource ?? String(serverUrl)));
+        const selected = new URL(resource ?? String(serverUrl));
+        this.#resource = selected.href;
+        return Promise.resolve(selected);
     }
     async invalidateCredentials(scope) {
         if (scope === "all") {
@@ -217,10 +190,17 @@ export class McpOAuthProvider {
                 delete next.refreshToken;
                 delete next.expiresAt;
             }
+            if (scope === "tokens" || scope === "client") {
+                return {
+                    ...next,
+                    scope: undefined,
+                    refreshScope: undefined,
+                    authorization: undefined,
+                    ...(scope === "client" ? { clientInfo: undefined } : {}),
+                };
+            }
             if (scope === "verifier")
                 next.codeVerifier = undefined;
-            if (scope === "client")
-                next.clientInfo = undefined;
             if (scope === "discovery")
                 next.discoveryState = undefined;
             return next;
@@ -238,6 +218,15 @@ export class McpOAuthProvider {
     get scopes() {
         return this.#options.scopes;
     }
+    get grantContext() {
+        return {
+            serverName: this.serverName,
+            serverUrl: this.serverUrl,
+            agentDir: this.store.agentDir,
+            clientId: this.#options.clientId,
+            clientMetadataUrl: this.#options.clientMetadataUrl,
+        };
+    }
     get #store() {
         return this.#options.store;
     }

package/dist/core/extensions/builtin/mcp/auth/oauth-refresh.d.ts

@@ -1,7 +1,7 @@
 import type { OAuthServerInfo } from "@modelcontextprotocol/sdk/client/auth.js";
 import type { AuthorizationServerMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
 import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { type McpOAuthProvider } from "./oauth-provider.ts";
+import type { McpOAuthProvider } from "./oauth-provider.ts";
 import type { McpStoredAuth } from "./token-store.ts";
 export interface RefreshManagerOptions {
     fetchFn?: FetchLike;

package/dist/core/extensions/builtin/mcp/auth/oauth-refresh.js

@@ -2,8 +2,9 @@ import { loadMcpSdkAuth } from "../sdk.lazy.js";
 import { safeDelay } from "../wrap.js";
 import { isInvalidGrant, isTransientTokenError, OAuthFlowError } from "./oauth-errors.js";
 import { oauthFetch } from "./oauth-fetch.js";
-import { credentialsMatchIssuer, validatedAuthorizationServerIssuer } from "./oauth-issuer.js";
-import { mergeTokensIntoStoredAuth, REFRESH_LEEWAY_MS, storedAuthToTokens, storedGrantIssuer, } from "./oauth-provider.js";
+import { canonicalAuthorizationServerIssuer, credentialsMatchIssuer, validatedAuthorizationServerIssuer, } from "./oauth-issuer.js";
+import { mergeTokensIntoStoredAuth, storedAuthToTokens, storedGrantIssuer, validGrantProof, withGrantAuthorization, } from "./oauth-grant.js";
+const REFRESH_LEEWAY_MS = 5 * 60 * 1000;
 export function isTokenStale(record, now) {
     const token = record?.accessToken;
     if (token === undefined || token.length === 0)
@@ -82,6 +83,7 @@ export class McpRefreshManager {
             });
         }
         const resource = new URL(current.resource ?? this.#provider.serverUrl);
+        const proof = validGrantProof(current, this.#provider.grantContext);
         const { refreshAuthorization } = await loadMcpSdkAuth();
         const maxRetries = this.#options.maxRetries ?? 2;
         for (let attempt = 0;; attempt++) {
@@ -93,10 +95,29 @@ export class McpRefreshManager {
                     resource,
                     fetchFn: oauthFetch(this.#options.fetchFn),
                 });
-                this.#provider.store.writeUnlocked(mergeTokensIntoStoredAuth(current, tokens, this.#provider.serverUrl, authorizationServer));
-                return { ...tokens, issuer: authorizationServer };
+                if (tokens.issuer !== undefined &&
+                    canonicalAuthorizationServerIssuer(tokens.issuer) !==
+                        canonicalAuthorizationServerIssuer(authorizationServer)) {
+                    this.#provider.store.writeUnlocked(undefined);
+                    throw new OAuthFlowError("needs_auth", "MCP refresh response names a different issuer.", {
+                        serverName: this.#provider.serverName,
+                    });
+                }
+                const next = mergeTokensIntoStoredAuth({ ...current, issuer: authorizationServer, resource: resource.href, refreshScope: proof?.refreshScope }, {
+                    ...tokens,
+                    issuer: authorizationServer,
+                    scope: tokens.scope === undefined ? proof?.refreshScope : tokens.scope,
+                });
+                const committed = withGrantAuthorization(next, this.#provider.grantContext, current);
+                this.#provider.store.writeUnlocked(committed);
+                const result = storedAuthToTokens(committed);
+                if (result === undefined)
+                    throw new OAuthFlowError("needs_auth", "MCP refresh returned no access token.");
+                return result;
             }
             catch (error) {
+                if (error instanceof OAuthFlowError)
+                    throw error;
                 if (isInvalidGrant(error)) {
                     // Terminal: drop credentials so the next use forces a clean re-auth.
                     this.#provider.store.writeUnlocked(undefined);

package/dist/core/extensions/builtin/mcp/auth/oauth.js

@@ -34,11 +34,11 @@ export async function finishAuthorization(provider, code, options = {}, iss) {
     let result;
     const { auth } = await loadMcpSdkAuth();
     try {
-        result = await auth(provider, {
+        result = await provider.withFreshAuthorization(() => auth(provider, {
             serverUrl: provider.serverUrl,
             authorizationCode: code,
             fetchFn: oauthFetch(options.fetchFn),
-        });
+        }));
     }
     catch (error) {
         if (isInvalidGrant(error) || isRejectedAuthorizationCode(error)) {
@@ -111,12 +111,15 @@ export async function clientCredentialsGrant(provider, options = {}) {
         },
     };
     const { fetchToken } = await loadMcpSdkAuth();
-    const tokens = await fetchToken(credentialsProvider, info.authorizationServerUrl, {
-        metadata: info.authorizationServerMetadata,
-        resource: new URL(provider.serverUrl),
-        fetchFn: oauthFetch(options.fetchFn),
+    await provider.validateResourceURL(provider.serverUrl, provider.serverUrl);
+    await provider.withFreshAuthorization(async () => {
+        const tokens = await fetchToken(credentialsProvider, info.authorizationServerUrl, {
+            metadata: info.authorizationServerMetadata,
+            resource: new URL(provider.serverUrl),
+            fetchFn: oauthFetch(options.fetchFn),
+        });
+        await provider.saveTokens({ ...tokens, issuer: validatedAuthorizationServerIssuer(info, provider.serverName) });
     });
-    await provider.saveTokens({ ...tokens, issuer: validatedAuthorizationServerIssuer(info, provider.serverName) });
 }
 export async function logout(provider) {
     await provider.store.clear();

package/dist/core/extensions/builtin/mcp/auth/token-store.d.ts

@@ -3,7 +3,24 @@ import type { OAuthClientInformationFull } from "@modelcontextprotocol/sdk/share
 export type McpClientRegistration = OAuthClientInformationFull & {
     redirectUrisSent?: string[];
 };
+export interface McpAuthorizationProof {
+    readonly credentialIdentity: string;
+    readonly previousCredentialIdentity?: string;
+    readonly issuer: string;
+    readonly resource: string;
+    readonly clientIdentity: string;
+    readonly scope: string;
+    readonly refreshScope?: string;
+}
+export interface McpAuthorization {
+    readonly version: 1;
+    readonly id: string;
+    readonly proof?: McpAuthorizationProof;
+}
 export interface McpStoredAuth {
+    readonly scope?: string;
+    readonly refreshScope?: string;
+    readonly authorization?: McpAuthorization;
     accessToken?: string;
     refreshToken?: string;
     clientInfo?: McpClientRegistration;
@@ -37,6 +54,7 @@ export declare class McpTokenStore<TRecord extends McpStoredAuth = McpStoredAuth
     readonly serverUrl: string;
     constructor(options: TokenStoreOptions);
     get rootDir(): string;
+    get agentDir(): string;
     get dir(): string;
     get tokensPath(): string;
     get lockPath(): string;

package/dist/core/extensions/builtin/mcp/auth/token-store.js

@@ -40,6 +40,9 @@ export class McpTokenStore {
     get rootDir() {
         return join(this.#agentDir, AUTH_ROOT);
     }
+    get agentDir() {
+        return this.#agentDir;
+    }
     get dir() {
         return join(this.rootDir, this.#hash);
     }

package/dist/core/extensions/builtin/mcp/catalog-cache.js

@@ -39,24 +39,25 @@ export function cachedCatalogNeedsRefresh(cached, now = Date.now()) {
     return now - cached.fetchedAt > CACHE_TTL_MS;
 }
 export async function collectServerCatalogForCache(connection, config, configHash, credentialIdentity) {
-    const tools = await collectAllPages((cursor) => listMcpTools(connection.client, cursor === undefined ? {} : { cursor }, {
+    const client = connection.client;
+    const tools = await collectAllPages((cursor) => listMcpTools(client, cursor === undefined ? {} : { cursor }, {
         timeout: config.requestTimeoutMs,
     }));
-    const resources = await collectOptionalPages((cursor) => connection.client.listResources(cursor === undefined ? {} : { cursor }, {
+    const resources = await collectOptionalPages((cursor) => client.listResources(cursor === undefined ? {} : { cursor }, {
         timeout: config.requestTimeoutMs,
     }));
-    const prompts = await collectOptionalPages((cursor) => connection.client.listPrompts(cursor === undefined ? {} : { cursor }, {
+    const prompts = await collectOptionalPages((cursor) => client.listPrompts(cursor === undefined ? {} : { cursor }, {
         timeout: config.requestTimeoutMs,
     }));
-    const resourceTemplates = await collectOptionalPages((cursor) => connection.client.listResourceTemplates(cursor === undefined ? {} : { cursor }, {
+    const resourceTemplates = await collectOptionalPages((cursor) => client.listResourceTemplates(cursor === undefined ? {} : { cursor }, {
         timeout: config.requestTimeoutMs,
     }));
     return {
         configHash,
-        ...(isModernMcpClient(connection.client) ? { modern: true } : {}),
+        ...(isModernMcpClient(client) ? { modern: true } : {}),
         credentialIdentity,
         fetchedAt: Date.now(),
-        instructions: connection.client.getInstructions(),
+        instructions: client.getInstructions(),
         prompts,
         resources,
         resourceTemplates,