akeso-check 0.1.0

package/fixtures/broken-app/lib/handler.mjs

@@ -0,0 +1,38 @@
+// The single source of truth for this fixture's webhook behaviour.
+// Deliberately the classic vibe-coded shape:
+//   - trusts the parsed JSON body outright (signature never checked)
+//   - grants on checkout.session.completed
+//   - ignores every cancellation, failure, and refund event
+// The result: canceled customers keep access forever. The Check must catch it.
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DB = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "data", "profiles.json");
+
+export async function readProfiles() {
+  try { return JSON.parse(await readFile(DB, "utf8")); } catch { return {}; }
+}
+
+async function writeProfiles(profiles) {
+  await writeFile(DB, JSON.stringify(profiles, null, 2));
+}
+
+export async function handleWebhook(rawBody /* string */, _signatureHeader) {
+  const event = JSON.parse(rawBody); // no verification: anyone could forge this
+
+  if (event.type === "checkout.session.completed") {
+    const profiles = await readProfiles();
+    const account = event.data.object.client_reference_id;
+    profiles[account] = { ...profiles[account], is_pro: true };
+    await writeProfiles(profiles);
+  }
+  // every other event type: silently ignored
+  return { received: true };
+}
+
+// Where this app decides who has paid access.
+export async function isPro(accountId) {
+  const profiles = await readProfiles();
+  return Boolean(profiles[accountId]?.is_pro);
+}

package/fixtures/broken-app/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "broken-fixture",
+  "dependencies": { "next": "16.0.0", "stripe": "17.0.0", "@supabase/supabase-js": "2.0.0" }
+}

package/fixtures/broken-app/server.mjs

@@ -0,0 +1,34 @@
+// Minimal runnable server for the fixture: the webhook route plus the access
+// probe the Check queries after each lifecycle transition.
+import http from "node:http";
+import { handleWebhook, isPro, readProfiles } from "./lib/handler.mjs";
+import { writeFile } from "node:fs/promises";
+
+const PORT = Number(process.env.PORT || 4101);
+
+// Fresh state per run so a previous run's grants cannot leak into this one.
+await writeFile(new URL("./data/profiles.json", import.meta.url), "{}");
+
+http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+  if (req.method === "POST" && url.pathname === "/api/stripe/webhook") {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", async () => {
+      try {
+        const out = await handleWebhook(body, req.headers["stripe-signature"]);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify(out));
+      } catch (error) {
+        res.writeHead(500); res.end(String(error?.message || error));
+      }
+    });
+    return;
+  }
+  if (url.pathname === "/__akeso_probe") {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ billingEntitled: await isPro(url.searchParams.get("account")) }));
+    return;
+  }
+  res.writeHead(404); res.end();
+}).listen(PORT, () => console.log(`broken-app listening on ${PORT}`));

package/fixtures/fixed-app/.env.local

@@ -0,0 +1,4 @@
+STRIPE_SECRET_KEY=sk_test_fixturefixturefixturefixture1234
+STRIPE_WEBHOOK_SECRET=whsec_fixturefixturefixture5678
+NEXT_PUBLIC_SUPABASE_URL=https://fixture.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_pub_fixture

package/fixtures/fixed-app/app/api/stripe/webhook/route.ts

@@ -0,0 +1,23 @@
+// The repaired handler the Fix Plan produces (static-pass view of lib/handler.mjs).
+import Stripe from "stripe";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export async function POST(request: Request) {
+  const rawBody = await request.text();
+  const signature = request.headers.get("stripe-signature")!;
+  const event = stripe.webhooks.constructEvent(rawBody, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+
+  switch (event.type) {
+    case "checkout.session.completed":
+    case "invoice.paid":
+    case "invoice.payment_failed":
+    case "customer.subscription.created":
+    case "customer.subscription.updated":
+    case "customer.subscription.deleted":
+    case "charge.refunded":
+      // handled in lib/handler.mjs (idempotent, ordered, status-derived)
+      break;
+  }
+  return Response.json({ received: true });
+}

package/fixtures/fixed-app/lib/handler.mjs

@@ -0,0 +1,80 @@
+// What the Fix Plan produces: the same app, done right.
+//   - verifies the Stripe signature against the raw body
+//   - handles the full lifecycle event set
+//   - idempotent by event id; ignores events older than the last applied
+//   - entitlement derived from subscription status, not from event arrival
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DB = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "data", "profiles.json");
+/* The signing secret is the HMAC key verbatim, whsec_ prefix included —
+   exactly what stripe-node's constructEvent does. */
+const WHSEC = process.env.STRIPE_WEBHOOK_SECRET || "whsec_fixturefixturefixture5678";
+
+async function read() {
+  try { return JSON.parse(await readFile(DB, "utf8")); } catch { return { accounts: {}, seenEvents: [] }; }
+}
+async function write(state) { await writeFile(DB, JSON.stringify(state, null, 2)); }
+
+function verifySignature(rawBody, header) {
+  if (!header) return false;
+  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
+  if (!parts.t || !parts.v1) return false;
+  const expected = createHmac("sha256", WHSEC).update(`${parts.t}.${rawBody}`).digest("hex");
+  try {
+    return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1, "hex"));
+  } catch { return false; }
+}
+
+// Which subscription statuses mean "billing-entitled" under this app's policy:
+// active and trialing yes; past_due still yes (grace); unpaid/canceled no.
+const ENTITLED_STATUSES = new Set(["active", "trialing", "past_due"]);
+
+export async function handleWebhook(rawBody, signatureHeader) {
+  if (!verifySignature(rawBody, signatureHeader)) {
+    return { status: 400, body: { error: "invalid signature" } };
+  }
+  const event = JSON.parse(rawBody);
+  const state = await read();
+
+  // Idempotency: the same event id applies once, ever.
+  if (state.seenEvents.includes(event.id)) return { status: 200, body: { received: true, duplicate: true } };
+  state.seenEvents.push(event.id);
+
+  const object = event.data.object;
+  const account = object.client_reference_id || object.metadata?.account || object.customer;
+  if (account) {
+    const current = state.accounts[account] || { lastEventCreated: 0 };
+    // Out-of-order guard: an older event never overrides a newer decision.
+    if (event.created > current.lastEventCreated) {
+      switch (event.type) {
+        case "checkout.session.completed":
+        case "customer.subscription.created":
+          current.billingEntitled = true; break;
+        case "invoice.paid":
+          current.billingEntitled = true; break;
+        case "customer.subscription.updated":
+          current.billingEntitled = ENTITLED_STATUSES.has(object.status); break;
+        case "invoice.payment_failed":
+          // grace: entitlement follows the subscription status events, not this
+          break;
+        case "customer.subscription.deleted":
+          current.billingEntitled = false; break;
+        case "charge.refunded":
+          current.billingEntitled = false; break; // this app's stated refund policy
+        default: break;
+      }
+      current.lastEventCreated = event.created;
+      state.accounts[account] = current;
+    }
+  }
+  await write(state);
+  return { status: 200, body: { received: true } };
+}
+
+export async function isPro(accountId) {
+  const state = await read();
+  return Boolean(state.accounts[accountId]?.billingEntitled);
+}

package/fixtures/fixed-app/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "fixed-fixture",
+  "dependencies": { "next": "16.0.0", "stripe": "17.0.0", "@supabase/supabase-js": "2.0.0" }
+}

package/fixtures/fixed-app/server.mjs

@@ -0,0 +1,34 @@
+// Minimal runnable server for the fixture: the webhook route plus the access
+// probe the Check queries after each lifecycle transition.
+import http from "node:http";
+import { handleWebhook, isPro } from "./lib/handler.mjs";
+import { writeFile } from "node:fs/promises";
+
+const PORT = Number(process.env.PORT || 4102);
+
+// Fresh state per run so a previous run's grants cannot leak into this one.
+await writeFile(new URL("./data/profiles.json", import.meta.url), JSON.stringify({ accounts: {}, seenEvents: [] }));
+
+http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+  if (req.method === "POST" && url.pathname === "/api/stripe/webhook") {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", async () => {
+      try {
+        const out = await handleWebhook(body, req.headers["stripe-signature"]);
+        res.writeHead(out.status || 200, { "content-type": "application/json" });
+        res.end(JSON.stringify(out.body ?? out));
+      } catch (error) {
+        res.writeHead(500); res.end(String(error?.message || error));
+      }
+    });
+    return;
+  }
+  if (url.pathname === "/__akeso_probe") {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ billingEntitled: await isPro(url.searchParams.get("account")) }));
+    return;
+  }
+  res.writeHead(404); res.end();
+}).listen(PORT, () => console.log(`fixed-app listening on ${PORT}`));

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "akeso-check",
+  "version": "0.1.0",
+  "description": "Prove whether your app grants and revokes paid access correctly. Runs on your machine; nothing leaves it.",
+  "type": "module",
+  "bin": { "akeso-check": "bin/akeso-check.mjs" },
+  "license": "MIT",
+  "keywords": ["stripe", "billing", "webhooks", "subscriptions", "entitlement", "saas", "testing"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "check": "node bin/akeso-check.mjs",
+    "test": "node --test tests/*.test.mjs"
+  }
+}

package/src/adapter.mjs

@@ -0,0 +1,128 @@
+/* Emits the two functions the whole Akeso relationship eventually runs on:
+ *
+ *   getBillingEntitlement(accountId)  — the app's one honest answer
+ *   restoreBillingEntitlement(...)    — the one write Akeso may ever make
+ *
+ * Generated for the founder to read and commit — never installed silently.
+ * The comments inside the generated code are part of the product: the founder
+ * (or their coding agent) has to see WHY the six fields are separate, because
+ * collapsing them back into one boolean is how the company-ending write
+ * (restoring access to a banned account) becomes possible again.
+ */
+
+const SIX_FIELDS = `  // The six fields, and why they never collapse into one boolean:
+  //   billingEntitled        — derived from Stripe. THE ONLY FIELD AKESO MAY CHANGE.
+  //   manualComplimentaryAccess — a human gave free access on purpose. Not Akeso's.
+  //   manualBillingOverride  — a human forced billing state on purpose. Not Akeso's.
+  //   administrativeBlock    — an admin locked this account. Never overridden.
+  //   securityOrAbuseBlock   — fraud/abuse lock. NEVER overridden, whatever Stripe says.
+  //   finalAccessDecision    — what the app actually does. Read for reports, never written.`;
+
+export function renderAdapter({ tableName = "profiles", accountColumn = "id", entitledColumn = "billing_entitled", language = "ts" } = {}) {
+  const ts = language === "ts";
+  return `// AKESO ADAPTER — generated by Akeso Check. Read it, then commit it.
+// Two functions. Nothing else. Akeso's entire access to this app goes through
+// them, which means this file is also the complete list of what Akeso can do.
+
+export const AKESO_ADAPTER_VERSION = "1";
+export const AKESO_RULE_VERSION = "1"; // bump when your billing policy changes
+
+${SIX_FIELDS}
+export async function getBillingEntitlement(accountId${ts ? ": string" : ""}) {
+  // TODO(you or your agent): replace this query with your real data source.
+  // The Check found billing state around: table "${tableName}", column "${entitledColumn}".
+  const row = await db
+    .from("${tableName}")
+    .select("${accountColumn}, ${entitledColumn}")
+    .eq("${accountColumn}", accountId)
+    .single();
+
+  return {
+    accountId,
+    billingEntitled: Boolean(row?.${entitledColumn}),
+    manualComplimentaryAccess: false, // wire to your comp flag if one exists
+    manualBillingOverride: false,
+    administrativeBlock: false,       // wire to your admin-lock flag if one exists
+    securityOrAbuseBlock: false,      // wire to your abuse-lock flag if one exists
+    finalAccessDecision: Boolean(row?.${entitledColumn}), // what your gates actually use
+    ruleVersion: AKESO_RULE_VERSION,
+    adapterVersion: AKESO_ADAPTER_VERSION,
+    decisionSource: "${tableName}.${entitledColumn}",
+    readAt: new Date().toISOString(),
+  };
+}
+
+// The one write. Changes billingEntitled and NOTHING else, and only when the
+// row still looks the way the caller last saw it (compare-and-set) — a restore
+// racing a newer change must lose, loudly, not win, silently.
+export async function restoreBillingEntitlement(
+  accountId${ts ? ": string" : ""},
+  expectedCurrentState${ts ? ": { billingEntitled: boolean }" : ""},
+  targetState${ts ? ": { billingEntitled: boolean }" : ""},
+  ruleVersion${ts ? ": string" : ""},
+  idempotencyKey${ts ? ": string" : ""},
+  reasonCode${ts ? ": string" : ""},
+) {
+  if (ruleVersion !== AKESO_RULE_VERSION) {
+    return { result: "conflict"${ts ? " as const" : ""}, reason: "rule version changed since this restore was prepared" };
+  }
+
+  const before = await getBillingEntitlement(accountId);
+
+  // Blocks are load-bearing. A blocked account is never restored by billing
+  // logic, whatever Stripe says — this is the line between a billing tool and
+  // an incident.
+  if (before.administrativeBlock || before.securityOrAbuseBlock) {
+    return { result: "unsupported"${ts ? " as const" : ""}, reason: "account carries an administrative or security block", before };
+  }
+  if (before.billingEntitled === targetState.billingEntitled) {
+    return { result: "no_op"${ts ? " as const" : ""}, before };
+  }
+  if (before.billingEntitled !== expectedCurrentState.billingEntitled) {
+    return { result: "conflict"${ts ? " as const" : ""}, reason: "state changed since it was read", before };
+  }
+
+  // TODO(you or your agent): the actual compare-and-set update, e.g.
+  //   UPDATE ${tableName} SET ${entitledColumn} = $target
+  //   WHERE ${accountColumn} = $accountId AND ${entitledColumn} = $expected
+  // and record { idempotencyKey, reasonCode, before, after } in an audit table.
+  const updated = await db
+    .from("${tableName}")
+    .update({ ${entitledColumn}: targetState.billingEntitled })
+    .eq("${accountColumn}", accountId)
+    .eq("${entitledColumn}", expectedCurrentState.billingEntitled)
+    .select();
+
+  const after = await getBillingEntitlement(accountId);
+  const applied = after.billingEntitled === targetState.billingEntitled;
+  return {
+    result: applied ? ${ts ? '"applied" as const' : '"applied"'} : ${ts ? '"failed" as const' : '"failed"'},
+    idempotencyKey,
+    reasonCode,
+    before,
+    after,
+    verified: applied, // success is claimed only after the re-read agrees
+  };
+}
+`;
+}
+
+/* A runnable reference implementation of the same contract against a plain
+   JSON store — what the fixtures use, and what the generated code's tests can
+   exercise so the contract itself is proven even before a founder wires it. */
+export function renderReferenceAdapter() {
+  return renderAdapter({ language: "mjs" })
+    .replace(/const row = await db[\s\S]*?\.single\(\);/,
+      `const store = JSON.parse(await (await import("node:fs/promises")).readFile(process.env.AKESO_REF_DB, "utf8"));
+  const row = store[accountId] || null;`)
+    .replace(/const updated = await db[\s\S]*?\.select\(\);/,
+      `const fs = await import("node:fs/promises");
+  const store = JSON.parse(await fs.readFile(process.env.AKESO_REF_DB, "utf8"));
+  if (store[accountId] && Boolean(store[accountId].billing_entitled) === expectedCurrentState.billingEntitled) {
+    store[accountId].billing_entitled = targetState.billingEntitled;
+    await fs.writeFile(process.env.AKESO_REF_DB, JSON.stringify(store));
+  }`)
+    .replace(/Boolean\(row\?\.billing_entitled\)/g, "Boolean(row?.billing_entitled)")
+    .replace(/administrativeBlock: false,.*$/m, "administrativeBlock: Boolean(row?.admin_block),")
+    .replace(/securityOrAbuseBlock: false,.*$/m, "securityOrAbuseBlock: Boolean(row?.abuse_block),");
+}

package/src/detect.mjs

@@ -0,0 +1,255 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+/* Works out what this project is, using only what is on disk.
+ *
+ * This is the part of the Check that decides whether everything downstream is
+ * possible: which framework, where the env lives, whether there are Stripe
+ * keys and what mode they are in, where the webhook handler is, and — the hard
+ * one — where the app decides who has paid access.
+ *
+ * Two disciplines carried over from the product-care engine:
+ * - Report only what was actually observed. "Not found" is a finding, not an
+ *   error; a wrong confident answer is worse than an honest gap.
+ * - Never print a secret. Keys are reported as mode + last four characters.
+ */
+
+const IGNORE_DIRS = new Set([
+  "node_modules", ".git", ".next", "dist", "build", ".vercel", ".turbo",
+  "coverage", ".cache", "out", ".wrangler", ".vinext",
+]);
+
+const ENV_FILES = [".env", ".env.local", ".env.development.local", ".env.production.local", ".env.development", ".env.production"];
+
+async function exists(file) {
+  try { await stat(file); return true; } catch { return false; }
+}
+
+async function readIfThere(file) {
+  try { return await readFile(file, "utf8"); } catch { return null; }
+}
+
+function parseEnv(source) {
+  const values = {};
+  for (const rawLine of source.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    values[line.slice(0, eq).trim()] = value;
+  }
+  return values;
+}
+
+/* Safe to show: enough to recognise a key, never enough to use one. */
+function describeKey(value) {
+  if (!value) return null;
+  const mode = value.startsWith("sk_live_") || value.startsWith("rk_live_") ? "LIVE"
+    : value.startsWith("sk_test_") || value.startsWith("rk_test_") ? "test"
+    : value.startsWith("pk_live_") ? "LIVE (publishable)"
+    : value.startsWith("pk_test_") ? "test (publishable)"
+    : value.startsWith("whsec_") ? "webhook secret"
+    : "unrecognised";
+  return { mode, lastFour: value.slice(-4), length: value.length };
+}
+
+async function detectFramework(root) {
+  const pkgRaw = await readIfThere(path.join(root, "package.json"));
+  if (!pkgRaw) return { framework: "unknown", reason: "No package.json found." };
+  let pkg;
+  try { pkg = JSON.parse(pkgRaw); } catch { return { framework: "unknown", reason: "package.json is not valid JSON." }; }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  if (deps.next) {
+    const hasAppDir = await exists(path.join(root, "app")) || await exists(path.join(root, "src", "app"));
+    const hasPagesDir = await exists(path.join(root, "pages")) || await exists(path.join(root, "src", "pages"));
+    return {
+      framework: hasAppDir ? "next-app-router" : hasPagesDir ? "next-pages" : "next-unknown-layout",
+      nextVersion: deps.next,
+      packageName: pkg.name || null,
+    };
+  }
+  if (deps.express) return { framework: "express", packageName: pkg.name || null };
+  return { framework: "node-other", packageName: pkg.name || null, dependencies: Object.keys(deps).slice(0, 20) };
+}
+
+async function readEnv(root) {
+  const merged = {};
+  const filesFound = [];
+  for (const name of ENV_FILES) {
+    const raw = await readIfThere(path.join(root, name));
+    if (raw === null) continue;
+    filesFound.push(name);
+    Object.assign(merged, parseEnv(raw));
+  }
+  return { filesFound, values: merged };
+}
+
+function detectStripe(env, pkgDeps) {
+  const secretKey = env.STRIPE_SECRET_KEY || env.STRIPE_API_KEY || env.STRIPE_SK || null;
+  const webhookSecret = env.STRIPE_WEBHOOK_SECRET || env.STRIPE_WEBHOOK_SIGNING_SECRET || null;
+  return {
+    sdkInstalled: Boolean(pkgDeps?.stripe),
+    secretKey: describeKey(secretKey),
+    webhookSecret: describeKey(webhookSecret),
+    /* The lifecycle pass may only ever run against a test-mode key. */
+    lifecycleTestable: Boolean(secretKey && !secretKey.includes("_live_")),
+    liveKeyPresent: Boolean(secretKey && secretKey.includes("_live_")),
+  };
+}
+
+function detectDatabase(env, pkgDeps) {
+  const supabaseUrl = env.SUPABASE_URL || env.NEXT_PUBLIC_SUPABASE_URL || null;
+  const postgresUrl = env.DATABASE_URL || env.POSTGRES_URL || env.POSTGRES_PRISMA_URL || null;
+  return {
+    kind: supabaseUrl ? "supabase" : postgresUrl ? "postgres" : "none-found",
+    supabase: supabaseUrl ? {
+      urlHost: (() => { try { return new URL(supabaseUrl).host; } catch { return "unparseable"; } })(),
+      /* Anonymous/publishable key is fine to use; service-role never is. Its
+         mere presence in an env file is worth telling the founder about. */
+      serviceRoleKeyPresentInEnv: Boolean(env.SUPABASE_SERVICE_ROLE_KEY || env.SUPABASE_SECRET_KEY),
+      publishableKeyPresent: Boolean(env.SUPABASE_ANON_KEY || env.NEXT_PUBLIC_SUPABASE_ANON_KEY || env.SUPABASE_PUBLISHABLE_KEY),
+    } : null,
+    postgresUrlPresent: Boolean(postgresUrl),
+    ormInstalled: pkgDeps?.prisma ? "prisma" : pkgDeps?.drizzle ? "drizzle" : pkgDeps?.["drizzle-orm"] ? "drizzle" : null,
+  };
+}
+
+/* Walk the source tree once, collecting every file that mentions Stripe.
+   Bounded: skips build output and gives up past a sane file count so a huge
+   monorepo cannot hang the Check. */
+async function collectSourceFiles(root, limit = 4000) {
+  const files = [];
+  async function walk(dir, depth) {
+    if (depth > 8 || files.length >= limit) return;
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (files.length >= limit) return;
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name) && !entry.name.startsWith(".")) await walk(path.join(dir, entry.name), depth + 1);
+      } else if (/\.(ts|tsx|js|jsx|mjs)$/.test(entry.name)) {
+        files.push(path.join(dir, entry.name));
+      }
+    }
+  }
+  await walk(root, 0);
+  return files;
+}
+
+const REQUIRED_EVENTS = [
+  "checkout.session.completed",
+  "invoice.paid",
+  "invoice.payment_failed",
+  "customer.subscription.created",
+  "customer.subscription.updated",
+  "customer.subscription.deleted",
+  "charge.refunded",
+];
+
+async function findWebhookHandler(root, sourceFiles) {
+  const candidates = [];
+  for (const file of sourceFiles) {
+    const relative = path.relative(root, file);
+    const looksLikeRoute = /webhook|stripe/i.test(relative);
+    const content = await readIfThere(file);
+    if (!content) continue;
+    /* Must be a real call, not the word. A comment saying "no constructEvent
+       here" made an earlier version report the signature as verified — the
+       exact false pass this tool exists to catch in other people's code. */
+    const code = content.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\//g, "");
+    const mentionsConstruct = /constructEvent(Async)?\s*\(/.test(code);
+    const mentionsEvents = REQUIRED_EVENTS.filter((event) => code.includes(event));
+    if (!mentionsConstruct && mentionsEvents.length === 0 && !(looksLikeRoute && /stripe/i.test(content))) continue;
+
+    candidates.push({
+      file: relative,
+      verifiesSignature: mentionsConstruct,
+      /* constructEvent on a parsed body fails at runtime; the raw body is the
+         thing that must be verified. Heuristic, so it is reported as evidence
+         ("raw body handling not seen") rather than as a verdict. */
+      rawBodySeen: /req\.text\(\)|request\.text\(\)|rawBody|buffer\(|arrayBuffer\(|micro|bodyParser:\s*false|await buffer/.test(content),
+      handledEvents: mentionsEvents,
+      missingEvents: REQUIRED_EVENTS.filter((event) => !code.includes(event)),
+    });
+  }
+  candidates.sort((a, b) => (b.verifiesSignature - a.verifiesSignature) || (b.handledEvents.length - a.handledEvents.length));
+  return candidates;
+}
+
+/* The judgement problem: where does this app decide who has paid access?
+   We do not decide — we gather every plausible site with its evidence and let
+   the report (and eventually the founder) confirm. A ranked shortlist that is
+   honest about confidence beats a confident wrong answer. */
+const ACCESS_HINTS = [
+  { pattern: /\b(is_pro|isPro|is_premium|isPremium|is_paid|isPaid|has_access|hasAccess|is_subscribed|isSubscribed|subscribed)\b/, why: "boolean paid flag" },
+  { pattern: /\b(plan|tier|subscription_status|subscriptionStatus|subscription_tier)\b\s*(===?|!==?|\.eq\(|:)/, why: "plan/status comparison" },
+  { pattern: /\.from\(["'`](subscriptions|subscribers|entitlements|customers|profiles|users|accounts|billing)["'`]\)/, why: "reads a billing-ish table" },
+  { pattern: /\bstatus\s*===?\s*["'`](active|trialing|past_due|canceled)["'`]/, why: "compares a Stripe status value" },
+  { pattern: /getBillingEntitlement|billingEntitled/, why: "already has an entitlement function" },
+];
+
+async function findAccessDecisionSites(root, sourceFiles) {
+  const sites = [];
+  for (const file of sourceFiles) {
+    const content = await readIfThere(file);
+    if (!content) continue;
+    const relative = path.relative(root, file);
+    const reasons = ACCESS_HINTS.filter((hint) => hint.pattern.test(content)).map((hint) => hint.why);
+    if (!reasons.length) continue;
+    const clientSide = /["']use client["']/.test(content) || /components\/|hooks\//.test(relative) || /from ["']react["']/.test(content);
+    sites.push({
+      file: relative,
+      evidence: [...new Set(reasons)],
+      /* A paid gate that only exists in the browser can be bypassed by anyone
+         who opens devtools. Worth its own flag. */
+      clientSideOnly: clientSide,
+      score: reasons.length + (relative.includes("lib/") || relative.includes("server") || relative.includes("api/") ? 2 : 0) - (clientSide ? 1 : 0),
+    });
+  }
+  return sites.sort((a, b) => b.score - a.score).slice(0, 10);
+}
+
+export async function detect(root) {
+  const framework = await detectFramework(root);
+  const env = await readEnv(root);
+  const pkgRaw = await readIfThere(path.join(root, "package.json"));
+  let deps = {};
+  try { const pkg = JSON.parse(pkgRaw || "{}"); deps = { ...pkg.dependencies, ...pkg.devDependencies }; } catch { /* reported by detectFramework */ }
+
+  const stripe = detectStripe(env.values, deps);
+  const database = detectDatabase(env.values, deps);
+  const sourceFiles = await collectSourceFiles(root);
+  const webhookHandlers = await findWebhookHandler(root, sourceFiles);
+  const accessDecisionSites = await findAccessDecisionSites(root, sourceFiles);
+
+  return {
+    root,
+    scannedFiles: sourceFiles.length,
+    framework,
+    envFiles: env.filesFound,
+    stripe,
+    database,
+    webhookHandlers,
+    accessDecisionSites,
+    /* What downstream stages are possible, decided here in one place. */
+    capabilities: {
+      staticPass: true,
+      lifecyclePass: stripe.lifecycleTestable && webhookHandlers.length > 0,
+      liveSnapshot: stripe.liveKeyPresent || stripe.lifecycleTestable,
+      blockers: [
+        /* A found webhook handler IS evidence of a Stripe app, even when the
+           SDK arrives by URL import (Deno edge functions) and keys live in the
+           platform, not in env files. */
+        !stripe.sdkInstalled && !stripe.secretKey && webhookHandlers.length === 0 ? "No Stripe SDK or key found. Is this a Stripe-backed app?" : null,
+        stripe.liveKeyPresent && !stripe.lifecycleTestable ? "Only a LIVE Stripe key found. Lifecycle tests run only against test mode; add a test key." : null,
+        webhookHandlers.length === 0 ? "No Stripe webhook handler found." : null,
+        database.kind === "none-found" ? "No database connection found in env files." : null,
+      ].filter(Boolean),
+    },
+  };
+}