akeso-check 0.1.0

package/src/lifecycle.mjs

@@ -0,0 +1,147 @@
+import { makeEvent, scenarios, signPayload } from "./stripe-events.mjs";
+
+/* Delivers the lifecycle scenarios to a running app and grades what its own
+ * billing entitlement says after each one.
+ *
+ * Discipline carried from the product-care engine: a delivery failure is OUR
+ * problem (server down, connection refused) and produces "could not test",
+ * never a failing grade for the app. Only the app's own answer to "is this
+ * person entitled?" can pass or fail a scenario.
+ */
+
+async function deliver(webhookUrl, event, webhookSecret) {
+  const rawBody = JSON.stringify(event);
+  const response = await fetch(webhookUrl, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "stripe-signature": signPayload(rawBody, webhookSecret),
+    },
+    body: rawBody,
+  });
+  return { status: response.status, ok: response.ok };
+}
+
+async function probe(probeUrl, account) {
+  /* A probe deployed on a public app carries a guard token in its URL, so the
+     account parameter joins with & when a query already exists. */
+  const joiner = probeUrl.includes("?") ? "&" : "?";
+  const response = await fetch(`${probeUrl}${joiner}account=${encodeURIComponent(account)}`);
+  if (!response.ok) throw new Error(`probe returned ${response.status}`);
+  const body = await response.json();
+  if (typeof body.billingEntitled !== "boolean") throw new Error("probe did not return billingEntitled");
+  return body.billingEntitled;
+}
+
+export async function runLifecycle({ webhookUrl, probeUrl, webhookSecret, accountFor, settleMs = 60, resetBeforeEach = false }) {
+  const results = [];
+
+  for (const scenario of scenarios({ accountFor })) {
+    /* On a shared real account, return it to "not entitled" before each
+       scenario by delivering a cancellation the app itself understands. On a
+       healthy app this makes every grant provable with one account; on an app
+       that ignores cancellations the reset is a no-op and the vacuous-pass
+       guard below reports not_provable — never a fake pass either way. */
+    if (resetBeforeEach) {
+      const reset = makeEvent({
+        type: "customer.subscription.deleted",
+        account: scenario.account,
+        created: scenario.resetCreated,
+        object: { status: "canceled" },
+      });
+      try {
+        await deliver(webhookUrl, reset, webhookSecret);
+        await new Promise((resolve) => setTimeout(resolve, settleMs));
+      } catch { /* the scenario's own delivery reports a dead server */ }
+    }
+
+    /* When scenarios are mapped onto a real shared account (a deployed app
+       where rows for made-up accounts cannot exist), a grant scenario that
+       starts with access already granted would pass vacuously. Same doctrine
+       as the sandbox driver: not provable is not a pass. */
+    if (accountFor && scenario.expect === true) {
+      let before = null;
+      try { before = await probe(probeUrl, scenario.account); } catch { /* main probe below reports it */ }
+      if (before === true) {
+        results.push({
+          id: scenario.id, name: scenario.name, expected: scenario.expect,
+          observed: null, deliveries: [], outcome: "not_provable",
+          critical: Boolean(scenario.critical), harnessError: null,
+          note: "not provable: access was already on when this scenario started",
+        });
+        continue;
+      }
+    }
+
+    const deliveries = [];
+    let harnessError = null;
+    try {
+      for (const event of scenario.events) {
+        deliveries.push({ type: event.type, ...(await deliver(webhookUrl, event, webhookSecret)) });
+        /* Small gap so file-backed fixtures and debounced handlers settle;
+           deployed serverless apps need more room than local fixtures. */
+        await new Promise((resolve) => setTimeout(resolve, settleMs));
+      }
+    } catch (error) {
+      harnessError = error?.message || String(error);
+    }
+
+    /* If the app rejected every event we sent, its state was never exercised
+       and the probe can only echo whatever was already true. That is not a
+       lifecycle result — for anyone. (Today's cause was our own signing bug;
+       an app-side verification bug shows up in the static findings instead.) */
+    if (!harnessError && deliveries.length && deliveries.every((d) => !d.ok)) {
+      harnessError = `every delivery was rejected (${deliveries.map((d) => d.status).join(", ")}); the lifecycle was never exercised`;
+    }
+
+    let observed = null;
+    let probeError = null;
+    if (!harnessError) {
+      try { observed = await probe(probeUrl, scenario.account); } catch (error) { probeError = error?.message || String(error); }
+    }
+
+    const graded = scenario.expect !== null && !harnessError && !probeError;
+    results.push({
+      id: scenario.id,
+      name: scenario.name,
+      expected: scenario.expect,
+      observed,
+      deliveries,
+      outcome: harnessError || probeError
+        ? "could_not_test"          /* our fault, never the app's */
+        : scenario.expect === null
+          ? "reported"              /* refund policy: shown, not graded */
+          : observed === scenario.expect ? "pass" : "fail",
+      critical: Boolean(scenario.critical),
+      harnessError: harnessError || probeError || null,
+    });
+  }
+
+  return { results, grade: gradeOf(results), scenarioCount: results.length };
+}
+
+/* One letter a founder understands. F is reserved for the failure that costs
+   money every single day: canceled customers keeping access. */
+export function gradeOf(results) {
+  const graded = results.filter((r) => r.outcome === "pass" || r.outcome === "fail");
+  const untestable = results.filter((r) => r.outcome === "could_not_test" || r.outcome === "not_provable");
+  if (graded.length === 0) return { letter: "?", reason: "Nothing could be tested. See the errors below. This is a problem with the run, not proof about the app." };
+
+  const failures = graded.filter((r) => r.outcome === "fail");
+  const criticalFailure = failures.find((r) => r.critical);
+
+  const letter = criticalFailure ? "F"
+    : failures.length === 0 ? (untestable.length ? "B" : "A")
+    : failures.length === 1 ? "C"
+    : "D";
+
+  const reason = criticalFailure
+    ? "Customers who cancel keep their paid access. This leaks money every day until it is fixed."
+    : failures.length === 0
+      ? untestable.length
+        ? `Every tested scenario passed, but ${untestable.length} could not be tested.`
+        : "Every lifecycle scenario passed."
+      : `${failures.length} lifecycle scenario${failures.length === 1 ? "" : "s"} failed.`;
+
+  return { letter, reason, failures: failures.map((r) => r.id), untested: untestable.map((r) => r.id) };
+}

package/src/probe.mjs

@@ -0,0 +1,167 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/* The access probe: a temporary route the Check adds to the founder's app so
+ * the lifecycle pass can ask THE APP'S OWN CODE "is this account entitled?"
+ * after each transition. Added for the run, removed afterwards — and removal
+ * refuses to touch any file the Check did not write.
+ *
+ * The judgement problem lives here: which function IS the app's access
+ * decision? Detection ranks candidate files; this module only wires a probe
+ * when it finds an exported function whose name and shape it recognises. When
+ * it is not sure, it says so and emits a two-line stub for the founder (or
+ * their coding agent) to complete — an honest gap beats a wrong wire.
+ */
+
+const MARKER = "AKESO PROBE — added by Akeso Check for a test run. Safe to delete.";
+
+/* Function names that mean "the billing/access decision" when exported.
+   Ordered: an explicit entitlement function beats a generic isPro. */
+const KNOWN_NAMES = [
+  "getBillingEntitlement",
+  "billingEntitled",
+  "isSubscribed",
+  "hasActiveSubscription",
+  "isPro",
+  "isPremium",
+  "isPaid",
+  "hasPaidAccess",
+  "hasAccess",
+];
+
+/* Find recognisable exported access functions in one file. Regex over source is
+   deliberate — no TS compiler dependency — and anything it cannot classify is
+   simply not offered, never guessed at. */
+export function findAccessExports(source) {
+  const found = [];
+  for (const name of KNOWN_NAMES) {
+    const patterns = [
+      new RegExp(`export\\s+(async\\s+)?function\\s+${name}\\s*\\(([^)]*)\\)`),
+      new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(async\\s*)?\\(([^)]*)\\)\\s*=>`),
+    ];
+    for (const pattern of patterns) {
+      const match = source.match(pattern);
+      if (match) {
+        const params = (match[2] ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+        found.push({ name, paramCount: params.length, firstParam: params[0] || null });
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+/* Choose the probe target across the ranked candidate files. One-argument
+   functions only: isPro(userId) is wireable; isPro(userId, featureFlag, ctx)
+   is a guess we refuse to make. */
+export async function chooseProbeTarget(root, accessDecisionSites) {
+  const considered = [];
+  for (const site of accessDecisionSites.slice(0, 6)) {
+    if (site.clientSideOnly) continue; /* a browser-side gate cannot answer for the server */
+    const source = await readFile(path.join(root, site.file), "utf8").catch(() => null);
+    if (!source) continue;
+    for (const fn of findAccessExports(source)) {
+      considered.push({ file: site.file, ...fn, siteScore: site.score });
+    }
+  }
+  considered.sort((a, b) =>
+    (KNOWN_NAMES.indexOf(a.name) - KNOWN_NAMES.indexOf(b.name)) || (b.siteScore - a.siteScore));
+
+  const wireable = considered.filter((c) => c.paramCount === 1);
+  return {
+    chosen: wireable[0] || null,
+    considered,
+    reason: wireable[0]
+      ? `Found ${wireable[0].name}(${wireable[0].firstParam}) in ${wireable[0].file}.`
+      : considered.length
+        ? "Access functions exist but none takes exactly one argument — wiring one would be a guess."
+        : "No recognisable exported access function was found.",
+  };
+}
+
+function probeRoutePath(root, framework) {
+  if (framework === "next-pages") return path.join(root, "pages", "api", "__akeso_probe.ts");
+  return path.join(root, "app", "api", "__akeso_probe", "route.ts");
+}
+
+/* Relative import from the generated route file to the access module, with the
+   extension handled the way the app's own imports are. */
+function importSpecifier(fromFile, toFile) {
+  let relative = path.relative(path.dirname(fromFile), toFile).replaceAll(path.sep, "/");
+  if (!relative.startsWith(".")) relative = `./${relative}`;
+  return relative.replace(/\.(ts|tsx)$/, "").replace(/\.(js)$/, "");
+}
+
+export function renderProbe({ framework, specifier, exportName }) {
+  const body = `// ${MARKER}
+// It exists so the lifecycle test can ask this app's own code whether an
+// account is billing-entitled. It reads; it never writes.
+import { ${exportName} } from "${specifier}";
+
+${framework === "next-pages"
+    ? `export default async function handler(req, res) {
+  const account = String(req.query.account || "");
+  res.status(200).json({ billingEntitled: Boolean(await ${exportName}(account)) });
+}`
+    : `export async function GET(request${framework.startsWith("node") ? "" : ": Request"}) {
+  const account = new URL(request.url).searchParams.get("account") || "";
+  return Response.json({ billingEntitled: Boolean(await ${exportName}(account)) });
+}`}
+`;
+  return body;
+}
+
+export function renderProbeStub(framework) {
+  return `// ${MARKER}
+// Akeso could not identify this app's access function on its own.
+// ONE LINE TO COMPLETE: import your access check and return its answer.
+// Example:  import { isPro } from "../../lib/access";
+${framework === "next-pages"
+    ? `export default async function handler(req, res) {
+  const account = String(req.query.account || "");
+  res.status(200).json({ billingEntitled: /* await isPro(account) */ null });
+}`
+    : `export async function GET(request: Request) {
+  const account = new URL(request.url).searchParams.get("account") || "";
+  return Response.json({ billingEntitled: /* await isPro(account) */ null });
+}`}
+`;
+}
+
+export async function installProbe(root, detection) {
+  const framework = detection.framework?.framework || "next-app-router";
+  const routeFile = probeRoutePath(root, framework)
+    .replace(/route\.ts$/, framework === "node-other" ? "route.mjs" : "route.ts");
+
+  const target = await chooseProbeTarget(root, detection.accessDecisionSites || []);
+  const content = target.chosen
+    ? renderProbe({
+      framework,
+      specifier: importSpecifier(routeFile, path.join(root, target.chosen.file)),
+      exportName: target.chosen.name,
+    })
+    : renderProbeStub(framework);
+
+  await mkdir(path.dirname(routeFile), { recursive: true });
+  await writeFile(routeFile, content);
+  return {
+    routeFile,
+    urlPath: "/api/__akeso_probe",
+    wired: Boolean(target.chosen),
+    reason: target.reason,
+    target: target.chosen || null,
+  };
+}
+
+/* Removal refuses to delete anything without the marker: if a founder edited
+   the stub into something real and kept it, that file is now theirs. */
+export async function removeProbe(routeFile) {
+  const content = await readFile(routeFile, "utf8").catch(() => null);
+  if (content === null) return { removed: false, reason: "already gone" };
+  if (!content.includes(MARKER)) return { removed: false, reason: "file no longer carries the Akeso marker — leaving it alone" };
+  await rm(routeFile);
+  /* tidy the wrapper dir Next requires, only if we created it and it is now empty */
+  const dir = path.dirname(routeFile);
+  if (path.basename(dir) === "__akeso_probe") await rm(dir, { recursive: false }).catch(() => {});
+  return { removed: true };
+}

package/src/report.mjs

@@ -0,0 +1,127 @@
+/* The report a founder actually sees: a local HTML file that opens in their
+ * browser. It looks like a website; it is a file on their machine, and saying
+ * so prominently is part of the product — the whole trust story is "nothing
+ * left your computer."
+ *
+ * Design rules, inherited from the product-care dashboard: plain English
+ * first, colour only where it carries state, nothing on the page that was not
+ * measured, and the limits of the run stated as prominently as the findings.
+ */
+
+const escapeHtml = (value) => String(value ?? "")
+  .replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+
+const GRADE_COPY = {
+  A: "Your billing lifecycle holds up.",
+  B: "Nothing failed, but some scenarios could not be tested.",
+  C: "One lifecycle scenario fails.",
+  D: "Several lifecycle scenarios fail.",
+  F: "Canceled customers keep paid access.",
+  "?": "The run itself had problems. This is not a verdict on your app.",
+};
+
+export function renderReport({ detection, lifecycle, generatedAt = new Date() }) {
+  const grade = lifecycle?.grade ?? { letter: "?", reason: "The lifecycle test did not run." };
+  const handler = detection.webhookHandlers?.[0] || null;
+
+  const staticFindings = [];
+  if (!handler) {
+    staticFindings.push({ tone: "bad", text: "No Stripe webhook handler was found. Payment events from Stripe have nowhere to land." });
+  } else {
+    if (!handler.verifiesSignature) staticFindings.push({ tone: "bad", text: "The webhook handler does not verify Stripe's signature. Anyone who finds the URL can forge payment events." });
+    else if (!handler.rawBodySeen) staticFindings.push({ tone: "warn", text: "Signature verification exists, but raw-body handling was not seen. Verification like this often fails at runtime." });
+    if (handler.missingEvents?.length) staticFindings.push({ tone: "warn", text: `The handler ignores ${handler.missingEvents.length} of the 7 lifecycle events: ${handler.missingEvents.join(", ")}.` });
+    if (staticFindings.length === 0) staticFindings.push({ tone: "ok", text: "Signature verified against the raw body, and all 7 lifecycle events are handled." });
+  }
+  const clientGate = (detection.accessDecisionSites || []).find((site) => site.clientSideOnly);
+  if (clientGate) staticFindings.push({ tone: "warn", text: `Paid access appears to be checked in the browser (${clientGate.file}), a gate anyone can step around with devtools.` });
+
+  const scenarioRows = (lifecycle?.results || []).map((result) => {
+    const mark = result.outcome === "pass" ? "✓"
+      : result.outcome === "fail" ? "✗"
+      : result.outcome === "reported" ? "•" : "?";
+    const cls = result.outcome === "pass" ? "ok"
+      : result.outcome === "fail" ? (result.critical ? "bad" : "warn")
+      : result.outcome === "reported" ? "note" : "mute";
+    const detail = result.outcome === "fail"
+      ? (result.expected ? "access should have been granted, but your app says no" : "access should have ended, but your app still grants it")
+      : result.outcome === "reported" ? `your app's policy: ${result.observed ? "keeps access" : "removes access"}`
+      : result.outcome === "could_not_test" ? escapeHtml(result.harnessError)
+      : result.outcome === "not_provable" ? escapeHtml(result.note || "not provable on this run") : "";
+    return `<div class="row ${cls}"><span class="mark">${mark}</span><span class="name">${escapeHtml(result.name)}</span><span class="detail">${detail}</span></div>`;
+  }).join("\n");
+
+  const findingRows = staticFindings.map((finding) =>
+    `<div class="row ${finding.tone}"><span class="mark">${finding.tone === "ok" ? "✓" : finding.tone === "bad" ? "✗" : "!"}</span><span class="name wide">${escapeHtml(finding.text)}</span></div>`,
+  ).join("\n");
+
+  const limits = [
+    "Only the billing lifecycle was tested. Not login, checkout UI, or anything else.",
+    "Events were delivered locally with your app's own webhook secret. If your handler re-fetches objects from Stripe's API, run the sandbox mode with your Stripe test key for full fidelity.",
+    detection.capabilities?.blockers?.length ? `Not possible on this project yet: ${detection.capabilities.blockers.join(" ")}` : null,
+  ].filter(Boolean).map((limit) => `<li>${escapeHtml(limit)}</li>`).join("\n");
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Akeso Check · ${escapeHtml(detection.framework?.packageName || "your app")}</title>
+<style>
+  :root { --bg:#fcfcfd; --ink:#16181d; --ink2:#5b6270; --ink3:#8a919e; --line:#e6e8ec;
+    --ok:#12784b; --warn:#96620a; --bad:#b3261e; --note:#2f4a78; }
+  @media (prefers-color-scheme: dark) { :root { --bg:#111317; --ink:#e9ebef; --ink2:#a4abb8;
+    --ink3:#767d8a; --line:#282c34; --ok:#4cbe83; --warn:#dfa94c; --bad:#ef8578; --note:#8aa9dc; } }
+  * { box-sizing:border-box; }
+  body { margin:0; background:var(--bg); color:var(--ink); font:16px/1.55 ui-sans-serif,-apple-system,system-ui,sans-serif; -webkit-font-smoothing:antialiased; }
+  .shell { max-width:640px; margin:0 auto; padding:40px 24px 100px; }
+  .local { font-size:12.5px; color:var(--ink3); border:1px solid var(--line); border-radius:20px; display:inline-block; padding:3px 12px; margin-bottom:34px; }
+  .gradeCard { border:1px solid var(--line); border-radius:10px; padding:30px 28px; display:flex; gap:26px; align-items:center; }
+  .gradeLetter { font-size:76px; font-weight:700; line-height:1; letter-spacing:-.04em; }
+  .g-A,.g-B { color:var(--ok); } .g-C { color:var(--warn); } .g-D,.g-F { color:var(--bad); } .g-\\? { color:var(--ink3); }
+  .gradeCard h1 { margin:0 0 6px; font-size:22px; letter-spacing:-.02em; }
+  .gradeCard p { margin:0; color:var(--ink2); font-size:15px; }
+  .app { font-size:13px; color:var(--ink3); margin-top:10px; }
+  h2 { font-size:12px; font-weight:600; letter-spacing:.06em; text-transform:uppercase; color:var(--ink3); margin:44px 0 4px; }
+  .intro { margin:2px 0 12px; color:var(--ink2); font-size:14.5px; }
+  .rows { border-top:1px solid var(--line); }
+  .row { display:flex; gap:12px; padding:11px 0; border-bottom:1px solid var(--line); align-items:baseline; font-size:15px; }
+  .mark { width:18px; text-align:center; flex:none; font-weight:600; }
+  .row.ok .mark { color:var(--ok); } .row.warn .mark { color:var(--warn); }
+  .row.bad .mark { color:var(--bad); } .row.bad .name { color:var(--bad); font-weight:600; }
+  .row.note .mark { color:var(--note); } .row.mute { color:var(--ink3); }
+  .name { flex:1; } .name.wide { flex:auto; }
+  .detail { color:var(--ink3); font-size:13.5px; text-align:right; max-width:40%; }
+  ul.limits { margin:8px 0 0; padding-left:20px; color:var(--ink2); font-size:14.5px; }
+  ul.limits li { margin-bottom:7px; }
+  .cta { margin-top:48px; border:1px solid var(--line); border-radius:10px; padding:22px 24px; }
+  .cta h3 { margin:0 0 6px; font-size:17px; } .cta p { margin:0 0 14px; color:var(--ink2); font-size:14.5px; }
+  .cta a { display:inline-block; background:var(--ink); color:var(--bg); text-decoration:none; border-radius:7px; padding:10px 18px; font-size:15px; font-weight:500; }
+  footer { margin-top:44px; font-size:12.5px; color:var(--ink3); }
+</style></head><body><div class="shell">
+  <div class="local">This report is a file on your computer. Nothing was sent anywhere.</div>
+  <div class="gradeCard">
+    <div class="gradeLetter g-${escapeHtml(grade.letter)}">${escapeHtml(grade.letter)}</div>
+    <div>
+      <h1>${escapeHtml(GRADE_COPY[grade.letter] || grade.reason)}</h1>
+      <p>${escapeHtml(grade.letter === "F" ? "This leaks money every day until it is fixed." : grade.reason)}</p>
+      <div class="app">${escapeHtml([
+        detection.framework?.packageName || detection.root,
+        { "next-app-router": "a Next.js app", "next-pages": "a Next.js app", express: "an Express app", "supabase-edge": "a Supabase Edge app", "node-other": "a Node app" }[detection.framework?.framework] || null,
+        detection.database?.kind && detection.database.kind !== "none-found" ? `with ${detection.database.kind === "supabase" ? "Supabase" : detection.database.kind}` : null,
+        detection.stripe?.secretKey ? `Stripe ${detection.stripe.secretKey.mode.toLowerCase()} mode` : null,
+      ].filter(Boolean).join(", "))}</div>
+    </div>
+  </div>
+
+  <h2>What we tested</h2>
+  <p class="intro">Akeso acted out ten billing situations against your app: paying, canceling, a failing card, a refund. After each one it asked your app the same question: does this customer still have paid access?</p>
+  <div class="rows">${scenarioRows || '<div class="row mute"><span class="mark">?</span><span class="name">The lifecycle test did not run on this project.</span></div>'}</div>
+
+  <h2>What your code shows</h2>
+  <p class="intro">Read from your webhook handler and access checks, before anything ran.</p>
+  <div class="rows">${findingRows}</div>
+
+  <h2>What this did not check</h2>
+  <ul class="limits">${limits}</ul>
+
+  <footer>Akeso Check · ${escapeHtml(generatedAt.toISOString().slice(0, 16).replace("T", " "))} · ${lifecycle ? `${lifecycle.scenarioCount} lifecycle scenarios` : "static analysis only"} · local run</footer>
+</div></body></html>`;
+}

package/src/sandbox.mjs

@@ -0,0 +1,191 @@
+import { signPayload } from "./stripe-events.mjs";
+
+/* The sandbox driver: the highest-fidelity lifecycle test.
+ *
+ * Where the local driver synthesises Stripe-shaped events, this one creates a
+ * REAL customer and subscription in the founder's own Stripe test sandbox and
+ * lets Stripe author the events. We then fetch those events from Stripe's API
+ * and deliver them to the locally running app, signed with the app's own
+ * webhook secret — so no Stripe CLI login and no public tunnel is needed.
+ * The payloads are Stripe's, byte for byte.
+ *
+ * Safety rails, in order of importance:
+ * - refuses to run with anything but a test-mode key, checked here and not
+ *   only at the call site
+ * - everything it creates is tagged and deleted afterwards
+ * - it writes only to the founder's own test sandbox, never to the app
+ */
+
+const API = "https://api.stripe.com/v1";
+
+function assertTestKey(key) {
+  if (!/^(sk|rk)_test_/.test(key || "")) {
+    throw new Error("The sandbox driver refuses to run without a test-mode key (sk_test_…). This is not configurable.");
+  }
+}
+
+async function stripe(key, method, path, params = {}) {
+  const body = new URLSearchParams();
+  const add = (name, value) => {
+    if (value === undefined || value === null) return;
+    if (typeof value === "object") for (const [k, v] of Object.entries(value)) add(`${name}[${k}]`, v);
+    else body.append(name, String(value));
+  };
+  for (const [name, value] of Object.entries(params)) add(name, value);
+
+  const response = await fetch(`${API}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${key}`,
+      ...(method === "GET" ? {} : { "Content-Type": "application/x-www-form-urlencoded" }),
+    },
+    ...(method === "GET" ? {} : { body }),
+  });
+  const json = await response.json();
+  if (!response.ok) throw new Error(`Stripe ${method} ${path} -> ${response.status}: ${json.error?.message || "unknown"}`);
+  return json;
+}
+
+/* Find-or-create the test plan the driver subscribes to. Idempotent through a
+   lookup key, so repeated runs reuse one price instead of littering the
+   founder's sandbox. */
+async function ensureTestPrice(key) {
+  const existing = await stripe(key, "GET", "/prices?lookup_keys[]=akeso-check-monthly&limit=1");
+  if (existing.data.length) return existing.data[0];
+  const product = await stripe(key, "POST", "/products", {
+    name: "Akeso Check test plan (safe to delete)",
+    metadata: { akeso: "check" },
+  });
+  return stripe(key, "POST", "/prices", {
+    product: product.id,
+    unit_amount: 2900,
+    currency: "usd",
+    recurring: { interval: "month" },
+    lookup_key: "akeso-check-monthly",
+    metadata: { akeso: "check" },
+  });
+}
+
+/* Stripe events relevant to our customer, oldest first, authored by Stripe. */
+async function eventsFor(key, { customerId, since }) {
+  const page = await stripe(key, "GET", `/events?limit=100&created[gte]=${since - 5}`);
+  return page.data
+    .filter((event) => {
+      const object = event.data?.object || {};
+      return object.customer === customerId || object.id === customerId;
+    })
+    .sort((a, b) => a.created - b.created);
+}
+
+async function deliverAll(events, { webhookUrl, webhookSecret, alreadyDelivered }) {
+  const delivered = [];
+  for (const event of events) {
+    if (alreadyDelivered.has(event.id)) continue;
+    alreadyDelivered.add(event.id);
+    const rawBody = JSON.stringify(event);
+    const response = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json", "stripe-signature": signPayload(rawBody, webhookSecret) },
+      body: rawBody,
+    });
+    delivered.push({ id: event.id, type: event.type, status: response.status });
+    await new Promise((resolve) => setTimeout(resolve, 60));
+  }
+  return delivered;
+}
+
+async function probe(probeUrl, account) {
+  /* A probe deployed on a public app carries a guard token in its URL, so the
+     account parameter joins with & when a query already exists. */
+  const joiner = probeUrl.includes("?") ? "&" : "?";
+  const response = await fetch(`${probeUrl}${joiner}account=${encodeURIComponent(account)}`);
+  const body = await response.json();
+  return Boolean(body.billingEntitled);
+}
+
+/* Subscribe -> cancel-at-period-end -> cancel-now, with the app's entitlement
+   read after each phase. Trial and renewal phases need test clocks and land in
+   the next iteration; the report never claims them meanwhile. */
+export async function runSandboxLifecycle({ stripeKey, webhookUrl, probeUrl, webhookSecret, log = () => {} }) {
+  assertTestKey(stripeKey);
+  const started = Math.floor(Date.now() / 1000);
+  const alreadyDelivered = new Set();
+  const phases = [];
+  let customerId = null;
+
+  try {
+    const price = await ensureTestPrice(stripeKey);
+    log(`test plan ready: ${price.id}`);
+
+    const customer = await stripe(stripeKey, "POST", "/customers", {
+      name: "Akeso Check synthetic customer",
+      metadata: { akeso: "check" },
+    });
+    customerId = customer.id;
+    await stripe(stripeKey, "POST", `/customers/${customerId}`, {
+      "invoice_settings[default_payment_method]": (await stripe(stripeKey, "POST", "/payment_methods/pm_card_visa/attach", { customer: customerId })).id,
+    });
+
+    const subscription = await stripe(stripeKey, "POST", "/subscriptions", {
+      customer: customerId,
+      "items[0][price]": price.id,
+      metadata: { akeso: "check" },
+    });
+    log(`subscribed: ${subscription.id} (${subscription.status})`);
+
+    let accessEverGranted = false;
+
+    const runPhase = async (name, expected) => {
+      /* Stripe writes events asynchronously; poll briefly rather than assuming. */
+      let delivered = [];
+      for (let i = 0; i < 10; i += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 1200));
+        delivered = [...delivered, ...await deliverAll(
+          await eventsFor(stripeKey, { customerId, since: started }),
+          { webhookUrl, webhookSecret, alreadyDelivered },
+        )];
+        if (delivered.length) break;
+      }
+      const observed = await probe(probeUrl, customerId);
+      if (observed) accessEverGranted = true;
+
+      /* The vacuous-pass guard: "cancellation removes access" proves nothing
+         if access was never granted in the first place. A removal phase on an
+         app that never granted is reported as unprovable, not as a pass — the
+         same positive-control discipline as everywhere else in this project. */
+      const removalPhase = expected === false;
+      const outcome = removalPhase && !accessEverGranted
+        ? "not_provable"
+        : observed === expected ? "pass" : "fail";
+
+      phases.push({
+        phase: name,
+        expected,
+        observed,
+        outcome,
+        ...(outcome === "not_provable" ? { reason: "access was never granted, so its removal cannot be tested" } : {}),
+        eventsDelivered: delivered.map((d) => d.type),
+      });
+      log(`${name}: expected ${expected}, app says ${observed} -> ${outcome}`);
+    };
+
+    await runPhase("real subscription grants access", true);
+
+    await stripe(stripeKey, "POST", `/subscriptions/${subscription.id}`, { cancel_at_period_end: true });
+    await runPhase("cancel at period end keeps access until the period ends", true);
+
+    await stripe(stripeKey, "DELETE", `/subscriptions/${subscription.id}`);
+    await runPhase("cancellation removes access", false);
+
+    return {
+      driver: "stripe-sandbox",
+      phases,
+      passed: phases.every((p) => p.outcome === "pass"),
+      notProvable: phases.filter((p) => p.outcome === "not_provable").map((p) => p.phase),
+      criticalFailure: phases.find((p) => p.phase.includes("removes access") && p.outcome === "fail") || null,
+    };
+  } finally {
+    /* Leave the founder's sandbox the way we found it. */
+    if (customerId) await stripe(stripeKey, "DELETE", `/customers/${customerId}`).catch(() => {});
+  }
+}