create-ailk 0.22.0 → 0.23.0

package/templates/apps/api/src/bin/stripe-connections-rekey.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/* istanbul ignore file -- CLI bootstrap; rekeyStripeConnections and
+   formatRekeyReport are unit-tested in
+   services/offerings/__tests__/connection.test.ts. */
+/**
+ * Re-encrypt every Organization Stripe connection under the current
+ * STRIPE_CONNECTION_KEY (#8907 D13, contract C10).
+ *
+ * Dev: `pnpm --filter @working-theory/api stripe-connections:rekey` (tsx,
+ * this file). Production: `node dist/bin/stripe-connections-rekey.js`.
+ *
+ * The rotation: set STRIPE_CONNECTION_KEY_PREVIOUS to the old key and the new
+ * key as STRIPE_CONNECTION_KEY, redeploy, run this, and unset _PREVIOUS once
+ * it prints `remaining=0`. A row counted `unreadable` decrypts under neither
+ * key; its owner reconnects or disconnects. A second run rekeys nothing.
+ *
+ * Run it with the production environment — `VERCEL_ENV=production`, or
+ * `NODE_ENV=production` off Vercel — the same predicate the API goes live on;
+ * anywhere else it prints `not_production`, reads nothing and exits 1.
+ *
+ * Prints one line of counts only — never a key, a value or a row id — and
+ * exits 1 when the key is not configured, off production, or the walk fails.
+ */
+import {
+  formatRekeyReport,
+  rekeyStripeConnections,
+} from "../services/offerings/connection.js";
+
+async function main(): Promise<void> {
+  const result = await rekeyStripeConnections();
+  if (!result.ok) {
+    console.error(formatRekeyReport(result));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(formatRekeyReport(result));
+}
+
+main().catch((err: unknown) => {
+  // The class name only: a store error's message is fixed, but nothing else
+  // a failure carries is printed.
+  const name = err instanceof Error ? err.name : "unknown";
+  console.error(`[stripe-connections-rekey] failed: ${name}`);
+  process.exitCode = 1;
+});

package/templates/apps/api/src/config/__tests__/stripe-connection-key.test.ts

@@ -0,0 +1,185 @@
+/**
+ * @file stripe-connection-key.test.ts
+ * @description STRIPE_CONNECTION_KEY and STRIPE_CONNECTION_KEY_PREVIOUS — the
+ * keys an Organization's Stripe connection is encrypted under (#8907 D3,
+ * AC-9; contract C3, C10).
+ *
+ * `resolveStripeConnectionKeys` reads both with the scheduling key's shape
+ * rule (canonical standard base64 of exactly 32 bytes), refuses a previous
+ * key with no current one or equal to it, and refuses either when it is the
+ * scheduling key — so one key never guards calendars and money. A refused
+ * key stops the API at startup; a refusal names the variable and the reason
+ * kind, never any part of the value. Unset is a supported state.
+ */
+
+// Mock dotenv so a developer's local .env never leaks into the config module.
+jest.mock("dotenv", () => ({
+  config: jest.fn(),
+}));
+
+const mockLoggerError = jest.fn();
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    warn: jest.fn(),
+    info: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveStripeConnectionKeys } from "../index";
+
+const A = randomBytes(32);
+const B = randomBytes(32);
+const S = randomBytes(32);
+const b64 = (bytes: Buffer) => bytes.toString("base64");
+
+/** 32 bytes whose base64 differs from its base64url, so the url form is refused. */
+function urlOnlyKey(): string {
+  let bytes = randomBytes(32);
+  while (!/[+/]/.test(bytes.toString("base64"))) bytes = randomBytes(32);
+  return bytes.toString("base64url");
+}
+
+describe("resolveStripeConnectionKeys (#8907 D3)", () => {
+  it("answers both buffers for two distinct canonical 32-byte keys", () => {
+    const result = resolveStripeConnectionKeys({ current: b64(A), previous: b64(B), scheduling: S });
+    expect(result.kind).toBe("ok");
+    if (result.kind !== "ok") throw new Error("expected ok");
+    expect(result.current?.equals(A)).toBe(true);
+    expect(result.previous?.equals(B)).toBe(true);
+  });
+
+  it("answers ok with nothing when both are unset or empty", () => {
+    expect(resolveStripeConnectionKeys({ current: undefined, previous: "", scheduling: S })).toEqual({
+      kind: "ok",
+    });
+  });
+
+  it("answers the current key alone with no previous", () => {
+    const result = resolveStripeConnectionKeys({ current: b64(A), previous: undefined, scheduling: undefined });
+    expect(result).toEqual({ kind: "ok", current: A });
+  });
+
+  const urlKey = urlOnlyKey();
+  const shortKey = b64(randomBytes(16));
+  it.each([
+    ["a base64url current key", { current: urlKey }, "STRIPE_CONNECTION_KEY", "not-canonical-base64", urlKey],
+    ["a 16-byte current key", { current: shortKey }, "STRIPE_CONNECTION_KEY", "length", shortKey],
+    [
+      "a 16-byte previous key",
+      { current: b64(A), previous: shortKey },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "length",
+      shortKey,
+    ],
+    [
+      "a previous key with no current",
+      { previous: b64(B) },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "previous_without_current",
+      b64(B),
+    ],
+    [
+      "equal current and previous",
+      { current: b64(A), previous: b64(A) },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "previous_equals_current",
+      b64(A),
+    ],
+    [
+      "a current key equal to the scheduling key",
+      { current: b64(S) },
+      "STRIPE_CONNECTION_KEY",
+      "shared_with_scheduling",
+      b64(S),
+    ],
+    [
+      "a previous key equal to the scheduling key",
+      { current: b64(A), previous: b64(S) },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "shared_with_scheduling",
+      b64(S),
+    ],
+  ])("refuses %s, naming the variable and the reason only", (_label, raw, variable, reason, value) => {
+    const result = resolveStripeConnectionKeys({
+      current: (raw as { current?: string }).current,
+      previous: (raw as { previous?: string }).previous,
+      scheduling: S,
+    });
+    expect(result).toEqual({ kind: "refused", variable, reason });
+    expect(JSON.stringify(result)).not.toContain(value.slice(0, 8));
+  });
+});
+
+describe("config.STRIPE_CONNECTION_KEY at startup (#8907 D3)", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+    delete process.env.AILK_ENABLED_MODULES;
+    delete process.env.AILK_TRUSTED_ORIGINS;
+    delete process.env.SCHEDULING_CREDENTIAL_KEY;
+    delete process.env.STRIPE_CONNECTION_KEY;
+    delete process.env.STRIPE_CONNECTION_KEY_PREVIOUS;
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    jest.restoreAllMocks();
+  });
+
+  it("exposes the decoded keys when they are valid, and nothing when unset", () => {
+    process.env.STRIPE_CONNECTION_KEY = b64(A);
+    process.env.STRIPE_CONNECTION_KEY_PREVIOUS = b64(B);
+    const { config } = require("../index");
+    expect(config.STRIPE_CONNECTION_KEY.equals(A)).toBe(true);
+    expect(config.STRIPE_CONNECTION_KEY_PREVIOUS.equals(B)).toBe(true);
+
+    jest.resetModules();
+    delete process.env.STRIPE_CONNECTION_KEY;
+    delete process.env.STRIPE_CONNECTION_KEY_PREVIOUS;
+    const { config: unset } = require("../index");
+    expect(unset.STRIPE_CONNECTION_KEY).toBeUndefined();
+    expect(unset.STRIPE_CONNECTION_KEY_PREVIOUS).toBeUndefined();
+  });
+
+  it.each([
+    ["a 31-byte key", { STRIPE_CONNECTION_KEY: b64(randomBytes(31)) }],
+    ["the scheduling key", { STRIPE_CONNECTION_KEY: b64(S), SCHEDULING_CREDENTIAL_KEY: b64(S) }],
+    ["a previous key alone", { STRIPE_CONNECTION_KEY_PREVIOUS: b64(B) }],
+  ])("exits on a refused value (%s), logging the variable but never the value", (_label, env) => {
+    Object.assign(process.env, env);
+    const exitSpy = jest.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("Process exit called");
+    });
+    const consoleError = jest.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(() => require("../index")).toThrow("Process exit called");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(mockLoggerError).toHaveBeenCalledTimes(1);
+
+    const logged = JSON.stringify([mockLoggerError.mock.calls, consoleError.mock.calls]);
+    expect(logged).toContain("STRIPE_CONNECTION_KEY");
+    for (const value of Object.values(env)) {
+      expect(logged).not.toContain(value);
+      expect(logged).not.toContain(value.slice(0, 12));
+    }
+  });
+});
+
+describe("the .env.example files (#8907 D3)", () => {
+  const REPO_ROOT = join(__dirname, "..", "..", "..", "..", "..");
+
+  it.each([".env.example", "apps/api/.env.example"])("%s documents both variables, commented out", (file) => {
+    const text = readFileSync(join(REPO_ROOT, file), "utf8");
+    expect(text).toMatch(/^# STRIPE_CONNECTION_KEY=$/m);
+    expect(text).toMatch(/^# STRIPE_CONNECTION_KEY_PREVIOUS=$/m);
+  });
+});

package/templates/apps/api/src/config/index.ts

@@ -112,6 +112,15 @@ export interface Config {
   // env-configured CAL_API_KEY path works exactly as before. Held decoded,
   // never as the raw string, and never logged.
   SCHEDULING_CREDENTIAL_KEY?: Buffer;
+  // An Organization's Stripe connection (#8907 D3, contract C3, C10) — the
+  // AES-256-GCM key services/offerings/connection.ts encrypts each
+  // connection's restricted key and webhook secret under, and the key it
+  // replaced during a rotation. The SCHEDULING_CREDENTIAL_KEY shape rule,
+  // checked at startup by resolveStripeConnectionKeys() below; a refused
+  // value stops the API. Optional: unset (or empty) means a connection can be
+  // read and removed but not written. Held decoded, never logged.
+  STRIPE_CONNECTION_KEY?: Buffer;
+  STRIPE_CONNECTION_KEY_PREVIOUS?: Buffer;
   // What a hub does with a request to a spoke-aware public surface (meeting
   // types, the three lead writes, booking, availability, event meta, the
   // public content reads) that carries no `x-ailk-spoke-key` (#7532 D7,
@@ -258,6 +267,82 @@ export function resolveSchedulingCredentialKey(
   return { kind: 'ok', key };
 }
 
+/** The two variables an Organization's Stripe connection key is read from (#8907 D3). */
+export type StripeConnectionKeyVariable =
+  | 'STRIPE_CONNECTION_KEY'
+  | 'STRIPE_CONNECTION_KEY_PREVIOUS';
+
+/** Why a Stripe connection key was refused (#8907 D3). */
+export type StripeConnectionKeyRefusal =
+  | SchedulingCredentialKeyRefusal
+  | 'previous_without_current'
+  | 'previous_equals_current'
+  | 'shared_with_scheduling';
+
+/**
+ * The Stripe connection keys (#8907 D3, contract C3, C10). Pure;
+ * `validateConfig()` calls it once.
+ *
+ * Each raw value is read with `resolveSchedulingCredentialKey`, the one shape
+ * rule. A previous key needs a current one, may not equal it, and neither may
+ * equal the scheduling key (`Buffer.equals`), so one key never guards both
+ * calendars and money. A refusal names the variable and the reason kind only,
+ * never any part of a value.
+ */
+export function resolveStripeConnectionKeys(input: {
+  current: string | undefined;
+  previous: string | undefined;
+  scheduling: Buffer | undefined;
+}):
+  | { kind: 'ok'; current?: Buffer; previous?: Buffer }
+  | {
+      kind: 'refused';
+      variable: StripeConnectionKeyVariable;
+      reason: StripeConnectionKeyRefusal;
+    } {
+  const current = resolveSchedulingCredentialKey(input.current);
+  if (current.kind === 'refused') {
+    return { kind: 'refused', variable: 'STRIPE_CONNECTION_KEY', reason: current.reason };
+  }
+  const previous = resolveSchedulingCredentialKey(input.previous);
+  if (previous.kind === 'refused') {
+    return { kind: 'refused', variable: 'STRIPE_CONNECTION_KEY_PREVIOUS', reason: previous.reason };
+  }
+  const currentKey = current.kind === 'ok' ? current.key : undefined;
+  const previousKey = previous.kind === 'ok' ? previous.key : undefined;
+  if (previousKey && !currentKey) {
+    return {
+      kind: 'refused',
+      variable: 'STRIPE_CONNECTION_KEY_PREVIOUS',
+      reason: 'previous_without_current',
+    };
+  }
+  if (previousKey && currentKey?.equals(previousKey)) {
+    return {
+      kind: 'refused',
+      variable: 'STRIPE_CONNECTION_KEY_PREVIOUS',
+      reason: 'previous_equals_current',
+    };
+  }
+  if (input.scheduling) {
+    if (currentKey?.equals(input.scheduling)) {
+      return { kind: 'refused', variable: 'STRIPE_CONNECTION_KEY', reason: 'shared_with_scheduling' };
+    }
+    if (previousKey?.equals(input.scheduling)) {
+      return {
+        kind: 'refused',
+        variable: 'STRIPE_CONNECTION_KEY_PREVIOUS',
+        reason: 'shared_with_scheduling',
+      };
+    }
+  }
+  return {
+    kind: 'ok',
+    ...(currentKey && { current: currentKey }),
+    ...(previousKey && { previous: previousKey }),
+  };
+}
+
 /**
  * `AILK_HUB_REQUIRE_SPOKE_KEY` (#7532 D7, #7633 D2): unset, empty or blank →
  * `"auto"`; `true`/`1` → `"on"`; `false`/`0` → `"off"` — case-insensitive,
@@ -364,6 +449,24 @@ function validateConfig(): Config {
     process.exit(1);
   }
 
+  // #8907 D3 — a set-but-refused Stripe connection key stops the API in every
+  // environment, for the scheduling key's reason; so does a key shared with
+  // the scheduling key or a previous key that could never be rotated away.
+  // The variable and the reason kind only, never a value.
+  const stripeConnectionKeys = resolveStripeConnectionKeys({
+    current: process.env.STRIPE_CONNECTION_KEY,
+    previous: process.env.STRIPE_CONNECTION_KEY_PREVIOUS,
+    scheduling: schedulingKey.kind === 'ok' ? schedulingKey.key : undefined,
+  });
+  if (stripeConnectionKeys.kind === 'refused') {
+    const { variable, reason } = stripeConnectionKeys;
+    const message =
+      '❌ STRIPE_CONNECTION_KEY and STRIPE_CONNECTION_KEY_PREVIOUS must each be canonical standard base64 of exactly 32 bytes (openssl rand -base64 32), distinct from each other and from SCHEDULING_CREDENTIAL_KEY, and a previous key needs a current one';
+    logger.error({ variable, reason }, message);
+    console.error(message, JSON.stringify({ variable, reason }));
+    process.exit(1);
+  }
+
   // #7532 D7, #7633 D2 — the hub's spoke-key mode. An unparseable value stops
   // the API: a typo read as "off" would silently leave the hub open to
   // header-less callers. The message names the variable, never its value.
@@ -479,6 +582,12 @@ function validateConfig(): Config {
     ...(schedulingKey.kind === 'ok' && {
       SCHEDULING_CREDENTIAL_KEY: schedulingKey.key,
     }),
+    ...(stripeConnectionKeys.current && {
+      STRIPE_CONNECTION_KEY: stripeConnectionKeys.current,
+    }),
+    ...(stripeConnectionKeys.previous && {
+      STRIPE_CONNECTION_KEY_PREVIOUS: stripeConnectionKeys.previous,
+    }),
     AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey,
     AILK_SPOKE_FLOW_SEED: spokeFlowSeed,
   };

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -203,6 +203,9 @@ export const prisma = {
     findFirst: jest.fn(),
     findMany: jest.fn(),
     updateMany: jest.fn(),
+    // `count` — the flow engine's completion-email caps (#8847 security
+    // review). Unarranged it resolves undefined, which caps nothing.
+    count: jest.fn(),
   },
   subscriber: {
     create: jest.fn(),

package/templates/apps/api/src/lib/__tests__/flow-rename-race.db.test.ts

@@ -0,0 +1,116 @@
+/**
+ * @file flow-rename-race.db.test.ts
+ *
+ * LIVE-DATABASE proof of #8734 AC-5 (spec
+ * docs/specs/8734-magnet-slug-renames-an-anonymous-spec.md D4): two renames
+ * racing for one free slug are serialized by `flow_definitions`'
+ * `(site_id, slug)` unique key. `flows.rename`'s first write is the
+ * definition row, so the second transaction's write waits on the first's
+ * uncommitted index entry and, once the first commits, fails with `23505` —
+ * which Prisma reports as `P2002` and `rename` answers `conflict`. The pre-
+ * checks run at READ COMMITTED and guarantee nothing here; the key does.
+ *
+ * Runs only when `AILK_TEST_LIVE_DATABASE === "1"` (set beside a real
+ * `DATABASE_URL` by `.github/workflows/api-postgres-compat.yml`), and uses the
+ * `pg` driver directly, the same reason `rate-limit-cross-isolate.db.test.ts`
+ * does: the generated Prisma client is ESM-only and cannot load under this
+ * package's CJS ts-jest transform.
+ */
+import { Client } from "pg";
+
+const describeDb =
+  process.env.AILK_TEST_LIVE_DATABASE === "1" ? describe : describe.skip;
+
+describeDb("flow_definitions' (site_id, slug) key serializes two renames to one slug (live, #8734 AC-5)", () => {
+  let first: Client;
+  let second: Client;
+  let workspaceId = "";
+  let rowA = "";
+  let rowB = "";
+
+  async function insertRow(slug: string): Promise<string> {
+    const res = await first.query<{ id: string }>(
+      `INSERT INTO "flow_definitions"
+         ("site_id", "workspace_id", "slug", "config", "kind", "title", "status", "customers_enabled", "updated_at")
+       VALUES ($1, $1, $2, '{}'::jsonb, 'contact', $2, 'draft', false, now())
+       RETURNING "id"`,
+      [workspaceId, slug],
+    );
+    return res.rows[0]!.id;
+  }
+
+  /** Until `pid`'s statement is blocked on a lock — the wait the key imposes. */
+  async function waitUntilBlocked(pid: number): Promise<void> {
+    for (let attempt = 0; attempt < 100; attempt++) {
+      const res = await first.query<{ wait_event_type: string | null }>(
+        `SELECT "wait_event_type" FROM pg_stat_activity WHERE "pid" = $1`,
+        [pid],
+      );
+      if (res.rows[0]?.wait_event_type === "Lock") return;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error("the second rename never waited on the first");
+  }
+
+  beforeAll(async () => {
+    first = new Client({ connectionString: process.env.DATABASE_URL });
+    second = new Client({ connectionString: process.env.DATABASE_URL });
+    await first.connect();
+    await second.connect();
+    const ws = await first.query<{ id: string }>(
+      `SELECT 'wksp_' || uuidv7()::text AS "id"`,
+    );
+    workspaceId = ws.rows[0]!.id;
+    rowA = await insertRow("race-a");
+    rowB = await insertRow("race-b");
+  });
+
+  afterAll(async () => {
+    await first.query(`DELETE FROM "flow_definitions" WHERE "workspace_id" = $1`, [
+      workspaceId,
+    ]);
+    await first.end();
+    await second.end();
+  });
+
+  it("the second rename to one slug waits on the first, then fails 23505 on flow_definitions_site_id_slug_key; one row holds the slug", async () => {
+    const rename = `UPDATE "flow_definitions" SET "slug" = 'race-x' WHERE "id" = $1`;
+    const secondPid = (await second.query<{ pid: number }>("SELECT pg_backend_pid() AS pid"))
+      .rows[0]!.pid;
+
+    let error: { code?: string; constraint?: string } | null | undefined;
+    try {
+      await first.query("BEGIN");
+      await first.query(rename, [rowA]);
+
+      await second.query("BEGIN");
+      // Not awaited: it blocks on the first transaction's uncommitted entry.
+      const loser = second.query(rename, [rowB]).then(
+        () => null,
+        (failure: unknown) => failure as { code?: string; constraint?: string },
+      );
+      await waitUntilBlocked(secondPid);
+
+      await first.query("COMMIT");
+      error = await loser;
+    } finally {
+      await first.query("ROLLBACK");
+      await second.query("ROLLBACK");
+    }
+
+    expect(error).toMatchObject({
+      code: "23505",
+      constraint: "flow_definitions_site_id_slug_key",
+    });
+    const atSlug = await first.query<{ count: string }>(
+      `SELECT count(*) AS "count" FROM "flow_definitions" WHERE "workspace_id" = $1 AND "slug" = 'race-x'`,
+      [workspaceId],
+    );
+    expect(atSlug.rows[0]!.count).toBe("1");
+    const b = await first.query<{ slug: string }>(
+      `SELECT "slug" FROM "flow_definitions" WHERE "id" = $1`,
+      [rowB],
+    );
+    expect(b.rows[0]!.slug).toBe("race-b");
+  });
+});

package/templates/apps/api/src/lib/error-serializer.ts

@@ -16,6 +16,7 @@
  *   - Leaves replies that handlers already committed (explicit status + body)
  *     untouched
  */
+import { idRegex } from "@working-theory/ids";
 import type { FastifyError, FastifyInstance } from "fastify";
 
 const GENERIC_INTERNAL_BODY = { error: "internal_error" } as const;
@@ -30,16 +31,82 @@ const GENERIC_INTERNAL_BODY = { error: "internal_error" } as const;
  * EVERY route. Logging the raw target would write that credential into the
  * API's own log the moment anything went wrong, which is precisely when logs
  * get read, copied into tickets, and shipped to third parties.
- *
- * The path itself is kept: it is what makes the line useful, and a route
- * parameter like `:id` is an identifier rather than a secret. The matching
- * strip lives on the Fastify logger's own `req` serializer in `server.ts`.
  */
 function pathWithoutQuery(url: string): string {
   const queryAt = url.indexOf("?");
   return queryAt === -1 ? url : url.slice(0, queryAt);
 }
 
+/**
+ * #6084 D14 — `GET /v1/checkout/sessions/:id` puts its credential in the
+ * PATH, so a `cs_…`-shaped segment is truncated to its first 8 characters
+ * plus `…` (a path SEGMENT rule, never a substring replace, so it cannot
+ * corrupt an unrelated URL). #6216 D11 adds the same arm for `lead_…`
+ * segments and #8438 SEC-8438-10 for `person_…` segments, which would
+ * otherwise put a full id beside `remoteAddress`.
+ */
+const SESSION_ID_LOG_SEGMENT = /^cs_[A-Za-z0-9_]+$/;
+const LEAD_ID_LOG_SEGMENT = idRegex("lead");
+const PERSON_ID_LOG_SEGMENT = idRegex("person");
+
+/**
+ * #8932 D10 (contract W9) — a webhook connection token is the per-connection
+ * receiver's routing credential (`/v1/webhooks/<provider>/:connectionToken`).
+ * Every segment after the provider is replaced by one literal
+ * `:connectionToken`, keeping no prefix — unlike the id arms above — and
+ * empty segments are dropped first, so a trailing slash, a double slash or a
+ * mis-pasted extra segment cannot carry the token past the rule.
+ */
+const CONNECTION_TOKEN_PLACEHOLDER = ":connectionToken";
+
+/** A segment as the router matches it: percent-decoded, or raw when it does not decode. */
+function decodedSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+function redactConnectionToken(path: string): string | null {
+  // Compared DECODED: the router decodes before it matches, so
+  // `/v1/%77ebhooks/stripe/<token>` reaches the token route and must be
+  // redacted like its plain spelling.
+  const segments = path
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodedSegment);
+  if (segments.length < 4 || segments[0] !== "v1" || segments[1] !== "webhooks") {
+    return null;
+  }
+  return `/${segments.slice(0, 3).join("/")}/${CONNECTION_TOKEN_PLACEHOLDER}`;
+}
+
+/**
+ * The ONE path redactor for a log line (#8932 D10): the query string dropped,
+ * a webhook connection token replaced whole, and every `cs_…`, `lead_…` and
+ * `person_…` segment truncated. The Fastify request serializer (`server.ts`)
+ * and this handler's three `path:` fields both call it, so a 429, 413, 415 or
+ * 5xx on a token route logs the same redacted path its request line does.
+ * A route parameter that is an identifier rather than a secret — `:id` — is
+ * kept: it is what makes the line useful.
+ */
+export function redactLogPath(url: string): string {
+  const path = pathWithoutQuery(url);
+  const tokenless = redactConnectionToken(path);
+  if (tokenless !== null) return tokenless;
+  return path
+    .split("/")
+    .map((segment) =>
+      SESSION_ID_LOG_SEGMENT.test(segment) ||
+      LEAD_ID_LOG_SEGMENT.test(segment) ||
+      PERSON_ID_LOG_SEGMENT.test(segment)
+        ? `${segment.slice(0, 8)}…`
+        : segment,
+    )
+    .join("/");
+}
+
 export function registerErrorSerializer(server: FastifyInstance): void {
   server.setErrorHandler(async (err: FastifyError, request, reply) => {
     // Validation errors (Fastify's schema validator) — keep structured detail.
@@ -49,7 +116,7 @@ export function registerErrorSerializer(server: FastifyInstance): void {
       request.log.warn(
         {
           method: request.method,
-          path: pathWithoutQuery(request.url),
+          path: redactLogPath(request.url),
           validation: err.validation,
         },
         "request validation failed",
@@ -68,7 +135,7 @@ export function registerErrorSerializer(server: FastifyInstance): void {
       request.log.info(
         {
           method: request.method,
-          path: pathWithoutQuery(request.url),
+          path: redactLogPath(request.url),
           statusCode: status,
           errName: err.name,
         },
@@ -83,7 +150,7 @@ export function registerErrorSerializer(server: FastifyInstance): void {
     request.log.error(
       {
         method: request.method,
-        path: pathWithoutQuery(request.url),
+        path: redactLogPath(request.url),
         errName: err.name,
         errMessage: err.message,
         errStack: err.stack,