@bugmole/cli 0.4.0 → 0.6.0

package/src/runtime/web-suite.test.ts

@@ -95,3 +95,68 @@ test("typed secrets never reach the uploaded log, and the shared session is dele
     await fs.rm(dir, { recursive: true, force: true });
   }
 });
+
+test("a flow written for production runs against --base-url, not production", async (t) => {
+  const { chromium } = await import("playwright");
+  try {
+    await fs.access(chromium.executablePath());
+  } catch {
+    t.skip("Chromium is not installed");
+    return;
+  }
+  const http = await import("node:http");
+  const seen: string[] = [];
+  const server = http.createServer((request, response) => {
+    seen.push(request.url ?? "");
+    response.writeHead(200, { "content-type": "text/html" });
+    response.end("<!doctype html><h1>Pricing on staging</h1>");
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as { port: number };
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-suite-rebase-"));
+  await fs.writeFile(path.join(dir, "pricing.yaml"), "url: https://production.invalid/pricing/\n---\n- launchApp\n- assertVisible: \"Pricing on staging\"\n");
+  try {
+    const report = await runWebSuite({ flowsDir: dir, baseUrl: `http://127.0.0.1:${port}`, artifactsDir: path.join(dir, "artifacts"), projectId: "demo" });
+    assert.equal(report.totals.passed, 1, report.flows[0]?.message);
+    assert.ok(seen.includes("/pricing/"), seen.join(","));
+  } finally {
+    server.close();
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("waiting for text survives the page navigating away mid-check, as a sign-in redirect does", async (t) => {
+  const { chromium } = await import("playwright");
+  try {
+    await fs.access(chromium.executablePath());
+  } catch {
+    t.skip("Chromium is not installed");
+    return;
+  }
+  const { isNavigationError } = await import("./playwright-driver.js");
+  assert.equal(isNavigationError(new Error("page.evaluate: Execution context was destroyed, most likely because of a navigation")), true);
+  assert.equal(isNavigationError(new Error("Target closed")), false);
+  const http = await import("node:http");
+  const server = http.createServer((request, response) => {
+    response.writeHead(200, { "content-type": "text/html" });
+    if (request.url === "/app") {
+      // The app is slow to answer, so the check runs while the page is between documents.
+      setTimeout(() => response.end("<!doctype html><h1>Quality, as a flow.</h1>"), 700);
+      return;
+    }
+    response.end("<!doctype html><p>Signing you in…</p><script>setTimeout(() => { location.href = '/app'; }, 150)</script>");
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as { port: number };
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-suite-nav-"));
+  await fs.writeFile(path.join(dir, "sign-in.yaml"), "url: /\n---\n- launchApp\n- assertVisible:\n    text: \"Quality, as a flow.\"\n    timeout: 10000\n");
+  try {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const report = await runWebSuite({ flowsDir: dir, baseUrl: `http://127.0.0.1:${port}/`, artifactsDir: path.join(dir, `artifacts-${attempt}`), projectId: "demo" });
+      assert.equal(report.totals.passed, 1, report.flows[0]?.message);
+    }
+  } finally {
+    server.close();
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/web-suite.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { PlaywrightDriver } from "./playwright-driver.js";
-import type { DriverResult } from "./driver.js";
+import type { AppDriver, DriverResult } from "./driver.js";
 import { targetLabel, type RunTarget } from "./browser-matrix.js";
 import { resolveTargetConcurrency, runPool } from "./target-runner.js";
 
@@ -13,6 +13,8 @@ export interface WebSuiteOptions {
   runId?: string;
   headless?: boolean;
   timeoutMs?: number;
+  /** Wraps the suite's driver, e.g. to give flows their secrets (secret-driver.ts). */
+  wrapDriver?: (driver: AppDriver) => AppDriver;
   /**
    * Comma-separated substrings matched against flow file names, for re-running
    * part of a suite. Include the sign-in flow when the suite shares a session.
@@ -96,7 +98,8 @@ export async function runWebSuite(options: WebSuiteOptions): Promise<WebSuiteRep
     throw new Error(`No flow files found in ${options.flowsDir}${options.grep ? ` matching "${options.grep}"` : ""}.`);
   }
 
-  const driver = new PlaywrightDriver({ headless: options.headless ?? true });
+  const base = new PlaywrightDriver({ headless: options.headless ?? true });
+  const driver = options.wrapDriver ? options.wrapDriver(base) : base;
   const startedAt = new Date().toISOString();
   const targets = options.targets?.length ? options.targets : undefined;
 
@@ -125,6 +128,9 @@ export async function runWebSuite(options: WebSuiteOptions): Promise<WebSuiteRep
         flowPath,
         platform: "web",
         target: { baseUrl: options.baseUrl },
+        // The suite runs against --base-url: a flow written for another
+        // address (production, say) is moved onto it, as plan runs do.
+        rebaseOrigin: true,
         timeoutMs: options.timeoutMs ?? 30_000,
         artifactsDir: options.artifactsDir,
         sessionStatePath,

package/src/storage/create-object-store.ts

@@ -1,5 +1,5 @@
 import { Storage } from "@google-cloud/storage";
-import { LocalObjectStore, type ObjectStore, type StorageProvider, type StoredObject } from "./object-store.js";
+import { LocalObjectStore, withSecretRedaction, type ObjectStore, type StorageProvider, type StoredObject } from "./object-store.js";
 import { S3ObjectStore } from "./remote-object-store.js";
 import { RegistryObjectStore } from "./registry-object-store.js";
 import { resolveLocalStorageDirectory, type StorageSettings } from "./storage-directory.js";
@@ -106,6 +106,10 @@ export function createProjectObjectStore(cfg: StorageSettings, fallback = "./run
 }
 
 export function createObjectStore(config: ObjectStoreConfig): ObjectStore {
+  return withSecretRedaction(openObjectStore(config));
+}
+
+function openObjectStore(config: ObjectStoreConfig): ObjectStore {
   const nested = (config as Record<string, unknown>)[config.provider] as Record<string, string | undefined> | undefined;
   const value = (name: string, fallback?: string) => nested?.[name] ?? fallback;
   if (config.provider === "local") {

package/src/storage/object-store.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { redactBody, redactSecrets } from "../runtime/secret-redaction.js";
 
 /** "bugmole" is Bugmole-managed storage, reached through the registry. */
 export type StorageProvider = "local" | "gcs" | "s3" | "r2" | "bugmole";
@@ -22,6 +23,16 @@ export type ObjectStore = {
   publicUrl?(key: string, expiresInSeconds?: number): Promise<string>;
 };
 
+/**
+ * Wraps a store so text uploads never carry a flow secret the worker typed:
+ * logs, results, manifests and failure context are redacted on the way out.
+ */
+export function withSecretRedaction(store: ObjectStore): ObjectStore {
+  const put = store.put.bind(store);
+  store.put = (key, body, contentType) => put(key, redactBody(body, contentType), contentType);
+  return store;
+}
+
 export function normalizeKey(key: string): string {
   const normalized = key.replaceAll("\\", "/").replace(/^\/+/, "");
   if (!normalized || normalized.split("/").some((part) => part === ".." || part === ".")) {
@@ -97,5 +108,5 @@ export class LocalObjectStore implements ObjectStore {
 }
 
 export function json(value: unknown): string {
-  return JSON.stringify(value, null, 2);
+  return redactSecrets(JSON.stringify(value, null, 2));
 }

package/src/storage/test-case-results.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ObjectStore, StoredObject } from "./object-store.js";
+import { putTestCaseResults, testCaseHistoryKey, testCaseHistoryPrefix, testCaseResultsKey } from "./test-case-results.js";
+
+function memoryStore(): ObjectStore & { objects: Map<string, string> } {
+  const objects = new Map<string, string>();
+  const stored = (key: string): StoredObject => ({ key, size: objects.get(key)!.length, modifiedAt: new Date(0).toISOString() });
+  return {
+    provider: "local",
+    objects,
+    async put(key, body) {
+      objects.set(key, typeof body === "string" ? body : new TextDecoder().decode(body));
+      return stored(key);
+    },
+    async get(key) {
+      return new TextEncoder().encode(objects.get(key)!);
+    },
+    async getText(key) {
+      if (!objects.has(key)) throw new Error("missing");
+      return objects.get(key)!;
+    },
+    async has(key) {
+      return objects.has(key);
+    },
+    async list(prefix) {
+      return [...objects.keys()].filter((key) => key.startsWith(prefix)).map(stored);
+    },
+    async deletePrefix(prefix) {
+      for (const key of [...objects.keys()]) if (key.startsWith(prefix)) objects.delete(key);
+    },
+    async publicUrl(key) {
+      return key;
+    },
+  } as ObjectStore & { objects: Map<string, string> };
+}
+
+test("latest and history keys stay inside the project and apart from each other", () => {
+  assert.equal(testCaseResultsKey("qa framework", "login"), "projects/qa%20framework/test-case-results/login.json");
+  assert.equal(testCaseHistoryPrefix("qa framework", "login"), "projects/qa%20framework/test-case-history/login/");
+  assert.ok(!testCaseHistoryPrefix("demo").startsWith("projects/demo/test-case-results/"));
+});
+
+test("history keys sort by recording time and name the run", () => {
+  const early = testCaseHistoryKey("demo", "login", "2026-09-01T09:05:03.007Z", "run-b");
+  const late = testCaseHistoryKey("demo", "login", "2026-09-10T00:00:00.000Z", "run-a");
+  assert.equal(early, "projects/demo/test-case-history/login/20260901T090503007Z-run-b.json");
+  assert.ok(early < late);
+  // A run id that isn't safe in a key is replaced, not copied into the path.
+  const unsafe = testCaseHistoryKey("demo", "login", "2026-09-01T00:00:00.000Z", "../other");
+  assert.match(unsafe, /^projects\/demo\/test-case-history\/login\/20260901T000000000Z-[0-9a-f]{8}\.json$/);
+});
+
+test("each write replaces the latest file and adds one history entry", async () => {
+  const store = memoryStore();
+  await putTestCaseResults(store, "demo", { caseSetId: "login", recordedAt: "2026-09-01T00:00:00.000Z", runId: "r1", results: [{ caseId: "a", status: "passed" }] });
+  const second = await putTestCaseResults(store, "demo", { caseSetId: "login", recordedAt: "2026-09-02T00:00:00.000Z", results: [{ caseId: "a", status: "failed" }] });
+  assert.equal(second.objectKey, "projects/demo/test-case-results/login.json");
+  assert.equal(JSON.parse(store.objects.get(second.objectKey)!).results[0].status, "failed");
+  const history = await store.list(testCaseHistoryPrefix("demo", "login"));
+  assert.equal(history.length, 2);
+  assert.ok(history.some((object) => object.key === second.historyKey));
+  assert.equal((await store.list("projects/demo/test-case-results/")).length, 1);
+});

package/src/storage/test-case-results.ts

@@ -0,0 +1,49 @@
+import { randomBytes } from "node:crypto";
+import type { ObjectStore } from "./object-store.js";
+import { projectPrefix } from "./keys.js";
+
+/**
+ * Where test case verdicts live.
+ *
+ * `latest` is the one file per case set every reader already knows; each
+ * write replaces it. `history` keeps one file per write beside it so the
+ * dashboard can show a case's pass/fail trail. History sits under its own
+ * prefix rather than inside `test-case-results/`: readers list that prefix
+ * and treat every JSON file in it as the latest verdicts for a case set.
+ */
+export function testCaseResultsKey(projectId: string, caseSetId: string): string {
+  return `${projectPrefix(projectId)}/test-case-results/${caseSetId}.json`;
+}
+
+export function testCaseHistoryPrefix(projectId: string, caseSetId?: string): string {
+  const base = `${projectPrefix(projectId)}/test-case-history/`;
+  return caseSetId ? `${base}${caseSetId}/` : base;
+}
+
+/**
+ * One history file name per write. It starts with the recording time in a
+ * fixed-width form so names sort oldest to newest, then the run id (or a
+ * random suffix) so two writes in the same millisecond never collide.
+ */
+export function testCaseHistoryKey(projectId: string, caseSetId: string, recordedAt: string, runId?: string): string {
+  const parsed = typeof recordedAt === "string" ? Date.parse(recordedAt) : Number.NaN;
+  const stamp = new Date(Number.isFinite(parsed) ? parsed : Date.now()).toISOString().replace(/[-:.]/g, "");
+  const suffix = typeof runId === "string" && /^[a-zA-Z0-9._-]+$/.test(runId) ? runId : randomBytes(4).toString("hex");
+  return `${testCaseHistoryPrefix(projectId, caseSetId)}${stamp}-${suffix}.json`;
+}
+
+/** Write a result set as the latest verdicts and as one more history entry. */
+export async function putTestCaseResults(
+  store: ObjectStore,
+  projectId: string,
+  record: { caseSetId: string; recordedAt: string; runId?: string } & Record<string, unknown>,
+): Promise<{ objectKey: string; historyKey: string }> {
+  const body = JSON.stringify(record, null, 2) + "\n";
+  const objectKey = testCaseResultsKey(projectId, record.caseSetId);
+  const historyKey = testCaseHistoryKey(projectId, record.caseSetId, record.recordedAt, record.runId);
+  // History first: if the second write fails the latest file is unchanged,
+  // rather than showing a verdict that never reached the history.
+  await store.put(historyKey, body, "application/json");
+  await store.put(objectKey, body, "application/json");
+  return { objectKey, historyKey };
+}

package/src/vendor/byok.ts

@@ -0,0 +1,371 @@
+// VENDORED from theaiinc/arcana packages/byok/src/byok.ts by `node scripts/sync-byok.mjs` — change it there, then sync.
+// Bring-your-own-vault secret resolution: read a secret by reference from
+// the vault its owner already uses, without the Arcana app, a phone, or any
+// third-party SDK.
+//
+//   gcpsm://projects/P/secrets/S[/versions/V]   Google Secret Manager
+//   awssm://REGION/SECRET_ID[#field]            AWS Secrets Manager (#field reads one field of a JSON secret)
+//   keychain://SERVICE/ACCOUNT                  the machine's keychain (macOS Keychain, Linux Secret Service)
+//   env://VARIABLE                              an environment variable
+//
+// A reference is a pointer, not a credential, so it is safe to store and
+// commit. A value is returned to the caller only, never logged or put in an
+// error message.
+//
+// One file, no dependencies, erasable TypeScript only: Node runs it as is,
+// and other projects (the Bugmole CLI) vendor it verbatim.
+
+import { execFile } from "node:child_process";
+import { createHash, createHmac, createSign } from "node:crypto";
+
+export type SecretReference =
+  | { kind: "gcp"; project: string; secret: string; version: string }
+  | { kind: "aws"; region: string; secretId: string; field?: string }
+  | { kind: "keychain"; service: string; account: string }
+  | { kind: "env"; variable: string };
+
+export type ByokDeps = {
+  env?: Record<string, string | undefined>;
+  fetch?: typeof fetch;
+  /** Runs a program and returns its stdout; replaceable in tests. */
+  exec?: (file: string, args: string[], options?: { input?: string }) => Promise<string>;
+  platform?: string;
+  /**
+   * Environment prefixes AWS keys are read from, in order. A host can put a
+   * tenant's own read-only keys first (Bugmole Cloud uses VAULT_AWS_).
+   */
+  awsPrefixes?: string[];
+  /** Name of an environment variable holding a Google service account's JSON key. */
+  googleKeyVariable?: string;
+  /** Allow the aws, gcloud, security and secret-tool CLIs (default true). */
+  allowCli?: boolean;
+};
+
+export function parseReference(value: unknown): SecretReference | null {
+  if (typeof value !== "string" || /[\r\n]/.test(value)) return null;
+  const text = value.trim();
+  let match = /^gcpsm:\/\/projects\/([^/]+)\/secrets\/([^/]+)(?:\/versions\/([^/]+))?$/.exec(text);
+  if (match) return { kind: "gcp", project: match[1], secret: match[2], version: match[3] ?? "latest" };
+  match = /^awssm:\/\/([a-z]{2}(?:-[a-z]+)+-\d)\/([^#]+?)(?:#([^#]+))?$/.exec(text);
+  if (match) return { kind: "aws", region: match[1], secretId: decodeURIComponent(match[2]), ...(match[3] ? { field: match[3] } : {}) };
+  match = /^keychain:\/\/([^/]+)\/([^/]+)$/.exec(text);
+  if (match) return { kind: "keychain", service: match[1], account: match[2] };
+  match = /^env:\/\/([A-Za-z_][A-Za-z0-9_]*)$/.exec(text);
+  if (match) return { kind: "env", variable: match[1] };
+  return null;
+}
+
+export function formatReference(reference: SecretReference): string {
+  switch (reference.kind) {
+    case "gcp": return `gcpsm://projects/${reference.project}/secrets/${reference.secret}/versions/${reference.version}`;
+    case "aws": return `awssm://${reference.region}/${reference.secretId}${reference.field ? `#${reference.field}` : ""}`;
+    case "keychain": return `keychain://${reference.service}/${reference.account}`;
+    case "env": return `env://${reference.variable}`;
+  }
+}
+
+export const SOURCE_NAME: Record<SecretReference["kind"], string> = {
+  gcp: "Google Secret Manager",
+  aws: "AWS Secrets Manager",
+  keychain: "this machine's keychain",
+  env: "an environment variable",
+};
+
+function defaultExec(file: string, args: string[], options?: { input?: string }): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(file, args, { maxBuffer: 1024 * 1024 }, (error, stdout) => (error ? reject(error) : resolve(String(stdout))));
+    child.stdin?.end(options?.input);
+  });
+}
+
+function execOf(deps: ByokDeps): NonNullable<ByokDeps["exec"]> {
+  if (deps.allowCli === false) return async (file) => { throw new Error(`${file} isn't available here`); };
+  return deps.exec ?? defaultExec;
+}
+
+// ---------- the machine's keychain ----------
+
+type Keychain = Extract<SecretReference, { kind: "keychain" }>;
+
+const quoted = (text: string) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+async function readKeychain(reference: Keychain, deps: ByokDeps): Promise<string> {
+  const exec = execOf(deps);
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "linux") {
+    throw new Error("This machine has no supported keychain (macOS Keychain, or secret-tool on Linux)");
+  }
+  try {
+    if (platform === "darwin") return (await exec("security", ["find-generic-password", "-s", reference.service, "-a", reference.account, "-w"])).replace(/\n$/, "");
+    return await exec("secret-tool", ["lookup", "service", reference.service, "account", reference.account]);
+  } catch {
+    throw new Error(`No keychain entry ${formatReference(reference)} on this machine`);
+  }
+}
+
+/** Stores a value in the machine's keychain, replacing any earlier one. The value goes in on stdin, never in a command's arguments. */
+export async function writeKeychain(reference: Keychain, value: string, label: string, deps: ByokDeps = {}): Promise<void> {
+  const exec = execOf(deps);
+  const platform = deps.platform ?? process.platform;
+  if (platform === "darwin") {
+    // `security add-generic-password -w VALUE` would show the value in the
+    // process list; its interactive mode reads the same command from stdin.
+    await exec("security", ["-i"], {
+      input: `add-generic-password -U -s ${quoted(reference.service)} -a ${quoted(reference.account)} -l ${quoted(label)} -w ${quoted(value)}\n`,
+    });
+    return;
+  }
+  if (platform === "linux") {
+    await exec("secret-tool", ["store", "--label", label, "service", reference.service, "account", reference.account], { input: value });
+    return;
+  }
+  throw new Error("This machine has no supported keychain (macOS Keychain, or secret-tool on Linux)");
+}
+
+export async function deleteKeychain(reference: Keychain, deps: ByokDeps = {}): Promise<boolean> {
+  const exec = execOf(deps);
+  const platform = deps.platform ?? process.platform;
+  try {
+    if (platform === "darwin") await exec("security", ["delete-generic-password", "-s", reference.service, "-a", reference.account]);
+    else if (platform === "linux") await exec("secret-tool", ["clear", "service", reference.service, "account", reference.account]);
+    else return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Whether a keychain entry exists, without reading its value. */
+export async function keychainHas(reference: Keychain, deps: ByokDeps = {}): Promise<boolean> {
+  const exec = execOf(deps);
+  const platform = deps.platform ?? process.platform;
+  try {
+    // Without -w macOS prints the entry's attributes, not its value.
+    if (platform === "darwin") await exec("security", ["find-generic-password", "-s", reference.service, "-a", reference.account]);
+    else if (platform === "linux") {
+      const found = await exec("secret-tool", ["search", "service", reference.service, "account", reference.account]);
+      if (!found.trim()) return false;
+    } else return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------- AWS Secrets Manager ----------
+
+export type AwsCredentials = { accessKeyId: string; secretAccessKey: string; sessionToken?: string };
+
+const sha256Hex = (value: string) => createHash("sha256").update(value).digest("hex");
+const hmac = (key: string | Buffer, value: string) => createHmac("sha256", key).update(value).digest();
+
+/** AWS Signature Version 4 for a JSON POST. */
+export function signAws(params: { credentials: AwsCredentials; region: string; service: string; url: string; headers: Record<string, string>; body: string; now?: Date }): Record<string, string> {
+  const now = params.now ?? new Date();
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+  const date = amzDate.slice(0, 8);
+  const url = new URL(params.url);
+  const headers: Record<string, string> = {
+    ...Object.fromEntries(Object.entries(params.headers).map(([key, value]) => [key.toLowerCase(), value.trim()])),
+    host: url.host,
+    "x-amz-date": amzDate,
+    ...(params.credentials.sessionToken ? { "x-amz-security-token": params.credentials.sessionToken } : {}),
+  };
+  const names = Object.keys(headers).sort();
+  const canonical = [
+    "POST",
+    url.pathname || "/",
+    url.searchParams.toString(),
+    names.map((name) => `${name}:${headers[name]}\n`).join(""),
+    names.join(";"),
+    sha256Hex(params.body),
+  ].join("\n");
+  const scope = `${date}/${params.region}/${params.service}/aws4_request`;
+  const toSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256Hex(canonical)].join("\n");
+  const key = hmac(hmac(hmac(hmac(`AWS4${params.credentials.secretAccessKey}`, date), params.region), params.service), "aws4_request");
+  const signature = createHmac("sha256", key).update(toSign).digest("hex");
+  const { host: _host, ...rest } = headers;
+  return {
+    ...rest,
+    authorization: `AWS4-HMAC-SHA256 Credential=${params.credentials.accessKeyId}/${scope}, SignedHeaders=${names.join(";")}, Signature=${signature}`,
+  };
+}
+
+/** AWS keys from the configured environment prefixes, then the AWS CLI (profiles, SSO). */
+export async function awsCredentials(deps: ByokDeps = {}): Promise<AwsCredentials> {
+  const env = deps.env ?? process.env;
+  for (const prefix of deps.awsPrefixes ?? ["AWS_"]) {
+    const accessKeyId = env[`${prefix}ACCESS_KEY_ID`];
+    const secretAccessKey = env[`${prefix}SECRET_ACCESS_KEY`];
+    if (accessKeyId && secretAccessKey) {
+      const sessionToken = env[`${prefix}SESSION_TOKEN`];
+      return { accessKeyId, secretAccessKey, ...(sessionToken ? { sessionToken } : {}) };
+    }
+  }
+  try {
+    const parsed = JSON.parse(await execOf(deps)("aws", ["configure", "export-credentials", "--format", "process"])) as { AccessKeyId?: string; SecretAccessKey?: string; SessionToken?: string };
+    if (parsed.AccessKeyId && parsed.SecretAccessKey) {
+      return { accessKeyId: parsed.AccessKeyId, secretAccessKey: parsed.SecretAccessKey, ...(parsed.SessionToken ? { sessionToken: parsed.SessionToken } : {}) };
+    }
+  } catch {
+    // Reported below.
+  }
+  throw new Error("No AWS credentials: set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with the AWS CLI");
+}
+
+async function readAws(reference: Extract<SecretReference, { kind: "aws" }>, deps: ByokDeps): Promise<string> {
+  const credentials = await awsCredentials(deps);
+  const url = `https://secretsmanager.${reference.region}.amazonaws.com/`;
+  const body = JSON.stringify({ SecretId: reference.secretId });
+  const headers = signAws({
+    credentials,
+    region: reference.region,
+    service: "secretsmanager",
+    url,
+    headers: { "content-type": "application/x-amz-json-1.1", "x-amz-target": "secretsmanager.GetSecretValue" },
+    body,
+  });
+  const reply = await (deps.fetch ?? fetch)(url, { method: "POST", headers, body });
+  if (!reply.ok) throw new Error(`AWS Secrets Manager refused ${formatReference(reference)} (${reply.status}): ${await errorText(reply)}`);
+  const payload = await reply.json() as { SecretString?: string; SecretBinary?: string };
+  const text = payload.SecretString ?? (payload.SecretBinary ? Buffer.from(payload.SecretBinary, "base64").toString("utf8") : undefined);
+  if (text === undefined) throw new Error(`${formatReference(reference)} has no value`);
+  return reference.field ? jsonField(text, reference.field, formatReference(reference)) : text;
+}
+
+// ---------- Google Secret Manager ----------
+
+type ServiceAccountKey = { client_email?: string; private_key?: string; token_uri?: string };
+
+async function serviceAccountToken(key: ServiceAccountKey, doFetch: typeof fetch): Promise<string> {
+  if (!key.client_email || !key.private_key) throw new Error("The service account key needs client_email and private_key");
+  const now = Math.floor(Date.now() / 1000);
+  const tokenUri = key.token_uri ?? "https://oauth2.googleapis.com/token";
+  const encode = (value: object) => Buffer.from(JSON.stringify(value)).toString("base64url");
+  const unsigned = `${encode({ alg: "RS256", typ: "JWT" })}.${encode({
+    iss: key.client_email,
+    scope: "https://www.googleapis.com/auth/cloud-platform",
+    aud: tokenUri,
+    iat: now,
+    exp: now + 600,
+  })}`;
+  const signature = createSign("RSA-SHA256").update(unsigned).sign(key.private_key).toString("base64url");
+  const reply = await doFetch(tokenUri, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: `${unsigned}.${signature}` }).toString(),
+  });
+  if (!reply.ok) throw new Error(`Google refused the service account (${reply.status}): ${await errorText(reply)}`);
+  const body = await reply.json() as { access_token?: string };
+  if (!body.access_token) throw new Error("Google returned no access token for the service account");
+  return body.access_token;
+}
+
+/** A Google access token: a service account key, GOOGLE_OAUTH_ACCESS_TOKEN, or the signed-in gcloud CLI. */
+export async function googleAccessToken(deps: ByokDeps = {}): Promise<string> {
+  const env = deps.env ?? process.env;
+  const keyJson = deps.googleKeyVariable ? env[deps.googleKeyVariable] : undefined;
+  if (keyJson) {
+    let key: ServiceAccountKey;
+    try {
+      key = JSON.parse(keyJson) as ServiceAccountKey;
+    } catch {
+      throw new Error(`${deps.googleKeyVariable} isn't a service account key (JSON)`);
+    }
+    return serviceAccountToken(key, deps.fetch ?? fetch);
+  }
+  if (env.GOOGLE_OAUTH_ACCESS_TOKEN) return env.GOOGLE_OAUTH_ACCESS_TOKEN;
+  try {
+    const token = (await execOf(deps)("gcloud", ["auth", "print-access-token"])).trim();
+    if (token) return token;
+  } catch {
+    // Reported below.
+  }
+  throw new Error("No Google credentials: sign in with `gcloud auth login`, or set GOOGLE_OAUTH_ACCESS_TOKEN");
+}
+
+async function readGoogle(reference: Extract<SecretReference, { kind: "gcp" }>, deps: ByokDeps): Promise<string> {
+  const token = await googleAccessToken(deps);
+  const url = `https://secretmanager.googleapis.com/v1/projects/${encodeURIComponent(reference.project)}/secrets/${encodeURIComponent(reference.secret)}/versions/${encodeURIComponent(reference.version)}:access`;
+  const reply = await (deps.fetch ?? fetch)(url, { headers: { authorization: `Bearer ${token}` } });
+  if (!reply.ok) throw new Error(`Google Secret Manager refused ${formatReference(reference)} (${reply.status}): ${await errorText(reply)}`);
+  const body = await reply.json() as { payload?: { data?: string } };
+  if (!body.payload?.data) throw new Error(`${formatReference(reference)} has no value`);
+  return Buffer.from(body.payload.data, "base64").toString("utf8");
+}
+
+// ---------- shared ----------
+
+async function errorText(reply: Response): Promise<string> {
+  const text = (await reply.text().catch(() => "")).slice(0, 300);
+  try {
+    const parsed = JSON.parse(text) as { message?: string; Message?: string; error?: { message?: string } };
+    return parsed.error?.message ?? parsed.message ?? parsed.Message ?? text;
+  } catch {
+    return text;
+  }
+}
+
+function jsonField(text: string, field: string, label: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`${label} isn't JSON, so it has no field "${field}"`);
+  }
+  const value = (parsed as Record<string, unknown> | null)?.[field];
+  if (typeof value !== "string" && typeof value !== "number") throw new Error(`${label} has no text field "${field}"`);
+  return String(value);
+}
+
+/** Reads the value a reference points at. Errors name the reference, never a value. */
+export async function resolveReference(reference: SecretReference, deps: ByokDeps = {}): Promise<string> {
+  switch (reference.kind) {
+    case "env": {
+      const value = (deps.env ?? process.env)[reference.variable];
+      if (value === undefined || value === "") throw new Error(`${reference.variable} is not set`);
+      return value;
+    }
+    case "keychain": return readKeychain(reference, deps);
+    case "aws": return readAws(reference, deps);
+    case "gcp": return readGoogle(reference, deps);
+  }
+}
+
+export type Readiness = { ready: boolean; detail: string };
+
+/**
+ * Whether a reference can probably be read here, without reading it: an env
+ * variable or keychain entry exists, or credentials for the cloud vault do.
+ */
+export async function readiness(reference: SecretReference, deps: ByokDeps = {}): Promise<Readiness> {
+  const env = deps.env ?? process.env;
+  switch (reference.kind) {
+    case "env":
+      return env[reference.variable] ? { ready: true, detail: `Read from ${reference.variable}` } : { ready: false, detail: `${reference.variable} is not set` };
+    case "keychain":
+      return (await keychainHas(reference, deps))
+        ? { ready: true, detail: "In this machine's keychain" }
+        : { ready: false, detail: `No keychain entry ${formatReference(reference)}` };
+    case "aws":
+      try {
+        await awsCredentials({ ...deps, allowCli: false });
+        return { ready: true, detail: "AWS keys found; read when it's used" };
+      } catch {
+        // Checking the AWS CLI's profile could start a sign-in, so it isn't.
+        return deps.allowCli === false
+          ? { ready: false, detail: "No AWS keys" }
+          : { ready: true, detail: "No AWS keys in the environment; the AWS CLI's profile is tried when it's used" };
+      }
+    case "gcp": {
+      if ((deps.googleKeyVariable && env[deps.googleKeyVariable]) || env.GOOGLE_OAUTH_ACCESS_TOKEN) return { ready: true, detail: "Google credentials found; read when it's used" };
+      try {
+        const account = (await execOf(deps)("gcloud", ["auth", "list", "--filter=status:ACTIVE", "--format=value(account)"])).trim();
+        if (account) return { ready: true, detail: `Signed in to gcloud as ${account}; read when it's used` };
+      } catch {
+        // Reported below.
+      }
+      return { ready: false, detail: "No Google credentials: run gcloud auth login, or set GOOGLE_OAUTH_ACCESS_TOKEN" };
+    }
+  }
+}