@open-everywhere/adapters 0.6.0 → 0.7.0

package/agent/directory/okta.ts

@@ -1,7 +1,14 @@
 // THE OKTA DIRECTORY ADAPTER — everything it returns is a PROPOSAL, and nothing here confirms a link. The
 // grade follows the field: `externalId` is attested (the SCIM write-back), `credentials.userName` asserted.
 
-import { getSecretVia, type DirectoryAccount, type DirectoryPerson, type DirectoryProvider } from "@open-everywhere/core/agent/adapter-api.js";
+import {
+  declaredConnectionSignIns,
+  getSecretVia,
+  OKTA_LINK_PLATFORM,
+  type DirectoryAccount,
+  type DirectoryPerson,
+  type DirectoryProvider,
+} from "@open-everywhere/core/agent/adapter-api.js";
 import type { OktaAppMapping, OktaDirectoryConfig } from "./config.js";
 
 /** A `fetch`-shaped transport — the DI seam the offline test injects (defaults to global fetch). */
@@ -63,6 +70,34 @@ export interface OktaDirectoryDeps {
   readonly fetch?: FetchLike;
   /** Resolve the API token. Default: core's broker seam — see config.ts's header. */
   readonly resolveToken?: (broker: string, ref: string) => Promise<string>;
+  /** Does a connection sign people in through THIS Okta org for Cross App Access? Default: a declared `xaa`
+   *  sign-in whose `idpIssuer` has this org's origin. See {@link xaaNamesOrg}. */
+  readonly proposeOwnAccount?: () => boolean;
+}
+
+/**
+ * (OPE-2453) True when a declared `xaa` sign-in names this Okta org as its IdP. Only then does the arm propose each
+ * person's OWN Okta account (`okta`, the Okta user id) beside the app accounts: the Cross App Access completion
+ * admits a sign-in only for a confirmed `okta` account, and nothing else writes one. With no `xaa` declaration
+ * the arm proposes exactly what it did before, so a deployment that does not use Cross App Access sees no change.
+ */
+export function xaaNamesOrg(orgUrl: string, declared: ReadonlyMap<string, unknown> = declaredConnectionSignIns()): boolean {
+  let origin: string;
+  try {
+    origin = new URL(orgUrl).origin;
+  } catch {
+    return false;
+  }
+  for (const v of declared.values()) {
+    const rec = v as { mode?: unknown; idpIssuer?: unknown };
+    if (rec.mode !== "xaa" || typeof rec.idpIssuer !== "string") continue;
+    try {
+      if (new URL(rec.idpIssuer).origin === origin) return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
 }
 
 /** The display name to show a human, from whichever profile fields Okta actually filled in. DISPLAY
@@ -91,6 +126,7 @@ export function makeOktaDirectoryProvider(deps: OktaDirectoryDeps): DirectoryPro
   const { config } = deps;
   const fetchImpl = deps.fetch ?? fetch;
   const resolveToken = deps.resolveToken ?? ((broker: string, ref: string) => getSecretVia(broker, ref));
+  const proposeOwnAccount = deps.proposeOwnAccount ?? (() => xaaNamesOrg(config.orgUrl));
 
   // The operator's OWN Okta origin — the ONLY origin the SSWS token may ever be sent to. Computed
   // once; every request in getAll (the first AND every `Link: rel="next"` hop) is checked against it.
@@ -196,6 +232,8 @@ export function makeOktaDirectoryProvider(deps: OktaDirectoryDeps): DirectoryPro
       const users = await getAll<OktaUser>(`/api/v1/users?limit=${PAGE_LIMIT}`, token);
       const groups = await groupsByUser(token);
       const accounts = await accountsByUser(token);
+      // Read once per sync, like the token: a declaration change takes effect at the next tick.
+      const ownAccount = proposeOwnAccount();
 
       const people: DirectoryPerson[] = [];
       for (const user of users) {
@@ -205,7 +243,8 @@ export function makeOktaDirectoryProvider(deps: OktaDirectoryDeps): DirectoryPro
           externalId: user.id,
           displayName: displayNameOf(user),
           ...(email ? { email } : {}),
-          accounts: accounts.get(user.id) ?? [],
+          // The Okta user id IS Okta's own answer for its own account, so the grade is "attested".
+          accounts: ownAccount ? [...(accounts.get(user.id) ?? []), { platform: OKTA_LINK_PLATFORM, nativeId: user.id, grade: "attested" }] : (accounts.get(user.id) ?? []),
           groups: (groups.get(user.id) ?? []).slice().sort(),
           deprovisioned: DEPROVISIONED_STATUSES.has((user.status ?? "").toUpperCase()),
         });

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

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