@botbuddy/cli 1.64.33 → 1.65.0

package/src/staging-pool/help.mjs

@@ -10,7 +10,7 @@ export const BINDING_KEYS_HELP = `  Registered per tenant in the BotBuddy contro
     pool_id, environment "staging", app_slug, adapter "supabase-gotrue-totp",
     app_origin, supabase_url, publishable_key (public), storage_key,
     production_origins, password_env_file, launchd_label, docs,
-    personas { <alias>: { email, password_env, default_count 0-4 } }.
+    personas { <alias>: { email, password_env, default_count 0-4, sign_in? } }.
   No secret is registered: each persona's password stays in password_env_file
   (0600) on this Mac. Install refuses a production, http or loopback origin
   whatever is registered. No repository checkout is read.`;
@@ -69,7 +69,7 @@ IF IT REFUSES
 export const STAGING_POOL_HELP = `bb staging-pool — the human-installed job that keeps signed-in staging sessions ready for agents.
 
 A launchd job on this Mac signs each allowlisted seeded persona in to the
-tenant's staging app (password + TOTP via BotBuddy get_totp_code) every
+tenant's staging app (password + TOTP, or Okta SSO via sign_in) every
 5 minutes and keeps a few single-use sessions ready. Agents never sign in: they
 take a session with bb pw --environment staging <lane> auth --persona <alias>
 (bb pw auth --help).
@@ -110,8 +110,8 @@ HUMAN ONLY (Jono, from Terminal.app or iTerm) — refused inside a Claude or Cod
   tick [--pool <pool_id>] [--home <pool home>]
       One refresh and refill pass now (what the job runs).
       e.g. bb staging-pool tick
-  mint-one --persona <alias>
-      One real sign-in into the pool, to prove a repair worked.
+  mint-one --persona <alias> [--retry-held]
+      One real sign-in, to prove a repair worked.
       e.g. bb staging-pool mint-one --persona staging-admin
   uninstall [--keep-sessions]
       Stops the job and deletes its sessions (keeps them with --keep-sessions).

package/src/staging-pool/okta-steps.mjs

@@ -0,0 +1,120 @@
+// BOT-3145 (ported from supplyspark-ent PR #3534, ENT-5553): the real Okta Identity Engine
+// sign-in steps the staging session pool drives for an `okta-saml` persona
+// (signin-okta-saml.mjs). Node-stdlib-only and self-contained: `page` is any Playwright Page
+// (duck-typed: locator().first(), url()).
+//
+// Markup: Okta Sign-In Widget 7.50.0 on integrator-4707698.okta.com (IDX pipeline),
+// captured read-only on 2026-10-14 (fixtures/2026-10-14-okta-sso-signin.json). The same
+// selectors drive Supply Guard's daily real-Okta CI lane (e2e/sso/okta-login-driver.ts,
+// green every day through 2026-11-10). Recapture the fixture when the widget version changes.
+
+export const OKTA_SELECTORS = Object.freeze({
+  identifier: 'input[name="identifier"], input[name="username"], input#okta-signin-username',
+  password: 'input[type="password"], input[name="credentials.passcode"]',
+  submit: 'input[type="submit"], button[type="submit"]',
+  // The widget's form-level error callout (e.g. a rejected password).
+  formError: '[data-se="o-form-error-container"] .o-form-error-container, [data-se="o-form-error-container"], .okta-form-infobox-error',
+  heading: '[data-se="o-form-head"]',
+  // A challenge or enrolment for a factor other than the password (Okta Verify, email, phone,
+  // a TOTP code): the app's Okta policy is password-only 1FA, so any of these is a misconfig.
+  authenticatorList: '[data-se="authenticator-verify-list"], [data-se="authenticator-enroll-list"], .authenticator-verify-list, .authenticator-enroll-list',
+});
+
+/** Best-effort resilient driver for the real Okta Identity Engine sign-in form.
+ * Handles both the single-page and the two-step (identifier → password) layouts.
+ * Deliberately tolerant: a real external IdP's markup is outside our control, so
+ * the assertion that the login actually worked is the minted staging session. */
+export async function loginToOkta(page, username, password, expectedHost, { onPasswordSubmit, beforePasswordFill } = {}) {
+  // Fail closed before ever entering the credential: only ever type it on the EXACT
+  // registered Okta tenant host, so a misconfigured/compromised provider that 302s to a
+  // look-alike (e.g. okta.com.attacker.example) cannot harvest it.
+  const assertOnOktaHost = (stage) => {
+    let host = "";
+    try {
+      const url = new URL(page.url());
+      // BOT-3145: https only, so the password never goes into a plaintext page on the right host.
+      host = url.protocol === "https:" ? url.hostname : `${url.protocol}//${url.hostname}`;
+    } catch {
+      /* handled below */
+    }
+    if (host !== expectedHost) {
+      throw new Error(
+        `refusing to enter Okta credentials at ${stage}: page host ${host || "(unparseable)"} is not the registered Okta host ${expectedHost}.`,
+      );
+    }
+  };
+
+  const identifier = page.locator(OKTA_SELECTORS.identifier).first();
+  await identifier.waitFor({ state: "visible", timeout: 45_000 });
+  assertOnOktaHost("identifier");
+  await identifier.fill(username);
+
+  const passwordField = page.locator(OKTA_SELECTORS.password).first();
+  if (!(await passwordField.isVisible().catch(() => false))) {
+    // Two-step layout: advance past the identifier page.
+    await page.locator(OKTA_SELECTORS.submit).first().click();
+    await passwordField.waitFor({ state: "visible", timeout: 45_000 });
+  }
+  assertOnOktaHost("password");
+  // BOT-3145: the caller persists a pending credential hold here, BEFORE the password is typed, so a
+  // crash after the submit can never lose it; a failure to persist aborts with nothing typed.
+  if (beforePasswordFill) {
+    await beforePasswordFill();
+    assertOnOktaHost("password");
+  }
+  await passwordField.fill(password);
+  // From here the password counts as submitted, even if the click itself throws: the pool
+  // never re-submits it within a mint (ENT-5553 HF-01).
+  onPasswordSubmit?.();
+  await page.locator(OKTA_SELECTORS.submit).first().click();
+}
+
+async function visibleText(page, selector) {
+  const locator = page.locator(selector).first();
+  if (!(await locator.isVisible().catch(() => false))) return null;
+  const text = await locator.innerText().catch(() => "");
+  return String(text ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
+}
+
+/** A read-only, value-free snapshot of what the browser shows after the password submit.
+ * Never reads input values; text is the widget's own heading / error copy. */
+export async function readOktaPageState(page) {
+  let host = "";
+  let path = "";
+  let protocol = "";
+  try {
+    const url = new URL(page.url());
+    host = url.hostname;
+    path = url.pathname;
+    protocol = url.protocol;
+  } catch {
+    /* unparseable: classified as unknown */
+  }
+  const [passwordVisible, identifierVisible, authenticatorListVisible, errorText, headingText] = await Promise.all([
+    page.locator(OKTA_SELECTORS.password).first().isVisible().catch(() => false),
+    page.locator(OKTA_SELECTORS.identifier).first().isVisible().catch(() => false),
+    page.locator(OKTA_SELECTORS.authenticatorList).first().isVisible().catch(() => false),
+    visibleText(page, OKTA_SELECTORS.formError),
+    visibleText(page, OKTA_SELECTORS.heading),
+  ]);
+  return { host, path, protocol, passwordVisible, identifierVisible, authenticatorListVisible, errorText, headingText };
+}
+
+const LOCKED_OUT = /locked|suspended|deactivated/i;
+const MFA_HEADING = /security method|okta verify|verify with (?!your password)|enter (a|the|your) code|set up|enroll|authenticator|push notification|phone|email/i;
+
+/** Pure classification of a page state on the Okta host after the password submit.
+ * Returns one of: "pending" (still working — keep waiting), "password_rejected",
+ * "account_locked", "mfa_prompt", "off_okta" (not on the Okta host). */
+export function classifyOktaPageState(state, { expectedHost }) {
+  if (!state || state.host !== expectedHost) return "off_okta";
+  if (state.errorText && LOCKED_OUT.test(state.errorText)) return "account_locked";
+  // A factor challenge reuses the passcode input name, so the heading decides first: the
+  // password step's own heading ("Verify with your password") never matches.
+  if (state.authenticatorListVisible) return "mfa_prompt";
+  if (state.headingText && MFA_HEADING.test(state.headingText)) return "mfa_prompt";
+  // Any form-level error while the password step is still on screen is a rejected
+  // credential (the widget words it "Password is incorrect" / "Unable to sign in").
+  if (state.errorText && (state.passwordVisible || state.identifierVisible)) return "password_rejected";
+  return "pending";
+}

package/src/staging-pool/policy.mjs

@@ -10,6 +10,8 @@
 
 import { execFileSync } from "node:child_process";
 
+import { TOTP_SIGN_IN } from "./sign-in-kinds.mjs";
+
 export class MintRefusedError extends Error {
   constructor(code, message) {
     super(message);
@@ -75,6 +77,8 @@ export function stagingTargetFromBinding(binding) {
     appSlug: binding.appSlug,
     tenant: binding.tenant,
     personaEmails: Object.freeze(Object.values(binding.personas).map((persona) => persona.email)),
+    // BOT-3145: each persona's sign-in kind, from the binding only (state-file claim checks).
+    personaSignIns: Object.freeze(Object.fromEntries(Object.values(binding.personas).map((persona) => [persona.email, persona.signIn ?? TOTP_SIGN_IN]))),
     loopback: false,
   });
 }

package/src/staging-pool/pool.mjs

@@ -88,12 +88,98 @@ export function createSessionPool({
   const lastTickPath = join(poolDir, "last-tick.json");
   const healthPath = join(poolDir, "health.json");
 
-  async function readHealth() {
+  // strict (tick, mint-one): only a missing file reads as empty. Anything else would silently drop a
+  // credential hold (BOT-3145), so it fails closed with health_unreadable. status stays lenient.
+  // Strict only for a pool that serves an okta-saml persona (review round 2, P3-2): a TOTP-only
+  // pool keeps its old self-healing rewrite. status marks an unreadable file so --check names it.
+  const holdsCredentials = Object.values(target.personaSignIns ?? {}).some((spec) => spec?.kind === "okta-saml");
+  async function readHealth({ strict = false } = {}) {
     try {
       const health = await readJson(healthPath);
       return { lastSuccessfulTickAt: health.lastSuccessfulTickAt ?? null, personas: health.personas ?? {} };
+    } catch (error) {
+      if (error?.code === "ENOENT") return { lastSuccessfulTickAt: null, personas: {} };
+      if (strict && holdsCredentials) {
+        throw Object.assign(new Error(`${healthPath} is unreadable (${error?.code ?? error?.name ?? "error"}); a credential hold may be in it.`), { code: "health_unreadable" });
+      }
+      return { lastSuccessfulTickAt: null, personas: {}, ...(holdsCredentials ? { unreadable: true } : {}) };
+    }
+  }
+
+  async function writeHealth(health) {
+    await replaceFile(healthPath, `${JSON.stringify(health, null, 2)}\n`);
+  }
+
+  // Review round 2, P2-1: the pending hold is on disk BEFORE the password is typed, so a crash,
+  // reboot or uninstall mid-sign-in can never lose it. Cleared below when the outcome proves the
+  // password was accepted or never submitted.
+  function holdPersister(health, entry) {
+    return async (holdKey) => {
+      entry.credentialHold = holdKey;
+      entry.credentialHoldPending = true;
+      await writeHealth(health);
+    };
+  }
+
+  // A pending hold is released only when the adapter vouched the outcome is not a refusal
+  // (credentialChecked). Anything else — a crash, an unclassified error — keeps it (fail closed).
+  function recordMintFailureHold(entry, error) {
+    if (typeof error?.holdKey === "string" && error.holdKey) entry.credentialHold = error.holdKey;
+    else if (entry.credentialHoldPending && error?.credentialChecked === true) entry.credentialHold = null;
+    delete entry.credentialHoldPending;
+  }
+
+  function healthEntry(health, persona) {
+    const entry = (health.personas[persona] ??= {});
+    entry.belowTargetTicks ??= 0;
+    entry.consecutiveMintFailures ??= 0;
+    entry.backoffMintFailures ??= 0;
+    entry.nextMintAttemptAt ??= null;
+    entry.lastMintError ??= null;
+    return entry;
+  }
+
+  // BOT-3145: true while the persona's held credential is still the one it would sign in with (or
+  // that cannot be told); a changed credential clears the hold.
+  async function credentialStillHeld(entry, persona) {
+    if (!entry.credentialHold) return false;
+    const holdKey = await currentHoldKey(persona);
+    // "<key id>:<fingerprint>": a replaced hold key (another key id) keeps the hold (round 2, P3-3).
+    const keyId = (value) => String(value).split(":")[0];
+    if (holdKey !== null && keyId(holdKey) === keyId(entry.credentialHold) && holdKey !== entry.credentialHold) {
+      entry.credentialHold = null;
+      logger({ event: "credential_hold_cleared", persona });
+      return false;
+    }
+    return true;
+  }
+
+  function recordMintSuccess(entry) {
+    entry.consecutiveMintFailures = 0;
+    entry.backoffMintFailures = 0;
+    entry.nextMintAttemptAt = null;
+    entry.lastMintError = null;
+    entry.credentialHold = null;
+    delete entry.credentialHoldPending;
+  }
+
+  // BOT-3145: status shows only that a persona's credential is held, never its fingerprint.
+  function publicHealth(health) {
+    const personas = {};
+    for (const [persona, entry] of Object.entries(health.personas)) {
+      const { credentialHold, credentialHoldPending: _pending, ...rest } = entry ?? {};
+      personas[persona] = credentialHold ? { ...rest, credentialHeld: true } : rest;
+    }
+    return { ...health, personas };
+  }
+
+  // BOT-3145: the fingerprint of the credential this persona would sign in with now, or null.
+  async function currentHoldKey(persona) {
+    if (typeof signIn.credentialHoldKey !== "function") return null;
+    try {
+      return (await signIn.credentialHoldKey(persona)) ?? null;
     } catch {
-      return { lastSuccessfulTickAt: null, personas: {} };
+      return null;
     }
   }
 
@@ -315,11 +401,11 @@ export function createSessionPool({
   }
 
   // Caller holds the tick lock.
-  async function mintIntoReady(persona) {
+  async function mintIntoReady(persona, { persistHold } = {}) {
     const mintedAt = new Date(now()).toISOString();
     const slotId = `${personaKey(persona)}~${now()}~${randomId()}`;
     const workDir = join(dirs.work, slotId);
-    const storedSession = await signIn.mint({ target, persona });
+    const storedSession = await signIn.mint({ target, persona, ...(persistHold ? { persistHold } : {}) });
     await ensureDir(workDir);
     try {
       const meta = buildMeta({ persona, slotId, storedSession, mintedAt, refreshCount: 0 });
@@ -477,20 +563,22 @@ export function createSessionPool({
       }
 
       const counts = await countReady(plan.map(([persona]) => persona));
-      const health = await readHealth();
+      const health = await readHealth({ strict: true });
       summary.backoffSkips = 0;
+      summary.heldSkips = 0;
       for (const [persona, want] of plan) {
-        const entry = (health.personas[persona] ??= {
-          belowTargetTicks: 0,
-          consecutiveMintFailures: 0,
-          backoffMintFailures: 0,
-          nextMintAttemptAt: null,
-          lastMintError: null,
-        });
+        const entry = healthEntry(health, persona);
         // Every refill sign-in's MFA verify deletes the persona's AAL1 sessions on
         // staging (ENT-4994), so repeated failures back off instead of retrying
         // every tick.
-        if (counts[persona] < want && entry.nextMintAttemptAt && Date.parse(entry.nextMintAttemptAt) > now()) {
+        // BOT-3145: a persona whose last mint refused (or could not confirm) its IdP password is
+        // held until that password changes: no sign-in may submit it again (Okta lockout).
+        // Re-checked every tick, full or not, so a fixed password clears a stale hold (P2-c).
+        const held = await credentialStillHeld(entry, persona);
+        if (held && counts[persona] < want) {
+          summary.heldSkips += 1;
+          logger({ event: "mint_held_skip", persona, lastMintError: entry.lastMintError });
+        } else if (counts[persona] < want && entry.nextMintAttemptAt && Date.parse(entry.nextMintAttemptAt) > now()) {
           summary.backoffSkips += 1;
           logger({
             event: "mint_backoff_skip",
@@ -503,16 +591,14 @@ export function createSessionPool({
           while (counts[persona] < want) {
             summary.signIns += 1;
             try {
-              await mintIntoReady(persona);
+              await mintIntoReady(persona, { persistHold: holdPersister(health, entry) });
               counts[persona] += 1;
-              entry.consecutiveMintFailures = 0;
-              entry.backoffMintFailures = 0;
-              entry.nextMintAttemptAt = null;
-              entry.lastMintError = null;
+              recordMintSuccess(entry);
             } catch (error) {
               summary.mintFailures += 1;
               entry.consecutiveMintFailures += 1;
               entry.lastMintError = error?.code ?? "error";
+              recordMintFailureHold(entry, error);
               // BOT-2952: an outage that never got a password grant created no AAL1 session and
               // ran no MFA verify, so it retries on the next tick and does not lengthen a later
               // backoff. A 429 is Auth asking us to slow down, so it backs off like any other
@@ -544,10 +630,15 @@ export function createSessionPool({
       }
       // A persona the config no longer serves (removed or 0) drops its backoff and streaks, so
       // re-enabling it after a repair mints on the next tick (Codex R13).
+      // BOT-3145: a credential hold outlives the persona being switched off, so re-enabling it never
+      // re-submits a refused password.
       for (const persona of Object.keys(health.personas)) {
-        if (!(wanted.get(persona) > 0)) delete health.personas[persona];
+        if (wanted.get(persona) > 0) continue;
+        const hold = health.personas[persona]?.credentialHold;
+        if (hold) health.personas[persona] = { credentialHold: hold };
+        else delete health.personas[persona];
       }
-      if (summary.mintFailures === 0 && summary.backoffSkips === 0) health.lastSuccessfulTickAt = summary.at;
+      if (summary.mintFailures === 0 && summary.backoffSkips === 0 && summary.heldSkips === 0) health.lastSuccessfulTickAt = summary.at;
       await replaceFile(healthPath, `${JSON.stringify(health, null, 2)}\n`);
       summary.ready = counts;
       logger({ event: "tick", ...summary });
@@ -556,10 +647,29 @@ export function createSessionPool({
     });
   }
 
-  async function mintOne({ persona }) {
+  // BOT-3145: mint-one honours and records credential holds like a tick. retryHeld is the human's
+  // deliberate single re-submission of a held credential (after unlocking or checking the IdP user).
+  async function mintOne({ persona, retryHeld = false }) {
     assertPersonaAllowed(target, persona);
     const result = await withTickLock(async () => {
-      const minted = await mintIntoReady(persona);
+      const health = await readHealth({ strict: true });
+      const entry = healthEntry(health, persona);
+      if (!retryHeld && (await credentialStillHeld(entry, persona))) {
+        await writeHealth(health);
+        throw Object.assign(new Error(`${persona} is held: its IdP refused, or never confirmed, the configured password.`), { code: "credential_held" });
+      }
+      let minted;
+      try {
+        minted = await mintIntoReady(persona, { persistHold: holdPersister(health, entry) });
+      } catch (error) {
+        entry.consecutiveMintFailures += 1;
+        entry.lastMintError = error?.code ?? "error";
+        recordMintFailureHold(entry, error);
+        await writeHealth(health);
+        throw error;
+      }
+      recordMintSuccess(entry);
+      await writeHealth(health);
       logger({ event: "mint_one", persona, slotId: minted.slotId, signIns: 1 });
       return minted;
     });
@@ -650,6 +760,8 @@ export function createSessionPool({
         slotId,
         persona: meta.persona,
         aal: meta.aal,
+        // BOT-3145: the auth methods (e.g. totp, sso/saml) — metadata, never session material.
+        amr: Array.isArray(meta.amr) ? meta.amr : [],
         sessionRef: meta.sessionRef,
         ageSeconds: Math.round((now() - Date.parse(meta.mintedAt)) / 1000),
         verifiedAgeSeconds: Math.round((now() - Date.parse(meta.verifiedAt)) / 1000),
@@ -676,7 +788,7 @@ export function createSessionPool({
     return {
       poolDir,
       target: target.name,
-      health: await readHealth(),
+      health: publicHealth(await readHealth()),
       ready: await collect(dirs.ready),
       taken: (await list(dirs.taken)).length,
       work: (await list(dirs.work)).length,

package/src/staging-pool/sign-in-kinds.mjs

@@ -0,0 +1,87 @@
+// BOT-3145: how a pool persona signs in, and which session claims prove it.
+//
+// A persona with no `sign_in` block signs in with password + TOTP (BOT-2084) and must
+// hold an aal2 session. A persona with `sign_in: { kind: "okta-saml", ... }` signs in
+// through its tenant's Okta IdP over SAML (signin-okta-saml.mjs) and must hold a
+// session whose amr carries `sso/saml` (GoTrue issues it at aal1: the IdP owns the
+// second factor). The kind comes only from the tenant's authenticated binding, so
+// nothing an agent passes can turn a TOTP persona into an SSO one.
+//
+// Node-stdlib-only and self-contained (the installed job copies this directory).
+
+export const SIGN_IN_KINDS = Object.freeze({ TOTP: "gotrue-totp", OKTA_SAML: "okta-saml" });
+
+const SIGN_IN_KEYS = new Set(["kind", "sso_domain", "idp_host", "admission_function", "admission_route"]);
+// A bare DNS hostname: labels of [a-z0-9-], at least one dot, no port, path or scheme.
+const HOSTNAME_RE = /^(?=.{4,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+// An Edge Function slug on the binding's own supabase_url, never a URL.
+const FUNCTION_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+// The app path the admission function must answer with for an admitted member (e.g. "/dashboard").
+const ROUTE_RE = /^\/[A-Za-z0-9/_-]{0,100}$/;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+export const TOTP_SIGN_IN = Object.freeze({ kind: SIGN_IN_KINDS.TOTP });
+
+// raw: a persona's `sign_in` value from the binding (undefined → TOTP). Returns the
+// frozen camelCase spec, or a { field, message } problem. Shared by the CLI's binding
+// parser; the control-plane registry (stagingSessionPoolRegistry.ts) mirrors these rules, and
+// both test suites carry the same refusal cases.
+export function parseSignIn(raw) {
+  if (raw === undefined) return { ok: true, signIn: TOTP_SIGN_IN };
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return problem("sign_in", "sign_in must be an object");
+  for (const key of Object.keys(raw)) {
+    if (!SIGN_IN_KEYS.has(key)) return problem("sign_in", `unknown sign_in key ${JSON.stringify(key.slice(0, 40))}`);
+  }
+  if (raw.kind !== SIGN_IN_KINDS.OKTA_SAML) return problem("sign_in.kind", `sign_in.kind must be "${SIGN_IN_KINDS.OKTA_SAML}" (omit sign_in for password + TOTP)`);
+  if (!isHostname(raw.sso_domain)) return problem("sign_in.sso_domain", "sign_in.sso_domain must be the SSO provider's email domain");
+  if (!isHostname(raw.idp_host) || LOOPBACK_HOSTS.has(String(raw.idp_host).toLowerCase())) {
+    return problem("sign_in.idp_host", "sign_in.idp_host must be the IdP's bare public hostname (credentials are typed only there)");
+  }
+  if (raw.admission_function !== undefined && (typeof raw.admission_function !== "string" || !FUNCTION_SLUG_RE.test(raw.admission_function))) {
+    return problem("sign_in.admission_function", "sign_in.admission_function must be an Edge Function slug");
+  }
+  if (raw.admission_route !== undefined && (raw.admission_function === undefined || typeof raw.admission_route !== "string" || !ROUTE_RE.test(raw.admission_route))) {
+    return problem("sign_in.admission_route", "sign_in.admission_route must be an app path, and needs admission_function");
+  }
+  return {
+    ok: true,
+    signIn: Object.freeze({
+      kind: SIGN_IN_KINDS.OKTA_SAML,
+      ssoDomain: raw.sso_domain.toLowerCase(),
+      idpHost: raw.idp_host.toLowerCase(),
+      admissionFunction: raw.admission_function ?? null,
+      admissionRoute: raw.admission_route ?? null,
+    }),
+  };
+}
+
+function isHostname(value) {
+  return typeof value === "string" && HOSTNAME_RE.test(value);
+}
+
+function problem(field, message) {
+  return { ok: false, field, message };
+}
+
+export function amrMethods(claims) {
+  return Array.isArray(claims?.amr) ? claims.amr.map((entry) => entry?.method ?? String(entry)) : [];
+}
+
+// Why a session's claims are wrong for a persona of this sign-in kind, or null.
+// TOTP: aal2. okta-saml: amr carries sso/saml at aal1 or aal2. Email always matches.
+export function sessionClaimsProblem(claims, { email, signIn = TOTP_SIGN_IN } = {}) {
+  if (String(claims?.email ?? "").toLowerCase() !== String(email ?? "").toLowerCase()) return "persona_mismatch";
+  if (signIn.kind === SIGN_IN_KINDS.OKTA_SAML) {
+    if (!amrMethods(claims).includes("sso/saml")) return "not_sso_session";
+    if (claims.aal !== "aal1" && claims.aal !== "aal2") return "aal_unknown";
+    return null;
+  }
+  if (claims?.aal !== "aal2") return "aal_downgraded";
+  return null;
+}
+
+// The take side's requirement for a persona, in a form the lane daemon can check
+// without importing this module (pw/staging-auth.mjs installCode).
+export function requiredAuthFor(signIn = TOTP_SIGN_IN) {
+  return signIn.kind === SIGN_IN_KINDS.OKTA_SAML ? Object.freeze({ amr: "sso/saml" }) : Object.freeze({ aal: "aal2" });
+}

package/src/staging-pool/signin-dispatch.mjs

@@ -0,0 +1,31 @@
+// BOT-3145: routes each pool persona to its sign-in adapter by the binding's `sign_in` kind
+// (sign-in-kinds.mjs): password + TOTP (signin-gotrue-totp.mjs) or Okta SAML
+// (signin-okta-saml.mjs). The pool stays kind-agnostic; it sees one { mint, refresh,
+// credentialHoldKey } recipe. Node-stdlib-only and self-contained.
+
+import { SIGN_IN_KINDS, TOTP_SIGN_IN } from "./sign-in-kinds.mjs";
+import { SignInError } from "./signin-gotrue-totp.mjs";
+
+export function signInLookup(binding) {
+  const byEmail = new Map(Object.values(binding?.personas ?? {}).map((persona) => [persona.email, persona.signIn ?? TOTP_SIGN_IN]));
+  return (persona) => byEmail.get(persona) ?? TOTP_SIGN_IN;
+}
+
+export function createBindingSignIn({ binding, totp, okta }) {
+  if (!totp) throw new Error("createBindingSignIn needs the TOTP adapter.");
+  const signInFor = signInLookup(binding);
+  const adapterFor = (persona) => {
+    if (signInFor(persona).kind !== SIGN_IN_KINDS.OKTA_SAML) return totp;
+    if (!okta) throw new SignInError("okta_adapter_unavailable", `${persona} signs in through Okta, and this job has no Okta adapter.`);
+    return okta;
+  };
+  return {
+    mint: async (args) => adapterFor(args.persona).mint(args),
+    refresh: async (args) => adapterFor(args.persona).refresh(args),
+    // A fingerprint of the credential a held persona would sign in with; null for kinds with no hold.
+    async credentialHoldKey(persona) {
+      const adapter = adapterFor(persona);
+      return typeof adapter.credentialHoldKey === "function" ? adapter.credentialHoldKey(persona) : null;
+    },
+  };
+}