@open-everywhere/adapters 0.6.0 → 0.8.0

package/agent/model/model-config-check.ts

@@ -0,0 +1,243 @@
+// THE LIVE MODEL CONFIG CHECK (OPE-2556, the OPE-2535 ticket's comment #2). It answers, BEFORE a call fails, whether
+// the deployment's model config can be served: for each model the caller lists (the stack roles, the gateway
+// transcription routes, the domain and role routes, `models.force`), one GET of the gateway's
+// public `/v1/models/<id>/endpoints` read, and three questions:
+//
+//   ① does the model exist on the gateway?
+//   ② does at least one `providers.only` provider serve it? (A slug that serves none of the checked models gets a
+//      warning, because it is most likely a typo. It is not a failure: every call can still be served.)
+//   ③ does at least one allowed provider meet EVERY `models.dataPolicy` row at once (`has_zdr`, `has_no_training`,
+//      `inference_regions`)?
+//
+// A row no provider can meet is named before deploy, for example "region eu: no provider for deepseek/…".
+//
+// 🔴 THE ENDPOINT FIELDS ARE UNDOCUMENTED, so a missing field is UNKNOWN, never a pass. One rule reads more than a
+// field: `inference_regions`. Most endpoints omit it. When at least one endpoint of a model lists regions, an endpoint
+// that omits them is read as serving none of the listed regions: that is how the gateway answered on 2026-10-14
+// ("No provider for deepseek/deepseek-v4-flash-0731 supports the requested inference region", where only some
+// endpoints listed `us` and none listed `eu`). When no endpoint lists regions, the region row is unknown.
+//
+// It needs the network, so it is never an offline gate. Three readers run it: the deployment status probe
+// (`model-route`, gateway-probe.ts), which `create --check --host` and the setup skill read, and
+// `npm run check:model-config`, which runs it from the app (a clone or a scaffolded app) before a deploy.
+
+import { type ModelDataPolicy, type ModelTarget, mergeDataPolicy } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The default origin of the Vercel AI Gateway's public model reads. */
+const DEFAULT_GATEWAY_ORIGIN = "https://ai-gateway.vercel.sh";
+
+export type CheckVerdict = "yes" | "no" | "unknown";
+
+/** One endpoint (one provider serving one model), as the check reads it. `undefined` is an unknown field. */
+export interface EndpointFacts {
+  readonly provider: string;
+  readonly zdr: boolean | undefined;
+  readonly noTraining: boolean | undefined;
+  /** The regions the endpoint lists, or undefined when the endpoint omits the field. */
+  readonly regions: readonly string[] | undefined;
+}
+
+/** A model the deployment can resolve, and the target its calls go through. */
+export interface CheckedModel {
+  readonly id: string;
+  /** The `models.targets` entry (absent: `gateway`). */
+  readonly via?: string;
+}
+
+/** One problem or gap the check found. `row` names the demand in the settings file's words. */
+export interface ConfigFinding {
+  readonly met: Exclude<CheckVerdict, "yes">;
+  readonly model?: string;
+  readonly row: string;
+  readonly detail: string;
+}
+
+export interface ConfigCheckResult {
+  /** "no" when any finding is "no"; "unknown" when any is "unknown"; else "yes". */
+  readonly met: CheckVerdict;
+  readonly findings: readonly ConfigFinding[];
+  /** How many distinct (target, model) pairs were read. */
+  readonly checked: number;
+}
+
+/** The endpoints read for one model id under a target's base URL (or the default origin). The id keeps its slash. */
+export function modelEndpointsUrl(id: string, baseUrl?: string): string {
+  let origin = DEFAULT_GATEWAY_ORIGIN;
+  if (baseUrl !== undefined) {
+    try {
+      origin = new URL(baseUrl).origin;
+    } catch {
+      // The settings validator refuses an unparseable url; the default origin keeps the check honest.
+    }
+  }
+  return `${origin}/v1/models/${id.split("/").map(encodeURIComponent).join("/")}/endpoints`;
+}
+
+const asBool = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined);
+
+/** Parse an `/endpoints` body into facts, or undefined when the body is not one. Pure. */
+export function parseEndpoints(body: unknown): EndpointFacts[] | undefined {
+  const eps = (body as { data?: { endpoints?: unknown } } | null)?.data?.endpoints;
+  if (!Array.isArray(eps)) return undefined;
+  const out: EndpointFacts[] = [];
+  for (const e of eps) {
+    if (e === null || typeof e !== "object") continue;
+    const r = e as Record<string, unknown>;
+    if (typeof r["provider_name"] !== "string") continue;
+    const regions = Array.isArray(r["inference_regions"])
+      ? (r["inference_regions"] as unknown[]).flatMap((x) => {
+          const g = (x as { geo_region?: unknown } | null)?.geo_region;
+          return typeof g === "string" ? [g] : [];
+        })
+      : undefined;
+    out.push({ provider: r["provider_name"], zdr: asBool(r["has_zdr"]), noTraining: asBool(r["has_no_training"]), regions });
+  }
+  return out;
+}
+
+const and = (a: CheckVerdict, b: CheckVerdict): CheckVerdict => (a === "no" || b === "no" ? "no" : a === "unknown" || b === "unknown" ? "unknown" : "yes");
+/** At least one provider: "yes" when one is, "no" when every one is not (or there is none), else "unknown". */
+const any = (vs: readonly CheckVerdict[]): CheckVerdict => (vs.includes("yes") ? "yes" : vs.every((v) => v === "no") ? "no" : "unknown");
+const fromBool = (b: boolean | undefined): CheckVerdict => (b === undefined ? "unknown" : b ? "yes" : "no");
+
+/** The policy's rows as (label, per-endpoint verdict) pairs. */
+function rowJudges(policy: ModelDataPolicy, eps: readonly EndpointFacts[]): { label: string; judge: (e: EndpointFacts) => CheckVerdict }[] {
+  const rows: { label: string; judge: (e: EndpointFacts) => CheckVerdict }[] = [];
+  if (policy.zeroRetention === true) rows.push({ label: "zeroRetention", judge: (e) => fromBool(e.zdr) });
+  if (policy.noTraining === true) rows.push({ label: "noTraining", judge: (e) => fromBool(e.noTraining) });
+  const region = policy.region;
+  if (region !== undefined) {
+    const listed = eps.some((e) => e.regions !== undefined);
+    rows.push({ label: `region ${region}`, judge: (e) => (e.regions !== undefined ? fromBool(e.regions.includes(region)) : listed ? "no" : "unknown") });
+  }
+  return rows;
+}
+
+/**
+ * Judge one model's endpoints against a target and the policy. Pure. Returns the findings ("no" and "unknown" only),
+ * so an empty list means every demand is met.
+ */
+export function judgeModelEndpoints(id: string, eps: readonly EndpointFacts[], target: ModelTarget, policy: ModelDataPolicy, via = "gateway"): ConfigFinding[] {
+  const findings: ConfigFinding[] = [];
+  const only = target.providers?.only;
+  const candidates = only === undefined ? eps : eps.filter((e) => only.includes(e.provider));
+  if (only !== undefined && candidates.length === 0) {
+    findings.push({ met: "no", model: id, row: `models.targets.${via}.providers.only`, detail: `providers.only: no allowed provider serves ${id}` });
+    return findings;
+  }
+  // The target's own `dataPolicy` rows join the deployment's (OPE-2531). Two different regions cannot both be met.
+  let merged: ModelDataPolicy;
+  try {
+    merged = mergeDataPolicy(policy, target.dataPolicy);
+  } catch {
+    findings.push({ met: "no", model: id, row: `models.targets.${via}.dataPolicy region`, detail: `region: models.dataPolicy and target ${via} name two different regions` });
+    return findings;
+  }
+  // The region evidence is read over ALL the model's endpoints: whether the gateway lists regions for this model at all.
+  const rows = rowJudges(merged, eps);
+  if (rows.length === 0) return findings;
+  const joint = any(candidates.map((e) => rows.reduce<CheckVerdict>((v, r) => and(v, r.judge(e)), "yes")));
+  if (joint === "yes") return findings;
+  // Name each row no provider can meet on its own; when every row is met by SOME provider, name them together.
+  const alone = rows.map((r) => ({ label: r.label, v: any(candidates.map(r.judge)) }));
+  const failing = alone.filter((r) => r.v === joint);
+  const named = failing.length > 0 ? failing.map((r) => r.label) : [rows.map((r) => r.label).join(" + ")];
+  // A row the deployment's own policy does not set came from the target: name the target's row (OPE-2531).
+  const ownRows = rowJudges(policy, eps).map((r) => r.label);
+  for (const label of named) {
+    findings.push({
+      met: joint,
+      model: id,
+      row: label
+        .split(" + ")
+        .map((l) => (ownRows.includes(l) ? `models.dataPolicy ${l}` : `models.targets.${via}.dataPolicy ${l}`))
+        .join(" + "),
+      detail: joint === "no" ? `${label}: no provider for ${id}` : `${label}: the gateway does not say whether a provider of ${id} meets it`,
+    });
+  }
+  return findings;
+}
+
+export interface ConfigCheckInput {
+  readonly models: readonly CheckedModel[];
+  readonly targets: Readonly<Record<string, ModelTarget>>;
+  readonly policy: ModelDataPolicy;
+  /** The base URL each target resolves to (absent: the default origin). */
+  readonly baseUrlFor: (via: string) => string | undefined;
+  readonly fetchImpl?: typeof globalThis.fetch;
+  /** One budget for every read. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Run the check: one GET per distinct (target, model), in parallel, under one time budget. FAIL-SOFT: a read that
+ * fails or times out is "unknown" for that model, never a pass and never a throw. No vendor error text is forwarded.
+ */
+export async function checkModelConfig(input: ConfigCheckInput): Promise<ConfigCheckResult> {
+  const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+  const seen = new Map<string, CheckedModel & { via: string }>();
+  for (const m of input.models) {
+    const via = m.via ?? "gateway";
+    seen.set(`${via}\u0000${m.id}`, { id: m.id, via });
+  }
+  const controller = new AbortController();
+  const fuse = setTimeout(() => controller.abort(), input.timeoutMs ?? 5_000);
+  const servedBy = new Map<string, Set<string>>(); // via → providers that serve at least one checked model
+  try {
+    const perModel = await Promise.all(
+      [...seen.values()].map(async (m): Promise<ConfigFinding[]> => {
+        const target = input.targets[m.via];
+        if (target === undefined) return [{ met: "no", model: m.id, row: `via ${m.via}`, detail: `via ${m.via}: models.targets names no such target` }];
+        let res: Response;
+        try {
+          res = await fetchImpl(modelEndpointsUrl(m.id, input.baseUrlFor(m.via)), { method: "GET", signal: controller.signal });
+        } catch {
+          return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the gateway did not answer the endpoints read` }];
+        }
+        // A retargeted target (a relay) owes nobody this read: its 404 or 405 means "not served here", not "no such model".
+        const retargeted = input.baseUrlFor(m.via) !== undefined;
+        if (retargeted && (res.status === 404 || res.status === 405)) {
+          return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the target ${m.via} does not serve the endpoints read` }];
+        }
+        if (res.status === 404) return [{ met: "no", model: m.id, row: "model id", detail: `${m.id}: the gateway does not know this model` }];
+        if (!res.ok) return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the endpoints read answered HTTP ${res.status}` }];
+        let eps: EndpointFacts[] | undefined;
+        try {
+          eps = parseEndpoints(await res.json());
+        } catch {
+          eps = undefined;
+        }
+        if (eps === undefined) return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the endpoints read is not in the expected shape` }];
+        const served = servedBy.get(m.via) ?? new Set<string>();
+        for (const e of eps) served.add(e.provider);
+        servedBy.set(m.via, served);
+        return judgeModelEndpoints(m.id, eps, target, input.policy, m.via);
+      }),
+    );
+    const findings = perModel.flat();
+    // A `providers.only` slug that serves none of the target's checked models: most likely a typo. It is a WARNING
+    // ("unknown"), never a "no": every call can still be served, and a deployer may list a provider for a later stack.
+    // Only judged when every model of the target was read, so a failed read never blames a slug.
+    for (const [via, served] of servedBy) {
+      const readAll = ![...seen.values()].some((m) => m.via === via && findings.some((f) => f.model === m.id && f.row === "endpoints"));
+      if (!readAll) continue;
+      for (const slug of input.targets[via]?.providers?.only ?? []) {
+        if (!served.has(slug)) findings.push({ met: "unknown", row: `models.targets.${via}.providers.only`, detail: `providers.only: "${slug}" serves none of the checked models` });
+      }
+    }
+    const met: CheckVerdict = findings.some((f) => f.met === "no") ? "no" : findings.length > 0 ? "unknown" : "yes";
+    return { met, findings, checked: seen.size };
+  } finally {
+    clearTimeout(fuse);
+  }
+}
+
+/** The result in one short line a person reads: "4 models checked, no problem", or the problems by name. Pure. */
+export function configCheckSummary(r: ConfigCheckResult): string {
+  const plural = r.checked === 1 ? "model" : "models";
+  if (r.findings.length === 0) return `model config: ${r.checked} ${plural} checked, every demand can be served`;
+  const no = r.findings.filter((f) => f.met === "no");
+  const shown = (no.length > 0 ? no : r.findings).map((f) => f.detail);
+  const head = no.length > 0 ? `${no.length} problem${no.length === 1 ? "" : "s"}` : "not fully measured";
+  return `model config: ${head} — ${shown.slice(0, 3).join("; ")}${shown.length > 3 ? `; and ${shown.length - 3} more` : ""}`;
+}

package/agent/model/target-url.ts

@@ -0,0 +1,38 @@
+// THE BASE URL OF A MODEL TARGET (OPE-2556) — `models.targets.<name>.url`, with the deprecated `OE_AI_GATEWAY_URL`
+// as the `gateway` target's fallback for one release. Its own module so the model adapter (gateway.ts) and the
+// status probe (gateway-probe.ts) resolve the same URL without the probe loading the adapter.
+
+import { DEFAULT_MODEL_VIA, type ModelTarget } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The deprecated env var that retargets the `gateway` target (OPE-2556: `models.targets.gateway.url` replaces it). */
+export const DEPRECATED_GATEWAY_URL_ENV = "OE_AI_GATEWAY_URL";
+
+const warned = new Set<string>();
+function warnOnce(key: string, message: string): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}
+
+/**
+ * THE BASE URL OF ONE TARGET. The target's `url` wins. The deprecated `OE_AI_GATEWAY_URL` still retargets the
+ * `gateway` target when its `url` is unset, for one release, with a warning. Absent both: the kind's default
+ * endpoint (`undefined`). Pure but for the warnings; exported for tests.
+ */
+export function targetBaseUrl(name: string, t: ModelTarget, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const fromEnv = name === DEFAULT_MODEL_VIA ? env[DEPRECATED_GATEWAY_URL_ENV]?.trim() || undefined : undefined;
+  if (t.url !== undefined) {
+    if (fromEnv !== undefined && fromEnv !== t.url) {
+      warnOnce("env-ignored", `[open-everywhere:model] ${DEPRECATED_GATEWAY_URL_ENV} is set and ignored: models.targets.${name}.url wins. Unset the env var.`);
+    }
+    return t.url;
+  }
+  if (fromEnv !== undefined) {
+    warnOnce(
+      "env-deprecated",
+      `[open-everywhere:model] ${DEPRECATED_GATEWAY_URL_ENV} is deprecated and goes away in the next release. Move it to models.targets.${name}.url in agent/settings/settings.ts.`,
+    );
+  }
+  return fromEnv;
+}
+

package/agent/model/transcription-routes.ts

@@ -18,12 +18,17 @@
 // provider allow-list, a timeout) tries the fallback route. Both fail ⇒ it throws one error that names both. It
 // never tries a third route: the stack names what may hear the meeting, and nothing else may.
 //
+// 🔴 THE DATA POLICY (OPE-2535). A `gateway` route carries `models.dataPolicy` on every call (gateway.ts). The
+// `deepinfra` route cannot carry it, so with any row set it REFUSES before a byte leaves, and the fallback rule
+// above does not let the audio go anywhere the policy did not allow. A `self-hosted` route is the deployer's own
+// server, so the policy's provider rows do not apply to it.
+//
 // 🔴 THE DISCLOSURE IS DERIVED. The approval card shows {@link roleDisclosure}, built from the SAME route list the
 // call walks, so the card cannot name one provider while the audio goes to another.
 
 import { experimental_transcribe as transcribe } from "ai";
-import { getOperatorSecret } from "@open-everywhere/core/agent/adapter-api.js";
-import { GATEWAY_TARGET_HOST, gatewayTranscriptionModel, sharedHostPlaneFetch } from "./gateway.js";
+import { type ModelDataPolicy, dataPolicyActive, dataPolicyRows, getOperatorSecret, getSettings } from "@open-everywhere/core/agent/adapter-api.js";
+import { gatewayTargetHost, gatewayTranscriptionModel, sharedHostPlaneFetch } from "./gateway.js";
 
 /** How a route reaches its model. */
 export type TranscriptionVia = "gateway" | "deepinfra" | "self-hosted";
@@ -82,6 +87,8 @@ export interface TranscriptionDeps {
   readonly attemptTimeoutMs?: number;
   /** Where a fall-through is reported. Default: `console.warn`. */
   readonly warn?: (message: string) => void;
+  /** The deployment's data policy, read per call. Default: `models.dataPolicy` from the settings. */
+  readonly dataPolicy?: () => ModelDataPolicy;
 }
 
 /** The secret-store name of the DeepInfra key. A fixed name in code, so no config line can point it at another secret. */
@@ -259,7 +266,7 @@ function selfHostedCall(f: typeof fetch) {
  * union and neither the turn model nor a transcription route drops the other's host.
  */
 export function roleHostPlaneHosts(role: TranscriptionRoleSpec): string[] {
-  const hosts = [GATEWAY_TARGET_HOST];
+  const hosts = [gatewayTargetHost()];
   for (const r of [role.primary, role.fallback]) {
     if (r === undefined || r.via === "gateway") continue;
     const h = routeHost(r);
@@ -277,7 +284,14 @@ export function routeTransport(r: TranscriptionRouteSpec, deps: TranscriptionDep
   const f = deps.fetch ?? (deps.hostPlane ?? sharedHostPlaneFetch)(roleHostPlaneHosts({ primary: r })) ?? lateFetch;
   if (r.via === "deepinfra") {
     const call = deepinfraCall(f, deps.secret ?? storeOnlySecret);
-    return (req) => call(r, req);
+    const policy = deps.dataPolicy ?? (() => getSettings().models.dataPolicy);
+    return async (req) => {
+      const p = policy();
+      if (dataPolicyActive(p)) {
+        throw new Error(`models.dataPolicy (${dataPolicyRows(p).join(", ")}): the deepinfra route cannot carry these rows, so it refuses`);
+      }
+      return await call(r, req);
+    };
   }
   const call = selfHostedCall(f);
   return (req) => call(r, req);

package/agent/oe-oauth/config.ts

@@ -14,6 +14,9 @@ export const OE_OAUTH_MODE_DISCOVERY = "discovery-dcr-pkce";
 /** The static confidential-client dialect (OPE-1086) — no discovery, no registration, HTTP Basic. */
 export const OE_OAUTH_MODE_STATIC = "static-confidential";
 
+/** The Cross App Access dialect (OPE-2453) — an IdP sign-in once, then an ID-JAG mint per app token. */
+export const OE_OAUTH_MODE_XAA = "xaa";
+
 /** How a static provider encodes its token-request body. Declared, never inferred: Notion's REST
  *  token endpoint takes JSON, the RFC 6749 default is form-encoded, and sending the wrong one reads
  *  as an authentication failure rather than as a shape error. */
@@ -66,8 +69,36 @@ export interface OeOauthStaticProviderConfig extends OeOauthProviderConfigBase {
   readonly bodyEncoding: OeOauthBodyEncoding;
 }
 
-/** One provider's OAuth target, in one of the two declared modes. */
-export type OeOauthProviderConfig = OeOauthDiscoveryProviderConfig | OeOauthStaticProviderConfig;
+/**
+ * A Cross App Access provider (OPE-2453). The person signs in to the IdP (`idpIssuer`) once; each mint then trades
+ * the person's IdP refresh token for an ID-JAG (RFC 8693, at the IdP) and the ID-JAG for the app's access token
+ * (RFC 7523, at `resourceTokenEndpoint`). Two confidential clients, two secret REFS, no literal secret.
+ */
+export interface OeOauthXaaProviderConfig extends OeOauthProviderConfigBase {
+  readonly mode: typeof OE_OAUTH_MODE_XAA;
+  /** The IdP's OIDC issuer. Its `/.well-known/openid-configuration` names the authorize, token, JWKS and
+   *  revocation endpoints. HTTPS only. */
+  readonly idpIssuer: string;
+  readonly idpClientId: string;
+  readonly idpClientSecretRef: string;
+  readonly idpClientSecretBroker: string;
+  /** The app's authorization server issuer — the ID-JAG `audience`. */
+  readonly audience: string;
+  /** The RFC 8707 resource both legs name, when the app asks for one. */
+  readonly resource?: string;
+  readonly resourceTokenEndpoint: string;
+  readonly resourceClientId: string;
+  readonly resourceClientSecretRef: string;
+  readonly resourceClientSecretBroker: string;
+}
+
+/** One provider's OAuth target, in one of the three declared modes. */
+export type OeOauthProviderConfig = OeOauthDiscoveryProviderConfig | OeOauthStaticProviderConfig | OeOauthXaaProviderConfig;
+
+/** Narrow a provider config to the Cross App Access mode. Reads the DECLARED `mode` only. */
+export function isXaa(cfg: OeOauthProviderConfig): cfg is OeOauthXaaProviderConfig {
+  return cfg.mode === OE_OAUTH_MODE_XAA;
+}
 
 /** Narrow a provider config to the static confidential-client mode. Reads the DECLARED `mode` and
  *  nothing else — never the presence of a field. */
@@ -162,6 +193,39 @@ function parseStaticProvider(ref: string, rec: Record<string, unknown>): OeOauth
   };
 }
 
+/** Parse ONE `xaa` entry, with every refusal stated. */
+function parseXaaProvider(ref: string, rec: Record<string, unknown>): OeOauthXaaProviderConfig {
+  const where = `sign-in "${ref}"`;
+  // 🔴 A LITERAL SECRET IS REFUSED, as in the static dialect: a declaration is committed source.
+  for (const literal of ["clientSecret", "idpClientSecret", "resourceClientSecret"]) {
+    if (literal in rec) {
+      throw new Error(
+        `${where} carries a literal "${literal}". A client secret must NEVER live in a sign-in declaration — store it in the ` +
+          `credential store and name it with "${literal === "clientSecret" ? "idpClientSecretRef" : `${literal}Ref`}".`,
+      );
+    }
+  }
+  const resource = rec.resource === undefined ? undefined : requireString(rec.resource, `${where}.resource`);
+  const scopes = parseScopes(rec.scopes);
+  return {
+    mode: OE_OAUTH_MODE_XAA,
+    ref,
+    // The issuer is compared byte-for-byte with the id token's `iss`, so it is kept exactly as declared.
+    idpIssuer: requireHttpsUrl(rec.idpIssuer, `${where}.idpIssuer`),
+    idpClientId: requireString(rec.idpClientId, `${where}.idpClientId`),
+    idpClientSecretRef: requireString(rec.idpClientSecretRef, `${where}.idpClientSecretRef`),
+    idpClientSecretBroker: rec.idpClientSecretBroker === undefined ? "db" : requireString(rec.idpClientSecretBroker, `${where}.idpClientSecretBroker`),
+    audience: requireString(rec.audience, `${where}.audience`),
+    ...(resource ? { resource } : {}),
+    resourceTokenEndpoint: requireHttpsUrl(rec.resourceTokenEndpoint, `${where}.resourceTokenEndpoint`),
+    resourceClientId: requireString(rec.resourceClientId, `${where}.resourceClientId`),
+    resourceClientSecretRef: requireString(rec.resourceClientSecretRef, `${where}.resourceClientSecretRef`),
+    resourceClientSecretBroker:
+      rec.resourceClientSecretBroker === undefined ? "db" : requireString(rec.resourceClientSecretBroker, `${where}.resourceClientSecretBroker`),
+    ...(scopes ? { scopes } : {}),
+  };
+}
+
 /** Parse ONE `discovery-dcr-pkce` entry. */
 function parseDiscoveryProvider(ref: string, rec: Record<string, unknown>): OeOauthDiscoveryProviderConfig {
   const where = `sign-in "${ref}"`;
@@ -192,9 +256,13 @@ function parseDeclarations(declared: ReadonlyMap<string, unknown>): Map<string,
       out.set(ref, parseStaticProvider(ref, rec));
       continue;
     }
+    if (mode === OE_OAUTH_MODE_XAA) {
+      out.set(ref, parseXaaProvider(ref, rec));
+      continue;
+    }
     if (mode !== OE_OAUTH_MODE_DISCOVERY) {
       throw new Error(
-        `sign-in "${ref}".mode ${JSON.stringify(mode)} is not a known oe-oauth mode — use "${OE_OAUTH_MODE_DISCOVERY}" or "${OE_OAUTH_MODE_STATIC}".`,
+        `sign-in "${ref}".mode ${JSON.stringify(mode)} is not a known oe-oauth mode — use "${OE_OAUTH_MODE_DISCOVERY}", "${OE_OAUTH_MODE_STATIC}" or "${OE_OAUTH_MODE_XAA}".`,
       );
     }
     const parsed = parseDiscoveryProvider(ref, rec);

package/agent/oe-oauth/errors.ts

@@ -2,7 +2,7 @@
 // DUCK-TYPED across processes. SECURITY: no error here carries a token, a code, or a PKCE verifier.
 
 /** The subject an error is about, as a log-safe label (never an opaque token). */
-export function subjectLabel(subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }): string {
+function subjectLabel(subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }): string {
   return subject.type === "app" ? "app" : `user:${subject.id}`;
 }
 
@@ -40,6 +40,23 @@ export class OeOauthRefreshContendedError extends Error {
   }
 }
 
+/** Cross App Access (OPE-2453): the IdP or the app REFUSED the mint for a person who is signed in — the IdP admin
+ *  removed the pairing, unassigned the person, or never granted this app. A new sign-in link cannot fix that, so
+ *  this error is DELIBERATELY not classified as user-auth-required: the person gets no "Connect my account" link,
+ *  only the reason. Carries the RFC 6749 error code, never token material. */
+export class OeOauthAccessRemovedError extends Error {
+  readonly code = "oe_oauth_access_removed";
+  readonly oauthError?: string;
+  constructor(providerRef: string, subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }, where: "idp" | "app", oauthError?: string) {
+    super(
+      `connection "${providerRef}": ${subjectLabel(subject)} — the ${where === "idp" ? "identity provider" : "app"} refused access` +
+        `${oauthError ? ` (${oauthError})` : ""}. Your identity-provider admin manages this access; a new sign-in will not restore it.`,
+    );
+    this.name = "OeOauthAccessRemovedError";
+    if (oauthError) this.oauthError = oauthError;
+  }
+}
+
 /** A generic upstream OAuth failure (token endpoint / discovery / DCR returned an error). `oauthError`
  *  is the RFC 6749 `error` code when the body carried one (e.g. "invalid_grant", "invalid_client") —
  *  a fixed-vocabulary string, never a secret. */

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);
+}