@open-everywhere/adapters 0.5.0 → 0.7.0

package/agent/oe-oauth/oauth-client.ts

@@ -21,6 +21,8 @@ export interface DiscoveredEndpoints {
 /** A token endpoint response (authorization-code exchange or refresh). Only the fields we persist. */
 export interface OAuthTokenResponse {
   readonly access_token: string;
+  /** OIDC: present when the request asked for `openid` (the Cross App Access sign-in, OPE-2453). */
+  readonly id_token?: string;
   readonly refresh_token?: string;
   readonly expires_in?: number;
   readonly scope?: string;
@@ -301,11 +303,16 @@ async function postTokenConfidential(
  */
 export async function exchangeCodeConfidential(
   tokenEndpoint: string,
-  input: { readonly code: string; readonly redirectUri: string },
+  input: { readonly code: string; readonly redirectUri: string; readonly codeVerifier?: string },
   client: ConfidentialClient,
   fetchImpl: OAuthFetch,
 ): Promise<OAuthTokenResponse> {
-  const res = await postTokenConfidential(tokenEndpoint, client, { grant_type: "authorization_code", code: input.code, redirect_uri: input.redirectUri }, fetchImpl);
+  const res = await postTokenConfidential(
+    tokenEndpoint,
+    client,
+    { grant_type: "authorization_code", code: input.code, redirect_uri: input.redirectUri, ...(input.codeVerifier ? { code_verifier: input.codeVerifier } : {}) },
+    fetchImpl,
+  );
   return readTokenResponse(tokenEndpoint, res);
 }
 
@@ -374,3 +381,112 @@ export function refreshToken(
     fetchImpl,
   );
 }
+
+// ── Cross App Access (OPE-2453): OIDC sign-in at the IdP, then the two ID-JAG legs ─────────────────────────────
+
+/** RFC 8693 / ID-JAG wire constants. The draft is `draft-ietf-oauth-identity-assertion-authz-grant-04`, so these
+ *  names can still move before an RFC; each lives here once. */
+export const GRANT_TOKEN_EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange";
+export const GRANT_JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+export const TOKEN_TYPE_ID_JAG = "urn:ietf:params:oauth:token-type:id-jag";
+export const TOKEN_TYPE_REFRESH_TOKEN = "urn:ietf:params:oauth:token-type:refresh_token";
+
+/** The IdP endpoints an OIDC discovery document names. */
+export interface OidcEndpoints {
+  readonly authorizationEndpoint: string;
+  readonly tokenEndpoint: string;
+  readonly jwksUri: string;
+  readonly revocationEndpoint?: string;
+}
+
+/**
+ * OIDC discovery at `issuer` (OpenID Connect Discovery §4). The document's `issuer` MUST equal the configured one
+ * (§4.3): a mismatch means the document is not this IdP's, so it is refused. Every endpoint must be https.
+ */
+export async function discoverOidc(issuer: string, fetchImpl: OAuthFetch): Promise<OidcEndpoints> {
+  const url = `${trimSlash(issuer)}/.well-known/openid-configuration`;
+  const res = await fetchImpl(url, { headers: { accept: "application/json" }, redirect: "error" });
+  if (!res.ok) throw new OeOauthError(`OIDC discovery failed for ${issuer}`, { httpStatus: res.status, ...(await readError(res)) });
+  const doc = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  if (doc["issuer"] !== issuer) throw new OeOauthError(`OIDC discovery for ${issuer} names a different issuer — refused`);
+  const https = (k: string): string | undefined => {
+    const v = doc[k];
+    if (typeof v !== "string" || v === "") return undefined;
+    if (!v.startsWith("https://")) throw new OeOauthError(`OIDC discovery for ${issuer}: ${k} is not https — refused`);
+    return v;
+  };
+  const authorizationEndpoint = https("authorization_endpoint");
+  const tokenEndpoint = https("token_endpoint");
+  const jwksUri = https("jwks_uri");
+  const revocationEndpoint = https("revocation_endpoint");
+  if (!authorizationEndpoint || !tokenEndpoint || !jwksUri) {
+    throw new OeOauthError(`OIDC discovery for ${issuer} is missing authorization_endpoint, token_endpoint or jwks_uri`);
+  }
+  return { authorizationEndpoint, tokenEndpoint, jwksUri, ...(revocationEndpoint ? { revocationEndpoint } : {}) };
+}
+
+/** Fetch the IdP's JWKS document — the keys an id token must verify against. */
+export async function fetchJwks(jwksUri: string, fetchImpl: OAuthFetch): Promise<{ keys: Record<string, unknown>[] }> {
+  const res = await fetchImpl(jwksUri, { headers: { accept: "application/json" }, redirect: "error" });
+  if (!res.ok) throw new OeOauthError(`JWKS fetch failed at ${jwksUri}`, { httpStatus: res.status });
+  const doc = (await res.json().catch(() => ({}))) as { keys?: unknown };
+  if (!Array.isArray(doc.keys)) throw new OeOauthError(`JWKS at ${jwksUri} carries no keys array`);
+  return { keys: doc.keys as Record<string, unknown>[] };
+}
+
+/**
+ * LEG 1 — RFC 8693 token exchange at the IdP: the person's IdP refresh token for an ID-JAG naming `audience`. OE
+ * authenticates as its IdP client (HTTP Basic). The ID-JAG comes back in `access_token`, and the response must
+ * say `issued_token_type` is an ID-JAG: anything else is not the grant leg 2 expects.
+ */
+export async function requestIdJag(
+  tokenEndpoint: string,
+  input: { readonly subjectToken: string; readonly audience: string; readonly resource?: string; readonly scopes?: readonly string[] },
+  client: ConfidentialClient,
+  fetchImpl: OAuthFetch,
+): Promise<string> {
+  const res = await postTokenConfidential(
+    tokenEndpoint,
+    client,
+    {
+      grant_type: GRANT_TOKEN_EXCHANGE,
+      requested_token_type: TOKEN_TYPE_ID_JAG,
+      subject_token: input.subjectToken,
+      subject_token_type: TOKEN_TYPE_REFRESH_TOKEN,
+      audience: input.audience,
+      ...(input.resource ? { resource: input.resource } : {}),
+      ...(input.scopes && input.scopes.length ? { scope: input.scopes.join(" ") } : {}),
+    },
+    fetchImpl,
+  );
+  const body = (await readTokenResponse(tokenEndpoint, res)) as OAuthTokenResponse & { issued_token_type?: unknown };
+  if (body.issued_token_type !== TOKEN_TYPE_ID_JAG) {
+    throw new OeOauthError(`token endpoint ${tokenEndpoint} answered the ID-JAG exchange with another token type — refused`);
+  }
+  return body.access_token;
+}
+
+/**
+ * LEG 2 — RFC 7523 JWT bearer grant at the APP's authorization server: the ID-JAG for the app's access token. OE
+ * authenticates with the client the APP issued it (HTTP Basic); the app checks the ID-JAG's `client_id` against
+ * it. The draft says the app SHOULD NOT return a refresh token, so the caller re-mints at expiry.
+ */
+export async function jwtBearerGrant(
+  tokenEndpoint: string,
+  input: { readonly assertion: string; readonly resource?: string; readonly scopes?: readonly string[] },
+  client: ConfidentialClient,
+  fetchImpl: OAuthFetch,
+): Promise<OAuthTokenResponse> {
+  const res = await postTokenConfidential(
+    tokenEndpoint,
+    client,
+    {
+      grant_type: GRANT_JWT_BEARER,
+      assertion: input.assertion,
+      ...(input.resource ? { resource: input.resource } : {}),
+      ...(input.scopes && input.scopes.length ? { scope: input.scopes.join(" ") } : {}),
+    },
+    fetchImpl,
+  );
+  return readTokenResponse(tokenEndpoint, res);
+}

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

@@ -2,8 +2,25 @@
 // encrypted KV. Refresh is single-flight in-process AND cross-process, because the provider ROTATES tokens.
 
 import type { EncryptedKvVault } from "@open-everywhere/core/agent/adapter-api.js";
-import { agentDisplayName, encryptedKvVault, getSecretVia, OE_OAUTH_CALLBACK_PATH } from "@open-everywhere/core/agent/adapter-api.js";
-import { isStaticConfidential, OE_OAUTH_MODE_STATIC, type OeOauthProviderConfig, type OeOauthStaticProviderConfig } from "./config.js";
+import {
+  agentDisplayName,
+  checkXaaIdentityBinding,
+  encryptedKvVault,
+  recordXaaRefusal,
+  getSecretVia,
+  OE_OAUTH_CALLBACK_PATH,
+  verifyOidcIdToken,
+  type XaaBindingVerdict,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import {
+  isStaticConfidential,
+  isXaa,
+  OE_OAUTH_MODE_STATIC,
+  OE_OAUTH_MODE_XAA,
+  type OeOauthProviderConfig,
+  type OeOauthStaticProviderConfig,
+  type OeOauthXaaProviderConfig,
+} from "./config.js";
 import {
   discoverEndpoints,
   registerClient,
@@ -15,13 +32,18 @@ import {
   refreshTokenConfidential,
   revokeToken,
   revokeTokenConfidential,
+  discoverOidc,
+  fetchJwks,
+  requestIdJag,
+  jwtBearerGrant,
   type ConfidentialClient,
+  type OidcEndpoints,
   type OAuthFetch,
   type OAuthTokenResponse,
 } from "./oauth-client.js";
-import { randomUUID } from "node:crypto";
+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";
 
 /** 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" };
@@ -77,9 +99,11 @@ interface PendingRecord {
   /** The RFC 8707 resource indicator. ABSENT on a `static-confidential` row — that dialect sends
    *  none — and present on every discovery row, including every row written before OPE-1086. */
   readonly resource?: string;
-  /** Stamped ONLY on a `static-confidential` row, from the config's declared mode at mint time. Its
+  /** Stamped ONLY on a `static-confidential` or an `xaa` row, from the config's declared mode at mint time. Its
    *  absence is the discovery dialect, which is what every pre-OPE-1086 row means. */
-  readonly mode?: typeof OE_OAUTH_MODE_STATIC;
+  readonly mode?: typeof OE_OAUTH_MODE_STATIC | typeof OE_OAUTH_MODE_XAA;
+  /** The OIDC `nonce` of an `xaa` sign-in (OPE-2453): the id token must carry it back. Absent on other rows. */
+  readonly nonce?: string;
   readonly redirectUri: string;
   readonly scopes?: readonly string[];
   readonly createdAt: number;
@@ -106,6 +130,31 @@ interface PendingSweepReport {
   readonly unreadable: number;
 }
 
+/**
+ * A person's IdP grant for Cross App Access (OPE-2453): the IdP refresh token their one sign-in yielded, and the
+ * IdP account (`sub`) the identity-link plane confirmed as theirs. ONE row per (IdP client, person), shared by every
+ * `xaa` connection that names the same IdP client — so one sign-in serves every paired app.
+ */
+interface IdpGrantRecord {
+  readonly refreshToken: string;
+  readonly idpSubject: string;
+  readonly obtainedAt: number;
+}
+
+/** 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"] as const;
+
+/** 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: ReadonlySet<string> = 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: ReadonlySet<string> = 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;
+
 /** A persisted token record. `expiresAt` absent ⇒ no known expiry (never proactively refreshed). */
 interface TokenRecord {
   readonly accessToken: string;
@@ -156,6 +205,20 @@ export interface OeOauthVaultDeps {
    * 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>;
+  /** Mints the OIDC nonce of an `xaa` sign-in. Default: the same generator as the opaque state. */
+  readonly newNonce?: () => string;
+  /** Verify an `xaa` sign-in's id token. Default: core's `verifyOidcIdToken` (jose, full signature check). */
+  readonly verifyIdToken?: typeof verifyOidcIdToken;
+  /** Decide whether the IdP account that signed in may complete this requester's `xaa` link. Default: core's
+   *  `checkXaaIdentityBinding` — a confirmed `okta` account on the requester's link-set, refusal by default. */
+  readonly bindIdentity?: (input: {
+    readonly principalSubject: string;
+    readonly signerSubject: string | undefined;
+    readonly connection: string;
+    readonly stage?: "sign-in" | "mint";
+  }) => Promise<XaaBindingVerdict>;
+  /** Audit an `xaa` sign-in refused before the binding ran. Default: core's `recordXaaRefusal`. */
+  readonly recordRefusal?: typeof recordXaaRefusal;
 }
 
 function subjectKey(subject: OeOauthSubject): string {
@@ -191,10 +254,18 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
   const newClaimId = deps.newClaimId ?? (() => randomUUID());
   const sleep = deps.sleep ?? realSleep;
   const resolveSecret = deps.resolveSecret ?? ((broker: string | undefined, ref: string) => 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: string) => `oe-oauth:dcr:${providerRef}`;
   const pendRef = (state: string) => `oe-oauth:pend:${state}`;
   const tokRef = (providerRef: string, subject: OeOauthSubject) => `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: OeOauthXaaProviderConfig) => createHash("sha256").update(`${cfg.idpIssuer}\n${cfg.idpClientId}`).digest("hex").slice(0, 32);
+  const idpRef = (cfg: OeOauthXaaProviderConfig, subject: OeOauthSubject) => `oe-oauth:xaa-idp:${idpKey(cfg)}:${subjectKey(subject)}`;
 
   function providerConfig(providerRef: string): OeOauthProviderConfig {
     const cfg = providersNow().get(providerRef);
@@ -234,6 +305,7 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
     // 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.`);
+    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<DcrClientRecord>(dcrRef(providerRef));
       if (again && !dcrRecordNeedsBackfill(again)) return again; // another caller already completed it
@@ -324,6 +396,230 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
     };
   }
 
+  /** A confidential client for one `xaa` leg, secret read through its broker PER CALL. The error names the ref. */
+  async function xaaClient(cfg: OeOauthXaaProviderConfig, leg: "idp" | "app"): Promise<ConfidentialClient> {
+    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<string, { readonly at: number; readonly endpoints: OidcEndpoints }>();
+  async function oidcFor(cfg: OeOauthXaaProviderConfig): Promise<OidcEndpoints> {
+    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: string, subject: OeOauthSubject): asserts subject is { readonly type: "user"; readonly id: string } {
+    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: OeOauthXaaProviderConfig,
+    subject: OeOauthSubject,
+    options: { readonly expiresInMs?: number; readonly consent?: unknown },
+  ): Promise<{ url: string }> {
+    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: PendingRecord = {
+      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: string, pending: PendingRecord, code: string): Promise<{ rebound: boolean }> {
+    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: string | undefined;
+    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)) as Parameters<typeof verifyOidcIdToken>[1]["jwks"], 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<IdpGrantRecord>(gRef)) !== null;
+    const grant: IdpGrantRecord = { 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: unknown): string | undefined {
+    const code = (e as { oauthError?: unknown } | null)?.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: OeOauthXaaProviderConfig, providerRef: string, subject: OeOauthSubject, grant: IdpGrantRecord): Promise<string> {
+    const oidc = await oidcFor(cfg);
+    const legParams = { ...(cfg.resource ? { resource: cfg.resource } : {}), ...(cfg.scopes ? { scopes: cfg.scopes } : {}) };
+    let idJag: string;
+    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: OAuthTokenResponse;
+    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: OeOauthXaaProviderConfig, providerRef: string, subject: OeOauthSubject): Promise<string> {
+    requireXaaPerson(providerRef, subject);
+    const ref = tokRef(providerRef, subject);
+    const fast = await readJson<TokenRecord>(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<TokenRecord>(ref);
+        if (rec && !isExpired(rec)) return rec.accessToken;
+        const grant = await readJson<IdpGrantRecord>(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<TokenRecord>(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);
+      }
+    });
+  }
+
+  /** Purge a person's IdP grant: revoke the IdP refresh token at the IdP (best-effort), then delete the row. */
+  async function forgetIdpGrant(cfg: OeOauthXaaProviderConfig, subject: OeOauthSubject): Promise<boolean> {
+    const gRef = idpRef(cfg, subject);
+    return vault.withLock(gRef, async () => {
+      const grant = await readJson<IdpGrantRecord>(gRef);
+      if (grant) {
+        try {
+          const oidc = await oidcFor(cfg);
+          if (oidc.revocationEndpoint) {
+            await revokeTokenConfidential(oidc.revocationEndpoint, { token: grant.refreshToken, tokenTypeHint: "refresh_token" }, await xaaClient(cfg, "idp"), doFetch);
+          }
+        } catch (e) {
+          console.warn(`[oe-oauth] IdP revocation failed for "${cfg.ref}" (purging locally anyway): ${e instanceof Error ? e.message : String(e)}`);
+        }
+      }
+      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.
@@ -333,6 +629,9 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
     // 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(
@@ -469,7 +768,39 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
           lastError = e;
         }
       }
-      if (failures > 0 && purged === 0 && failures === all.size) throw lastError;
+      // (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<string>();
+      for (const cfg of all.values()) {
+        if (!isXaa(cfg) || seenIdp.has(idpKey(cfg))) continue;
+        seenIdp.add(idpKey(cfg));
+        try {
+          if (await forgetIdpGrant(cfg, subject)) purged++;
+        } catch (e) {
+          failures++;
+          lastError = e;
+        }
+      }
+      // 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 + seenIdp.size + (orphanFailed ? 1 : 0)) throw lastError;
       return purged;
     },
 
@@ -480,7 +811,11 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
      * counts as absent (mirrors the mint's readJson semantics — fail toward re-consent, never crash).
      */
     async hasToken(providerRef: string, subject: OeOauthSubject): Promise<boolean> {
-      return (await readJson<TokenRecord>(tokRef(providerRef, subject))) !== null;
+      if ((await readJson<TokenRecord>(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<IdpGrantRecord>(idpRef(cfg, subject))) !== null;
     },
 
     /**
@@ -492,6 +827,16 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
       subject: OeOauthSubject,
       options: { readonly expiresInMs?: number; readonly consent?: unknown },
     ): Promise<{ url: string }> {
+      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) throw new Error(`connection "${providerRef}": OE_PUBLIC_BASE_URL is unset — cannot build a redirect_uri.`);
@@ -552,6 +897,10 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
       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");
+      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
@@ -586,6 +935,8 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
      * single-flight runs — an in-process mutex, then a cross-process row CLAIM that elects ONE refresher.
      */
     async accessTokenFor(providerRef: string, subject: OeOauthSubject): Promise<string> {
+      const xaaCfg = providersNow().get(providerRef);
+      if (xaaCfg !== undefined && isXaa(xaaCfg)) return xaaAccessTokenFor(xaaCfg, providerRef, subject);
       const ref = tokRef(providerRef, subject);
       const fast = await readJson<TokenRecord>(ref);
       if (!fast) throw new OeOauthNeedsConsentError(providerRef, subject);

package/agent/register-defaults.ts

@@ -26,6 +26,8 @@ import { registerAwsAccess } from "./aws/register.js";
 import { awsAccessEnabled } from "./aws/config.js";
 import { registerDirectoryAdapter } from "./directory/register.js";
 import { registerGatewayRouteProbe } from "./model/gateway-probe.js";
+import { registerLongLivedBoxes } from "./sandbox/long-lived-box.js";
+import { registerNativeTranscriptSources } from "./meetings/native-sources.js";
 import { registerNeon } from "./postgres/neon.js";
 import {
   registerDbCredentialBroker,
@@ -197,6 +199,15 @@ async function wireDefaultAdapters(options: DefaultAdapterOptions): Promise<Defa
     provider.register();
   }
 
+  // The long-lived box (OPE-2459): one box backend per sandbox backend, picked by the same rule as the
+  // turn-end stopper. A box is what a meeting bot (and later the person's browser) runs in. just-bash
+  // registers a backend that refuses with a reason, so a feature never runs a box somewhere unreviewed.
+  registerLongLivedBoxes();
+
+  // The native meeting-transcript readers (OPE-2471): Teams, Meet and Zoom. Each reads only behind the meeting
+  // policy's `native` block and a member's `meeting.recap` card, so registering all three is harmless.
+  registerNativeTranscriptSources();
+
   // The deployment-status surface's model probe (OPE-2230). It registers a function, and nothing
   // calls it until somebody reads `GET /eve/v1/oe/status`.
   registerGatewayRouteProbe();