create-ailk 0.11.2 → 0.11.4

package/component-catalog.json

@@ -49,7 +49,7 @@
       "importPath": "@working-theory/templates/shells",
       "rootBarrel": "@working-theory/templates",
       "sourceRoot": "packages/templates/src/shells",
-      "count": 5
+      "count": 6
     },
     {
       "name": "docs-blog-blocks",
@@ -3015,6 +3015,17 @@
       "descriptionGrade": "weak",
       "sectionType": null
     },
+    {
+      "name": "SignedInShell",
+      "tier": "shells",
+      "sourcePath": "packages/templates/src/shells/SignedInShell.tsx",
+      "importPath": "@working-theory/templates/shells",
+      "exported": true,
+      "description": "Every AILK signed-in area runs on this frame: the admin app's workspace (AppFrame supplies its switcher, Library and gating as content) and a site's own /account area.",
+      "descriptionSource": "doc-comment",
+      "descriptionGrade": "strong",
+      "sectionType": null
+    },
     {
       "name": "DocsActionBar",
       "tier": "docs-blog-blocks",

package/component-catalog.md

@@ -15,13 +15,13 @@ The component inventory of `@working-theory/ui` and the shells of `@working-theo
 3. Check the Primitives, Panels and Shells tables too — a low-level control, a collapsible layout container, or a route-level frame lives there, not under Sections or Blocks.
 4. Only then build. If you do build, you are declaring the capability is genuinely absent.
 
-Inventory: **303 component files** across 16 tiers — 55 sections, 99 blocks, 18 chrome, 79 primitives, 6 panels, 5 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 5 scheduling-blocks, 3 signal-collectors-sections, 8 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 300 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
+Inventory: **304 component files** across 16 tiers — 55 sections, 99 blocks, 18 chrome, 79 primitives, 6 panels, 6 shells, 5 docs-blog-blocks, 1 docs-blog-chrome, 2 docs-blog-shells, 2 scheduling-sections, 5 scheduling-blocks, 3 signal-collectors-sections, 8 signal-collectors-blocks, 2 commerce-sections, 12 commerce-blocks, 1 commerce-panels. 301 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
 
-Description coverage: **299/303** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 224 from the component's own doc-comment header, 31 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
+Description coverage: **300/304** components carry a capability description derived from source — 44 from the section registry's hand-authored when-to-use text, 225 from the component's own doc-comment header, 31 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
 
-Of those, **268** are *strong* — a capability sentence you could match a requirement against — and **31** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
+Of those, **269** are *strong* — a capability sentence you could match a requirement against — and **31** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
 
-Per tier, strong out of total: **Sections** 54/55 · **Blocks** 93/99 · **Chrome** 10/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 4/5 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 5/5 · **Signal-Collectors Sections** 3/3 · **Signal-Collectors Blocks** 7/8 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
+Per tier, strong out of total: **Sections** 54/55 · **Blocks** 93/99 · **Chrome** 10/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 5/6 · **Shells** 5/6 · **Docs + Blog Blocks** 5/5 · **Docs + Blog Chrome** 1/1 · **Docs + Blog Shells** 0/2 · **Scheduling Sections** 2/2 · **Scheduling Blocks** 5/5 · **Signal-Collectors Sections** 3/3 · **Signal-Collectors Blocks** 7/8 · **Commerce Sections** 2/2 · **Commerce Blocks** 12/12 · **Commerce Panels** 1/1. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
 
 That grade is **mechanical**. It counts what it can measure — how much a description adds beyond the component's own name, how much of it is spent on wiring, whether the extraction came out damaged — and it cannot tell a fluent paragraph about the wrong subject from a useful one. A person reading these tables will find more rows unusable than the weak count admits. Treat it as a floor on the problem, not a measurement of it, and read the source before concluding a capability is absent.
 
@@ -365,7 +365,7 @@ Import: `import { X } from "@working-theory/ui/panels";` (or from the `@working-
 
 ---
 
-## Shells (5)
+## Shells (6)
 
 Route-level slot-frames — the outermost layout a page is placed into. They supply geometry and slots (nav / sidebar / main / footer), not content: you inject the real Nav, Footer and sidebar. A different package from every tier above: `@working-theory/templates`.
 
@@ -378,6 +378,7 @@ Import: `import { X } from "@working-theory/templates/shells";` (or from the `@w
 | `AuthShell` | The frame the five auth pages (/sign-in, /sign-up, /forgot-password, /reset-password, /verify-email) share: a brand mark top-start, one centered content column, and a slim footer. No nav — an auth page has nothing to navigate to, and the marketing Nav is exactly what this shell exists to replace on those routes. | `import { AuthShell } from "@working-theory/templates/shells"` |
 | `DeckHeroObserver` | Internal client island for MarketingShell's `deckHero` option. | internal — compose from `packages/templates/src/shells/DeckHeroObserver.tsx` |
 | `MarketingShell` | Public-facing marketing site **slot-frame**. Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* (top + bottom) and *where sections go* (the body), owning **geometry only**. Chrome (Nav/Footer) and sections **fill** the slots — nothing is baked into the component. See (first instance). *(weak)* | `import { MarketingShell } from "@working-theory/templates/shells"` |
+| `SignedInShell` | Every AILK signed-in area runs on this frame: the admin app's workspace (AppFrame supplies its switcher, Library and gating as content) and a site's own /account area. | `import { SignedInShell } from "@working-theory/templates/shells"` |
 
 ---
 

package/dist/surfaces.d.ts

@@ -162,11 +162,10 @@ export declare function surfaceForRouteDir(routeDir: string): string | undefined
  * file only when the target does not already have it — it never overwrites,
  * the same rule routes themselves follow.
  *
- * `(authed)/account` depending on two files INSIDE `(authed)/waitlist`
- * (`ForbiddenState.tsx`, `format.ts`) is real, found by reading the account
- * page's own imports, not guessed from the issue text: the account page
- * renders a shared "forbidden" empty state and shared count/date formatters
- * that the waitlist dashboard also uses, rather than duplicating them.
+ * Every list is read from the route's own imports, not guessed from issue
+ * text. `(authed)/account` no longer reaches into `(authed)/waitlist` (#7430):
+ * its layout renders the site's mark through `siteLogo()` on SignedInShell,
+ * so `site-logo.tsx` and the `site-brand.tsx` it reads travel with it.
  */
 export declare const ROUTE_DEPENDENCIES: Readonly<Record<string, readonly string[]>>;
 /**

package/dist/surfaces.js

@@ -609,6 +609,13 @@ export const ROUTE_SINCE = {
     // choice #5048's "projects/apply" entry already made for the same reason.
     "(authed)": "0.18.0",
     "(authed)/account": "0.18.0",
+    // #7430 — the base account area's three new route directories (spec 7423
+    // U4): item detail, User settings and Support. Genuinely new, so they
+    // attach at today's fixed-group version, the same rule #5977, #5678, #5479,
+    // #5371 and #5048 applied.
+    "(authed)/account/inbox/[kind]/[id]": "0.30.0",
+    "(authed)/account/settings": "0.30.0",
+    "(authed)/account/support": "0.30.0",
     // The leads inbox (#5678). The ROUTE ships in every scaffold, Free
     // included — lead capture is a never-gate surface, so reading a lead back
     // is one too. Whether it shows a ROW is a separate question with two
@@ -691,11 +698,10 @@ export function surfaceForRouteDir(routeDir) {
  * file only when the target does not already have it — it never overwrites,
  * the same rule routes themselves follow.
  *
- * `(authed)/account` depending on two files INSIDE `(authed)/waitlist`
- * (`ForbiddenState.tsx`, `format.ts`) is real, found by reading the account
- * page's own imports, not guessed from the issue text: the account page
- * renders a shared "forbidden" empty state and shared count/date formatters
- * that the waitlist dashboard also uses, rather than duplicating them.
+ * Every list is read from the route's own imports, not guessed from issue
+ * text. `(authed)/account` no longer reaches into `(authed)/waitlist` (#7430):
+ * its layout renders the site's mark through `siteLogo()` on SignedInShell,
+ * so `site-logo.tsx` and the `site-brand.tsx` it reads travel with it.
  */
 export const ROUTE_DEPENDENCIES = {
     // #5963 — the (auth) group's layout renders the brand mark through
@@ -715,12 +721,45 @@ export const ROUTE_DEPENDENCIES = {
     "(auth)/sign-up": ["apps/web/lib/auth-env.ts"],
     "(auth)/forgot-password": ["apps/web/lib/auth-env.ts"],
     "(auth)/reset-password": ["apps/web/lib/auth-env.ts"],
-    "(authed)": ["apps/web/auth.ts", "apps/web/lib/auth-env.ts"],
+    // #7430 — the group's layout reads `isAccountPath()` to give the account
+    // area its member-facing signed-out gate.
+    "(authed)": [
+        "apps/web/auth.ts",
+        "apps/web/lib/auth-env.ts",
+        "apps/web/lib/auth-routes.ts",
+    ],
     "(authed)/account": [
         "apps/web/lib/account-config.ts",
         "apps/web/lib/server-api.ts",
-        `${ROUTE_ROOT}/(authed)/waitlist/components/ForbiddenState.tsx`,
-        `${ROUTE_ROOT}/(authed)/waitlist/format.ts`,
+        "apps/web/lib/site-brand.tsx",
+        "apps/web/lib/site-logo.tsx",
+    ],
+    // #7430 — the three child routes also import files in their PARENT's
+    // directory. A scaffold whose `(authed)/account` predates #7430 keeps its
+    // own copy of that route (sync-routes never overwrites), so the files the
+    // children need travel with them: each is new in #7430, never a changed
+    // file sync-routes could not update.
+    "(authed)/account/inbox/[kind]/[id]": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/server-api.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
+        `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
+    ],
+    "(authed)/account/settings": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/auth-env.ts",
+        "apps/web/lib/server-api.ts",
+        "apps/web/lib/site-brand.tsx",
+        "apps/web/lib/site-theme.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/support-actions.ts`,
+    ],
+    "(authed)/account/support": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/server-api.ts",
+        `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
+        `${ROUTE_ROOT}/(authed)/account/support-actions.ts`,
     ],
     "(authed)/admin": [
         "apps/web/lib/server-api.ts",
@@ -773,6 +812,9 @@ export const ROUTE_MESSAGE_NAMESPACES = {
     "(auth)/reset-password": ["auth"],
     "(auth)/verify-email": ["auth"],
     "(authed)/account": ["account"],
+    "(authed)/account/inbox/[kind]/[id]": ["account"],
+    "(authed)/account/settings": ["account"],
+    "(authed)/account/support": ["account"],
     "(authed)/admin": ["admin"],
     "(authed)/leads": ["leadsInbox"],
     // #5977 — every string on both editor routes comes from the `edit`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,8 +27,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.30.0",
-    "@working-theory/templates": "0.30.0"
+    "@working-theory/schema": "0.32.0",
+    "@working-theory/templates": "0.32.0"
   },
   "repository": {
     "type": "git",

package/templates/.env.example

@@ -449,6 +449,35 @@ CONTENT_ADAPTER=mdx
 # API is not on localhost.
 # AILK_API_URL=http://localhost:3001
 #
+# Hub and spokes — per-visitor lead limits (#7394). When one apps/api (the
+# hub) is the lead sink for several apps/web sites (spokes) that call it
+# server-to-server through AILK_API_URL, every visitor of a spoke arrives at
+# the hub from the spoke's one egress IP. A spoke holding a hub-issued key
+# forwards the visitor's IP on its three lead writes (contact, newsletter,
+# callback), and the hub counts each visitor separately. Runbook:
+# docs/runbooks/site-configuration.md § Hub and spokes: per-visitor lead
+# limits. All four unset = the behaviour before #7394.
+#
+# HUB (apps/api). One key per spoke, comma-separated; each at least 32
+# characters (mint with `openssl rand -hex 32`). A shorter entry is ignored
+# with a warning naming its position. A key's position identifies its spoke
+# in the rate-limit log: to revoke one, BLANK its entry (`k1,,k3`) rather
+# than deleting it, so no other key changes position.
+# AILK_VISITOR_FORWARD_KEYS=
+#
+# HUB (apps/api). The leads scope's per-visitor limit per minute, and each
+# key's own ceiling per minute across all of its visitors. Whole numbers from
+# 1 to 999999; an invalid value is ignored with a warning. Defaults: 10 and
+# 300.
+# AILK_RATE_LIMIT_LEADS_PER_MINUTE=10
+# AILK_RATE_LIMIT_LEADS_PER_KEY_PER_MINUTE=300
+#
+# SPOKE (apps/web, server-only — never NEXT_PUBLIC_). This spoke's key: one
+# entry of the hub's AILK_VISITOR_FORWARD_KEYS. Sent only when AILK_API_URL
+# is https (or loopback). Issue a key only to a spoke whose platform
+# overwrites x-forwarded-for / x-real-ip with the real client address.
+# AILK_VISITOR_FORWARD_KEY=
+#
 # NEXT_PUBLIC_ENABLED_LOCALES — do NOT set by hand. Baked at build time by
 # apps/web/next.config.mjs from project.yaml `product.locales` (falls back to
 # "en" when project.yaml is absent) and read by middleware.ts, the sitemap

package/templates/apps/api/src/__tests__/leads-forwarded-rate-limit.test.ts

@@ -0,0 +1,135 @@
+/**
+ * @file leads-forwarded-rate-limit.test.ts
+ * @description #7394 AC-7 — a keyed spoke's lead writes are limited per
+ * visitor end to end, through the real `build()` and the REAL
+ * `@fastify/rate-limit` global ceiling.
+ *
+ * `server.test.ts` (and ten other `apps/api` files) replace
+ * `@fastify/rate-limit` with a no-op for the whole file, so none of them can
+ * observe the global ceiling. This file does not mock it. It mocks only the
+ * two boundaries `server.test.ts` mocks for infrastructure reasons:
+ * `@fastify/cors` and `@working-theory/email` (an ESM-only transitive dep).
+ *
+ * `DATABASE_URL` is unset for the file's duration, so a lead write takes the
+ * zero-config path, where the route refuses the empty body `{}` with a 400
+ * before any write. With the setup file's placeholder `DATABASE_URL`, the
+ * route would first try to resolve the site's workspace against a database
+ * this test does not have. The limiter runs on `onRequest`, before either.
+ *
+ * Every request comes from one `x-forwarded-for` — the spoke host. Each
+ * sub-case gets a fresh `build()` after `__resetBuckets()`, so neither the
+ * in-house buckets nor the plugin's own in-memory store carry over.
+ *
+ * Spec: docs/specs/7394-the-leads-rate-limit-scope-spec.md §5.1 AC-7.
+ */
+
+import { __resetBuckets } from "../middleware/rate-limit";
+import { build } from "../server";
+
+jest.mock("@fastify/cors", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+const KEY = "0123456789abcdef".repeat(4); // gitleaks:allow — test fixture, not a credential (#7394)
+const SPOKE_HOST = "198.51.100.7";
+
+/** A distinct, valid visitor IP per index. */
+function visitor(i: number): string {
+  return `203.0.${Math.floor(i / 250)}.${(i % 250) + 1}`;
+}
+
+function headersFor(
+  visitorIp: string,
+  withKey: boolean,
+): Record<string, string> {
+  return {
+    "x-forwarded-for": SPOKE_HOST,
+    "x-ailk-visitor-ip": visitorIp,
+    ...(withKey && { "x-ailk-visitor-forward-key": KEY }),
+  };
+}
+
+describe("leads rate limit for a keyed spoke, against the real global ceiling (#7394 AC-7)", () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any matches server.test.ts
+  let app: any;
+  const prior = process.env.AILK_VISITOR_FORWARD_KEYS;
+  const priorDatabaseUrl = process.env.DATABASE_URL;
+
+  async function statuses(
+    count: number,
+    request: (i: number) => {
+      method: string;
+      url: string;
+      headers: Record<string, string>;
+      payload?: unknown;
+    },
+  ): Promise<number[]> {
+    const codes: number[] = [];
+    for (let i = 0; i < count; i++) {
+      const res = await app.inject(request(i));
+      codes.push(res.statusCode);
+    }
+    return codes;
+  }
+
+  function leadWrite(visitorIp: string, withKey: boolean) {
+    return {
+      method: "POST",
+      url: "/v1/leads/submit",
+      headers: headersFor(visitorIp, withKey),
+      payload: {},
+    };
+  }
+
+  beforeEach(async () => {
+    __resetBuckets();
+    process.env.AILK_VISITOR_FORWARD_KEYS = KEY;
+    delete process.env.DATABASE_URL;
+    app = await build();
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+    app = undefined;
+  });
+
+  afterAll(() => {
+    if (prior === undefined) delete process.env.AILK_VISITOR_FORWARD_KEYS;
+    else process.env.AILK_VISITOR_FORWARD_KEYS = prior;
+    if (priorDatabaseUrl !== undefined)
+      process.env.DATABASE_URL = priorDatabaseUrl;
+  });
+
+  it("(a) 61 keyed lead writes from distinct visitors behind one spoke host: none is 429", async () => {
+    const codes = await statuses(61, (i) => leadWrite(visitor(i), true));
+    // The route refuses `{}` before any write, so every answer is that 400.
+    expect(codes.every((code) => code === 400)).toBe(true);
+  });
+
+  it("(b) 11 keyed lead writes from one visitor: the eleventh is 429", async () => {
+    const codes = await statuses(11, () => leadWrite("203.0.113.1", true));
+    expect(codes.slice(0, 10).every((code) => code === 400)).toBe(true);
+    expect(codes[10]).toBe(429);
+  });
+
+  it("(c) 11 unkeyed lead writes from distinct visitors: the eleventh is 429", async () => {
+    const codes = await statuses(11, (i) => leadWrite(visitor(i), false));
+    expect(codes.slice(0, 10).every((code) => code === 400)).toBe(true);
+    expect(codes[10]).toBe(429);
+  });
+
+  it("(d) 61 keyed GET /health from distinct visitors: the global ceiling still keys on the spoke host", async () => {
+    const codes = await statuses(61, (i) => ({
+      method: "GET",
+      url: "/health",
+      headers: headersFor(visitor(i), true),
+    }));
+    expect(codes[59]).toBe(200);
+    expect(codes[60]).toBe(429);
+  });
+});

package/templates/apps/api/src/__tests__/vercel-handler.test.ts

@@ -15,6 +15,11 @@
  *    string) instead of response.rawPayload corrupts any non-UTF-8 response
  *    by substituting U+FFFD for every invalid byte.
  *
+ * #7440 extends the request side: the adapter must forward the RAW bytes the
+ * client sent, not the parsed `req.body` — a signed webhook (Stripe, Slack,
+ * Cal.com) is verified over the exact bytes, and a re-serialization of the
+ * parse never matches a pretty-printed original.
+ *
  * The two request-side tests below drive a REAL minimal Fastify instance
  * through the handler — the defect lives inside Fastify's own
  * content-length check, so a mocked inject() cannot fail the way production
@@ -29,6 +34,9 @@
  * by every later test regardless of what that test wants build() to return.
  */
 
+import { createHmac } from 'node:crypto';
+import { PassThrough } from 'node:stream';
+
 import type { VercelRequest, VercelResponse } from '@vercel/node';
 import Fastify from 'fastify';
 
@@ -60,6 +68,47 @@ function asRequest(stub: MockVercelRequest): VercelRequest {
   return stub;
 }
 
+/**
+ * A body-carrying request the way the Vercel Node runtime hands it over: the
+ * runtime's helpers drain the stream to a Buffer, expose a lazily PARSED
+ * `req.body`, then replay the very same bytes through a PassThrough that only
+ * `on`/`addListener` for `data`/`end` reach (`restoreBody` in @vercel/node's
+ * serverless-functions helpers). The stub reproduces exactly that: an
+ * already-ended original stream with the replay patched over it, and `body`
+ * set to what the runtime's parser produced (`parsed`, default the JSON parse).
+ */
+function bodyRequest(fields: {
+  method?: string;
+  url: string;
+  headers: Record<string, string>;
+  raw: string;
+  parsed?: unknown;
+}): VercelRequest {
+  const original = new PassThrough();
+  original.end();
+  original.resume();
+  const replay = new PassThrough();
+  replay.end(Buffer.from(fields.raw));
+  const originalOn = original.on.bind(original);
+  const replayedOn = (name: string, cb: (...args: unknown[]) => void) =>
+    name === 'data' || name === 'end' ? replay.on(name, cb) : originalOn(name, cb);
+  const stub = Object.assign(original, {
+    read: replay.read.bind(replay),
+    on: replayedOn,
+    addListener: replayedOn,
+    method: fields.method ?? 'POST',
+    url: fields.url,
+    headers: fields.headers,
+    body: 'parsed' in fields ? fields.parsed : fields.raw ? JSON.parse(fields.raw) : {},
+    query: {},
+  });
+  // @ts-expect-error: a Readable carrying the fields above satisfies the
+  // subset of VercelRequest the handler reads (stream + method/url/headers/
+  // body/query); a full VercelRequest (extends http.IncomingMessage) cannot
+  // be constructed without a live connection.
+  return stub;
+}
+
 interface MockRes {
   headersSent: boolean;
   _status?: number;
@@ -134,19 +183,17 @@ describe('vercel-handler — request side: stale content-length (#5168)', () =>
 
     const body = { hello: 'world', nested: { a: 1 } };
     const pretty = JSON.stringify(body, null, 2);
-    const req: MockVercelRequest = {
-      method: 'POST',
+    const req = bodyRequest({
       url: '/echo',
       headers: {
         'content-type': 'application/json',
         'content-length': String(Buffer.byteLength(pretty)),
       },
-      body,
-      query: {},
-    };
+      raw: pretty,
+    });
     const res = makeRes();
 
-    await handler(asRequest(req), asResponse(res));
+    await handler(req, asResponse(res));
 
     expect(res._status).toBe(200);
     expect(JSON.parse(res._sent as string)).toEqual(body);
@@ -158,25 +205,199 @@ describe('vercel-handler — request side: stale content-length (#5168)', () =>
 
     const body = { hello: 'world' };
     const compactPlusNewline = JSON.stringify(body) + '\n';
-    const req: MockVercelRequest = {
-      method: 'POST',
+    const req = bodyRequest({
       url: '/echo',
       headers: {
         'content-type': 'application/json',
         'content-length': String(Buffer.byteLength(compactPlusNewline)),
       },
-      body,
-      query: {},
-    };
+      raw: compactPlusNewline,
+    });
     const res = makeRes();
 
-    await handler(asRequest(req), asResponse(res));
+    await handler(req, asResponse(res));
 
     expect(res._status).toBe(200);
     expect(JSON.parse(res._sent as string)).toEqual(body);
   });
 });
 
+// ── #7440: the signed bytes reach the verifier ──────────────────────────────
+//
+// Stripe signs the ORIGINAL bytes of the event — pretty-printed JSON — and the
+// adapter used to forward the runtime's PARSED `req.body`, which inject()
+// re-serialized compactly, so verifyWebhookSignature could never match on a
+// Vercel deployment. These tests mount the REAL Stripe receiver behind the
+// same raw-buffer parser server.ts scopes to the webhooks sub-router, and sign
+// with the REAL verifier's scheme — only the licence (commerce-claimed), the
+// analytics sink and Prisma are faked, none of which the verify path reads.
+
+jest.mock('@working-theory/license', () => ({
+  checkLicense: jest.fn().mockResolvedValue({
+    tier: 'pro',
+    plan: 'pro-monthly',
+    features: ['commerce'],
+    expiresAt: null,
+    revoked: false,
+  }),
+  readStoredJwtState: jest.fn(),
+}));
+jest.mock('@working-theory/analytics/server', () => ({
+  track: jest.fn().mockResolvedValue(undefined),
+}));
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock('../lib/prisma.js');
+
+/** Stripe's v1 scheme: `t=<ts>,v1=<hex HMAC-SHA256(secret, "<ts>.<payload>")>`. */
+function stripeSignature(payload: string, secret: string): string {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const v1 = createHmac('sha256', secret).update(`${timestamp}.${payload}`).digest('hex');
+  return `t=${timestamp},v1=${v1}`;
+}
+
+describe('vercel-handler — raw bytes reach webhook verification (#7440)', () => {
+  let app: ReturnType<typeof Fastify>;
+
+  beforeEach(async () => {
+    jest.resetModules();
+    const { stripeWebhookHandler } = require('../routes/webhooks/stripe');
+    app = Fastify();
+    await app.register(async (webhooksScope) => {
+      webhooksScope.addContentTypeParser(
+        'application/json',
+        { parseAs: 'buffer' },
+        (_req, body, done) => {
+          done(null, body);
+        },
+      );
+      webhooksScope.addContentTypeParser(
+        'application/x-www-form-urlencoded',
+        { parseAs: 'buffer' },
+        (_req, body, done) => {
+          done(null, body);
+        },
+      );
+      webhooksScope.post('/v1/webhooks/stripe', stripeWebhookHandler);
+      webhooksScope.post('/v1/form-echo', async (req) => ({
+        raw: Buffer.isBuffer(req.body) ? req.body.toString('utf8') : null,
+      }));
+    });
+    app.post('/echo', async (req) => req.body);
+    await app.ready();
+    jest.doMock('../server', () => ({ build: jest.fn().mockResolvedValue(app) }));
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  function webhookSecret(): string {
+    const { config } = require('../config') as { config: { STRIPE_WEBHOOK_SECRET?: string } };
+    if (!config.STRIPE_WEBHOOK_SECRET) throw new Error('test setup sets STRIPE_WEBHOOK_SECRET');
+    return config.STRIPE_WEBHOOK_SECRET;
+  }
+
+  it('verifies a Stripe-signed, pretty-printed event and returns 200', async () => {
+    const handler = loadHandler();
+    // Stripe's own delivery format: indent=2, as every webhook body arrives.
+    const event = JSON.stringify(
+      {
+        id: 'evt_7440_pretty_printed',
+        object: 'event',
+        type: 'test.helper.unhandled',
+        created: 1_759_000_000,
+        data: { object: { id: 'obj_7440' } },
+      },
+      null,
+      2,
+    );
+    const req = bodyRequest({
+      url: '/v1/webhooks/stripe',
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': String(Buffer.byteLength(event)),
+        'stripe-signature': stripeSignature(event, webhookSecret()),
+      },
+      raw: event,
+    });
+    const res = makeRes();
+
+    await handler(req, asResponse(res));
+
+    expect(res._status).toBe(200);
+    expect(JSON.parse(String(res._sent))).toEqual({ received: true });
+  });
+
+  it('still rejects a body that differs from the signed bytes', async () => {
+    const handler = loadHandler();
+    const signed = JSON.stringify({ id: 'evt_7440_tampered', type: 'test.helper' }, null, 2);
+    const sent = signed.replace('evt_7440_tampered', 'evt_7440_tampereD');
+    const req = bodyRequest({
+      url: '/v1/webhooks/stripe',
+      headers: {
+        'content-type': 'application/json',
+        'stripe-signature': stripeSignature(signed, webhookSecret()),
+      },
+      raw: sent,
+    });
+    const res = makeRes();
+
+    await handler(req, asResponse(res));
+
+    expect(res._status).toBe(400);
+    expect(JSON.parse(String(res._sent))).toEqual({ error: 'signature-invalid' });
+  });
+
+  it('forwards a urlencoded body byte-for-byte to the raw-buffer scope (Slack)', async () => {
+    const handler = loadHandler();
+    const form = 'payload=%7B%22type%22%3A%22block_actions%22%7D&token=abc';
+    const req = bodyRequest({
+      url: '/v1/form-echo',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      raw: form,
+      parsed: { payload: '{"type":"block_actions"}', token: 'abc' },
+    });
+    const res = makeRes();
+
+    await handler(req, asResponse(res));
+
+    expect(res._status).toBe(200);
+    expect(JSON.parse(String(res._sent))).toEqual({ raw: form });
+  });
+
+  // The fallback re-serializes `{}` (2 bytes) against a declared length of 0,
+  // so this also guards the content-length strip (#5168).
+  it('keeps an empty JSON POST answering as it did (the runtime parse, `{}`)', async () => {
+    const handler = loadHandler();
+    const req = bodyRequest({
+      url: '/echo',
+      headers: { 'content-type': 'application/json', 'content-length': '0' },
+      raw: '',
+    });
+    const res = makeRes();
+
+    await handler(req, asResponse(res));
+
+    expect(res._status).toBe(200);
+    expect(JSON.parse(String(res._sent))).toEqual({});
+  });
+
+  it('keeps a POST with no content-type bodiless, as the runtime forwarded it', async () => {
+    const handler = loadHandler();
+    const req = bodyRequest({
+      url: '/echo',
+      headers: { 'content-length': '5' },
+      raw: 'hello',
+      parsed: undefined,
+    });
+    const res = makeRes();
+
+    await handler(req, asResponse(res));
+
+    expect(res._status).toBe(200);
+  });
+});
+
 describe('vercel-handler — response side: binary round-trip (#5168)', () => {
   beforeEach(() => {
     jest.resetModules();