@zackbart/connecta 0.28.0 → 0.29.0

package/dist/auth/downstream-oauth.js

@@ -1,397 +1,101 @@
 import { UnauthorizedError } from "@modelcontextprotocol/client";
 import { Deferred, Effect } from "effect";
-import { retryAfterMs } from "../connectors/guarded-fetch.js";
+import { revokeDownstreamGrant } from "./downstream-revocation.js";
+import { authenticateRemoteClient, downstreamClientMetadata, remoteClientAuthMethod, } from "./downstream-client-metadata.js";
+import { SentSecrets } from "../sent-secrets.js";
 import { ConnectorCallError } from "../errors.js";
+import { attachOAuthPartition, oauthPartitionFor, retainOAuthPartition } from "../oauth-partition.js";
+import { inheritOAuthSealer } from "../oauth-sealing.js";
 import { detach, fromSignal, runEdge } from "../runtime/run.js";
-/** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
-function randomState() {
-    const bytes = new Uint8Array(32);
-    crypto.getRandomValues(bytes);
-    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-}
-/** Length-safe, constant-time string compare (no early-exit on first mismatch). */
-function timingSafeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let diff = 0;
-    for (let i = 0; i < a.length; i++)
-        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    return diff === 0;
-}
-const LEGACY_GENERATION = "legacy";
-const ACTIVE_GENERATION_PREFIX = "v2:";
-const RESETTING_GENERATION_PREFIX = "reset:";
-const DISCONNECTED_GENERATION_PREFIX = "disconnected:";
-const STORED_VALUE_VERSION = 2;
-const OAUTH_VALUE_KEYS = [
-    "oauth:client",
-    "oauth:tokens",
-    "oauth:pending",
-    "oauth:verifier",
-    "oauth:state",
-    "oauth:discovery",
-];
-/**
- * The values that are credentials: tokens, a registered client (which may
- * carry a secret), and the PKCE verifier. With a sealing vault they are
- * ciphertext at rest. Flow bookkeeping — state, pending URL, discovery, and
- * the generation — stays plaintext: the callback route reads state directly,
- * and none of it authenticates anything on its own.
- */
-const SEALED_OAUTH_KEYS = new Set([
-    "oauth:client",
-    "oauth:tokens",
-    "oauth:verifier",
-]);
-const SEALED_VALUE_VERSION = 1;
-/**
- * The longest cleanup lineage a reset publishes. A reset's storage work no
- * longer depends on the lineage's length — it deletes one retired generation
- * after the fence and sweeps at most MAX_EXPIRED_SWEEP before it — so this
- * guards only the size of the two records every reset reads. A generation
- * name is 39 characters, so 5,000 entries is about 210 KB of manifest and
- * 280 KB of times: far under Workers KV's 25 MiB value limit, and a few
- * milliseconds to parse. Reaching it takes more than 4,000 resets of one
- * connector in a day on top of the 1,000 an earlier release allowed, which
- * is a loop, not an operator. An earlier release refuses a lineage longer
- * than 1,000, so rolling back past this one wedges only a connector that
- * went beyond that — which that release would have wedged anyway.
- */
-const MAX_CLEANUP_BACKLOG = 5_000;
-/**
- * How long a retired generation stays in the cleanup lineage. A late write
- * lands in a retired namespace only from a request that captured that
- * generation before the reset and is still running — an OAuth flow, a token
- * refresh, or a reader whose eventually consistent store (Workers KV serves a
- * stale generation for a minute or more) has not yet seen the fence. None of
- * those outlive a day. A late writer's own cleanup deletes what it wrote, and
- * if that delete fails it records the generation as retired again from that
- * moment; residue it leaves is unreadable behind the fence either way. Once
- * the grace has passed, a reset sweeps the generation, and one whose keys
- * are confirmed deleted cannot be written again, so it leaves the lineage.
- * That is an assumption, not a proof: a request that holds a retired
- * generation for longer than this and dies between its write and its own
- * cleanup leaves residue no reset tracks. It is still unreadable — the epoch
- * fence, not this cleanup, is what keeps an old namespace out of use.
- */
-const CLEANUP_GRACE_MS = 24 * 60 * 60 * 1000;
-/**
- * The most past-grace generations one reset sweeps before publishing. The
- * rest stay in the lineage for a later reset, so a backlog built by a burst
- * of resets drains over several resets instead of in one request.
- */
-const MAX_EXPIRED_SWEEP = 16;
-/**
- * Independent storage deletes one cleanup keeps in flight: Workers allows six
- * simultaneous open connections per invocation, and more would only queue.
- */
-const DELETE_CONCURRENCY = 6;
-/**
- * How many of the most recently retired generations a reset checks for an
- * unfinished cleanup. The case that matters is the one just before: an
- * operator whose Disconnect or Restart reported a failed cleanup retries, and
- * that retry must delete the grant the failure left behind. Eight covers that
- * with room for a burst of failing restarts, costs eight small reads per
- * reset, and bounds a retry to eight generations' deletes; anything older is
- * reclaimed by the past-grace sweep instead.
- */
-const RETRY_PROBES = 8;
-/**
- * How long a pending authorization URL may be handed out again instead of
- * starting a fresh flow. The URL itself never expires on connecta's side, but
- * the authorization server's half of it does: a pushed request URI lives
- * seconds to minutes (RFC 9126), and login transactions are commonly held
- * for minutes, not hours. Past this age a reissued URL is more likely to land
- * the operator on an expired-session page than on consent, and a fresh start
- * costs one authorization request, not a client registration. It also sits
- * inside the registry's 15-minute personal-auth handoff.
- */
-const PENDING_AUTHORIZATION_MAX_AGE_MS = 10 * 60 * 1000;
-/**
- * Union two lineages by generation, keeping the later retirement time, so a
- * merge can only ever lengthen a generation's grace. Order is first-seen.
- */
-function mergeLineage(...lineages) {
-    const merged = new Map();
-    for (const lineage of lineages) {
-        for (const { generation, retiredAt } of lineage) {
-            const known = merged.get(generation);
-            merged.set(generation, known === undefined ? retiredAt : Math.max(known, retiredAt));
-        }
+import { OAUTH_FLOW_TTL_SECONDS, OAUTH_REFRESH_LEASE_SECONDS, oauthFlowKeys, oauthGrantKeys, oauthRefreshKeys, oauthRefreshSpentKeys, oauthRefreshActiveKeys, } from "../storage/keys.js";
+import { isRefreshTokenRequest, isOAuthCredentialRequest, refreshResponseOutcome, sdkSafeTokenResponse, tokenGrantType, } from "./oauth-token-response.js";
+import { deleteV2Keys, discoveryIssuer, readV2Grant } from "./oauth-v2-migration.js";
+/** RFC 6749 section 3.3: one or more scope tokens, separated by single spaces. */
+const OAUTH_SCOPE = /^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/;
+/** Refuse, at construction, a configured scope no authorization server could parse. */
+export function assertOAuthScope(connectorId, scope) {
+    if (scope !== undefined && !OAUTH_SCOPE.test(scope)) {
+        throw new Error(`[connecta] connector "${connectorId}" OAuth scope must contain space-separated scope tokens.`);
     }
-    return [...merged].map(([generation, retiredAt]) => ({
-        generation,
-        retiredAt,
-    }));
 }
 /**
- * A limiter admitting at most `limit` storage operations at once. A finished
- * operation hands its slot straight to the next waiter, so the bound holds
- * even when new callers arrive between the two.
+ * The context an explicit authorization start runs under: allowed to begin
+ * consent, with a request scope of its own, carrying the registry's sealer and
+ * owner partition across the copy. Only `startAuth` builds one; status reads
+ * and calls never do, which is what keeps them from starting authorization.
  */
-function concurrencyLimit(limit) {
-    let active = 0;
-    const waiting = [];
-    return async (run) => {
-        if (active < limit)
-            active++;
-        else
-            await new Promise((resume) => waiting.push(resume));
-        try {
-            return await run();
-        }
-        finally {
-            const next = waiting.shift();
-            if (next)
-                next();
-            else
-                active--;
-        }
-    };
+export function authorizingContext(ctx) {
+    return attachOAuthPartition(inheritOAuthSealer(ctx, {
+        ...ctx,
+        requestScope: ctx.requestScope ?? ctx,
+        allowAuthorization: true,
+    }), oauthPartitionFor(ctx));
 }
 /**
- * The first rejection in input order, as `{ reason }`. The wrapper matters: a
- * store may reject with `undefined` or another falsy value, and that is still
- * a failed delete.
+ * A callback whose consent another callback already claimed: fixed text, and
+ * nothing was sent. Its own class so the callback route can answer it as the
+ * already-used link it is, not as an exchange the provider refused.
  */
-function firstRejection(results) {
-    for (const result of results) {
-        if (result.status === "rejected")
-            return { reason: result.reason };
-    }
-    return undefined;
-}
-function isRefreshTokenRequest(init) {
-    if ((init?.method ?? "GET").toUpperCase() !== "POST")
-        return false;
-    const body = init?.body;
-    if (body instanceof URLSearchParams) {
-        return body.get("grant_type") === "refresh_token";
-    }
-    if (typeof body !== "string")
-        return false;
-    return new URLSearchParams(body).get("grant_type") === "refresh_token";
-}
-function sdkAcceptsOAuthTokens(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const candidate = value;
-    if (typeof candidate.access_token !== "string" ||
-        typeof candidate.token_type !== "string") {
-        return false;
-    }
-    for (const key of ["id_token", "scope", "refresh_token"]) {
-        if (candidate[key] !== undefined && typeof candidate[key] !== "string") {
-            return false;
-        }
-    }
-    if (candidate.expires_in !== undefined) {
-        try {
-            if (!Number.isFinite(Number(candidate.expires_in)))
-                return false;
-        }
-        catch {
-            return false;
-        }
-    }
-    return true;
-}
-const MAX_REFRESH_RESPONSE_BYTES = 65_536;
-class OversizedRefreshResponse extends Error {
-    constructor() {
-        super(`OAuth refresh response exceeded ${MAX_REFRESH_RESPONSE_BYTES} bytes.`);
-    }
-}
-async function readRefreshResponse(response) {
-    if (Number(response.headers.get("content-length")) > MAX_REFRESH_RESPONSE_BYTES) {
-        void response.body?.cancel().catch(() => { });
-        throw new OversizedRefreshResponse();
-    }
-    const reader = response.clone().body?.getReader();
-    if (!reader)
-        return undefined;
-    const decoder = new TextDecoder();
-    let size = 0;
-    let text = "";
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            size += value.byteLength;
-            if (size > MAX_REFRESH_RESPONSE_BYTES) {
-                // A cloned body's cancellation can await its sibling. Cancel both,
-                // without making the refusal wait for the provider to finish sending.
-                void reader.cancel().catch(() => { });
-                void response.body?.cancel().catch(() => { });
-                throw new OversizedRefreshResponse();
-            }
-            text += decoder.decode(value, { stream: true });
-        }
-        return JSON.parse(text + decoder.decode());
-    }
-    finally {
-        reader.releaseLock();
+export class OAuthCallbackClaimedError extends ConnectorCallError {
+    constructor(connectorId) {
+        super("connector_call_failed", `Connector "${connectorId}" authorization callback was already used by another request; nothing was exchanged.`);
+        this.name = "OAuthCallbackClaimedError";
     }
 }
-/** Client-error statuses that describe the moment, not the grant. */
-const TRANSIENT_CLIENT_STATUSES = new Set([408, 425, 429]);
-/**
- * OAuth `error` codes on which the SDK's own `auth()` drops state and starts
- * over. Handing the SDK one of these is how a dead grant reaches consent on an
- * explicit authorization, and `auth_required` on a passive call.
- */
-const SDK_RESTARTING_CODES = new Set([
-    "invalid_grant",
-    "invalid_client",
-    "unauthorized_client",
-]);
-function oauthErrorCode(body) {
-    if (!body || typeof body !== "object" || Array.isArray(body))
-        return undefined;
-    const code = body.error;
-    return typeof code === "string" ? code : undefined;
+/** A local destination guard proved that no OAuth HTTP request left. */
+export class OAuthRequestNotSentError extends ConnectorCallError {
 }
-function transientFailure(reason, response, cause) {
-    const wait = response ? retryAfterMs(response.headers) : undefined;
-    return {
-        kind: "transient",
-        reason,
-        ...(response ? { status: response.status } : {}),
-        ...(wait !== undefined ? { retryAfterMs: wait } : {}),
-        ...(cause !== undefined ? { cause } : {}),
-    };
+/** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
+function randomState() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
-/** What the SDK sees for a refused grant it would otherwise misread. */
-function refusedGrantResponse(original) {
-    void original.body?.cancel().catch(() => { });
-    return Response.json({
-        error: "invalid_grant",
-        error_description: "The authorization server refused the refresh token.",
-    }, { status: 400 });
+/** 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("");
 }
-/** What the SDK sees for an outage whose body names a restarting code. */
-function outageResponse(original) {
-    void original.body?.cancel().catch(() => { });
-    const retryAfter = original.headers.get("retry-after");
-    return Response.json({
-        error: "server_error",
-        error_description: "The authorization server is temporarily unavailable.",
-    }, {
-        status: original.status,
-        ...(retryAfter !== null ? { headers: { "retry-after": retryAfter } } : {}),
-    });
+function storedRefreshSpent(raw) {
+    const value = raw === null ? undefined : parsed(raw);
+    return plainObject(value) &&
+        value.connectaOAuthRefreshSpent === 1 &&
+        typeof value.epoch === "string" &&
+        typeof value.holder === "string" &&
+        typeof value.activeKey === "string" &&
+        (value.state === "outstanding" ||
+            value.state === "ambiguous" ||
+            (value.state === "resolved" && typeof value.resolvedAt === "number" && Number.isFinite(value.resolvedAt)))
+        ? value
+        : undefined;
 }
-/**
- * Classify the token endpoint's answer once, on a clone, and keep the parsed
- * tokens: a valid response has already consumed the rotating refresh token, so
- * the host persists it (`coordinatedFetch`) rather than trusting the SDK's
- * later `saveTokens` to arrive on a request that may already be cancelled.
- *
- * A failure also decides what the SDK gets to parse. Pinned against
- * `@modelcontextprotocol/client` 2.0.0, `dist/index.mjs`: `authInternal()`
- * swallows a refresh failure that is not an `OAuthError`, or is `server_error`,
- * and falls through to `startAuthorization` (`state()`, `saveCodeVerifier()`,
- * `redirectToAuthorization()`); it rethrows every other `OAuthError`, and
- * `auth()` retries once after `invalidateCredentials()` only for
- * `invalid_grant` (tokens) and `invalid_client`/`unauthorized_client` (client
- * and tokens). `executeTokenRequest()` turns a 2xx body carrying `error` into
- * an `OAuthError` with that code. So a dead grant the SDK would rethrow
- * (`bad_refresh_token`, `invalid_scope`, …) reaches it as `invalid_grant`, and
- * an outage whose body names any code but `server_error` reaches it as
- * `server_error` — a 5xx `invalid_grant` must not make the SDK drop a grant
- * nobody refused. The provider hooks below finish the job. If the SDK moves,
- * the tests under "remoteMcp() dead and transient refresh grants" fail first.
- */
-async function refreshResponseOutcome(response) {
-    if (!response.ok) {
-        let code;
-        try {
-            code = oauthErrorCode(await readRefreshResponse(response));
-        }
-        catch {
-            // Not JSON, or too large to be an OAuth error: the status decides.
-        }
-        const failure = new Error(`OAuth refresh failed with HTTP ${response.status}.`);
-        if (response.status >= 400 &&
-            response.status < 500 &&
-            !TRANSIENT_CLIENT_STATUSES.has(response.status)) {
-            return {
-                failure,
-                verdict: { kind: "dead" },
-                forSdk: code !== undefined && SDK_RESTARTING_CODES.has(code)
-                    ? response
-                    : refusedGrantResponse(response),
-            };
-        }
-        return {
-            failure,
-            verdict: transientFailure(`answered HTTP ${response.status}`, response),
-            forSdk: code !== undefined && code !== "server_error"
-                ? outageResponse(response)
-                : response,
-        };
-    }
-    let parsed;
-    try {
-        parsed = await readRefreshResponse(response);
-    }
-    catch (error) {
-        if (error instanceof OversizedRefreshResponse)
-            throw error;
-        return {
-            failure: new Error("OAuth refresh response did not contain JSON tokens."),
-            verdict: transientFailure("answered without a token response", response),
-            forSdk: response,
-        };
-    }
-    if (sdkAcceptsOAuthTokens(parsed))
-        return { tokens: parsed };
-    if (oauthErrorCode(parsed) !== undefined) {
-        return {
-            failure: new Error("OAuth refresh was refused by the authorization server."),
-            verdict: { kind: "dead" },
-            forSdk: refusedGrantResponse(response),
-        };
-    }
+const REFRESH_REQUEST_DEADLINE_MS = 20_000;
+const REFRESH_WAIT_DEADLINE_MS = 35_000;
+function refreshWait(signal) {
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), REFRESH_WAIT_DEADLINE_MS);
+    let closed = false;
+    const abort = () => deadline.abort(aborted(signal));
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted)
+        abort();
     return {
-        failure: new Error("OAuth refresh response did not match the token schema."),
-        verdict: transientFailure("answered without a token response", response),
-        forSdk: response,
+        signal: deadline.signal,
+        run: (operation) => runEdge(Effect.raceAllFirst([
+            fromSignal(deadline.signal),
+            Effect.tryPromise({ try: operation, catch: (error) => error }),
+        ])),
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        },
     };
 }
-function refreshMutationPendingResponse() {
-    return Response.json({
-        error: "temporarily_unavailable",
-        error_description: "OAuth refresh is temporarily unavailable while previous credentials commit.",
-    }, { status: 503 });
-}
 function aborted(signal) {
-    return (signal?.reason ?? new DOMException("This operation was aborted", "AbortError"));
-}
-/**
- * Call `onAbort` once when `signal` aborts, at once if it already has, until
- * the returned function stops watching. The owner's abort needs a listener
- * rather than an interrupt once the SDK holds the answer: the SDK saves the
- * tokens after `coordinatedFetch` has returned, when no fiber of the owner's
- * is left to interrupt.
- */
-function whenAborted(signal, onAbort) {
-    let watching = true;
-    const stop = () => {
-        if (!watching)
-            return;
-        watching = false;
-        signal.removeEventListener("abort", listener);
-    };
-    const listener = () => {
-        stop();
-        onAbort();
-    };
-    signal.addEventListener("abort", listener, { once: true });
-    if (signal.aborted)
-        listener();
-    return stop;
+    return signal?.reason ?? new DOMException("This operation was aborted", "AbortError");
 }
 /**
  * The outcome of a flight another request owns, failures included. Rejects
@@ -404,106 +108,74 @@ function whenAborted(signal, onAbort) {
  * instead hands the rest of its work back to its own request, as workerd does
  * for any promise resolved from another one.
  */
-function waitForRefreshFlight(flight, signal) {
+function waitForRefreshFlight(flight, signal, deadline) {
     const settled = Deferred.await(flight.outcome);
     // The abort goes first, so a caller that has already left never joins.
-    return runEdge(signal
-        ? Effect.raceAllFirst([
-            fromSignal(signal),
-            settled,
-        ])
-        : settled);
+    return runEdge(Effect.raceAllFirst([
+        ...(signal ? [fromSignal(signal)] : []),
+        ...(deadline ? [fromSignal(deadline)] : []),
+        settled,
+    ]));
+}
+/** Tokens as a token response the SDK parses: only the client stamps an issuer. */
+function tokenResponse(tokens) {
+    const { issuer: _issuer, ...answer } = tokens;
+    return Response.json(answer);
+}
+function refreshTokensDigest(tokens) {
+    const { issuer: _issuer, ...answer } = tokens;
+    return oauthStateDigest(JSON.stringify(Object.fromEntries(Object.entries(answer).sort(([a], [b]) => a.localeCompare(b)))));
+}
+function requestedRefreshToken(init) {
+    return init?.body instanceof URLSearchParams
+        ? init.body.get("refresh_token")
+        : new URLSearchParams(String(init?.body ?? "")).get("refresh_token");
 }
 /**
- * Share one rotating-token redemption within one connector runtime and OAuth
- * generation. The first request still owns the real fetch and response, and
- * its abort ends the flight at any point until the flight settles: first by
- * interrupting the redemption, then, once the SDK holds the answer, through
- * one bounded listener, so a cancellation cannot strand waiters during token
- * storage. Followers wait on the flight's Deferred for that provider to save
- * tokens, then re-read storage. The map never retains a token response or
- * transport.
+ * The token endpoint as one connector runtime's OAuth flows reach it.
  *
- * This is intentionally runtime-local. KVStorage has no atomic coordination
- * operation, so a second isolate can still race the same refresh token.
+ * A refresh is redeemed once per owner partition and epoch: the first request
+ * owns the fetch, classifies the answer, and stores an accepted rotation, by
+ * compare-and-set, before anyone is released, so a cancelled owner or an SDK
+ * that redirects instead of saving cannot strand a spent refresh token.
+ * Requests that arrive meanwhile join its outcome; a request whose token read
+ * predates a stored refresh is handed that refresh instead of redeeming again.
+ * A shared-storage lease prevents concurrent redemption across isolates;
+ * the grant CAS also fences stale rotations.
+ *
+ * A code exchange claims its consent's flow record and re-checks the epoch in
+ * the turn that dispatches it (`KvOAuthProvider.claimCodeExchange`,
+ * `dispatchCodeExchange`). Every token answer the SDK parses is rebuilt from
+ * the OAuth `error` code alone unless it is a token response.
  */
 export class OAuthRefreshCoordinator {
     retainPartition;
+    flights = new Map();
     constructor(retainPartition = () => () => { }) {
         this.retainPartition = retainPartition;
     }
-    /** Keep an accepted credential write alive independently of its caller. */
-    retainWork() {
-        return this.retainPartition();
-    }
-    releaseFlightPartition(flight) {
-        if (flight.settled && !flight.answerPending && !flight.recoveryPending) {
-            flight.releasePartition();
-        }
-    }
-    flights = new Map();
-    /** Opaque identities only: no request promise, signal, callback, or response. */
-    pendingMutations = new Map();
-    /** One bounded latest-success slot, containing only generation + identity. */
-    successfulRefresh;
-    /** Replaced on every map mutation, closing flight/pending ABA across awaits. */
-    stateRevision = {};
-    advanceStateRevision() {
-        this.stateRevision = {};
-    }
-    observeAuthoritativeGeneration(generation) {
-        const staleGenerations = new Set([
-            ...this.flights.keys(),
-            ...this.pendingMutations.keys(),
-        ]);
-        for (const stale of staleGenerations) {
-            if (stale !== generation)
-                this.retire(stale);
-        }
-        if (this.successfulRefresh &&
-            this.successfulRefresh.generation !== generation) {
-            this.successfulRefresh = undefined;
-            this.advanceStateRevision();
-        }
-    }
-    settle(generation, flight, outcome) {
-        if (this.flights.get(generation) !== flight)
-            return;
-        this.flights.delete(generation);
-        flight.settled = true;
-        this.advanceStateRevision();
-        flight.stopObservingOwnerAbort();
-        this.releaseFlightPartition(flight);
-        // Last, because joined fibers resume inside this call.
-        Deferred.doneUnsafe(flight.outcome, Effect.succeed(outcome));
-    }
-    markMutationPending(generation, flight) {
-        if (this.flights.get(generation) !== flight)
-            return false;
-        this.pendingMutations.set(generation, flight.mutationId);
-        this.advanceStateRevision();
-        return true;
-    }
-    finishMutation(generation, flight) {
-        if (this.pendingMutations.get(generation) === flight.mutationId) {
-            this.pendingMutations.delete(generation);
-            this.advanceStateRevision();
-            return true;
-        }
-        return false;
-    }
-    /** @internal Opaque basis for issuer-aware provider token reads. */
-    successfulRefreshIdentity(generation) {
-        return this.successfulRefresh?.generation === generation
-            ? this.successfulRefresh.identity
-            : undefined;
-    }
-    coordinatedFetch(provider, baseFetch, requestSignal) {
+    coordinatedFetch(provider, baseFetch, requestSignal, defer, resourceFetch = baseFetch) {
         return async (input, init) => {
-            // Await passthrough failures here so workerd associates the rejection
-            // with the fetch the SDK is already awaiting, rather than reporting the
-            // adopted inner promise as an unhandled rejection.
-            if (!isRefreshTokenRequest(init)) {
+            // Freeze the form before any await: classification and the spent digest
+            // must describe the exact token sent, even if its caller mutates a form.
+            init = init
+                ? { ...init, ...(init.body instanceof URLSearchParams ? { body: new URLSearchParams(init.body) } : {}) }
+                : undefined;
+            if (isRefreshTokenRequest(init)) {
+                const signal = requestSignal && init?.signal
+                    ? AbortSignal.any([requestSignal, init.signal])
+                    : (requestSignal ?? init?.signal ?? undefined);
+                return this.refresh(provider, input, init, baseFetch, signal, defer);
+            }
+            const grantType = tokenGrantType(init);
+            const tokenRequest = isOAuthCredentialRequest(init);
+            const exchange = grantType === "authorization_code";
+            if (exchange) {
+                const answered = await provider.claimCodeExchange();
+                if (answered)
+                    return answered;
+            }
+            const dispatch = () => {
                 if (requestSignal?.aborted)
                     throw aborted(requestSignal);
                 const signal = requestSignal
@@ -511,370 +183,365 @@ export class OAuthRefreshCoordinator {
                         ? AbortSignal.any([requestSignal, init.signal])
                         : requestSignal
                     : init?.signal;
-                return await baseFetch(input, { ...init, ...(signal ? { signal } : {}) });
-            }
+                // Credential-bearing OAuth requests use the raw send path. A redirect
+                // is a dispatched failure, never authority to send the form again.
+                return tokenRequest
+                    ? baseFetch(input, { ...init, redirect: "manual", ...(signal ? { signal } : {}) })
+                    : resourceFetch(input, { ...init, ...(signal ? { signal } : {}) });
+            };
+            // Awaited here so workerd associates a rejection with the fetch the SDK
+            // is already awaiting, not with an adopted inner promise.
+            const response = await (exchange ? provider.dispatchCodeExchange(dispatch, input) : dispatch());
+            if (!tokenRequest)
+                return response;
+            // A code exchange's failure is the SDK's to log as well.
+            const forSdk = await sdkSafeTokenResponse(response, exchange ? (tokens) => provider.recordCodeExchangeTokens(tokens) : undefined);
+            if (exchange && forSdk !== response)
+                provider.recordCodeExchangeRefusal(forSdk);
+            return forSdk;
+        };
+    }
+    async refresh(provider, input, init, baseFetch, signal, defer) {
+        const waiting = refreshWait(signal);
+        try {
             // A verdict belongs to one refresh; never let an older one decide this.
             provider.recordRefreshFailure(undefined);
-            const generation = await provider.flowGeneration();
-            const requestedRefreshToken = init?.body instanceof URLSearchParams
-                ? init.body.get("refresh_token")
-                : new URLSearchParams(String(init?.body ?? "")).get("refresh_token");
-            for (let attempt = 0; attempt < 64; attempt++) {
-                if (requestSignal?.aborted)
-                    throw aborted(requestSignal);
-                const revisionBeforeReads = this.stateRevision;
-                const activeGeneration = await provider.generation();
-                this.observeAuthoritativeGeneration(activeGeneration);
-                if (activeGeneration !== generation)
-                    this.retire(generation);
-                const activeFlight = this.flights.get(generation);
-                const pendingMutation = this.pendingMutations.get(generation);
-                if (activeGeneration === generation &&
-                    pendingMutation &&
-                    activeFlight?.mutationId !== pendingMutation) {
-                    return refreshMutationPendingResponse();
-                }
-                let currentTokens = activeGeneration === generation ? await provider.tokens() : undefined;
-                const latestGeneration = await provider.generation();
-                this.observeAuthoritativeGeneration(latestGeneration);
-                if (latestGeneration !== generation) {
-                    this.retire(generation);
-                    currentTokens = undefined;
-                }
-                if (this.stateRevision !== revisionBeforeReads)
-                    continue;
-                // Re-check both identities after every storage await. An owner can
-                // abort while this caller reads tokens, leaving only the mutation
-                // marker; a reset can likewise retire this caller's captured epoch.
-                const existing = this.flights.get(generation);
-                const latestPendingMutation = this.pendingMutations.get(generation);
-                if (latestGeneration === generation &&
-                    latestPendingMutation &&
-                    existing?.mutationId !== latestPendingMutation) {
-                    return refreshMutationPendingResponse();
-                }
-                // This flow may have read a token just before another flow saved its
-                // rotation. Replaying the retired token would recreate the race after
-                // the first network response. Give the SDK the already-saved rotating
-                // credential instead. A tokenless current value cannot do that: the
-                // SDK would merge the requested old refresh token back into it.
-                if (currentTokens?.refresh_token &&
-                    (currentTokens.refresh_token !== requestedRefreshToken ||
-                        provider.refreshBasisChanged(currentTokens, generation))) {
-                    return Response.json(currentTokens);
-                }
-                if (currentTokens?.refresh_token !== requestedRefreshToken) {
-                    return Response.json({
-                        error: "invalid_grant",
-                        error_description: "Refresh token is no longer active.",
-                    }, { status: 400 });
-                }
-                if (existing) {
-                    const outcome = await waitForRefreshFlight(existing, requestSignal);
+            const epoch = await waiting.run(() => provider.flowEpoch());
+            const requested = requestedRefreshToken(init);
+            for (let attempt = 0; attempt < 8; attempt++) {
+                if (signal?.aborted)
+                    throw aborted(signal);
+                const joined = this.flights.get(epoch);
+                if (joined) {
+                    const outcome = await waitForRefreshFlight(joined, signal, waiting.signal);
                     if (outcome.status === "failed") {
-                        // A joined caller inherits the owner's verdict, so every scope on
-                        // one flight ends the same way: auth_required or a retryable outage.
                         provider.recordRefreshFailure(outcome.verdict);
                         throw outcome.error;
                     }
-                    if (outcome.status === "refreshed") {
-                        const activeGeneration = await provider.generation();
-                        const refreshedTokens = activeGeneration === generation
-                            ? await provider.tokens()
-                            : undefined;
-                        if (refreshedTokens?.refresh_token) {
-                            return Response.json(refreshedTokens);
-                        }
-                    }
+                    if (outcome.status === "refreshed")
+                        return provider.adoptRefresh(outcome.tokens);
                     continue;
                 }
-                // An owner that has already left never publishes a flight, and never
-                // reaches the token endpoint.
-                if (requestSignal?.aborted)
-                    throw aborted(requestSignal);
-                const flight = {
-                    outcome: Deferred.makeUnsafe(),
-                    stopObservingOwnerAbort: () => { },
-                    mutationId: {},
-                    writing: false,
-                    answerPending: true,
-                    recoveryPending: false,
-                    settled: false,
-                    releasePartition: this.retainWork(),
-                    persist: (tokens) => provider.saveAcceptedRefreshTokens(tokens, generation, flight),
-                };
-                this.flights.set(generation, flight);
-                this.advanceStateRevision();
-                provider.captureRefreshFlight(generation, flight);
-                const currentRefreshToken = currentTokens?.refresh_token;
-                // The token request starts now, as a plain promise: an owner that
-                // stops waiting for its answer can still hand the answer on.
-                const answer = (async () => {
-                    const response = await baseFetch(input, requestSignal ? { ...init, signal: requestSignal } : init);
-                    return { response, outcome: await refreshResponseOutcome(response) };
-                })();
-                // Record what the token endpoint said, then settle the flight or
-                // hand it to the SDK's saveTokens.
-                const commit = ({ response, outcome, }) => {
-                    if (outcome.failure) {
-                        // Failed responses never reach a successful saveTokens callback.
-                        // Give current waiters a bounded failure now, carrying the
-                        // verdict, and hand the SDK an answer it classifies the same way.
-                        provider.recordRefreshFailure(outcome.verdict);
-                        // Drop a refused grant while the flight still stands: a caller
-                        // arriving meanwhile joins it instead of redeeming the dead token
-                        // again, and no later request or isolate can replay it.
-                        const discard = outcome.verdict.kind === "dead"
-                            ? Effect.promise(() => provider.discardRefusedGrant(requestedRefreshToken, generation))
-                            : Effect.void;
-                        return discard.pipe(Effect.map(() => {
-                            this.fail(generation, flight, outcome.failure, outcome.verdict);
-                            return outcome.forSdk;
-                        }));
-                    }
-                    // A valid response means the authorization server has consumed the
-                    // rotating refresh token. The SDK's saveTokens normally persists it;
-                    // keep this copy so `fail` can persist it instead if that callback
-                    // never comes (the SDK merges the old refresh token the same way).
-                    const rotatedRefreshToken = outcome.tokens.refresh_token ?? currentRefreshToken;
-                    const accepted = {
-                        ...outcome.tokens,
-                        ...(rotatedRefreshToken !== undefined
-                            ? { refresh_token: rotatedRefreshToken }
-                            : {}),
-                    };
-                    flight.acceptedTokens = accepted;
-                    if (!this.markMutationPending(generation, flight)) {
-                        // Already settled (the owner was cancelled first). Still write the
-                        // rotation: losing it would leave a dead credential.
-                        flight.recoveryPending = true;
-                        detach(Effect.promise(() => flight.persist(accepted)).pipe(Effect.ensuring(Effect.sync(() => {
-                            flight.recoveryPending = false;
-                            this.releaseFlightPartition(flight);
-                        }))));
-                        return Effect.fail(new Error("OAuth refresh ended before tokens could be saved."));
-                    }
-                    // The SDK holds the answer from here, after this fiber is gone, so
-                    // a listener watches for the owner leaving before it saves. Then
-                    // `fail` persists the rotation instead.
-                    if (requestSignal) {
-                        flight.stopObservingOwnerAbort = whenAborted(requestSignal, () => this.fail(generation, flight, aborted(requestSignal)));
-                    }
-                    return Effect.succeed(response);
-                };
-                const finishAnswer = Effect.sync(() => {
-                    flight.answerPending = false;
-                    this.releaseFlightPartition(flight);
-                });
-                const commitAnswer = (value) => commit(value).pipe(Effect.ensuring(finishAnswer));
-                // The owner's redemption. Its abort interrupts the wait for the token
-                // endpoint and nothing after it: an answer, once it exists, is
-                // committed before anyone is released, so no caller is let go to
-                // redeem a token the server has already refused or spent. An answer
-                // that arrives after the owner left is committed in the background,
-                // as the foreground would have.
-                const redemption = Effect.uninterruptibleMask((restore) => restore(Effect.tryPromise({ try: () => answer, catch: (error) => error })).pipe(Effect.onInterrupt(() => Effect.sync(() => {
-                    this.fail(generation, flight, aborted(requestSignal));
-                    detach(Effect.promise(() => answer).pipe(Effect.flatMap(commitAnswer), Effect.ensuring(finishAnswer)));
-                })), Effect.catch((error) => {
-                    // No answer at all — the network, or a body too large to be
-                    // one — is an outage. A refusal connecta itself raised (a
-                    // redirect the policy forbids) and this owner's own
-                    // cancellation are not.
-                    const verdict = !requestSignal?.aborted &&
-                        !(error instanceof ConnectorCallError && !error.retryable)
-                        ? transientFailure(error instanceof OversizedRefreshResponse
-                            ? "answered with an oversized response"
-                            : "could not be reached", undefined, error)
-                        : undefined;
-                    if (verdict)
-                        provider.recordRefreshFailure(verdict);
-                    flight.answerPending = false;
-                    this.fail(generation, flight, error, verdict);
-                    // Retirement may already have removed the flight from the map.
-                    // Its rejected answer still finishes the retained partition work.
-                    this.releaseFlightPartition(flight);
-                    return Effect.fail(error);
-                }), Effect.flatMap(commitAnswer)));
-                return await runEdge(requestSignal
-                    ? Effect.raceAllFirst([
-                        redemption,
-                        fromSignal(requestSignal),
-                    ])
-                    : redemption);
+                // Preparation reads share the same bound as later claim waits.
+                const current = await waiting.run(() => provider.storedTokens());
+                if (this.flights.has(epoch))
+                    continue;
+                if (current?.refresh_token &&
+                    (current.refresh_token !== requested || provider.refreshedSinceRead(current, epoch))) {
+                    return provider.adoptRefresh(current);
+                }
+                if (current?.refresh_token !== requested) {
+                    provider.recordRefreshFailure({ kind: "dead" });
+                    return Response.json({ error: "invalid_grant", error_description: "Refresh token is no longer active." }, { status: 400 });
+                }
+                const redemption = this.redeem(provider, epoch, requested, input, init, baseFetch, signal, waiting);
+                // The refresh owns its completion after dispatch, including storage.
+                // Attach it before yielding so a cancelled Worker keeps that work alive.
+                try {
+                    detach(Effect.promise(() => redemption), defer ? { waitUntil: defer } : undefined);
+                }
+                catch {
+                    // A missing or refusing runtime hook still leaves the promise running.
+                }
+                if (!signal)
+                    return await redemption;
+                return await runEdge(Effect.raceAllFirst([
+                    Effect.tryPromise({ try: () => redemption, catch: (error) => error }),
+                    fromSignal(signal),
+                ]));
             }
-            return refreshMutationPendingResponse();
-        };
-    }
-    /** Start storage only while this owner still holds its exact flight. */
-    beginMutation(generation, flight) {
-        if (this.flights.get(generation) !== flight)
-            return false;
-        flight.writing = true;
-        return true;
-    }
-    /** Publish one exact owner's successful save without disturbing a newer try. */
-    succeedMutation(generation, flight) {
-        if (this.finishMutation(generation, flight)) {
-            this.successfulRefresh = { generation, identity: {} };
-            this.advanceStateRevision();
+            throw provider.refreshContended();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw aborted(signal);
+            if (waiting.signal.aborted)
+                throw provider.refreshContended();
+            throw error;
+        }
+        finally {
+            waiting.close();
         }
-        this.settle(generation, flight, { status: "refreshed" });
     }
-    /**
-     * Give joined callers a fetch/flow failure, without rejecting the gate. A
-     * `verdict` travels with it only when the token endpoint decided the
-     * failure; an abort or a write failure carries none.
-     */
-    fail(generation, flight, error, verdict) {
-        // Only saveTokens owns a live credential write. If it has started, its
-        // success/failure callback clears the marker even after owner cancellation.
-        if (flight.writing) {
-            this.settle(generation, flight, { status: "failed", error });
-            return;
+    async redeem(provider, epoch, requested, input, init, baseFetch, signal, waiting) {
+        const flight = { outcome: Deferred.makeUnsafe() };
+        this.flights.set(epoch, flight);
+        // Pin the owner partition until the flight settles, whoever is waiting.
+        const release = this.retainPartition();
+        const settle = (outcome) => {
+            if (this.flights.get(epoch) === flight)
+                this.flights.delete(epoch);
+            release();
+            // Last, because joined fibers resume inside this call.
+            Deferred.doneUnsafe(flight.outcome, Effect.succeed(outcome));
+        };
+        const fail = (error, verdict) => {
+            if (verdict)
+                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 = await provider.claimRefresh(epoch, requested, signal, waiting);
+            if (claim instanceof Response) {
+                const tokens = await waiting.run(() => provider.storedTokens());
+                if (tokens)
+                    settle({ status: "refreshed", tokens });
+                else
+                    settle({ status: "retired" });
+                return claim;
+            }
+            lease = claim;
+        }
+        catch (error) {
+            fail(error, provider.refreshVerdict());
+            throw error;
         }
-        // The token endpoint already answered with valid tokens but the SDK will
-        // not save them (the owner was cancelled, redirected, or invalidated).
-        // The old refresh token is spent, so the host persists the rotation
-        // itself and keeps contenders behind the marker until it lands. Joined
-        // callers then receive the saved rotation, never a retired token to
-        // redeem again. saveTokens' own bookkeeping settles the flight when the
-        // provider still holds it; otherwise settle here once the write ends.
-        const tokens = flight.acceptedTokens;
-        if (tokens !== undefined &&
-            this.pendingMutations.get(generation) === flight.mutationId) {
-            flight.writing = true;
-            flight.recoveryPending = true;
-            const written = (outcome) => {
-                if (this.finishMutation(generation, flight)) {
-                    this.settle(generation, flight, outcome);
+        const releaseLease = async (verdict, resolution = "ambiguous") => {
+            await provider.releaseRefresh(lease, verdict, undefined, resolution);
+        };
+        let outcome;
+        const deadline = new AbortController();
+        let dispatched = false;
+        let timer;
+        try {
+            const read = provider
+                .dispatchRefresh(lease, () => {
+                if (signal?.aborted)
+                    throw aborted(signal);
+                if (init?.signal?.aborted)
+                    throw aborted(init.signal);
+                dispatched = true;
+                // Preparation remains bounded through the send transition. After
+                // dispatch, caller cancellation must not prevent an answer's commit.
+                waiting.close();
+                // Start the deadline at dispatch, including the response body read.
+                timer = setTimeout(() => {
+                    deadline.abort(new DOMException("OAuth refresh timed out", "TimeoutError"));
+                }, REFRESH_REQUEST_DEADLINE_MS);
+                return baseFetch(input, { ...init, redirect: "manual", signal: deadline.signal });
+            }, waiting)
+                .then((response) => {
+                if (deadline.signal.aborted) {
+                    void response.body?.cancel().catch(() => { });
+                    throw aborted(deadline.signal);
                 }
-            };
-            detach(Effect.tryPromise({
-                try: () => flight.persist(tokens),
-                catch: (writeError) => writeError,
-            }).pipe(Effect.match({
-                onSuccess: () => written({ status: "refreshed" }),
-                onFailure: (error) => written({ status: "failed", error }),
-            }), Effect.ensuring(Effect.sync(() => {
-                flight.recoveryPending = false;
-                this.releaseFlightPartition(flight);
-            }))));
-            return;
+                return refreshResponseOutcome(response, deadline.signal);
+            });
+            // The deadline can settle the race before a late fetch/body rejects.
+            void read.catch(() => { });
+            outcome = await runEdge(Effect.raceAllFirst([
+                Effect.tryPromise({ try: () => read, catch: (error) => error }),
+                fromSignal(deadline.signal),
+            ]));
+            if (deadline.signal.aborted)
+                throw aborted(deadline.signal);
         }
-        // A response alone is not a write and must never strand the generation.
-        this.finishMutation(generation, flight);
-        this.settle(generation, flight, {
-            status: "failed",
-            error,
-            ...(verdict !== undefined ? { verdict } : {}),
-        });
-    }
-    /** Finish an exact failed credential write, then publish its failure. */
-    failMutation(generation, flight, error) {
-        this.finishMutation(generation, flight);
-        this.settle(generation, flight, { status: "failed", error });
-    }
-    /** Force reauthorization fences and wakes every waiter on the retired epoch. */
-    retire(generation) {
-        if (this.pendingMutations.delete(generation)) {
-            this.advanceStateRevision();
+        catch (error) {
+            if (!dispatched) {
+                // A cancelled or timed-out unsent holder leaves a safely expiring
+                // claim. Cleanup must not retain its local flight or partition pin.
+                if (!waiting.signal.aborted && !signal?.aborted && !init?.signal?.aborted) {
+                    await waiting.run(() => releaseLease()).catch(() => { });
+                    if (provider.refreshVerdict()?.kind === "dead") {
+                        await waiting.run(() => provider.discardRefusedGrant(requested, epoch)).catch(() => { });
+                    }
+                }
+                const failure = !signal?.aborted && waiting.signal.aborted ? provider.refreshContended() : error;
+                fail(failure, provider.refreshVerdict());
+                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.");
+            await releaseLease({ kind: "dead" });
+            await provider.discardRefusedGrant(requested, epoch);
+            fail(failure, { kind: "dead" });
+            throw failure;
         }
-        if (this.successfulRefresh?.generation === generation) {
-            this.successfulRefresh = undefined;
-            this.advanceStateRevision();
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        // 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.
+            await provider.discardRefusedGrant(requested, epoch);
+            await 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 = await provider.storeRefresh(epoch, requested, accepted, issuer);
+        }
+        catch {
+            const failure = new UnauthorizedError("OAuth refresh could not be committed; authorization required.");
+            await releaseLease({ kind: "dead" }, "resolved");
+            await provider.discardRefusedGrant(requested, epoch);
+            fail(failure, { kind: "dead" });
+            throw failure;
+        }
+        if (!committed) {
+            // Restart, Disconnect, or another consent decides the newer grant.
+            await releaseLease({ kind: "dead" }, "resolved");
+            const failure = new UnauthorizedError("OAuth refresh grant is no longer active.");
+            fail(failure, { kind: "dead" });
+            throw failure;
         }
-        const flight = this.flights.get(generation);
+        await provider.releaseRefresh(lease, undefined, committed, "resolved");
+        settle({ status: "refreshed", tokens: committed });
+        return provider.adoptRefresh(committed);
+    }
+    /** A reset fenced `epoch`: wake its joiners now rather than at the answer. */
+    retire(epoch) {
+        const flight = this.flights.get(epoch);
         if (!flight)
             return;
-        this.settle(generation, flight, { status: "retired" });
+        this.flights.delete(epoch);
+        Deferred.doneUnsafe(flight.outcome, Effect.succeed({ status: "retired" }));
     }
 }
-function storedOAuthValue(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const candidate = value;
-    return (candidate.connectaOAuthVersion === STORED_VALUE_VERSION &&
-        typeof candidate.generation === "string" &&
-        (candidate.issuer === undefined || typeof candidate.issuer === "string") &&
-        (candidate.binding === undefined || typeof candidate.binding === "string") &&
-        "value" in candidate);
-}
-function legacyStoredOAuthValue(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const candidate = value;
-    return (candidate.connectaOAuthVersion === 1 &&
-        typeof candidate.generation === "string" &&
-        "value" in candidate);
-}
-function sealedOAuthValue(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const candidate = value;
-    return (candidate.connectaOAuthSealed === SEALED_VALUE_VERSION &&
-        typeof candidate.sealed === "string");
-}
-function isModernGeneration(generation) {
-    return (generation.startsWith(ACTIVE_GENERATION_PREFIX) ||
-        generation.startsWith(RESETTING_GENERATION_PREFIX) ||
-        generation.startsWith(DISCONNECTED_GENERATION_PREFIX));
-}
 /**
- * Physical key for an OAuth value in one authorization epoch. Legacy values
- * keep their historical names so upgrades can read an existing grant. Modern
- * values get an epoch-specific namespace: a stale write or delete can then
- * affect only its own flow, even if it lands after a replacement flow.
+ * One refresh coordinator per owner partition, for one connector runtime.
+ * Long-lived enough for distinct request scopes to join one token redemption;
+ * it owns no client, transport, or request state. Production contexts carry a
+ * stable registry partition; hand-written contexts coordinate by their shared
+ * storage object instead.
  */
-export function oauthValueStorageKey(key, generation) {
-    return generation !== null && isModernGeneration(generation)
-        ? `${key}:epoch:${generation}`
-        : key;
-}
-function cleanupBacklogKey(generation) {
-    return `oauth:cleanup:${encodeURIComponent(generation)}`;
+export function refreshCoordinatorsByPartition() {
+    const coordinators = new WeakMap();
+    return (ctx) => {
+        const partition = oauthPartitionFor(ctx) ?? ctx.storage;
+        let coordinator = coordinators.get(partition);
+        if (!coordinator) {
+            coordinator = new OAuthRefreshCoordinator(() => retainOAuthPartition(partition));
+            coordinators.set(partition, coordinator);
+        }
+        return coordinator;
+    };
 }
+const GRANT = oauthGrantKeys.grant;
+/** The epoch of an owner with no grant record yet. */
+const INITIAL_EPOCH = "initial";
+/** The epoch of a record that does not parse: readers see no grant in it. */
+const UNREADABLE_EPOCH = "unreadable";
+const ACTIVE_EPOCH_PREFIX = "v3:";
+const DISCONNECTED_EPOCH_PREFIX = "disconnected:";
+const GRANT_VERSION = 3;
+const FLOW_VERSION = 1;
+/** Attempts at one grant write while other writers keep winning. */
+const MAX_GRANT_WRITES = 32;
 /**
- * Retirement times for a lineage, beside it rather than inside it: the
- * manifest stays the plain array of generation names every release reads, so
- * rolling back to one that predates the times still resets and cleans up.
- * Membership belongs to the manifest alone. A time with no manifest entry is
- * ignored, and an entry with no time reads as retired "now", so any
- * interleaving of the two keys errs toward a longer grace.
+ * How long a pending authorization URL may be handed out again instead of
+ * starting a fresh flow. The authorization server's half of it expires: a
+ * pushed request URI lives seconds to minutes (RFC 9126), and login
+ * transactions are commonly held for minutes. Past this age a reissued URL
+ * more likely lands on an expired session than on consent, and a fresh start
+ * costs one authorization request, not a registration. It sits inside the
+ * flow record's fifteen minutes.
  */
-function cleanupTimesKey(generation) {
-    return `oauth:cleanup-at:${encodeURIComponent(generation)}`;
+const PENDING_AUTHORIZATION_MAX_AGE_MS = 10 * 60 * 1000;
+async function discoveryBinding(state) {
+    return state
+        ? {
+            issuer: discoveryIssuer(state),
+            tokenEndpoint: state.authorizationServerMetadata?.token_endpoint,
+            ...(state.authorizationServerMetadata?.authorization_response_iss_parameter_supported === true
+                ? { issRequired: true }
+                : {}),
+            discovery: await oauthStateDigest(JSON.stringify(state)),
+        }
+        : {};
 }
-/** Parse a times record, reading anything malformed as "no times known". */
-function retirementTimes(raw) {
-    const times = new Map();
-    if (raw === null)
-        return times;
-    let parsed;
+function plainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parsed(raw) {
     try {
-        parsed = JSON.parse(raw);
+        return JSON.parse(raw);
     }
     catch {
-        return times;
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return times;
-    }
-    for (const [generation, retiredAt] of Object.entries(parsed)) {
-        if (typeof retiredAt === "number" && Number.isFinite(retiredAt)) {
-            times.set(generation, retiredAt);
-        }
+        return undefined;
     }
-    return times;
+}
+function storedGrant(raw) {
+    const value = parsed(raw);
+    return plainObject(value) &&
+        value.connectaOAuth === GRANT_VERSION &&
+        typeof value.epoch === "string" &&
+        (value.flow === undefined || typeof value.flow === "string") &&
+        (value.sealed === undefined || typeof value.sealed === "string")
+        ? value
+        : undefined;
+}
+/** The epoch a raw grant record names, without opening its body. */
+function epochOf(raw) {
+    if (raw === null)
+        return INITIAL_EPOCH;
+    return storedGrant(raw)?.epoch ?? UNREADABLE_EPOCH;
+}
+/** Nothing here trusts stored bytes: keep only what has the expected shape. */
+function grantBody(value) {
+    if (!plainObject(value))
+        return {};
+    const { issuer, client, tokens, discovery, refreshConsent } = value;
+    return {
+        ...(typeof issuer === "string" ? { issuer } : {}),
+        ...(plainObject(client) && plainObject(client.value) && typeof client.value.client_id === "string"
+            ? {
+                client: {
+                    value: client.value,
+                    ...(typeof client.binding === "string" ? { binding: client.binding } : {}),
+                    ...(client.carried === true ? { carried: true } : {}),
+                    ...(client.registrationPath === "cimd" ||
+                        client.registrationPath === "dcr" ||
+                        client.registrationPath === "static"
+                        ? { registrationPath: client.registrationPath }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(plainObject(tokens) && typeof tokens.access_token === "string"
+            ? { tokens: tokens }
+            : {}),
+        ...(discoveryIssuer(discovery) !== undefined ? { discovery: discovery } : {}),
+        ...(plainObject(refreshConsent) &&
+            typeof refreshConsent.digest === "string" &&
+            typeof refreshConsent.resolution === "string"
+            ? { refreshConsent: { digest: refreshConsent.digest, resolution: refreshConsent.resolution } }
+            : {}),
+    };
+}
+/** What an invalidation compares: the value exactly as this flow saw it. */
+function fingerprint(value) {
+    return value === undefined ? undefined : JSON.stringify(value);
+}
+function isDisconnectedEpoch(epoch) {
+    return epoch.startsWith(DISCONNECTED_EPOCH_PREFIX);
 }
 /**
- * OAuthClientProvider implemented over KVStorage for a single downstream
- * connector. Keys live in the connector's namespace as `oauth:<field>`.
+ * OAuthClientProvider over one owner's grant record and its consents' flow
+ * records, in one connector's namespace.
  *
- * Headless twist: redirectToAuthorization() cannot navigate a user agent, so it
- * STORES the authorization URL; the registry surfaces it as status
- * "auth_required" and the operator opens it. The /oauth/callback/<id> route then
- * drives transport.finishAuth(code).
+ * Headless: `redirectToAuthorization()` cannot navigate a user agent, so it
+ * stores the consent; the registry surfaces its URL, and the
+ * `/oauth/callback/<id>` route drives the exchange.
+ *
+ * A flow — a connect attempt, an `api()` call or start, or a callback — binds
+ * to one epoch. Its reads fail once another epoch is live, and its writes are
+ * compare-and-sets against the record it read, so a restart or disconnect,
+ * which replaces the epoch, fences every flow that began before it.
  */
 export class KvOAuthProvider {
     connectorId;
@@ -887,20 +554,40 @@ export class KvOAuthProvider {
     clientBinding;
     onReset;
     scope;
+    refreshNow;
+    clientOptions;
     clientMetadataUrl;
+    addClientAuthentication;
+    /** The epoch this provider's flow reads and writes in, once known. */
+    epoch;
+    /** Set when a flow binds: from then on a replaced epoch fails the flow. */
+    bound = false;
+    /** The consent being started, held until `redirectToAuthorization` stores it. */
+    consentDiscovery;
+    consent = {};
+    /** The consent this provider stored, for the start that asked for it. */
+    published;
+    /** The consent a matching `verifyState` found, which the exchange claims. */
+    callback;
+    /** Set by `bindFlow`: this provider exchanges a code. */
+    codeExchange = false;
+    /** The token endpoint's refusal of this exchange's code, for the SDK's retry. */
+    exchangeRefusal;
+    /** Resolution observed when the code answer completed, before the SDK saves. */
+    exchangeConsent;
     /**
-     * The reset generation this provider's flow started under. Every OAuth value
-     * it writes carries this epoch, so a late write can land after a reset without
-     * becoming readable under the new generation.
+     * The client and tokens as this flow last saw them. An invalidation removes
+     * only these, never a value another flow wrote meanwhile.
      */
-    capturedGeneration = null;
-    refreshFlight;
+    seen = {};
     /** How the last refresh this provider took part in failed, if it did. */
     refreshFailure;
-    /** Tokens this request's issuer-aware auth flow decided to refresh. */
+    /** The tokens this flow's issuer-aware read handed the SDK to refresh. */
     refreshBasis;
+    /** The access token of a refresh the coordinator already stored. */
+    storedRefresh;
     constructor(connectorId, storage, redirectUri, refreshCoordinator, allowAuthorization = true, 
-    /** Present when the deployment's vault can seal; credentials are then ciphertext. */
+    /** Present when the deployment's vault can seal; the grant is then ciphertext. */
     sealer, 
     /** Request ownership for a start; a timed-out SDK hook may still resume. */
     signal, 
@@ -909,7 +596,9 @@ export class KvOAuthProvider {
     /** Request-local observer so the operator route drains every reset it began. */
     onReset, 
     /** SDK uses this only when the authorization server advertises support. */
-    clientMetadataUrl, scope) {
+    clientMetadataUrl, scope, 
+    /** Isolate-local clock, used only for claims that have never been sent. */
+    refreshNow = Date.now, clientOptions) {
         this.connectorId = connectorId;
         this.storage = storage;
         this.redirectUri = redirectUri;
@@ -920,837 +609,1271 @@ export class KvOAuthProvider {
         this.clientBinding = clientBinding;
         this.onReset = onReset;
         this.scope = scope;
+        this.refreshNow = refreshNow;
+        this.clientOptions = clientOptions;
         if (clientMetadataUrl !== undefined)
             this.clientMetadataUrl = clientMetadataUrl;
+        const client = clientOptions?.client;
+        if (client)
+            this.addClientAuthentication = (headers, params) => authenticateRemoteClient(client, headers, params);
     }
-    /**
-     * Stamp the force-reauth generation the current connect flow started under.
-     * Called by the connector once per connect, before c.connect(). The callback
-     * path captures the generation stored beside its verified state instead.
-     */
-    captureGeneration(gen) {
-        this.capturedGeneration = gen;
-    }
-    /** The generation captured for this flow, before a concurrent reset. */
-    async flowGeneration() {
-        return this.capturedGeneration ?? this.generation();
-    }
-    /** @internal Record the refresh attempt this provider owns. */
-    captureRefreshFlight(generation, flight) {
-        this.refreshFlight = { generation, flight };
+    get redirectUrl() {
+        return this.redirectUri;
     }
-    /**
-     * @internal How the refresh this provider owned or joined failed, recorded by
-     * the coordinator; `undefined` clears it. The SDK learns nothing from this
-     * directly — the hooks it calls next (`state`, `saveCodeVerifier`,
-     * `redirectToAuthorization`, `invalidateCredentials`) read it.
-     */
-    recordRefreshFailure(failure) {
-        this.refreshFailure = failure;
+    get clientMetadata() {
+        const client = this.clientOptions?.client;
+        return downstreamClientMetadata(this.redirectUri, this.scope, this.clientOptions?.name, client ? remoteClientAuthMethod(client) : "none");
+    }
+    // --- the grant record ---------------------------------------------------
+    /** The grant's additional authenticated data: record and epoch. */
+    grantLabel(epoch) {
+        return `${GRANT}:${epoch}`;
+    }
+    async encodeGrant(grant) {
+        this.assertCredentialFree({ issuer: grant.body.issuer, discovery: grant.body.discovery }, grant.body);
+        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) {
+            if (this.sealer) {
+                stored.sealed = await this.sealer.seal(this.grantLabel(grant.epoch), JSON.stringify(grant.body));
+            }
+            else {
+                stored.body = grant.body;
+            }
+        }
+        return JSON.stringify(stored);
     }
     /**
-     * @internal Delete the grant the authorization server just refused, but only
-     * while storage still holds exactly that refresh token in this generation: a
-     * consent that completed meanwhile must survive. Where the store has
-     * `compareAndSet`, the delete is conditional on the exact raw string read
-     * (ciphertext, when sealed), so a write landing in between wins. A store
-     * without it (Workers KV) gets the read followed by a plain delete, and a
-     * write landing between the two can still be lost — the same window the
-     * SDK's own invalidation has. Best effort: if storage fails, the next
-     * refresh is refused again and ends the same way.
+     * Open a stored grant. A body that does not open — tampered, under a
+     * rotated key, moved from another connector, owner, or epoch, or sealed
+     * with no sealer configured — reads as empty: authorization again.
      */
-    async discardRefusedGrant(refreshToken, generation) {
-        try {
-            const read = await this.readStoredValue("oauth:tokens", (raw) => JSON.parse(raw));
-            if (!read ||
-                read.stored.generation !== generation ||
-                read.stored.value.refresh_token !== refreshToken) {
-                return;
-            }
-            const physicalKey = oauthValueStorageKey("oauth:tokens", generation);
-            if (this.storage.compareAndSet) {
-                await this.storage.compareAndSet(physicalKey, read.raw, null);
+    async openGrant(raw) {
+        if (raw === null)
+            return { epoch: INITIAL_EPOCH, body: {} };
+        const stored = storedGrant(raw);
+        if (!stored)
+            return { epoch: UNREADABLE_EPOCH, body: {} };
+        let body = stored.body;
+        if (stored.sealed !== undefined) {
+            body = undefined;
+            try {
+                if (this.sealer)
+                    body = parsed(await this.sealer.open(this.grantLabel(stored.epoch), stored.sealed));
             }
-            else {
-                await this.storage.delete(physicalKey);
+            catch {
+                this.sealer?.warn(`[connecta] connector "${this.connectorId}" has a sealed OAuth grant ` +
+                    "the configured vault cannot open; treating it as absent, so the " +
+                    "connector needs authorization again. A changed vault key or " +
+                    "tampered storage causes this.");
             }
         }
-        catch {
-            // See above: a refusal that could not be recorded recurs, it does not hide.
+        return {
+            epoch: stored.epoch,
+            ...(stored.cleanupPending ? { cleanupPending: true } : {}),
+            ...(stored.flow !== undefined ? { flow: stored.flow } : {}),
+            body: grantBody(body),
+        };
+    }
+    /**
+     * The grant as stored now, migrating layout 2 on first sight. 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.
+     */
+    async readGrant() {
+        let raw = await this.storage.get(GRANT);
+        if (raw === null)
+            raw = await this.migrate();
+        if (raw !== null && storedGrant(raw)?.cleanupPending)
+            raw = await this.cleanupV2(raw);
+        const grant = await this.openGrant(raw);
+        if (raw !== null && this.sealer && storedGrant(raw)?.body !== undefined && !this.signal?.aborted) {
+            const sealed = await this.encodeGrant(grant);
+            if (await this.storage.compareAndSet(GRANT, raw, sealed).catch(() => false))
+                raw = sealed;
         }
+        return { raw, grant };
     }
     /**
-     * Why a passive request cannot start consent. After a transient refresh
-     * failure that is a retryable outage, not an authorization problem: the SDK
-     * falls through to authorization on any refresh it could not parse, and
-     * answering that with `UnauthorizedError` would tell the agent a working
-     * grant needs consent.
+     * Layout 2's grant, written once as this owner's record. Whichever request
+     * writes first wins; the layout 2 keys are deleted once a record exists.
      */
-    authorizationRefused() {
-        const failure = this.refreshFailure;
-        return failure?.kind === "transient"
-            ? this.refreshOutage(failure)
-            : new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
-    }
-    refreshOutage(failure) {
-        const { cause } = failure;
-        return new ConnectorCallError(failure.status === 429 ? "rate_limited" : "unavailable", `Connector "${this.connectorId}" could not refresh its OAuth grant: the ` +
-            `authorization server ${failure.reason}. The grant is kept; retry later.`, {
-            ...(cause !== undefined ? { cause } : {}),
-            ...(failure.retryAfterMs !== undefined
-                ? { retryAfterMs: failure.retryAfterMs }
-                : {}),
-            ...(cause instanceof ConnectorCallError && cause.details
-                ? { details: cause.details }
-                : {}),
+    async migrate() {
+        const found = await readV2Grant(this.storage, this.sealer);
+        // A request that has already left writes nothing, this included.
+        if (!found || this.signal?.aborted)
+            return null;
+        const prefix = found.disconnected ? DISCONNECTED_EPOCH_PREFIX : ACTIVE_EPOCH_PREFIX;
+        const encoded = await this.encodeGrant({
+            epoch: `${prefix}${crypto.randomUUID()}`,
+            body: found.body,
+            cleanupPending: true,
         });
+        let written;
+        try {
+            written = await this.storage.compareAndSet(GRANT, null, encoded);
+        }
+        catch {
+            // A store's own error can quote the value it refused.
+            throw this.credentialWriteError();
+        }
+        const raw = written ? encoded : await this.storage.get(GRANT);
+        return raw;
     }
-    failRefreshFlight(error) {
-        const owned = this.refreshFlight;
-        this.refreshFlight = undefined;
-        if (owned) {
-            this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
+    /** Deletion is retried on every read, including reads after a reset. */
+    async cleanupV2(raw) {
+        try {
+            if (!(await deleteV2Keys(this.storage)))
+                return raw;
+            const grant = await this.openGrant(raw);
+            delete grant.cleanupPending;
+            const cleared = await this.encodeGrant(grant);
+            if (await this.storage.compareAndSet(GRANT, raw, cleared))
+                return cleared;
+            return this.storage.get(GRANT);
+        }
+        catch {
+            // The durable marker survives both deletion and marker-clear failures.
+            return raw;
         }
     }
-    /** True when another request saved a refresh result after this flow's read. */
-    refreshBasisChanged(current, generation) {
-        const basis = this.refreshBasis;
-        return Boolean(basis &&
-            basis.generation === generation &&
-            (basis.accessToken !== current.access_token ||
-                basis.refreshToken !== current.refresh_token ||
-                basis.successIdentity !==
-                    this.refreshCoordinator?.successfulRefreshIdentity(generation)));
+    /** The grant a bound flow reads: a replaced epoch fails it. */
+    async boundGrant() {
+        const { grant } = await this.readGrant();
+        if (this.bound && grant.epoch !== this.epoch)
+            throw this.flowSuperseded();
+        return grant;
     }
     /**
-     * The epoch this provider writes under. Direct unit/custom use lazily captures
-     * the current generation; connector-driven connect and callback paths stamp it
-     * explicitly before the SDK can write.
+     * The one way a grant changes: read, change, compare-and-set, again while
+     * other writers win. The write belongs to `epoch` (default: the flow's,
+     * captured now if unset) and lands nowhere once another is live: `quiet`
+     * drops it silently, otherwise a bound flow fails as superseded. `commit`
+     * writes after the request's abort too. `change` returning undefined
+     * leaves the grant as it is.
      */
-    async writeGeneration() {
-        this.capturedGeneration ??= await this.generation();
-        return this.capturedGeneration;
-    }
-    /**
-     * Store a value in the flow's physical epoch namespace. The pre-write check
-     * avoids needless stale residue. The namespaced key closes the remaining
-     * check-then-write race: a late old write cannot overwrite a replacement
-     * flow's value because the two writes have different physical keys.
-     */
-    async writeValue(key, value, serializeLegacy, issuer, writtenAt, binding, commitAcceptedRefresh = false) {
-        const generation = await this.writeGeneration();
-        await this.storeInGeneration(key, generation, () => {
-            const stored = {
-                connectaOAuthVersion: STORED_VALUE_VERSION,
-                generation,
-                ...(issuer !== undefined ? { issuer } : {}),
-                ...(binding !== undefined ? { binding } : {}),
-                ...(writtenAt !== undefined ? { writtenAt } : {}),
-                value,
-            };
-            return isModernGeneration(generation) || issuer !== undefined
-                ? JSON.stringify(stored)
-                : serializeLegacy(value);
-        }, undefined, commitAcceptedRefresh);
-    }
-    /**
-     * The generation fence every write goes through: refuse unless `generation`
-     * is still the live, writable epoch, write (sealed when the key holds a
-     * credential and a sealer exists), then clean up if the epoch moved under
-     * the write. With `expected`, the write also requires the physical key to
-     * still hold exactly that raw value, so re-encoding cannot resurrect a value
-     * another request replaced in the meantime.
-     */
-    async storeInGeneration(key, generation, serialize, expected, commitAcceptedRefresh = false) {
-        if ((!commitAcceptedRefresh && this.signal?.aborted) ||
-            generation.startsWith(RESETTING_GENERATION_PREFIX) ||
-            generation.startsWith(DISCONNECTED_GENERATION_PREFIX) ||
-            (await this.generation()) !== generation) {
-            return;
-        }
-        const physicalKey = oauthValueStorageKey(key, generation);
-        const plaintext = serialize();
-        const serialized = this.sealer && SEALED_OAUTH_KEYS.has(key)
-            ? JSON.stringify({
-                connectaOAuthSealed: SEALED_VALUE_VERSION,
-                sealed: await this.sealer.seal(physicalKey, plaintext),
-            })
-            : plaintext;
-        if (!commitAcceptedRefresh && this.signal?.aborted)
-            return;
-        if (expected === undefined) {
-            await this.storage.set(physicalKey, serialized);
-        }
-        else if (!(await this.replaceExactly(physicalKey, expected, serialized))) {
-            return;
-        }
-        // If reset landed after the pre-write check and completed its cleanup
-        // before this set, remove the now-unreachable residue ourselves. The epoch
-        // key already provides correctness; this second check is physical hygiene.
-        const current = await this.generation();
-        if (current !== generation || (!commitAcceptedRefresh && this.signal?.aborted)) {
+    async updateGrant(change, options = {}) {
+        for (let attempt = 0; attempt < MAX_GRANT_WRITES; attempt++) {
+            if (!options.commit && this.signal?.aborted)
+                return false;
+            const { raw, grant } = await this.readGrant();
+            const epoch = options.epoch ?? (this.epoch ??= grant.epoch);
+            if (grant.epoch !== epoch) {
+                if (options.quiet || !this.bound)
+                    return false;
+                throw this.flowSuperseded();
+            }
+            // A disconnect's epoch holds nothing until an explicit start replaces it.
+            if (isDisconnectedEpoch(epoch))
+                return false;
+            const next = change(grant);
+            if (next === undefined)
+                return true;
+            const encoded = await this.encodeGrant(next);
+            if (!options.commit && this.signal?.aborted)
+                return false;
+            let written;
             try {
-                // On cancellation the generation may still be active. A newer flow
-                // could have written this key while the old storage set was pending.
-                if (this.storage.compareAndSet) {
-                    await this.storage.compareAndSet(physicalKey, serialized, null);
-                }
-                else if ((await this.storage.get(physicalKey)) === serialized) {
-                    await this.storage.delete(physicalKey);
-                }
+                written = await this.storage.compareAndSet(GRANT, raw, encoded);
             }
             catch {
-                // Make a transient cleanup failure retryable by the next force reset.
-                // This is still best-effort if storage cannot accept the backlog write.
-                try {
-                    await this.rememberRetiredGeneration(current, generation);
-                }
-                catch {
-                    // The old namespace is already unreadable; storage availability is
-                    // the remaining physical-hygiene boundary.
-                }
+                // A store's own error can quote the value it refused.
+                throw this.credentialWriteError();
+            }
+            if (written) {
+                if (next.epoch !== grant.epoch)
+                    this.epoch = next.epoch;
+                return true;
             }
         }
+        throw this.credentialWriteError();
+    }
+    /** Store a client or tokens for `issuer`'s grant, replacing another server's. */
+    async writeCredential(field, value, issuer, refreshConsent) {
+        await this.updateGrant((grant) => {
+            const body = issuer !== undefined && grant.body.issuer !== issuer ? { issuer } : { ...grant.body };
+            if (field === "client")
+                body.client = value;
+            else {
+                body.tokens = value;
+                delete body.refreshConsent;
+                if (refreshConsent)
+                    body.refreshConsent = refreshConsent;
+            }
+            return this.withIssuer(grant, body);
+        });
+        // A flow may invalidate what it wrote itself.
+        this.seen[field] = fingerprint(field === "client" ? value.value : value);
     }
-    /**
-     * Compare-and-set where the store has it. A store without it gets a re-read
-     * immediately before the write: it narrows the race to one round trip, the
-     * same exposure that store already has for every other OAuth write.
-     */
-    async replaceExactly(physicalKey, expected, next) {
-        if (this.storage.compareAndSet) {
-            return this.storage.compareAndSet(physicalKey, expected, next);
+    withIssuer(grant, body) {
+        if (grant.body.issuer !== undefined && grant.body.issuer !== body.issuer) {
+            if (this.codeExchange)
+                throw this.flowSuperseded();
+            return {
+                epoch: `${ACTIVE_EPOCH_PREFIX}${crypto.randomUUID()}`,
+                ...(grant.cleanupPending ? { cleanupPending: true } : {}),
+                body,
+            };
         }
-        if ((await this.storage.get(physicalKey)) !== expected)
-            return false;
-        await this.storage.set(physicalKey, next);
-        return true;
+        return { ...grant, body };
     }
-    /**
-     * Open a sealed credential. Anything that does not open — a tampered value,
-     * a rotated vault key, ciphertext copied from another connector or owner, or
-     * sealed state with no sealer configured — reads as absent, which fails
-     * closed to reauthorization.
-     */
-    async openValue(key, physicalKey, sealed) {
-        if (!this.sealer || !SEALED_OAUTH_KEYS.has(key))
-            return undefined;
-        try {
-            return await this.sealer.open(physicalKey, sealed);
-        }
-        catch {
-            this.sealer.warn(`[connecta] connector "${this.connectorId}" has sealed OAuth state ` +
-                `(${key}) the configured vault cannot open; treating it as absent, ` +
-                "so the connector needs authorization again. A changed vault key " +
-                "or tampered storage causes this.");
-            return undefined;
-        }
+    /** Static clients bind to deployment configuration without storing secrets. */
+    configuredAuthorizationBinding() {
+        return undefined;
     }
-    /**
-     * Re-encode plaintext an older release (or a vault-less deployment) wrote,
-     * in place and byte-for-byte, through the same generation fence as every
-     * write. A failure leaves the plaintext readable; the next write seals it.
-     */
-    async sealInPlace(key, generation, raw) {
-        try {
-            await this.storeInGeneration(key, generation, () => raw, raw);
-        }
-        catch {
-            this.sealer?.warn(`[connecta] connector "${this.connectorId}" could not seal plaintext ` +
-                `OAuth state (${key}); it stays readable and is sealed on its next write.`);
-        }
+    async bindingForGrant(grant) {
+        const configured = this.configuredAuthorizationBinding();
+        return configured
+            ? { ...configured, issuer: grant.body.issuer }
+            : {
+                ...(await discoveryBinding(grant.body.discovery)),
+                issuer: grant.body.issuer,
+                clientId: grant.body.client?.value.client_id,
+            };
     }
-    /**
-     * Read a value only when it belongs to the active generation. Plain legacy
-     * values remain readable until the first v2 reset, so upgrades do not discard
-     * an existing grant; once a modern epoch exists, untagged residue fails
-     * closed. With a sealer, a credential found in plaintext is returned and
-     * then sealed where it lies.
-     */
-    async readValue(key, parseLegacy) {
-        const read = await this.readStoredValue(key, parseLegacy);
-        if (!read)
-            return undefined;
-        if (read.plaintextCredential) {
-            await this.sealInPlace(key, read.stored.generation, read.raw);
+    async checkFlowBinding(grant) {
+        const binding = this.callback?.flow.binding;
+        if (!binding || fingerprint(binding) !== fingerprint(await this.bindingForGrant(grant))) {
+            throw this.flowSuperseded();
         }
-        return read.stored;
     }
-    /**
-     * `readValue` without the in-place sealing, keeping the exact raw string
-     * (ciphertext, when sealed) the value came from, for a compare-and-set.
-     */
-    async readStoredValue(key, parseLegacy) {
-        const generation = await this.generation();
-        const physicalKey = oauthValueStorageKey(key, generation);
-        const raw = await this.storage.get(physicalKey);
-        if (raw === null)
-            return undefined;
-        if (generation.startsWith(RESETTING_GENERATION_PREFIX) ||
-            generation.startsWith(DISCONNECTED_GENERATION_PREFIX)) {
-            return undefined;
-        }
-        let text = raw;
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            // Raw string state from a pre-envelope deployment is handled below.
+    /** Validate RFC 9207 against the server this consent selected. */
+    validateCallbackIssuer(issuer) {
+        if (!this.callback ||
+            (issuer === null
+                ? this.callback.flow.binding?.issRequired === true
+                : issuer !== this.callback.flow.binding?.issuer)) {
+            throw new ConnectorCallError("connector_call_failed", `Connector "${this.connectorId}" authorization callback issuer does not match its consent; nothing was exchanged.`);
         }
-        let plaintextCredential = false;
-        if (sealedOAuthValue(parsed)) {
-            const opened = await this.openValue(key, physicalKey, parsed.sealed);
-            if (opened === undefined)
-                return undefined;
-            text = opened;
-            parsed = undefined;
-            try {
-                parsed = JSON.parse(text);
+    }
+    // --- flow records ---------------------------------------------------------
+    flowLabel(key, epoch) {
+        return `${key}:${epoch}`;
+    }
+    async encodeFlow(key, flow) {
+        const { verifier, ...rest } = flow;
+        const stored = { connectaOAuthFlow: FLOW_VERSION, ...rest };
+        if (verifier !== undefined) {
+            if (this.sealer) {
+                stored.verifier = await this.sealer.seal(this.flowLabel(key, flow.epoch), verifier);
+                stored.sealed = true;
             }
-            catch {
-                // A sealed raw legacy string, handled below like its plaintext form.
+            else {
+                stored.verifier = verifier;
             }
         }
-        else {
-            plaintextCredential = this.sealer !== undefined && SEALED_OAUTH_KEYS.has(key);
-        }
-        const stored = this.interpretValue(text, parsed, generation, parseLegacy);
-        return stored ? { stored, raw, plaintextCredential } : undefined;
-    }
-    interpretValue(raw, parsed, generation, parseLegacy) {
-        if (storedOAuthValue(parsed)) {
-            return parsed.generation === generation
-                ? {
-                    value: parsed.value,
-                    generation,
-                    ...(parsed.issuer !== undefined ? { issuer: parsed.issuer } : {}),
-                    ...(parsed.binding !== undefined ? { binding: parsed.binding } : {}),
-                    // Only a finite number is a time; anything else reads as untimed.
-                    ...(typeof parsed.writtenAt === "number" &&
-                        Number.isFinite(parsed.writtenAt)
-                        ? { writtenAt: parsed.writtenAt }
-                        : {}),
-                }
-                : undefined;
-        }
-        if (legacyStoredOAuthValue(parsed)) {
-            return parsed.generation === generation
-                ? { value: parsed.value, generation }
-                : undefined;
-        }
-        if (isModernGeneration(generation))
-            return undefined;
-        return { value: parseLegacy(raw), generation };
-    }
-    /**
-     * Read credentials only for the authorization server that issued them.
-     *
-     * Values written before issuer binding are bound on their first read with a
-     * validated SDK issuer, preserving an existing grant across this upgrade.
-     * A later issuer change is different: publish a new generation before
-     * returning no credentials, so every isolate drops the old registration and
-     * token set and the SDK starts authorization from scratch.
-     */
-    async readIssuerBoundValue(key, parseLegacy, ctx) {
-        const read = await this.readStoredValue(key, parseLegacy);
-        if (!read)
+        return JSON.stringify(stored);
+    }
+    /** A flow record, its verifier opened only when `withVerifier`. */
+    async openFlow(key, raw, withVerifier) {
+        const value = parsed(raw);
+        if (!plainObject(value) ||
+            value.connectaOAuthFlow !== FLOW_VERSION ||
+            typeof value.epoch !== "string" ||
+            typeof value.at !== "number" ||
+            (value.url !== undefined && typeof value.url !== "string") ||
+            (value.verifier !== undefined && typeof value.verifier !== "string")) {
             return undefined;
-        const stored = read.stored;
-        if (!ctx || stored.issuer !== undefined) {
-            if (read.plaintextCredential) {
-                await this.sealInPlace(key, stored.generation, read.raw);
-            }
-            if (!ctx)
-                return stored.value;
         }
-        if (stored.issuer === undefined) {
-            // Binding is a migration of the value just read, never a new grant.
-            // A rotation or revocation that replaced it must win this race.
-            await this.storeInGeneration(key, stored.generation, () => JSON.stringify({
-                connectaOAuthVersion: STORED_VALUE_VERSION,
-                ...stored,
-                issuer: ctx.issuer,
-            }), read.raw);
-            return stored.value;
-        }
-        if (stored.issuer === ctx.issuer)
-            return stored.value;
-        if (this.signal?.aborted)
-            throw this.signal.reason;
+        const flow = {
+            epoch: value.epoch,
+            at: value.at,
+            ...(plainObject(value.binding) ? { binding: value.binding } : {}),
+            ...(typeof value.url === "string" ? { url: value.url } : {}),
+            ...(value.consumed === true ? { consumed: true } : {}),
+        };
+        if (!withVerifier || typeof value.verifier !== "string")
+            return flow;
+        if (value.sealed !== true)
+            return { ...flow, verifier: value.verifier };
         try {
-            await this.resetAuthorization();
+            if (!this.sealer)
+                return undefined;
+            return { ...flow, verifier: await this.sealer.open(this.flowLabel(key, flow.epoch), value.verifier) };
         }
-        finally {
-            // The issuer-aware flow may continue after the reset. Stamp any later
-            // writes into the replacement epoch; the connector's generation check
-            // still discards this connection attempt before caching it.
-            this.captureGeneration(await this.generation());
+        catch {
+            this.sealer?.warn(`[connecta] connector "${this.connectorId}" has a sealed OAuth consent ` +
+                "the configured vault cannot open; its callback is refused.");
+            return undefined;
         }
-        return undefined;
     }
-    /**
-     * Attempt every key deletion, a bounded number at a time, then report the
-     * first failure in key order. The deletes are independent, so none waits
-     * on another's round trip.
-     */
-    async deleteAll(keys, limit = concurrencyLimit(DELETE_CONCURRENCY)) {
-        const failure = firstRejection(await Promise.allSettled(keys.map((key) => limit(() => this.storage.delete(key)))));
-        if (failure)
-            throw failure.reason;
+    /** The live epoch's latest consent, until a callback claims it. */
+    async latestConsent() {
+        const grant = await this.boundGrant();
+        if (grant.flow === undefined)
+            return undefined;
+        const key = oauthFlowKeys.flow(grant.flow);
+        const raw = await this.storage.get(key);
+        const flow = raw === null ? undefined : await this.openFlow(key, raw, false);
+        return flow && !flow.consumed && flow.epoch === grant.epoch && flow.url !== undefined
+            ? { ...flow, url: flow.url }
+            : undefined;
+    }
+    // --- flows and epochs -----------------------------------------------------
+    /** The live epoch; an owner with no grant yet has the initial one. */
+    async liveEpoch() {
+        return (await this.readGrant()).grant.epoch;
+    }
+    /** True only after an operator disconnect, until an explicit start replaces it. */
+    async operatorDisconnected() {
+        return isDisconnectedEpoch(await this.liveEpoch());
+    }
+    isOperatorDisconnectedEpoch(epoch) {
+        return isDisconnectedEpoch(epoch);
     }
     /**
-     * Delete each retired generation's values, then its own manifest and times
-     * once every value is gone, sharing one bound across all of them. Settles
-     * one result per generation, in input order.
+     * 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.
      */
-    cleanupGenerations(generations, limit) {
-        return Promise.allSettled(generations.map(async (generation) => {
-            await this.deleteAll(this.valueKeysForGeneration(generation), limit);
-            await this.deleteAll([cleanupBacklogKey(generation), cleanupTimesKey(generation)], limit);
-        }));
+    async beginFlow() {
+        const epoch = await this.liveEpoch();
+        this.epoch = epoch;
+        this.bound = true;
+        return epoch;
+    }
+    /** The epoch this flow is bound to, or the live one. */
+    async flowEpoch() {
+        return this.epoch ?? (await this.liveEpoch());
     }
     /**
-     * The cleanup lineage published for `generation`, with retirement times,
-     * and the times record exactly as stored. An entry with no recorded time —
-     * written by an earlier release, or whose time write failed — reads as
-     * retired `now`, which can only lengthen its grace.
+     * Bind a code exchange: to the epoch its verified consent was written in, or
+     * the live one for an exchange no callback verified. An epoch already
+     * replaced fails here, before the SDK can send anything. What the grant
+     * holds now is all a refused code may invalidate.
      */
-    async cleanupBacklog(generation, now) {
-        const reads = await Promise.allSettled([
-            this.storage.get(cleanupBacklogKey(generation)),
-            this.storage.get(cleanupTimesKey(generation)),
-        ]);
-        const failure = firstRejection(reads);
-        if (failure)
-            throw failure.reason;
-        const [raw, rawTimes] = reads.map((read) => read.status === "fulfilled" ? read.value : null);
-        const recorded = retirementTimes(rawTimes ?? null);
-        if (raw === null || raw === undefined)
-            return { lineage: [], recorded };
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed) ||
-            parsed.length > MAX_CLEANUP_BACKLOG ||
-            !parsed.every((value) => typeof value === "string")) {
-            throw new Error(`Invalid OAuth cleanup backlog for "${this.connectorId}"`);
-        }
-        return {
-            lineage: mergeLineage(parsed.map((entry) => ({
-                generation: entry,
-                retiredAt: recorded.get(entry) ?? now,
-            }))),
-            recorded,
+    async bindFlow() {
+        const { grant } = await this.readGrant();
+        const epoch = this.callback?.flow.epoch ?? this.epoch ?? grant.epoch;
+        if (grant.epoch !== epoch)
+            throw this.flowSuperseded();
+        this.epoch = epoch;
+        this.bound = true;
+        this.codeExchange = true;
+        await this.checkFlowBinding(grant);
+        this.seen = {
+            client: fingerprint(grant.body.client?.value),
+            tokens: fingerprint(grant.body.tokens),
         };
     }
-    timesRecord(lineage) {
-        return JSON.stringify(Object.fromEntries(lineage));
+    /** Retain an already verified snapshot only for the exact same state. */
+    async verifyCallbackState(state) {
+        if (this.callback?.key === oauthFlowKeys.flow(await oauthStateDigest(state)))
+            return true;
+        return this.verifyState(state);
+    }
+    /** Whether `verifyState` matched a consent on this provider. */
+    verified() {
+        return this.callback !== undefined;
     }
-    /** Write a lineage's manifest and its times, reporting the first failure. */
-    async publishLineage(generation, lineage) {
-        const failure = firstRejection(await Promise.allSettled([
-            this.storage.set(cleanupBacklogKey(generation), JSON.stringify(lineage.map((entry) => entry.generation))),
-            this.storage.set(cleanupTimesKey(generation), this.timesRecord(lineage.map((entry) => [entry.generation, entry.retiredAt]))),
-        ]));
-        if (failure)
-            throw failure.reason;
+    /** The fixed, retryable failure of a flow a later reset superseded. */
+    flowSuperseded() {
+        return new ConnectorCallError("unavailable", `Connector "${this.connectorId}" authorization changed while this request was in flight; try again.`);
     }
     /**
-     * Record that a write just landed in `retired` after `active` fenced it,
-     * so its grace starts over from now. A generation not yet listed is
-     * appended. One already listed keeps its place in the manifest and has
-     * only its time moved: a reset that is sweeping it re-reads the lineage
-     * before publishing, sees the new time, and keeps it.
-     *
-     * Only the times record is rewritten for a listed generation, so this can
-     * never drop a manifest entry. Two late writers racing here can lose one
-     * time update to the other: a lost bump leaves the older time, which
-     * shortens that generation's grace back to what it was before the write
-     * (no worse than never recording it), and a time dropped from the record
-     * reads as retired "now", which only lengthens a grace.
+     * A credential write that storage refused, in fixed text and with no cause
+     * attached. Retryable: the grant it held is untouched.
      */
-    async rememberRetiredGeneration(active, retired) {
-        const now = Date.now();
-        const { lineage, recorded } = await this.cleanupBacklog(active, now);
-        if (lineage.some((entry) => entry.generation === retired)) {
-            await this.storage.set(cleanupTimesKey(active), this.timesRecord([...recorded, [retired, now]]));
-            return;
-        }
-        if (lineage.length >= MAX_CLEANUP_BACKLOG) {
-            throw new Error(`OAuth cleanup backlog for "${this.connectorId}" is full`);
-        }
-        await this.publishLineage(active, [
-            ...lineage,
-            { generation: retired, retiredAt: now },
-        ]);
+    credentialWriteError() {
+        return new ConnectorCallError("unavailable", `Connector "${this.connectorId}" could not store its OAuth credentials; try again shortly.`);
     }
-    valueKeysForGeneration(generation) {
-        return OAUTH_VALUE_KEYS.map((key) => oauthValueStorageKey(key, generation));
+    /** @internal Other requests kept refreshing faster than this one could join. */
+    refreshContended() {
+        this.recordRefreshFailure({ kind: "contended" });
+        return new ConnectorCallError("unavailable", `Connector "${this.connectorId}" could not refresh its OAuth grant while other requests were; retry.`);
     }
-    get redirectUrl() {
-        return this.redirectUri;
-    }
-    get clientMetadata() {
-        return {
-            redirect_uris: [this.redirectUri],
-            client_name: "connecta",
-            grant_types: ["authorization_code", "refresh_token"],
-            response_types: ["code"],
-            token_endpoint_auth_method: "none",
-            ...(this.scope !== undefined ? { scope: this.scope } : {}),
-        };
+    /**
+     * A passive call cannot start consent. A waiter deadline remains retryable;
+     * any dispatched failure requires consent because its token is spent.
+     */
+    authorizationRefused() {
+        const failure = this.refreshFailure;
+        if (failure?.kind === "contended")
+            return this.refreshContended();
+        return new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
     }
+    // --- the SDK's hooks --------------------------------------------------------
     async clientInformation(ctx) {
-        return this.readIssuerBoundValue("oauth:client", (raw) => JSON.parse(raw), ctx);
+        const { body } = await this.boundGrant();
+        const client = this.clientOptions?.client;
+        if (!body.client && !this.allowAuthorization)
+            throw this.authorizationRefused();
+        if (client) {
+            if ((ctx && ctx.issuer !== client.issuer) || body.issuer !== client.issuer)
+                throw this.flowSuperseded();
+            if (body.client &&
+                (body.client.value.client_id !== client.clientId || body.client.binding !== this.clientBinding))
+                throw this.flowSuperseded();
+            return {
+                client_id: client.clientId,
+                issuer: client.issuer,
+                token_endpoint_auth_method: this.clientMetadata.token_endpoint_auth_method,
+                ...(client.clientSecret !== undefined ? { client_secret: client.clientSecret } : {}),
+            };
+        }
+        if (!body.client || (ctx && body.issuer !== ctx.issuer))
+            return undefined;
+        this.seen.client = fingerprint(body.client.value);
+        return ctx ? { ...body.client.value, issuer: ctx.issuer } : body.client.value;
     }
     async saveClientInformation(info, ctx) {
-        await this.writeValue("oauth:client", info, (value) => JSON.stringify(value), ctx?.issuer, undefined, this.clientBinding);
+        const { body } = await this.boundGrant();
+        const registrationPath = this.clientOptions?.client
+            ? "static"
+            : body.client?.value.client_id === info.client_id && body.client.registrationPath
+                ? body.client.registrationPath
+                : this.clientMetadataUrl &&
+                    body.discovery?.authorizationServerMetadata?.client_id_metadata_document_supported === true
+                    ? "cimd"
+                    : "dcr";
+        await this.writeCredential("client", {
+            value: this.clientOptions?.client ? { client_id: this.clientOptions.client.clientId } : info,
+            registrationPath,
+            ...(this.clientBinding !== undefined ? { binding: this.clientBinding } : {}),
+        }, ctx?.issuer);
+    }
+    async registrationPath() {
+        const { body } = await this.boundGrant();
+        return body.client?.registrationPath;
+    }
+    /** Intake and saved URLs share a guard. Include the current grant's secrets
+     * so a fresh request can reject an older cache before sending credentials. */
+    assertCredentialFree(value, body, consentUrl = false) {
+        // OAuth intentionally puts its public client identity in consent. Exempt
+        // only that parameter when it equals the bound/configured client, leaving
+        // every other occurrence subject to the credential check. The URL itself
+        // is never changed, only this matching view.
+        if (consentUrl && typeof value === "string") {
+            const url = new URL(value);
+            const clientId = this.clientOptions?.client?.clientId ??
+                body.client?.value.client_id ??
+                this.configuredAuthorizationBinding()?.clientId;
+            const ids = url.searchParams.getAll("client_id");
+            if (clientId && ids.length === 1 && ids[0] === clientId)
+                url.searchParams.delete("client_id");
+            value = url.href;
+        }
+        const secrets = new SentSecrets();
+        for (const value of [
+            body.tokens?.access_token,
+            body.tokens?.refresh_token,
+            body.client?.value.client_secret,
+            this.clientOptions?.client?.clientSecret,
+        ]) {
+            if (typeof value === "string")
+                secrets.secret(value);
+        }
+        if (body.client?.value.client_secret)
+            secrets.add(body.client.value.client_id);
+        if (this.clientOptions?.client?.clientSecret)
+            secrets.add(this.clientOptions.client.clientId);
+        const urls = [];
+        const collect = (item) => {
+            if (typeof item === "string") {
+                try {
+                    urls.push(new URL(item).href);
+                }
+                catch {
+                    /* Not a URL field. */
+                }
+            }
+            else if (item && typeof item === "object")
+                for (const field of Object.values(item))
+                    collect(field);
+        };
+        collect(value);
+        if ([secrets, this.clientOptions?.secrets].some((source) => source && (source.redact(value) !== value || urls.some((url) => source.containsUrl(url))))) {
+            throw new ConnectorCallError("connector_call_failed", "OAuth metadata or consent URL contains a credential; refusing authorization.", { retryable: false });
+        }
+    }
+    /** Only metadata bound to the discovered issuer can supply operator origins. */
+    async validatedIssuerOrigin() {
+        const { body } = await this.boundGrant();
+        const state = body.discovery;
+        if (!state ||
+            state.authorizationServerMetadata?.issuer !== state.authorizationServerUrl ||
+            body.issuer !== state.authorizationServerUrl)
+            return undefined;
+        this.assertCredentialFree(state, body);
+        return new URL(state.authorizationServerUrl).origin;
     }
     async discoveryState() {
-        return (await this.readValue("oauth:discovery", (raw) => JSON.parse(raw)))?.value;
+        const { body } = await this.boundGrant();
+        const state = body.discovery;
+        this.assertCredentialFree(state, body);
+        this.consentDiscovery = state;
+        return state;
     }
+    /**
+     * Discovery names the grant's server: the same one keeps the client and
+     * tokens beside it, another replaces them. The SDK discovers afresh only
+     * without a cached record — a restart's carried client, say — and what a
+     * different server leaves behind would never be sent to it anyway.
+     */
     async saveDiscoveryState(state) {
-        await this.writeValue("oauth:discovery", state, (value) => JSON.stringify(value));
+        this.assertCredentialFree(state, (await this.boundGrant()).body);
+        const issuer = discoveryIssuer(state);
+        if (this.clientOptions?.client && issuer !== this.clientOptions.client.issuer)
+            throw this.flowSuperseded();
+        if (!this.allowAuthorization && !(await this.boundGrant()).body.client)
+            throw this.authorizationRefused();
+        this.consentDiscovery = state;
+        await this.updateGrant((grant) => {
+            const body = grant.body.issuer !== issuer ? (issuer !== undefined ? { issuer } : {}) : { ...grant.body };
+            this.assertCredentialFree(state, grant.body);
+            body.discovery = state;
+            return this.withIssuer(grant, body);
+        });
     }
+    /**
+     * The grant's tokens, for the server that issued them only. An
+     * issuer-aware read records what it handed the SDK, so the coordinator can
+     * tell a refresh another request completed since.
+     */
     async tokens(ctx) {
-        const refreshGeneration = ctx ? await this.flowGeneration() : undefined;
-        const successIdentity = refreshGeneration !== undefined
-            ? this.refreshCoordinator?.successfulRefreshIdentity(refreshGeneration)
-            : undefined;
-        const tokens = await this.readIssuerBoundValue("oauth:tokens", (raw) => JSON.parse(raw), ctx);
-        if (ctx && tokens && refreshGeneration !== undefined) {
-            this.refreshBasis = {
-                accessToken: tokens.access_token,
-                generation: refreshGeneration,
-                ...(tokens.refresh_token !== undefined
-                    ? { refreshToken: tokens.refresh_token }
-                    : {}),
-                ...(successIdentity !== undefined ? { successIdentity } : {}),
-            };
-        }
-        return tokens;
+        const grant = await this.boundGrant();
+        const { tokens } = grant.body;
+        if (!tokens || (ctx && grant.body.issuer !== ctx.issuer))
+            return undefined;
+        this.seen.tokens = fingerprint(tokens);
+        if (!ctx)
+            return tokens;
+        this.refreshBasis = { accessToken: tokens.access_token, epoch: grant.epoch, issuer: ctx.issuer };
+        return { ...tokens, issuer: ctx.issuer };
     }
     async saveTokens(tokens, ctx) {
-        const owned = this.refreshFlight;
-        if (owned?.flight.acceptedTokens !== undefined) {
-            await this.persistAcceptedTokens(tokens, ctx, owned);
-        }
-        else {
-            await this.persistTokens(tokens, ctx, false, owned);
-        }
-    }
-    /** @internal Commit an already redeemed rotation even after its request leaves. */
-    async saveAcceptedRefreshTokens(tokens, generation, flight) {
-        await this.persistAcceptedTokens(tokens, undefined, { generation, flight });
-    }
-    persistAcceptedTokens(tokens, ctx, owned) {
-        // The SDK can save the same response while cancellation recovery is
-        // writing it. A second write could land after the next rotation, so both
-        // paths await this exact flight's one commit, including its failure.
-        return owned.flight.persistence ??= this.persistTokens(tokens, ctx, true, owned);
-    }
-    async persistTokens(tokens, ctx, commitAcceptedRefresh, owned) {
-        const releasePartition = this.refreshCoordinator?.retainWork();
-        // A retired flight (the owner was cancelled or superseded after the
-        // token response) still writes: the authorization server has already
-        // consumed the old refresh token, so dropping the rotated one would leave a
-        // dead credential. writeValue itself refuses when the generation moved.
-        // Only the coordinator bookkeeping belongs to the exact live flight.
-        const coordinated = owned !== undefined &&
-            this.refreshCoordinator?.beginMutation(owned.generation, owned.flight) === true;
-        try {
-            await this.writeValue("oauth:tokens", tokens, (value) => JSON.stringify(value), ctx?.issuer, undefined, undefined, commitAcceptedRefresh);
-            if (coordinated)
-                this.refreshCoordinator?.succeedMutation(owned.generation, owned.flight);
-            this.refreshFailure = undefined;
-        }
-        catch (error) {
-            if (coordinated)
-                this.refreshCoordinator?.failMutation(owned.generation, owned.flight, error);
-            throw error;
-        }
-        finally {
-            // The write owns this identity even if an SDK failure callback has
-            // already detached the provider's flight while storage was pending.
-            if (this.refreshFlight === owned)
-                this.refreshFlight = undefined;
-            releasePartition?.();
-        }
+        if (this.refreshFailure?.kind === "dead")
+            throw this.authorizationRefused();
+        // The coordinator stored this refresh already, or handed on another's.
+        if (this.storedRefresh !== undefined && tokens.access_token === this.storedRefresh)
+            return;
+        const refreshConsent = this.exchangeConsent &&
+            tokens.refresh_token !== undefined &&
+            this.exchangeConsent.digest === (await oauthStateDigest(tokens.refresh_token))
+            ? this.exchangeConsent
+            : undefined;
+        await this.writeCredential("tokens", tokens, ctx?.issuer, refreshConsent);
+        this.refreshFailure = undefined;
     }
     /**
-     * OAuth `state`. The SDK calls this (when present) and appends the value to
-     * the authorization URL. We generate a fresh random value and persist it so
-     * the public /oauth/callback route can prove the callback belongs to a flow
-     * WE started. Without it, anyone holding a pending authorization URL could
-     * complete consent with their own account (login CSRF) — PKCE does not help,
-     * since the verifier belongs to connecta, not the attacker. Cleared in
-     * clearPending() once the flow completes.
+     * OAuth `state`: 256 random bits the consent URL carries and the callback
+     * must present, so nobody holding a consent URL can complete it with their
+     * own account (login CSRF). Stored, by digest, with the consent.
      */
     async state() {
         if (!this.allowAuthorization)
             throw this.authorizationRefused();
-        const value = randomState();
-        await this.writeValue("oauth:state", value, (raw) => raw);
-        return value;
-    }
-    /**
-     * Constant-time check of a callback's `state` against the stored one-shot
-     * value. Absent stored state or absent candidate → false (fail closed).
-     */
-    async verifyState(candidate) {
-        const expected = await this.readValue("oauth:state", (raw) => raw);
-        if (!expected || candidate === null)
-            return false;
-        const matches = timingSafeEqual(candidate, expected.value);
-        if (matches)
-            this.captureGeneration(expected.generation);
-        return matches;
+        const state = randomState();
+        this.consent = { state };
+        return state;
     }
     async saveCodeVerifier(verifier) {
         if (!this.allowAuthorization)
             throw this.authorizationRefused();
-        await this.writeValue("oauth:verifier", verifier, (raw) => raw);
+        this.consent = { ...this.consent, verifier };
     }
     async codeVerifier() {
-        const stored = await this.readValue("oauth:verifier", (raw) => raw);
-        if (!stored) {
+        const verifier = this.callback?.flow.verifier ?? this.consent.verifier;
+        if (verifier === undefined) {
             throw new Error(`No PKCE code verifier for "${this.connectorId}"`);
         }
-        return stored.value;
+        return verifier;
     }
+    /**
+     * Store the consent: its flow record first, by state digest with the
+     * link's lifetime, then the grant's pointer to it, in the flow's epoch. A
+     * reset that replaced the epoch fails the start, and the record is removed,
+     * so no start hands out a consent its callback could not complete.
+     */
     async redirectToAuthorization(authorizationUrl) {
+        if (!this.allowAuthorization)
+            throw this.authorizationRefused();
+        this.assertCredentialFree(authorizationUrl.toString(), (await this.boundGrant()).body, true);
+        const state = this.consent.state ?? authorizationUrl.searchParams.get("state");
+        if (!state)
+            throw new Error(`OAuth consent for "${this.connectorId}" carries no state`);
+        const client = this.clientOptions?.client;
+        if (client && !(await this.boundGrant()).body.client) {
+            await this.saveClientInformation({ client_id: client.clientId }, { issuer: client.issuer });
+        }
+        const configured = this.configuredAuthorizationBinding();
+        if (configured?.issuer !== undefined) {
+            const issuer = configured.issuer;
+            // Static adapters do not save discovery or client configuration. Publish
+            // their server identity before consent so a changed endpoint fences the
+            // old grant before any code exchange can leave.
+            await this.updateGrant((grant) => grant.body.issuer === issuer ? undefined : this.withIssuer(grant, { issuer }));
+        }
+        const epoch = await this.flowEpoch();
+        this.epoch = epoch;
+        const digest = await oauthStateDigest(state);
+        const key = oauthFlowKeys.flow(digest);
+        const url = authorizationUrl.toString();
+        const { verifier } = this.consent;
+        const grant = await this.boundGrant();
+        this.assertCredentialFree(url, grant.body, true);
+        const binding = this.configuredAuthorizationBinding() ?? {
+            ...(await discoveryBinding(this.consentDiscovery ?? grant.body.discovery)),
+            issuer: discoveryIssuer(this.consentDiscovery) ?? grant.body.issuer,
+            clientId: authorizationUrl.searchParams.get("client_id") ?? grant.body.client?.value.client_id,
+        };
+        const record = await this.encodeFlow(key, {
+            epoch,
+            at: Date.now(),
+            binding,
+            url,
+            ...(verifier !== undefined ? { verifier } : {}),
+        });
+        if (this.signal?.aborted)
+            return;
+        if (!(await this.storage.compareAndSet(key, null, record, { ttlSeconds: OAUTH_FLOW_TTL_SECONDS }))) {
+            throw new Error(`OAuth consent for "${this.connectorId}" reused a state`);
+        }
+        let published = false;
         try {
-            if (!this.allowAuthorization)
-                throw this.authorizationRefused();
-            // Timestamped so a later start can tell a URL worth reissuing from a
-            // stale one. A pre-envelope (legacy-generation) write keeps its raw
-            // format for older readers and carries no time.
-            await this.writeValue("oauth:pending", authorizationUrl.toString(), (raw) => raw, undefined, Date.now());
-            this.failRefreshFlight(new Error("OAuth refresh required reauthorization before tokens were saved."));
+            published = await this.updateGrant((grant) => ({ ...grant, flow: digest }), { epoch });
         }
-        catch (error) {
-            this.failRefreshFlight(error);
-            throw error;
+        finally {
+            if (!published)
+                await this.storage.compareAndSet(key, record, null).catch(() => { });
         }
+        if (published)
+            this.published = { epoch, url };
     }
-    /** The stored authorization URL, if a flow is pending. */
+    /** The consent this provider stored, while its epoch is still live. */
+    async consentUrl() {
+        const published = this.published;
+        if (!published)
+            return undefined;
+        if (epochOf(await this.storage.get(GRANT)) !== published.epoch)
+            throw this.flowSuperseded();
+        this.assertCredentialFree(published.url, (await this.boundGrant()).body, true);
+        return published.url;
+    }
+    /** The live epoch's pending consent URL, if one is unclaimed. */
     async pendingAuthorizationUrl() {
-        return (await this.readValue("oauth:pending", (raw) => raw))?.value;
+        const url = (await this.latestConsent())?.url;
+        this.assertCredentialFree(url, (await this.boundGrant()).body, true);
+        return url;
     }
     /**
-     * The pending authorization URL, only while it is still worth handing out
-     * again: written within PENDING_AUTHORIZATION_MAX_AGE_MS of now, in either
-     * direction to tolerate clock skew between isolates. A URL with no write
-     * time — stored by an earlier release, or under a pre-envelope generation —
-     * is treated as stale, so the caller starts a fresh flow instead.
+     * The pending consent URL, only while it is still worth handing out again:
+     * unclaimed, written within PENDING_AUTHORIZATION_MAX_AGE_MS of now in
+     * either direction (clock skew between isolates), and naming the grant's
+     * client. A callback whose exchange the server refused with
+     * `invalid_client` drops the client, and its URL would send the operator to
+     * a consent the server has already refused.
      */
     async reusablePendingAuthorizationUrl() {
-        const pending = await this.readValue("oauth:pending", (raw) => raw);
-        if (pending?.writtenAt === undefined)
+        const consent = await this.latestConsent();
+        if (!consent || Math.abs(Date.now() - consent.at) >= PENDING_AUTHORIZATION_MAX_AGE_MS) {
             return undefined;
-        return Math.abs(Date.now() - pending.writtenAt) <
-            PENDING_AUTHORIZATION_MAX_AGE_MS
-            ? pending.value
-            : undefined;
+        }
+        this.assertCredentialFree(consent.url, (await this.boundGrant()).body, true);
+        let clientId;
+        try {
+            clientId = new URL(consent.url).searchParams.get("client_id");
+        }
+        catch {
+            return undefined;
+        }
+        const client = await this.clientInformation();
+        return clientId !== null && client?.client_id === clientId ? consent.url : undefined;
     }
-    /** Clear one-shot flow state after the callback completes. */
-    async clearPending() {
-        const generation = await this.writeGeneration();
-        await this.deleteAll([
-            oauthValueStorageKey("oauth:pending", generation),
-            oauthValueStorageKey("oauth:verifier", generation),
-            oauthValueStorageKey("oauth:state", generation),
-        ]);
+    /**
+     * Find the consent a callback's `state` names. One read whatever the
+     * answer; the callback route's refusals pay the same. A claimed consent
+     * no longer matches.
+     */
+    async verifyState(candidate) {
+        this.callback = undefined;
+        if (candidate === null)
+            return false;
+        const key = oauthFlowKeys.flow(await oauthStateDigest(candidate));
+        const raw = await this.storage.get(key);
+        const flow = raw === null ? undefined : await this.openFlow(key, raw, true);
+        if (raw === null || !flow || flow.consumed)
+            return false;
+        this.callback = { key, raw, flow, claimed: false };
+        this.epoch = flow.epoch;
+        return true;
     }
     /**
-     * Force-reauth epoch shared across isolates through storage. Old numeric
-     * generations remain valid strings for migration; new resets use unique
-     * nonces, avoiding the lost-update race of read/increment/write.
+     * @internal The first half of the fence a code exchange crosses after every
+     * read it depends on, just before the code leaves: claim the consent by
+     * compare-and-set from the exact record `verifyState` found to a claimed
+     * one. Of several callbacks carrying one state, exactly one wins; the
+     * others send nothing. A claim that fails because a restart swept the
+     * consent reports the supersession. The claim is spent whether or not the
+     * exchange succeeds; the SDK's one retry after a refused code is answered
+     * with that refusal, never sent again.
      */
-    async generation() {
-        return (await this.storage.get("oauth:generation")) ?? LEGACY_GENERATION;
+    async claimCodeExchange() {
+        if (this.exchangeRefusal)
+            return this.exchangeRefusal.clone();
+        await this.claimConsent();
+        return undefined;
     }
-    /** True only after an operator disconnect, until an explicit authorization starts. */
-    async operatorDisconnected() {
-        return this.isOperatorDisconnectedGeneration(await this.generation());
+    /** Terminate the verified consent on an error, sharing the code exchange CAS. */
+    async consumeAuthError() {
+        const { grant } = await this.readGrant();
+        if (!this.callback || grant.epoch !== this.callback.flow.epoch)
+            throw this.flowSuperseded();
+        await this.checkFlowBinding(grant);
+        await this.claimConsent();
+        this.callback = undefined;
+    }
+    async claimConsent() {
+        const callback = this.callback;
+        if (!callback)
+            throw this.flowSuperseded();
+        if (callback.claimed)
+            throw new OAuthCallbackClaimedError(this.connectorId);
+        callback.claimed = true;
+        const { epoch, at } = callback.flow;
+        const claimed = JSON.stringify({
+            connectaOAuthFlow: FLOW_VERSION,
+            epoch,
+            at,
+            consumed: true,
+        });
+        const remaining = Math.ceil((at + OAUTH_FLOW_TTL_SECONDS * 1000 - Date.now()) / 1000);
+        const ttlSeconds = Math.min(OAUTH_FLOW_TTL_SECONDS, Math.max(1, remaining));
+        if (await this.storage.compareAndSet(callback.key, callback.raw, claimed, { ttlSeconds })) {
+            return;
+        }
+        if (epochOf(await this.storage.get(GRANT)) !== epoch)
+            throw this.flowSuperseded();
+        throw new OAuthCallbackClaimedError(this.connectorId);
+    }
+    /**
+     * @internal The second half: read the live epoch and, in the reaction to
+     * that read, dispatch. No await stands between the check and `send`. A
+     * reset published at or before the read fails the exchange with nothing
+     * sent; one published after it, while the request is leaving, cannot be
+     * ordered before the send without a lock across requests, and its tokens
+     * are refused by the grant's compare-and-set: one more consent.
+     */
+    async dispatchCodeExchange(send, endpoint) {
+        const epoch = this.epoch;
+        if (!this.codeExchange || epoch === undefined)
+            throw this.flowSuperseded();
+        const raw = await this.storage.get(GRANT);
+        const grant = await this.openGrant(raw);
+        if (grant.epoch !== epoch)
+            throw this.flowSuperseded();
+        await this.checkFlowBinding(grant);
+        if (endpoint !== undefined && this.callback?.flow.binding?.tokenEndpoint !== String(endpoint)) {
+            throw this.flowSuperseded();
+        }
+        // Opening ciphertext may yield. Re-read the exact record after opening,
+        // then check and send in the same reaction, without another await.
+        return this.storage.get(GRANT).then((current) => {
+            if (current !== raw)
+                throw this.flowSuperseded();
+            const sent = send();
+            sent.catch(() => { });
+            return sent;
+        });
     }
-    /** Interpret a generation already read by a connector without another KV lookup. */
-    isOperatorDisconnectedGeneration(generation) {
-        return generation.startsWith(DISCONNECTED_GENERATION_PREFIX);
+    /** @internal Keep a refused code's answer for the SDK's retry to read. */
+    recordCodeExchangeRefusal(forSdk) {
+        this.exchangeRefusal = forSdk.clone();
     }
-    /** Publish a unique active epoch without a read/modify/write race. */
-    async bumpGeneration() {
-        const next = `${ACTIVE_GENERATION_PREFIX}${crypto.randomUUID()}`;
-        await this.storage.set("oauth:generation", next);
-        return next;
+    /** @internal Observe resolution while accepting the code response, never on a later SDK save. */
+    async recordCodeExchangeTokens(tokens) {
+        this.exchangeConsent = undefined;
+        if (tokens.refresh_token === undefined)
+            return;
+        try {
+            const digest = await oauthStateDigest(tokens.refresh_token);
+            const resolution = await this.storage.get(oauthRefreshSpentKeys.spent(digest));
+            const spent = storedRefreshSpent(resolution);
+            // Observing the exact resolved storage write before consent completion
+            // proves their order without comparing isolate clocks. A consent that
+            // saw outstanding/ambiguous cannot become eligible on a delayed save.
+            if (spent?.state === "resolved")
+                this.exchangeConsent = { digest, resolution: resolution };
+        }
+        catch {
+            throw this.credentialWriteError();
+        }
     }
     /**
-     * Fence every flow that could still write, then remove all durable and
-     * one-shot authorization state. The generation is intentionally retained:
-     * it is the epoch fence that tells another isolate not to resurrect
-     * credentials it read before this reset.
-     *
-     * Once the fence is durable, attempt every deletion even if one fails. A
-     * partial backend outage should not leave unrelated secrets behind merely
-     * because an earlier key happened to be the first failed delete.
-     *
-     * A reset's storage work does not grow with the resets before it. After
-     * the fence it deletes the one generation it retired, and retries any of
-     * the RETRY_PROBES most recent ones whose cleanup failed. Before publishing,
-     * it sweeps at most MAX_EXPIRED_SWEEP generations retired more than
-     * CLEANUP_GRACE_MS ago — every value, then its manifest and times — and
-     * only a generation whose sweep fully succeeded is left out of the new
-     * lineage. Everything else is carried with its retirement time: a
-     * generation still inside its grace whose cleanup finished is not deleted
-     * again, because a late write into it is unreadable behind the fence and
-     * the late writer deletes it itself, or records the generation again if it
-     * cannot; the sweep reclaims whatever is left once the grace has passed.
-     * The live manifest is never rewritten: an entry leaves the lineage only by
-     * being absent from the next epoch's manifest, which no other request
-     * writes until that epoch is active.
+     * Remove what the SDK asks, but only as this flow saw it: a refused code or
+     * refresh says nothing about a client or tokens another flow wrote since.
+     * The verifier lives in its consent, which the claim already spent.
      */
-    resetAuthorization(operatorDisconnected = false, preserveClient = false) {
-        const reset = this.performResetAuthorization(operatorDisconnected, preserveClient);
-        this.onReset?.(reset);
-        return reset;
+    async invalidateCredentials(scope) {
+        const fields = {
+            all: ["client", "tokens", "discovery"],
+            client: ["client"],
+            tokens: ["tokens"],
+            discovery: ["discovery"],
+            verifier: [],
+        }[scope];
+        if (fields.length > 0) {
+            await this.updateGrant((grant) => {
+                const body = { ...grant.body };
+                let changed = false;
+                for (const field of fields) {
+                    const current = field === "client" ? body.client?.value : body[field];
+                    if (current === undefined)
+                        continue;
+                    if (field !== "discovery" && fingerprint(current) !== this.seen[field])
+                        continue;
+                    delete body[field];
+                    changed = true;
+                }
+                return changed ? { ...grant, body } : undefined;
+            }, { quiet: true });
+        }
+        // The SDK invalidates after a refused refresh and then starts over, which
+        // on `invalid_client` means registering a new client. A passive request
+        // must not begin authorization, so it ends here, as auth_required.
+        if (!this.allowAuthorization && this.refreshFailure?.kind === "dead") {
+            throw this.authorizationRefused();
+        }
     }
-    async performResetAuthorization(operatorDisconnected, preserveClient) {
-        const nonce = crypto.randomUUID();
-        const previous = await this.generation();
-        // Only an explicitly forced restart may carry a registration forward.
-        // Discovery is never copied: the SDK must select the authorization server
-        // again, then its issuer-aware clientInformation hook checks the issuer.
-        const priorClient = preserveClient && !operatorDisconnected && this.clientBinding
-            ? await this.readValue("oauth:client", (raw) => {
-                try {
-                    return JSON.parse(raw);
+    // --- refresh, for the coordinator ---------------------------------------------
+    /**
+     * @internal How the refresh this provider owned or joined failed; undefined
+     * clears it. The hooks the SDK calls next (`state`, `saveCodeVerifier`,
+     * `redirectToAuthorization`, `invalidateCredentials`, `saveTokens`) read it.
+     */
+    recordRefreshFailure(failure) {
+        this.refreshFailure = failure;
+    }
+    /** @internal A shared-storage claim precedes every refresh dispatch. */
+    async claimRefresh(epoch, requested, signal, sharedWait) {
+        const waiting = sharedWait ?? refreshWait(signal);
+        const wait = waiting.run;
+        let delay = 10;
+        try {
+            const digest = await wait(() => oauthStateDigest(requested ?? ""));
+            const key = oauthRefreshKeys.lease(epoch, digest);
+            const spentKey = oauthRefreshSpentKeys.spent(digest);
+            while (!waiting.signal.aborted) {
+                if (signal?.aborted)
+                    throw aborted(signal);
+                const current = await wait(() => this.storedTokens());
+                if (current?.refresh_token !== requested || (current && this.refreshedSinceRead(current, epoch))) {
+                    if (!current)
+                        this.recordRefreshFailure({ kind: "dead" });
+                    return current ? this.adoptRefresh(current) : Response.json({ error: "invalid_grant" }, { status: 400 });
                 }
-                catch {
-                    return {};
+                const raw = await wait(() => this.storage.get(key));
+                const stored = raw === null ? undefined : parsed(raw);
+                if (plainObject(stored) &&
+                    stored.completed === true &&
+                    current &&
+                    stored.tokenDigest === (await wait(() => refreshTokensDigest(current)))) {
+                    return this.adoptRefresh(current);
                 }
-            })
-            : undefined;
-        const reusableClient = priorClient?.generation === previous &&
-            priorClient.issuer !== undefined &&
-            priorClient.binding === this.clientBinding &&
-            typeof priorClient.value?.client_id === "string"
-            ? priorClient
-            : undefined;
-        const now = Date.now();
-        const inherited = await this.cleanupBacklog(previous, now);
-        const active = `${operatorDisconnected
-            ? DISCONNECTED_GENERATION_PREFIX
-            : ACTIVE_GENERATION_PREFIX}${nonce}`;
-        const limit = concurrencyLimit(DELETE_CONCURRENCY);
-        const withinGrace = (entry) => now - entry.retiredAt < CLEANUP_GRACE_MS;
-        let lineage = inherited.lineage;
-        const expired = lineage
-            .filter((entry) => !withinGrace(entry))
-            .sort((a, b) => a.retiredAt - b.retiredAt)
-            .slice(0, MAX_EXPIRED_SWEEP)
-            .map((entry) => entry.generation);
-        if (expired.length > 0) {
-            const swept = await this.cleanupGenerations(expired, limit);
-            const reclaimed = new Set(expired.filter((_, index) => swept[index]?.status === "fulfilled"));
-            // The sweep widened the window between reading the live manifest and
-            // publishing its successor. A stale writer's cleanup may have appended
-            // to it meanwhile, so read it again and carry the union — and keep a
-            // swept generation after all if that append restarted its grace.
-            const latest = await this.cleanupBacklog(previous, now);
-            lineage = mergeLineage(lineage, latest.lineage).filter((entry) => withinGrace(entry) || !reclaimed.has(entry.generation));
+                if (plainObject(stored) && (plainObject(stored.verdict) || stored.completed === true)) {
+                    this.recordRefreshFailure({ kind: "dead" });
+                    await wait(() => this.discardRefusedGrant(requested, epoch));
+                    throw new UnauthorizedError("OAuth refresh grant is no longer active.");
+                }
+                if (plainObject(stored) && stored.state !== "claimed") {
+                    // Never compare another isolate's clock for a sent request. The
+                    // durable record survives expiry of this storage-owned liveness key.
+                    const active = typeof stored.activeKey === "string"
+                        ? await wait(() => this.storage.get(stored.activeKey))
+                        : null;
+                    if (active === null) {
+                        const refused = JSON.stringify({ ...stored, verdict: { kind: "dead" } });
+                        if (await wait(() => this.storage.compareAndSet(key, raw, refused))) {
+                            await wait(() => this.resolveRefreshSpent({ key, spentKey, spentExpected: null, raw: raw }, "ambiguous"));
+                            this.recordRefreshFailure({ kind: "dead" });
+                            await wait(() => this.discardRefusedGrant(requested, epoch));
+                            throw new UnauthorizedError("OAuth refresh outcome is unknown; authorization required.");
+                        }
+                        continue;
+                    }
+                }
+                else {
+                    const spentExpected = await wait(() => this.storage.get(spentKey));
+                    if (spentExpected !== null) {
+                        const spent = storedRefreshSpent(spentExpected);
+                        const consent = (await wait(() => this.boundGrant())).body.refreshConsent;
+                        if (spent?.state !== "resolved" ||
+                            spent.epoch === epoch ||
+                            consent?.digest !== digest ||
+                            consent.resolution !== spentExpected) {
+                            // Reset can sweep the old lease while its request remains live.
+                            // Only storage-owned expiry can make an outstanding send ambiguous.
+                            if (spent?.state === "outstanding" && (await wait(() => this.storage.get(spent.activeKey))) === null) {
+                                await wait(() => this.storage.compareAndSet(spentKey, spentExpected, JSON.stringify({ ...spent, state: "ambiguous" })));
+                            }
+                            this.recordRefreshFailure({ kind: "dead" });
+                            await wait(() => this.discardRefusedGrant(requested, epoch));
+                            throw new UnauthorizedError("OAuth refresh token was already spent; authorization required.");
+                        }
+                    }
+                    if (raw === null ||
+                        (plainObject(stored) && typeof stored.expiresAt === "number" && stored.expiresAt <= this.refreshNow())) {
+                        // Clock skew can replace an unsent claim; its dispatch CAS then loses.
+                        const claimed = JSON.stringify({
+                            connectaOAuthRefresh: 1,
+                            holder: crypto.randomUUID(),
+                            state: "claimed",
+                            expiresAt: this.refreshNow() + OAUTH_REFRESH_LEASE_SECONDS * 1000,
+                        });
+                        let won;
+                        try {
+                            won = await wait(() => this.storage.compareAndSet(key, raw, claimed));
+                        }
+                        catch {
+                            throw this.credentialWriteError();
+                        }
+                        if (won) {
+                            try {
+                                const latest = await wait(() => this.storedTokens());
+                                if (latest?.refresh_token !== requested || (latest && this.refreshedSinceRead(latest, epoch))) {
+                                    await wait(() => this.releaseRefresh({ key, spentKey, spentExpected, raw: claimed }));
+                                    return latest
+                                        ? this.adoptRefresh(latest)
+                                        : Response.json({ error: "invalid_grant" }, { status: 400 });
+                                }
+                                if (signal?.aborted)
+                                    throw aborted(signal);
+                                return { key, spentKey, spentExpected, raw: claimed };
+                            }
+                            catch (error) {
+                                // An unsent claim can expire safely. A caller that has left must
+                                // settle its local flight without awaiting cleanup storage.
+                                if (!waiting.signal.aborted && !signal?.aborted) {
+                                    await wait(() => this.releaseRefresh({ key, spentKey, spentExpected, raw: claimed }));
+                                }
+                                throw error;
+                            }
+                        }
+                    }
+                }
+                await runEdge(Effect.raceAllFirst([
+                    Effect.sleep(delay),
+                    fromSignal(waiting.signal),
+                    ...(signal ? [fromSignal(signal)] : []),
+                ]));
+                delay = Math.min(250, delay * 2);
+            }
         }
-        const retired = mergeLineage(lineage, [
-            { generation: previous, retiredAt: now },
-        ]);
-        if (retired.length > MAX_CLEANUP_BACKLOG) {
-            throw new Error(`OAuth cleanup backlog for "${this.connectorId}" is full`);
+        catch (error) {
+            if (signal?.aborted)
+                throw aborted(signal);
+            if (!waiting.signal.aborted)
+                throw error;
         }
-        // Publish the complete inherited cleanup work under the prospective epoch
-        // before making that epoch active. A crash or later retry can therefore
-        // always recover the older namespaces without a storage prefix scan.
-        await this.publishLineage(active, retired);
-        // This is the one authoritative transition. From this point onward every
-        // old physical namespace is unreadable. There is deliberately no second
-        // "finalize" write: concurrent resets therefore cannot overwrite a newer
-        // reset's epoch after their cleanup finishes out of order.
-        // A rejection may follow a committed fence. Keep its lineage even when
-        // the answer is lost: the next reset must still find the retired grants.
-        // A manifest for an epoch that never activated is harmless residue.
-        await this.storage.set("oauth:generation", active);
-        this.refreshCoordinator?.retire(previous);
-        if (reusableClient && !this.signal?.aborted) {
-            // readValue opened the old physical key; writeValue seals the plaintext
-            // under the new one. Copying ciphertext would fail its AAD check.
-            this.captureGeneration(active);
-            await this.writeValue("oauth:client", reusableClient.value, (value) => JSON.stringify(value), reusableClient.issuer, undefined, this.clientBinding);
+        finally {
+            if (!sharedWait)
+                waiting.close();
         }
-        // Delete the generation just retired: its values, then the lineage it
-        // published, which the new epoch has copied. Then retry the newest few
-        // younger entries whose own cleanup failed. A generation's manifest is
-        // deleted only after all of its values, so a manifest still present means
-        // its cleanup did not finish (or a late writer recorded into it after it
-        // did); an absent one means there is nothing to retry. That keeps the
-        // 0.26.0 promise that the next reset retries a failed cleanup of the
-        // grant being retired, at a bounded cost: RETRY_PROBES reads, and a full
-        // cleanup only for generations that need one. Everything older waits for
-        // its grace to pass (see above).
-        const probed = retired
-            .filter((entry) => entry.generation !== previous && withinGrace(entry))
-            .sort((a, b) => b.retiredAt - a.retiredAt)
-            .slice(0, RETRY_PROBES)
-            .map((entry) => entry.generation);
-        const probes = await Promise.allSettled(probed.map((generation) => limit(() => this.storage.get(cleanupBacklogKey(generation)))));
-        const unfinished = probed.filter((_, index) => {
-            const probe = probes[index];
-            // A probe that could not read is retried rather than assumed clean.
-            return probe?.status !== "fulfilled" || probe.value !== null;
+        throw this.refreshContended();
+    }
+    /** @internal Only the successful claimed-to-dispatched CAS may send. */
+    async dispatchRefresh(lease, send, waiting) {
+        const stored = parsed(lease.raw);
+        const epoch = await waiting.run(() => this.flowEpoch());
+        const activeKey = oauthRefreshActiveKeys.holder(epoch, stored.holder);
+        await waiting.run(() => this.storage.set(activeKey, JSON.stringify({ connectaOAuthRefresh: 1 }), {
+            ttlSeconds: OAUTH_REFRESH_LEASE_SECONDS,
+        }));
+        const dispatched = JSON.stringify({ ...stored, state: "dispatched", activeKey });
+        const transition = this.storage.compareAndSet(lease.key, lease.raw, dispatched).then((won) => {
+            if (!won)
+                throw this.refreshContended();
+            lease.raw = dispatched;
+            if (waiting.signal.aborted)
+                throw aborted(waiting.signal);
+        });
+        void transition.catch(() => { });
+        await waiting.run(() => transition);
+        // One CAS owns the fingerprint across every epoch. Only a later consent
+        // that observed a resolved write may replace it. No TTL or deletion path.
+        lease.spentRaw = JSON.stringify({
+            connectaOAuthRefreshSpent: 1,
+            epoch,
+            holder: stored.holder,
+            activeKey,
+            state: "outstanding",
         });
-        const failure = firstRejection(await this.cleanupGenerations([previous, ...unfinished], limit));
-        // Keep the active manifest immutable for the epoch's whole lifetime, even
-        // after successful cleanup. A late old-epoch write can land after cleanup;
-        // if its self-delete fails, the next reset must still inherit the complete
-        // lineage without racing a manifest shrink/delete. The successor copies
-        // this manifest before activation and then removes this retired copy.
-        if (failure)
-            throw failure.reason;
+        const preparation = this.storage
+            .compareAndSet(lease.spentKey, lease.spentExpected, lease.spentRaw)
+            .catch(() => {
+            this.recordRefreshFailure({ kind: "dead" });
+            throw new UnauthorizedError("OAuth refresh dispatch could not be recorded; authorization required.");
+        })
+            .then((unspent) => {
+            if (!unspent) {
+                this.recordRefreshFailure({ kind: "dead" });
+                throw new UnauthorizedError("OAuth refresh token was already spent; authorization required.");
+            }
+            // A storage operation can finish after its waiter left. Never send from
+            // abandoned preparation, even if both CAS operations succeeded.
+            if (waiting.signal.aborted)
+                throw aborted(waiting.signal);
+            const sent = send();
+            sent.catch(() => { });
+            return { sent };
+        });
+        void preparation.catch(() => { });
+        const { sent } = await waiting.run(() => preparation);
+        return sent;
+    }
+    /** @internal Release by CAS after a commit or a classified failure. */
+    async releaseRefresh(lease, verdict, tokens, resolution = "ambiguous") {
+        const stored = parsed(lease.raw);
+        // Only an unsent claim may be removed. Dispatched outcomes never reopen it.
+        const next = stored.state === "claimed"
+            ? null
+            : JSON.stringify({
+                ...stored,
+                ...(tokens
+                    ? { completed: true, tokenDigest: await refreshTokensDigest(tokens) }
+                    : { verdict: { kind: "dead" } }),
+            });
+        // Verdicts contain fixed typed facts; no downstream causes or text.
+        if (verdict)
+            this.recordRefreshFailure(verdict);
+        await this.resolveRefreshSpent(lease, resolution);
+        const released = await this.storage.compareAndSet(lease.key, lease.raw, next).catch(() => false);
+        if (released && stored.activeKey)
+            await this.storage.delete(stored.activeKey).catch(() => { });
+    }
+    async resolveRefreshSpent(lease, state) {
+        try {
+            const raw = lease.spentRaw ?? (await this.storage.get(lease.spentKey));
+            const spent = storedRefreshSpent(raw);
+            const holder = parsed(lease.raw).holder;
+            if (spent?.state !== "outstanding" || spent.holder !== holder)
+                return;
+            // The timestamp belongs to this resolution write, never to dispatch.
+            // Consent copies the exact stored receipt, so wall clocks grant no sends.
+            await this.storage.compareAndSet(lease.spentKey, raw, JSON.stringify({
+                ...spent,
+                state,
+                ...(state === "resolved" ? { resolvedAt: Date.now() } : {}),
+            }));
+        }
+        catch {
+            // A lost resolution answer leaves outstanding or the durable outcome;
+            // either blocks replay until a later consent observes a resolved write.
+        }
     }
-    async invalidateCredentials(scope) {
-        const endsRefresh = scope === "all" || scope === "tokens";
+    /** @internal The same typed verdict for local and cross-isolate joiners. */
+    refreshVerdict() {
+        return this.refreshFailure;
+    }
+    /** @internal The grant's tokens as stored, in the flow's epoch. */
+    async storedTokens() {
+        return (await this.boundGrant()).body.tokens;
+    }
+    /** @internal True when a refresh landed after this flow's issuer-aware read. */
+    refreshedSinceRead(current, epoch) {
+        const basis = this.refreshBasis;
+        return basis !== undefined && basis.epoch === epoch && basis.accessToken !== current.access_token;
+    }
+    /** @internal The issuer this flow's issuer-aware read bound its refresh to. */
+    refreshIssuer(epoch) {
+        const basis = this.refreshBasis;
+        return basis?.epoch === epoch ? basis.issuer : undefined;
+    }
+    /** @internal Hand the SDK tokens already stored, so its save is not repeated. */
+    adoptRefresh(tokens) {
+        this.storedRefresh = tokens.access_token;
+        return tokenResponse(tokens);
+    }
+    /**
+     * @internal Store an accepted rotation in `epoch`, even after the request
+     * that redeemed it has left, unless a newer rotation, another server's
+     * grant, or another epoch is there now. A token response names no issuer:
+     * the one the refreshed grant was bound to is stamped here.
+     */
+    async storeRefresh(epoch, requested, tokens, issuer) {
+        for (let attempt = 0; attempt < MAX_GRANT_WRITES; attempt++) {
+            try {
+                const { raw, grant } = await this.readGrant();
+                if (grant.epoch !== epoch || (issuer !== undefined && grant.body.issuer !== issuer))
+                    return undefined;
+                if (grant.body.tokens?.refresh_token !== requested)
+                    return grant.body.tokens;
+                const committed = issuer !== undefined ? { ...tokens, issuer } : tokens;
+                const encoded = await this.encodeGrant({ ...grant, body: { ...grant.body, tokens: committed } });
+                if (await this.storage.compareAndSet(GRANT, raw, encoded))
+                    return committed;
+            }
+            catch {
+                // A failed or lost CAS answer may still have committed. Re-read the
+                // epoch and retry these in-memory tokens without another HTTP request.
+            }
+        }
+        throw this.credentialWriteError();
+    }
+    /**
+     * @internal Drop the tokens the authorization server just refused, only
+     * while the grant still holds that refresh token in `epoch`: a consent
+     * that completed meanwhile survives. Best effort: if storage fails, the
+     * next refresh is refused again and ends the same way.
+     */
+    async discardRefusedGrant(refreshToken, epoch) {
         try {
-            const generation = await this.writeGeneration();
-            if (scope === "all") {
-                await this.deleteAll([
-                    oauthValueStorageKey("oauth:client", generation),
-                    oauthValueStorageKey("oauth:tokens", generation),
-                    oauthValueStorageKey("oauth:verifier", generation),
-                    oauthValueStorageKey("oauth:discovery", generation),
-                ]);
+            await this.updateGrant((grant) => {
+                if (grant.body.tokens?.refresh_token !== refreshToken)
+                    return undefined;
+                const { tokens: _refused, ...body } = grant.body;
+                return { ...grant, body };
+            }, { epoch, quiet: true, commit: true });
+        }
+        catch {
+            // See above: a refusal that could not be recorded recurs, it does not hide.
+        }
+    }
+    // --- restart and disconnect ---------------------------------------------------
+    /**
+     * Replace the epoch, by one compare-and-set: the grant goes with it, and
+     * every flow bound to the old epoch fails at its next read or write. A
+     * forced restart may carry the registration forward (`carriableClient`);
+     * a disconnect leaves only its epoch, which no passive request leaves.
+     * Then the old epochs' consents are removed; that is hygiene, since their
+     * callbacks fail the epoch check anyway and the records expire.
+     */
+    resetAuthorization(operatorDisconnected = false, preserveClient = false) {
+        const reset = this.performReset(operatorDisconnected, preserveClient);
+        this.onReset?.(reset);
+        return reset;
+    }
+    /** Remove the local grant before a bounded, best-effort RFC 7009 request. */
+    disconnectAuthorization(send) {
+        const reset = this.performReset(true, false, send);
+        this.onReset?.(reset);
+        return reset;
+    }
+    async performReset(operatorDisconnected, preserveClient, revoke) {
+        const epoch = `${operatorDisconnected ? DISCONNECTED_EPOCH_PREFIX : ACTIVE_EPOCH_PREFIX}${crypto.randomUUID()}`;
+        for (let attempt = 0; attempt < MAX_GRANT_WRITES; attempt++) {
+            const { raw, grant } = await this.readGrant();
+            const carried = preserveClient && !operatorDisconnected ? this.carriableClient(grant) : undefined;
+            const encoded = await this.encodeGrant({ epoch, body: carried ?? {}, cleanupPending: true });
+            let written;
+            try {
+                written = await this.storage.compareAndSet(GRANT, raw, encoded);
             }
-            else if (scope === "client") {
-                await this.storage.delete(oauthValueStorageKey("oauth:client", generation));
+            catch {
+                throw this.credentialWriteError();
             }
-            else if (scope === "tokens") {
-                await this.storage.delete(oauthValueStorageKey("oauth:tokens", generation));
+            if (written) {
+                this.refreshCoordinator?.retire(grant.epoch);
+                try {
+                    await this.cleanupV2(encoded);
+                    await this.sweepConsents();
+                    await this.sweepRefreshLeases();
+                }
+                finally {
+                    if (revoke)
+                        await revokeDownstreamGrant(grant.body, revoke, this.clientOptions?.client);
+                }
+                return;
             }
-            else if (scope === "verifier") {
-                await this.storage.delete(oauthValueStorageKey("oauth:verifier", generation));
+        }
+        throw this.credentialWriteError();
+    }
+    /**
+     * Remove every consent of an epoch no longer live. The records are read
+     * before the epoch, and epochs never recur, so a consent whose epoch is not
+     * the live one then can never complete; each goes by compare-and-set
+     * against what was read. Best effort.
+     */
+    async sweepConsents() {
+        try {
+            const consents = [];
+            for (const key of await this.storage.list(oauthFlowKeys.prefix)) {
+                const raw = await this.storage.get(key);
+                if (raw !== null)
+                    consents.push([key, raw]);
             }
-            else if (scope === "discovery") {
-                await this.storage.delete(oauthValueStorageKey("oauth:discovery", generation));
+            const live = epochOf(await this.storage.get(GRANT));
+            for (const [key, raw] of consents) {
+                const flow = parsed(raw);
+                if (plainObject(flow) && flow.epoch === live)
+                    continue;
+                await this.storage.compareAndSet(key, raw, null);
             }
-            if (endsRefresh) {
-                this.failRefreshFlight(new Error("OAuth refresh invalidated credentials before tokens were saved."));
+        }
+        catch {
+            // Hygiene only: the epoch, not this, fences a stale consent.
+        }
+    }
+    async sweepRefreshLeases() {
+        try {
+            const records = [];
+            // A reset may sweep an old lease while its HTTP request is still live.
+            // Keep holder liveness until completion or its storage-owned TTL: spent
+            // records in later epochs still use it to distinguish live from crashed.
+            for (const key of await this.storage.list(oauthRefreshKeys.prefix)) {
+                const raw = await this.storage.get(key);
+                if (raw !== null)
+                    records.push([key, raw]);
+            }
+            const live = epochOf(await this.storage.get(GRANT));
+            for (const [key, raw] of records) {
+                if (!key.startsWith(`${oauthRefreshKeys.prefix}${live}:`)) {
+                    await this.storage.compareAndSet(key, raw, null);
+                }
             }
         }
-        catch (error) {
-            if (endsRefresh)
-                this.failRefreshFlight(error);
-            throw error;
+        catch {
+            // Stale dispatch records cannot grant credentials: epochs never recur.
         }
-        // The SDK invalidates after a refused refresh and then starts over, which
-        // on `invalid_client` means registering a new client. A passive request
-        // must not begin authorization, so it ends here, as auth_required.
-        if (!this.allowAuthorization && this.refreshFailure?.kind === "dead") {
-            throw this.authorizationRefused();
+    }
+    /**
+     * The registration a forced restart may carry into its new epoch, or
+     * nothing. It must be bound to a server (`issuer`) and registered under this
+     * connector's exact configuration, redirect URI, and client metadata
+     * (`binding`), in this owner's own grant. Never carried:
+     *
+     * - A URL-based client (`clientMetadataUrl`): nothing was registered, and
+     *   leaving it behind makes the SDK ask fresh metadata whether the server
+     *   still accepts one.
+     * - One whose `client_secret_expires_at` has passed (RFC 7591: zero means
+     *   never).
+     * - One a previous restart carried that has not since earned tokens. The
+     *   SDK builds a consent URL locally and sends nothing that could answer
+     *   `invalid_client`, and RFC 6749 section 4.1.2.1 forbids redirecting an
+     *   unknown client to the callback, so tokens are the only proof the server
+     *   still knows it. Without them the next restart registers again.
+     */
+    carriableClient(grant) {
+        const { issuer, client, tokens } = grant.body;
+        const clientId = client?.value.client_id;
+        const expiresAt = client?.value.client_secret_expires_at;
+        if (!this.clientBinding ||
+            issuer === undefined ||
+            !client ||
+            client.binding !== this.clientBinding ||
+            typeof clientId !== "string" ||
+            client.registrationPath === "cimd" ||
+            client.registrationPath === "static" ||
+            // Legacy records have no mechanism field: retain their conservative
+            // URL-client refusal, but never reinterpret a recorded DCR identity.
+            (client.registrationPath === undefined && clientId === this.clientMetadataUrl) ||
+            this.clientOptions?.client !== undefined ||
+            (typeof expiresAt === "number" && expiresAt > 0 && expiresAt * 1000 <= Date.now()) ||
+            (client.carried && !tokens)) {
+            return undefined;
         }
+        return {
+            issuer,
+            client: {
+                value: client.value,
+                binding: client.binding,
+                carried: true,
+                ...(client.registrationPath ? { registrationPath: client.registrationPath } : {}),
+            },
+        };
     }
 }