@botbuddy/cli 1.64.34 → 1.66.0

package/src/staging-pool/signin-okta-saml.mjs

@@ -0,0 +1,530 @@
+// BOT-3145 (ported from supplyspark-ent PR #3534, ENT-5553): the "okta-saml" sign-in kind
+// for pool personas whose binding carries `sign_in: { kind: "okta-saml", ... }`.
+//
+// The same path a tenant's real-Okta CI drives, end to end:
+//   1. POST /auth/v1/sso {domain: sign_in.sso_domain, skip_http_redirect, redirect_to: app origin}
+//      → the IdP URL, pinned to the exact registered sign_in.idp_host;
+//   2. a fresh headless browser runs the Okta steps (okta-steps.mjs: username → Next → password →
+//      Verify); Okta posts the SAML assertion to GoTrue's ACS, which redirects to the app origin
+//      with the session in the URL fragment;
+//   3. the ACS POST is intercepted: Playwright performs it with redirects off, reads the 302's
+//      Location (the app origin + session fragment) and answers the browser with a blank page,
+//      so the app never boots and never rotates the refresh token this adapter is about to store;
+//   4. GET /auth/v1/user for the user object, then (when the binding names one) POST the tenant's
+//      admission Edge Function (Supply Guard: sso-claim-membership, ENT-4508 — without it the
+//      app rejects an unclaimed SAML session). For an existing member it is idempotent.
+// The result is the six-field supabase-js session (aal1, amr sso/saml), like the TOTP adapter's.
+// GoTrue maps the IdP subject to the same auth user on every sign-in, so a mint never creates a
+// user (no new SSO MAU per mint, ENT-5017).
+//
+// SAML RelayState has a short validity window, so the browser is launched BEFORE the SSO begin
+// and the Okta steps run immediately after it (2026-10-14 staging: begin → ACS in 4.4 s).
+//
+// Lockout protection (#3534 HF-01): the password is submitted at most once per mint, and a
+// rejected or unconfirmed password carries `holdKey` — a keyed fingerprint of the password tried —
+// so the pool stops signing in with it until the human changes the value (repeated bad passwords
+// would lock the shared Okta test user out, and with it the tenant's CI).
+
+import { createHmac, randomBytes } from "node:crypto";
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+
+import { classifyOktaPageState, loginToOkta, readOktaPageState } from "./okta-steps.mjs";
+import { SIGN_IN_KINDS, sessionClaimsProblem } from "./sign-in-kinds.mjs";
+import { SignInError } from "./signin-gotrue-totp.mjs";
+import { decodeJwtClaims, toStoredSession } from "./state-file.mjs";
+
+const SSO_SESSION_FRAGMENT_KEYS = ["access_token", "refresh_token"];
+// 520-524: Cloudflare answering for an unreachable origin (BOT-2947).
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504, 520, 521, 522, 523, 524]);
+const BLANK_PAGE = "<!doctype html><title>bb staging-pool</title>";
+// GoTrue's SAML Assertion Consumer Service, on whatever host staging's auth is served from
+// (Supply Guard 2026-10-14: https://staging-api.supply-guard.io/auth/v1/sso/saml/acs).
+export const ACS_ROUTE = "**/auth/v1/sso/saml/acs*";
+// Failures that mean "this password is wrong, or may be": the pool holds the persona until the
+// value changes, so the shared Okta test user is not locked out by repeated submissions.
+export const HELD_CODES = new Set(["okta_password_rejected", "okta_password_unconfirmed"]);
+
+// BOT-3145 review: a password that was submitted but never confirmed is held too, unless the
+// outcome proves Okta accepted it: its ACS answered, the browser left the Okta host, or Okta asked
+// for a second factor. Every other submitted-and-unconfirmed outcome could be a refusal.
+export function holdable(error, progress) {
+  if (HELD_CODES.has(error.code)) return true;
+  if (!progress.passwordSubmitted || progress.acsAnswered || progress.leftOkta) return false;
+  return error.code !== "okta_mfa_prompt" && error.code !== "okta_saml_relay_expired";
+}
+
+// A keyed fingerprint (HMAC-SHA256 under a random per-install key kept 0600 in the pool home):
+// enough to notice the human changed the password, useless as an offline verifier to anyone
+// without the key. Stored in health.json; `status` shows only `held: true` (#3534 HF-02).
+// "<key id>:<fingerprint>": the key id (a hash of the key, not of any password) lets the pool tell a
+// changed password from a replaced key, so deleting credential-hold.key never clears a hold.
+export function credentialFingerprint(password, holdSecret) {
+  if (!holdSecret || holdSecret.length < 16) throw new Error("credentialFingerprint needs the pool's hold key.");
+  const keyId = createHmac("sha256", holdSecret).update("bb staging-pool okta credential hold key id").digest("hex").slice(0, 8);
+  const fingerprint = createHmac("sha256", holdSecret).update(`bb staging-pool okta credential hold\0${password}`).digest("hex").slice(0, 16);
+  return `${keyId}:${fingerprint}`;
+}
+
+// Loads (or creates once, 0600) the pool's random hold key.
+// A short or unreadable key is never replaced silently: that would orphan every recorded hold, so it
+// throws and the mint fails closed (credential_hold_unavailable) before any IdP contact.
+const HOLD_KEY_BYTES = 32;
+function checkedHoldKey(key, path) {
+  if (!key || key.length < HOLD_KEY_BYTES) throw new Error(`The credential hold key ${path} is corrupt (under ${HOLD_KEY_BYTES} bytes).`);
+  return key;
+}
+
+export function loadOrCreateHoldKey(path, { fs = { readFileSync, writeFileSync, chmodSync }, random = () => randomBytes(HOLD_KEY_BYTES) } = {}) {
+  try {
+    return checkedHoldKey(fs.readFileSync(path), path);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const key = random();
+  try {
+    fs.writeFileSync(path, key, { mode: 0o600, flag: "wx" });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    return checkedHoldKey(fs.readFileSync(path), path); // a concurrent first use won the race
+  }
+  fs.chmodSync(path, 0o600);
+  return checkedHoldKey(key, path);
+}
+
+// The first line of a browser error, with every URL query removed: Playwright messages carry
+// the IdP URL (SAMLRequest, RelayState) and a multi-line call log (#3534 HF-04).
+export function browserErrorSummary(error) {
+  return String(error?.message ?? error)
+    .split("\n")[0]
+    .replace(/(https?:\/\/[^\s?#]+)[?#]\S*/g, "$1?…")
+    .slice(0, 200);
+}
+
+function sanitizeState(state) {
+  if (!state) return null;
+  return {
+    host: state.host,
+    path: state.path,
+    heading: state.headingText ?? null,
+    error: state.errorText ?? null,
+    passwordVisible: Boolean(state.passwordVisible),
+    authenticatorListVisible: Boolean(state.authenticatorListVisible),
+  };
+}
+
+export function createOktaSamlSignIn({
+  fetchImpl = globalThis.fetch,
+  launchBrowser,
+  passwordFor,
+  signInFor,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  nowMs = () => Date.now(),
+  logger = () => {},
+  maxAttempts = 2,
+  landingTimeoutMs = 90_000,
+  pollMs = 1_000,
+  backoffMs = 5_000,
+  holdSecret,
+} = {}) {
+  if (typeof launchBrowser !== "function") throw new Error("createOktaSamlSignIn needs launchBrowser.");
+  if (typeof passwordFor !== "function") throw new Error("createOktaSamlSignIn needs passwordFor.");
+  if (typeof signInFor !== "function") throw new Error("createOktaSamlSignIn needs signInFor (the binding's per-persona sign_in).");
+  if (typeof holdSecret !== "function") throw new Error("createOktaSamlSignIn needs holdSecret (the pool's hold key).");
+
+  async function call(url, { method = "POST", headers, body } = {}) {
+    let response;
+    try {
+      response = await fetchImpl(url, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    } catch (error) {
+      return { status: 0, body: null, networkError: error?.message ?? String(error) };
+    }
+    let parsed = null;
+    try {
+      parsed = await response.json();
+    } catch {
+      parsed = null;
+    }
+    return { status: response.status, body: parsed };
+  }
+
+  const describe = (response) =>
+    `HTTP ${response.status} ${response.body?.error_code ?? response.body?.errorCode ?? response.body?.code ?? response.body?.error ?? "unknown"}`;
+  const isTransient = (response) => response.status === 0 || RETRYABLE_STATUSES.has(response.status);
+
+  async function beginSso(target, spec) {
+    const begin = await call(`${target.supabaseUrl}/auth/v1/sso`, {
+      headers: { apikey: target.publishableKey, "Content-Type": "application/json" },
+      body: { domain: spec.ssoDomain, skip_http_redirect: true, redirect_to: target.appOrigin },
+    });
+    if (begin.status !== 200) {
+      throw new SignInError("sso_begin_failed", `GoTrue SSO begin for ${spec.ssoDomain} refused: ${describe(begin)}.`, {
+        transient: isTransient(begin),
+        status: begin.status,
+      });
+    }
+    let idpHost = "";
+    try {
+      const parsed = new URL(begin.body?.url);
+      // https only: the password is never typed into a plaintext page, even on the right host.
+      idpHost = parsed.protocol === "https:" ? parsed.hostname : `${parsed.protocol}//${parsed.hostname}`;
+    } catch {
+      idpHost = "";
+    }
+    if (idpHost !== spec.idpHost) {
+      throw new SignInError(
+        "okta_unexpected_host",
+        `GoTrue routed ${spec.ssoDomain} to ${idpHost || "(no URL)"}, not the registered Okta host ${spec.idpHost}.`,
+      );
+    }
+    return begin.body.url;
+  }
+
+  // Runs the Okta steps and intercepts GoTrue's ACS. Returns the ACS redirect target (its
+  // fragment carries the session or a GoTrue error).
+  //
+  // The ACS POST is fetched by Playwright with redirects off and answered with a blank page, so
+  // the browser never follows the 302 to the app. Routing the app origin instead does NOT work:
+  // Playwright never routes a request that is the result of a redirect (proven in real Chromium
+  // on 2026-10-14, supplyspark-ent ENT-5553), so the app would boot and could rotate the refresh token.
+  //
+  // `progress` records whether the password was submitted and whether GoTrue's ACS answered, so
+  // mint() never re-submits a password whose outcome it could not confirm (#3534 HF-01).
+  async function driveOkta({ browser, target, spec, persona, password, idpUrl, progress, beforePasswordFill }) {
+    const unreachable = (error) =>
+      new SignInError("okta_unreachable", `The browser could not reach Okta: ${browserErrorSummary(error)}`, { transient: true });
+    let context;
+    try {
+      context = await browser.newContext();
+    } catch (error) {
+      throw unreachable(error);
+    }
+    let landedUrl = "";
+    let acsFailure = null;
+    let acsIntercepted = false;
+    const onAppOrigin = (url) => {
+      try {
+        return new URL(url).origin === target.appOrigin;
+      } catch {
+        return false;
+      }
+    };
+    const onAcs = async (route) => {
+      acsIntercepted = true;
+      try {
+        const response = await route.fetch({ maxRedirects: 0 });
+        const location = response.headers()?.location ?? "";
+        // Success is a 302 to the app with the session in the fragment; GoTrue answers an ACS
+        // error with a 303 redirect carrying error params (both seen on staging, 2026-10-14).
+        if (onAppOrigin(location) && /[#&?]access_token=/.test(location)) {
+          landedUrl = location;
+        } else {
+          const body = await response.text().catch(() => "");
+          acsFailure = { status: response.status(), location, body: String(body).slice(0, 400) };
+        }
+        progress.acsAnswered = true;
+      } catch (error) {
+        acsFailure = { status: 0, location: "", body: browserErrorSummary(error) };
+      }
+      await route.fulfill({ status: 200, contentType: "text/html", body: BLANK_PAGE });
+    };
+    let page;
+    try {
+      await context.route(ACS_ROUTE, onAcs);
+      page = await context.newPage();
+    } catch (error) {
+      throw unreachable(error);
+    }
+    let reachedApp = false;
+    page.on("framenavigated", (frame) => {
+      if (frame !== page.mainFrame()) return;
+      if (onAppOrigin(frame.url())) {
+        reachedApp = true;
+        progress.leftOkta = true;
+      }
+    });
+    const settled = () => {
+      if (landedUrl) return landedUrl;
+      if (acsFailure) {
+        let code = null;
+        try {
+          const failed = new URL(acsFailure.location);
+          code = new URLSearchParams(failed.hash.replace(/^#/, "")).get("error_code") ?? failed.searchParams.get("error_code");
+        } catch {
+          code = null;
+        }
+        code ??= /"?error_code"?\s*[:=]\s*"?([a-z_]+)/i.exec(acsFailure.body)?.[1] ?? `http_${acsFailure.status}`;
+        return `${target.appOrigin}/#error_code=${encodeURIComponent(code)}&error=acs_error`;
+      }
+      if (reachedApp && !acsIntercepted) {
+        throw new SignInError(
+          "sso_acs_not_intercepted",
+          `The SAML callback reached ${target.appOrigin} without passing ${ACS_ROUTE}; refusing a session the app may already have rotated.`,
+        );
+      }
+      return "";
+    };
+    try {
+      await page.goto(idpUrl, { waitUntil: "commit" });
+    } catch (error) {
+      throw unreachable(error);
+    }
+    try {
+      await loginToOkta(page, persona, password, spec.idpHost, {
+        beforePasswordFill,
+        onPasswordSubmit: () => {
+          progress.passwordSubmitted = true;
+        },
+      });
+    } catch (error) {
+      if (error instanceof SignInError) throw error;
+      if (settled()) return settled();
+      if (/refusing to enter Okta credentials/.test(String(error?.message))) {
+        throw new SignInError("okta_unexpected_host", browserErrorSummary(error));
+      }
+      const state = await readOktaPageState(page).catch(() => null);
+      logger({ event: "okta_page_state", persona, stage: "steps", state: sanitizeState(state) });
+      throw new SignInError("okta_steps_failed", `Okta sign-in steps did not complete: ${browserErrorSummary(error)}`, {
+        transient: true,
+      });
+    }
+    const deadline = nowMs() + landingTimeoutMs;
+    let lastState = null;
+    for (;;) {
+      if (settled()) return settled();
+      if (nowMs() >= deadline) {
+        logger({ event: "okta_page_state", persona, stage: "timeout", state: sanitizeState(lastState) });
+        // Okta kept its sign-in form after Verify with no error we recognise: the password may
+        // have been refused in markup we never captured. Hold it like a rejection (#3534 HF-01).
+        if (
+          progress.passwordSubmitted &&
+          lastState?.host === spec.idpHost &&
+          (lastState.passwordVisible || lastState.identifierVisible)
+        ) {
+          throw new SignInError(
+            "okta_password_unconfirmed",
+            `Okta still showed its sign-in form ${Math.round(landingTimeoutMs / 1000)} s after ${persona}'s password was submitted; treating its configured password as rejected.`,
+          );
+        }
+        throw new SignInError("okta_timeout", `No SAML callback reached GoTrue's ACS within ${Math.round(landingTimeoutMs / 1000)} s.`, {
+          transient: true,
+        });
+      }
+      await sleep(pollMs);
+      if (settled()) return settled();
+      const state = await readOktaPageState(page).catch(() => null);
+      if (!state) continue;
+      lastState = state;
+      const verdict = classifyOktaPageState(state, { expectedHost: spec.idpHost });
+      // Off the Okta host after Verify: Okta accepted the password and moved on (no hold).
+      if (verdict === "off_okta") {
+        // Only a real https page on another host proves Okta moved on; about:blank or a browser
+        // error page proves nothing (review round 2, P3-1).
+        if (progress.passwordSubmitted && state.protocol === "https:" && state.host && state.host !== spec.idpHost) progress.leftOkta = true;
+        continue;
+      }
+      if (verdict === "pending") continue;
+      logger({ event: "okta_page_state", persona, stage: verdict, state: sanitizeState(state) });
+      if (verdict === "password_rejected") {
+        throw new SignInError(
+          "okta_password_rejected",
+          `Okta rejected ${persona}'s sign-in with its configured password (${state.errorText ?? "form error"}).`,
+        );
+      }
+      if (verdict === "account_locked") {
+        throw new SignInError("okta_account_locked", `Okta reports ${persona} as locked or suspended (${state.errorText}).`);
+      }
+      throw new SignInError(
+        "okta_mfa_prompt",
+        `Okta asked ${persona} for a second factor (${state.headingText ?? "authenticator challenge"}); the app's Okta policy should be password-only.`,
+      );
+    }
+  }
+
+  async function sessionFromLanding({ target, spec, persona, landedUrl }) {
+    const url = new URL(landedUrl);
+    const params = new URLSearchParams(url.hash.replace(/^#/, ""));
+    for (const [key, value] of new URLSearchParams(url.search)) if (!params.has(key)) params.set(key, value);
+    const errorCode = params.get("error_code");
+    if (errorCode || params.get("error")) {
+      if (errorCode === "saml_relay_state_expired" || errorCode === "saml_relay_state_not_found") {
+        throw new SignInError("okta_saml_relay_expired", `GoTrue refused the SAML callback: ${errorCode}.`, { transient: true });
+      }
+      throw new SignInError("sso_callback_error", `GoTrue refused the SAML callback: ${errorCode ?? params.get("error")}.`);
+    }
+    if (!SSO_SESSION_FRAGMENT_KEYS.every((key) => params.get(key))) {
+      throw new SignInError("sso_callback_error", "The SAML callback carried no session.");
+    }
+    const accessToken = params.get("access_token");
+    const user = await call(`${target.supabaseUrl}/auth/v1/user`, {
+      method: "GET",
+      headers: { apikey: target.publishableKey, Authorization: `Bearer ${accessToken}` },
+    });
+    if (user.status !== 200 || !user.body?.id) {
+      throw new SignInError("sso_user_unreadable", `GoTrue /user refused the new SSO session: ${describe(user)}.`, {
+        transient: isTransient(user),
+      });
+    }
+    let storedSession;
+    try {
+      storedSession = toStoredSession({
+        access_token: accessToken,
+        refresh_token: params.get("refresh_token"),
+        token_type: params.get("token_type") ?? "bearer",
+        expires_in: params.get("expires_in") ? Number(params.get("expires_in")) : undefined,
+        user: user.body,
+      });
+    } catch (error) {
+      throw new SignInError("sso_callback_error", error.message);
+    }
+    const problem = sessionClaimsProblem(decodeJwtClaims(storedSession.access_token), { email: persona, signIn: spec });
+    if (problem) throw new SignInError(problem === "persona_mismatch" ? "persona_mismatch" : "not_sso_session", `The SAML session is wrong for ${persona} (${problem}).`);
+    return storedSession;
+  }
+
+  // The tenant's admission writer for a fresh SAML session (sign_in.admission_function), when the
+  // binding names one. Admitted = HTTP 200, success not false, no re-authentication asked for,
+  // and (when sign_in.admission_route is set) the member route, e.g. Supply Guard's /dashboard
+  // rather than /access-pending.
+  async function admit({ target, spec, persona, storedSession }) {
+    if (!spec.admissionFunction) return;
+    const claim = await call(`${target.supabaseUrl}/functions/v1/${spec.admissionFunction}`, {
+      headers: {
+        apikey: target.publishableKey,
+        Authorization: `Bearer ${storedSession.access_token}`,
+        "Content-Type": "application/json",
+      },
+      body: {},
+    });
+    const admitted =
+      claim.status === 200 &&
+      claim.body?.success !== false &&
+      claim.body?.reauthenticate !== true &&
+      (!spec.admissionRoute || claim.body?.route === spec.admissionRoute);
+    if (admitted) {
+      logger({ event: "sso_admitted", persona, outcome: claim.body?.outcome ?? null });
+      return;
+    }
+    const outcome = claim.body?.outcome ?? claim.body?.errorCode ?? claim.body?.error_code ?? null;
+    throw new SignInError(
+      "sso_admission_failed",
+      `${spec.admissionFunction} did not admit ${persona}: HTTP ${claim.status} ${outcome ?? "unknown"} route ${claim.body?.route ?? "none"}.`,
+      { transient: isTransient(claim) || claim.body?.reauthenticate === true, status: claim.status },
+    );
+  }
+
+  function oktaSpec(persona) {
+    const spec = signInFor(persona);
+    if (spec?.kind !== SIGN_IN_KINDS.OKTA_SAML) {
+      throw new SignInError("wrong_sign_in_kind", `${persona} does not sign in through Okta.`);
+    }
+    return spec;
+  }
+
+  // persistHold(holdKey), from the pool: saves a pending credential hold before the password is
+  // typed (review round 2, P2-1). If it throws, nothing is typed.
+  async function mint({ target, persona, persistHold }) {
+    const spec = oktaSpec(persona);
+    if (target.loopback) {
+      throw new SignInError("okta_target_unsupported", "Okta SAML personas sign in on staging only (local GoTrue has no SAML SP).");
+    }
+    // password-source.mjs reads the persona's password_env from the binding's 0600 file and
+    // fails closed with its own password_source_* code.
+    const password = await passwordFor({ persona });
+    // The hold fingerprint is computed BEFORE any IdP contact: if it cannot be, nothing is
+    // submitted (a refused password must always be holdable, fail closed).
+    let holdKey;
+    try {
+      holdKey = credentialFingerprint(password, holdSecret());
+    } catch (error) {
+      throw new SignInError("credential_hold_unavailable", `The pool's credential hold key is unusable, so ${persona} is not signed in: ${String(error?.message ?? error).slice(0, 200)}`);
+    }
+    let lastFailure = "no attempt made";
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      let browser;
+      const progress = { passwordSubmitted: false, acsAnswered: false, leftOkta: false };
+      try {
+        try {
+          browser = await launchBrowser();
+        } catch (error) {
+          throw new SignInError("okta_browser_unavailable", `Could not start headless Chromium: ${browserErrorSummary(error)}`);
+        }
+        const idpUrl = await beginSso(target, spec);
+        const beforePasswordFill = persistHold
+          ? async () => {
+            try {
+              await persistHold(holdKey);
+            } catch (error) {
+              throw new SignInError("credential_hold_unavailable", `The pool could not save a pending credential hold for ${persona}, so nothing was typed: ${String(error?.message ?? error).slice(0, 200)}`);
+            }
+          }
+          : undefined;
+        const landedUrl = await driveOkta({ browser, target, spec, persona, password, idpUrl, progress, beforePasswordFill });
+        const storedSession = await sessionFromLanding({ target, spec, persona, landedUrl });
+        await admit({ target, spec, persona, storedSession });
+        logger({ event: "mint_ok", persona, attempt, signIn: SIGN_IN_KINDS.OKTA_SAML });
+        return storedSession;
+      } catch (error) {
+        // Anything thrown after the password went in is a failed sign-in step, so it can be held.
+        if (!(error instanceof SignInError) && !progress.passwordSubmitted) throw error;
+        const failure = error instanceof SignInError ? error : new SignInError("okta_steps_failed", `Okta sign-in failed after the password was submitted: ${browserErrorSummary(error)}`);
+        if (holdable(failure, progress)) failure.holdKey = holdKey;
+        // The pool may release a pending hold only on this adapter's explicit verdict.
+        failure.credentialChecked = true;
+        error = failure;
+        // #3534 HF-01: once the password was submitted, only an answered ACS (Okta accepted it) or
+        // an expired RelayState (Okta posted back, so it accepted it) may re-submit it in this mint.
+        if (progress.passwordSubmitted && !progress.acsAnswered && error.code !== "okta_saml_relay_expired") {
+          error.transient = false;
+        }
+        if (!error.transient || attempt >= maxAttempts) throw error;
+        lastFailure = `${error.code}: ${error.message}`;
+        logger({ event: "mint_retry", persona, attempt, reason: error.code });
+        await sleep(backoffMs * attempt);
+      } finally {
+        await browser?.close().catch(() => {});
+      }
+    }
+    // Only transient, non-holdable attempts are retried (a holdable one is never transient), so this
+    // verdict is "checked: nothing refused".
+    throw Object.assign(new SignInError("mint_retries_exhausted", `Mint gave up after ${maxAttempts} attempts (last: ${lastFailure}).`, {
+      transient: true,
+    }), { credentialChecked: true });
+  }
+
+  // Liveness for a slot this caller exclusively holds: the refresh grant answers from the
+  // session's current server-side state, and the result must still be this persona's SAML session.
+  async function refresh({ target, storedSession, persona }) {
+    const response = await call(`${target.supabaseUrl}/auth/v1/token?grant_type=refresh_token`, {
+      headers: { apikey: target.publishableKey, "Content-Type": "application/json" },
+      body: { refresh_token: storedSession.refresh_token },
+    });
+    if (response.status !== 200) {
+      if (isTransient(response)) return { ok: false, transient: true, reason: describe(response) };
+      return { ok: false, transient: false, reason: response.body?.error_code ?? `http_${response.status}` };
+    }
+    let next;
+    try {
+      next = toStoredSession(response.body);
+    } catch {
+      return { ok: false, transient: false, reason: "refresh_response_invalid" };
+    }
+    const problem = sessionClaimsProblem(decodeJwtClaims(next.access_token), { email: persona, signIn: oktaSpec(persona) });
+    if (problem) return { ok: false, transient: false, reason: problem };
+    return { ok: true, storedSession: next };
+  }
+
+  // The pool skips a persona whose last mint was refused for THIS credential. Null when the
+  // password cannot be read (the mint then fails with the password source's own code).
+  async function credentialHoldKey(persona) {
+    oktaSpec(persona);
+    let password;
+    try {
+      password = await passwordFor({ persona });
+    } catch {
+      return null;
+    }
+    return password ? credentialFingerprint(password, holdSecret()) : null;
+  }
+
+  return { mint, refresh, credentialHoldKey };
+}

package/src/staging-pool/state-file.mjs

@@ -7,6 +7,8 @@
 
 import { createHash } from "node:crypto";
 
+import { TOTP_SIGN_IN, sessionClaimsProblem } from "./sign-in-kinds.mjs";
+
 export class StateFileRejectedError extends Error {
   constructor(message) {
     super(message);
@@ -105,10 +107,14 @@ export function assertStorageStateClean(state, target) {
   } catch (error) {
     throw new StateFileRejectedError(error.message);
   }
-  if (claims.aal !== "aal2") throw new StateFileRejectedError(`Session is ${claims.aal ?? "unknown"}, not aal2.`);
   if (!target.personaEmails?.includes(claims.email)) {
     throw new StateFileRejectedError("Session persona is not an allowlisted seeded persona.");
   }
+  // BOT-3145: TOTP personas hold aal2; okta-saml personas hold an sso/saml session.
+  const signIn = target.personaSignIns?.[claims.email] ?? TOTP_SIGN_IN;
+  const problem = sessionClaimsProblem(claims, { email: claims.email, signIn });
+  if (problem === "aal_downgraded") throw new StateFileRejectedError(`Session is ${claims.aal ?? "unknown"}, not aal2.`);
+  if (problem) throw new StateFileRejectedError(`Session claims are wrong for its ${signIn.kind} persona (${problem}).`);
   return session;
 }
 

package/src/staging-pool/test-helpers/bindings.mjs

@@ -39,3 +39,33 @@ export const SG_TARGET = stagingTargetFromBinding(SG_BINDING);
 const { _comment: _note, ...BOTBUDDY_REGISTRATION } = JSON.parse(readFileSync(new URL("../../../../scripts/staging-session-pool.botbuddy.json", import.meta.url), "utf8"));
 export const BOTBUDDY_RAW_BINDING = Object.freeze({ schema_version: 1, ...BOTBUDDY_REGISTRATION });
 export const BOTBUDDY_BINDING = parsePoolBinding(BOTBUDDY_RAW_BINDING);
+
+// BOT-3145: Supply Guard's binding with its Okta E2E org admin as an okta-saml persona
+// (the values ENT-5553 registers; the 2026-10-14 fixture's IdP host and SSO domain).
+export const OKTA_IDP_HOST = "integrator-4707698.okta.com";
+export const OKTA_SSO_DOMAIN = "okta-e2e.supplyguard.test";
+export const OKTA_PERSONA = "sso-convert-acceptance@okta-e2e.supplyguard.test";
+export const OKTA_PASSWORD_ENV = "OKTA_E2E_USER_PASSWORD";
+export const SG_OKTA_RAW_BINDING = Object.freeze({
+  ...SG_RAW_BINDING,
+  staging_session_pool: {
+    ...SG_RAW_BINDING.staging_session_pool,
+    personas: {
+      ...SG_RAW_BINDING.staging_session_pool.personas,
+      "okta-org-admin": {
+        email: OKTA_PERSONA,
+        password_env: OKTA_PASSWORD_ENV,
+        default_count: 1,
+        sign_in: {
+          kind: "okta-saml",
+          sso_domain: OKTA_SSO_DOMAIN,
+          idp_host: OKTA_IDP_HOST,
+          admission_function: "sso-claim-membership",
+          admission_route: "/dashboard",
+        },
+      },
+    },
+  },
+});
+export const SG_OKTA_BINDING = parsePoolBinding(SG_OKTA_RAW_BINDING);
+export const SG_OKTA_TARGET = stagingTargetFromBinding(SG_OKTA_BINDING);