create-ailk 0.5.0 → 0.6.0

package/templates/apps/api/src/services/__tests__/request-confirm.test.ts

@@ -0,0 +1,444 @@
+/**
+ * request-confirm.ts (#5970) — the credential, the configuration and the
+ * capture-side send.
+ *
+ * The Prisma boundary is the repo-standard `__mocks__/prisma.ts` double; the
+ * email package is mocked at the PACKAGE boundary (never at an internal
+ * module), the shape every service suite in this directory uses.
+ */
+
+const mockSendRequestConfirmEmail = jest.fn();
+const mockSendLeadNotification = jest.fn();
+
+jest.mock("@working-theory/email", () => ({
+  sendRequestConfirmEmail: (...args: unknown[]) =>
+    mockSendRequestConfirmEmail(...args),
+  sendRequestPaidLinkEmail: jest.fn(),
+  sendLeadNotification: (...args: unknown[]) =>
+    mockSendLeadNotification(...args),
+}));
+
+// 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");
+
+import { prisma } from "../../lib/prisma.js";
+import { routeLead } from "../lead-routing.js";
+import {
+  CONFIRM_TOKEN_TTL_MS,
+  claimConfirmation,
+  confirmLinkFor,
+  hashConfirmToken,
+  recordPaymentLink,
+  requestConfirmConfig,
+  requestConfirmSupersedesNotification,
+  resolveConfirmableRequest,
+  sendRequestConfirmLink,
+} from "../request-confirm.js";
+
+const CALLBACK_ID = "callbk_0000000000000001";
+const REQUEST = { name: "Ada Lovelace", phone: "+44 7700 900000" };
+
+/** Turn the fire-and-forget `void` entry point into something awaitable. */
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+const ENV_KEYS = [
+  "AILK_REQUEST_CONFIRM_ENABLED",
+  "AILK_REQUEST_CONFIRM_TO",
+  "AILK_REQUEST_CONFIRM_FROM",
+  "AILK_REQUEST_CONFIRM_CURRENCY",
+  "AILK_REQUEST_CONFIRM_MAX_MINOR",
+  "AILK_LEAD_NOTIFICATION_TO",
+  "AILK_LEAD_NOTIFICATION_FROM",
+  "AILK_PUBLIC_API_URL",
+  "AILK_ENABLED_MODULES",
+] as const;
+
+function enable(overrides: Record<string, string | undefined> = {}) {
+  process.env["AILK_REQUEST_CONFIRM_ENABLED"] = "true";
+  process.env["AILK_REQUEST_CONFIRM_TO"] = "owner@example.com";
+  process.env["AILK_REQUEST_CONFIRM_FROM"] = "hello@example.com";
+  process.env["AILK_PUBLIC_API_URL"] = "https://api.example.com";
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  for (const key of ENV_KEYS) delete process.env[key];
+  mockSendRequestConfirmEmail.mockResolvedValue({ ok: true, messageId: "m1" });
+  mockSendLeadNotification.mockResolvedValue({ ok: true, messageId: "m0" });
+  (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.callback.update as jest.Mock).mockResolvedValue({});
+  (prisma.callback.findFirst as jest.Mock).mockResolvedValue(null);
+});
+
+afterEach(() => {
+  for (const key of ENV_KEYS) delete process.env[key];
+});
+
+// ── The credential ─────────────────────────────────────────────────────────
+
+describe("the confirm credential", () => {
+  it("stores a digest that is never the token itself", async () => {
+    enable();
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+
+    const stored = (prisma.callback.updateMany as jest.Mock).mock.calls[0][0];
+    const link = mockSendRequestConfirmEmail.mock.calls[0][0]
+      .confirmLink as string;
+    const token = new URL(link).searchParams.get("token")!;
+
+    expect(token).toHaveLength(43); // 32 CSPRNG bytes, base64url
+    expect(stored.data.confirmTokenHash).toBe(hashConfirmToken(token));
+    expect(stored.data.confirmTokenHash).not.toBe(token);
+    // The mint guard is what makes the credential one-per-row — and
+    // `confirmedAt: null` beside it is what stops a fresh credential landing
+    // on an ALREADY-CONFIRMED row, whose digest is also null (#5970 security
+    // review, § 8).
+    expect(stored.where).toEqual({
+      id: CALLBACK_ID,
+      confirmTokenHash: null,
+      confirmedAt: null,
+    });
+  });
+
+  it("expires the credential seven days out", async () => {
+    enable();
+    const before = Date.now();
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+
+    const stored = (prisma.callback.updateMany as jest.Mock).mock.calls[0][0];
+    const expiry = (stored.data.confirmTokenExpiresAt as Date).getTime();
+    expect(CONFIRM_TOKEN_TTL_MS).toBe(7 * 24 * 60 * 60 * 1000);
+    expect(expiry).toBeGreaterThanOrEqual(before + CONFIRM_TOKEN_TTL_MS);
+    expect(expiry).toBeLessThanOrEqual(Date.now() + CONFIRM_TOKEN_TTL_MS);
+  });
+
+  it("mints a different token every time", async () => {
+    enable();
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+    const [a, b] = mockSendRequestConfirmEmail.mock.calls.map(
+      (call) => call[0].confirmLink as string,
+    );
+    expect(a).not.toBe(b);
+  });
+
+  it("builds the confirm link on the API's own origin, token percent-encoded", () => {
+    const link = confirmLinkFor(
+      "https://api.example.com",
+      CALLBACK_ID,
+      "a+b/c=",
+    );
+    const url = new URL(link);
+    expect(url.origin).toBe("https://api.example.com");
+    expect(url.pathname).toBe(`/v1/requests/${CALLBACK_ID}/confirm`);
+    expect(url.searchParams.get("token")).toBe("a+b/c=");
+    expect(url.search).not.toContain("a+b/c=");
+  });
+});
+
+// ── Resolution: the four refusals are indistinguishable ────────────────────
+
+describe("resolveConfirmableRequest()", () => {
+  it("puts the id, the digest, the expiry and the not-confirmed predicate in one where", async () => {
+    await resolveConfirmableRequest(CALLBACK_ID, "tok");
+    const call = (prisma.callback.findFirst as jest.Mock).mock.calls[0][0];
+    expect(call.where.id).toBe(CALLBACK_ID);
+    expect(call.where.confirmTokenHash).toBe(hashConfirmToken("tok"));
+    expect(call.where.confirmedAt).toBeNull();
+    expect(call.where.confirmTokenExpiresAt.gt).toBeInstanceOf(Date);
+  });
+
+  it("returns null when nothing matches — a tampered, expired, spent or cross-row token alike", async () => {
+    (prisma.callback.findFirst as jest.Mock).mockResolvedValue(null);
+    await expect(
+      resolveConfirmableRequest(CALLBACK_ID, "wrong"),
+    ).resolves.toBeNull();
+  });
+});
+
+// ── Claiming: verification and stamping in one guarded update ──────────────
+
+describe("claimConfirmation()", () => {
+  const CLAIM = {
+    id: CALLBACK_ID,
+    token: "tok",
+    confirmedTime: "Tuesday 9am",
+    buyerEmail: "buyer@example.com",
+    amountMinor: 12900,
+    currency: "usd",
+  };
+
+  it("carries the same four predicates the resolver does, and spends the credential", async () => {
+    await expect(claimConfirmation(CLAIM)).resolves.toBe(true);
+    const call = (prisma.callback.updateMany as jest.Mock).mock.calls[0][0];
+    expect(call.where.id).toBe(CALLBACK_ID);
+    expect(call.where.confirmTokenHash).toBe(hashConfirmToken("tok"));
+    expect(call.where.confirmedAt).toBeNull();
+    expect(call.where.confirmTokenExpiresAt.gt).toBeInstanceOf(Date);
+    expect(call.data.confirmedAt).toBeInstanceOf(Date);
+    expect(call.data.confirmedTime).toBe("Tuesday 9am");
+    expect(call.data.buyerEmail).toBe("buyer@example.com");
+    expect(call.data.amountMinor).toBe(12900);
+    expect(call.data.currency).toBe("usd");
+    // Spending the credential is in the SAME statement as the stamp.
+    expect(call.data.confirmTokenHash).toBeNull();
+  });
+
+  it("omits amount and currency when the caller resolved a catalogue price instead", async () => {
+    await claimConfirmation({
+      id: CALLBACK_ID,
+      token: "tok",
+      confirmedTime: "Tuesday 9am",
+      buyerEmail: "buyer@example.com",
+    });
+    const call = (prisma.callback.updateMany as jest.Mock).mock.calls[0][0];
+    expect(call.data).not.toHaveProperty("amountMinor");
+    expect(call.data).not.toHaveProperty("currency");
+  });
+
+  it("reports false when no row matched — the loser of a double-POST race", async () => {
+    (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    await expect(claimConfirmation(CLAIM)).resolves.toBe(false);
+  });
+});
+
+describe("recordPaymentLink()", () => {
+  it("writes the artifact id the webhook stamp matches on", async () => {
+    await recordPaymentLink(CALLBACK_ID, "plink_abc");
+    expect(prisma.callback.update).toHaveBeenCalledWith({
+      where: { id: CALLBACK_ID },
+      data: { stripePaymentLinkId: "plink_abc" },
+    });
+  });
+});
+
+// ── Configuration ──────────────────────────────────────────────────────────
+
+describe("requestConfirmConfig()", () => {
+  it("is null with the flag unset — the default every existing suite runs under", () => {
+    expect(requestConfirmConfig()).toBeNull();
+    expect(requestConfirmSupersedesNotification()).toBe(false);
+  });
+
+  it("is null when the flag is on but no recipient resolves", () => {
+    enable({ AILK_REQUEST_CONFIRM_TO: undefined });
+    expect(requestConfirmConfig()).toBeNull();
+  });
+
+  it("is null when the flag is on but no base URL resolves", () => {
+    enable({ AILK_PUBLIC_API_URL: undefined });
+    expect(requestConfirmConfig()).toBeNull();
+  });
+
+  it("falls back to the lead-notification pair for recipient and sender", () => {
+    enable({
+      AILK_REQUEST_CONFIRM_TO: undefined,
+      AILK_REQUEST_CONFIRM_FROM: undefined,
+      AILK_LEAD_NOTIFICATION_TO: "ops@example.com",
+      AILK_LEAD_NOTIFICATION_FROM: "noreply@example.com",
+    });
+    expect(requestConfirmConfig()).toMatchObject({
+      to: "ops@example.com",
+      from: "noreply@example.com",
+    });
+  });
+
+  it("is null on a MULTI-TENANT build, however completely it is configured", () => {
+    // #5970 security review, finding 3. Every value here is process-wide, as
+    // is STRIPE_SECRET_KEY — so on a multi-tenant deployment one tenant's
+    // customer would pay into the deployment's own Stripe account. The feature
+    // fails closed there rather than mis-routing money.
+    enable();
+    expect(requestConfirmConfig()).not.toBeNull();
+    process.env["AILK_ENABLED_MODULES"] = "multi-tenant,docs";
+    expect(requestConfirmConfig()).toBeNull();
+    // And because the notification predicate reads the same function, the
+    // generic lead notification is NOT suppressed on such a build — the
+    // callback path is byte-for-byte what it was before this feature.
+    expect(requestConfirmSupersedesNotification()).toBe(false);
+  });
+
+  it("caps the money-gate ceiling at the column's own limit", () => {
+    // `amount_minor` is a Postgres INTEGER. A ceiling above it would admit an
+    // amount that passes every check and then throws out of Prisma at write
+    // time — a 500 on a money path, from a configuration typo (§ 8).
+    enable({ AILK_REQUEST_CONFIRM_MAX_MINOR: "99999999999" });
+    expect(requestConfirmConfig()?.maxAmountMinor).toBe(2_147_483_647);
+  });
+
+  it("defaults the currency and the money-gate ceiling", () => {
+    enable();
+    expect(requestConfirmConfig()).toMatchObject({
+      currency: "usd",
+      maxAmountMinor: 1_000_000,
+    });
+  });
+
+  it("takes a configured currency and ceiling, and ignores ones that do not parse", () => {
+    enable({
+      AILK_REQUEST_CONFIRM_CURRENCY: "GBP",
+      AILK_REQUEST_CONFIRM_MAX_MINOR: "50000",
+    });
+    expect(requestConfirmConfig()).toMatchObject({
+      currency: "gbp",
+      maxAmountMinor: 50000,
+    });
+
+    // A ceiling that does not parse must not become NaN (which refuses every
+    // amount) or unbounded — it falls back to the platform default.
+    enable({ AILK_REQUEST_CONFIRM_MAX_MINOR: "lots" });
+    expect(requestConfirmConfig()?.maxAmountMinor).toBe(1_000_000);
+    enable({ AILK_REQUEST_CONFIRM_MAX_MINOR: "-5" });
+    expect(requestConfirmConfig()?.maxAmountMinor).toBe(1_000_000);
+  });
+});
+
+// ── The capture-side send ──────────────────────────────────────────────────
+
+describe("sendRequestConfirmLink()", () => {
+  it("writes no credential and sends nothing when the feature is off", async () => {
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+    expect(prisma.callback.updateMany).not.toHaveBeenCalled();
+    expect(mockSendRequestConfirmEmail).not.toHaveBeenCalled();
+  });
+
+  it("sends exactly one email, carrying the request's details, when configured", async () => {
+    enable();
+    sendRequestConfirmLink(CALLBACK_ID, {
+      ...REQUEST,
+      preferredTime: "Tuesday morning",
+    });
+    await flush();
+
+    expect(mockSendRequestConfirmEmail).toHaveBeenCalledTimes(1);
+    expect(mockSendRequestConfirmEmail.mock.calls[0][0]).toMatchObject({
+      to: "owner@example.com",
+      fromAddress: "hello@example.com",
+      request: {
+        name: "Ada Lovelace",
+        phone: "+44 7700 900000",
+        preferredTime: "Tuesday morning",
+      },
+    });
+  });
+
+  it("sends nothing when the row already carries a live credential", async () => {
+    enable();
+    (prisma.callback.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+    expect(mockSendRequestConfirmEmail).not.toHaveBeenCalled();
+  });
+
+  it("never throws when the email package reports a failure", async () => {
+    enable();
+    mockSendRequestConfirmEmail.mockResolvedValue({
+      ok: false,
+      error: { kind: "send_failed", message: "domain not verified" },
+    });
+    expect(() => sendRequestConfirmLink(CALLBACK_ID, REQUEST)).not.toThrow();
+    await flush();
+  });
+
+  it("never throws when the database write itself rejects", async () => {
+    enable();
+    (prisma.callback.updateMany as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+    expect(() => sendRequestConfirmLink(CALLBACK_ID, REQUEST)).not.toThrow();
+    await flush();
+    expect(mockSendRequestConfirmEmail).not.toHaveBeenCalled();
+  });
+});
+
+// ── "Exactly one email" (AC-1), measured across both senders ───────────────
+//
+// The claim AC-1 makes is about the TENANT'S INBOX, and two modules decide
+// what lands in it: `lead-routing.ts` sends the generic notification, this
+// module sends the confirm message. Asserting either one alone would leave the
+// interesting failure — both firing, or neither — untested. So these two cases
+// drive `routeLead` itself and count BOTH senders.
+describe("exactly one email reaches the tenant (AC-1)", () => {
+  const CALLBACK = {
+    kind: "callback" as const,
+    siteId: "site_1",
+    name: "Ada Lovelace",
+    phone: "+44 7700 900000",
+    payload: {},
+  };
+  const META = {
+    ip: "203.0.113.1",
+    userAgent: "test",
+    receivedAt: new Date().toISOString(),
+  };
+
+  beforeEach(() => {
+    process.env["DATABASE_URL"] = "postgresql://localhost/test";
+    (prisma.callback.create as jest.Mock).mockResolvedValue({
+      id: CALLBACK_ID,
+    });
+  });
+
+  it("with the feature ON: the confirm email replaces the generic notification", async () => {
+    enable();
+    const result = await routeLead(CALLBACK, META);
+    expect(result.ok).toBe(true);
+
+    // The generic notification is suppressed — that is what makes the total
+    // one rather than two.
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+    expect(result.ok && result.email).toEqual({
+      skipped: true,
+      reason: "request_confirm",
+    });
+
+    // And the confirm message is the one that goes.
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+    expect(mockSendRequestConfirmEmail).toHaveBeenCalledTimes(1);
+  });
+
+  it("on the FILE-FALLBACK path the generic notification still goes, feature on or not", async () => {
+    // #5970 security review round 3, M1. When the DB is unavailable the
+    // callback is written to the file fallback and there is no row to mint a
+    // credential against — so suppressing the generic notification would have
+    // meant ZERO operator emails for every callback captured during an outage,
+    // on the one surface whose whole point is that an outage must not lose a
+    // lead.
+    enable();
+    process.env["AILK_LEAD_NOTIFICATION_TO"] = "ops@example.com";
+    process.env["AILK_LEAD_NOTIFICATION_FROM"] = "noreply@example.com";
+    (prisma.callback.create as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+
+    const result = await routeLead(CALLBACK, META);
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.persisted).toBe("file");
+    // The email the operator would otherwise never have received.
+    expect(mockSendLeadNotification).toHaveBeenCalledTimes(1);
+    expect(mockSendRequestConfirmEmail).not.toHaveBeenCalled();
+  });
+
+  it("with the feature OFF: the generic notification still goes, exactly as before", async () => {
+    process.env["AILK_LEAD_NOTIFICATION_TO"] = "ops@example.com";
+    process.env["AILK_LEAD_NOTIFICATION_FROM"] = "noreply@example.com";
+    const result = await routeLead(CALLBACK, META);
+    expect(result.ok).toBe(true);
+    expect(mockSendLeadNotification).toHaveBeenCalledTimes(1);
+
+    // And nothing from this feature runs at all.
+    sendRequestConfirmLink(CALLBACK_ID, REQUEST);
+    await flush();
+    expect(mockSendRequestConfirmEmail).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/api/src/services/__tests__/revalidation.test.ts

@@ -0,0 +1,238 @@
+/**
+ * @file revalidation.test.ts
+ * @description Proves the publish-revalidation webhook (#5851) against a REAL
+ * loopback HTTP server (spec D11), not a `global.fetch` double: the contract
+ * under test is the wire format, and only a real server proves that the bytes
+ * on the wire are the bytes the signature covers. The server recomputes the
+ * HMAC inside its own handler — the receiver's verification, performed for
+ * real — and compares with `timingSafeEqual`, exactly as a Phase-3 receiver
+ * will (spec FR7).
+ *
+ * The server binds 127.0.0.1, which `ssrfBlocked` rejects; D7's
+ * `allowPrivate: true` is what makes this substrate runnable at all.
+ *
+ * `CONTENT_REVALIDATE_*` are read through `config`, which snapshots
+ * `process.env` at import time — so every case sets env first and then
+ * `require`s the service through `jest.resetModules()`.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+
+// Obviously-fake signing key — never a real secret (repo rule).
+const TEST_SECRET = "not-a-real-secret-fixture-value";
+const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
+const EVENT_HEADER = "x-ailk-revalidate-event";
+
+const TARGET = {
+  workspaceId: "ws_test_0001",
+  type: "page",
+  slug: "pricing",
+  locale: "en",
+};
+
+interface LogLine {
+  level: "info" | "warn" | "error";
+  obj: Record<string, unknown>;
+  msg: string;
+}
+
+// Captured through the observability boundary so assertions don't depend on
+// pino's stdout serialization — the idiom of config/__tests__/index.test.ts.
+const mockLogLines: LogLine[] = [];
+const mockRecord =
+  (level: LogLine["level"]) => (obj: Record<string, unknown>, msg: string) =>
+    void mockLogLines.push({ level, obj, msg });
+
+jest.mock("dotenv", () => ({ config: jest.fn() }));
+jest.mock("@working-theory/observability", () => ({
+  createLogger: jest.fn(() => ({
+    info: mockRecord("info"),
+    warn: mockRecord("warn"),
+    error: mockRecord("error"),
+    debug: jest.fn(),
+  })),
+  logger: {
+    error: jest.fn(),
+    warn: jest.fn(),
+    info: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+interface Recorded {
+  rawBody: string;
+  signatureValid: boolean;
+  signatureHeader: string;
+  eventHeader: string;
+  contentType: string;
+  receivedAt: number;
+}
+
+let server: Server;
+let serverUrl: string;
+let recorded: Recorded[] = [];
+/** Status codes the server replies with, one per request, in order. */
+let responseStatuses: number[] = [];
+
+beforeAll(async () => {
+  server = createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => void chunks.push(c));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks);
+
+      // The receiver's own verification (FR7): recompute HMAC-SHA256 over the
+      // RAW request body bytes and compare in constant time.
+      const expected = Buffer.from(
+        createHmac("sha256", TEST_SECRET).update(raw).digest("hex"),
+        "utf8",
+      );
+      const received = Buffer.from(
+        String(req.headers[SIGNATURE_HEADER] ?? "").replace(/^sha256=/, ""),
+        "utf8",
+      );
+      const signatureValid =
+        expected.length === received.length &&
+        timingSafeEqual(expected, received);
+
+      recorded.push({
+        rawBody: raw.toString("utf8"),
+        signatureValid,
+        signatureHeader: String(req.headers[SIGNATURE_HEADER] ?? ""),
+        eventHeader: String(req.headers[EVENT_HEADER] ?? ""),
+        contentType: String(req.headers["content-type"] ?? ""),
+        receivedAt: Date.now(),
+      });
+
+      res.writeHead(responseStatuses[recorded.length - 1] ?? 200);
+      res.end();
+    });
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  serverUrl = `http://127.0.0.1:${port}/api/revalidate`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve, reject) =>
+    server.close((err) => (err ? reject(err) : resolve())),
+  );
+});
+
+const originalEnv = process.env;
+
+beforeEach(() => {
+  jest.resetModules();
+  process.env = { ...originalEnv };
+  process.env.CONTENT_REVALIDATE_URL = serverUrl;
+  process.env.CONTENT_REVALIDATE_SECRET = TEST_SECRET;
+  recorded = [];
+  responseStatuses = [];
+  mockLogLines.length = 0;
+});
+
+afterEach(() => {
+  process.env = originalEnv;
+});
+
+function loadService(): typeof import("../revalidation") {
+  return require("../revalidation") as typeof import("../revalidation");
+}
+
+describe("notifyRevalidate", () => {
+  it("POSTs the four-key body once with a signature the receiver verifies", async () => {
+    responseStatuses = [200];
+
+    await loadService().notifyRevalidate(TARGET, { event: "publish" });
+
+    expect(recorded).toHaveLength(1);
+    const [req] = recorded;
+    expect(JSON.parse(req.rawBody)).toEqual(TARGET);
+    expect(Object.keys(JSON.parse(req.rawBody))).toEqual([
+      "workspaceId",
+      "type",
+      "slug",
+      "locale",
+    ]);
+    expect(req.signatureValid).toBe(true);
+    expect(req.signatureHeader).toMatch(/^sha256=[0-9a-f]{64}$/);
+    expect(req.eventHeader).toBe("publish");
+    expect(req.contentType).toBe("application/json");
+
+    const sent = mockLogLines.filter((l) => l.msg === "revalidate.sent");
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatchObject({
+      level: "info",
+      obj: { ...TARGET, event: "publish", attempt: 1, status: 200 },
+    });
+  });
+
+  it("retries a 5xx with D3 backoff and succeeds on the third attempt", async () => {
+    responseStatuses = [500, 500, 200];
+
+    await loadService().notifyRevalidate(TARGET, { event: "unpublish" });
+
+    expect(recorded).toHaveLength(3);
+    // D3 — 500 ms before attempt 2, 2000 ms before attempt 3. Bounded on BOTH
+    // sides: a lower bound alone would pass an arbitrarily long backoff, and
+    // the whole point of D3's schedule is that it fits the 60 s publish budget.
+    // The upper slack absorbs loopback scheduling jitter, nothing more.
+    const gapA = recorded[1].receivedAt - recorded[0].receivedAt;
+    const gapB = recorded[2].receivedAt - recorded[1].receivedAt;
+    expect(gapA).toBeGreaterThanOrEqual(500);
+    expect(gapA).toBeLessThan(2000);
+    expect(gapB).toBeGreaterThanOrEqual(2000);
+    expect(gapB).toBeLessThan(4000);
+    expect(recorded.every((r) => r.signatureValid)).toBe(true);
+
+    expect(
+      mockLogLines.filter((l) => l.msg === "revalidate.sent"),
+    ).toHaveLength(1);
+    expect(mockLogLines.some((l) => l.level === "error")).toBe(false);
+  }, 20_000);
+
+  it("stops at three attempts, logs the failure at error, and still resolves", async () => {
+    responseStatuses = [500, 500, 500];
+
+    await expect(
+      loadService().notifyRevalidate(TARGET, { event: "publish" }),
+    ).resolves.toBeUndefined();
+
+    expect(recorded).toHaveLength(3);
+
+    const perAttempt = mockLogLines.filter(
+      (l) => l.level === "warn" && l.msg === "revalidate.failed",
+    );
+    expect(perAttempt.map((l) => l.obj.attempt)).toEqual([1, 2, 3]);
+
+    const terminal = mockLogLines.filter(
+      (l) => l.level === "error" && l.msg === "revalidate.failed",
+    );
+    expect(terminal).toHaveLength(1);
+    expect(terminal[0].obj).toMatchObject({
+      ...TARGET,
+      event: "publish",
+      attempts: 3,
+      lastStatus: 500,
+    });
+  }, 20_000);
+
+  it("is a single-warning no-op with CONTENT_REVALIDATE_URL unset", async () => {
+    delete process.env.CONTENT_REVALIDATE_URL;
+    delete process.env.CONTENT_REVALIDATE_SECRET;
+
+    await expect(
+      loadService().notifyRevalidate(TARGET, { event: "publish" }),
+    ).resolves.toBeUndefined();
+
+    expect(recorded).toHaveLength(0);
+    expect(mockLogLines).toHaveLength(1);
+    expect(mockLogLines[0]).toMatchObject({
+      level: "warn",
+      msg: "revalidate.skipped",
+      obj: { ...TARGET, event: "publish", reason: "url_unset" },
+    });
+  });
+});