@open-everywhere/adapters 0.1.0

package/dist/agent/oe-oauth/token-vault.d.ts

@@ -0,0 +1,107 @@
+import type { EncryptedKvVault } from "@open-everywhere/core/agent/adapter-api.js";
+import { type OeOauthProviderConfig } from "./config.js";
+import { type OAuthFetch } from "./oauth-client.js";
+/** A subject a token is minted for — the service identity, or a specific user principal. */
+export type OeOauthSubject = {
+    readonly type: "user";
+    readonly id: string;
+} | {
+    readonly type: "app";
+};
+/** What one {@link OeOauthTokenVault.sweepExpiredPending} run looked at. The four counts
+ *  RECONCILE: `scanned` === `deleted` + `live` + `unreadable` + (rows another caller removed
+ *  between the listing and the delete). */
+interface PendingSweepReport {
+    /** Pending rows the enumeration returned. */
+    readonly scanned: number;
+    /** Rows destroyed — past `expiresAt` + the retention window. */
+    readonly deleted: number;
+    /** Rows KEPT because they may still complete (inside the window, or inside the grace). */
+    readonly live: number;
+    /** Rows KEPT because their record did not read, so their expiry could not be established. */
+    readonly unreadable: number;
+}
+export declare const CLAIM_LEASE_TTL_MS = 30000;
+/** Injectable seams — every live default is used byte-for-byte in production. */
+export interface OeOauthVaultDeps {
+    readonly vault?: EncryptedKvVault;
+    readonly fetch?: OAuthFetch;
+    readonly now?: () => number;
+    readonly newState?: () => string;
+    readonly newPkce?: () => {
+        readonly verifier: string;
+        readonly challenge: string;
+    };
+    /** The OE-owned callback redirect URI. Default: OE_PUBLIC_BASE_URL + the callback route path. */
+    readonly redirectUri?: () => string | undefined;
+    readonly pendingTtlMs?: number;
+    /** How long past `expiresAt` an unusable pending row is kept. Default {@link DEFAULT_PENDING_RETENTION_MS}. */
+    readonly pendingRetentionMs?: number;
+    readonly expirySkewMs?: number;
+    /** Mints the random, non-secret cross-process claim id. Default: `randomUUID`. */
+    readonly newClaimId?: () => string;
+    /** Backoff wait between a loser's poll iterations. Default: real `setTimeout`. Tests inject a
+     *  clock-advancing (timeout scenario) or microtask-yielding (concurrency scenario) stub. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * Read a `static-confidential` provider's CLIENT SECRET by ref through its broker — the one credential path
+     * every other stored secret takes. Read PER TOKEN CALL, so a rotated secret takes effect at once.
+     */
+    readonly resolveSecret?: (broker: string | undefined, ref: string) => Promise<string>;
+}
+declare function subjectKey(subject: OeOauthSubject): string;
+/**
+ * Construct a token vault over the configured providers. One instance is built at registration and
+ * shared, so the in-process single-flight lock (core withLock) coordinates all callers in the process.
+ */
+export declare function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProviderConfig>, deps?: OeOauthVaultDeps): {
+    subjectKey: typeof subjectKey;
+    /** {@link forget} — purge ONE provider's token record for a subject. */
+    forget: (providerRef: string, subject: OeOauthSubject) => Promise<boolean>;
+    /** {@link sweepExpiredPending} — destroy the expired pending-authorization rows. */
+    sweepExpiredPending: () => Promise<PendingSweepReport>;
+    /**
+     * Purge EVERY configured provider's token record for `subject` — only the vault knows the full set. A
+     * provider whose purge THROWS does not stop the others, and it rethrows only if every one failed.
+     */
+    forgetAll(subject: OeOauthSubject): Promise<number>;
+    /**
+     * (OPE-93) Cheap EXISTENCE probe: is there a stored token record for (provider, subject) RIGHT NOW?
+     * A local vault read only — never a mint, never a refresh. Existence is the right signal even if the
+     * access token is expired: the real mint path ({@link accessTokenFor}) refreshes it. A corrupt record
+     * counts as absent (mirrors the mint's readJson semantics — fail toward re-consent, never crash).
+     */
+    hasToken(providerRef: string, subject: OeOauthSubject): Promise<boolean>;
+    /**
+     * Start an interactive authorization: ensure the client, mint PKCE and an opaque state, persist the pending
+     * row, and return the URL. It ALSO sweeps the expired pending rows, LAST and best-effort.
+     */
+    startAuthorization(providerRef: string, subject: OeOauthSubject, options: {
+        readonly expiresInMs?: number;
+        readonly consent?: unknown;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Complete the callback: look up the pending record by `state`, exchange the `code`, store the
+     * tokens, and consume the pending row (single-use, verifier scrubbed). Returns the provider ref,
+     * the SUBJECT the row was bound for and whether that bind REPLACED an existing row — the three
+     * facts the callback route's `connector.credential_bound` audit row carries (OPE-1937). NEVER a
+     * token: the caller writes an audit row from this, and no token material may reach it.
+     * Throws on unknown/expired/consumed state or an exchange failure — the callback route renders it.
+     */
+    completeAuthorization(state: string, code: string): Promise<{
+        providerRef: string;
+        subject: OeOauthSubject;
+        rebound: boolean;
+        consent?: unknown;
+    }>;
+    /**
+     * Read-or-refresh the access token. The fast path returns a valid token with no lock; otherwise the two-layer
+     * single-flight runs — an in-process mutex, then a cross-process row CLAIM that elects ONE refresher.
+     */
+    accessTokenFor(providerRef: string, subject: OeOauthSubject): Promise<string>;
+};
+export type OeOauthTokenVault = ReturnType<typeof makeOeOauthTokenVault>;
+export {};
+//# sourceMappingURL=token-vault.d.ts.map

package/dist/agent/oe-oauth/token-vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-vault.d.ts","sourceRoot":"","sources":["../../../agent/oe-oauth/token-vault.ts"],"names":[],"mappings":"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"}

package/dist/agent/oe-oauth/token-vault.js

@@ -0,0 +1,498 @@
+// The own-rolled OAuth token vault — DCR client, pending-authorization and token records over core's
+// encrypted KV. Refresh is single-flight in-process AND cross-process, because the provider ROTATES tokens.
+import { encryptedKvVault, getSecretVia, OE_OAUTH_CALLBACK_PATH } from "@open-everywhere/core/agent/adapter-api.js";
+import { isStaticConfidential, OE_OAUTH_MODE_STATIC } from "./config.js";
+import { discoverEndpoints, registerClient, buildAuthorizationUrl, buildStaticAuthorizationUrl, exchangeCode, exchangeCodeConfidential, refreshToken, refreshTokenConfidential, revokeToken, revokeTokenConfidential, } from "./oauth-client.js";
+import { randomUUID } from "node:crypto";
+import { makePkce, makeState } from "./pkce.js";
+import { OeOauthNeedsConsentError, OeOauthNeedsReconsentError, OeOauthRefreshContendedError, isInvalidGrant } from "./errors.js";
+function isStaticClient(rec) {
+    return rec.mode === OE_OAUTH_MODE_STATIC;
+}
+const DEFAULT_PENDING_TTL_MS = 15 * 60 * 1000; // 15 min consent window
+const DEFAULT_EXPIRY_SKEW_MS = 60 * 1000; // refresh when within 60s of expiry
+// How long an expired pending row is KEPT before the sweep destroys it. Not a security window — completion
+// already refuses a row past `expiresAt` — it buys the true error, "authorization state expired".
+const DEFAULT_PENDING_RETENTION_MS = 60 * 60 * 1000;
+// A claim is a LEASE: the winner stamps it on the row with an atomic CAS and releases it. A claim older than
+// the lease TTL counts as abandoned and may be stolen, so a crashed winner never wedges the row.
+export const CLAIM_LEASE_TTL_MS = 30_000;
+// A LOSER never calls the token endpoint — it waits for the winner's rotated token and adopts it, then fails
+// closed with a retryable error. DELIBERATELY shorter than the lease, so it never steals a valid claim.
+const LOSER_WAIT_BUDGET_MS = 15_000;
+// Poll cadence while a loser waits for the winner's rotated token to land.
+const LOSER_POLL_MS = 250;
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function subjectKey(subject) {
+    return subject.type === "app" ? "app" : `user:${subject.id}`;
+}
+function defaultRedirectUri() {
+    const base = process.env.OE_PUBLIC_BASE_URL?.trim().replace(/\/+$/, "");
+    if (!base)
+        return undefined;
+    const withScheme = /^https?:\/\//i.test(base) ? base : `https://${base}`;
+    return `${withScheme}${OE_OAUTH_CALLBACK_PATH}`;
+}
+/**
+ * Construct a token vault over the configured providers. One instance is built at registration and
+ * shared, so the in-process single-flight lock (core withLock) coordinates all callers in the process.
+ */
+export function makeOeOauthTokenVault(providers, deps = {}) {
+    const vault = deps.vault ?? encryptedKvVault();
+    const doFetch = deps.fetch ?? ((input, init) => fetch(input, init));
+    const now = deps.now ?? Date.now;
+    const newState = deps.newState ?? makeState;
+    const newPkce = deps.newPkce ?? makePkce;
+    const redirectUriOf = deps.redirectUri ?? defaultRedirectUri;
+    const pendingTtl = deps.pendingTtlMs ?? DEFAULT_PENDING_TTL_MS;
+    const pendingRetention = deps.pendingRetentionMs ?? DEFAULT_PENDING_RETENTION_MS;
+    const skew = deps.expirySkewMs ?? DEFAULT_EXPIRY_SKEW_MS;
+    const newClaimId = deps.newClaimId ?? (() => randomUUID());
+    const sleep = deps.sleep ?? realSleep;
+    const resolveSecret = deps.resolveSecret ?? ((broker, ref) => getSecretVia(broker, ref));
+    const dcrRef = (providerRef) => `oe-oauth:dcr:${providerRef}`;
+    const pendRef = (state) => `oe-oauth:pend:${state}`;
+    const tokRef = (providerRef, subject) => `oe-oauth:tok:${providerRef}:${subjectKey(subject)}`;
+    function providerConfig(providerRef) {
+        const cfg = providers.get(providerRef);
+        if (!cfg)
+            throw new Error(`connection "${providerRef}": no oe-oauth provider config (set OE_OAUTH_CONFIG / OE_OAUTH_NOTION_RESOURCE).`);
+        return cfg;
+    }
+    async function readJson(ref) {
+        const raw = await vault.read(ref);
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null; // a corrupt record is treated as absent — fail closed to re-consent, never crash a mint
+        }
+    }
+    /** True when {@link ensureDcrClient} should attempt a BACKFILL (OPE-1037) — re-run discovery and
+     *  merge what it learns onto an EXISTING record, never re-register. Only a field discovery alone
+     *  can supply belongs here; `clientId`/`registrationEndpoint` never change by this path. */
+    function dcrRecordNeedsBackfill(rec) {
+        return rec.revocationEndpoint === undefined;
+    }
+    /** Read-or-register the provider's DCR client, under the DCR-ref lock (no double registration).
+     *  Also BACKFILLS (OPE-1037): a record missing a field the adapter now understands is re-checked
+     *  against live discovery and merged, never re-registered — see the module header. */
+    async function ensureDcrClient(providerRef) {
+        const existing = await readJson(dcrRef(providerRef));
+        if (existing && !dcrRecordNeedsBackfill(existing))
+            return existing;
+        const cfg = providerConfig(providerRef);
+        // Unreachable through {@link ensureClient}, which routes a static provider away from this
+        // function entirely. Stated as a refusal rather than a cast so a future caller that reaches it
+        // directly gets an error instead of a discovery request built from an absent `resource`.
+        if (isStaticConfidential(cfg))
+            throw new Error(`connection "${providerRef}": declares the "${OE_OAUTH_MODE_STATIC}" mode, which registers no dynamic client.`);
+        return vault.withLock(dcrRef(providerRef), async () => {
+            const again = await readJson(dcrRef(providerRef));
+            if (again && !dcrRecordNeedsBackfill(again))
+                return again; // another caller already completed it
+            if (again) {
+                // BACKFILL, not registration: re-discover and merge the missing field(s) onto the record
+                // that is already there. Best-effort — a discovery failure or a server that genuinely
+                // publishes none must never block the mint the caller actually asked for.
+                try {
+                    const endpoints = await discoverEndpoints(cfg.resource, doFetch);
+                    if (endpoints.revocationEndpoint === undefined)
+                        return again; // this provider cannot be told
+                    const backfilled = { ...again, revocationEndpoint: endpoints.revocationEndpoint };
+                    await vault.write(dcrRef(providerRef), JSON.stringify(backfilled), { connector: providerRef });
+                    return backfilled;
+                }
+                catch (e) {
+                    console.warn(`[oe-oauth] DCR backfill discovery failed for "${providerRef}" (using the frozen record): ${e instanceof Error ? e.message : String(e)}`);
+                    return again;
+                }
+            }
+            const redirectUri = redirectUriOf();
+            if (!redirectUri) {
+                throw new Error(`connection "${providerRef}": OE_PUBLIC_BASE_URL is unset — cannot register a DCR client without a redirect_uri.`);
+            }
+            const endpoints = await discoverEndpoints(cfg.resource, doFetch);
+            const { clientId } = await registerClient(endpoints.registrationEndpoint, { clientName: cfg.clientName ?? "Open Everywhere", redirectUri, ...(cfg.scopes ? { scopes: cfg.scopes } : {}) }, doFetch);
+            const record = {
+                clientId,
+                authorizationEndpoint: endpoints.authorizationEndpoint,
+                tokenEndpoint: endpoints.tokenEndpoint,
+                registrationEndpoint: endpoints.registrationEndpoint,
+                ...(endpoints.revocationEndpoint ? { revocationEndpoint: endpoints.revocationEndpoint } : {}),
+                resource: cfg.resource,
+                ...(cfg.scopes ? { scopes: cfg.scopes } : {}),
+                registeredAt: now(),
+            };
+            await vault.write(dcrRef(providerRef), JSON.stringify(record), { connector: providerRef });
+            return record;
+        });
+    }
+    /** The client of a `static-confidential` provider, straight from config. NO network call, NO vault
+     *  read, NO vault write, NO lock — see the module header for why there is nothing to persist. */
+    function staticClient(cfg) {
+        return {
+            mode: OE_OAUTH_MODE_STATIC,
+            clientId: cfg.clientId,
+            authorizationEndpoint: cfg.authorizationEndpoint,
+            tokenEndpoint: cfg.tokenEndpoint,
+            ...(cfg.revocationEndpoint ? { revocationEndpoint: cfg.revocationEndpoint } : {}),
+            ...(cfg.scopes ? { scopes: cfg.scopes } : {}),
+            ...(cfg.authorizeParams ? { authorizeParams: cfg.authorizeParams } : {}),
+        };
+    }
+    /**
+     * The provider's client, in whichever dialect its config DECLARES. A static provider never reaches
+     * `ensureDcrClient`, so it never discovers, registers or writes a DCR row — the two share no network path.
+     */
+    async function ensureClient(providerRef) {
+        const cfg = providers.get(providerRef);
+        return cfg !== undefined && isStaticConfidential(cfg) ? staticClient(cfg) : ensureDcrClient(providerRef);
+    }
+    /**
+     * Resolve a static provider's confidential client, client secret included, for ONE token call.
+     *
+     * 🔴 THE ERROR NAMES THE REF, NEVER THE VALUE. A missing secret is the ordinary un-provisioned
+     * state (the operator has not run `oe secret set` yet), and it has to say which ref to fill —
+     * which is a config string, not secret material.
+     */
+    async function confidentialClientFor(cfg) {
+        const secret = await resolveSecret(cfg.clientSecretBroker, cfg.clientSecretRef);
+        if (typeof secret !== "string" || secret === "") {
+            throw new Error(`connection "${cfg.ref}": the OAuth client secret at ref "${cfg.clientSecretRef}" (broker "${cfg.clientSecretBroker}") has no stored value — ` +
+                `store it with \`oe secret set ${cfg.clientSecretRef}\` before this connection can mint a token.`);
+        }
+        return {
+            clientId: cfg.clientId,
+            clientSecret: secret,
+            bodyEncoding: cfg.bodyEncoding,
+            ...(cfg.tokenHeaders ? { headers: cfg.tokenHeaders } : {}),
+        };
+    }
+    /**
+     * Exchange the callback's `code` against ONE pending row, in the dialect that row was minted in.
+     * 🔴 The row's stamp and the live config must AGREE: a disagreement is REFUSED rather than resolved.
+     */
+    async function exchangeForPending(pending, code) {
+        // `providers.get`, not providerConfig: the discovery path never read the config here before this
+        // mode existed, and it must not start failing on a config-absent ref now. The drift check below
+        // therefore runs only when there IS a config to compare against.
+        const cfg = providers.get(pending.providerRef);
+        const startedStatic = pending.mode === OE_OAUTH_MODE_STATIC;
+        if (cfg !== undefined && isStaticConfidential(cfg) !== startedStatic) {
+            throw new Error(`connection "${pending.providerRef}": this authorization started as ${startedStatic ? "a static confidential client" : "a public PKCE client"}, ` +
+                `but the provider config no longer declares that mode — start again.`);
+        }
+        if (startedStatic) {
+            if (cfg === undefined || !isStaticConfidential(cfg)) {
+                throw new Error(`connection "${pending.providerRef}": no static confidential provider config, so the client that started this authorization cannot be resolved — start again.`);
+            }
+            return exchangeCodeConfidential(pending.tokenEndpoint, { code, redirectUri: pending.redirectUri }, await confidentialClientFor(cfg), doFetch);
+        }
+        if (!pending.resource)
+            throw new Error(`connection "${pending.providerRef}": this authorization record carries no resource indicator — start again.`);
+        return exchangeCode(pending.tokenEndpoint, { code, verifier: pending.pkceVerifier, clientId: pending.clientId, redirectUri: pending.redirectUri, resource: pending.resource }, doFetch);
+    }
+    function isExpired(rec) {
+        return rec.expiresAt !== undefined && now() >= rec.expiresAt - skew;
+    }
+    async function storeToken(providerRef, subject, tok, priorRefresh) {
+        const refresh = tok.refresh_token ?? priorRefresh; // keep the prior refresh if the server didn't rotate
+        const record = {
+            accessToken: tok.access_token,
+            ...(refresh ? { refreshToken: refresh } : {}),
+            ...(typeof tok.expires_in === "number" ? { expiresAt: now() + tok.expires_in * 1000 } : {}),
+            ...(tok.scope ? { scopes: tok.scope.split(/\s+/).filter(Boolean) } : {}),
+            obtainedAt: now(),
+        };
+        await vault.write(tokRef(providerRef, subject), JSON.stringify(record), { connector: providerRef });
+        return record;
+    }
+    /**
+     * PURGE one (provider, subject) record: vendor revocation FIRST, then the at-rest row. The ORDER makes a
+     * racing cross-process refresh benign; where a vendor cannot cascade, the access token lives out its TTL.
+     */
+    async function forget(providerRef, subject) {
+        const ref = tokRef(providerRef, subject);
+        return vault.withLock(ref, async () => {
+            const rec = await readJson(ref);
+            if (rec) {
+                // The client, in whichever dialect this provider declares. A STATIC provider's client comes
+                // from config — which is a read, not a registration, so the "never registers" rule above
+                // holds on both paths. `providers.get` rather than `providerConfig`: a purge must still
+                // destroy the row for a provider whose config an operator has already removed.
+                const cfg = providers.get(providerRef);
+                const client = cfg && isStaticConfidential(cfg) ? staticClient(cfg) : await readJson(dcrRef(providerRef));
+                // Prefer the REFRESH token: revoking it kills the whole grant family (RFC 7009 §2.1),
+                // whereas revoking an access token kills only that one.
+                const token = rec.refreshToken ?? rec.accessToken;
+                if (client?.revocationEndpoint && token) {
+                    try {
+                        const hint = rec.refreshToken ? "refresh_token" : "access_token";
+                        if (cfg && isStaticConfidential(cfg)) {
+                            await revokeTokenConfidential(client.revocationEndpoint, { token, tokenTypeHint: hint }, await confidentialClientFor(cfg), doFetch);
+                        }
+                        else {
+                            await revokeToken(client.revocationEndpoint, { token, clientId: client.clientId, tokenTypeHint: hint }, doFetch);
+                        }
+                    }
+                    catch (e) {
+                        // A vendor failure NEVER blocks the local delete — leaving a secret at rest with us
+                        // because someone else's server is down is the worse of the two outcomes. Message only:
+                        // the client's errors are built never to carry token material.
+                        console.warn(`[oe-oauth] revocation at the provider failed for "${providerRef}" (purging locally anyway): ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                }
+            }
+            // Runs even when there was no record to read (a corrupt/undecryptable envelope reads as null —
+            // readJson's fail-toward-reconsent semantics — and that row must still be destroyed).
+            return vault.delete(ref);
+        });
+    }
+    /**
+     * DESTROY the pending rows past `expiresAt` plus the retention grace: a row keyed by the opaque `state` can
+     * never be named again, yet an unconsumed one still holds its PKCE verifier. A row that will not READ is KEPT.
+     */
+    async function sweepExpiredPending() {
+        const refs = await vault.listRefs("oe-oauth:pend:");
+        let deleted = 0;
+        let live = 0;
+        let unreadable = 0;
+        for (const ref of refs) {
+            // The read is guarded PER ROW. `readJson` swallows a JSON parse failure but NOT a decrypt
+            // failure: `vault.read` THROWS on an undecryptable envelope (a tampered blob, or an AES key
+            // rotated out from under the row). Unguarded, ONE such row would abort the whole sweep — and
+            // because the mint calls this best-effort, the abort would be swallowed and the sweep would
+            // silently do nothing from then on. A row we cannot read is the case this loop must survive,
+            // not the case that stops it.
+            let rec;
+            try {
+                rec = await readJson(ref);
+            }
+            catch {
+                unreadable++;
+                continue;
+            }
+            if (!rec || typeof rec.expiresAt !== "number" || !Number.isFinite(rec.expiresAt)) {
+                unreadable++;
+                continue;
+            }
+            if (now() <= rec.expiresAt + pendingRetention) {
+                live++;
+                continue;
+            }
+            if (await vault.delete(ref))
+                deleted++;
+        }
+        return { scanned: refs.length, deleted, live, unreadable };
+    }
+    return {
+        subjectKey,
+        /** {@link forget} — purge ONE provider's token record for a subject. */
+        forget,
+        /** {@link sweepExpiredPending} — destroy the expired pending-authorization rows. */
+        sweepExpiredPending,
+        /**
+         * Purge EVERY configured provider's token record for `subject` — only the vault knows the full set. A
+         * provider whose purge THROWS does not stop the others, and it rethrows only if every one failed.
+         */
+        async forgetAll(subject) {
+            let purged = 0;
+            let failures = 0;
+            let lastError;
+            for (const providerRef of providers.keys()) {
+                try {
+                    if (await forget(providerRef, subject))
+                        purged++;
+                }
+                catch (e) {
+                    failures++;
+                    lastError = e;
+                }
+            }
+            if (failures > 0 && purged === 0 && failures === providers.size)
+                throw lastError;
+            return purged;
+        },
+        /**
+         * (OPE-93) Cheap EXISTENCE probe: is there a stored token record for (provider, subject) RIGHT NOW?
+         * A local vault read only — never a mint, never a refresh. Existence is the right signal even if the
+         * access token is expired: the real mint path ({@link accessTokenFor}) refreshes it. A corrupt record
+         * counts as absent (mirrors the mint's readJson semantics — fail toward re-consent, never crash).
+         */
+        async hasToken(providerRef, subject) {
+            return (await readJson(tokRef(providerRef, subject))) !== null;
+        },
+        /**
+         * Start an interactive authorization: ensure the client, mint PKCE and an opaque state, persist the pending
+         * row, and return the URL. It ALSO sweeps the expired pending rows, LAST and best-effort.
+         */
+        async startAuthorization(providerRef, subject, options) {
+            const client = await ensureClient(providerRef);
+            const redirectUri = redirectUriOf();
+            if (!redirectUri)
+                throw new Error(`connection "${providerRef}": OE_PUBLIC_BASE_URL is unset — cannot build a redirect_uri.`);
+            const state = newState();
+            // A static confidential provider does NOT mint a PKCE pair. The mint is skipped rather than
+            // minted-and-discarded, so nothing writes a verifier this flow will never present.
+            const pkce = isStaticClient(client) ? { verifier: "", challenge: "" } : newPkce();
+            const pending = {
+                providerRef,
+                subject,
+                pkceVerifier: pkce.verifier,
+                tokenEndpoint: client.tokenEndpoint,
+                clientId: client.clientId,
+                ...(isStaticClient(client) ? { mode: OE_OAUTH_MODE_STATIC } : { resource: client.resource }),
+                redirectUri,
+                ...(client.scopes ? { scopes: client.scopes } : {}),
+                createdAt: now(),
+                expiresAt: now() + (options.expiresInMs ?? pendingTtl),
+                ...(options.consent ? { consent: options.consent } : {}),
+            };
+            await vault.write(pendRef(state), JSON.stringify(pending), { connector: providerRef });
+            const url = isStaticClient(client)
+                ? buildStaticAuthorizationUrl({
+                    authorizationEndpoint: client.authorizationEndpoint,
+                    clientId: client.clientId,
+                    redirectUri,
+                    state,
+                    ...(client.scopes ? { scopes: client.scopes } : {}),
+                    ...(client.authorizeParams ? { extraParams: client.authorizeParams } : {}),
+                })
+                : buildAuthorizationUrl({
+                    authorizationEndpoint: client.authorizationEndpoint,
+                    clientId: client.clientId,
+                    redirectUri,
+                    state,
+                    codeChallenge: pkce.challenge,
+                    resource: client.resource,
+                    ...(client.scopes ? { scopes: client.scopes } : {}),
+                });
+            try {
+                await sweepExpiredPending();
+            }
+            catch (e) {
+                console.warn(`[oe-oauth] the expired-pending sweep failed (the authorization URL is unaffected): ${e instanceof Error ? e.message : String(e)}`);
+            }
+            return { url };
+        },
+        /**
+         * Complete the callback: look up the pending record by `state`, exchange the `code`, store the
+         * tokens, and consume the pending row (single-use, verifier scrubbed). Returns the provider ref,
+         * the SUBJECT the row was bound for and whether that bind REPLACED an existing row — the three
+         * facts the callback route's `connector.credential_bound` audit row carries (OPE-1937). NEVER a
+         * token: the caller writes an audit row from this, and no token material may reach it.
+         * Throws on unknown/expired/consumed state or an exchange failure — the callback route renders it.
+         */
+        async completeAuthorization(state, code) {
+            const pending = await readJson(pendRef(state));
+            if (!pending)
+                throw new Error("unknown or expired authorization state");
+            if (pending.consumed)
+                throw new Error("authorization state already used");
+            if (now() > pending.expiresAt)
+                throw new Error("authorization state expired");
+            const tok = await exchangeForPending(pending, code);
+            // 🔴 READ BEFORE THE WRITE. `storeToken` writes the row unconditionally (last-write-wins), so the
+            // only moment the REBIND is observable is here, before it. A second admin replacing the app row
+            // every routine spends is the case this flag exists to make visible.
+            // 🔴 AND IT IS A READ-BEFORE-WRITE WITH NO CROSS-PROCESS LOCK, so say what it proves. This method
+            // takes no lock at all, and `withLock` is a per-key IN-PROCESS mutex — two callbacks landing on
+            // separate instances for one subject can both read `null` and both report `false`, though one of
+            // them did replace the other. A SERIAL second consent, which is the case the row exists for,
+            // always reports `true`. Closing the window needs a compare-and-set write in the store, not here.
+            const rebound = (await readJson(tokRef(pending.providerRef, pending.subject))) !== null;
+            await storeToken(pending.providerRef, pending.subject, tok);
+            // Consume single-use + scrub the verifier (defeats replay; the verifier is spent).
+            // (OPE-1619) SCRUB THE CARRIAGE HERE TOO, for the same reason and at the same moment. It was
+            // spent the instant it was handed back below, and it holds a room id, a thread id, a
+            // principal id and a paused-session id — data with no remaining purpose. Leaving it until
+            // `sweepExpiredPending` collects the row would keep one person's conversation addresses at
+            // rest for the whole retention window past their last use.
+            await vault.write(pendRef(state), JSON.stringify({ ...pending, consumed: true, pkceVerifier: "", consent: undefined }), { connector: pending.providerRef });
+            // (OPE-1619) Hand the carriage back verbatim. The three refusals above run FIRST, so a consent
+            // that arrives on an unknown, spent or EXPIRED state returns no carriage at all — there is
+            // nothing for the return hop to resume from, which is where "past the TTL, a fresh ask" is
+            // enforced at its root rather than by a second check downstream.
+            return { providerRef: pending.providerRef, subject: pending.subject, rebound, ...(pending.consent ? { consent: pending.consent } : {}) };
+        },
+        /**
+         * Read-or-refresh the access token. The fast path returns a valid token with no lock; otherwise the two-layer
+         * single-flight runs — an in-process mutex, then a cross-process row CLAIM that elects ONE refresher.
+         */
+        async accessTokenFor(providerRef, subject) {
+            const ref = tokRef(providerRef, subject);
+            const fast = await readJson(ref);
+            if (!fast)
+                throw new OeOauthNeedsConsentError(providerRef, subject);
+            if (!isExpired(fast))
+                return fast.accessToken;
+            return vault.withLock(ref, async () => {
+                const rec = await readJson(ref);
+                if (!rec)
+                    throw new OeOauthNeedsConsentError(providerRef, subject);
+                if (!isExpired(rec))
+                    return rec.accessToken; // an in-process winner already refreshed
+                if (!rec.refreshToken)
+                    throw new OeOauthNeedsReconsentError(providerRef, subject, "no refresh token stored");
+                const presentedRefresh = rec.refreshToken;
+                // Layer 2 — CROSS-PROCESS single-flight. The in-process mutex above serialises THIS process;
+                // the atomic row-claim serialises across processes/instances (advisory locks are unusable over
+                // the pooled, session-less PgClient — see the kv-vault module doc). Exactly one claimant refreshes.
+                const claimId = newClaimId();
+                const won = await vault.claim(ref, claimId, now(), CLAIM_LEASE_TTL_MS);
+                if (won) {
+                    try {
+                        // `providers.get`, not providerConfig — see {@link ensureClient}: a discovery refresh
+                        // must still resolve from a complete DCR record when the config entry is absent.
+                        const cfg = providers.get(providerRef);
+                        let tok;
+                        try {
+                            // The dialect decides the refresh call and nothing else about this block. A static
+                            // provider takes no discovery hop and no DCR read on its way here.
+                            if (cfg !== undefined && isStaticConfidential(cfg)) {
+                                tok = await refreshTokenConfidential(cfg.tokenEndpoint, { refreshToken: presentedRefresh, ...(cfg.scopes ? { scopes: cfg.scopes } : {}) }, await confidentialClientFor(cfg), doFetch);
+                            }
+                            else {
+                                const client = await ensureDcrClient(providerRef);
+                                tok = await refreshToken(client.tokenEndpoint, { refreshToken: presentedRefresh, clientId: client.clientId, resource: client.resource, ...(client.scopes ? { scopes: client.scopes } : {}) }, doFetch);
+                            }
+                        }
+                        catch (e) {
+                            if (isInvalidGrant(e)) {
+                                // Last-resort net: another process rotated in the sliver before we claimed (or a stale
+                                // lease let two refresh). If the stored refresh token advanced and the access token is
+                                // fresh, adopt it instead of bricking the grant.
+                                const rec2 = await readJson(ref);
+                                if (rec2 && !isExpired(rec2) && rec2.refreshToken !== rec.refreshToken)
+                                    return rec2.accessToken;
+                                throw new OeOauthNeedsReconsentError(providerRef, subject, "refresh token rejected (invalid_grant)");
+                            }
+                            throw e;
+                        }
+                        const stored = await storeToken(providerRef, subject, tok, rec.refreshToken);
+                        return stored.accessToken;
+                    }
+                    finally {
+                        await vault.releaseClaim(ref, claimId);
+                    }
+                }
+                // Lost the claim — a live winner (another instance) is refreshing. Do NOT touch the token
+                // endpoint (presenting the consumed refresh token would trip reuse detection). Wait for the
+                // winner's rotated token to land and adopt it; bound the wait and fail closed on timeout.
+                const deadline = now() + LOSER_WAIT_BUDGET_MS;
+                for (;;) {
+                    const rec2 = await readJson(ref);
+                    if (rec2 && !isExpired(rec2))
+                        return rec2.accessToken; // adopted the winner's fresh token
+                    if (now() >= deadline)
+                        throw new OeOauthRefreshContendedError(providerRef, subject);
+                    await sleep(LOSER_POLL_MS);
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=token-vault.js.map