@zackbart/connecta 0.37.0 → 0.38.0

package/dist/auth/downstream-oauth.js

@@ -1,3 +1,4 @@
+import { bytesToHex, sha256Hex } from "../bytes.js";
 import { UnauthorizedError } from "@modelcontextprotocol/client";
 import { Effect, Exit } from "effect";
 import { byteReadResponse } from "../byte-read-response.js";
@@ -8,12 +9,12 @@ import { keepErrorName } from "../redaction-identity.js";
 import { fromSignal, runEdge } from "../runtime/run.js";
 import { Settlement } from "../runtime/settlement.js";
 import { SentSecrets } from "../sent-secrets.js";
-import { OAUTH_FLOW_TTL_SECONDS, OAUTH_REFRESH_LEASE_SECONDS, oauthFlowKeys, oauthGrantKeys, oauthRefreshActiveKeys, oauthRefreshKeys, oauthRefreshSpentKeys, } from "../storage/keys.js";
+import { OAUTH_FLOW_TTL_SECONDS, OAUTH_REFRESH_LEASE_SECONDS, oauthFlowKeys, oauthGrantKeys, retiredOAuthKeys, oauthRefreshActiveKeys, oauthRefreshKeys, oauthRefreshSpentKeys, } from "../storage/keys.js";
 import { authenticateRemoteClient, downstreamClientMetadata, remoteClientAuthMethod, } from "./downstream-client-metadata.js";
 import { revokeDownstreamGrant } from "./downstream-revocation.js";
 import { authAwait, authCall, authCatch, authDetached, authFlow, authInvoke, authMethod, authOwnMethod, authProgram, authStorage, authThen, authValue, registerAuth, registerAuthMethod, } from "./native.js";
 import { isOAuthCredentialRequest, isRefreshTokenRequest, refreshResponseOutcome, sdkSafeTokenResponse, tokenGrantType, } from "./oauth-token-response.js";
-import { deleteV2Keys, discoveryIssuer, readV2Grant, } from "./oauth-v2-migration.js";
+import { discoveryIssuer } from "./oauth-grant.js";
 /** @internal Keep the SDK's cloned body reads inside the code exchange's request. */
 export function codeExchangeResponse(response, signal) {
     if (!response.body)
@@ -105,12 +106,11 @@ export class OAuthRequestNotSentError extends ConnectorCallError {
 function randomState() {
     const bytes = new Uint8Array(32);
     crypto.getRandomValues(bytes);
-    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    return bytesToHex(bytes);
 }
 /** Lowercase hex SHA-256 of a consent's `state`: the name of its flow record. */
 export async function oauthStateDigest(state) {
-    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(state));
-    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+    return sha256Hex(state);
 }
 function storedRefreshSpent(raw) {
     const value = raw === null ? undefined : parsed(raw);
@@ -126,10 +126,11 @@ function storedRefreshSpent(raw) {
         : undefined;
 }
 const REFRESH_REQUEST_DEADLINE_MS = 20_000;
+const REFRESH_COMMIT_DEADLINE_MS = 20_000;
 const REFRESH_WAIT_DEADLINE_MS = 35_000;
-function refreshWait(signal) {
+function refreshWait(signal, timeoutMs = REFRESH_WAIT_DEADLINE_MS) {
     const deadline = new AbortController();
-    let timer = setTimeout(() => deadline.abort(), REFRESH_WAIT_DEADLINE_MS);
+    let timer = setTimeout(() => deadline.abort(), timeoutMs);
     let closed = false;
     let transferred = false;
     let requestStarted = false;
@@ -429,9 +430,13 @@ export class OAuthRefreshCoordinator {
             return authFlow(function* () {
                 const flight = { outcome: new Settlement() };
                 this.flights.set(epoch, flight);
-                // Pin the owner partition until the flight settles, whoever is waiting.
+                // Pin the owner partition until this coordinator exits, whoever is waiting.
                 const release = this.retainPartition();
+                let settled = false;
                 const settle = (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
                     if (this.flights.get(epoch) === flight)
                         this.flights.delete(epoch);
                     release();
@@ -443,131 +448,162 @@ export class OAuthRefreshCoordinator {
                         provider.recordRefreshFailure(verdict);
                     settle({ status: "failed", error, ...(verdict ? { verdict } : {}) });
                 };
-                // The authorization server this redemption answers to, fixed now.
-                const issuer = provider.refreshIssuer(epoch);
-                let lease;
-                try {
-                    const claim = (yield authInvoke(provider, "claimRefresh", [epoch, requested, undefined, waiting]));
-                    if (claim instanceof Response) {
-                        const tokens = (yield authInvoke(waiting, "run", [
-                            authMethod(() => {
-                                return authInvoke(provider, "storedTokens", [waiting.signal]);
-                            }),
-                        ]));
-                        if (tokens)
-                            settle({ status: "refreshed", tokens });
-                        else
-                            settle({ status: "retired" });
-                        return claim;
-                    }
-                    lease = claim;
-                }
-                catch (error) {
-                    fail(error, provider.refreshVerdict());
-                    throw error;
-                }
-                const releaseLease = authMethod((verdict, resolution = "ambiguous") => {
-                    return authFlow(function* () {
-                        (yield authInvoke(provider, "releaseRefresh", [lease, verdict, undefined, resolution]));
-                    }.bind(this));
-                });
-                let outcome;
-                const deadline = waiting.signal;
                 let dispatched = false;
+                const unknownOutcome = () => new UnauthorizedError("OAuth refresh outcome is unknown; authorization required.");
+                // One budget for the entire commit/cleanup phase, including retries
+                // and lease release. Interrupt native continuations, never detach a
+                // Promise whose late read could still start a credential write.
+                const complete = authMethod((operation) => {
+                    const completion = refreshWait(undefined, REFRESH_COMMIT_DEADLINE_MS);
+                    return authInvoke(completion, "run", [operation]).pipe(Effect.catch((error) => Effect.fail(completion.signal.aborted ? unknownOutcome() : error)), Effect.ensuring(Effect.sync(() => completion.close())));
+                });
                 try {
-                    const read = authFlow(function* () {
-                        const response = (yield authInvoke(provider, "dispatchRefresh", [
-                            lease,
-                            authMethod(() => authFlow(function* () {
-                                waiting.beginRequest();
-                                dispatched = true;
-                                return (yield authCall(baseFetch, [
-                                    input,
-                                    { ...init, redirect: "manual", signal: deadline },
-                                ]));
-                            }.bind(this))),
-                            waiting,
-                        ]));
-                        if (deadline.aborted) {
-                            void response.body?.cancel().catch(() => { });
-                            throw aborted(deadline);
-                        }
-                        return (yield authCall(refreshResponseOutcome, [response, deadline]));
-                    }.bind(this));
-                    outcome = (yield Effect.raceFirst(read, fromSignal(deadline)));
-                    if (deadline.aborted)
-                        throw aborted(deadline);
-                }
-                catch (error) {
-                    if (!dispatched) {
-                        // Only the coordinator's own preparation deadline can interrupt a
-                        // submitted claim. Caller cancellation no longer reaches this work.
-                        if (!waiting.signal.aborted) {
-                            (yield authCatch(authInvoke(waiting, "run", [
+                    // The authorization server this redemption answers to, fixed now.
+                    const issuer = provider.refreshIssuer(epoch);
+                    let lease;
+                    try {
+                        const claim = (yield authInvoke(provider, "claimRefresh", [epoch, requested, undefined, waiting]));
+                        if (claim instanceof Response) {
+                            const tokens = (yield authInvoke(waiting, "run", [
                                 authMethod(() => {
-                                    return authCall(releaseLease, []);
+                                    return authInvoke(provider, "storedTokens", [waiting.signal]);
                                 }),
-                            ]), () => { }));
-                            if (provider.refreshVerdict()?.kind === "dead") {
+                            ]));
+                            if (tokens)
+                                settle({ status: "refreshed", tokens });
+                            else
+                                settle({ status: "retired" });
+                            return claim;
+                        }
+                        lease = claim;
+                    }
+                    catch (error) {
+                        fail(error, provider.refreshVerdict());
+                        throw error;
+                    }
+                    const releaseLease = authMethod((verdict, resolution = "ambiguous") => {
+                        return authFlow(function* () {
+                            (yield authInvoke(provider, "releaseRefresh", [lease, verdict, undefined, resolution]));
+                        }.bind(this));
+                    });
+                    let outcome;
+                    const deadline = waiting.signal;
+                    try {
+                        const read = authFlow(function* () {
+                            const response = (yield authInvoke(provider, "dispatchRefresh", [
+                                lease,
+                                authMethod(() => authFlow(function* () {
+                                    waiting.beginRequest();
+                                    dispatched = true;
+                                    return (yield authCall(baseFetch, [
+                                        input,
+                                        { ...init, redirect: "manual", signal: deadline },
+                                    ]));
+                                }.bind(this))),
+                                waiting,
+                            ]));
+                            if (deadline.aborted) {
+                                void response.body?.cancel().catch(() => { });
+                                throw aborted(deadline);
+                            }
+                            return (yield authCall(refreshResponseOutcome, [response, deadline]));
+                        }.bind(this));
+                        outcome = (yield Effect.raceFirst(read, fromSignal(deadline)));
+                        if (deadline.aborted)
+                            throw aborted(deadline);
+                    }
+                    catch (error) {
+                        if (!dispatched) {
+                            // Only the coordinator's own preparation deadline can interrupt a
+                            // submitted claim. Caller cancellation no longer reaches this work.
+                            if (!waiting.signal.aborted) {
                                 (yield authCatch(authInvoke(waiting, "run", [
                                     authMethod(() => {
-                                        return authInvoke(provider, "discardRefusedGrant", [requested, epoch]);
+                                        return authCall(releaseLease, []);
                                     }),
                                 ]), () => { }));
+                                if (provider.refreshVerdict()?.kind === "dead") {
+                                    (yield authCatch(authInvoke(waiting, "run", [
+                                        authMethod(() => {
+                                            return authInvoke(provider, "discardRefusedGrant", [requested, epoch]);
+                                        }),
+                                    ]), () => { }));
+                                }
                             }
+                            const failure = waiting.signal.aborted ? provider.refreshContended() : error;
+                            fail(failure, provider.refreshVerdict());
+                            throw failure;
                         }
-                        const failure = waiting.signal.aborted ? provider.refreshContended() : error;
-                        fail(failure, provider.refreshVerdict());
+                        // A sent request without a definitive answer may have rotated the token.
+                        // Persist the refusal before dropping tokens, so interrupted cleanup or a
+                        // later write of the same fingerprint cannot make it redeemable again.
+                        const failure = new UnauthorizedError("OAuth refresh outcome is unknown; authorization required.");
+                        (yield authCall(complete, [
+                            authMethod(() => authFlow(function* () {
+                                (yield authCall(releaseLease, [{ kind: "dead" }]));
+                                (yield authInvoke(provider, "discardRefusedGrant", [requested, epoch]));
+                            })),
+                        ]));
+                        fail(failure, { kind: "dead" });
                         throw failure;
                     }
-                    // A sent request without a definitive answer may have rotated the token.
-                    // Persist the refusal before dropping tokens, so interrupted cleanup or a
-                    // later write of the same fingerprint cannot make it redeemable again.
-                    const failure = new UnauthorizedError("OAuth refresh outcome is unknown; authorization required.");
-                    (yield authCall(releaseLease, [{ kind: "dead" }]));
-                    (yield authInvoke(provider, "discardRefusedGrant", [requested, epoch]));
-                    fail(failure, { kind: "dead" });
-                    throw failure;
+                    finally {
+                        waiting.close();
+                    }
+                    return (yield authCall(complete, [
+                        authMethod(() => authFlow(function* () {
+                            // An answer exists from here on, and is committed whatever the owner does.
+                            if (outcome.failure) {
+                                // Drop a refused grant while the flight still stands: a caller arriving
+                                // meanwhile joins it instead of redeeming the dead token again.
+                                (yield authInvoke(provider, "discardRefusedGrant", [requested, epoch]));
+                                (yield authCall(releaseLease, [outcome.verdict, "resolved"]));
+                                fail(outcome.failure, outcome.verdict);
+                                return outcome.forSdk;
+                            }
+                            // The server consumed the old refresh token; the SDK merges it back the
+                            // same way when a rotation omits one.
+                            const accepted = {
+                                ...outcome.tokens,
+                                ...(outcome.tokens.refresh_token === undefined && requested !== null
+                                    ? { refresh_token: requested }
+                                    : {}),
+                            };
+                            let committed;
+                            try {
+                                committed = (yield authInvoke(provider, "storeRefresh", [epoch, requested, accepted, issuer]));
+                            }
+                            catch {
+                                const failure = new UnauthorizedError("OAuth refresh could not be committed; authorization required.");
+                                (yield authCall(releaseLease, [{ kind: "dead" }, "resolved"]));
+                                (yield authInvoke(provider, "discardRefusedGrant", [requested, epoch]));
+                                fail(failure, { kind: "dead" });
+                                throw failure;
+                            }
+                            if (!committed) {
+                                // Restart, Disconnect, or another consent decides the newer grant.
+                                (yield authCall(releaseLease, [{ kind: "dead" }, "resolved"]));
+                                const failure = new UnauthorizedError("OAuth refresh grant is no longer active.");
+                                fail(failure, { kind: "dead" });
+                                throw failure;
+                            }
+                            (yield authInvoke(provider, "releaseRefresh", [lease, undefined, committed, "resolved"]));
+                            settle({ status: "refreshed", tokens: committed });
+                            return provider.adoptRefresh(committed);
+                        })),
+                    ]));
+                }
+                catch (error) {
+                    fail(error, dispatched ? { kind: "dead" } : provider.refreshVerdict());
+                    throw error;
                 }
                 finally {
                     waiting.close();
+                    // No storage in this finalizer: even interruption or a failed
+                    // cleanup must drop the local flight and its owner retention.
+                    if (!settled)
+                        fail(unknownOutcome(), dispatched ? { kind: "dead" } : provider.refreshVerdict());
                 }
-                // An answer exists from here on, and is committed whatever the owner does.
-                if (outcome.failure) {
-                    // Drop a refused grant while the flight still stands: a caller arriving
-                    // meanwhile joins it instead of redeeming the dead token again.
-                    (yield authInvoke(provider, "discardRefusedGrant", [requested, epoch]));
-                    (yield authCall(releaseLease, [outcome.verdict, "resolved"]));
-                    fail(outcome.failure, outcome.verdict);
-                    return outcome.forSdk;
-                }
-                // The server consumed the old refresh token; the SDK merges it back the
-                // same way when a rotation omits one.
-                const accepted = {
-                    ...outcome.tokens,
-                    ...(outcome.tokens.refresh_token === undefined && requested !== null ? { refresh_token: requested } : {}),
-                };
-                let committed;
-                try {
-                    committed = (yield authInvoke(provider, "storeRefresh", [epoch, requested, accepted, issuer]));
-                }
-                catch {
-                    const failure = new UnauthorizedError("OAuth refresh could not be committed; authorization required.");
-                    (yield authCall(releaseLease, [{ kind: "dead" }, "resolved"]));
-                    (yield authInvoke(provider, "discardRefusedGrant", [requested, epoch]));
-                    fail(failure, { kind: "dead" });
-                    throw failure;
-                }
-                if (!committed) {
-                    // Restart, Disconnect, or another consent decides the newer grant.
-                    (yield authCall(releaseLease, [{ kind: "dead" }, "resolved"]));
-                    const failure = new UnauthorizedError("OAuth refresh grant is no longer active.");
-                    fail(failure, { kind: "dead" });
-                    throw failure;
-                }
-                (yield authInvoke(provider, "releaseRefresh", [lease, undefined, committed, "resolved"]));
-                settle({ status: "refreshed", tokens: committed });
-                return provider.adoptRefresh(committed);
             }.bind(this));
         }, OAuthRefreshCoordinator.prototype.redeem);
     }
@@ -782,7 +818,7 @@ export class KvOAuthProvider {
         if (client)
             this.addClientAuthentication = (headers, params) => authenticateRemoteClient(client, headers, params);
     }
-    /** Stored facts only: no migration, sealing writes, refresh or discovery. */
+    /** Stored facts only: no sealing writes, refresh or discovery. */
     storedAuthorization(issuer) {
         return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "storedAuthorization", [issuer]));
     }
@@ -798,39 +834,6 @@ export class KvOAuthProvider {
     wait(work, signal = this.signal) {
         return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "wait", [work, signal]));
     }
-    /** Legacy helpers must fence their inner reads/deletes too, not just our join. */
-    preparationStorage(signal) {
-        if (!signal)
-            return this.storage;
-        const storage = this.storage;
-        return {
-            ...storage,
-            get: authMethod((key) => {
-                return authInvoke(this, "wait", [
-                    authMethod(() => {
-                        return authStorage(storage, "get", [key]);
-                    }),
-                    signal,
-                ]);
-            }),
-            list: authMethod((prefix) => {
-                return authInvoke(this, "wait", [
-                    authMethod(() => {
-                        return authStorage(storage, "list", [prefix]);
-                    }),
-                    signal,
-                ]);
-            }),
-            delete: authMethod((key) => {
-                return authInvoke(this, "wait", [
-                    authMethod(() => {
-                        return authStorage(storage, "delete", [key]);
-                    }),
-                    signal,
-                ]);
-            }),
-        };
-    }
     // --- the grant record ---------------------------------------------------
     /** The grant's additional authenticated data: record and epoch. */
     grantLabel(epoch) {
@@ -848,21 +851,13 @@ export class KvOAuthProvider {
         return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "openGrant", [raw, signal]));
     }
     /**
-     * The grant as stored now, migrating layout 2 on first sight. A plaintext
+     * The current grant record. A plaintext
      * body, written before the vault could seal, is sealed where it lies by
      * compare-and-set; a failure leaves it readable for the next write to seal.
      */
     readGrant(signal = this.signal) {
         return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "readGrant", [signal]));
     }
-    /** Layout 2 migration and its cleanup retain the reading operation's owner. */
-    migrate(signal) {
-        return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "migrate", [signal]));
-    }
-    /** Deletion is retried on every read, including reads after a reset. */
-    cleanupV2(raw, signal = this.signal) {
-        return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "cleanupV2", [raw, signal]));
-    }
     /** The grant a bound flow reads: a replaced epoch fails it. */
     boundGrant(signal = this.signal) {
         return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "boundGrant", [signal]));
@@ -892,7 +887,6 @@ export class KvOAuthProvider {
                 throw this.flowSuperseded();
             return {
                 epoch: `${ACTIVE_EPOCH_PREFIX}${crypto.randomUUID()}`,
-                ...(grant.cleanupPending ? { cleanupPending: true } : {}),
                 body,
             };
         }
@@ -948,9 +942,10 @@ export class KvOAuthProvider {
      * Begin a flow — a connect, whose 401 may refresh or start consent, or an
      * `api()` call or start — in the live epoch, and return it. Nothing about
      * the grant is decided here: a grant belongs to one server by construction.
+     * An expected epoch continues an existing attempt; a replacement fails it.
      */
-    beginFlow() {
-        return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "beginFlow", []));
+    beginFlow(expectedEpoch) {
+        return runEdge(authOwnMethod(KvOAuthProvider.prototype, this, "beginFlow", [expectedEpoch]));
     }
     /** The epoch this flow is bound to, or the live one. */
     flowEpoch() {
@@ -1373,7 +1368,6 @@ export class KvOAuthProvider {
                 const stored = {
                     connectaOAuth: GRANT_VERSION,
                     epoch: grant.epoch,
-                    ...(grant.cleanupPending ? { cleanupPending: true } : {}),
                     ...(grant.flow !== undefined ? { flow: grant.flow } : {}),
                 };
                 if (Object.keys(grant.body).length > 0) {
@@ -1429,7 +1423,6 @@ export class KvOAuthProvider {
                 }
                 return {
                     epoch: stored.epoch,
-                    ...(stored.cleanupPending ? { cleanupPending: true } : {}),
                     ...(stored.flow !== undefined ? { flow: stored.flow } : {}),
                     body: grantBody(body),
                 };
@@ -1460,10 +1453,17 @@ export class KvOAuthProvider {
                     }),
                     signal,
                 ]));
-                if (raw === null)
-                    raw = (yield authInvoke(this, "migrate", [signal]));
-                if (raw !== null && storedGrant(raw)?.cleanupPending)
-                    raw = (yield authInvoke(this, "cleanupV2", [raw, signal]));
+                if (raw === null) {
+                    // Inspect names only: retired credentials are never opened or copied.
+                    const keys = (yield authInvoke(this, "wait", [
+                        authMethod(() => authStorage(this.storage, "list", [retiredOAuthKeys.scan])),
+                        signal,
+                    ]));
+                    if (keys.some((key) => retiredOAuthKeys.prefixes.some((prefix) => key.startsWith(prefix))))
+                        (this.sealer ?? console).warn(`[connecta] connector "${this.connectorId}" has an unsupported pre-layout-3 OAuth grant; ` +
+                            "treating it as absent. Connect again to authorize, or restore a backup and run the " +
+                            "OAuth migration on Connecta 0.37.1 before upgrading.");
+                }
                 const grant = (yield authInvoke(this, "openGrant", [raw, signal]));
                 if (raw !== null && this.sealer && storedGrant(raw)?.body !== undefined) {
                     const sealed = (yield authInvoke(this, "encodeGrant", [grant, signal]));
@@ -1478,99 +1478,6 @@ export class KvOAuthProvider {
                 return { raw, grant };
             }.bind(this));
         }, KvOAuthProvider.prototype.readGrant);
-        registerAuthMethod(KvOAuthProvider.prototype, "migrate", function (signal) {
-            return authFlow(function* () {
-                const sealer = this.sealer;
-                const found = (yield authInvoke(this, "wait", [
-                    authMethod(() => {
-                        return authCall(readV2Grant, [
-                            this.preparationStorage(signal),
-                            sealer && {
-                                ...sealer,
-                                open: authMethod((label, value) => {
-                                    return authInvoke(this, "wait", [
-                                        authMethod(() => {
-                                            return authInvoke(sealer, "open", [label, value]);
-                                        }),
-                                        signal,
-                                    ]);
-                                }),
-                            },
-                        ]);
-                    }),
-                    signal,
-                ]));
-                if (!found)
-                    return null;
-                const prefix = found.disconnected ? DISCONNECTED_EPOCH_PREFIX : ACTIVE_EPOCH_PREFIX;
-                const encoded = (yield authInvoke(this, "encodeGrant", [
-                    {
-                        epoch: `${prefix}${crypto.randomUUID()}`,
-                        body: found.body,
-                        cleanupPending: true,
-                    },
-                    signal,
-                ]));
-                let written;
-                try {
-                    written = (yield authInvoke(this, "wait", [
-                        authMethod(() => {
-                            return authStorage(this.storage, "compareAndSet", [GRANT, null, encoded]);
-                        }),
-                        signal,
-                    ]));
-                }
-                catch {
-                    if (signal?.aborted)
-                        throw aborted(signal);
-                    throw this.credentialWriteError();
-                }
-                return (yield written
-                    ? authValue(() => encoded)
-                    : authInvoke(this, "wait", [
-                        authMethod(() => {
-                            return authStorage(this.storage, "get", [GRANT]);
-                        }),
-                        signal,
-                    ]));
-            }.bind(this));
-        }, KvOAuthProvider.prototype.migrate);
-        registerAuthMethod(KvOAuthProvider.prototype, "cleanupV2", function (raw, signal) {
-            signal = signal === undefined ? this.signal : signal;
-            return authFlow(function* () {
-                try {
-                    if (!(yield authInvoke(this, "wait", [
-                        authMethod(() => {
-                            return authCall(deleteV2Keys, [this.preparationStorage(signal)]);
-                        }),
-                        signal,
-                    ])))
-                        return raw;
-                    const grant = (yield authInvoke(this, "openGrant", [raw, signal]));
-                    delete grant.cleanupPending;
-                    const cleared = (yield authInvoke(this, "encodeGrant", [grant, signal]));
-                    if ((yield authInvoke(this, "wait", [
-                        authMethod(() => {
-                            return authStorage(this.storage, "compareAndSet", [GRANT, raw, cleared]);
-                        }),
-                        signal,
-                    ])))
-                        return cleared;
-                    return (yield authInvoke(this, "wait", [
-                        authMethod(() => {
-                            return authStorage(this.storage, "get", [GRANT]);
-                        }),
-                        signal,
-                    ]));
-                }
-                catch {
-                    if (signal?.aborted)
-                        throw aborted(signal);
-                    // The durable marker survives both deletion and marker-clear failures.
-                    return raw;
-                }
-            }.bind(this));
-        }, KvOAuthProvider.prototype.cleanupV2);
         registerAuthMethod(KvOAuthProvider.prototype, "boundGrant", function (signal) {
             signal = signal === undefined ? this.signal : signal;
             return authFlow(function* () {
@@ -1770,9 +1677,11 @@ export class KvOAuthProvider {
                 return isDisconnectedEpoch((yield authInvoke(this, "liveEpoch", [])));
             }.bind(this));
         }, KvOAuthProvider.prototype.operatorDisconnected);
-        registerAuthMethod(KvOAuthProvider.prototype, "beginFlow", function () {
+        registerAuthMethod(KvOAuthProvider.prototype, "beginFlow", function (expectedEpoch) {
             return authFlow(function* () {
                 const epoch = (yield authInvoke(this, "liveEpoch", []));
+                if (expectedEpoch !== undefined && epoch !== expectedEpoch)
+                    throw this.flowSuperseded();
                 this.epoch = epoch;
                 this.bound = true;
                 return epoch;
@@ -1893,9 +1802,29 @@ export class KvOAuthProvider {
                 const { body } = (yield authInvoke(this, "activeGrant", []));
                 if (this.signal?.aborted)
                     throw aborted(this.signal);
-                const state = body.discovery;
+                let state = body.discovery;
+                if (state?.resourceMetadataUrl && this.clientOptions?.resourceOrigin) {
+                    let sameOrigin = false;
+                    try {
+                        sameOrigin = new URL(state.resourceMetadataUrl).origin === this.clientOptions.resourceOrigin;
+                    }
+                    catch {
+                        // A malformed legacy URL is no more usable than a foreign one.
+                    }
+                    if (!sameOrigin) {
+                        // Never hand the SDK a legacy foreign URL or its resource
+                        // document. Keep the issuer binding for callbacks, but force
+                        // same-origin resource discovery on every SDK path. This read
+                        // does not mutate the stored grant.
+                        state = { ...state };
+                        delete state.resourceMetadataUrl;
+                        delete state.resourceMetadata;
+                    }
+                }
                 this.assertCredentialFree(state, body);
-                this.consentDiscovery = state;
+                // Bind consent to durable discovery until the SDK saves a new
+                // state. A same-origin metadata 404 can leave the cache unchanged.
+                this.consentDiscovery = body.discovery;
                 return state;
             }.bind(this));
         }, KvOAuthProvider.prototype.discoveryState);
@@ -2704,10 +2633,7 @@ export class KvOAuthProvider {
                 for (let attempt = 0; attempt < MAX_GRANT_WRITES; attempt++) {
                     const { raw, grant } = (yield authInvoke(this, "readGrant", [null]));
                     const carried = preserveClient && !operatorDisconnected ? this.carriableClient(grant) : undefined;
-                    const encoded = (yield authInvoke(this, "encodeGrant", [
-                        { epoch, body: carried ?? {}, cleanupPending: true },
-                        null,
-                    ]));
+                    const encoded = (yield authInvoke(this, "encodeGrant", [{ epoch, body: carried ?? {} }, null]));
                     let written;
                     try {
                         written = (yield authStorage(this.storage, "compareAndSet", [GRANT, raw, encoded]));
@@ -2718,7 +2644,6 @@ export class KvOAuthProvider {
                     if (written) {
                         this.refreshCoordinator?.retire(grant.epoch);
                         try {
-                            (yield authInvoke(this, "cleanupV2", [encoded, null]));
                             (yield authInvoke(this, "sweepConsents", []));
                             (yield authInvoke(this, "sweepRefreshLeases", []));
                         }

package/dist/auth/downstream-revocation.js

@@ -4,7 +4,7 @@ import { fromSignal, runEdge } from "../runtime/run.js";
 import { classifyHost } from "../url-safety.js";
 import { authenticateRemoteClient, remoteClientAuthMethod, } from "./downstream-client-metadata.js";
 import { authCall, authFlow, authProgram, registerAuth } from "./native.js";
-import { discoveryIssuer } from "./oauth-v2-migration.js";
+import { discoveryIssuer } from "./oauth-grant.js";
 /** Local removal succeeded; provider-side removal needs the operator's attention. */
 export class OAuthRevocationError extends ConnectorCallError {
     constructor() {

package/dist/auth/oauth-grant.js

@@ -0,0 +1,11 @@
+function plainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** The issuer a discovery record names, as the SDK derives it. */
+export function discoveryIssuer(state) {
+    if (!plainObject(state) || typeof state.authorizationServerUrl !== "string")
+        return undefined;
+    const metadata = state.authorizationServerMetadata;
+    const issuer = plainObject(metadata) && typeof metadata.issuer === "string" ? metadata.issuer : state.authorizationServerUrl;
+    return issuer === "" ? undefined : issuer;
+}

package/dist/auth/oauth-token-response.js

@@ -3,7 +3,7 @@ import { authCall, authFlow, authInvoke, authProgram, registerAuth } from "./nat
 // The token endpoint's answers as downstream OAuth classifies them and the SDK
 // gets to parse them: a refresh's re-consent verdict, and every failure
 // rebuilt from its OAuth `error` code alone, so nothing else a token endpoint
-// wrote reaches the SDK's console output (#695).
+// wrote reaches the SDK's console output.
 /** The `grant_type` of a token request, or undefined for any other request. */
 export function tokenGrantType(init) {
     if ((init?.method ?? "GET").toUpperCase() !== "POST")