@open-everywhere/adapters 0.6.0 → 0.8.0

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

@@ -1,14 +1,25 @@
 // 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 { agentDisplayName, 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 { agentDisplayName, checkXaaIdentityBinding, encryptedKvVault, recordXaaRefusal, getSecretVia, OE_OAUTH_CALLBACK_PATH, verifyOidcIdToken, } from "@open-everywhere/core/agent/adapter-api.js";
+import { isStaticConfidential, isXaa, OE_OAUTH_MODE_STATIC, OE_OAUTH_MODE_XAA, } from "./config.js";
+import { discoverEndpoints, registerClient, buildAuthorizationUrl, buildStaticAuthorizationUrl, exchangeCode, exchangeCodeConfidential, refreshToken, refreshTokenConfidential, revokeToken, revokeTokenConfidential, discoverOidc, fetchJwks, requestIdJag, jwtBearerGrant, } from "./oauth-client.js";
+import { createHash, randomUUID } from "node:crypto";
 import { makePkce, makeState } from "./pkce.js";
-import { OeOauthNeedsConsentError, OeOauthNeedsReconsentError, OeOauthRefreshContendedError, isInvalidGrant } from "./errors.js";
+import { OeOauthAccessRemovedError, OeOauthNeedsConsentError, OeOauthNeedsReconsentError, OeOauthRefreshContendedError, isInvalidGrant } from "./errors.js";
 function isStaticClient(rec) {
     return rec.mode === OE_OAUTH_MODE_STATIC;
 }
+/** The IdP scopes the Cross App Access sign-in asks for: an id token (`openid`) and a refresh token to exchange
+ *  (`offline_access`). Fixed — the app's own scopes ride leg 1 and leg 2, never this sign-in. */
+const XAA_IDP_SCOPES = ["openid", "offline_access"];
+/** RFC 6749 / 8693 error codes that mean the IdP REFUSED this person's ID-JAG on policy (the admin removed the
+ *  pairing or the assignment). `invalid_grant` is NOT here: it means the IdP sign-in itself lapsed, and a new
+ *  sign-in fixes that. */
+const XAA_IDP_REFUSALS = new Set(["access_denied", "unauthorized_client", "invalid_target"]);
+/** Error codes that mean the APP refused the ID-JAG for this person. No new sign-in fixes these. */
+const XAA_APP_REFUSALS = new Set(["invalid_grant", "access_denied", "unauthorized_client"]);
+/** How long a discovered OIDC document is reused before it is fetched again. */
+const OIDC_DISCOVERY_TTL_MS = 60 * 60 * 1000;
 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
@@ -51,9 +62,17 @@ export function makeOeOauthTokenVault(source, deps = {}) {
     const newClaimId = deps.newClaimId ?? (() => randomUUID());
     const sleep = deps.sleep ?? realSleep;
     const resolveSecret = deps.resolveSecret ?? ((broker, ref) => getSecretVia(broker, ref));
+    const newNonce = deps.newNonce ?? makeState;
+    const verifyIdToken = deps.verifyIdToken ?? verifyOidcIdToken;
+    const bindIdentity = deps.bindIdentity ?? checkXaaIdentityBinding;
+    const recordRefusal = deps.recordRefusal ?? recordXaaRefusal;
     const dcrRef = (providerRef) => `oe-oauth:dcr:${providerRef}`;
     const pendRef = (state) => `oe-oauth:pend:${state}`;
     const tokRef = (providerRef, subject) => `oe-oauth:tok:${providerRef}:${subjectKey(subject)}`;
+    // The IdP grant is keyed by the IdP CLIENT (issuer + client id), not by the connection: every `xaa` connection
+    // that names the same IdP client shares one person's sign-in. Hashed so the ref carries no URL punctuation.
+    const idpKey = (cfg) => createHash("sha256").update(`${cfg.idpIssuer}\n${cfg.idpClientId}`).digest("hex").slice(0, 32);
+    const idpRef = (cfg, subject) => `oe-oauth:xaa-idp:${idpKey(cfg)}:${subjectKey(subject)}`;
     function providerConfig(providerRef) {
         const cfg = providersNow().get(providerRef);
         if (!cfg) {
@@ -91,6 +110,8 @@ export function makeOeOauthTokenVault(source, deps = {}) {
         // 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.`);
+        if (isXaa(cfg))
+            throw new Error(`connection "${providerRef}": declares the "${OE_OAUTH_MODE_XAA}" mode, which registers no dynamic client.`);
         return vault.withLock(dcrRef(providerRef), async () => {
             const again = await readJson(dcrRef(providerRef));
             if (again && !dcrRecordNeedsBackfill(again))
@@ -175,6 +196,263 @@ export function makeOeOauthTokenVault(source, deps = {}) {
             ...(cfg.tokenHeaders ? { headers: cfg.tokenHeaders } : {}),
         };
     }
+    /** A confidential client for one `xaa` leg, secret read through its broker PER CALL. The error names the ref. */
+    async function xaaClient(cfg, leg) {
+        const [clientId, secretRef, broker] = leg === "idp" ? [cfg.idpClientId, cfg.idpClientSecretRef, cfg.idpClientSecretBroker] : [cfg.resourceClientId, cfg.resourceClientSecretRef, cfg.resourceClientSecretBroker];
+        const secret = await resolveSecret(broker, secretRef);
+        if (typeof secret !== "string" || secret === "") {
+            throw new Error(`connection "${cfg.ref}": the ${leg === "idp" ? "identity-provider" : "app"} client secret at ref "${secretRef}" (broker "${broker}") has no stored value — ` +
+                `store it with \`oe secret set ${secretRef}\` before this connection can mint a token.`);
+        }
+        return { clientId, clientSecret: secret, bodyEncoding: "form" };
+    }
+    // The IdP's discovered endpoints, per issuer, reused for an hour: every mint's leg 1 needs the token endpoint,
+    // and a discovery hop per mint would double the IdP traffic for nothing.
+    const oidcCache = new Map();
+    async function oidcFor(cfg) {
+        const hit = oidcCache.get(cfg.idpIssuer);
+        if (hit && now() - hit.at < OIDC_DISCOVERY_TTL_MS)
+            return hit.endpoints;
+        const endpoints = await discoverOidc(cfg.idpIssuer, doFetch);
+        oidcCache.set(cfg.idpIssuer, { at: now(), endpoints });
+        return endpoints;
+    }
+    /** An `xaa` connection acts only AS A PERSON: the ID-JAG names a human. There is no service account to mint. */
+    function requireXaaPerson(providerRef, subject) {
+        if (subject.type !== "user") {
+            throw new Error(`connection "${providerRef}": the "${OE_OAUTH_MODE_XAA}" sign-in acts only as a person — it has no service account to mint for.`);
+        }
+    }
+    /**
+     * Start the person's IdP sign-in for an `xaa` connection: OIDC auth code with PKCE and a nonce, `openid` +
+     * `offline_access`. The pending row is the same shape as the other dialects', stamped `mode: "xaa"`.
+     */
+    async function xaaStartAuthorization(cfg, subject, options) {
+        requireXaaPerson(cfg.ref, subject);
+        const oidc = await oidcFor(cfg);
+        const redirectUri = redirectUriOf();
+        if (!redirectUri)
+            throw new Error(`connection "${cfg.ref}": OE_PUBLIC_BASE_URL is unset — cannot build a redirect_uri.`);
+        const state = newState();
+        const pkce = newPkce();
+        const nonce = newNonce();
+        const pending = {
+            providerRef: cfg.ref,
+            subject,
+            pkceVerifier: pkce.verifier,
+            tokenEndpoint: oidc.tokenEndpoint,
+            clientId: cfg.idpClientId,
+            mode: OE_OAUTH_MODE_XAA,
+            nonce,
+            redirectUri,
+            scopes: XAA_IDP_SCOPES,
+            createdAt: now(),
+            expiresAt: now() + (options.expiresInMs ?? pendingTtl),
+            ...(options.consent ? { consent: options.consent } : {}),
+        };
+        await vault.write(pendRef(state), JSON.stringify(pending), { connector: cfg.ref });
+        // The PKCE pair and the nonce ride `extraParams`: this function's own parameters (client_id, redirect_uri,
+        // state, scope) are applied after them and win, so nothing here can be overridden.
+        const url = buildStaticAuthorizationUrl({
+            authorizationEndpoint: oidc.authorizationEndpoint,
+            clientId: cfg.idpClientId,
+            redirectUri,
+            state,
+            scopes: XAA_IDP_SCOPES,
+            extraParams: { nonce, code_challenge: pkce.challenge, code_challenge_method: "S256" },
+        });
+        return { url };
+    }
+    /**
+     * Complete an `xaa` sign-in: exchange the code at the IdP, VERIFY the id token (signature, iss, aud, nonce), and
+     * admit the sign-in only when the identity-link plane confirms the IdP account is the requester's own. Then store
+     * the person's IdP refresh token as their IdP grant. A refusal SPENDS the link (the pending row is consumed).
+     */
+    async function xaaCompleteAuthorization(state, pending, code) {
+        const cfg = providersNow().get(pending.providerRef);
+        if (cfg === undefined || !isXaa(cfg) || cfg.idpClientId !== pending.clientId) {
+            throw new Error(`connection "${pending.providerRef}": this sign-in started under an "${OE_OAUTH_MODE_XAA}" declaration that no longer stands — start again.`);
+        }
+        const spend = () => vault.write(pendRef(state), JSON.stringify({ ...pending, consumed: true, pkceVerifier: "", nonce: "", consent: undefined }), { connector: pending.providerRef });
+        const tok = await exchangeCodeConfidential(pending.tokenEndpoint, { code, redirectUri: pending.redirectUri, codeVerifier: pending.pkceVerifier }, await xaaClient(cfg, "idp"), doFetch);
+        let signer;
+        try {
+            if (!tok.id_token)
+                throw new Error("the IdP returned no id token");
+            const oidc = await oidcFor(cfg);
+            signer = (await verifyIdToken(tok.id_token, { jwks: (await fetchJwks(oidc.jwksUri, doFetch)), issuer: cfg.idpIssuer, audience: cfg.idpClientId, nonce: pending.nonce ?? "" })).sub;
+        }
+        catch (e) {
+            await spend();
+            const reason = e instanceof Error ? e.message : String(e);
+            // Every refused attempt leaves one audit row — a forged or replayed id token most of all.
+            if (pending.subject.type === "user")
+                await recordRefusal({ principalSubject: pending.subject.id, connection: pending.providerRef, reason });
+            throw new Error(`connection "${pending.providerRef}": the identity-provider sign-in was refused — ${reason}.`);
+        }
+        if (pending.subject.type !== "user") {
+            await spend();
+            throw new Error(`connection "${pending.providerRef}": the "${OE_OAUTH_MODE_XAA}" sign-in acts only as a person.`);
+        }
+        // 🔴 THE BINDING. Whoever opened the link signed in; the grant is stored for the requester only when that IdP
+        // account is a CONFIRMED account of theirs. Otherwise one person could mint another person's app tokens.
+        const verdict = await bindIdentity({ principalSubject: pending.subject.id, signerSubject: signer, connection: pending.providerRef });
+        if (!verdict.ok) {
+            await spend();
+            throw new Error(`connection "${pending.providerRef}": the identity-provider sign-in was refused — ${verdict.reason}.`);
+        }
+        if (!tok.refresh_token) {
+            await spend();
+            await recordRefusal({ principalSubject: pending.subject.id, connection: pending.providerRef, reason: "the IdP returned no refresh token", signerSubject: verdict.idpNativeId });
+            throw new Error(`connection "${pending.providerRef}": the IdP returned no refresh token — the OE app at the IdP must allow the refresh-token grant and the offline_access scope.`);
+        }
+        const gRef = idpRef(cfg, pending.subject);
+        const rebound = (await readJson(gRef)) !== null;
+        const grant = { refreshToken: tok.refresh_token, idpSubject: verdict.idpNativeId, obtainedAt: now() };
+        await vault.write(gRef, JSON.stringify(grant), { connector: pending.providerRef });
+        await spend();
+        return { rebound };
+    }
+    /** The RFC 6749 `error` code an upstream failure carried, if any. */
+    function oauthErrorOf(e) {
+        const code = e?.oauthError;
+        return typeof code === "string" ? code.toLowerCase() : undefined;
+    }
+    /** ONE `xaa` mint, run by the claim winner: leg 1 at the IdP, leg 2 at the app, then cache the app token for its
+     *  lifetime. Never a refresh token from the app — a re-mint is the only refresh. */
+    async function xaaMint(cfg, providerRef, subject, grant) {
+        const oidc = await oidcFor(cfg);
+        const legParams = { ...(cfg.resource ? { resource: cfg.resource } : {}), ...(cfg.scopes ? { scopes: cfg.scopes } : {}) };
+        let idJag;
+        try {
+            idJag = await requestIdJag(oidc.tokenEndpoint, { subjectToken: grant.refreshToken, audience: cfg.audience, ...legParams }, await xaaClient(cfg, "idp"), doFetch);
+        }
+        catch (e) {
+            const code = oauthErrorOf(e);
+            if (code === "invalid_grant")
+                throw new OeOauthNeedsReconsentError(providerRef, subject, "the identity-provider sign-in is no longer valid (invalid_grant)");
+            if (code !== undefined && XAA_IDP_REFUSALS.has(code))
+                throw new OeOauthAccessRemovedError(providerRef, subject, "idp", code);
+            throw e;
+        }
+        let tok;
+        try {
+            tok = await jwtBearerGrant(cfg.resourceTokenEndpoint, { assertion: idJag, ...legParams }, await xaaClient(cfg, "app"), doFetch);
+        }
+        catch (e) {
+            const code = oauthErrorOf(e);
+            if (code !== undefined && XAA_APP_REFUSALS.has(code))
+                throw new OeOauthAccessRemovedError(providerRef, subject, "app", code);
+            throw e;
+        }
+        const { refresh_token: _ignored, ...withoutRefresh } = tok;
+        return (await storeToken(providerRef, subject, withoutRefresh)).accessToken;
+    }
+    /**
+     * Read-or-mint an `xaa` connection's app token. A cached token serves until its expiry (less the skew), so a
+     * person costs ONE mint per token lifetime — the IdP caps ID-JAGs per person per app per month. The CROSS-PROCESS
+     * claim sits on the person's IdP GRANT row (it always exists here; the app-token row may not yet), and a loser
+     * polls for the winner's token or for the claim to come free, bounded like the refresh path.
+     */
+    async function xaaAccessTokenFor(cfg, providerRef, subject) {
+        requireXaaPerson(providerRef, subject);
+        const ref = tokRef(providerRef, subject);
+        const fast = await readJson(ref);
+        if (fast && !isExpired(fast))
+            return fast.accessToken;
+        const gRef = idpRef(cfg, subject);
+        return vault.withLock(ref, async () => {
+            const deadline = now() + LOSER_WAIT_BUDGET_MS;
+            for (;;) {
+                const rec = await readJson(ref);
+                if (rec && !isExpired(rec))
+                    return rec.accessToken;
+                const grant = await readJson(gRef);
+                if (!grant)
+                    throw new OeOauthNeedsConsentError(providerRef, subject);
+                const claimId = newClaimId();
+                if (await vault.claim(gRef, claimId, now(), CLAIM_LEASE_TTL_MS)) {
+                    try {
+                        // Another process may have minted and released between our read and our claim: adopt its token.
+                        const won = await readJson(ref);
+                        if (won && !isExpired(won))
+                            return won.accessToken;
+                        // 🔴 RE-CHECK THE BINDING AT EACH MINT, not only at sign-in. An operator who revokes the `okta` link or
+                        // suspends the set must stop the minting at once; the stored grant alone would keep minting until the
+                        // IdP refresh token dies. The check runs per MINT (once per token lifetime), never per cached read.
+                        const still = await bindIdentity({ principalSubject: subject.id, signerSubject: grant.idpSubject, connection: providerRef, stage: "mint" });
+                        // An UNREADABLE link plane says nothing about the person: refuse this mint, keep the grant, and let a
+                        // retry succeed. Only a definite refusal (the link is gone) deletes the grant.
+                        if (!still.ok && still.unreadable) {
+                            throw new Error(`connection "${providerRef}": the identity-link plane could not be read, so the Okta grant could not be re-checked — retry.`);
+                        }
+                        if (!still.ok) {
+                            await vault.delete(gRef);
+                            throw new OeOauthNeedsConsentError(providerRef, subject);
+                        }
+                        return await xaaMint(cfg, providerRef, subject, grant);
+                    }
+                    finally {
+                        await vault.releaseClaim(gRef, claimId);
+                    }
+                }
+                if (now() >= deadline)
+                    throw new OeOauthRefreshContendedError(providerRef, subject);
+                await sleep(LOSER_POLL_MS);
+            }
+        });
+    }
+    /** How a failed IdP revocation is reported (OPE-2565): `idp:` and the issuer's host, the name an operator knows it by. */
+    function idpReportRef(cfg) {
+        try {
+            return `idp:${new URL(cfg.idpIssuer).host}`;
+        }
+        catch {
+            return "idp:";
+        }
+    }
+    /**
+     * Run one revocation call, and retry it ONCE on a failure (OPE-2565). A second failure is warned and handed to
+     * `onUnrevoked`, so the purge's caller records it: the row is deleted anyway, and the token stays valid at the
+     * provider until it expires. Never throws — a vendor failure never blocks the local delete.
+     */
+    async function revokeWithRetry(providerRef, call, onUnrevoked, what) {
+        for (let attempt = 1;; attempt++) {
+            try {
+                await call();
+                return;
+            }
+            catch (e) {
+                if (attempt < 2)
+                    continue;
+                // Message only: the client's errors are built never to carry token material.
+                console.warn(`[oe-oauth] ${what} failed twice for "${providerRef}" (purging locally anyway; the token stays valid there until it expires): ${e instanceof Error ? e.message : String(e)}`);
+                onUnrevoked?.(providerRef);
+                return;
+            }
+        }
+    }
+    /**
+     * Purge a person's IdP grant: revoke the IdP refresh token at the IdP (one retry), then delete the row. A failure
+     * is reported as `idp:<issuer host>`, never under the connection's ref: the token that stays valid is the IdP
+     * grant, which every `xaa` connection on that IdP shares, so naming the connection would send the operator to
+     * the wrong system.
+     */
+    async function forgetIdpGrant(cfg, subject, onUnrevoked) {
+        const gRef = idpRef(cfg, subject);
+        return vault.withLock(gRef, async () => {
+            const grant = await readJson(gRef);
+            if (grant) {
+                await revokeWithRetry(idpReportRef(cfg), async () => {
+                    const oidc = await oidcFor(cfg);
+                    if (oidc.revocationEndpoint) {
+                        await revokeTokenConfidential(oidc.revocationEndpoint, { token: grant.refreshToken, tokenTypeHint: "refresh_token" }, await xaaClient(cfg, "idp"), doFetch);
+                    }
+                }, onUnrevoked, "IdP revocation");
+            }
+            return vault.delete(gRef);
+        });
+    }
     /**
      * 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.
@@ -184,6 +462,9 @@ export function makeOeOauthTokenVault(source, deps = {}) {
         // 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 = providersNow().get(pending.providerRef);
+        if (cfg !== undefined && isXaa(cfg)) {
+            throw new Error(`connection "${pending.providerRef}": this authorization started under another dialect, but the provider config now declares "${OE_OAUTH_MODE_XAA}" — start again.`);
+        }
         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"}, ` +
@@ -217,8 +498,9 @@ export function makeOeOauthTokenVault(source, deps = {}) {
     /**
      * 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.
+     * A revocation call that fails is retried once; a second failure goes to `onUnrevoked` (OPE-2565).
      */
-    async function forget(providerRef, subject) {
+    async function forget(providerRef, subject, onUnrevoked) {
         const ref = tokRef(providerRef, subject);
         return vault.withLock(ref, async () => {
             const rec = await readJson(ref);
@@ -233,21 +515,19 @@ export function makeOeOauthTokenVault(source, deps = {}) {
                 // 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";
+                    const endpoint = client.revocationEndpoint;
+                    const hint = rec.refreshToken ? "refresh_token" : "access_token";
+                    // 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. It is no longer only a warning (OPE-2565):
+                    // after one retry it is reported, and the purge's caller records it as a failure.
+                    await revokeWithRetry(providerRef, async () => {
                         if (cfg && isStaticConfidential(cfg)) {
-                            await revokeTokenConfidential(client.revocationEndpoint, { token, tokenTypeHint: hint }, await confidentialClientFor(cfg), doFetch);
+                            await revokeTokenConfidential(endpoint, { token, tokenTypeHint: hint }, await confidentialClientFor(cfg), doFetch);
                         }
                         else {
-                            await revokeToken(client.revocationEndpoint, { token, clientId: client.clientId, tokenTypeHint: hint }, doFetch);
+                            await revokeToken(endpoint, { 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)}`);
-                    }
+                    }, onUnrevoked, "revocation at the provider");
                 }
             }
             // Runs even when there was no record to read (a corrupt/undecryptable envelope reads as null —
@@ -299,17 +579,66 @@ export function makeOeOauthTokenVault(source, deps = {}) {
         /** {@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
+         * Purge EVERY provider's token record for `subject` — the declared ones, and any undeclared one the vault
+         * still holds a row for (OPE-2560) — 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) {
+        async forgetAll(subject, onUnrevoked) {
             let purged = 0;
             let failures = 0;
             let lastError;
             const all = providersNow();
             for (const providerRef of all.keys()) {
                 try {
-                    if (await forget(providerRef, subject))
+                    if (await forget(providerRef, subject, onUnrevoked))
+                        purged++;
+                }
+                catch (e) {
+                    failures++;
+                    lastError = e;
+                }
+            }
+            // (OPE-2560) A token row for a connection that is NOT declared here is still a live grant at rest: a
+            // declaration an operator removed, or a process that declares none at all (the `oe erase` operator CLI
+            // loads no connection module). Its ref names the provider, so it goes through the same `forget`: revoked at
+            // the provider when the stored DCR client names a revocation endpoint, then deleted. A static provider's
+            // client lives only in its declaration, so with none its token is deleted locally and cannot be revoked.
+            // The ref is `oe-oauth:tok:<providerRef>:<subject key>`; a provider ref holds no ':', so the split is exact.
+            const tokPrefix = "oe-oauth:tok:";
+            const tokSuffix = `:${subjectKey(subject)}`;
+            let undeclaredAttempts = 0;
+            try {
+                for (const ref of await vault.listRefs(tokPrefix)) {
+                    if (!ref.endsWith(tokSuffix))
+                        continue;
+                    const providerRef = ref.slice(tokPrefix.length, ref.length - tokSuffix.length);
+                    if (providerRef.length === 0 || providerRef.includes(":") || all.has(providerRef))
+                        continue;
+                    undeclaredAttempts++;
+                    try {
+                        if (await forget(providerRef, subject, onUnrevoked))
+                            purged++;
+                    }
+                    catch (e) {
+                        failures++;
+                        lastError = e;
+                    }
+                }
+            }
+            catch (e) {
+                failures++;
+                lastError = e;
+                undeclaredAttempts++;
+            }
+            // (OPE-2453) A person's IdP grant is shared by every `xaa` connection naming one IdP client, so it is purged
+            // once per IdP client, after the per-connection rows. It is the credential that mints all of them.
+            const seenIdp = new Set();
+            for (const cfg of all.values()) {
+                if (!isXaa(cfg) || seenIdp.has(idpKey(cfg)))
+                    continue;
+                seenIdp.add(idpKey(cfg));
+                try {
+                    if (await forgetIdpGrant(cfg, subject, onUnrevoked))
                         purged++;
                 }
                 catch (e) {
@@ -317,7 +646,29 @@ export function makeOeOauthTokenVault(source, deps = {}) {
                     lastError = e;
                 }
             }
-            if (failures > 0 && purged === 0 && failures === all.size)
+            // An IdP grant whose declaration is GONE is still a live IdP refresh token at rest. With no config there is no
+            // client to revoke it with, so it is deleted locally and the gap is said out loud.
+            // The ref is `oe-oauth:xaa-idp:<32 hex>:<subject key>`; the subject key is matched EXACTLY, never by suffix.
+            const covered = new Set([...all.values()].filter(isXaa).map((cfg) => idpRef(cfg, subject)));
+            const orphanRef = /^oe-oauth:xaa-idp:[0-9a-f]{32}:(.*)$/u;
+            let orphanFailed = false;
+            try {
+                for (const ref of await vault.listRefs("oe-oauth:xaa-idp:")) {
+                    if (orphanRef.exec(ref)?.[1] !== subjectKey(subject) || covered.has(ref))
+                        continue;
+                    console.warn(`[oe-oauth] an IdP grant with no declared xaa connection was deleted locally — it could not be revoked at the IdP.`);
+                    if (await vault.delete(ref))
+                        purged++;
+                }
+            }
+            catch (e) {
+                failures++;
+                lastError = e;
+                orphanFailed = true;
+            }
+            // "Every purge attempt failed" counts only the attempts that ran: the orphan sweep is one attempt only when
+            // it failed. Counting it always would let a purge where every provider failed return 0 with no error.
+            if (failures > 0 && purged === 0 && failures === all.size + undeclaredAttempts + seenIdp.size + (orphanFailed ? 1 : 0))
                 throw lastError;
             return purged;
         },
@@ -328,13 +679,29 @@ export function makeOeOauthTokenVault(source, deps = {}) {
          * 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;
+            if ((await readJson(tokRef(providerRef, subject))) !== null)
+                return true;
+            // (OPE-2453) For an `xaa` connection the person's GRANT is their IdP sign-in: with it, the next mint
+            // succeeds with no consent screen, even for an app this person has never used.
+            const cfg = providersNow().get(providerRef);
+            return cfg !== undefined && isXaa(cfg) && (await readJson(idpRef(cfg, 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 xaaCfg = providersNow().get(providerRef);
+            if (xaaCfg !== undefined && isXaa(xaaCfg)) {
+                const out = await xaaStartAuthorization(xaaCfg, subject, options);
+                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 out;
+            }
             const client = await ensureClient(providerRef);
             const redirectUri = redirectUriOf();
             if (!redirectUri)
@@ -399,6 +766,10 @@ export function makeOeOauthTokenVault(source, deps = {}) {
                 throw new Error("authorization state already used");
             if (now() > pending.expiresAt)
                 throw new Error("authorization state expired");
+            if (pending.mode === OE_OAUTH_MODE_XAA) {
+                const { rebound } = await xaaCompleteAuthorization(state, pending, code);
+                return { providerRef: pending.providerRef, subject: pending.subject, rebound, ...(pending.consent ? { consent: pending.consent } : {}) };
+            }
             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
@@ -428,6 +799,9 @@ export function makeOeOauthTokenVault(source, deps = {}) {
          * single-flight runs — an in-process mutex, then a cross-process row CLAIM that elects ONE refresher.
          */
         async accessTokenFor(providerRef, subject) {
+            const xaaCfg = providersNow().get(providerRef);
+            if (xaaCfg !== undefined && isXaa(xaaCfg))
+                return xaaAccessTokenFor(xaaCfg, providerRef, subject);
             const ref = tokRef(providerRef, subject);
             const fast = await readJson(ref);
             if (!fast)