@zackbart/connecta 0.34.1 → 0.35.0

package/dist/auth/static-oauth.js

@@ -1,13 +1,34 @@
 import { auth, OAuthError, UnauthorizedError } from "@modelcontextprotocol/client";
+import { Effect } from "effect";
 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 { deriveContext } from "../derived-context.js";
+import { ConnectorCallError, msg, resendAdviceOf, withResendAdvice } from "../errors.js";
+import { guardedTransport, sendCredentialPost } from "../guarded-transport.js";
+import { oauthPartitionFor, retainOAuthPartition } from "../oauth-partition.js";
 import { oauthSealerFor } from "../oauth-sealing.js";
 import { describeFailure } from "../operator-record.js";
-import { assertOAuthScope, authorizingContext, KvOAuthProvider, refreshCoordinatorsByPartition, } from "./downstream-oauth.js";
+import { assertProviderCallOpen, bindProviderResponse, dispatchProviderRequest, providerRequest, readRequest, recordingFetch, recordProviderResponse, renewedAfterUnauthorized, takeProviderHandoff, vendorRefusal, } from "../provider-call.js";
+import { viewSignal } from "../runtime/call.js";
+import { runEdge } from "../runtime/run.js";
+import { SharedRead } from "../runtime/shared-read.js";
+import { sentSecretsFetch, sentSecretsFor, shortSecretWarning } from "../sent-secrets.js";
+import { unsentAfterUnauthorized } from "../write-outcome.js";
 import { trackRemoteClientRequest } from "./downstream-client-metadata.js";
+import { assertOAuthScope, authorizingContext, codeExchangeResponse, KvOAuthProvider, refreshCoordinatorsByPartition, } from "./downstream-oauth.js";
+import { authView } from "./native-call.js";
+import { authCall, authFlow, authInvoke, authMethod, authOwnMethod, authProgram, authValue, registerAuth, registerAuthMethod, } from "./native.js";
 import { trackOAuthStartReset } from "./oauth-start-reset.js";
+import { bindRenewableGrant, OAUTH_CHALLENGE_MAX_BYTES } from "./renewable-grant.js";
+/**
+ * Token-request header values Connecta itself sends, by lowercase name: JSON
+ * content negotiation and the media types maintained providers configure.
+ * Registering one would redact a vendor's name wherever its fragments recur.
+ * Any other configured value, under any name, may carry a credential and is
+ * registered.
+ */
+export const PUBLIC_TOKEN_REQUEST_HEADERS = new Map([
+    ["accept", new Set(["application/json", "application/vnd.ccbchurch.v2+json"])],
+]);
 /**
  * Downstream OAuth for a hand-written `api()` connector: the authorization
  * code grant against endpoints and a pre-registered client the deployment
@@ -159,8 +180,8 @@ class StaticOAuthProvider extends KvOAuthProvider {
     settings;
     /** Set only for the code exchange of a PKCE-less flow. */
     exchangeCode;
-    constructor(connectorId, ctx, coordinator, settings) {
-        super(connectorId, ctx.storage, `${ctx.baseUrl}/oauth/callback/${connectorId}`, coordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx), ctx.signal, 
+    constructor(connectorId, ctx, coordinator, settings, requestOwned = false) {
+        super(connectorId, ctx.storage, `${ctx.baseUrl}/oauth/callback/${connectorId}`, coordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx), viewSignal(ctx, requestOwned), 
         // 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, { secrets: sentSecretsFor(ctx) });
@@ -171,15 +192,8 @@ class StaticOAuthProvider extends KvOAuthProvider {
      * never written to storage, sealed or otherwise: it is deployment config,
      * not grant state, and an operator disconnect cannot delete it.
      */
-    async clientInformation() {
-        const { settings } = this;
-        return {
-            client_id: settings.clientId,
-            ...(settings.clientSecret !== undefined ? { client_secret: settings.clientSecret } : {}),
-            redirect_uris: [this.redirectUrl],
-            token_endpoint_auth_method: settings.clientAuthentication,
-            issuer: settings.identity,
-        };
+    clientInformation() {
+        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "clientInformation", []));
     }
     configuredAuthorizationBinding() {
         return {
@@ -188,8 +202,8 @@ class StaticOAuthProvider extends KvOAuthProvider {
             tokenEndpoint: this.settings.tokenEndpoint.href,
         };
     }
-    async saveClientInformation() {
-        // Nothing to save: the SDK only saves a client it registered or stamped.
+    saveClientInformation() {
+        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "saveClientInformation", []));
     }
     /**
      * Discovery as a constant. Supplying both halves keeps the SDK from
@@ -198,28 +212,15 @@ class StaticOAuthProvider extends KvOAuthProvider {
      * The metadata names no `issuer`, so the SDK binds grants to the configured
      * token endpoint and does not demand an RFC 9207 `iss` it cannot know.
      */
-    async discoveryState() {
-        const { settings } = this;
-        const metadata = {
-            authorization_endpoint: settings.authorizationEndpoint.href,
-            token_endpoint: settings.tokenEndpoint.href,
-            response_types_supported: ["code"],
-            grant_types_supported: ["authorization_code", "refresh_token"],
-            code_challenge_methods_supported: ["S256"],
-            token_endpoint_auth_methods_supported: [settings.clientAuthentication],
-        };
-        return {
-            authorizationServerUrl: settings.identity,
-            authorizationServerMetadata: metadata,
-            resourceMetadata: { resource: settings.serverUrl.origin },
-        };
+    discoveryState() {
+        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "discoveryState", []));
     }
-    async saveDiscoveryState() {
-        // Configuration is the discovery; there is nothing to remember.
+    saveDiscoveryState() {
+        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "saveDiscoveryState", []));
     }
     /** No RFC 8707 `resource` parameter: a plain REST API names no resource. */
-    async validateResourceURL() {
-        return undefined;
+    validateResourceURL() {
+        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "validateResourceURL", []));
     }
     /**
      * The code exchange without `code_verifier`, for a flow whose authorization
@@ -239,18 +240,122 @@ class StaticOAuthProvider extends KvOAuthProvider {
     exchanging(code) {
         this.exchangeCode = code;
     }
-    async redirectToAuthorization(authorizationUrl) {
-        for (const [name, value] of this.settings.authorizationParams) {
-            authorizationUrl.searchParams.set(name, value);
-        }
-        if (!this.settings.pkce) {
-            authorizationUrl.searchParams.delete("code_challenge");
-            authorizationUrl.searchParams.delete("code_challenge_method");
-        }
-        await super.redirectToAuthorization(authorizationUrl);
+    redirectToAuthorization(authorizationUrl) {
+        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "redirectToAuthorization", [authorizationUrl]));
+    }
+    static {
+        registerAuthMethod(StaticOAuthProvider.prototype, "clientInformation", function () {
+            return authValue(() => {
+                const { settings } = this;
+                return {
+                    client_id: settings.clientId,
+                    ...(settings.clientSecret !== undefined ? { client_secret: settings.clientSecret } : {}),
+                    redirect_uris: [this.redirectUrl],
+                    token_endpoint_auth_method: settings.clientAuthentication,
+                    issuer: settings.identity,
+                };
+            });
+        }, StaticOAuthProvider.prototype.clientInformation);
+        registerAuthMethod(StaticOAuthProvider.prototype, "saveClientInformation", function () {
+            // Nothing to save: the SDK only saves a client it registered or stamped.
+            return Effect.void;
+        }, StaticOAuthProvider.prototype.saveClientInformation);
+        registerAuthMethod(StaticOAuthProvider.prototype, "discoveryState", function () {
+            return authValue(() => {
+                const { settings } = this;
+                const metadata = {
+                    authorization_endpoint: settings.authorizationEndpoint.href,
+                    token_endpoint: settings.tokenEndpoint.href,
+                    response_types_supported: ["code"],
+                    grant_types_supported: ["authorization_code", "refresh_token"],
+                    code_challenge_methods_supported: ["S256"],
+                    token_endpoint_auth_methods_supported: [settings.clientAuthentication],
+                };
+                return {
+                    authorizationServerUrl: settings.identity,
+                    authorizationServerMetadata: metadata,
+                    resourceMetadata: { resource: settings.serverUrl.origin },
+                };
+            });
+        }, StaticOAuthProvider.prototype.discoveryState);
+        registerAuthMethod(StaticOAuthProvider.prototype, "saveDiscoveryState", function () {
+            // Configuration is the discovery; there is nothing to remember.
+            return Effect.void;
+        }, StaticOAuthProvider.prototype.saveDiscoveryState);
+        registerAuthMethod(StaticOAuthProvider.prototype, "validateResourceURL", function () {
+            return authValue(() => {
+                return undefined;
+            });
+        }, StaticOAuthProvider.prototype.validateResourceURL);
+        registerAuthMethod(StaticOAuthProvider.prototype, "redirectToAuthorization", function (authorizationUrl) {
+            return authFlow(function* () {
+                for (const [name, value] of this.settings.authorizationParams) {
+                    authorizationUrl.searchParams.set(name, value);
+                }
+                if (!this.settings.pkce) {
+                    authorizationUrl.searchParams.delete("code_challenge");
+                    authorizationUrl.searchParams.delete("code_challenge_method");
+                }
+                (yield authCall(KvOAuthProvider.prototype.redirectToAuthorization, [authorizationUrl], this));
+            }.bind(this));
+        }, StaticOAuthProvider.prototype.redirectToAuthorization);
     }
 }
 const AUTH_REQUIRED_MESSAGE = "Authorization required — open the URL to connect.";
+/** Release the resource body before renewal, bounding even the facade's discarded challenge. */
+function readChallenge(response, signal, method) {
+    return runEdge(authProgram(readChallengeNative, [response, signal, method]));
+}
+const readChallengeNative = /* @__PURE__ */ registerAuth(readChallenge, function (response, signal, method) {
+    return authFlow(function* () {
+        if (method?.toUpperCase() === "HEAD") {
+            void response.body?.cancel().catch(() => { });
+            return;
+        }
+        const oversized = () => new ConnectorCallError("connector_call_failed", "The OAuth challenge exceeded its response ceiling.", {
+            retryable: false,
+        });
+        if (Number(response.headers.get("content-length")) > OAUTH_CHALLENGE_MAX_BYTES) {
+            void response.body?.cancel().catch(() => { });
+            throw oversized();
+        }
+        if (!response.body)
+            return;
+        const reader = response.body.getReader();
+        const cancel = () => {
+            void reader.cancel().catch(() => { });
+        };
+        signal.addEventListener("abort", cancel, { once: true });
+        if (signal.aborted)
+            cancel();
+        let total = 0;
+        try {
+            while (true) {
+                let chunk;
+                try {
+                    chunk = (yield authInvoke(reader, "read", []));
+                }
+                catch {
+                    // Like the guarded client, a broken challenge body cannot replace its 401.
+                    break;
+                }
+                if (signal.aborted)
+                    throw signal.reason;
+                if (chunk.done)
+                    break;
+                total += chunk.value.byteLength;
+                if (total > OAUTH_CHALLENGE_MAX_BYTES) {
+                    cancel();
+                    throw oversized();
+                }
+            }
+        }
+        finally {
+            signal.removeEventListener("abort", cancel);
+            reader.releaseLock();
+        }
+    });
+});
 /** The grant behind one `api()` connector's `oauth`, as the hooks it exposes. */
 export function staticOAuth(id, config) {
     const settings = settingsFor(id, config);
@@ -261,266 +366,553 @@ export function staticOAuth(id, config) {
     const rejectedScopes = new WeakSet();
     const scopeOf = (ctx) => ctx.requestScope ?? ctx;
     const warnShortSecret = shortSecretWarning();
-    const providerFor = (ctx) => {
+    const providerFor = (ctx, requestOwned = false) => {
         warnShortSecret(settings.clientSecret, ctx.logger);
-        return new StaticOAuthProvider(id, ctx, coordinatorFor(ctx), settings);
+        return new StaticOAuthProvider(id, ctx, coordinatorFor(ctx), settings, requestOwned);
     };
     /**
-     * The global `fetch`, read per request, with the configured token-request
+     * The owned credential transport, 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 = async (ctx, input, init = {}) => {
-        const url = new URL(input);
-        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);
-        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" }));
-    };
+    const tokenEndpointFetch = authMethod((secrets, input, init = {}) => {
+        return authFlow(function* () {
+            const url = new URL(input);
+            const request = { ...init, redirect: "manual" };
+            if (settings.tokenRequestHeaders.length && `${url.origin}${url.pathname}` === settings.identity) {
+                const headers = new Headers(init.headers);
+                for (const [name, value] of settings.tokenRequestHeaders)
+                    headers.set(name, value);
+                for (const [name, value] of settings.tokenRequestHeaders)
+                    if (!PUBLIC_TOKEN_REQUEST_HEADERS.get(name.toLowerCase())?.has(value))
+                        secrets.header(value);
+                request.headers = headers;
+            }
+            trackRemoteClientRequest(secrets, input, request);
+            // The coordinator or code-exchange wrapper authorizes this send. Refresh
+            // claim submission may outlive the caller; this transport uses no
+            // request-owned capability and changes no closed resource-call ledger.
+            const dispatch = {
+                dispatched: false,
+                auxiliary: true,
+                provider: id,
+                method: request.method ?? "GET",
+            };
+            secrets.request(input, request);
+            const response = (yield authCall(sendCredentialPost, [
+                input,
+                request,
+                () => dispatchProviderRequest(undefined, dispatch, request.headers),
+            ]));
+            recordProviderResponse(dispatch, response.status);
+            return byteReadResponse(response);
+        });
+    });
     /**
      * The SDK's `auth()` over this provider. The token endpoint is fetched
      * 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, (input, init) => tokenEndpointFetch(ctx, input, init), ctx.signal, ctx.defer),
+    const runAuth = authMethod((provider, ctx, exchange, requestOwned = false) => {
+        return authFlow(function* () {
+            const secrets = sentSecretsFor(ctx);
+            return (yield authCall(auth, [
+                provider,
+                {
+                    serverUrl: settings.serverUrl,
+                    ...exchange,
+                    fetchFn: coordinatorFor(ctx).coordinatedFetch(provider, authMethod((input, init) => {
+                        return authFlow(function* () {
+                            if (exchange) {
+                                // A code exchange has no submitted refresh claim transferring
+                                // ownership. Only explicit scope revocation stops a callback:
+                                // the production callback route remains uninterruptible and
+                                // does not revoke its own scope while exchanging a code.
+                                return (yield authView(ctx, authMethod((signal) => {
+                                    return authFlow(function* () {
+                                        assertProviderCallOpen(ctx, id, true);
+                                        const response = (yield authCall(tokenEndpointFetch, [
+                                            secrets,
+                                            input,
+                                            {
+                                                ...init,
+                                                signal: init?.signal ? AbortSignal.any([init.signal, signal]) : signal,
+                                            },
+                                        ]));
+                                        // An override can ignore abort. Never hand its late tokens
+                                        // to the SDK, which would otherwise persist both credentials.
+                                        if (signal.aborted) {
+                                            void response.body?.cancel().catch(() => { });
+                                            throw signal.reason;
+                                        }
+                                        // The SDK clones and reads this body after fetch resolves.
+                                        // Revocation must cancel that read even for a custom fetch.
+                                        return codeExchangeResponse(response, signal);
+                                    });
+                                }), true));
+                            }
+                            return (yield authCall(tokenEndpointFetch, [secrets, input, init]));
+                        });
+                    }), viewSignal(ctx, requestOwned || exchange !== undefined), ctx.defer, undefined, () => {
+                        guardedTransport(true);
+                    }),
+                },
+            ]));
+        });
     });
     // 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:
-     * a token another request has already rotated in, or else one coordinated
-     * refresh. A second 401 is `auth_required`, latched for the request scope
-     * so a program's later calls do not each spend a refresh on it.
+     * The token to send after `spent` drew a 401: one another request has
+     * already rotated in, or else one coordinated refresh.
      */
-    const authorizedFetch = async (ctx, input, init = {}) => {
-        const url = new URL(input);
-        if (!settings.apiOrigins.has(url.origin)) {
-            throw new ConnectorCallError("connector_call_failed", `Connector "${id}" sends its OAuth access token only to its declared ` +
-                `apiOrigins, and ${url.origin} is not one of them.`, { retryable: false });
-        }
-        if (init.body instanceof ReadableStream) {
-            throw new TypeError(`Connector "${id}": ctx.oauth.fetch may replay a request once after a ` +
-                "refresh, so it cannot send a stream body. Buffer the body first.");
-        }
-        const headers = new Headers(init.headers);
-        if (headers.has("authorization")) {
-            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 = 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.
-            // 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 } : {}),
+    const renewedToken = authMethod((provider, ctx, spent, requestOwned = false) => {
+        return authFlow(function* () {
+            // Only renewal whose claim CAS was submitted may survive this call.
+            // Race each preparation read too, and never resume SDK work or consume a
+            // rotated token after closure, even if a storage promise completes late.
+            const live = authMethod((work) => {
+                return authFlow(function* () {
+                    if (ctx.signal?.aborted)
+                        throw ctx.signal.reason;
+                    const value = (yield authView(ctx, work, requestOwned));
+                    if (ctx.signal?.aborted)
+                        throw ctx.signal.reason;
+                    return value;
+                });
             });
-            return byteReadResponse(response);
+            const current = (yield authCall(live, [
+                authMethod(() => {
+                    return authInvoke(provider, "tokens", [issuerContext]);
+                }),
+            ]));
+            if (current && current.access_token !== spent)
+                return current.access_token;
+            if ((yield authCall(live, [
+                authMethod(() => {
+                    return authCall(runAuth, [provider, ctx, undefined, requestOwned]);
+                }),
+            ])) !== "AUTHORIZED")
+                throw authRequiredError();
+            const refreshed = (yield authCall(live, [
+                authMethod(() => {
+                    return authInvoke(provider, "tokens", [issuerContext]);
+                }),
+            ]));
+            if (!refreshed)
+                throw authRequiredError();
+            return refreshed.access_token;
+        });
+    });
+    /** One call's grant use; submitted refresh work keeps the coordinator's owner. */
+    const grantFor = (ctx, requestOwned = false) => {
+        let provider;
+        const use = authMethod((work) => {
+            return authView(ctx, authMethod((signal) => {
+                return authFlow(function* () {
+                    assertProviderCallOpen(ctx, id, requestOwned);
+                    if (rejectedScopes.has(scopeOf(ctx)))
+                        throw authRequiredError();
+                    const live = deriveContext(ctx, { signal });
+                    const release = retainOAuthPartition(oauthPartitionFor(live));
+                    try {
+                        provider ??= new SharedRead(() => authView(live, authMethod(() => {
+                            return authFlow(function* () {
+                                const value = providerFor(live, requestOwned);
+                                const epoch = (yield authInvoke(value, "beginFlow", []));
+                                if (value.isOperatorDisconnectedEpoch(epoch)) {
+                                    throw new ConnectorCallError("downstream_oauth_required", disconnectedMessage);
+                                }
+                                return value;
+                            });
+                        }), requestOwned), undefined, ctx.requestScope ?? ctx);
+                        return (yield authCall(work, [(yield provider.join(signal)), live]));
+                    }
+                    catch (error) {
+                        if (signal.aborted)
+                            throw signal.reason;
+                        if (error instanceof UnauthorizedError) {
+                            rejectedScopes.add(scopeOf(ctx));
+                            throw authRequiredError();
+                        }
+                        throw error;
+                    }
+                    finally {
+                        release();
+                    }
+                });
+            }), requestOwned);
+        });
+        return {
+            token: authMethod(() => {
+                return authCall(use, [
+                    authMethod((provider) => {
+                        return authFlow(function* () {
+                            const tokens = (yield authInvoke(provider, "tokens", [issuerContext]));
+                            if (!tokens)
+                                throw authRequiredError();
+                            return tokens.access_token;
+                        });
+                    }),
+                ]);
+            }),
+            refresh: authMethod((stale) => {
+                return authCall(use, [
+                    authMethod((provider, live) => {
+                        return authCall(renewedToken, [provider, live, stale, requestOwned]);
+                    }),
+                ]);
+            }),
+            rejected: authMethod(() => {
+                return authView(ctx, authMethod(() => {
+                    return authValue(() => {
+                        rejectedScopes.add(scopeOf(ctx));
+                        throw authRequiredError();
+                    });
+                }), requestOwned);
+            }),
         };
-        if (rejectedScopes.has(scopeOf(ctx)))
-            throw authRequiredError();
-        const release = retainOAuthPartition(oauthPartitionFor(ctx));
-        try {
-            if (signal?.aborted)
-                throw signal.reason;
+    };
+    /**
+     * One request through the owner's grant. A 401 earns exactly one recovery
+     * ({@link renewedToken}). A read is then sent once more; a write never is
+     * (INV-9), since a server may act on a request before it rejects the
+     * token. Whatever recovery meets is never reported as retryable: an
+     * authorization verdict keeps its code, and anything else (a disconnect or
+     * reset racing the refresh) leaves the outcome unknown. A second 401 is
+     * `auth_required`, latched for the request scope so a program's later
+     * calls do not each spend a refresh on it.
+     */
+    const authorizedFetch = authMethod((ctx, input, init = {}) => {
+        return authFlow(function* () {
+            let prepared = takeProviderHandoff(init);
+            const auxiliary = prepared?.auxiliary === true;
+            // Own the complete token preparation and fetch helper. The coordinator
+            // still owns a submitted refresh claim independently of this wait.
+            return (yield authView(ctx, authMethod((owned) => {
+                return authFlow(function* () {
+                    // A call that already ended reads no token and sends nothing more.
+                    assertProviderCallOpen(ctx, id, auxiliary);
+                    const owner = prepared;
+                    const url = new URL(input);
+                    if (!settings.apiOrigins.has(url.origin)) {
+                        throw new ConnectorCallError("connector_call_failed", `Connector "${id}" sends its OAuth access token only to its declared ` +
+                            `apiOrigins, and ${url.origin} is not one of them.`, { retryable: false });
+                    }
+                    if (init.body instanceof ReadableStream) {
+                        throw new TypeError(`Connector "${id}": ctx.oauth.fetch may replay a request once after a ` +
+                            "refresh, so it cannot send a stream body. Buffer the body first.");
+                    }
+                    const headers = new Headers(init.headers);
+                    if (headers.has("authorization")) {
+                        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 ? AbortSignal.any([init.signal, owned]) : owned;
+                    ctx = deriveContext(ctx, { signal });
+                    const detachAnswers = [];
+                    const send = authMethod((accessToken) => {
+                        return authFlow(function* () {
+                            if (signal?.aborted)
+                                throw signal.reason;
+                            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.
+                            // 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 request = {
+                                ...init,
+                                headers: sent,
+                                redirect: "manual",
+                                ...(signal ? { signal } : {}),
+                            };
+                            const dispatch = prepared ?? providerRequest(ctx, auxiliary, id);
+                            prepared = undefined;
+                            dispatchProviderRequest(ctx, dispatch, sent, request.method ?? "GET");
+                            // A native waiter can close before fetch settles. This leaf
+                            // observer records only immutable response facts, and cancels
+                            // a late body; it never resumes request-owned preparation.
+                            const pending = sentSecretsFetch(ctx)(url, request).then((response) => {
+                                recordProviderResponse(dispatch, response.status);
+                                if (response.status === 401) {
+                                    // Closure can settle the handler before renewal's catch maps
+                                    // this answer. Preserve its OAuth verdict in the ledger first;
+                                    // only the final write decider reports it. A live renewal keeps
+                                    // its own precise verdict and never replays a write.
+                                    const abandoned = () => {
+                                        vendorRefusal(unsentAfterUnauthorized(`Connector "${id}"'s API`, signal.reason, "downstream_oauth_required"), dispatch);
+                                    };
+                                    if (signal.aborted)
+                                        abandoned();
+                                    else {
+                                        signal.addEventListener("abort", abandoned, { once: true });
+                                        detachAnswers.push(() => signal.removeEventListener("abort", abandoned));
+                                    }
+                                }
+                                // A custom fetch may answer after revocation. Its physical status
+                                // remains a fact, but its body belongs to no live helper or handler.
+                                if (signal.aborted)
+                                    void response.body?.cancel().catch(() => { });
+                                return response;
+                            });
+                            const response = (yield authValue(() => pending));
+                            if (signal.aborted)
+                                throw signal.reason;
+                            const answer = byteReadResponse(response);
+                            bindProviderResponse(answer, dispatch, owner);
+                            return { response: answer, dispatch };
+                        });
+                    });
+                    const release = retainOAuthPartition(oauthPartitionFor(ctx));
+                    try {
+                        if (signal?.aborted)
+                            throw signal.reason;
+                        const grant = grantFor(ctx, auxiliary);
+                        const stale = (yield authInvoke(grant, "token", []));
+                        const { response: first, dispatch } = (yield authCall(send, [stale]));
+                        if (first.status !== 401)
+                            return first;
+                        try {
+                            (yield authCall(readChallenge, [first, signal, init.method]));
+                        }
+                        catch (error) {
+                            if (signal.aborted)
+                                throw signal.reason;
+                            if (!readRequest(dispatch)) {
+                                throw vendorRefusal(unsentAfterUnauthorized(`Connector "${id}"'s API`, error, "downstream_oauth_required"), dispatch);
+                            }
+                            throw error;
+                        }
+                        if (!readRequest(dispatch)) {
+                            let renewal;
+                            try {
+                                const fresh = (yield authInvoke(grant, "refresh", [stale]));
+                                if (signal?.aborted)
+                                    throw signal.reason;
+                                // The call's ledger keeps this 401's verdict, or that renewal
+                                // replaced the token this request sent (Q8). The same token back
+                                // renewed nothing.
+                                renewedAfterUnauthorized(dispatch, stale, fresh);
+                                if (fresh === stale)
+                                    renewal = authRequiredError();
+                            }
+                            catch (error) {
+                                if (error instanceof UnauthorizedError)
+                                    rejectedScopes.add(scopeOf(ctx));
+                                renewal = error instanceof UnauthorizedError ? authRequiredError() : error;
+                            }
+                            throw vendorRefusal(unsentAfterUnauthorized(`Connector "${id}"'s API`, renewal, "downstream_oauth_required"), dispatch);
+                        }
+                        const accessToken = (yield authInvoke(grant, "refresh", [stale]));
+                        if (signal?.aborted)
+                            throw signal.reason;
+                        renewedAfterUnauthorized(dispatch, stale, accessToken);
+                        const { response: second } = (yield authCall(send, [accessToken]));
+                        if (second.status !== 401)
+                            return second;
+                        void second.body?.cancel().catch(() => { });
+                        return (yield authInvoke(grant, "rejected", []));
+                    }
+                    catch (error) {
+                        // The SDK can replace cancellation with its passive-consent refusal,
+                        // and write recovery normally replaces errors with a 401 verdict. A
+                        // closed capability must still fail promptly with its own close reason;
+                        // the invocation's ledger retains the write's uncertainty and handoff.
+                        if (signal?.aborted)
+                            throw signal.reason;
+                        if (error instanceof UnauthorizedError) {
+                            rejectedScopes.add(scopeOf(ctx));
+                            throw authRequiredError();
+                        }
+                        throw error;
+                    }
+                    finally {
+                        for (const detach of detachAnswers)
+                            detach();
+                        release();
+                    }
+                });
+            }), auxiliary));
+        });
+    });
+    const status = authMethod((ctx) => {
+        return authFlow(function* () {
+            if (rejectedScopes.has(scopeOf(ctx))) {
+                return {
+                    state: "auth_required",
+                    message: "Authorization required \u2014 the downstream rejected this connector's OAuth grant.",
+                };
+            }
+            // A status read never starts authorization: this provider cannot, and
+            // 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);
-            // 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);
+            if ((yield authInvoke(provider, "operatorDisconnected", []))) {
+                return { state: "auth_required", message: disconnectedMessage };
             }
-            const tokens = await provider.tokens(issuerContext);
-            if (!tokens)
-                throw authRequiredError();
-            const first = await send(tokens.access_token);
-            if (first.status !== 401)
-                return first;
-            void first.body?.cancel().catch(() => { });
-            let accessToken;
-            const current = await provider.tokens(issuerContext);
-            if (current && current.access_token !== tokens.access_token) {
-                accessToken = current.access_token;
+            return (yield authInvoke(provider, "tokens", [issuerContext]))
+                ? { state: "ok" }
+                : { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
+        });
+    });
+    const startAuth = authMethod((original, opts) => {
+        return authFlow(function* () {
+            const ctx = authorizingContext(original);
+            const provider = providerFor(ctx);
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
+            const disconnected = opts?.force
+                ? false
+                : (yield authInvoke(provider, "operatorDisconnected", []));
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
+            if (opts?.force || disconnected) {
+                (yield authInvoke(provider, "resetAuthorization", []));
+                rejectedScopes.delete(scopeOf(original));
             }
             else {
-                if ((await runAuth(provider, ctx)) !== "AUTHORIZED")
-                    throw authRequiredError();
-                const refreshed = await provider.tokens(issuerContext);
-                if (!refreshed)
-                    throw authRequiredError();
-                accessToken = refreshed.access_token;
-            }
-            const second = await send(accessToken);
-            if (second.status !== 401)
-                return second;
-            void second.body?.cancel().catch(() => { });
-            rejectedScopes.add(scopeOf(ctx));
-            throw authRequiredError();
-        }
-        catch (error) {
-            if (error instanceof UnauthorizedError) {
-                rejectedScopes.add(scopeOf(ctx));
-                throw authRequiredError();
+                // Hand back a recent consent URL rather than overwrite the verifier
+                // the operator may be mid-consent on.
+                const pending = (yield authInvoke(provider, "reusablePendingAuthorizationUrl", []));
+                if (pending) {
+                    return {
+                        state: "auth_required",
+                        authorizationUrl: pending,
+                        authorizationReused: true,
+                        message: AUTH_REQUIRED_MESSAGE,
+                    };
+                }
             }
-            throw error;
-        }
-        finally {
-            release();
-        }
-    };
-    const status = async (ctx) => {
-        if (rejectedScopes.has(scopeOf(ctx))) {
-            return {
-                state: "auth_required",
-                message: "Authorization required — the downstream rejected this connector's OAuth grant.",
-            };
-        }
-        // A status read never starts authorization: this provider cannot, and
-        // 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(issuerContext))
-            ? { state: "ok" }
-            : { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
-    };
-    const startAuth = async (original, opts) => {
-        const ctx = authorizingContext(original);
-        const provider = providerFor(ctx);
-        if (ctx.signal?.aborted)
-            throw ctx.signal.reason;
-        const disconnected = opts?.force ? false : await provider.operatorDisconnected();
-        if (ctx.signal?.aborted)
-            throw ctx.signal.reason;
-        if (opts?.force || disconnected) {
-            await provider.resetAuthorization();
-            rejectedScopes.delete(scopeOf(original));
-        }
-        else {
-            // Hand back a recent consent URL rather than overwrite the verifier
-            // the operator may be mid-consent on.
-            const pending = await provider.reusablePendingAuthorizationUrl();
-            if (pending) {
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
+            try {
+                // A grant from a since-repointed token endpoint reads as absent here,
+                // and the consent this start begins replaces it.
+                (yield authInvoke(provider, "beginFlow", []));
+                if ((yield authInvoke(provider, "tokens", [issuerContext]))) {
+                    return { state: "ok", message: "Already authorized \u2014 connection is healthy." };
+                }
+                if ((yield authCall(runAuth, [provider, ctx])) === "AUTHORIZED") {
+                    return { state: "ok", message: "Already authorized \u2014 connection is healthy." };
+                }
+                const authorizationUrl = (yield authInvoke(provider, "consentUrl", []));
                 return {
                     state: "auth_required",
-                    authorizationUrl: pending,
-                    authorizationReused: true,
+                    ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
                     message: AUTH_REQUIRED_MESSAGE,
                 };
             }
-        }
-        if (ctx.signal?.aborted)
-            throw ctx.signal.reason;
-        try {
-            // 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.consentUrl();
-            return {
-                state: "auth_required",
-                ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
-                message: AUTH_REQUIRED_MESSAGE,
-            };
-        }
-        catch (error) {
-            if (error instanceof UnauthorizedError) {
-                return { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
+            catch (error) {
+                if (error instanceof UnauthorizedError) {
+                    return { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
+                }
+                // Reaches the agent through authorize_connector. Text already in
+                // connecta's words passes with its advice to try again, since this is
+                // no write's failure (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
+                        ? withResendAdvice(msg(error), resendAdviceOf(error))
+                        : describeFailure(id, 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) => {
-        rejectedScopes.delete(scopeOf(ctx));
-        await providerFor(ctx).resetAuthorization(true);
-    };
-    const verifyState = async (state, ctx) => {
-        // The provider that verified the state captured its flow's epoch, and the
-        // exchange must write under exactly that one.
-        const provider = providerFor(ctx);
-        callbackProviders.set(scopeOf(ctx), provider);
-        return provider.verifyState(state);
-    };
-    const finishAuth = async (code, ctx, callbackParams) => {
-        const provider = callbackProviders.get(scopeOf(ctx)) ?? providerFor(ctx);
-        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 } : {}),
         });
-        if (result !== "AUTHORIZED") {
-            throw new UnauthorizedError("Failed to authorize");
-        }
-        rejectedScopes.delete(scopeOf(ctx));
-    };
+    });
+    const disconnectAuth = authMethod((ctx) => {
+        return authFlow(function* () {
+            rejectedScopes.delete(scopeOf(ctx));
+            (yield authInvoke(providerFor(ctx), "resetAuthorization", [true]));
+        });
+    });
+    const verifyState = authMethod((state, ctx) => {
+        return authFlow(function* () {
+            // The provider that verified the state captured its flow's epoch, and the
+            // exchange must write under exactly that one.
+            const provider = providerFor(ctx);
+            callbackProviders.set(scopeOf(ctx), provider);
+            return (yield authInvoke(provider, "verifyState", [state]));
+        });
+    });
+    const finishAuth = authMethod((code, ctx, callbackParams) => {
+        return authView(ctx, authMethod(() => {
+            return authFlow(function* () {
+                const provider = callbackProviders.get(scopeOf(ctx)) ?? providerFor(ctx);
+                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 || !(yield authInvoke(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);
+                (yield authInvoke(provider, "bindFlow", []));
+                const result = (yield authCall(runAuth, [
+                    provider,
+                    ctx,
+                    {
+                        authorizationCode,
+                        ...(iss !== undefined ? { iss } : {}),
+                    },
+                ]));
+                if (result !== "AUTHORIZED") {
+                    throw new UnauthorizedError("Failed to authorize");
+                }
+                rejectedScopes.delete(scopeOf(ctx));
+            });
+        }), true);
+    });
     return {
-        status: retainingOAuthPartition(status, 0),
-        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),
-        }),
+        status: retainAuthPartition(status, 0),
+        startAuth: retainAuthPartition(startAuth, 0),
+        disconnectAuth: retainAuthPartition(disconnectAuth, 0),
+        verifyState: retainAuthPartition(verifyState, 1),
+        verifyCallbackIssuer: retainAuthPartition(authMethod((issuer, ctx) => {
+            return authValue(() => {
+                const provider = callbackProviders.get(scopeOf(ctx));
+                if (!provider)
+                    return false;
+                provider.validateCallbackIssuer(issuer);
+                return true;
+            });
+        }), 1),
+        consumeAuthError: retainAuthPartition(authMethod((ctx) => {
+            return authFlow(function* () {
+                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.");
+                (yield authInvoke(provider, "consumeAuthError", []));
+            });
+        }), 0),
+        finishAuth: retainAuthPartition(finishAuth, 1),
+        access: (ctx) => bindRenewableGrant({
+            fetch: recordingFetch(authMethod((input, init) => {
+                return authCall(authorizedFetch, [ctx, input, init]);
+            })),
+        }, grantFor(ctx)),
     };
 }
+// Hook calls keep the existing owner partition pinned while their native
+// program settles. Each Promise shell enters its own registered program.
+function retainAuthPartition(operation, contextIndex = 0) {
+    return authMethod((...args) => authFlow(function* () {
+        const release = retainOAuthPartition(oauthPartitionFor(args[contextIndex]));
+        try {
+            return (yield authCall(operation, args));
+        }
+        finally {
+            release();
+        }
+    }));
+}