ada-agent 0.7.0 → 0.8.0

package/README.md

@@ -252,6 +252,12 @@ model allowlist + tool rules pushed to every client), per-user usage metering, a
 activated only when you create seats, file-backed, self-hosted in your own network. See
 **[docs/enterprise.md](docs/enterprise.md)** for the 2-minute bootstrap.
 
+**SSO (OIDC)** — federate login to your IdP (Okta, Entra single-tenant, Auth0, Keycloak, Google
+Workspace): `ADA_OIDC_ISSUER=… ada-server`, then developers run `ada login oidc`. The backend
+JIT-provisions a seat for the verified identity and offboarding is immediate. Stdlib-only RS256/JWKS
+verification, no new dependency; fail-closed by construction. See
+**[docs/enterprise-stage2-oidc.md](docs/enterprise-stage2-oidc.md)**.
+
 ## Benchmarks
 
 ada can run **SWE-bench Verified** — it generates patches for real GitHub issues (one isolated repo

package/docs/enterprise-stage2-oidc.md

@@ -0,0 +1,135 @@
+# Enterprise Stage 2 — OIDC SSO + JIT seat provisioning
+
+Status: **shipped in 0.8.0**. This is the design record; the operator runbook is in
+[enterprise.md](enterprise.md#sso-oidc--federate-login-to-your-idp).
+
+## Why this, and why not SAML
+
+After Stage 1 (seats, model allowlist, provider pinning, metering, audit), the #1 enterprise
+security-review gate for a tool that **holds provider API keys** and **reads source code** is
+centralized identity with provable, timely deprovisioning — *"when Alice is offboarded, is her access
+gone in minutes?"* Static `ada_sk_` seat keys can't answer that.
+
+OIDC beat the alternatives on unblock-value ÷ cost, grounded in the real code:
+
+- **vs SAML** — a terminal has no device grant, so SAML needs a brand-new loopback auth-code+PKCE
+  flow *and* an XML-DSig / exclusive-C14N assertion verifier that Node's stdlib can't provide (forcing
+  a dependency or a hand-rolled, XSW-prone verifier). OIDC reuses the existing RFC 8628 device flow
+  (`oauth.ts`) and needs only stdlib RS256/JWKS verification. Most SAML-mandating IdPs speak OIDC too.
+  SAML is deferred to a fast-follow for a contractually SAML-only account.
+- **vs a seatless verify-only login** — real buyers gate on *demonstrable* deprovisioning (SOC 2
+  CC6.3 / ISO 27001 A.9.2.6). Verify-only bounds revocation by IdP token lifetime with no kill switch.
+  We take exactly one rung more: a JIT seat + an immediate `disable-by-externalId` admin endpoint.
+
+Ranking: **oidc-sso (build now) > SCIM (Stage 3) > audit→SIEM export (Stage 4) > SAML (Stage 5a) >
+durable-store/HA (Stage 5c)**.
+
+## Goals / non-goals
+
+**Goals:** federate login to the org's single-tenant OIDC IdP via the device flow; JIT-provision a
+seat keyed to a stable, non-secret, issuer-scoped `externalId` (`iss#sub`); fail closed everywhere;
+RS256/JWKS verification with **zero new dependencies**; an immediate admin deprovision path.
+
+**Non-goals (sequenced later, and honest about it):** SCIM auto-provisioning (Stage 3); SIEM/audit
+**export** (Stage 4 — Stage 2 only *appends* login events, it makes no SIEM-readiness claim); SAML
+(5a); secrets-at-rest encryption of `credentials.json`/`users.json` (5b); Postgres/HA (5c);
+multi-tenant issuers (rejected at load).
+
+## Architecture — model B (seat key as the durable bearer)
+
+The ID token is a **one-time provisioning artifact**, not a per-request credential. This is what makes
+headless work and keeps the long-lived replayable secret a *server-minted, disableable* seat key
+rather than a stealable `id_token`.
+
+```
+1. Client startup: GET /v1/whoami → 401 (backend locked because ADA_OIDC_ISSUER is set).
+2. Client GET /v1/auth/methods (unauth) → { methods:["oidc"], oidc:{ issuer, clientId,
+   deviceAuthEndpoint, tokenEndpoint, scope, exchangePath } }.   ← client needs NO OIDC env of its own
+3. `ada login oidc` runs the device flow against the IdP (browser; MFA/conditional-access enforced
+   BY the IdP). Gets { id_token, access_token, ... }.
+4. Client POST {exchangePath}  Authorization: Bearer <id_token>
+      backend: verifyOidcToken → isProvisionAllowed (group/domain) → upsertSeatForSSO(iss#sub)
+               → audit sso_login → 200 { seat_key: "ada_sk_…", user, role }
+      client: store the SEAT KEY under the "oidc" credential (not the id_token).
+5. Every later request (chat/embeddings/models/whoami, and ALL of -p / serve / acp) sends the
+   ada_sk_ seat key through the hardened identifySeat hot path. No per-request JWKS/RSA, no network.
+6. Offboarding: admin POST /v1/users/disable-by-external { externalId } → next request 401; re-login
+   refused (disabled seat is never resurrected).
+```
+
+## Files, endpoints, env
+
+**New** `src/server/oidc.ts` (stdlib-only): `oidcEnabled()`, `oidcConfig()` (validates + fails closed),
+`assertOidcConfig()` (startup abort), `discover()` (cached openid-configuration), `verifyOidcToken()`
+(RS256/JWKS with a `getKey`/`now` seam for tests), `isProvisionAllowed()`, `mapIdentityToSeatFields()`.
+
+**Changed** `src/server/enterprise.ts`: `Seat` gains `externalId?`/`iss?`; `seatByExternalId()`,
+`upsertSeatForSSO()`, `disableSeatByExternalId()`. `index.ts`: `locked() += oidcEnabled()`; `identify()`
+skips GitHub/Google when OIDC is on; pre-auth `GET /v1/auth/methods` + `POST /v1/auth/oidc/exchange`;
+admin `POST /v1/users/disable-by-external`; startup `assertOidcConfig()`. `oauth.ts`: `deviceGrant()`
+(returns the raw token response incl. `id_token`); `deviceLogin()` builds on it. `cli.ts`:
+`identityToken()` returns the OIDC seat key; `oidcLogin()` + `ensureAuth()` self-configure from
+`/v1/auth/methods`.
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `GET /v1/auth/methods` | none | advertise enabled login methods + public OIDC endpoints |
+| `POST /v1/auth/oidc/exchange` | Bearer = `id_token` | verify → provision → return a seat key (once). The ONLY JWT entry point. |
+| `POST /v1/users/disable-by-external` | admin | immediate offboarding by `iss#sub` |
+
+| Env | Purpose | Gate |
+|---|---|---|
+| `ADA_OIDC_ISSUER` | master opt-in; `iss` + discovery. **https, single-tenant only.** | unset ⇒ inert; multi-tenant ⇒ refuse start |
+| `ADA_OIDC_CLIENT_ID` | device-flow app id; expected `aud`/`azp` | required with issuer |
+| `ADA_OIDC_ALLOWED_GROUPS` | groups permitted to provision | **unset + no domains ⇒ refuse start** |
+| `ADA_OIDC_ALLOWED_DOMAINS` | alt allow-surface (email domains) | — |
+| `ADA_OIDC_ADMIN_GROUP` | group ⇒ `role:"admin"` | unset ⇒ all `dev` |
+| `ADA_OIDC_GROUP_CLAIM` / `ADA_OIDC_NAME_CLAIM` | claim names | `groups` / email→preferred_username→sub |
+| `ADA_OIDC_JWKS_URI` / `ADA_OIDC_AUDIENCE` / `ADA_OIDC_CLOCK_SKEW_MS` / `ADA_OIDC_SCOPE` | overrides | discovered / =client id / 120000 / `openid profile email` |
+
+## Security model — the fail-closed points (each resolves a red-team finding)
+
+- **Backend locks on OIDC.** `locked()` includes `oidcEnabled()`, so a fresh SSO deployment with zero
+  seats never falls to the dev-open `{user:"dev"}` branch. *(Fails closed at `locked()`.)*
+- **No open provisioning.** `isProvisionAllowed()` requires a **positive** group/domain match, and the
+  server **refuses to start** without an allow-surface — a public issuer can't JIT a seat for every
+  account it will sign a token for. Domain matches require a **verified** email (`email_verified:true`
+  in the token) so a self-service IdP can't provision an unverified `attacker@corp.com`; IdPs that omit
+  the claim must use a group allowlist. *(Fails closed at startup + per exchange.)*
+- **Legacy shared keys refused under SSO.** `ADA_CLIENT_KEYS` is ignored whenever OIDC is on (single
+  identity authority), so a still-configured shared key can't bypass verification before the first
+  seat is minted.
+- **Issuer-scoped identity.** `externalId = iss#sub`; multi-tenant issuers rejected at load — a reused
+  `sub` across tenants can't collapse two people onto one seat. *(Fails closed at config load.)*
+- **Immediate, demonstrable deprovisioning.** Model B + `disableSeatByExternalId` +
+  `/v1/users/disable-by-external`: a disabled seat 401s on the next request and re-login is refused,
+  independent of token lifetime. *(Fails closed in `identifySeat`/`upsertSeatForSSO`.)*
+- **One JWT entry point.** The `id_token` is accepted only at `/v1/auth/oidc/exchange`; it never
+  reaches the per-request identity path, so it can't be forwarded to GitHub/Google verification.
+- **Verifier hardening.** `alg` allowlisted to RS256 (rejects `none`/`HS*` key-confusion); `aud` must
+  include the client id; `azp` (when present) must equal the client id, and a multi-audience token
+  without `azp` is rejected; `exp`/`nbf`/`iat` checked with bounded skew. JWKS fetches are rate-capped
+  (≤1 refetch/60s) so an attacker-chosen `kid` can't amplify fetches; `jwks_uri` must be https and is
+  blocked from loopback/private hosts (a lightweight SSRF guard — origin is not pinned to the issuer
+  because Google Workspace serves JWKS from a different origin).
+- **One identity authority.** GitHub/Google login is disabled while OIDC is on, so a person disabled
+  in the IdP can't re-enter via a still-allowed GitHub account. Admin role is downgraded to dev on a
+  login that no longer carries the admin group (privilege revocation); escalation stays an explicit
+  admin action.
+
+## Verification
+
+`npm run typecheck` + `npm run selfcheck` (hermetic: JIT mint/reuse/no-escalation, immediate
+deprovision-by-externalId, prototype-safe scan, and a full RS256 verify test with a local keypair +
+injected JWKS covering tamper/wrong-aud/`alg=none`/expiry → all `null`). Live-verified: OIDC-locked
+backend 401s a tokenless request, fail-closed startup on missing allow-surface and multi-tenant
+issuer, real-Google discovery + JWKS guard, exchange rejects a bogus token.
+
+## Roadmap
+
+- **Stage 3 — SCIM 2.0**: admin-gated `/scim/v2/Users` driving `createSeat`/`disableSeatByExternalId`
+  on the `iss#sub` index shipped here (no migration). Automates joiner/mover/leaver.
+- **Stage 4 — audit/usage SIEM export**: tee `appendAudit`/`appendUsage` to syslog/webhook/OTLP-JSON;
+  audit hash-chain + `GET /v1/audit/verify`. Carries the Stage 2/3 `sso_*`/`scim_*` events.
+- **Stage 5** — SAML (named account only); secrets-at-rest encryption; Postgres/HA at the `dataDir()`
+  seam.

package/docs/enterprise.md

@@ -41,6 +41,57 @@ DELETE /v1/users/<keyPrefix>   # disable a seat (≥12 chars of its key; kept fo
 Full keys are never listed after creation — only a 14-char prefix. `ADA_ADMIN_KEY` is the
 break-glass admin; create an admin *seat* for day-to-day and keep the env key in a vault.
 
+## SSO (OIDC) — federate login to your IdP
+
+Instead of handing out static seat keys, connect your OIDC IdP (Okta, Entra **single-tenant**, Auth0,
+Keycloak, Google Workspace). Developers sign in through the browser via the device flow, and the
+backend **JIT-provisions a seat** for the verified identity. Seats are keyed to a stable, non-secret
+`iss#sub`, so offboarding has a target.
+
+```bash
+# On the backend (all values are non-secret except any confidential-client secret):
+export ADA_OIDC_ISSUER=https://your-tenant.okta.com          # single-tenant issuer URL (https)
+export ADA_OIDC_CLIENT_ID=<device-flow app client id>
+export ADA_OIDC_ALLOWED_GROUPS=ada-users                     # OR ADA_OIDC_ALLOWED_DOMAINS=yourco.com
+export ADA_OIDC_ADMIN_GROUP=ada-admins                       # optional: this group → role "admin"
+ada-server                                                   # banner: [OIDC SSO (0 seats — awaiting first login)]
+```
+
+**Setting `ADA_OIDC_ISSUER` locks the backend immediately** (before any seat exists) — a request
+that doesn't authenticate gets `401`, never dev-open. Two fail-closed guards refuse to start on unsafe
+config: no `ALLOWED_GROUPS`/`ALLOWED_DOMAINS` (would provision every IdP user), or a **multi-tenant**
+issuer (`.../common` or `.../organizations`, where `sub` isn't unique). When OIDC is on, the
+GitHub/Google login path is disabled — the IdP is the single identity authority.
+
+The developer needs **no OIDC config** — the client learns it from the backend:
+
+```bash
+export ADA_BACKEND_URL=https://ada.yourcompany.com/v1
+ada login oidc     # opens the IdP in a browser; on success stores a seat key. Then just `ada`.
+```
+
+Under the hood the ID token is a **one-time provisioning artifact**: `ada login oidc` exchanges it at
+`POST /v1/auth/oidc/exchange` for a durable `ada_sk_` seat key, and every later request (including
+`-p`, `serve`, `acp`) carries that seat key — so long headless runs never expire mid-job, and
+revocation is a seat-disable, not a token-lifetime wait.
+
+**Offboarding (immediate):** disable the seat by its `iss#sub`. The next request 401s and re-login is
+refused (a disabled seat is never resurrected).
+
+```bash
+curl -X POST -H "Authorization: Bearer $ADA_ADMIN_KEY" \
+     -d '{"externalId":"https://your-tenant.okta.com#00u1a2b3c4"}' \
+     http://localhost:8787/v1/users/disable-by-external
+```
+
+`GET /v1/auth/methods` (unauthenticated) advertises the enabled methods. ID-token verification is
+stdlib-only (RS256 + JWKS, `alg` allowlisted, `iss`/`aud`/`azp`/`exp`/`nbf` checked) — no new
+dependency. Full env reference and the security model: [enterprise-stage2-oidc.md](enterprise-stage2-oidc.md).
+
+Automated joiner/mover/leaver (**SCIM**) and audit **export to a SIEM** are the sequenced next stages;
+today login events (`sso_login`, `sso_login_denied`, `seat_created`, `seat_disabled`) are appended to
+the audit log but not yet streamed out.
+
 ## Org policy
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ada-agent",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A from-zero terminal coding agent with a Cursor-style routing backend, ~285 skills, MCP connectors, and ask/plan/auto modes",
   "type": "module",
   "license": "MIT",

package/src/client/cli.ts

@@ -12,8 +12,8 @@ import { Agent, type AgentEvent, type ApprovalDecision, type OnApprove } from ".
 import { ApprovalRegistry, newId, sseFrame } from "./agent-server.ts";
 import { expandPrompt, loadPrompts } from "./prompts.ts";
 import { Session, list, type SessionMeta } from "./session.ts";
-import { deleteCredential, getCredential, listCredentials } from "../server/credentials.ts";
-import { deviceLogin, oauthConfig } from "../server/oauth.ts";
+import { deleteCredential, getCredential, listCredentials, setCredential } from "../server/credentials.ts";
+import { deviceGrant, deviceLogin, oauthConfig } from "../server/oauth.ts";
 import { addTrust, isTrusted, loadSettings, setActiveAgentPermissions, setOrgPermissions, type PermRule, type Settings } from "./settings.ts";
 import { getCommands, loadExtensions } from "./extensions.ts";
 import { registerTool, setAsker } from "./tools.ts";
@@ -36,8 +36,12 @@ type RL = ReturnType<typeof createInterface>;
 
 const BACKEND = process.env.ADA_BACKEND_URL ?? "http://localhost:8787/v1";
 
-/** A stored GitHub/Google login token, sent as the bearer so the backend can identify us. */
+/** A stored login credential, sent as the bearer so the backend can identify us. An OIDC SSO seat
+ *  key (ada_sk_…) wins — it's a durable, server-minted, disableable bearer (see oidcLogin). A seat
+ *  key is only honored by the backend that minted it, so a stray one sent elsewhere just 401s. */
 function identityToken(): string | undefined {
+  const oidc = getCredential("oidc");
+  if (oidc?.type === "oauth" && oidc.key) return oidc.key;
   for (const p of ["github", "google"]) {
     const c = getCredential(p);
     if (c?.type === "oauth" && c.access) return c.access;
@@ -353,8 +357,52 @@ function makeClient(): OpenAI {
   return new OpenAI({ baseURL: BACKEND, apiKey: clientKey(), maxRetries: 0 });
 }
 
-/** Run the device flow for `provider`; returns true on success (token stored). */
+interface AuthMethods {
+  methods: string[];
+  oidc?: { issuer: string; clientId: string; deviceAuthEndpoint: string; tokenEndpoint: string; scope: string; exchangePath: string };
+  oidcError?: string;
+}
+
+/** Ask the backend which login methods it offers (so the client needs no OIDC env of its own). */
+async function fetchAuthMethods(): Promise<AuthMethods | null> {
+  try {
+    const r = await fetch(`${BACKEND}/auth/methods`, { signal: AbortSignal.timeout(4000) });
+    if (!r.ok) return null;
+    return (await r.json()) as AuthMethods;
+  } catch {
+    return null;
+  }
+}
+
+/** OIDC SSO login (model B): device-flow against the org IdP using the backend-advertised config,
+ *  then exchange the id_token for a durable seat key stored under the "oidc" credential. */
+async function oidcLogin(): Promise<boolean> {
+  const m = await fetchAuthMethods();
+  if (!m?.oidc) {
+    console.log(m?.oidcError ? `SSO unavailable: ${m.oidcError}` : "this backend does not offer OIDC SSO.");
+    return false;
+  }
+  const { clientId, deviceAuthEndpoint, tokenEndpoint, scope, exchangePath } = m.oidc;
+  try {
+    const tok = await deviceGrant("SSO", { clientId, deviceUrl: deviceAuthEndpoint, tokenUrl: tokenEndpoint, scope }, (s) => console.log(s));
+    const idToken = tok.id_token as string | undefined;
+    if (!idToken) throw new Error("IdP returned no id_token — ensure the 'openid' scope is granted");
+    const r = await fetch(`${BACKEND}${exchangePath}`, { method: "POST", headers: { authorization: `Bearer ${idToken}` } });
+    if (!r.ok) throw new Error(`exchange failed: HTTP ${r.status} ${await r.text().catch(() => "")}`);
+    const { seat_key, user, role } = (await r.json()) as { seat_key?: string; user?: string; role?: string };
+    if (!seat_key) throw new Error("backend returned no seat_key");
+    await setCredential("oidc", { type: "oauth", key: seat_key });
+    console.log(`Logged in via SSO as ${user} (${role}).`);
+    return true;
+  } catch (e) {
+    console.error(`SSO login failed: ${e instanceof Error ? e.message : e}`);
+    return false;
+  }
+}
+
+/** Run the device flow for `provider`; returns true on success (credential stored). */
 async function loginFlow(provider: string): Promise<boolean> {
+  if (provider === "oidc" || provider === "sso") return oidcLogin();
   const cfg = oauthConfig(provider);
   if (!cfg) {
     console.log(`No OAuth config for ${provider}. Set ADA_OAUTH_${provider.toUpperCase()}_{CLIENT_ID,DEVICE_URL,TOKEN_URL}.`);
@@ -411,12 +459,16 @@ async function ensureAuth(rl: RL, client: OpenAI): Promise<OpenAI> {
     return client; // backend unreachable — the model fetch will report it
   }
   if (status !== 401) return client; // 200 = already authorized, or backend is open (dev)
-  const provider = ["github", "google"].find((p) => oauthConfig(p));
+  // Prefer the org IdP if the backend advertises OIDC SSO; else fall back to a locally-configured
+  // GitHub/Google OAuth app.
+  const methods = await fetchAuthMethods();
+  const provider = methods?.methods.includes("oidc") ? "oidc" : ["github", "google"].find((p) => oauthConfig(p));
   if (!provider) {
-    console.log("\x1b[33mthis backend requires login, but no OAuth provider is configured (set ADA_OAUTH_*).\x1b[0m");
+    console.log("\x1b[33mthis backend requires login, but no login method is available (backend offers no SSO and no ADA_OAUTH_* is set).\x1b[0m");
     return client;
   }
-  const ans = (await rl.question(`\x1b[33mnot logged in — sign in with ${provider}? [Y/n] \x1b[0m`)).trim().toLowerCase();
+  const label = provider === "oidc" ? `your org (${methods?.oidc?.issuer ?? "SSO"})` : provider;
+  const ans = (await rl.question(`\x1b[33mnot logged in — sign in with ${label}? [Y/n] \x1b[0m`)).trim().toLowerCase();
   if (ans === "n" || ans === "no") return client;
   return (await loginFlow(provider)) ? makeClient() : client;
 }

package/src/selfcheck.ts

@@ -349,6 +349,86 @@ async function main(): Promise<void> {
     }
   }
 
+  // --- OIDC SSO (Stage 2): JIT seat invariants + hermetic RS256 id-token verification ---
+  {
+    const dir = join(tmpdir(), `ada-oidc-${Date.now()}`);
+    const ent = await import("./server/enterprise.ts");
+    const oidc = await import("./server/oidc.ts");
+    const { generateKeyPairSync, sign } = await import("node:crypto");
+    const savedEnv = { ...process.env };
+    const iss = "https://idp.example.com";
+    process.env.ADA_DATA_DIR = dir;
+    process.env.ADA_OIDC_ISSUER = iss;
+    process.env.ADA_OIDC_CLIENT_ID = "ada-client";
+    process.env.ADA_OIDC_ALLOWED_GROUPS = "engineering";
+    process.env.ADA_OIDC_ADMIN_GROUP = "admins";
+    try {
+      // JIT seat provisioning invariants (the load-bearing new behavior).
+      const ext = `${iss}#sub-123`;
+      const k1 = ent.upsertSeatForSSO(ext, iss, "sso-user", "dev", dir);
+      assert.ok(k1 && k1.startsWith("ada_sk_") && k1.length > 40, "OIDC JIT mints a valid seat key");
+      assert.equal(ent.upsertSeatForSSO(ext, iss, "sso-user", "dev", dir), k1, "same iss#sub reuses one seat (no key rotation)");
+      assert.equal(ent.upsertSeatForSSO(ext, iss, "sso-user", "admin", dir), k1, "existing seat is NOT auto-escalated to admin on login");
+      assert.deepEqual(ent.identifySeat(k1!, dir), { user: "sso-user", role: "dev" }, "SSO seat key authenticates like any seat");
+      assert.equal(ent.disableSeatByExternalId(ext, dir), "sso-user", "disable-by-externalId offboards");
+      assert.equal(ent.upsertSeatForSSO(ext, iss, "sso-user", "dev", dir), null, "disabled externalId denies re-login (fail-closed deprovision, no resurrect)");
+      assert.equal(ent.identifySeat(k1!, dir), null, "disabled SSO seat no longer authenticates");
+      assert.equal(ent.seatByExternalId("__proto__", dir), null, "externalId scan is prototype-safe");
+      // admin→dev downgrade when the admin group drops off a later login.
+      const ext2 = `${iss}#boss`;
+      const kb = ent.upsertSeatForSSO(ext2, iss, "boss", "admin", dir);
+      assert.equal(ent.identifySeat(kb!, dir)!.role, "admin", "admin seat provisioned");
+      assert.equal(ent.upsertSeatForSSO(ext2, iss, "boss", "dev", dir), kb, "downgrade reuses the same key");
+      assert.equal(ent.identifySeat(kb!, dir)!.role, "dev", "admin→dev downgrade on group removal");
+
+      // group/domain gate.
+      assert.ok(oidc.isProvisionAllowed({ iss, sub: "s", name: "n", groups: ["engineering"] }), "allowed group provisions");
+      assert.ok(!oidc.isProvisionAllowed({ iss, sub: "s", name: "n", groups: ["other"], email: "x@evil.com" }), "non-allowed group/domain refused");
+      assert.equal(oidc.mapIdentityToSeatFields({ iss, sub: "z", name: "z", groups: ["admins"] }).role, "admin", "admin group → admin role");
+
+      // Hermetic RS256 verification: sign a token locally, verify via an injected JWKS key.
+      const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+      const pubJwk = { ...(publicKey.export({ format: "jwk" }) as Record<string, unknown>), kid: "test", kty: "RSA" };
+      const getKey = (kid: string) => (kid === "test" ? pubJwk : null);
+      const now = 1_800_000_000_000;
+      const sec = Math.floor(now / 1000);
+      const b64u = (o: unknown): string => Buffer.from(typeof o === "string" ? o : JSON.stringify(o)).toString("base64url");
+      const mkToken = (payload: Record<string, unknown>, alg = "RS256"): string => {
+        const head = b64u({ alg, kid: "test", typ: "JWT" });
+        const body = b64u(payload);
+        if (alg === "none") return `${head}.${body}.`;
+        return `${head}.${body}.${sign("RSA-SHA256", Buffer.from(`${head}.${body}`), privateKey).toString("base64url")}`;
+      };
+      const good = { iss, aud: "ada-client", sub: "sub-123", exp: sec + 3600, iat: sec, groups: ["engineering"], email: "dev@corp.com" };
+      const id = await oidc.verifyOidcToken(mkToken(good), { getKey, now });
+      assert.ok(id && id.sub === "sub-123" && id.iss === iss, "valid RS256 id_token verifies");
+      const validTok = mkToken(good);
+      assert.equal(await oidc.verifyOidcToken(`${validTok.slice(0, -4)}AAAA`, { getKey, now }), null, "tampered signature → null");
+      assert.equal(await oidc.verifyOidcToken(mkToken({ ...good, aud: "someone-else" }), { getKey, now }), null, "wrong audience → null");
+      assert.equal(await oidc.verifyOidcToken(mkToken(good, "none"), { getKey, now }), null, "alg=none → null (no key confusion)");
+      assert.equal(await oidc.verifyOidcToken(mkToken({ ...good, exp: sec - 7200 }), { getKey, now }), null, "expired token → null");
+      // email is trusted only when the IdP marks it verified (domain-provisioning fail-open fix).
+      const idU = await oidc.verifyOidcToken(mkToken({ ...good, email: "x@corp.com", email_verified: false }), { getKey, now });
+      assert.ok(idU && idU.email === undefined, "unverified email dropped from identity");
+      const idV = await oidc.verifyOidcToken(mkToken({ ...good, email: "x@corp.com", email_verified: true }), { getKey, now });
+      assert.equal(idV!.email, "x@corp.com", "verified email kept");
+
+      // SSRF guard classifies against a parsed IP (net.isIP), not a string prefix.
+      for (const bad of ["https://[::1]/keys", "https://[fe80::1]/keys", "https://[fc00::1]/keys", "https://[::ffff:127.0.0.1]/keys", "https://127.0.0.1/keys", "https://10.1.2.3/keys", "http://idp.okta.com/keys"]) {
+        assert.throws(() => oidc.assertSafeJwksUri(bad), `jwks_uri rejected: ${bad}`);
+      }
+      for (const ok of ["https://fcm.googleapis.com/keys", "https://fd-idp.corp.com/keys", "https://your-tenant.okta.com/oauth2/v1/keys"]) {
+        assert.doesNotThrow(() => oidc.assertSafeJwksUri(ok), `jwks_uri allowed: ${ok}`);
+      }
+    } finally {
+      for (const k of ["ADA_DATA_DIR", "ADA_OIDC_ISSUER", "ADA_OIDC_CLIENT_ID", "ADA_OIDC_ALLOWED_GROUPS", "ADA_OIDC_ADMIN_GROUP"]) {
+        if (savedEnv[k] === undefined) delete process.env[k];
+        else process.env[k] = savedEnv[k];
+      }
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
   // --- org policy merge: restrictive wins, org can tighten but never loosen ---
   {
     const { permissionFor, setActiveAgentPermissions, setOrgPermissions } = await import("./client/settings.ts");

package/src/server/enterprise.ts

@@ -35,6 +35,8 @@ export interface Seat {
   role: "admin" | "dev";
   created: string;
   disabled?: boolean;
+  externalId?: string; // OIDC SSO: issuer-scoped stable id (`iss#sub`) — non-secret, the deprovision target
+  iss?: string; // OIDC issuer the seat was provisioned from (so an issuer change is detectable)
 }
 export interface PolicyRule {
   tool?: string;
@@ -137,6 +139,66 @@ export function createSeat(name: string, role: "admin" | "dev" = "dev", dir = da
   return key;
 }
 
+/** Find a seat by its OIDC externalId (`iss#sub`). Scans the (small) seat map by VALUE — externalId
+ *  is compared, never used as a lookup key, so it's inherently prototype-safe. Inherits CorruptStore
+ *  from loadSeats (callers fail closed). */
+export function seatByExternalId(externalId: string, dir = dataDir()): { key: string; seat: Seat } | null {
+  const seats = loadSeats(dir);
+  for (const key of Object.keys(seats)) {
+    const seat = seats[key]!;
+    if (seat.externalId === externalId) return { key, seat };
+  }
+  return null;
+}
+
+/** JIT-provision (or reuse) a seat for a verified OIDC identity. Returns the seat's `ada_sk_` key, or
+ *  null if the seat exists but is DISABLED (a deprovisioned user must not be resurrected by re-login).
+ *  - existing enabled seat → reuse its key (NO rotation); if it was admin and the login no longer
+ *    carries the admin group, downgrade admin→dev (privilege revocation). Never auto-ESCALATE here.
+ *  - new identity → mint one key, stamp externalId+iss, one `seat_created` audit row. */
+export function upsertSeatForSSO(externalId: string, iss: string, name: string, role: "admin" | "dev", dir = dataDir()): string | null {
+  const seats = loadSeats(dir);
+  let foundKey: string | null = null;
+  for (const key of Object.keys(seats)) {
+    if (seats[key]!.externalId === externalId) {
+      foundKey = key;
+      break;
+    }
+  }
+  if (foundKey) {
+    const seat = seats[foundKey]!;
+    if (seat.disabled) return null; // deprovisioned — do NOT resurrect
+    if (seat.role === "admin" && role === "dev") {
+      seat.role = "dev";
+      saveSeats(seats, dir);
+      appendAudit({ ts: Date.now(), user: name, event: "role_changed", detail: `${name} admin→dev (SSO group removed)` }, dir);
+    }
+    return foundKey;
+  }
+  const key = `ada_sk_${randomBytes(24).toString("hex")}`;
+  seats[key] = { name, role, created: new Date().toISOString(), externalId, iss };
+  saveSeats(seats, dir);
+  appendAudit({ ts: Date.now(), user: name, event: "seat_created", detail: `${name} (${role}) via OIDC ${externalId}` }, dir);
+  return key;
+}
+
+/** Immediate offboarding: disable the seat for an OIDC externalId. The admin endpoint (and, later,
+ *  SCIM DELETE) call this — the next identifySeat for that key returns null (401). */
+export function disableSeatByExternalId(externalId: string, dir = dataDir()): string | null {
+  const seats = loadSeats(dir);
+  for (const key of Object.keys(seats)) {
+    const seat = seats[key]!;
+    if (seat.externalId === externalId) {
+      if (seat.disabled) return seat.name; // idempotent
+      seat.disabled = true;
+      saveSeats(seats, dir);
+      appendAudit({ ts: Date.now(), user: seat.name, event: "seat_disabled", detail: `${seat.name} (SSO ${externalId})` }, dir);
+      return seat.name;
+    }
+  }
+  return null;
+}
+
 /** Disable (not delete — the audit trail keeps the history) the seat whose key starts with prefix. */
 export function disableSeat(prefix: string, dir = dataDir()): string | null {
   if (prefix.length < 12) return null; // too short to be safely unique

package/src/server/index.ts

@@ -5,8 +5,9 @@
 import { createServer } from "node:http";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { PORT, PROVIDERS, clientKeys, configuredProviders, isConfigured } from "./config.ts";
-import { CorruptStore, type Identity, appendAudit, appendUsage, auditTail, createSeat, disableSeat, enterpriseMode, extractLastUsage, identifySeat, listSeats, loadPolicy, modelAllowed, savePolicy, usageSummary, validatePolicy } from "./enterprise.ts";
+import { CorruptStore, type Identity, appendAudit, appendUsage, auditTail, createSeat, disableSeat, disableSeatByExternalId, enterpriseMode, extractLastUsage, identifySeat, listSeats, loadPolicy, modelAllowed, savePolicy, upsertSeatForSSO, usageSummary, validatePolicy } from "./enterprise.ts";
 import { allowedUsers, isAllowed, verifyIdentity } from "./identity.ts";
+import { assertOidcConfig, discover, isProvisionAllowed, mapIdentityToSeatFields, oidcConfig, oidcEnabled, verifyOidcToken } from "./oidc.ts";
 import { adapterFor } from "./providers/registry.ts";
 import { route } from "./router.ts";
 
@@ -20,7 +21,9 @@ function readBody(req: IncomingMessage): Promise<string> {
 }
 
 function locked(): boolean {
-  return enterpriseMode() || clientKeys() !== null || allowedUsers() !== null || !!process.env.ADA_REQUIRE_LOGIN;
+  // OIDC must lock the backend the instant ADA_OIDC_ISSUER is set — BEFORE any seat exists — else a
+  // fresh SSO deployment with zero seats would fall through identify() to dev-open.
+  return enterpriseMode() || clientKeys() !== null || allowedUsers() !== null || oidcEnabled() || !!process.env.ADA_REQUIRE_LOGIN;
 }
 
 /** Resolve a request to WHO is making it. Order: seat key / ADA_ADMIN_KEY (enterprise), legacy
@@ -40,10 +43,17 @@ async function identify(req: IncomingMessage): Promise<Identity | "corrupt" | nu
     }
     if (seat) return seat;
     // Legacy ADA_CLIENT_KEYS are NOT honored once seats/admin-key exist — enterprise supersedes them,
-    // so a disabled seat can't be resurrected via a still-configured shared key.
-    if (!enterpriseMode() && clientKeys()?.includes(token)) return { user: "team", role: "dev" };
-    const id = await verifyIdentity(token); // GitHub / Google login
-    if (id && isAllowed(id.user)) return { user: id.user, role: "dev" };
+    // so a disabled seat can't be resurrected via a still-configured shared key. They're ALSO refused
+    // whenever OIDC is the org's IdP (single identity authority) — else a still-set shared key would
+    // bypass SSO verification during the window before the first seat is minted.
+    if (!oidcEnabled() && !enterpriseMode() && clientKeys()?.includes(token)) return { user: "team", role: "dev" };
+    // One identity authority: when OIDC is the org's IdP, the GitHub/Google login path is disabled so
+    // a person disabled in the IdP can't re-enter via a still-allowed GitHub account. (SSO users
+    // authenticate at /v1/auth/oidc/exchange and then carry a seat key, not an id_token, per request.)
+    if (!oidcEnabled()) {
+      const id = await verifyIdentity(token); // GitHub / Google login
+      if (id && isAllowed(id.user)) return { user: id.user, role: "dev" };
+    }
   }
   return locked() ? null : { user: "dev", role: "dev" }; // dev mode: open
 }
@@ -162,6 +172,74 @@ async function handleEmbeddings(req: IncomingMessage, res: ServerResponse, who:
   res.end(text);
 }
 
+/** Public: advertise enabled login methods so the terminal client can self-configure (no OIDC env on
+ *  the client). For OIDC it returns the issuer + client id + device/token endpoints (all public
+ *  discovery values) plus the exchange path. Unauthenticated by design. */
+async function handleAuthMethods(res: ServerResponse): Promise<void> {
+  const methods: string[] = [];
+  const out: Record<string, unknown> = {};
+  if (oidcEnabled()) {
+    try {
+      const cfg = oidcConfig();
+      const d = await discover();
+      if (d.device_authorization_endpoint && d.token_endpoint) {
+        methods.push("oidc");
+        out.oidc = {
+          issuer: cfg.issuer,
+          clientId: cfg.clientId,
+          deviceAuthEndpoint: d.device_authorization_endpoint,
+          tokenEndpoint: d.token_endpoint,
+          scope: cfg.scope,
+          exchangePath: "/v1/auth/oidc/exchange",
+        };
+      } else {
+        out.oidcError = "IdP does not advertise a device_authorization_endpoint (device flow unavailable)";
+      }
+    } catch (e) {
+      out.oidcError = e instanceof Error ? e.message : String(e);
+    }
+  }
+  return json(res, 200, { methods, ...out });
+}
+
+/** Public: exchange a verified OIDC id_token for a seat key (model B — the id_token is a one-time
+ *  provisioning artifact; every later request carries the returned ada_sk_ seat key). This is the
+ *  ONLY endpoint that accepts a JWT, so an id_token never reaches the per-request seat/identity path. */
+async function handleOidcExchange(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  if (!oidcEnabled()) return json(res, 404, { error: { message: "OIDC not enabled" } });
+  const h = req.headers["authorization"];
+  const idToken = typeof h === "string" && h.startsWith("Bearer ") ? h.slice(7) : "";
+  if (!idToken) return json(res, 401, { error: { message: "missing id_token bearer" } });
+
+  let identity: Awaited<ReturnType<typeof verifyOidcToken>>;
+  try {
+    identity = await verifyOidcToken(idToken);
+  } catch {
+    identity = null;
+  }
+  if (!identity) return json(res, 401, { error: { message: "invalid or unverifiable id_token" } });
+
+  if (!isProvisionAllowed(identity)) {
+    appendAudit({ ts: Date.now(), user: identity.email ?? identity.sub, event: "sso_login_denied", detail: `not in allowed group/domain: ${identity.iss}#${identity.sub}` });
+    return json(res, 403, { error: { message: "not authorized by org group/domain policy" } });
+  }
+
+  const { externalId, iss, name, role } = mapIdentityToSeatFields(identity);
+  let key: string | null;
+  try {
+    key = upsertSeatForSSO(externalId, iss, name, role);
+  } catch (e) {
+    if (e instanceof CorruptStore) return json(res, 503, { error: { message: "seat store unreadable — refusing to provision (fail-closed)" } });
+    throw e;
+  }
+  if (!key) {
+    appendAudit({ ts: Date.now(), user: name, event: "sso_login_denied", detail: `seat disabled: ${externalId}` });
+    return json(res, 403, { error: { message: "your seat has been disabled — contact your admin" } });
+  }
+  appendAudit({ ts: Date.now(), user: name, event: "sso_login", detail: externalId });
+  return json(res, 200, { seat_key: key, user: name, role });
+}
+
 const server = createServer(async (req, res) => {
   try {
     const url = new URL(req.url ?? "/", "http://localhost");
@@ -169,6 +247,10 @@ const server = createServer(async (req, res) => {
       res.writeHead(200, { "content-type": "text/plain" });
       return res.end("ada backend ok");
     }
+    // Pre-auth login routes (a locked backend must still let a new user authenticate).
+    if (req.method === "GET" && url.pathname === "/v1/auth/methods") return await handleAuthMethods(res);
+    if (req.method === "POST" && url.pathname === "/v1/auth/oidc/exchange") return await handleOidcExchange(req, res);
+
     const who = await identify(req);
     if (who === "corrupt") return json(res, 503, { error: { message: "auth store unreadable — refusing all requests (fail-closed). Fix ~/.ada/server/users.json." } });
     if (!who) return json(res, 401, { error: { message: "unauthorized — invalid client key, seat key, or login" } });
@@ -239,6 +321,26 @@ const server = createServer(async (req, res) => {
         return json(res, name ? 200 : 404, name ? { ok: true, disabled: name } : { error: { message: "unknown or ambiguous key prefix (send ≥12 chars)" } });
       }
     }
+    // Immediate offboarding by OIDC externalId (`iss#sub`) — the entry point an admin (or Stage-3
+    // SCIM) uses to kill a leaver's access without waiting for the id_token to expire.
+    if (req.method === "POST" && url.pathname === "/v1/users/disable-by-external") {
+      if (who.role !== "admin") return json(res, 403, { error: { message: "admin only" } });
+      let externalId = "";
+      try {
+        externalId = String((JSON.parse(await readBody(req)) as { externalId?: string }).externalId ?? "").trim();
+      } catch {
+        /* falls through to the empty check */
+      }
+      if (!externalId) return json(res, 400, { error: { message: "missing 'externalId' (iss#sub)" } });
+      let name: string | null;
+      try {
+        name = disableSeatByExternalId(externalId);
+      } catch (e) {
+        if (e instanceof CorruptStore) return json(res, 503, { error: { message: "seat store unreadable" } });
+        throw e;
+      }
+      return json(res, name ? 200 : 404, name ? { ok: true, disabled: name } : { error: { message: "no seat for that externalId" } });
+    }
     if (req.method === "GET" && url.pathname === "/v1/usage") {
       if (who.role !== "admin") return json(res, 403, { error: { message: "admin only" } });
       return json(res, 200, usageSummary(Math.min(Number(url.searchParams.get("days")) || 30, 365)));
@@ -260,14 +362,26 @@ const server = createServer(async (req, res) => {
   }
 });
 
+// Fail fast on bad OIDC config (multi-tenant issuer, missing allow-surface, …) — never boot into a
+// state where SSO would provision seats unsafely.
+try {
+  assertOidcConfig();
+} catch (e) {
+  console.error(`\x1b[31m[fatal] OIDC misconfigured: ${e instanceof Error ? e.message : e}\x1b[0m`);
+  process.exit(1);
+}
+
 server.listen(PORT, () => {
-  if (enterpriseMode() && clientKeys()) console.warn("\x1b[33m[warn] ADA_CLIENT_KEYS is set but ignored in enterprise mode (seats supersede it) — unset it to avoid confusion.\x1b[0m");
+  if ((enterpriseMode() || oidcEnabled()) && clientKeys()) console.warn("\x1b[33m[warn] ADA_CLIENT_KEYS is set but ignored in enterprise/OIDC mode (seats/SSO supersede it) — unset it to avoid confusion.\x1b[0m");
   const seats = listSeats().filter((s) => !s.disabled).length;
+  const sso = oidcEnabled() ? " + OIDC SSO" : "";
   const auth = enterpriseMode()
-    ? `ENTERPRISE (${seats} seat${seats === 1 ? "" : "s"}${process.env.ADA_ADMIN_KEY ? " + admin key" : ""})`
-    : locked()
-      ? `auth ON (client keys + GitHub/Google login${allowedUsers() ? `, allowlist: ${allowedUsers()!.length}` : ""})`
-      : "AUTH DISABLED (dev) — set ADA_CLIENT_KEYS or ADA_ADMIN_KEY to lock down";
+    ? `ENTERPRISE (${seats} seat${seats === 1 ? "" : "s"}${process.env.ADA_ADMIN_KEY ? " + admin key" : ""}${sso})`
+    : oidcEnabled()
+      ? `OIDC SSO (0 seats — awaiting first login)`
+      : locked()
+        ? `auth ON (client keys + GitHub/Google login${allowedUsers() ? `, allowlist: ${allowedUsers()!.length}` : ""})`
+        : "AUTH DISABLED (dev) — set ADA_CLIENT_KEYS or ADA_ADMIN_KEY to lock down";
   const provs = configuredProviders();
   console.log(`ada backend → http://localhost:${PORT}  [${auth}]`);
   console.log(`providers: ${provs.length ? provs.join(", ") : "(none configured — set provider API keys)"}`);

package/src/server/oauth.ts

@@ -55,8 +55,10 @@ async function postForm(url: string, body: Record<string, string>): Promise<Reco
   return (await res.json()) as Record<string, unknown>;
 }
 
-/** Run the device flow: print the user code, poll for the token, store it on success. */
-export async function deviceLogin(provider: string, cfg: OAuthConfig, print: (s: string) => void): Promise<void> {
+/** Run the device flow: print the user code, poll, and RETURN the raw token response (access_token,
+ *  id_token, refresh_token, …) without storing anything. Callers decide what to persist — GitHub/Google
+ *  store the access token (deviceLogin below); OIDC SSO exchanges the id_token for a seat key. */
+export async function deviceGrant(provider: string, cfg: OAuthConfig, print: (s: string) => void): Promise<Record<string, unknown>> {
   const secret: Record<string, string> = cfg.clientSecret ? { client_secret: cfg.clientSecret } : {};
   const dev = await postForm(cfg.deviceUrl, { client_id: cfg.clientId, scope: cfg.scope ?? "", ...secret });
   const deviceCode = dev.device_code as string;
@@ -74,16 +76,7 @@ export async function deviceLogin(provider: string, cfg: OAuthConfig, print: (s:
       grant_type: "urn:ietf:params:oauth:grant-type:device_code",
       ...secret,
     });
-    if (tok.access_token) {
-      await setCredential(provider, {
-        type: "oauth",
-        access: tok.access_token as string,
-        refresh: tok.refresh_token as string | undefined,
-        expires: tok.expires_in ? Date.now() + Number(tok.expires_in) * 1000 : undefined,
-      });
-      print(`Logged in to ${provider}.`);
-      return;
-    }
+    if (tok.access_token || tok.id_token) return tok;
     const err = tok.error as string | undefined;
     if (err && err !== "authorization_pending" && err !== "slow_down") {
       throw new Error((tok.error_description as string) ?? err);
@@ -91,3 +84,15 @@ export async function deviceLogin(provider: string, cfg: OAuthConfig, print: (s:
   }
   throw new Error("device login timed out");
 }
+
+/** Device flow for identity providers (GitHub/Google): grant, then store the access token. */
+export async function deviceLogin(provider: string, cfg: OAuthConfig, print: (s: string) => void): Promise<void> {
+  const tok = await deviceGrant(provider, cfg, print);
+  await setCredential(provider, {
+    type: "oauth",
+    access: tok.access_token as string,
+    refresh: tok.refresh_token as string | undefined,
+    expires: tok.expires_in ? Date.now() + Number(tok.expires_in) * 1000 : undefined,
+  });
+  print(`Logged in to ${provider}.`);
+}

package/src/server/oidc.ts

@@ -0,0 +1,300 @@
+// OIDC SSO for the enterprise control plane (Stage 2). The org connects its IdP (Okta, Entra
+// single-tenant, Auth0, Keycloak, Google Workspace) via ADA_OIDC_ISSUER; a terminal user runs the
+// device flow in a browser and the backend maps the verified ID token to a seat (see enterprise.ts
+// upsertSeatForSSO). ID-token verification is stdlib-only (node:crypto RS256 + JWKS) — no new dep.
+//
+// Fail-closed contract (hardened after an adversarial red-team):
+//   - setting ADA_OIDC_ISSUER LOCKS the backend (see index.ts locked()), before any seat exists;
+//   - provisioning requires a POSITIVE group/domain match — an empty allowlist refuses to start,
+//     so a public/multi-tenant issuer can't JIT a seat for every account it will sign a token for;
+//   - multi-tenant issuers (Entra common/organizations) are rejected at config load;
+//   - seats key on `iss#sub` (issuer-scoped), so a reused `sub` across IdPs can't collide.
+
+import { createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { isIP } from "node:net";
+
+export interface OidcConfig {
+  issuer: string;
+  clientId: string;
+  audience: string;
+  allowedGroups: string[];
+  allowedDomains: string[];
+  adminGroup?: string;
+  groupClaim: string;
+  nameClaim: string;
+  jwksUri?: string;
+  clockSkewMs: number;
+  scope: string;
+}
+
+export interface OidcIdentity {
+  iss: string;
+  sub: string;
+  name: string;
+  email?: string;
+  groups: string[];
+}
+
+/** OIDC is the master opt-in. Gates locked() in index.ts so the backend never falls to dev-open. */
+export function oidcEnabled(): boolean {
+  return !!process.env.ADA_OIDC_ISSUER;
+}
+
+function list(v: string | undefined): string[] {
+  return (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function stripSlash(u: string): string {
+  return u.replace(/\/+$/, "");
+}
+
+/** Parse + VALIDATE the OIDC config from env. Throws (fail-closed) on any unsafe/incomplete config;
+ *  call assertOidcConfig() once at startup so misconfiguration aborts the process instead of
+ *  surfacing per-request. */
+export function oidcConfig(): OidcConfig {
+  const issuer = process.env.ADA_OIDC_ISSUER;
+  if (!issuer) throw new Error("oidcConfig() called without ADA_OIDC_ISSUER");
+  if (!/^https:\/\//i.test(issuer)) throw new Error("ADA_OIDC_ISSUER must be an https URL");
+  // Multi-tenant issuers make `sub`/`iss` non-unique across tenants → reject (single-tenant only).
+  if (/login\.microsoftonline\.com\/(common|organizations)(\/|$)/i.test(issuer) || /\{tenant\}|\{tenantid\}/i.test(issuer)) {
+    throw new Error("multi-tenant OIDC issuer rejected — configure a concrete single-tenant issuer URL");
+  }
+  const clientId = process.env.ADA_OIDC_CLIENT_ID;
+  if (!clientId) throw new Error("ADA_OIDC_CLIENT_ID is required when ADA_OIDC_ISSUER is set");
+  const allowedGroups = list(process.env.ADA_OIDC_ALLOWED_GROUPS);
+  const allowedDomains = list(process.env.ADA_OIDC_ALLOWED_DOMAINS).map((d) => d.toLowerCase());
+  // Positive allow-surface is mandatory: without it JIT would provision a seat for every identity
+  // the IdP will sign a token for (esp. a public issuer). Refuse to start.
+  if (!allowedGroups.length && !allowedDomains.length) {
+    throw new Error("set ADA_OIDC_ALLOWED_GROUPS or ADA_OIDC_ALLOWED_DOMAINS — refusing to provision every IdP user (fail-closed)");
+  }
+  const jwksUri = process.env.ADA_OIDC_JWKS_URI;
+  if (jwksUri) assertSafeJwksUri(jwksUri);
+  return {
+    issuer: stripSlash(issuer),
+    clientId,
+    audience: process.env.ADA_OIDC_AUDIENCE ?? clientId,
+    allowedGroups,
+    allowedDomains,
+    adminGroup: process.env.ADA_OIDC_ADMIN_GROUP || undefined,
+    groupClaim: process.env.ADA_OIDC_GROUP_CLAIM ?? "groups",
+    nameClaim: process.env.ADA_OIDC_NAME_CLAIM ?? "",
+    jwksUri,
+    clockSkewMs: Number(process.env.ADA_OIDC_CLOCK_SKEW_MS) || 120_000,
+    scope: process.env.ADA_OIDC_SCOPE ?? "openid profile email",
+  };
+}
+
+/** Abort startup on bad OIDC config (called from index.ts). Returns true if OIDC is on and valid. */
+export function assertOidcConfig(): boolean {
+  if (!oidcEnabled()) return false;
+  oidcConfig(); // throws on any problem
+  return true;
+}
+
+function isPrivateV4(host: string): boolean {
+  const p = host.split(".").map(Number);
+  if (p.length !== 4 || p.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true; // malformed → refuse
+  const [a, b] = p as [number, number, number, number];
+  return a === 0 || a === 127 || a === 10 || (a === 192 && b === 168) || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31);
+}
+
+function isPrivateV6(host: string): boolean {
+  const h = host.toLowerCase();
+  if (h === "::1" || h === "::") return true; // loopback / unspecified
+  const mapped = /((?:\d{1,3}\.){3}\d{1,3})$/.exec(h);
+  if (h.startsWith("::") && mapped) return isPrivateV4(mapped[1]!); // IPv4-mapped/compat → classify embedded v4
+  const g = h.split(":")[0];
+  if (!g) return true; // other ::-prefixed low addresses — refuse conservatively
+  return /^fe[89ab]/.test(g) || /^f[cd]/.test(g); // fe80::/10 link-local, fc00::/7 ULA
+}
+
+// A jwks_uri must be https and must not point at loopback/link-local/private hosts — a lightweight
+// SSRF guard for a typo'd/compromised issuer. Classification is against a PARSED IP (net.isIP),
+// never a string prefix: WHATWG URL keeps IPv6 in brackets, and prefix tests both miss `[::1]` and
+// falsely reject DNS names like `fcm.googleapis.com`. (We deliberately do NOT pin origin to the
+// issuer: Google Workspace serves its JWKS from googleapis.com, a different origin than the issuer.)
+export function assertSafeJwksUri(uri: string): void {
+  let u: URL;
+  try {
+    u = new URL(uri);
+  } catch {
+    throw new Error(`invalid jwks_uri: ${uri}`);
+  }
+  if (u.protocol !== "https:") throw new Error(`jwks_uri must be https: ${uri}`);
+  let host = u.hostname.toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1); // unwrap IPv6 literal
+  const fam = isIP(host); // 4, 6, or 0 (DNS name)
+  if (fam === 0) {
+    if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal")) {
+      throw new Error(`jwks_uri host not allowed (loopback/internal): ${host}`);
+    }
+    return; // ordinary DNS name — resolves at fetch; the issuer is deployer-controlled
+  }
+  if (fam === 4 ? isPrivateV4(host) : isPrivateV6(host)) throw new Error(`jwks_uri host not allowed (private/loopback IP): ${host}`);
+}
+
+// ---- OIDC discovery (device/token/jwks endpoints), cached for the process ----
+interface Discovery {
+  device_authorization_endpoint?: string;
+  token_endpoint?: string;
+  jwks_uri?: string;
+}
+let discoveryCache: { at: number; doc: Discovery } | null = null;
+let discoveryInflight: Promise<Discovery> | null = null;
+let discoveryFailUntil = 0;
+const DISCOVERY_TTL = 3_600_000; // endpoints are stable; refresh hourly
+
+/** Cached OIDC discovery. Reached from the UNAUTHENTICATED /v1/auth/methods, so concurrent callers
+ *  share one in-flight fetch and a failure is negative-cached briefly — a cold cache during an IdP
+ *  outage can't fan out to one outbound request per anonymous caller. */
+export async function discover(): Promise<Discovery> {
+  if (discoveryCache && Date.now() - discoveryCache.at < DISCOVERY_TTL) return discoveryCache.doc;
+  if (Date.now() < discoveryFailUntil) throw new Error("OIDC discovery temporarily unavailable (cached failure)");
+  if (discoveryInflight) return discoveryInflight;
+  discoveryInflight = (async () => {
+    try {
+      const { issuer } = oidcConfig();
+      const r = await fetch(`${issuer}/.well-known/openid-configuration`, { signal: AbortSignal.timeout(8000) });
+      if (!r.ok) throw new Error(`OIDC discovery failed: HTTP ${r.status} at ${issuer}/.well-known/openid-configuration`);
+      const doc = (await r.json()) as Discovery;
+      if (doc.jwks_uri) assertSafeJwksUri(doc.jwks_uri);
+      discoveryCache = { at: Date.now(), doc };
+      return doc;
+    } catch (e) {
+      discoveryFailUntil = Date.now() + 10_000; // negative-cache 10s to stop pre-auth fan-out
+      throw e;
+    } finally {
+      discoveryInflight = null;
+    }
+  })();
+  return discoveryInflight;
+}
+
+// ---- JWKS cache with a fetch rate-cap (an attacker-chosen `kid` can't force unbounded refetches) ----
+type Jwk = Record<string, unknown> & { kid?: string; kty?: string; use?: string; alg?: string };
+const jwksCache = new Map<string, Jwk>();
+let lastJwksFetch = 0;
+const JWKS_MIN_REFETCH_MS = 60_000;
+
+async function refreshJwks(): Promise<void> {
+  lastJwksFetch = Date.now();
+  const uri = oidcConfig().jwksUri ?? (await discover()).jwks_uri;
+  if (!uri) throw new Error("no jwks_uri (set ADA_OIDC_JWKS_URI or fix discovery)");
+  assertSafeJwksUri(uri);
+  const r = await fetch(uri, { signal: AbortSignal.timeout(8000) });
+  if (!r.ok) throw new Error(`JWKS fetch failed: HTTP ${r.status}`);
+  const { keys } = (await r.json()) as { keys?: Jwk[] };
+  for (const k of keys ?? []) {
+    if (k.kty === "RSA" && k.use !== "enc" && k.kid) jwksCache.set(k.kid, k);
+  }
+}
+
+async function defaultGetKey(kid: string): Promise<Jwk | null> {
+  const hit = jwksCache.get(kid);
+  if (hit) return hit;
+  if (Date.now() - lastJwksFetch > JWKS_MIN_REFETCH_MS) {
+    await refreshJwks();
+    return jwksCache.get(kid) ?? null;
+  }
+  return null; // rate-capped: unknown kid, refetched too recently
+}
+
+function b64urlJson(part: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(Buffer.from(part, "base64url").toString("utf8")) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/** Verify an OIDC ID token → identity, or null on ANY failure (bad alg/sig/claims). `opts.getKey`
+ *  and `opts.now` are injectable for hermetic tests; production uses the JWKS cache + wall clock. */
+export async function verifyOidcToken(
+  idToken: string,
+  opts: { getKey?: (kid: string) => Promise<Jwk | null> | Jwk | null; now?: number } = {},
+): Promise<OidcIdentity | null> {
+  const cfg = oidcConfig();
+  const now = opts.now ?? Date.now();
+  const getKey = opts.getKey ?? defaultGetKey;
+
+  const parts = idToken.split(".");
+  if (parts.length !== 3) return null;
+  const [h, p, s] = parts as [string, string, string];
+  const header = b64urlJson(h);
+  const payload = b64urlJson(p);
+  if (!header || !payload) return null;
+  if (header.alg !== "RS256") return null; // allowlist RS256 only — reject "none" and HS* (key confusion)
+
+  const kid = typeof header.kid === "string" ? header.kid : "";
+  if (!kid) return null;
+  let jwk: Jwk | null;
+  try {
+    jwk = await getKey(kid);
+  } catch {
+    return null; // JWKS/network error ⇒ deny
+  }
+  if (!jwk) return null;
+
+  // Verify the RS256 signature over `header.payload`.
+  let ok = false;
+  try {
+    const pub = createPublicKey({ key: jwk, format: "jwk" } as unknown as import("node:crypto").JsonWebKeyInput);
+    ok = cryptoVerify("RSA-SHA256", Buffer.from(`${h}.${p}`), pub, Buffer.from(s, "base64url"));
+  } catch {
+    return null;
+  }
+  if (!ok) return null;
+
+  // Claims.
+  const skew = cfg.clockSkewMs;
+  if (payload.iss !== cfg.issuer) return null;
+  const aud = payload.aud;
+  const audArr = Array.isArray(aud) ? aud.map(String) : typeof aud === "string" ? [aud] : [];
+  if (!audArr.includes(cfg.audience)) return null;
+  // If aud carries extra resource ids we don't own AND azp is absent, reject (token minted for a
+  // different client). When azp is present it must be our client id.
+  if (typeof payload.azp === "string") {
+    if (payload.azp !== cfg.clientId) return null;
+  } else if (audArr.length > 1) {
+    return null;
+  }
+  if (typeof payload.exp !== "number" || payload.exp * 1000 <= now - skew) return null;
+  if (typeof payload.nbf === "number" && payload.nbf * 1000 > now + skew) return null;
+  if (typeof payload.iat === "number" && payload.iat * 1000 > now + skew) return null;
+  if (typeof payload.sub !== "string" || !payload.sub) return null;
+
+  const groupsRaw = payload[cfg.groupClaim];
+  const groups = Array.isArray(groupsRaw) ? groupsRaw.map(String) : typeof groupsRaw === "string" ? [groupsRaw] : [];
+  // Only trust `email` when the IdP marks it verified — domain-based provisioning (isProvisionAllowed)
+  // matches on the email domain, and a self-service IdP will happily sign a token for an unverified
+  // attacker@corp.com. IdPs that omit email_verified simply can't use the domain allowlist (use groups).
+  const email = payload.email_verified === true && typeof payload.email === "string" ? payload.email : undefined;
+  const name =
+    (cfg.nameClaim && typeof payload[cfg.nameClaim] === "string" && (payload[cfg.nameClaim] as string)) ||
+    email ||
+    (typeof payload.preferred_username === "string" ? payload.preferred_username : undefined) ||
+    (payload.sub as string);
+
+  return { iss: cfg.issuer, sub: payload.sub, name, email, groups };
+}
+
+/** Positive, fail-closed membership: true iff the identity is in an allowed group OR email domain.
+ *  oidcConfig() already refuses to start with an empty allow-surface, so this is never vacuously true. */
+export function isProvisionAllowed(id: OidcIdentity): boolean {
+  const cfg = oidcConfig();
+  if (cfg.allowedGroups.length && id.groups.some((g) => cfg.allowedGroups.includes(g))) return true;
+  if (cfg.allowedDomains.length && id.email) {
+    const domain = id.email.split("@")[1]?.toLowerCase();
+    if (domain && cfg.allowedDomains.includes(domain)) return true;
+  }
+  return false;
+}
+
+/** Map a verified identity to seat fields. externalId is issuer-scoped (`iss#sub`); admin role only
+ *  when the configured admin group is present in the token. */
+export function mapIdentityToSeatFields(id: OidcIdentity): { externalId: string; iss: string; name: string; role: "admin" | "dev" } {
+  const cfg = oidcConfig();
+  const role: "admin" | "dev" = cfg.adminGroup && id.groups.includes(cfg.adminGroup) ? "admin" : "dev";
+  return { externalId: `${id.iss}#${id.sub}`, iss: id.iss, name: id.name, role };
+}