@botbuddy/cli 1.60.5 → 1.60.7

package/src/staging-pool/signin-gotrue-totp.mjs

@@ -0,0 +1,198 @@
+// BOT-2084 (lifted from supplyspark-ent ENT-5120 signin-recipe.mjs): the
+// "supabase-gotrue-totp" sign-in adapter for seeded personas.
+//
+// Node-stdlib-only (global fetch) and self-contained. It performs the same GoTrue calls the staging
+// sign-in form makes — password grant, then the TOTP challenge/verify of the
+// persona's verified factor — and returns the aal2 session in the shape supabase-js
+// persists. It never calls logout (any scope), never enrols/unenrols a factor and
+// never touches app data (design constraint 6).
+//
+// GoTrue deletes a user's other AAL1 sessions on each successful MFA verify
+// (ENT-4994), so a concurrent CI sign-in can revoke this recipe's AAL1 session
+// between the password grant and the verify. That 403 session_not_found restarts
+// the attempt from the password grant.
+
+import { assertPersonaAllowed } from "./policy.mjs";
+import { decodeJwtClaims, toStoredSession } from "./state-file.mjs";
+
+export class SignInError extends Error {
+  constructor(code, message, { transient = false, status } = {}) {
+    super(message);
+    this.name = "SignInError";
+    this.code = code;
+    this.transient = transient;
+    this.status = status;
+  }
+}
+
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const REVOKED_ERROR_CODES = new Set(["session_not_found", "bad_jwt", "refresh_token_not_found"]);
+
+function describeFailure(response) {
+  const errorCode = response.body?.error_code ?? response.body?.error ?? "unknown";
+  return `HTTP ${response.status} ${errorCode}`;
+}
+
+// passwordFor({ persona }) resolves the seeded persona's password at mint time
+// (password-source.mjs reads it from the binding's 0600 env file); it is never
+// logged, returned or written anywhere.
+export function createGoTrueTotpSignIn({
+  fetchImpl = globalThis.fetch,
+  totpProvider,
+  passwordFor,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  nowMs = () => Date.now(),
+  logger = () => {},
+  maxAttempts = 3,
+  totpPeriodSeconds = 30,
+  backoffMs = 2_000,
+} = {}) {
+  if (typeof totpProvider !== "function") throw new Error("createGoTrueTotpSignIn needs a totpProvider.");
+  if (typeof passwordFor !== "function") throw new Error("createGoTrueTotpSignIn needs a passwordFor source.");
+
+  async function gotrue(target, path, { body, accessToken } = {}) {
+    const headers = { apikey: target.publishableKey, "Content-Type": "application/json" };
+    if (accessToken) headers.Authorization = `Bearer ${accessToken}`;
+    let response;
+    try {
+      response = await fetchImpl(`${target.supabaseUrl}${path}`, {
+        method: "POST",
+        headers,
+        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 isTransient = (response) => response.status === 0 || RETRYABLE_STATUSES.has(response.status);
+  const isRevoked = (response) =>
+    (response.status === 401 || response.status === 403) && REVOKED_ERROR_CODES.has(response.body?.error_code);
+
+  function assertAal2ForPersona(storedSession, persona) {
+    const claims = decodeJwtClaims(storedSession.access_token);
+    if (claims.aal !== "aal2") throw new SignInError("not_aal2", `Verify returned an ${claims.aal ?? "unknown"} session, not aal2.`);
+    if (claims.email !== persona) throw new SignInError("persona_mismatch", "Verify returned a session for a different user.");
+  }
+
+  async function waitForNextTotpWindow() {
+    const intoWindowMs = nowMs() % (totpPeriodSeconds * 1000);
+    await sleep(totpPeriodSeconds * 1000 - intoWindowMs + 1000);
+  }
+
+  async function mint({ target, persona }) {
+    assertPersonaAllowed(target, persona);
+    let lastFailure = "no attempt made";
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      const retry = async (reason, { waitWindow = false } = {}) => {
+        lastFailure = reason;
+        logger({ event: "mint_retry", persona, attempt, reason });
+        if (attempt < maxAttempts) {
+          if (waitWindow) await waitForNextTotpWindow();
+          else await sleep(backoffMs * attempt);
+        }
+      };
+
+      const password = await gotrue(target, "/auth/v1/token?grant_type=password", {
+        body: { email: persona, password: await passwordFor({ persona }) },
+      });
+      if (password.status !== 200) {
+        if (isTransient(password)) {
+          await retry(`password grant ${describeFailure(password)}`);
+          continue;
+        }
+        throw new SignInError("password_rejected", `Password grant refused: ${describeFailure(password)}.`, {
+          status: password.status,
+        });
+      }
+      const aal1Token = password.body?.access_token;
+      const factor = (password.body?.user?.factors ?? []).find(
+        (candidate) => candidate.factor_type === "totp" && candidate.status === "verified",
+      );
+      if (!factor) {
+        throw new SignInError("no_verified_totp_factor", `${persona} has no verified TOTP factor on ${target.name}.`);
+      }
+
+      const challenge = await gotrue(target, `/auth/v1/factors/${factor.id}/challenge`, { accessToken: aal1Token });
+      if (challenge.status !== 200) {
+        if (isRevoked(challenge)) {
+          await retry("aal1 session revoked before challenge");
+          continue;
+        }
+        if (isTransient(challenge)) {
+          await retry(`challenge ${describeFailure(challenge)}`);
+          continue;
+        }
+        throw new SignInError("challenge_failed", `MFA challenge refused: ${describeFailure(challenge)}.`, {
+          status: challenge.status,
+        });
+      }
+
+      const code = await totpProvider({ persona, environment: target.totpEnvironment });
+      const verify = await gotrue(target, `/auth/v1/factors/${factor.id}/verify`, {
+        accessToken: aal1Token,
+        body: { challenge_id: challenge.body?.id, code },
+      });
+      if (verify.status !== 200) {
+        if (isRevoked(verify)) {
+          await retry("aal1 session revoked before verify");
+          continue;
+        }
+        if (verify.status === 422 && verify.body?.error_code === "mfa_verification_failed") {
+          await retry("totp code rejected", { waitWindow: true });
+          continue;
+        }
+        if (isTransient(verify)) {
+          await retry(`verify ${describeFailure(verify)}`);
+          continue;
+        }
+        throw new SignInError("verify_failed", `MFA verify refused: ${describeFailure(verify)}.`, { status: verify.status });
+      }
+
+      let storedSession;
+      try {
+        storedSession = toStoredSession(verify.body);
+      } catch (error) {
+        throw new SignInError("verify_response_invalid", error.message);
+      }
+      assertAal2ForPersona(storedSession, persona);
+      logger({ event: "mint_ok", persona, attempt });
+      return storedSession;
+    }
+    throw new SignInError("mint_retries_exhausted", `Mint gave up after ${maxAttempts} attempts (last: ${lastFailure}).`, {
+      transient: true,
+    });
+  }
+
+  // Liveness for a slot this caller exclusively holds: the refresh grant returns a
+  // token minted from the session's CURRENT server-side state, so a deleted session
+  // fails and a downgraded one comes back aal1.
+  async function refresh({ target, storedSession, persona }) {
+    const response = await gotrue(target, "/auth/v1/token?grant_type=refresh_token", {
+      body: { refresh_token: storedSession.refresh_token },
+    });
+    if (response.status !== 200) {
+      if (isTransient(response)) return { ok: false, transient: true, reason: describeFailure(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 claims = decodeJwtClaims(next.access_token);
+    if (claims.aal !== "aal2") return { ok: false, transient: false, reason: "aal_downgraded" };
+    if (persona && claims.email !== persona) return { ok: false, transient: false, reason: "persona_mismatch" };
+    return { ok: true, storedSession: next };
+  }
+
+  return { mint, refresh };
+}

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

@@ -0,0 +1,166 @@
+// BOT-2084 (lifted from supplyspark-ent ENT-5120 state-file.mjs): the pool's
+// storage-state contract and its redaction.
+//
+// Node-stdlib-only and self-contained. A pool state file is a Playwright storage state that holds the
+// target app origin and exactly one localStorage key — the Supabase auth session —
+// and nothing else: no cookies, no other origin, no BotBuddy widget token.
+
+import { createHash } from "node:crypto";
+
+export class StateFileRejectedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StateFileRejectedError";
+    this.code = "state_file_rejected";
+  }
+}
+
+const STORED_SESSION_FIELDS = ["access_token", "token_type", "expires_in", "expires_at", "refresh_token", "user"];
+
+export function decodeJwtClaims(token) {
+  if (typeof token !== "string") throw new Error("JWT is not a string.");
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("JWT does not have three segments.");
+  try {
+    return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    throw new Error("JWT payload is not valid JSON.");
+  }
+}
+
+// Shape persisted by supabase-js under the auth storage key (projected from a real
+// Supply Guard staging browser state on 2026-10-05; BotBuddy's client uses the same
+// supabase-js default): exactly these six fields.
+export function toStoredSession(response) {
+  const accessToken = response?.access_token;
+  if (typeof accessToken !== "string" || !accessToken) throw new Error("Session response has no access_token.");
+  if (typeof response.refresh_token !== "string" || !response.refresh_token) {
+    throw new Error("Session response has no refresh_token.");
+  }
+  if (!response.user || typeof response.user !== "object") throw new Error("Session response has no user.");
+  const claims = decodeJwtClaims(accessToken);
+  if (!Number.isFinite(claims.exp)) throw new Error("Access token has no exp claim.");
+  return {
+    access_token: accessToken,
+    token_type: response.token_type ?? "bearer",
+    expires_in: Number(response.expires_in ?? claims.exp - Math.floor(Date.now() / 1000)),
+    expires_at: claims.exp,
+    refresh_token: response.refresh_token,
+    user: response.user,
+  };
+}
+
+export function buildStorageState({ target, storedSession }) {
+  return {
+    cookies: [],
+    origins: [
+      {
+        origin: target.appOrigin,
+        localStorage: [{ name: target.storageKey, value: JSON.stringify(storedSession) }],
+      },
+    ],
+  };
+}
+
+export function readStoredSession(state, target) {
+  const entry = state?.origins?.[0]?.localStorage?.find((item) => item.name === target.storageKey);
+  if (!entry) throw new StateFileRejectedError(`State has no ${target.storageKey} entry.`);
+  try {
+    return JSON.parse(entry.value);
+  } catch {
+    throw new StateFileRejectedError("Auth storage entry is not valid JSON.");
+  }
+}
+
+// Called before every write and after every read. Error messages name keys and
+// origins only, never values.
+export function assertStorageStateClean(state, target) {
+  if (!state || typeof state !== "object") throw new StateFileRejectedError("State is not an object.");
+  const topLevel = Object.keys(state).sort().join(",");
+  if (topLevel !== "cookies,origins") {
+    throw new StateFileRejectedError(`State has unexpected top-level keys (${topLevel}).`);
+  }
+  if (!Array.isArray(state.cookies) || state.cookies.length !== 0) {
+    throw new StateFileRejectedError("State must carry no cookies.");
+  }
+  if (!Array.isArray(state.origins) || state.origins.length !== 1) {
+    throw new StateFileRejectedError("State must carry exactly one origin.");
+  }
+  const [origin] = state.origins;
+  if (origin.origin !== target.appOrigin) {
+    throw new StateFileRejectedError(`State origin ${origin.origin} is not ${target.appOrigin}.`);
+  }
+  const keys = (origin.localStorage ?? []).map((item) => item.name);
+  if (keys.length !== 1 || keys[0] !== target.storageKey) {
+    throw new StateFileRejectedError(`State localStorage keys (${keys.join(",")}) must be exactly ${target.storageKey}.`);
+  }
+  const session = readStoredSession(state, target);
+  const fields = Object.keys(session).sort().join(",");
+  if (fields !== [...STORED_SESSION_FIELDS].sort().join(",")) {
+    throw new StateFileRejectedError(`Auth session has unexpected fields (${fields}).`);
+  }
+  let claims;
+  try {
+    claims = decodeJwtClaims(session.access_token);
+  } 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.");
+  }
+  return session;
+}
+
+export function sessionRef(sessionId) {
+  return createHash("sha256").update(String(sessionId)).digest("hex").slice(0, 12);
+}
+
+export function describeStoredSession(storedSession, { nowMs = Date.now() } = {}) {
+  const claims = decodeJwtClaims(storedSession.access_token);
+  return {
+    persona: claims.email ?? null,
+    aal: claims.aal ?? null,
+    amr: Array.isArray(claims.amr) ? claims.amr.map((entry) => entry?.method ?? String(entry)) : [],
+    accessExpiresAt: new Date(claims.exp * 1000).toISOString(),
+    accessExpiresInSeconds: Math.round(claims.exp - nowMs / 1000),
+    sessionRef: claims.session_id ? sessionRef(claims.session_id) : null,
+  };
+}
+
+const MIN_SECRET_LENGTH = 6;
+const PATTERNS = [
+  /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, // JWTs
+  /((?<![A-Za-z_])"?(?:access_token|refresh_token|code|password|provider_token)"?\s*[:=]\s*"?)[^",\s}]+/gi,
+  /(Bearer\s+)[^\s",]+/gi,
+];
+
+export function createRedactor() {
+  const secrets = new Set();
+  const redactString = (input) => {
+    let text = String(input);
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {
+      text = text.split(secret).join("[REDACTED]");
+    }
+    text = text.replace(PATTERNS[0], "[REDACTED]");
+    text = text.replace(PATTERNS[1], "$1[REDACTED]");
+    text = text.replace(PATTERNS[2], "$1[REDACTED]");
+    return text;
+  };
+  const redact = (value) => {
+    if (typeof value === "string") return redactString(value);
+    if (Array.isArray(value)) return value.map(redact);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item)]));
+    }
+    return value;
+  };
+  return {
+    register(secret) {
+      const value = String(secret ?? "");
+      if (value.length < MIN_SECRET_LENGTH) throw new Error("Refusing to register a redaction secret that is too short.");
+      secrets.add(value);
+    },
+    redact,
+  };
+}

package/src/staging-pool/totp-botbuddy.mjs

@@ -0,0 +1,106 @@
+// BOT-2084 (lifted from supplyspark-ent ENT-5120 botbuddy-totp.mjs): staging TOTP
+// codes come from BotBuddy get_totp_code via the botbuddy CLI, pinned to the
+// binding's tenant and app_slug. Node-stdlib-only and self-contained. The code is returned to the caller and
+// never logged; errors never echo the CLI's stdout.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { AGENT_CONTEXT_ENV_MARKERS } from "./policy.mjs";
+
+export class TotpSourceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "TotpSourceError";
+    this.code = code;
+  }
+}
+
+const MIN_REMAINING_SECONDS = 5;
+
+const defaultExec = promisify(execFile);
+
+function childEnv(env) {
+  const next = { ...env };
+  for (const name of AGENT_CONTEXT_ENV_MARKERS) delete next[name];
+  return next;
+}
+
+async function callBotBuddy({ exec, botbuddyBin, env, tenant, tool, args }) {
+  try {
+    const { stdout } = await exec(botbuddyBin, ["call", tool, "--pin", tenant, "--json", JSON.stringify(args)], {
+      env: childEnv(env),
+      timeout: 60_000,
+      maxBuffer: 1024 * 1024,
+    });
+    return stdout;
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new TotpSourceError("botbuddy_cli_missing", `botbuddy CLI not found at ${botbuddyBin}; install @botbuddy/cli or re-run install.`);
+    }
+    const stderr = String(error?.stderr ?? "").replace(/\d{6}/g, "[REDACTED]").slice(0, 300);
+    throw new TotpSourceError("totp_source_failed", `botbuddy call ${tool} failed (exit ${error?.code ?? "?"}): ${stderr}`);
+  }
+}
+
+export function createBotBuddyTotpProvider({
+  exec = defaultExec,
+  botbuddyBin,
+  tenant,
+  appSlug,
+  env = process.env,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  if (!botbuddyBin) throw new TotpSourceError("config_missing", "botbuddyBin (absolute path to the botbuddy CLI) is required.");
+  if (!tenant || !appSlug) throw new TotpSourceError("config_missing", "The binding's tenant and app_slug are required.");
+
+  async function fetchOnce({ persona, environment }) {
+    const stdout = await callBotBuddy({
+      exec,
+      botbuddyBin,
+      env,
+      tenant,
+      tool: "get_totp_code",
+      args: { app_slug: appSlug, seed_user_slug: persona, environment },
+    });
+    let body;
+    try {
+      body = JSON.parse(stdout);
+    } catch {
+      throw new TotpSourceError("totp_response_invalid", "get_totp_code returned non-JSON output.");
+    }
+    if (typeof body?.code !== "string" || !/^\d{6}$/.test(body.code)) {
+      throw new TotpSourceError("totp_response_invalid", "get_totp_code returned no 6-digit code.");
+    }
+    if (body.environment !== environment || body.seed_user_slug !== persona || body.app_slug !== appSlug) {
+      throw new TotpSourceError("totp_response_mismatch", "get_totp_code answered for a different app, persona or environment.");
+    }
+    return body;
+  }
+
+  return async function botbuddyTotp({ persona, environment }) {
+    let body = await fetchOnce({ persona, environment });
+    if (Number.isFinite(body.remaining_seconds) && body.remaining_seconds < MIN_REMAINING_SECONDS) {
+      await sleep((body.remaining_seconds + 1) * 1000);
+      body = await fetchOnce({ persona, environment });
+    }
+    return body.code;
+  };
+}
+
+// The botbuddy CLI auth boundary probe. Lists seed metadata only; never mints a code.
+export async function probeBotBuddy({ exec = defaultExec, botbuddyBin, env = process.env, tenant, appSlug, environment = "staging", personaEmails = [] } = {}) {
+  if (!botbuddyBin) throw new TotpSourceError("config_missing", "botbuddyBin is required.");
+  const stdout = await callBotBuddy({ exec, botbuddyBin, env, tenant, tool: "list_totp_seeds", args: { app_slug: appSlug } });
+  let seeds;
+  try {
+    seeds = JSON.parse(stdout);
+  } catch {
+    throw new TotpSourceError("probe_response_invalid", "list_totp_seeds returned non-JSON output.");
+  }
+  if (!Array.isArray(seeds)) throw new TotpSourceError("probe_response_invalid", "list_totp_seeds did not return a list.");
+  const matching = seeds.filter((seed) => seed.environment === environment && seed.app_slug === appSlug);
+  const registered = new Set(matching.map((seed) => seed.seed_user_slug));
+  const missing = personaEmails.filter((email) => !registered.has(email));
+  return { ok: missing.length === 0, appSlug, environment, seeds: matching.length, missingPersonas: missing };
+}