@zackbart/connecta 0.24.4 → 0.25.0

package/dist/auth/downstream-oauth.js

@@ -1,4 +1,8 @@
 import { UnauthorizedError } from "@modelcontextprotocol/client";
+import { Deferred, Effect } from "effect";
+import { retryAfterMs } from "../connectors/guarded-fetch.js";
+import { ConnectorCallError } from "../errors.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);
@@ -27,6 +31,19 @@ const OAUTH_VALUE_KEYS = [
     "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;
 const MAX_CLEANUP_BACKLOG = 1_000;
 function isRefreshTokenRequest(init) {
     if ((init?.method ?? "GET").toUpperCase() !== "POST")
@@ -101,15 +118,103 @@ async function readRefreshResponse(response) {
         reader.releaseLock();
     }
 }
+/** 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;
+}
+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 } : {}),
+    };
+}
+/** 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 });
+}
+/** 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 } } : {}),
+    });
+}
 /**
  * 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) {
-        return { failure: new Error(`OAuth refresh failed with HTTP ${response.status}.`) };
+        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 {
@@ -118,11 +223,26 @@ async function refreshResponseOutcome(response) {
     catch (error) {
         if (error instanceof OversizedRefreshResponse)
             throw error;
-        return { failure: new Error("OAuth refresh response did not contain JSON tokens.") };
+        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),
+        };
     }
-    return sdkAcceptsOAuthTokens(parsed)
-        ? { tokens: parsed }
-        : { failure: new Error("OAuth refresh response did not match the token schema.") };
+    return {
+        failure: new Error("OAuth refresh response did not match the token schema."),
+        verdict: transientFailure("answered without a token response", response),
+        forSdk: response,
+    };
 }
 function refreshMutationPendingResponse() {
     return Response.json({
@@ -131,42 +251,62 @@ function refreshMutationPendingResponse() {
     }, { status: 503 });
 }
 function aborted(signal) {
-    return (signal.reason ?? new DOMException("This operation was aborted", "AbortError"));
+    return (signal?.reason ?? new DOMException("This operation was aborted", "AbortError"));
 }
-async function waitForRefreshFlight(flight, signal) {
-    let outcome;
-    if (!signal) {
-        outcome = await flight.done;
-    }
-    else {
-        outcome = await new Promise((resolve, reject) => {
-            let settled = false;
-            const finish = (settle) => {
-                if (settled)
-                    return;
-                settled = true;
-                signal.removeEventListener("abort", onAbort);
-                settle();
-            };
-            const onAbort = () => finish(() => reject(aborted(signal)));
-            signal.addEventListener("abort", onAbort, { once: true });
-            void flight.done.then((result) => finish(() => resolve(result)));
-            // Abort may land between the caller's check and listener registration.
-            if (signal.aborted)
-                onAbort();
-        });
-    }
-    if (outcome.status === "failed")
-        throw outcome.error;
-    return outcome;
+/**
+ * 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;
+}
+/**
+ * The outcome of a flight another request owns, failures included. Rejects
+ * only with this caller's own abort.
+ *
+ * This wait is a Promise edge of its own, and the caller's storage reads stay
+ * outside it, on purpose. The owner settles the Deferred from its own request,
+ * and Deferred resumes a waiting fiber synchronously inside that call — on
+ * Workers, inside the owner's I/O context. Resolving this caller's promise
+ * 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) {
+    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);
 }
 /**
  * Share one rotating-token redemption within one connector runtime and OAuth
- * generation. The first request still owns the real fetch and response. Its
- * abort signal has one bounded listener until the exact flight settles, so a
- * cancellation after the response cannot strand waiters during token storage.
- * Followers wait for that provider to save tokens, then re-read storage. The
- * map never retains a token response or transport.
+ * 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.
  *
  * This is intentionally runtime-local. KVStorage has no atomic coordination
  * operation, so a second isolate can still race the same refresh token.
@@ -203,7 +343,8 @@ export class OAuthRefreshCoordinator {
         this.flights.delete(generation);
         this.advanceStateRevision();
         flight.stopObservingOwnerAbort();
-        flight.release(outcome);
+        // Last, because joined fibers resume inside this call.
+        Deferred.doneUnsafe(flight.outcome, Effect.succeed(outcome));
     }
     markMutationPending(generation, flight) {
         if (this.flights.get(generation) !== flight)
@@ -233,6 +374,8 @@ export class OAuthRefreshCoordinator {
             // adopted inner promise as an unhandled rejection.
             if (!isRefreshTokenRequest(init))
                 return await baseFetch(input, init);
+            // 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")
@@ -289,6 +432,12 @@ export class OAuthRefreshCoordinator {
                 }
                 if (existing) {
                     const outcome = await waitForRefreshFlight(existing, requestSignal);
+                    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
@@ -300,12 +449,12 @@ export class OAuthRefreshCoordinator {
                     }
                     continue;
                 }
-                let release;
+                // An owner that has already left never publishes a flight, and never
+                // reaches the token endpoint.
+                if (requestSignal?.aborted)
+                    throw aborted(requestSignal);
                 const flight = {
-                    done: new Promise((resolve) => {
-                        release = resolve;
-                    }),
-                    release: (outcome) => release(outcome),
+                    outcome: Deferred.makeUnsafe(),
                     stopObservingOwnerAbort: () => { },
                     mutationId: {},
                     writing: false,
@@ -314,60 +463,89 @@ export class OAuthRefreshCoordinator {
                 this.flights.set(generation, flight);
                 this.advanceStateRevision();
                 provider.captureRefreshFlight(generation, flight);
-                if (requestSignal) {
-                    let observing = true;
-                    const onOwnerAbort = () => {
-                        this.fail(generation, flight, aborted(requestSignal));
-                    };
-                    flight.stopObservingOwnerAbort = () => {
-                        if (!observing)
-                            return;
-                        observing = false;
-                        requestSignal.removeEventListener("abort", onOwnerAbort);
-                    };
-                    requestSignal.addEventListener("abort", onOwnerAbort, { once: true });
-                    // Abort may land between flight publication and listener registration.
-                    if (requestSignal.aborted)
-                        onOwnerAbort();
-                }
-                try {
+                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);
-                    // Failed responses never reach a successful saveTokens callback. Give
-                    // current waiters a bounded failure now while leaving the owner's
-                    // response untouched for the SDK to parse and classify itself.
-                    const outcome = await refreshResponseOutcome(response);
+                    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) {
-                        this.fail(generation, flight, outcome.failure);
-                        return response;
+                        // 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 ?? currentTokens?.refresh_token;
-                    flight.acceptedTokens = {
+                    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.
-                        void flight.persist?.(flight.acceptedTokens).catch(() => { });
-                        throw new Error("OAuth refresh ended before tokens could be saved.");
+                        detach(Effect.promise(() => flight.persist(accepted)));
+                        return Effect.fail(new Error("OAuth refresh ended before tokens could be saved."));
                     }
-                    if (requestSignal?.aborted) {
-                        // Same recovery as an abort landing later: `fail` persists.
-                        this.fail(generation, flight, aborted(requestSignal));
-                        throw aborted(requestSignal);
+                    // 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 response;
-                }
-                catch (error) {
-                    this.fail(generation, flight, error);
-                    throw error;
-                }
+                    return Effect.succeed(response);
+                };
+                // 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(commit)));
+                })), 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);
+                    this.fail(generation, flight, error, verdict);
+                    return Effect.fail(error);
+                }), Effect.flatMap(commit)));
+                return await runEdge(requestSignal
+                    ? Effect.raceAllFirst([
+                        redemption,
+                        fromSignal(requestSignal),
+                    ])
+                    : redemption);
             }
             return refreshMutationPendingResponse();
         };
@@ -387,8 +565,12 @@ export class OAuthRefreshCoordinator {
         }
         this.settle(generation, flight, { status: "refreshed" });
     }
-    /** Give joined callers a fetch/flow failure, without rejecting the gate. */
-    fail(generation, flight, error) {
+    /**
+     * 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) {
@@ -404,23 +586,29 @@ export class OAuthRefreshCoordinator {
         // provider still holds it; otherwise settle here once the write ends.
         const tokens = flight.acceptedTokens;
         if (tokens !== undefined &&
-            flight.persist !== undefined &&
             this.pendingMutations.get(generation) === flight.mutationId) {
             flight.writing = true;
-            void flight.persist(tokens).then(() => {
-                if (this.finishMutation(generation, flight)) {
-                    this.settle(generation, flight, { status: "refreshed" });
-                }
-            }, (writeError) => {
+            const written = (outcome) => {
                 if (this.finishMutation(generation, flight)) {
-                    this.settle(generation, flight, { status: "failed", error: writeError });
+                    this.settle(generation, flight, outcome);
                 }
-            });
+            };
+            detach(Effect.tryPromise({
+                try: () => flight.persist(tokens),
+                catch: (writeError) => writeError,
+            }).pipe(Effect.match({
+                onSuccess: () => written({ status: "refreshed" }),
+                onFailure: (error) => written({ status: "failed", error }),
+            })));
             return;
         }
         // A response alone is not a write and must never strand the generation.
         this.finishMutation(generation, flight);
-        this.settle(generation, flight, { status: "failed", error });
+        this.settle(generation, flight, {
+            status: "failed",
+            error,
+            ...(verdict !== undefined ? { verdict } : {}),
+        });
     }
     /** Finish an exact failed credential write, then publish its failure. */
     failMutation(generation, flight, error) {
@@ -459,6 +647,13 @@ function legacyStoredOAuthValue(value) {
         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) ||
@@ -493,6 +688,7 @@ export class KvOAuthProvider {
     redirectUri;
     refreshCoordinator;
     allowAuthorization;
+    sealer;
     /**
      * 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
@@ -500,14 +696,19 @@ export class KvOAuthProvider {
      */
     capturedGeneration = null;
     refreshFlight;
+    /** 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. */
     refreshBasis;
-    constructor(connectorId, storage, redirectUri, refreshCoordinator, allowAuthorization = true) {
+    constructor(connectorId, storage, redirectUri, refreshCoordinator, allowAuthorization = true, 
+    /** Present when the deployment's vault can seal; credentials are then ciphertext. */
+    sealer) {
         this.connectorId = connectorId;
         this.storage = storage;
         this.redirectUri = redirectUri;
         this.refreshCoordinator = refreshCoordinator;
         this.allowAuthorization = allowAuthorization;
+        this.sealer = sealer;
     }
     /**
      * Stamp the force-reauth generation the current connect flow started under.
@@ -525,6 +726,72 @@ export class KvOAuthProvider {
     captureRefreshFlight(generation, flight) {
         this.refreshFlight = { generation, flight };
     }
+    /**
+     * @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;
+    }
+    /**
+     * @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.
+     */
+    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);
+            }
+            else {
+                await this.storage.delete(physicalKey);
+            }
+        }
+        catch {
+            // See above: a refusal that could not be recorded recurs, it does not hide.
+        }
+    }
+    /**
+     * 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.
+     */
+    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 }
+                : {}),
+        });
+    }
     failRefreshFlight(error) {
         const owned = this.refreshFlight;
         this.refreshFlight = undefined;
@@ -559,21 +826,46 @@ export class KvOAuthProvider {
      */
     async writeValue(key, value, serializeLegacy, issuer) {
         const generation = await this.writeGeneration();
+        await this.storeInGeneration(key, generation, () => {
+            const stored = {
+                connectaOAuthVersion: STORED_VALUE_VERSION,
+                generation,
+                ...(issuer !== undefined ? { issuer } : {}),
+                value,
+            };
+            return isModernGeneration(generation) || issuer !== undefined
+                ? JSON.stringify(stored)
+                : serializeLegacy(value);
+        });
+    }
+    /**
+     * 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) {
         if (generation.startsWith(RESETTING_GENERATION_PREFIX) ||
             generation.startsWith(DISCONNECTED_GENERATION_PREFIX) ||
             (await this.generation()) !== generation) {
             return;
         }
-        const stored = {
-            connectaOAuthVersion: STORED_VALUE_VERSION,
-            generation,
-            ...(issuer !== undefined ? { issuer } : {}),
-            value,
-        };
         const physicalKey = oauthValueStorageKey(key, generation);
-        await this.storage.set(physicalKey, isModernGeneration(generation) || issuer !== undefined
-            ? JSON.stringify(stored)
-            : serializeLegacy(value));
+        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 (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.
@@ -595,21 +887,85 @@ export class KvOAuthProvider {
             }
         }
     }
+    /**
+     * 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);
+        }
+        if ((await this.storage.get(physicalKey)) !== expected)
+            return false;
+        await this.storage.set(physicalKey, next);
+        return true;
+    }
+    /**
+     * 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;
+        }
+    }
+    /**
+     * 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.`);
+        }
+    }
     /**
      * 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.
+     * 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);
+        }
+        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 raw = await this.storage.get(oauthValueStorageKey(key, 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);
@@ -617,6 +973,27 @@ export class KvOAuthProvider {
         catch {
             // Raw string state from a pre-envelope deployment is handled below.
         }
+        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);
+            }
+            catch {
+                // A sealed raw legacy string, handled below like its plaintext form.
+            }
+        }
+        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
                 ? {
@@ -758,6 +1135,7 @@ export class KvOAuthProvider {
             await this.writeValue("oauth:tokens", tokens, (value) => JSON.stringify(value), ctx?.issuer);
             if (coordinated)
                 this.refreshCoordinator?.succeedMutation(owned.generation, owned.flight);
+            this.refreshFailure = undefined;
         }
         catch (error) {
             if (coordinated)
@@ -782,7 +1160,7 @@ export class KvOAuthProvider {
      */
     async state() {
         if (!this.allowAuthorization)
-            throw new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
+            throw this.authorizationRefused();
         const value = randomState();
         await this.writeValue("oauth:state", value, (raw) => raw);
         return value;
@@ -802,7 +1180,7 @@ export class KvOAuthProvider {
     }
     async saveCodeVerifier(verifier) {
         if (!this.allowAuthorization)
-            throw new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
+            throw this.authorizationRefused();
         await this.writeValue("oauth:verifier", verifier, (raw) => raw);
     }
     async codeVerifier() {
@@ -815,7 +1193,7 @@ export class KvOAuthProvider {
     async redirectToAuthorization(authorizationUrl) {
         try {
             if (!this.allowAuthorization)
-                throw new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
+                throw this.authorizationRefused();
             await this.writeValue("oauth:pending", authorizationUrl.toString(), (raw) => raw);
             this.failRefreshFlight(new Error("OAuth refresh required reauthorization before tokens were saved."));
         }
@@ -952,5 +1330,11 @@ export class KvOAuthProvider {
                 this.failRefreshFlight(error);
             throw error;
         }
+        // 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();
+        }
     }
 }