@zackbart/connecta 0.28.1 → 0.30.0

package/dist/auth/static-oauth.js

@@ -1,9 +1,12 @@
 import { auth, OAuthError, UnauthorizedError } from "@modelcontextprotocol/client";
-import { redirectSafeFetch } from "../connectors/remote-mcp.js";
+import { byteReadResponse } from "../byte-read-response.js";
+import { sentSecretsFor, sentSecretsFetch, shortSecretWarning } from "../sent-secrets.js";
 import { ConnectorCallError, msg } from "../errors.js";
-import { oauthPartitionFor, retainOAuthPartition, retainingOAuthPartition, } from "../oauth-partition.js";
+import { oauthPartitionFor, retainOAuthPartition, retainingOAuthPartition } from "../oauth-partition.js";
 import { oauthSealerFor } from "../oauth-sealing.js";
-import { assertOAuthScope, authorizingContext, KvOAuthProvider, LEGACY_GENERATION, refreshCoordinatorsByPartition, } from "./downstream-oauth.js";
+import { describeFailure } from "../operator-record.js";
+import { assertOAuthScope, authorizingContext, KvOAuthProvider, refreshCoordinatorsByPartition, } from "./downstream-oauth.js";
+import { trackRemoteClientRequest } from "./downstream-client-metadata.js";
 import { trackOAuthStartReset } from "./oauth-start-reset.js";
 /**
  * Downstream OAuth for a hand-written `api()` connector: the authorization
@@ -11,8 +14,8 @@ import { trackOAuthStartReset } from "./oauth-start-reset.js";
  * declares, rather than ones a server advertises.
  *
  * Everything that makes the `remoteMcp()` grant safe is reused, not copied.
- * `StaticOAuthProvider` is a `KvOAuthProvider` — the same epochs, sealing,
- * owner partitions, generation fence, reset lineage, and refresh-failure
+ * `StaticOAuthProvider` is a `KvOAuthProvider` — the same grant record and
+ * consents, sealing, owner partitions, epoch fence, and refresh-failure
  * verdicts — whose discovery state and client are constants, and the SDK's
  * own `auth()` drives it through the same `OAuthRefreshCoordinator`. What a
  * static configuration subtracts is the network learning: no RFC 9728 or 8414
@@ -40,15 +43,9 @@ const RESERVED_TOKEN_HEADERS = new Set([
 ]);
 /** An RFC 9110 field-name token. */
 const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-const CLIENT_AUTHENTICATION = new Set([
-    "client_secret_basic",
-    "client_secret_post",
-    "none",
-]);
+const CLIENT_AUTHENTICATION = new Set(["client_secret_basic", "client_secret_post", "none"]);
 function isLoopback(hostname) {
-    return (hostname === "localhost" ||
-        hostname === "127.0.0.1" ||
-        hostname === "[::1]");
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
 }
 /** An absolute HTTPS URL (or HTTP on loopback), without credentials or fragment. */
 function configuredUrl(id, option, value) {
@@ -82,13 +79,11 @@ function settingsFor(id, config) {
     if (typeof config.clientId !== "string" || config.clientId.trim() === "") {
         throw new Error(`[connecta] connector "${id}" oauth.clientId must be a non-empty string.`);
     }
-    if (config.clientSecret !== undefined &&
-        (typeof config.clientSecret !== "string" || config.clientSecret === "")) {
+    if (config.clientSecret !== undefined && (typeof config.clientSecret !== "string" || config.clientSecret === "")) {
         // Usually an unset environment variable read as "". Never echo it.
         throw new Error(`[connecta] connector "${id}" oauth.clientSecret must be a non-empty string when set.`);
     }
-    const clientAuthentication = config.tokenEndpointAuthMethod ??
-        (config.clientSecret !== undefined ? "client_secret_basic" : "none");
+    const clientAuthentication = config.tokenEndpointAuthMethod ?? (config.clientSecret !== undefined ? "client_secret_basic" : "none");
     if (!CLIENT_AUTHENTICATION.has(clientAuthentication)) {
         throw new Error(`[connecta] connector "${id}" oauth.tokenEndpointAuthMethod must be ` +
             '"client_secret_basic", "client_secret_post", or "none".');
@@ -98,8 +93,7 @@ function settingsFor(id, config) {
             'tokenEndpointAuthMethod "none"; a public client sends no secret.');
     }
     if (clientAuthentication !== "none" && config.clientSecret === undefined) {
-        throw new Error(`[connecta] connector "${id}" oauth.tokenEndpointAuthMethod ` +
-            `"${clientAuthentication}" needs a clientSecret.`);
+        throw new Error(`[connecta] connector "${id}" oauth.tokenEndpointAuthMethod ` + `"${clientAuthentication}" needs a clientSecret.`);
     }
     assertOAuthScope(id, config.scope);
     const authorizationParams = [];
@@ -119,8 +113,7 @@ function settingsFor(id, config) {
             throw new Error(`[connecta] connector "${id}" oauth.tokenRequestHeaders has an invalid header name.`);
         }
         if (RESERVED_TOKEN_HEADERS.has(name.toLowerCase())) {
-            throw new Error(`[connecta] connector "${id}" oauth.tokenRequestHeaders may not set ` +
-                `"${name}"; the token request owns it.`);
+            throw new Error(`[connecta] connector "${id}" oauth.tokenRequestHeaders may not set ` + `"${name}"; the token request owns it.`);
         }
         if (typeof value !== "string" || value.includes("\r") || value.includes("\n") || value.includes("\0")) {
             throw new Error(`[connecta] connector "${id}" oauth.tokenRequestHeaders.${name} must be a single-line string.`);
@@ -170,7 +163,7 @@ class StaticOAuthProvider extends KvOAuthProvider {
         super(connectorId, ctx.storage, `${ctx.baseUrl}/oauth/callback/${connectorId}`, coordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx), ctx.signal, 
         // No client binding: the client is configuration, so there is no
         // registration for a restart to carry forward or discard.
-        undefined, (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), undefined, settings.scope);
+        undefined, (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), undefined, settings.scope, undefined, { secrets: sentSecretsFor(ctx) });
         this.settings = settings;
     }
     /**
@@ -182,14 +175,19 @@ class StaticOAuthProvider extends KvOAuthProvider {
         const { settings } = this;
         return {
             client_id: settings.clientId,
-            ...(settings.clientSecret !== undefined
-                ? { client_secret: settings.clientSecret }
-                : {}),
+            ...(settings.clientSecret !== undefined ? { client_secret: settings.clientSecret } : {}),
             redirect_uris: [this.redirectUrl],
             token_endpoint_auth_method: settings.clientAuthentication,
             issuer: settings.identity,
         };
     }
+    configuredAuthorizationBinding() {
+        return {
+            issuer: this.settings.identity,
+            clientId: this.settings.clientId,
+            tokenEndpoint: this.settings.tokenEndpoint.href,
+        };
+    }
     async saveClientInformation() {
         // Nothing to save: the SDK only saves a client it registered or stamped.
     }
@@ -262,36 +260,45 @@ export function staticOAuth(id, config) {
     const callbackProviders = new WeakMap();
     const rejectedScopes = new WeakSet();
     const scopeOf = (ctx) => ctx.requestScope ?? ctx;
-    const providerFor = (ctx) => new StaticOAuthProvider(id, ctx, coordinatorFor(ctx), settings);
+    const warnShortSecret = shortSecretWarning();
+    const providerFor = (ctx) => {
+        warnShortSecret(settings.clientSecret, ctx.logger);
+        return new StaticOAuthProvider(id, ctx, coordinatorFor(ctx), settings);
+    };
     /**
      * The global `fetch`, read per request, with the configured token-request
      * headers laid over the SDK's own. With discovery and registration answered
      * from configuration the token endpoint is the only URL the SDK fetches here;
      * the check keeps the headers on it even if that ever changes.
      */
-    const tokenEndpointFetch = (input, init = {}) => {
+    const tokenEndpointFetch = async (ctx, input, init = {}) => {
         const url = new URL(input);
-        if (settings.tokenRequestHeaders.length === 0 ||
-            `${url.origin}${url.pathname}` !== settings.identity) {
-            return fetch(input, init);
+        if (settings.tokenRequestHeaders.length === 0 || `${url.origin}${url.pathname}` !== settings.identity) {
+            trackRemoteClientRequest(sentSecretsFor(ctx), input, init);
+            return byteReadResponse(await sentSecretsFetch(ctx)(input, { ...init, redirect: "manual" }));
         }
         const headers = new Headers(init.headers);
         for (const [name, value] of settings.tokenRequestHeaders)
             headers.set(name, value);
-        return fetch(input, { ...init, headers });
+        for (const [, value] of settings.tokenRequestHeaders)
+            sentSecretsFor(ctx).header(value);
+        trackRemoteClientRequest(sentSecretsFor(ctx), input, { ...init, headers });
+        return byteReadResponse(await sentSecretsFetch(ctx)(input, { ...init, headers, redirect: "manual" }));
     };
     /**
      * The SDK's `auth()` over this provider. The token endpoint is fetched
-     * through the refresh coordinator — rotation, coalescing, and dead-versus-
-     * outage verdicts — above a fetch that refuses every redirect, as the
-     * `remoteMcp()` default does.
+     * through the refresh coordinator, with permanent spent fingerprints,
+     * rotation commits, and re-consent verdicts. Credential-bearing requests
+     * never follow redirects in either OAuth adapter.
      */
     const runAuth = (provider, ctx, exchange) => auth(provider, {
         serverUrl: settings.serverUrl,
         ...exchange,
-        fetchFn: coordinatorFor(ctx).coordinatedFetch(provider, redirectSafeFetch(id, "none", tokenEndpointFetch), ctx.signal),
+        fetchFn: coordinatorFor(ctx).coordinatedFetch(provider, (input, init) => tokenEndpointFetch(ctx, input, init), ctx.signal, ctx.defer),
     });
-    const authRequiredError = (cause) => new ConnectorCallError("auth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`, cause !== undefined ? { cause } : undefined);
+    // No cause, as in remoteMcp(): the `UnauthorizedError` class is the whole
+    // verdict, and a logger rendering the chain renders whatever it says.
+    const authRequiredError = () => new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`);
     const disconnectedMessage = `Connector "${id}" was disconnected by an operator — explicitly start authorization to reconnect it.`;
     /**
      * One request through the owner's grant. A 401 earns exactly one recovery:
@@ -314,20 +321,23 @@ export function staticOAuth(id, config) {
             throw new ConnectorCallError("connector_call_failed", `Connector "${id}": a request through ctx.oauth.fetch may not set ` +
                 "Authorization; the connector's grant owns it.", { retryable: false });
         }
-        const signal = init.signal && ctx.signal
-            ? AbortSignal.any([init.signal, ctx.signal])
-            : (init.signal ?? ctx.signal);
-        const send = (accessToken) => {
+        const signal = init.signal && ctx.signal ? AbortSignal.any([init.signal, ctx.signal]) : (init.signal ?? ctx.signal);
+        const send = async (accessToken) => {
+            sentSecretsFor(ctx).add(accessToken);
             const sent = new Headers(headers);
             sent.set("Authorization", `Bearer ${accessToken}`);
             // The token rides to a declared origin and no further: a redirect is
             // handed back to the handler unfollowed rather than re-sent anywhere.
-            return fetch(url, {
+            // The handler reads the answer with `.json()` or `.text()`, which read
+            // bytes here: workerd quotes a text read's non-text Content-Type in
+            // its own log, out of the handler's reach.
+            const response = await sentSecretsFetch(ctx)(url, {
                 ...init,
                 headers: sent,
                 redirect: "manual",
                 ...(signal ? { signal } : {}),
             });
+            return byteReadResponse(response);
         };
         if (rejectedScopes.has(scopeOf(ctx)))
             throw authRequiredError();
@@ -336,13 +346,12 @@ export function staticOAuth(id, config) {
             if (signal?.aborted)
                 throw signal.reason;
             const provider = providerFor(ctx);
-            const generation = await provider.generation();
-            if (provider.isOperatorDisconnectedGeneration(generation)) {
-                throw new ConnectorCallError("auth_required", disconnectedMessage);
+            // Bind this call's reads and writes to the live epoch: a reset landing
+            // meanwhile fails the call rather than handing it another flow's grant.
+            const epoch = await provider.beginFlow();
+            if (provider.isOperatorDisconnectedEpoch(epoch)) {
+                throw new ConnectorCallError("downstream_oauth_required", disconnectedMessage);
             }
-            // A refresh this call triggers writes into the epoch it started under,
-            // so a reset landing meanwhile leaves its rotation unreadable.
-            provider.captureGeneration(generation);
             const tokens = await provider.tokens(issuerContext);
             if (!tokens)
                 throw authRequiredError();
@@ -373,14 +382,7 @@ export function staticOAuth(id, config) {
         catch (error) {
             if (error instanceof UnauthorizedError) {
                 rejectedScopes.add(scopeOf(ctx));
-                throw authRequiredError(error);
-            }
-            // The coordinator's answer while another request is still committing
-            // a rotation it redeemed. The SDK rethrows it untouched; it is a
-            // moment, not a verdict on the grant.
-            if (error instanceof OAuthError && error.code === "temporarily_unavailable") {
-                throw new ConnectorCallError("unavailable", `Connector "${id}" could not refresh its OAuth grant while another ` +
-                    "request was saving one. The grant is kept; retry.", { cause: error });
+                throw authRequiredError();
             }
             throw error;
         }
@@ -396,13 +398,14 @@ export function staticOAuth(id, config) {
             };
         }
         // A status read never starts authorization: this provider cannot, and
-        // nothing here calls the SDK. A stored grant is healthy until a call
-        // says otherwise — the downstream is asked nothing.
+        // nothing here calls the SDK. A stored grant for the configured token
+        // endpoint is healthy until a call says otherwise — the downstream is
+        // asked nothing.
         const provider = providerFor(ctx);
         if (await provider.operatorDisconnected()) {
             return { state: "auth_required", message: disconnectedMessage };
         }
-        return (await provider.tokens())
+        return (await provider.tokens(issuerContext))
             ? { state: "ok" }
             : { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
     };
@@ -434,23 +437,16 @@ export function staticOAuth(id, config) {
         if (ctx.signal?.aborted)
             throw ctx.signal.reason;
         try {
-            let generation = await provider.generation();
-            // Born modern. The legacy generation exists so a `remoteMcp()` grant
-            // from before epochs survives an upgrade; this connector has no such
-            // past, and a flow started there writes an untimed pending URL that a
-            // second Connect could not hand back.
-            if (generation === LEGACY_GENERATION)
-                generation = await provider.bumpGeneration();
-            provider.captureGeneration(generation);
-            // An issuer-bound read: a grant from a since-repointed token endpoint
-            // is fenced here, before it could be reported healthy.
+            // A grant from a since-repointed token endpoint reads as absent here,
+            // and the consent this start begins replaces it.
+            await provider.beginFlow();
             if (await provider.tokens(issuerContext)) {
                 return { state: "ok", message: "Already authorized — connection is healthy." };
             }
             if ((await runAuth(provider, ctx)) === "AUTHORIZED") {
                 return { state: "ok", message: "Already authorized — connection is healthy." };
             }
-            const authorizationUrl = await provider.pendingAuthorizationUrl();
+            const authorizationUrl = await provider.consentUrl();
             return {
                 state: "auth_required",
                 ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
@@ -461,7 +457,13 @@ export function staticOAuth(id, config) {
             if (error instanceof UnauthorizedError) {
                 return { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
             }
-            return { state: "error", message: msg(error) };
+            // Reaches the agent through authorize_connector. Text already in
+            // connecta's words passes (token responses are rebuilt before the SDK
+            // reads them); anything else is told from its record.
+            return {
+                state: "error",
+                message: error instanceof ConnectorCallError || error instanceof OAuthError ? msg(error) : describeFailure(id, error),
+            };
         }
     };
     const disconnectAuth = async (ctx) => {
@@ -480,7 +482,14 @@ export function staticOAuth(id, config) {
         callbackProviders.delete(scopeOf(ctx));
         const authorizationCode = callbackParams?.get("code") ?? code;
         const iss = callbackParams?.get("iss") ?? undefined;
+        // Every exchange names and claims its own consent, including without PKCE.
+        const consent = callbackParams?.get("state") ?? null;
+        if (!consent || !(await provider.verifyCallbackState(consent))) {
+            throw new ConnectorCallError("connector_call_failed", `Connector "${id}" authorization callback matches no pending consent; nothing was exchanged.`);
+        }
+        provider.validateCallbackIssuer(callbackParams?.get("iss") ?? null);
         provider.exchanging(authorizationCode);
+        await provider.bindFlow();
         const result = await runAuth(provider, ctx, {
             authorizationCode,
             ...(iss !== undefined ? { iss } : {}),
@@ -488,7 +497,6 @@ export function staticOAuth(id, config) {
         if (result !== "AUTHORIZED") {
             throw new UnauthorizedError("Failed to authorize");
         }
-        await provider.clearPending();
         rejectedScopes.delete(scopeOf(ctx));
     };
     return {
@@ -496,6 +504,20 @@ export function staticOAuth(id, config) {
         startAuth: retainingOAuthPartition(startAuth, 0),
         disconnectAuth: retainingOAuthPartition(disconnectAuth, 0),
         verifyState: retainingOAuthPartition(verifyState, 1),
+        verifyCallbackIssuer: retainingOAuthPartition(async (issuer, ctx) => {
+            const provider = callbackProviders.get(scopeOf(ctx));
+            if (!provider)
+                return false;
+            provider.validateCallbackIssuer(issuer);
+            return true;
+        }, 1),
+        consumeAuthError: retainingOAuthPartition(async (ctx) => {
+            const provider = callbackProviders.get(scopeOf(ctx));
+            callbackProviders.delete(scopeOf(ctx));
+            if (!provider)
+                throw new ConnectorCallError("connector_call_failed", "OAuth error callback matches no pending consent.");
+            await provider.consumeAuthError();
+        }, 0),
         finishAuth: retainingOAuthPartition(finishAuth, 1),
         access: (ctx) => ({
             fetch: (input, init) => authorizedFetch(ctx, input, init),

package/dist/auth-elicitation.js

@@ -0,0 +1,288 @@
+import { enableAuthorizationHandoffs } from "./authorization-handoff.js";
+import { createRequestStateCodec, inputRequired, ProtocolError, INVALID_PARAMS, PROTOCOL_VERSION_META_KEY, CLIENT_CAPABILITIES_META_KEY, } from "@modelcontextprotocol/server";
+import { Effect } from "effect";
+import { runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { closeScope } from "./runtime/connector-scope.js";
+import { storedCredentialShape } from "./credential-rules.js";
+import { authRecoveryFacts, bindReplayReads, classificationDigest } from "./invocation-auth.js";
+import { CatalogService } from "./catalog-service.js";
+import { DownstreamElicitation, MAX_RELAY_STATE_CHARS, } from "./downstream-input.js";
+import { canonicalState as canonical, requestDigest as digest, stateObject as object, invalidRequestState as invalidState, REQUEST_STATE_TTL_MS as TTL_MS, MAX_INPUT_ROUNDS as MAX_ROUNDS, } from "./request-state.js";
+const INPUT_KEY = "connecta_auth";
+const MESSAGE = "Connect this service in your browser, then retry the request.";
+function failure(code, message) {
+    const structuredContent = { ok: false, error: { code, message, retryable: false } };
+    return { content: [{ type: "text", text: JSON.stringify(structuredContent) }], structuredContent, isError: true };
+}
+/** Request-local auth recovery at the MCP boundary, never inside a guest provider. */
+export class AuthElicitation {
+    options;
+    codec;
+    downstream;
+    stateCodec() {
+        const key = this.options.vault?.requestStateKey;
+        if (!key)
+            return invalidState();
+        return (this.codec ??= key.call(this.options.vault).then((bytes) => createRequestStateCodec({
+            key: bytes,
+            ttlSeconds: TTL_MS / 1000,
+            bind: () => canonical({ principal: this.options.principal, endpoint: this.options.endpoint }),
+        })));
+    }
+    constructor(options) {
+        this.options = options;
+        this.downstream = new DownstreamElicitation({
+            ...options,
+            mint: async (state, context) => (await this.stateCodec()).mint(state, context),
+        });
+    }
+    /** The SDK runs this before any tool handler, including non-auth tools. */
+    async verify(wire, context) {
+        const { vault, endpoint, principal, registry, canManage } = this.options;
+        if (!vault?.requestStateKey || wire.length > MAX_RELAY_STATE_CHARS)
+            return invalidState();
+        const state = await (await this.stateCodec()).verify(wire, context);
+        if (object(state) && state.version === 2 && state.kind === "downstream")
+            return this.downstream.verify(state, context);
+        if (wire.length > 8192)
+            return invalidState();
+        if (!object(state) ||
+            state.version !== 1 ||
+            !principal ||
+            state.principal !== principal ||
+            state.endpoint !== endpoint ||
+            typeof state.connector !== "string" ||
+            !registry.getConnector(state.connector) ||
+            !canManage(state.connector) ||
+            !Number.isSafeInteger(state.expiresAt) ||
+            state.expiresAt <= Date.now() ||
+            state.expiresAt > Date.now() + TTL_MS ||
+            !Number.isInteger(state.round) ||
+            state.round < 1 ||
+            state.round > MAX_ROUNDS ||
+            !["call_tool", "call_destructive_tool", "execute_code", "authorize_connector"].includes(String(state.tool)) ||
+            typeof state.digest !== "string" ||
+            !/^[a-f0-9]{64}$/.test(state.digest) ||
+            !Array.isArray(state.browserNonces) ||
+            state.browserNonces.length !== state.round ||
+            !state.browserNonces.every((nonce) => typeof nonce === "string" && /^[a-f0-9-]{36}$/.test(nonce)) ||
+            !Array.isArray(state.reads) ||
+            !state.reads.every((read) => object(read) &&
+                typeof read.address === "string" &&
+                typeof read.digest === "string" &&
+                /^[a-f0-9]{64}$/.test(read.digest)) ||
+            (state.address !== undefined && typeof state.address !== "string"))
+            return invalidState();
+        if (context.mcpReq.method !== "tools/call" || context.http?.req?.headers.get("Mcp-Name") !== state.tool)
+            return invalidState();
+        return state;
+    }
+    async browserProgress(state) {
+        let started;
+        let claimed;
+        let completed = false;
+        let pending = false;
+        for (const nonce of state.browserNonces) {
+            const progress = await this.options.linkProgress(state.connector, nonce);
+            if (progress === "started")
+                started = nonce;
+            if (progress === "claimed")
+                claimed = nonce;
+            completed ||= progress === "started";
+            pending ||= progress === "claimed";
+        }
+        const predecessor = started ?? claimed;
+        return { ...(predecessor ? { predecessor } : {}), completed: completed && !pending };
+    }
+    async connected(id, context) {
+        const { registry, publicUrl, vault, principal, defer } = this.options;
+        const connector = registry.getConnector(id);
+        const scope = {};
+        const signal = AbortSignal.any([context.mcpReq.signal, this.options.requestSignal]);
+        try {
+            return await runEdge(withDeadlineEffect((deadline) => Effect.gen(function* () {
+                const ctx = registry.contextFor(id, publicUrl, scope, { signal: deadline });
+                yield* Effect.addFinalizer(() => closeScope(connector, ctx, defer));
+                if (connector.credential) {
+                    const metadata = yield* Effect.promise(() => vault.metadata(id, connector.authScope === "personal" ? principal : undefined));
+                    if (storedCredentialShape(connector.credential, metadata?.fields ?? null).state !== "valid")
+                        return false;
+                }
+                if (!connector.status)
+                    return Boolean(connector.credential);
+                return ((yield* Effect.promise(() => registry.statusFor(id, publicUrl, scope, { signal: deadline }))).state ===
+                    "ok");
+            }).pipe(Effect.scoped), { signal, timeoutMs: 5000, timeoutError: new Error("Auth status check timed out") }));
+        }
+        catch {
+            return false;
+        }
+    }
+    async run(tool, args, context, operation) {
+        this.downstream.bind(context);
+        const prior = context.mcpReq.requestState();
+        if (prior?.version === 2)
+            return this.downstream.resume(prior, tool, args, context, operation);
+        const previous = prior;
+        const requestDigest = previous ? await digest(tool, args) : undefined;
+        if (previous && (previous.tool !== tool || previous.digest !== requestDigest || previous.address !== args.address))
+            return failure("invalid_request_state", "Invalid or expired requestState");
+        const response = context.mcpReq.inputResponses?.[INPUT_KEY];
+        if (previous && object(response) && !["accept", "decline", "cancel"].includes(String(response.action))) {
+            throw new ProtocolError(INVALID_PARAMS, "Invalid auth elicitation response", {
+                reason: "invalid_input_response",
+            });
+        }
+        if (previous && !(await this.options.claimRetry(previous.connector, previous.browserNonces.at(-1)))) {
+            return failure("invalid_request_state", "Invalid or expired requestState");
+        }
+        if (previous && object(response)) {
+            if (response.action === "decline")
+                return failure("auth_declined", "Connection was declined. The request was not retried.");
+            if (response.action === "cancel")
+                return failure("auth_cancelled", "Connection was cancelled. The request was not retried.");
+        }
+        if (previous?.reads.length) {
+            const catalog = new CatalogService(this.options.registry, this.options.publicUrl, {
+                requestScope: this.options.requestScope,
+                requestSignal: AbortSignal.any([context.mcpReq.signal, this.options.requestSignal]),
+            });
+            // Recheck every entered read before restarting any part of a program.
+            // A trusted pool cannot authorize replay of a newly classified write.
+            for (const read of previous.reads) {
+                const current = await catalog.resolveTool(read.address, { signal: context.mcpReq.signal });
+                if (!current.ok ||
+                    current.resolved.classificationFresh !== true ||
+                    current.resolved.definition.classification !== "read" ||
+                    (await classificationDigest(current.resolved.definition)) !== read.digest) {
+                    const structuredContent = {
+                        ok: false,
+                        error: {
+                            code: "auth_replay_refused",
+                            retryable: false,
+                            reconciliationRequired: true,
+                            message: "An entered read no longer has the same fresh classification. Reconcile its target before starting a new request.",
+                            authorizationUrl: (await this.options.connectLink(previous.connector)).url,
+                        },
+                    };
+                    return {
+                        isError: true,
+                        structuredContent,
+                        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+                    };
+                }
+            }
+            bindReplayReads(this.options.requestScope, previous.reads);
+        }
+        const browser = previous && tool === "authorize_connector" ? await this.browserProgress(previous) : undefined;
+        if (browser?.completed && previous) {
+            // Retire unspent links before the status read. A browser claim racing
+            // these CASes either wins and is observed as pending, or is refused.
+            await this.options.closeLinks(previous.connector, previous.browserNonces);
+            if ((await this.browserProgress(previous)).completed && (await this.connected(previous.connector, context))) {
+                const structuredContent = { connector: previous.connector, status: "ok" };
+                return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
+            }
+        }
+        const envelope = context.mcpReq.envelope;
+        const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
+        const elicitation = object(capabilities) ? capabilities.elicitation : undefined;
+        const capable = envelope?.[PROTOCOL_VERSION_META_KEY] === "2026-07-28" &&
+            object(elicitation) &&
+            Object.hasOwn(elicitation, "url") &&
+            object(elicitation.url);
+        enableAuthorizationHandoffs(this.options.requestScope, !capable);
+        let result = await operation();
+        const relayed = await this.downstream.finish(tool, args, context, result, previous);
+        if (relayed !== result)
+            return relayed;
+        const error = result.structuredContent?.error;
+        const authFailure = result.isError && object(error) && (error.code === "auth_required" || error.code === "downstream_oauth_required");
+        const explicit = tool === "authorize_connector" &&
+            ["oauth", "operator_config"].includes(String(result.structuredContent?.recovery));
+        if (!authFailure && !explicit)
+            return result;
+        const id = authFailure ? error.connector : explicit ? args.connector : undefined;
+        // Every accepted retry owns new request-local facts. Handler-authored
+        // errors and program write summaries cannot establish replay eligibility.
+        const facts = await authRecoveryFacts(this.options.requestScope, String(id));
+        const blocked = !explicit && (!facts.eligible || facts.writeEntered);
+        if (authFailure && (facts.unsafeEntered || (tool !== "call_tool" && !facts.eligible))) {
+            const structuredContent = {
+                ...result.structuredContent,
+                error: {
+                    ...error,
+                    retryable: false,
+                    reconciliationRequired: true,
+                    retry: "This call may have partially run. Reconcile its target before retrying after the operator completes recovery.",
+                },
+            };
+            result = { ...result, structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
+        }
+        const { registry, vault, principal, publicUrl, canManage, unavailable } = this.options;
+        const connector = typeof id === "string" ? registry.getConnector(id) : undefined;
+        const recoverable = connector?.startAuth || (connector?.credential && this.options.credentialUi);
+        if (typeof id !== "string" ||
+            !/^[a-z0-9_-]+$/.test(id) ||
+            !recoverable ||
+            !principal ||
+            !publicUrl ||
+            unavailable ||
+            !canManage(id))
+            return result;
+        // Incapable hosts already received the shared explicit-authorization handoff.
+        if (!capable)
+            return result;
+        if (blocked || !vault?.requestStateKey || !vault.seal || !vault.open) {
+            if (!authFailure)
+                return result;
+            const structuredContent = {
+                ...result.structuredContent,
+                error: {
+                    ...result.structuredContent?.error,
+                    authorizationUrl: error.authorizationUrl ?? (await this.options.connectLink(id)).url,
+                },
+            };
+            return { ...result, structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
+        }
+        if (previous && previous.round >= MAX_ROUNDS)
+            return failure("auth_round_limit", "Connection is still required after three prompts. Connect explicitly, then start a new request.");
+        // Once a verified browser has started this attempt, retries continue it.
+        // A pending consent must never be reset by another force=true prompt.
+        const forced = explicit && args.force === true;
+        const link = await this.options.connectLink(id, forced && !browser?.predecessor, forced ? browser?.predecessor : undefined);
+        const state = {
+            version: 1,
+            principal,
+            endpoint: this.options.endpoint,
+            connector: id,
+            tool,
+            ...(typeof args.address === "string" ? { address: args.address } : {}),
+            digest: requestDigest ?? (await digest(tool, args)),
+            round: (previous?.round ?? 0) + 1,
+            expiresAt: previous?.expiresAt ?? Date.now() + TTL_MS,
+            browserNonces: [...(previous?.browserNonces ?? []), link.nonce],
+            reads: [...new Map([...(previous?.reads ?? []), ...facts.reads].map((read) => [read.address, read])).values()],
+        };
+        const wire = await (await this.stateCodec()).mint(state, context);
+        if (wire.length > 8192) {
+            const structuredContent = {
+                ...result.structuredContent,
+                error: {
+                    ...result.structuredContent?.error,
+                    authorizationUrl: link.url,
+                },
+            };
+            return { ...result, structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
+        }
+        return inputRequired({
+            inputRequests: {
+                [INPUT_KEY]: inputRequired.elicitUrl({
+                    message: MESSAGE,
+                    url: link.url,
+                }),
+            },
+            requestState: wire,
+        });
+    }
+}