@bugmole/cli 0.4.0 → 0.6.0

package/src/runtime/site-discovery.ts

@@ -14,7 +14,7 @@ import { launcherFor } from "./browser-matrix.js";
 
 export type DiscoveryEvent = {
   at: string;
-  kind: "visit" | "click" | "form" | "page" | "flows" | "done" | "skip" | "error";
+  kind: "visit" | "click" | "form" | "page" | "flows" | "done" | "skip" | "error" | "limit";
   text: string;
   route?: string;
 };
@@ -29,8 +29,15 @@ export type DiscoveredPage = {
   heading?: string;
   /** The link labels a visitor clicks, from the home page, to reach this page. */
   path: string[];
-  links: Array<{ label: string; route: string }>;
+  /** `menu` names the button that must be opened first to see the link. */
+  links: Array<{ label: string; route: string; menu?: string }>;
   forms: DiscoveredForm[];
+  /**
+   * Visible buttons outside forms ("Continue with Aegis", "Add to cart"), by
+   * name. Discovery never presses them; they tell AI exploration what is
+   * really on the page, so it doesn't invent controls.
+   */
+  controls?: string[];
 };
 
 export type DiscoveredFlow = {
@@ -45,13 +52,45 @@ export type DiscoveredFlow = {
   steps: string[];
 };
 
+/**
+ * The bounds this exploration ran with and whether they cut it short. A crawl
+ * that stops at a limit has seen part of the app, and says how much it left.
+ */
+export type DiscoveryLimits = {
+  maxPages: number;
+  maxDepth: number;
+  /** It stopped with pages still queued because it reached maxPages. */
+  stoppedAtPageLimit: boolean;
+  /** Pages it found links to but never opened: queued past maxPages, or deeper than maxDepth. */
+  notFollowed: string[];
+};
+
 export type DiscoveryResult = {
   baseUrl: string;
   pages: DiscoveredPage[];
   flows: DiscoveredFlow[];
   events: DiscoveryEvent[];
+  limits?: DiscoveryLimits;
 };
 
+/** Discovery's bounds when nobody sets them: the Free plan's. */
+export const DEFAULT_DISCOVERY_LIMITS = { maxPages: 12, maxDepth: 2 } as const;
+
+/**
+ * Limits from the environment of the machine that explores
+ * (BUGMOLE_DISCOVERY_MAX_PAGES / BUGMOLE_DISCOVERY_MAX_DEPTH), for a project's
+ * own worker. Anything not a positive whole number is ignored.
+ */
+export function discoveryLimitsFromEnv(env: Record<string, string | undefined> = process.env): { maxPages?: number; maxDepth?: number } {
+  const read = (name: string) => {
+    const value = Number(env[name]);
+    return Number.isInteger(value) && value > 0 ? value : undefined;
+  };
+  const maxPages = read("BUGMOLE_DISCOVERY_MAX_PAGES");
+  const maxDepth = read("BUGMOLE_DISCOVERY_MAX_DEPTH");
+  return { ...(maxPages ? { maxPages } : {}), ...(maxDepth ? { maxDepth } : {}) };
+}
+
 export type DiscoveryOptions = {
   maxPages?: number;
   maxDepth?: number;
@@ -62,10 +101,21 @@ export type DiscoveryOptions = {
    * on the app gentle. Defaults to 600ms (BUGMOLE_DISCOVERY_DWELL_MS).
    */
   dwellMs?: number;
+  /**
+   * A Playwright storage-state file to start from, for exploring an app that
+   * needs sign-in. Links that sign out are already never followed.
+   */
+  storageState?: string;
+  /**
+   * Discovered flows open each page at its address instead of repeating the
+   * clicks that reached it. Use it for apps whose navigation hides behind a
+   * menu on phones, where the desktop clicks would not exist.
+   */
+  openEachPage?: boolean;
   onEvent?: (event: DiscoveryEvent, snapshot: DiscoveryResult) => void | Promise<void>;
 };
 
-const UNSAFE_LINK = /\b(log ?out|sign ?out|delete|remove|destroy|unsubscribe|deactivate|cancel (?:my )?(?:account|subscription))\b/i;
+export const UNSAFE_LINK = /\b(log ?out|sign ?out|delete|remove|destroy|unsubscribe|deactivate|cancel (?:my )?(?:account|subscription))\b/i;
 
 export function slugify(value: string): string {
   return value.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "home";
@@ -97,7 +147,7 @@ function sampleValue(field: DiscoveredField): string {
   if (hint.includes("email")) return "qa@example.com";
   if (hint.includes("phone") || field.type === "tel") return "+1 555 010 0100";
   if (field.type === "number") return "1";
-  if (field.type === "url" || hint.includes("website")) return "https://example.com";
+  if (field.type === "url" || /\b(url|website|link)\b/.test(hint)) return "https://example.com";
   if (hint.includes("name")) return "Bugmole";
   return "Test";
 }
@@ -105,7 +155,11 @@ function sampleValue(field: DiscoveredField): string {
 const FILLABLE = new Set(["text", "email", "password", "tel", "number", "url", "search", "textarea"]);
 
 /** Flows a visitor could run for each discovered page and form. */
-export function flowsFor(baseUrl: string, pages: readonly DiscoveredPage[]): DiscoveredFlow[] {
+export function flowsFor(
+  baseUrl: string,
+  pages: readonly DiscoveredPage[],
+  options: { openEachPage?: boolean } = {},
+): DiscoveredFlow[] {
   const flows: DiscoveredFlow[] = [];
   const used = new Set<string>();
   const uniqueId = (base: string) => {
@@ -114,22 +168,27 @@ export function flowsFor(baseUrl: string, pages: readonly DiscoveredPage[]): Dis
     used.add(id);
     return id;
   };
-  const header = (name: string) => `url: ${baseUrl}\nname: ${JSON.stringify(name)}\n---\n`;
-  const pathSteps = (page: DiscoveredPage) => page.path.map((label) => ({ tapOn: label }));
+  // A query on the base URL is app context (a selected project, say) that
+  // every page needs, so each opened page carries it.
+  const context = new URL(baseUrl).search;
+  const header = (name: string, page: DiscoveredPage) =>
+    `url: ${options.openEachPage ? `${new URL(page.route, baseUrl).origin}${page.route}${context}` : baseUrl}\nname: ${JSON.stringify(name)}\n---\n`;
+  const pathSteps = (page: DiscoveredPage) => (options.openEachPage ? [] : page.path.map((label) => ({ tapOn: label })));
 
   for (const page of pages) {
     const pageName = page.route === "/" ? "Open the home page" : `Visit ${describeRoute(page)}`;
     const landmark = page.heading ?? page.title;
     if (landmark) {
       const id = uniqueId(`discovered-${slugify(page.route === "/" ? "home" : describeRoute(page))}`);
-      const steps: unknown[] = ["launchApp", ...pathSteps(page), { assertVisible: landmark }];
+      // Then the page itself: it fits the screen and its links lead somewhere.
+      const steps: unknown[] = ["launchApp", ...pathSteps(page), { assertVisible: landmark }, "assertLayout", "assertLinks"];
       flows.push({
         id,
         name: pageName,
         kind: "page",
         route: page.route,
         file: `flows/discovered/${id}.yaml`,
-        content: header(pageName) + YAML.stringify(steps),
+        content: header(pageName, page) + YAML.stringify(steps),
         steps: steps.map(stepLabel),
       });
     }
@@ -141,7 +200,9 @@ export function flowsFor(baseUrl: string, pages: readonly DiscoveredPage[]): Dis
       const steps: unknown[] = [
         "launchApp",
         ...pathSteps(page),
-        ...fields.flatMap((field) => [{ tapOn: field.label }, { inputText: sampleValue(field) }]),
+        // Cleared first: a field may already hold a value (an app's own URL,
+        // say), and typing into the middle of it makes nonsense.
+        ...fields.flatMap((field) => [{ tapOn: field.label }, "eraseText", { inputText: sampleValue(field) }]),
         // Discovery never submits; the flow proves the form is ready to.
         ...(form.submit ? [{ assertClickable: form.submit }] : []),
       ];
@@ -151,7 +212,7 @@ export function flowsFor(baseUrl: string, pages: readonly DiscoveredPage[]): Dis
         kind: "form",
         route: page.route,
         file: `flows/discovered/${id}.yaml`,
-        content: header(name) + YAML.stringify(steps),
+        content: header(name, page) + YAML.stringify(steps),
         steps: steps.map(stepLabel),
       });
     }
@@ -160,7 +221,13 @@ export function flowsFor(baseUrl: string, pages: readonly DiscoveredPage[]): Dis
 }
 
 function stepLabel(step: unknown): string {
-  if (typeof step === "string") return step === "launchApp" ? "Open the app" : step;
+  if (typeof step === "string") {
+    if (step === "launchApp") return "Open the app";
+    if (step === "assertLayout") return "Nothing spills off the screen";
+    if (step === "assertLinks") return "Every link on the site works";
+    if (step === "eraseText") return "Clear the field";
+    return step;
+  }
   const [[key, value]] = Object.entries(step as Record<string, unknown>);
   const text = String(value);
   switch (key) {
@@ -186,7 +253,10 @@ const pageProbe = `() => {
   for (const link of document.querySelectorAll("a[href]")) {
     if (!visible(link)) continue;
     const label = text(link) || link.getAttribute("aria-label") || "";
-    if (label && label.length <= 60) links.push({ label, href: link.href });
+    // Card-style links carry a title and a sentence; only whole paragraphs
+    // wrapped in a link are left out.
+    // A download (an export, a report file) isn't a page a visitor reads.
+    if (label && label.length <= 200) links.push({ label, href: link.href, ...(link.hasAttribute("download") ? { download: true } : {}) });
   }
   const labelOf = (field) => {
     const own = field.labels && field.labels[0] ? text(field.labels[0]) : "";
@@ -208,24 +278,106 @@ const pageProbe = `() => {
     const legend = form.getAttribute("aria-label") || (form.querySelector("legend, h1, h2, h3") ? text(form.querySelector("legend, h1, h2, h3")) : "");
     forms.push({ name: legend || submitText || "form", fields, submit: submitText || undefined });
   }
-  return { title: document.title, heading: heading ? text(heading) : undefined, links, forms };
+  const controls = [];
+  for (const control of document.querySelectorAll("button, [role=button], input[type=submit], input[type=button]")) {
+    if (!visible(control) || control.closest("form") || control.closest("a[href]")) continue;
+    const name = (text(control) || control.getAttribute("aria-label") || control.value || "").trim();
+    if (name && name.length <= 60 && !controls.includes(name)) controls.push(name);
+    if (controls.length >= 30) break;
+  }
+  return { title: document.title, heading: heading ? text(heading) : undefined, links, forms, controls };
 }`;
 
-type Probe = { title: string; heading?: string; links: Array<{ label: string; href: string }>; forms: DiscoveredForm[] };
+type Probe = { title: string; heading?: string; links: Array<{ label: string; href: string; download?: boolean }>; forms: DiscoveredForm[]; controls?: string[] };
 
 async function readPage(page: Page): Promise<Probe> {
   return page.evaluate((source: string) => (new Function(`return (${source})`)() as () => Probe)(), pageProbe);
 }
 
+/**
+ * Menus a person can open — a closed disclosure button (aria-expanded="false")
+ * such as an account menu — and the links inside each. Opening one only
+ * reveals links; it is closed again before moving on.
+ */
+async function linksInMenus(page: Page, known: ReadonlySet<string>): Promise<Array<{ menu: string; label: string; href: string }>> {
+  const found: Array<{ menu: string; label: string; href: string }> = [];
+  const startUrl = page.url();
+  const buttons = page.locator('button[aria-expanded="false"]');
+  const count = Math.min(await buttons.count(), 8);
+  const names: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const button = buttons.nth(index);
+    if (!(await button.isVisible().catch(() => false))) continue;
+    // The accessible name, exactly as getByRole matches it, from the
+    // accessibility tree itself.
+    const snapshot = await button.ariaSnapshot().catch(() => "");
+    const quoted = /^- button "((?:[^"\\]|\\.)*)"/.exec(snapshot.trim());
+    const name = quoted ? (JSON.parse(`"${quoted[1]}"`) as string) : "";
+    if (name && name.length <= 60 && !UNSAFE_LINK.test(name) && !names.includes(name)) names.push(name);
+  }
+  for (const name of names) {
+    const button = page.getByRole("button", { name, exact: true }).first();
+    try {
+      await button.click({ timeout: 3_000 });
+      await page.waitForTimeout(200);
+      if (page.url() !== startUrl) {
+        // Not a menu after all: put the page back and stop opening things.
+        await page.goto(startUrl, { waitUntil: "load" });
+        break;
+      }
+      for (const link of (await readPage(page)).links) {
+        if (!known.has(link.href) && !found.some((item) => item.href === link.href)) found.push({ menu: name, ...link });
+      }
+    } catch {
+      // A button that can't be pressed hides nothing we can reach.
+    } finally {
+      await page.keyboard.press("Escape").catch(() => undefined);
+      if ((await button.getAttribute("aria-expanded").catch(() => null)) === "true") await button.click({ timeout: 3_000 }).catch(() => undefined);
+    }
+  }
+  return found;
+}
+
+/** The first visible h1/h2, to tell when a client-side navigation has rendered. */
+async function currentHeading(page: Page): Promise<string | undefined> {
+  return (await readPage(page).catch(() => undefined))?.heading;
+}
+
+const SIGN_IN_WORDS = /\b(sign ?in|log ?in|welcome back)\b/i;
+const SIGN_IN_BUTTON = /^(continue|sign in|log in) with\b/i;
+
+function looksLikeSignIn(page: DiscoveredPage): boolean {
+  if (page.forms.some((form) => form.fields.some((field) => field.type === "password"))) return true;
+  if (SIGN_IN_WORDS.test(page.heading ?? "") || SIGN_IN_WORDS.test(page.title)) return true;
+  return Boolean(page.controls?.some((control) => SIGN_IN_BUTTON.test(control)));
+}
+
+/**
+ * The crawl stopped at a sign-in page: everything it could reach is a sign-in
+ * screen, so what lies behind it is unexplored. Discovery doesn't sign in on
+ * its own; the caller should say so rather than present the one page it saw
+ * as the whole app.
+ */
+export function stoppedAtSignIn(result: Pick<DiscoveryResult, "pages">): boolean {
+  return result.pages.length > 0 && result.pages.length <= 2 && result.pages.every(looksLikeSignIn);
+}
+
 export async function discoverSite(baseUrl: string, options: DiscoveryOptions = {}): Promise<DiscoveryResult> {
   const start = new URL(baseUrl);
   const root = `${start.origin}${start.pathname}`;
-  const maxPages = options.maxPages ?? 12;
-  const maxDepth = options.maxDepth ?? 2;
+  const maxPages = options.maxPages ?? DEFAULT_DISCOVERY_LIMITS.maxPages;
+  const maxDepth = options.maxDepth ?? DEFAULT_DISCOVERY_LIMITS.maxDepth;
   const timeout = options.navigationTimeoutMs ?? 15_000;
   const envDwell = Number(process.env.BUGMOLE_DISCOVERY_DWELL_MS);
   const dwellMs = options.dwellMs ?? (Number.isFinite(envDwell) && envDwell >= 0 ? envDwell : 600);
   const result: DiscoveryResult = { baseUrl: root, pages: [], flows: [], events: [] };
+  // The same link in a shared menu is skipped on every page; say so once.
+  const skipped = new Set<string>();
+  const skipOnce = async (text: string, route: string) => {
+    if (skipped.has(text)) return;
+    skipped.add(text);
+    await emit("skip", text, route);
+  };
   const emit = async (kind: DiscoveryEvent["kind"], text: string, route?: string) => {
     const event: DiscoveryEvent = { at: new Date().toISOString(), kind, text, ...(route ? { route } : {}) };
     result.events.push(event);
@@ -235,12 +387,17 @@ export async function discoverSite(baseUrl: string, options: DiscoveryOptions =
   const { type, channel } = launcherFor("chromium");
   const browser = await type.launch({ headless: options.headless ?? true, ...(channel ? { channel } : {}) });
   try {
-    const context = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+    const context = await browser.newContext({
+      viewport: { width: 1280, height: 800 },
+      ...(options.storageState ? { storageState: options.storageState } : {}),
+    });
     const page = await context.newPage();
     page.setDefaultTimeout(timeout);
     const seen = new Set<string>();
+    // Links seen on a page at the depth limit, so never queued.
+    const tooDeep = new Set<string>();
     // Breadth-first, so pages close to home are found first.
-    const queue: Array<{ route: string; path: string[]; parent?: string }> = [{ route: discoverableRoute(root, root) ?? "/", path: [] }];
+    const queue: Array<{ route: string; path: string[]; parent?: string; menu?: string }> = [{ route: discoverableRoute(root, root) ?? "/", path: [] }];
 
     while (queue.length > 0 && result.pages.length < maxPages) {
       const next = queue.shift()!;
@@ -249,30 +406,68 @@ export async function discoverSite(baseUrl: string, options: DiscoveryOptions =
       try {
         if (next.path.length === 0) {
           await emit("visit", "Visiting home page", next.route);
-          await page.goto(root, { waitUntil: "load" });
+          await page.goto(`${root}${start.search}`, { waitUntil: "load" });
         } else {
           // Reach the page the way a visitor would: from its parent, by clicking.
-          const parentUrl = new URL(next.parent ?? "/", root).toString();
+          const parentUrl = `${new URL(next.parent ?? "/", root).toString()}${start.search}`;
           if (discoverableRoute(page.url(), root) !== next.parent) await page.goto(parentUrl, { waitUntil: "load" });
           const label = next.path[next.path.length - 1];
+          const before = await currentHeading(page);
+          if (next.menu) {
+            await emit("click", `Opening “${next.menu}”`, next.route);
+            // A disclosure can remember being open (the dashboard's Advanced
+            // group does); clicking it then would close it and hide the link.
+            const menuButton = page.getByRole("button", { name: next.menu, exact: true }).first();
+            if ((await menuButton.getAttribute("aria-expanded").catch(() => null)) !== "true") await menuButton.click();
+          }
           await emit("click", `Clicking “${label}”`, next.route);
           await page.getByRole("link", { name: label, exact: true }).first().click();
+          // Apps that route on the client change the address and then render,
+          // some time after the click returns: wait for both, bounded.
+          await page.waitForURL((url) => discoverableRoute(url.toString(), root) !== next.parent, { timeout }).catch(() => undefined);
           await page.waitForLoadState("load").catch(() => undefined);
+          await page.waitForFunction(
+            ([source, previous]) => ((new Function(`return (${source})`)() as () => { heading?: string })().heading ?? "") !== previous,
+            [pageProbe, before ?? ""] as const,
+            { timeout: 5_000 },
+          ).catch(() => undefined);
           await page.waitForTimeout(250);
         }
-        const route = discoverableRoute(page.url(), root) ?? next.route;
+        const landed = discoverableRoute(page.url(), root);
+        if (!landed) {
+          // A same-origin link that hands off elsewhere (an OAuth or install
+          // redirect, say) is not a page of this app.
+          await emit("skip", `“${next.path[next.path.length - 1] ?? next.route}” leaves the app`, next.route);
+          continue;
+        }
+        const route = landed;
+        if (next.path.length > 0 && route === next.parent) {
+          await emit("skip", `“${next.path[next.path.length - 1]}” did not lead anywhere`, next.route);
+          continue;
+        }
         if (route !== next.route && seen.has(route)) continue;
         seen.add(route);
+        // A link to an API endpoint or a file opens JSON or a viewer, not a page of the app.
+        const contentType = await page.evaluate("document.contentType").then(String).catch(() => "text/html");
+        if (!/html/i.test(contentType)) {
+          await emit("skip", `“${next.path[next.path.length - 1] ?? route}” opens a file (${contentType}), not a page`, route);
+          continue;
+        }
         const probe = await readPage(page);
+        const inMenus = await linksInMenus(page, new Set(probe.links.map((link) => link.href)));
         const links: DiscoveredPage["links"] = [];
-        for (const link of probe.links) {
+        for (const link of [...probe.links, ...inMenus] as Array<{ label: string; href: string; menu?: string; download?: boolean }>) {
           const target = discoverableRoute(link.href, root);
           if (!target || target === route || links.some((existing) => existing.route === target)) continue;
-          if (UNSAFE_LINK.test(link.label)) {
-            await emit("skip", `Skipping “${link.label}” (it could change data)`, target);
+          if (UNSAFE_LINK.test(link.label) || UNSAFE_LINK.test(target.replace(/[/_-]+/g, " "))) {
+            await skipOnce(`Skipping “${link.label}” (it could change data)`, target);
+            continue;
+          }
+          if (link.download || /^\/api(\/|$)/.test(target)) {
+            await skipOnce(`Skipping “${link.label}” (it downloads a file or calls the API)`, target);
             continue;
           }
-          links.push({ label: link.label, route: target });
+          links.push({ label: link.label, route: target, ...(link.menu ? { menu: link.menu } : {}) });
         }
         const discovered: DiscoveredPage = {
           route,
@@ -282,6 +477,7 @@ export async function discoverSite(baseUrl: string, options: DiscoveryOptions =
           path: next.path,
           links,
           forms: probe.forms,
+          ...(probe.controls?.length ? { controls: probe.controls } : {}),
         };
         result.pages.push(discovered);
         await emit("page", `Found ${describeRoute(discovered)} (${links.length} link${links.length === 1 ? "" : "s"})`, route);
@@ -289,16 +485,39 @@ export async function discoverSite(baseUrl: string, options: DiscoveryOptions =
           await emit("form", `Found a form: ${form.name} (${form.fields.map((field) => field.label).join(", ")})`, route);
         }
         if (dwellMs > 0) await page.waitForTimeout(dwellMs);
-        if (next.path.length < maxDepth) {
+        if (next.path.length >= maxDepth) {
+          for (const link of links) tooDeep.add(link.route);
+        } else {
           for (const link of links) {
-            if (!seen.has(link.route)) queue.push({ route: link.route, path: [...next.path, link.label], parent: route });
+            if (!seen.has(link.route)) {
+              queue.push({
+                route: link.route,
+                // A flow replays the path as taps, so a menu's button is a step too.
+                path: [...next.path, ...(link.menu ? [link.menu] : []), link.label],
+                parent: route,
+                ...(link.menu ? { menu: link.menu } : {}),
+              });
+            }
           }
         }
       } catch (error) {
         await emit("error", `Could not open ${next.route}: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`, next.route);
       }
     }
-    result.flows = flowsFor(root, result.pages);
+    const opened = new Set(result.pages.map((found) => found.route));
+    const queued = [...new Set(queue.map((item) => item.route))].filter((route) => !seen.has(route) && !opened.has(route));
+    const notFollowed = [...new Set([...queued, ...tooDeep])].filter((route) => !opened.has(route) && !seen.has(route));
+    const stoppedAtPageLimit = result.pages.length >= maxPages && queued.length > 0;
+    result.limits = { maxPages, maxDepth, stoppedAtPageLimit, notFollowed };
+    if (notFollowed.length) {
+      await emit(
+        "limit",
+        stoppedAtPageLimit
+          ? `Stopped at the ${maxPages}-page limit; ${notFollowed.length} linked page${notFollowed.length === 1 ? " was" : "s were"} not opened`
+          : `${notFollowed.length} linked page${notFollowed.length === 1 ? " is" : "s are"} deeper than ${maxDepth} click${maxDepth === 1 ? "" : "s"} from home and ${notFollowed.length === 1 ? "was" : "were"} not opened`,
+      );
+    }
+    result.flows = flowsFor(`${root}${start.search}`, result.pages, { openEachPage: options.openEachPage });
     await emit("flows", `Discovered ${result.flows.length} flow${result.flows.length === 1 ? "" : "s"} across ${result.pages.length} page${result.pages.length === 1 ? "" : "s"}`);
     await emit("done", "Exploration complete");
     return result;

package/src/runtime/vault-federation.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { awsWebIdentityCredentials, googleFederatedToken, registryIdentityTokens } from "./vault-federation.js";
+
+test("asks the registry for a token for the runner's own job, with the audience given", async () => {
+  const seen: Array<{ url: string; auth: string | null }> = [];
+  const source = registryIdentityTokens((async (url: string, init?: RequestInit) => {
+    seen.push({ url, auth: new Headers(init?.headers).get("authorization") });
+    return new Response(JSON.stringify({ token: "jwt" }), { status: 200 });
+  }) as typeof fetch, "https://api.bugmole.com", "vrt_runner", { kind: "task", id: "task 1" });
+  assert.equal(await source("sts.amazonaws.com"), "jwt");
+  assert.deepEqual(seen, [{ url: "https://api.bugmole.com/api/runner/tasks/task%201/identity-token?audience=sts.amazonaws.com", auth: "Bearer vrt_runner" }]);
+  const off = registryIdentityTokens((async () => new Response("{}", { status: 503 })) as unknown as typeof fetch, "https://r", "t", { kind: "run", id: "r" });
+  await assert.rejects(off("x"), /doesn't issue identity tokens/);
+});
+
+test("refuses settings that aren't a Google provider or an IAM role, before asking anyone", async () => {
+  const never = async () => { throw new Error("not called"); };
+  await assert.rejects(googleFederatedToken({ provider: "my-pool", identityToken: never }), /must look like projects\/NUMBER/);
+  await assert.rejects(awsWebIdentityCredentials({ roleArn: "bugmole-reader", sessionName: "s", identityToken: never }), /must be an IAM role ARN/);
+});
+
+test("passes on what the cloud said when it refuses", async () => {
+  const google = googleFederatedToken({
+    provider: "projects/1/locations/global/workloadIdentityPools/p/providers/q",
+    identityToken: async () => "jwt",
+    fetch: (async () => new Response(JSON.stringify({ error: "invalid_grant", error_description: "The audience in ID Token does not match" }), { status: 400 })) as unknown as typeof fetch,
+  });
+  await assert.rejects(google, /refused Bugmole's token \(400\): The audience in ID Token does not match/);
+  const aws = awsWebIdentityCredentials({
+    roleArn: "arn:aws:iam::123456789012:role/r",
+    sessionName: "bugmole run/1",
+    identityToken: async () => "jwt",
+    fetch: (async () => new Response("<ErrorResponse><Error><Message>Not authorized to perform sts:AssumeRoleWithWebIdentity</Message></Error></ErrorResponse>", { status: 403 })) as unknown as typeof fetch,
+  });
+  await assert.rejects(aws, /\(403\): Not authorized to perform sts:AssumeRoleWithWebIdentity/);
+});

package/src/runtime/vault-federation.ts

@@ -0,0 +1,128 @@
+// A Bugmole Cloud runner reading a project's own vault without a stored key.
+// The registry signs a short-lived identity token for the runner's job
+// (registry-worker/identity/oidc.ts); the project's cloud trusts Bugmole as an
+// identity provider and trades that token for credentials limited to what
+// the project allowed:
+//
+//   Google: Workload Identity Federation (STS token exchange), optionally
+//           impersonating a service account
+//   AWS:    an IAM role assumed with AssumeRoleWithWebIdentity
+//
+// What to trust is configured with three non-secret project settings, kept
+// with the project's secrets: VAULT_GCP_WORKLOAD_PROVIDER (the provider's
+// resource name), VAULT_GCP_SERVICE_ACCOUNT (optional) and VAULT_AWS_ROLE_ARN.
+
+import type { AwsCredentials } from "../vendor/byok.js";
+
+/** Asks the registry for an identity token with this audience, for the runner's job. */
+export type IdentityTokenSource = (audience: string) => Promise<string>;
+
+export function registryIdentityTokens(doFetch: typeof fetch, registryUrl: string, token: string, job: { kind: "run" | "task"; id: string }): IdentityTokenSource {
+  return async (audience) => {
+    const reply = await doFetch(`${registryUrl}/api/runner/${job.kind}s/${encodeURIComponent(job.id)}/identity-token?audience=${encodeURIComponent(audience)}`, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    if (reply.status === 503) throw new Error("This Bugmole registry doesn't issue identity tokens");
+    if (!reply.ok) throw new Error(`The registry refused an identity token (${reply.status})`);
+    const body = await reply.json() as { token?: unknown };
+    if (typeof body.token !== "string") throw new Error("The registry returned no identity token");
+    return body.token;
+  };
+}
+
+async function failure(reply: Response, what: string): Promise<Error> {
+  const text = (await reply.text().catch(() => "")).slice(0, 400);
+  let detail = text;
+  try {
+    const parsed = JSON.parse(text) as { error_description?: string; error?: { message?: string } | string };
+    detail = parsed.error_description ?? (typeof parsed.error === "string" ? parsed.error : parsed.error?.message) ?? text;
+  } catch {
+    // Not JSON (AWS answers in XML).
+    detail = /<Message>([^<]*)<\/Message>/.exec(text)?.[1] ?? text;
+  }
+  return new Error(`${what} (${reply.status}): ${detail}`);
+}
+
+/** A Workload Identity provider's resource name, as Google shows it. */
+const PROVIDER = /^projects\/\d+\/locations\/global\/workloadIdentityPools\/[a-z0-9-]+\/providers\/[a-z0-9-]+$/;
+
+/**
+ * A Google access token for the project's Workload Identity provider: the
+ * federated token itself, or a service account's when one is named.
+ */
+export async function googleFederatedToken(options: {
+  provider: string;
+  serviceAccount?: string;
+  identityToken: IdentityTokenSource;
+  fetch?: typeof fetch;
+}): Promise<string> {
+  const doFetch = options.fetch ?? fetch;
+  const provider = options.provider.replace(/^\/\/iam\.googleapis\.com\//, "");
+  if (!PROVIDER.test(provider)) {
+    throw new Error("VAULT_GCP_WORKLOAD_PROVIDER must look like projects/NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER");
+  }
+  const audience = `//iam.googleapis.com/${provider}`;
+  const subjectToken = await options.identityToken(audience);
+  const exchanged = await doFetch("https://sts.googleapis.com/v1/token", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      grantType: "urn:ietf:params:oauth:grant-type:token-exchange",
+      audience,
+      scope: "https://www.googleapis.com/auth/cloud-platform",
+      requestedTokenType: "urn:ietf:params:oauth:token-type:access_token",
+      subjectTokenType: "urn:ietf:params:oauth:token-type:jwt",
+      subjectToken,
+    }),
+  });
+  if (!exchanged.ok) throw await failure(exchanged, "Google's Workload Identity Federation refused Bugmole's token");
+  const federated = (await exchanged.json() as { access_token?: string }).access_token;
+  if (!federated) throw new Error("Google's token exchange returned no access token");
+  if (!options.serviceAccount) return federated;
+  const impersonated = await doFetch(
+    `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${encodeURIComponent(options.serviceAccount)}:generateAccessToken`,
+    {
+      method: "POST",
+      headers: { authorization: `Bearer ${federated}`, "content-type": "application/json" },
+      body: JSON.stringify({ scope: ["https://www.googleapis.com/auth/cloud-platform"], lifetime: "600s" }),
+    },
+  );
+  if (!impersonated.ok) throw await failure(impersonated, `Google refused impersonating ${options.serviceAccount}`);
+  const token = (await impersonated.json() as { accessToken?: string }).accessToken;
+  if (!token) throw new Error("Google returned no service account token");
+  return token;
+}
+
+/** Temporary AWS credentials for the project's role, assumed with Bugmole's token. */
+export async function awsWebIdentityCredentials(options: {
+  roleArn: string;
+  sessionName: string;
+  identityToken: IdentityTokenSource;
+  fetch?: typeof fetch;
+}): Promise<AwsCredentials> {
+  if (!/^arn:aws[a-z-]*:iam::\d{12}:role\/[\w+=,.@/-]+$/.test(options.roleArn)) {
+    throw new Error("VAULT_AWS_ROLE_ARN must be an IAM role ARN (arn:aws:iam::ACCOUNT:role/NAME)");
+  }
+  const webIdentityToken = await options.identityToken("sts.amazonaws.com");
+  // AssumeRoleWithWebIdentity is authorized by the token itself: no signature.
+  const reply = await (options.fetch ?? fetch)("https://sts.amazonaws.com/", {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      Action: "AssumeRoleWithWebIdentity",
+      Version: "2011-06-15",
+      RoleArn: options.roleArn,
+      RoleSessionName: options.sessionName.replace(/[^\w+=,.@-]/g, "-").slice(0, 64),
+      WebIdentityToken: webIdentityToken,
+      DurationSeconds: "900",
+    }).toString(),
+  });
+  if (!reply.ok) throw await failure(reply, `AWS refused assuming ${options.roleArn} with Bugmole's token`);
+  const xml = await reply.text();
+  const field = (name: string) => new RegExp(`<${name}>([^<]+)</${name}>`).exec(xml)?.[1];
+  const accessKeyId = field("AccessKeyId");
+  const secretAccessKey = field("SecretAccessKey");
+  const sessionToken = field("SessionToken");
+  if (!accessKeyId || !secretAccessKey || !sessionToken) throw new Error("AWS returned no credentials for the role");
+  return { accessKeyId, secretAccessKey, sessionToken };
+}