create-ailk 0.8.0 → 0.9.0

package/templates/apps/api/src/routes/webhooks/stripe.ts

@@ -34,16 +34,20 @@
  * Billing upsert (customer.created / checkout.session.completed):
  *   Billing-entity routing (org-scoped billing, #3601, spec D2): a checkout
  *   carrying metadata.organizationId links the Organization (multi-tenant
- *   module); absent → the existing User path (single-tenant), byte-for-byte.
+ *   module); absent → the User path (single-tenant).
  *
  *   Organization path (metadata.organizationId present):
  *     1. Typed composite match already pointing at this org → idempotent no-op
  *     2. Else link the target Organization (by id) billing fields
  *
- *   User path (no organizationId — unchanged):
+ *   User path (no organizationId):
  *     1. Typed composite match: (billingProvider="stripe", billingCustomerId=customer)
- *     2. Email fallback: User.findUnique({ where: { email } }) → update billing fields
- *     3. No match → 200 + warn log; no User row created (pre-signup state)
+ *     2. Verified user signal: metadata.ailk_user_id →
+ *        User.findUnique({ where: { id } }) → bind only when the row's
+ *        billingCustomerId is empty; otherwise log billing_identity_conflict
+ *        and write nothing (#6113). No signal → log billing_identity_unverified,
+ *        write nothing (#6852) — the payer-typed Checkout email never binds.
+ *     3. Signal names no User → warn billing_identity_unknown_user; no row created
  *
  * Recommender purchase stamp (checkout.session.completed / .expired, #4838):
  *   A session carrying metadata.flowCheckoutId (the FlowCheckout buyer row
@@ -275,7 +279,7 @@ export const stripeWebhookHandler = async (
       // Billing-entity routing (spec D2): a multi-tenant checkout stamps the
       // target Organization id in metadata.organizationId (an individual → their
       // sentinel default org). Present → link the Organization; absent → the
-      // existing User path, byte-for-byte (single-tenant, degrade-clean).
+      // User path (single-tenant, degrade-clean).
       const organizationId = customer.metadata?.["organizationId"] ?? null;
       if (organizationId) {
         await upsertOrgBillingIdentity(request, {
@@ -286,7 +290,8 @@ export const stripeWebhookHandler = async (
       } else {
         await upsertBillingIdentity(request, {
           customerId: customer.id,
-          email: customer.email ?? null,
+          userId: signalOf(customer.metadata),
+          eventType: event.type,
           eventIdPrefix,
         });
       }
@@ -306,7 +311,7 @@ export const stripeWebhookHandler = async (
       };
 
       // Billing-entity routing (spec D2): metadata.organizationId → Organization
-      // path; absent → the existing User path, unchanged (single-tenant).
+      // path; absent → the User path (single-tenant).
       const organizationId = session.metadata?.["organizationId"] ?? null;
       let billingTask: Promise<void> = Promise.resolve();
       if (session.customer) {
@@ -318,7 +323,8 @@ export const stripeWebhookHandler = async (
             })
           : upsertBillingIdentity(request, {
               customerId: session.customer,
-              email: session.customer_details?.email ?? null,
+              userId: signalOf(session.metadata),
+              eventType: event.type,
               eventIdPrefix,
             });
       }
@@ -704,14 +710,44 @@ async function stampRequestPaidByInvoice(
   }
 }
 
+/**
+ * The verified user signal (#6852): `metadata.ailk_user_id` on the Checkout
+ * session or the Stripe customer, when it is a non-empty string. Never
+ * `client_reference_id` (a Payment Link accepts it from the payer's URL) and
+ * never the payer-typed email.
+ */
+function signalOf(
+  metadata: Record<string, string> | null | undefined,
+): string | null {
+  const value: unknown = metadata?.["ailk_user_id"];
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
 /**
  * Link User.billingProvider + User.billingCustomerId for a Stripe customer.
  *
  * Lookup priority:
  *   1. Typed composite match: (billingProvider="stripe", billingCustomerId=customerId)
  *      → already linked; no-op (idempotent)
- *   2. Email fallback: User.findUnique({ where: { email } }) → update billing fields
- *   3. No match → warn; do NOT create a User row (pre-signup state preserved for Phase B #852)
+ *   2. Verified user signal (#6852): `metadata.ailk_user_id` →
+ *      User.findUnique({ where: { id } }) → bind only when the row's
+ *      billingCustomerId is empty; otherwise log billing_identity_conflict and
+ *      write nothing (#6113). The write is guarded on `billingCustomerId: null`;
+ *      a P2025 means a concurrent event bound the row first — the same customer
+ *      is a no-op, any other is a conflict.
+ *      No signal → log billing_identity_unverified and write nothing. The payer
+ *      types the Checkout email and Stripe never verifies it, so an email
+ *      never makes a binding, first or otherwise.
+ *      Trust boundary: Checkout-session and customer `metadata` can be written
+ *      only by a principal the seller authorised on their Stripe account (our
+ *      server's key, a write-capable restricted key, a connected app, the
+ *      dashboard, a Payment Link's own metadata) — never by the payer. A
+ *      producer sets the key only from an authenticated server session, never
+ *      from request input.
+ *   3. Signal names no User → warn billing_identity_unknown_user; do NOT
+ *      create a User row (pre-signup state preserved for Phase B #852)
+ *
+ * No line logs the email, the Stripe customer id, or an unresolved signal.
  *
  * DB failures are caught and logged — a broken DB link should not cause Stripe to retry
  * the event (which would fire analytics + billing again on eventual success).
@@ -720,9 +756,15 @@ async function upsertBillingIdentity(
   request: FastifyRequest,
   {
     customerId,
-    email,
+    userId,
+    eventType,
     eventIdPrefix,
-  }: { customerId: string; email: string | null; eventIdPrefix: string },
+  }: {
+    customerId: string;
+    userId: string | null;
+    eventType: string;
+    eventIdPrefix: string;
+  },
 ): Promise<void> {
   try {
     const existingByBilling = await prisma.user.findFirst({
@@ -740,30 +782,80 @@ async function upsertBillingIdentity(
       return;
     }
 
-    if (email) {
-      const existingByEmail = await prisma.user.findUnique({
-        where: { email },
-      });
+    if (!userId) {
+      // A customer Checkout creates never carries session metadata, so a
+      // no-signal customer.created is every ordinary purchase — info, not warn.
+      const fields = {
+        eventIdPrefix,
+        eventType,
+        outcome: "billing_identity_unverified",
+      };
+      const msg =
+        "stripe webhook: no verified user signal — billing identity not bound";
+      if (eventType === "customer.created") request.log.info(fields, msg);
+      else request.log.warn(fields, msg);
+      return;
+    }
 
-      if (existingByEmail) {
-        await prisma.user.update({
-          where: { id: existingByEmail.id },
-          data: {
-            billingProvider: "stripe",
-            billingCustomerId: customerId,
-          },
-        });
-        request.log.info(
-          { eventIdPrefix },
-          "billing identity linked via email fallback",
-        );
-        return;
-      }
+    const row = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { id: true, billingProvider: true, billingCustomerId: true },
+    });
+
+    if (!row) {
+      request.log.warn(
+        { eventIdPrefix, eventType, outcome: "billing_identity_unknown_user" },
+        "stripe webhook: user signal names no User — pre-signup state preserved",
+      );
+      return;
     }
 
-    request.log.warn(
+    const isSameBinding = (r: {
+      billingProvider: string | null;
+      billingCustomerId: string | null;
+    }) => r.billingProvider === "stripe" && r.billingCustomerId === customerId;
+    const logAlreadyLinked = () =>
+      request.log.info(
+        { eventIdPrefix, outcome: "billing_identity_already_linked" },
+        "billing identity already linked — idempotent no-op",
+      );
+    const logConflict = () =>
+      request.log.warn(
+        {
+          eventIdPrefix,
+          outcome: "billing_identity_conflict",
+          userId: row.id,
+        },
+        "stripe webhook: user already bound to a different billing customer — not re-pointed",
+      );
+
+    if (row.billingCustomerId !== null) {
+      if (isSameBinding(row)) logAlreadyLinked();
+      else logConflict();
+      return;
+    }
+
+    try {
+      await prisma.user.update({
+        where: { id: row.id, billingCustomerId: null },
+        data: {
+          billingProvider: "stripe",
+          billingCustomerId: customerId,
+        },
+      });
+    } catch (err) {
+      if ((err as { code?: unknown }).code !== "P2025") throw err;
+      const now = await prisma.user.findUnique({
+        where: { id: row.id },
+        select: { billingProvider: true, billingCustomerId: true },
+      });
+      if (now && isSameBinding(now)) logAlreadyLinked();
+      else logConflict();
+      return;
+    }
+    request.log.info(
       { eventIdPrefix },
-      "stripe webhook: no User match for billing identity — pre-signup state preserved",
+      "billing identity linked via verified user signal",
     );
   } catch (err) {
     request.log.error(

package/templates/apps/api/src/server.ts

@@ -12,6 +12,7 @@
 import cors from "@fastify/cors";
 import rateLimit from "@fastify/rate-limit";
 import { idRegex } from "@working-theory/ids";
+import { logger } from "@working-theory/observability";
 import Fastify from "fastify";
 import type {
   FastifyPluginAsync,
@@ -507,6 +508,31 @@ async function assertCommerceSandboxKey(key: string): Promise<void> {
   assertSandboxKeyFn(key);
 }
 
+/**
+ * #6889 (SEC-02 of the #6876 security review) — make the checkout route's
+ * posture observable. POST /v1/checkout/sessions admits a caller without
+ * X-Internal-Auth when OSS_API_INTERNAL_SECRET is unset. With FRONTEND_URL
+ * unset, the route's same-origin redirect lock (#6877) answers 500
+ * config-error to that caller, and the CORS and cookie-CSRF origin checks pin
+ * to the `http://localhost:3000` config default. Both stay optional (OSS
+ * standalone compat), so this only ever WARNS — once per unset variable, and
+ * only in production. FRONTEND_URL is read from the raw environment because
+ * `config.FRONTEND_URL` carries that localhost default.
+ */
+function warnOnUnsetProductionProtections(): void {
+  if (config.NODE_ENV !== "production") return;
+  if (!process.env["FRONTEND_URL"]) {
+    logger.warn(
+      "[startup] FRONTEND_URL not set in production — CORS/cookie origin checks are pinned to http://localhost:3000, and checkout answers 500 config-error to any caller admitted without X-Internal-Auth",
+    );
+  }
+  if (!process.env["OSS_API_INTERNAL_SECRET"]) {
+    logger.warn(
+      "[startup] OSS_API_INTERNAL_SECRET not set in production — the checkout route admits callers without X-Internal-Auth",
+    );
+  }
+}
+
 /**
  * Build Fastify server instance (for serverless or standalone)
  * @returns Configured Fastify instance ready for requests
@@ -515,6 +541,8 @@ export async function build() {
   // Startup-time validation: fail fast if LEAD_CAPTURE_FILE points at a missing directory.
   await validateLeadCaptureDir();
 
+  warnOnUnsetProductionProtections();
+
   // #6155 D6 — the site-alias workspace assertion (ownership brief § Layer
   // 2, AC-5): resolves + asserts once at startup that AILK_SITE_ID (or its
   // "default" fallback) names a real workspace, throwing when it does not —

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

@@ -4,9 +4,10 @@
  * 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).
+ * HMAC inside its own handler over the D1 base string
+ * `v0:{timestamp}:{event}:{rawBody}` (#5902) — the receiver's verification,
+ * performed for real — and compares with `timingSafeEqual`, exactly as the
+ * receiver does (spec FR7).
  *
  * The server binds 127.0.0.1, which `ssrfBlocked` rejects; D7's
  * `allowPrivate: true` is what makes this substrate runnable at all.
@@ -23,10 +24,13 @@ import type { AddressInfo } from "node:net";
 const TEST_SECRET = "not-a-real-secret-fixture-value";
 const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
 const EVENT_HEADER = "x-ailk-revalidate-event";
+const TIMESTAMP_HEADER = "x-ailk-revalidate-timestamp";
 
+// `type` must be a registered page type and `slug` a SLUG_PATTERN value — the
+// sender validates both before signing (#5902).
 const TARGET = {
   workspaceId: "ws_test_0001",
-  type: "page",
+  type: "Service",
   slug: "pricing",
   locale: "en",
 };
@@ -63,8 +67,11 @@ jest.mock("@working-theory/observability", () => ({
 interface Recorded {
   rawBody: string;
   signatureValid: boolean;
+  /** Whether the signature is HMAC over the raw body ALONE (the pre-#5902 wire). */
+  bodyOnlySignatureValid: boolean;
   signatureHeader: string;
   eventHeader: string;
+  timestampHeader: string;
   contentType: string;
   receivedAt: number;
 }
@@ -81,26 +88,40 @@ beforeAll(async () => {
     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 timestampHeader = String(req.headers[TIMESTAMP_HEADER] ?? "");
+      const eventHeader = String(req.headers[EVENT_HEADER] ?? "");
       const received = Buffer.from(
         String(req.headers[SIGNATURE_HEADER] ?? "").replace(/^sha256=/, ""),
         "utf8",
       );
-      const signatureValid =
-        expected.length === received.length &&
-        timingSafeEqual(expected, received);
+      const matches = (material: Buffer): boolean => {
+        const expected = Buffer.from(
+          createHmac("sha256", TEST_SECRET).update(material).digest("hex"),
+          "utf8",
+        );
+        return (
+          expected.length === received.length &&
+          timingSafeEqual(expected, received)
+        );
+      };
+
+      // The receiver's own verification (FR7, D1 as amended by #5902):
+      // recompute HMAC-SHA256 over `v0:{timestamp}:{event}:` followed by the
+      // RAW request body bytes, and compare in constant time.
+      const signatureValid = matches(
+        Buffer.concat([
+          Buffer.from(`v0:${timestampHeader}:${eventHeader}:`, "utf8"),
+          raw,
+        ]),
+      );
 
       recorded.push({
         rawBody: raw.toString("utf8"),
         signatureValid,
+        bodyOnlySignatureValid: matches(raw),
         signatureHeader: String(req.headers[SIGNATURE_HEADER] ?? ""),
-        eventHeader: String(req.headers[EVENT_HEADER] ?? ""),
+        eventHeader,
+        timestampHeader,
         contentType: String(req.headers["content-type"] ?? ""),
         receivedAt: Date.now(),
       });
@@ -219,6 +240,60 @@ describe("notifyRevalidate", () => {
     });
   }, 20_000);
 
+  it("signs v0:{timestamp}:{event}:{body} and sends the timestamp header (#5902)", async () => {
+    responseStatuses = [200];
+    const before = Math.floor(Date.now() / 1000);
+
+    await loadService().notifyRevalidate(TARGET, { event: "unpublish" });
+
+    const after = Math.floor(Date.now() / 1000);
+    expect(recorded).toHaveLength(1);
+    const [req] = recorded;
+
+    // Unix seconds, digits only, taken at send time — what the receiver checks
+    // its 5-minute tolerance against.
+    expect(req.timestampHeader).toMatch(/^[0-9]+$/);
+    const ts = Number(req.timestampHeader);
+    expect(ts).toBeGreaterThanOrEqual(before);
+    expect(ts).toBeLessThanOrEqual(after);
+
+    // The base-string shape, recomputed independently here: the timestamp and
+    // the event are inside the MAC, so neither can be altered in flight.
+    const expected = createHmac("sha256", TEST_SECRET)
+      .update(`v0:${req.timestampHeader}:unpublish:${req.rawBody}`, "utf8")
+      .digest("hex");
+    expect(req.signatureHeader).toBe(`sha256=${expected}`);
+    expect(req.signatureValid).toBe(true);
+    // And the body-alone signature of the pre-#5902 wire no longer verifies.
+    expect(req.bodyOnlySignatureValid).toBe(false);
+  });
+
+  it.each([
+    ["type", "page"], // not a registered page type
+    ["type", "Service:some-slug:en"], // the tag-collision shape (#6005 M3)
+    ["type", "S".repeat(300)],
+    ["slug", "Bad Slug"],
+    ["slug", "a:b"],
+    ["slug", ""],
+    ["locale", "english"],
+    ["locale", "en:x"],
+    ["locale", ""],
+  ])(
+    "throws before any outbound call on an invalid %s (%j) (#5902)",
+    async (field, value) => {
+      responseStatuses = [200];
+
+      await expect(
+        loadService().notifyRevalidate(
+          { ...TARGET, [field]: value },
+          { event: "publish" },
+        ),
+      ).rejects.toThrow();
+
+      expect(recorded).toHaveLength(0);
+    },
+  );
+
   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;

package/templates/apps/api/src/services/checkout-buyer.ts

@@ -0,0 +1,72 @@
+/**
+ * @file checkout-buyer.ts
+ * @description Resolves a signed-in user into the Checkout buyer
+ * `POST /v1/checkout/sessions` pins and stamps (#6866 D3).
+ *
+ * A buyer is a user whose email is VERIFIED — the customer created for them
+ * carries the account email, and it must never carry an unproven one — and
+ * whose billing binding, if any, is a Stripe customer. The binding decides
+ * whether the library reuses a customer (`customerId`) or creates one
+ * (`null`). A row bound under any other provider is not a buyer: the webhook
+ * never re-points a non-null `billingCustomerId` (#6113), so a new stamped
+ * customer could only be an orphan.
+ *
+ * Base tree (N4): imports only `verified-email.ts` and `lib/prisma.ts`, never
+ * the commerce overlay's `services/subscription.ts`. The billing read selects
+ * no email, so `tools/lint-email-authz.ts` has nothing to flag.
+ */
+
+import { prisma } from "../lib/prisma.js";
+
+import { findVerifiedEmail } from "./verified-email.js";
+
+export type CheckoutBuyer = {
+  userId: string;
+  email: string;
+  /** The user's bound Stripe customer, or `null` when one is to be created. */
+  customerId: string | null;
+};
+
+export type CheckoutBuyerResult =
+  | { ok: true; buyer: CheckoutBuyer }
+  | {
+      ok: false;
+      reason: "user_not_found" | "email_unverified" | "foreign_provider";
+    };
+
+/**
+ * @param userId the id resolved from the authenticated session cookie — never
+ *        a request-supplied value.
+ * @throws whatever Prisma throws; the caller degrades that to anonymous (F7).
+ */
+export async function resolveCheckoutBuyer(
+  userId: string,
+): Promise<CheckoutBuyerResult> {
+  const verified = await findVerifiedEmail(userId);
+  if (!verified.ok) return { ok: false, reason: verified.reason };
+
+  const billing = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { billingProvider: true, billingCustomerId: true },
+  });
+  if (!billing) return { ok: false, reason: "user_not_found" };
+
+  if (billing.billingCustomerId === null) {
+    return {
+      ok: true,
+      buyer: { userId, email: verified.value.email, customerId: null },
+    };
+  }
+  // The same provider predicate `resolveBillingCustomer` applies.
+  if (billing.billingProvider !== "stripe") {
+    return { ok: false, reason: "foreign_provider" };
+  }
+  return {
+    ok: true,
+    buyer: {
+      userId,
+      email: verified.value.email,
+      customerId: billing.billingCustomerId,
+    },
+  };
+}

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

@@ -3,30 +3,48 @@
  * @description The signed webhook `apps/api` fires at the site's
  * `/api/revalidate` on publish and unpublish (#5851, roadmap D6). One POST of
  * `{ workspaceId, type, slug, locale }` to `CONTENT_REVALIDATE_URL`, signed
- * HMAC-SHA256 over the exact body bytes with `CONTENT_REVALIDATE_SECRET`.
+ * HMAC-SHA256 with `CONTENT_REVALIDATE_SECRET` over the base string
+ * `v0:{timestamp}:{event}:{body}` (#5902) — the Slack shape
+ * (`routes/slack/actions.ts:56`) with the event folded in, so neither a replay
+ * outside the receiver's 5-minute window nor an in-flight event flip verifies.
+ *
+ * `type`, `slug` and `locale` are validated against bounded Zod shapes FIRST,
+ * before the config check and before any outbound call; an invalid value
+ * throws. That is the one way this function rejects, and it is a programmer
+ * error rather than a delivery failure: the publish routes already hold these
+ * values to the same shapes.
  *
  * Either var absent means "revalidation off": one `warn` and return. Both set
  * means three bounded attempts (500 ms then 2000 ms backoff, 10 s per-attempt
  * timeout — 32.5 s worst case), every attempt logged, and a final failure
- * LOGGED rather than thrown. `notifyRevalidate` never rejects, which is what
- * lets the publish path `await` it and still always complete.
+ * LOGGED rather than thrown. Delivery never rejects, which is what lets the
+ * publish path `await` it and still always complete.
  *
  * PII boundary: log lines carry only
  * `{ event, workspaceId, type, slug, locale, attempt/attempts, status/lastStatus, errName }`.
  * Never the secret, never the signature, never a response body, never page
  * content.
  *
- * Nothing calls this yet — the publish/unpublish handlers are a sibling child
- * of Epic #5323, and the receiver is Epic #5324. This module fixes the wire
- * contract a receiver implements: method POST; the four-key JSON body;
- * headers `content-type: application/json`, `x-ailk-revalidate-signature:
- * sha256=<lowercase hex>` and `x-ailk-revalidate-event: publish | unpublish`.
- * A receiver verifies by recomputing the HMAC over the RAW request body and
- * comparing in constant time.
+ * The publish and unpublish handlers in `routes/workspaces/content.ts` call
+ * this; the receiver is `apps/web/app/api/revalidate/route.ts`. This module
+ * fixes the wire contract that receiver implements: method POST; the four-key
+ * JSON body; headers `content-type: application/json`,
+ * `x-ailk-revalidate-timestamp: <unix seconds>`,
+ * `x-ailk-revalidate-event: publish | unpublish` and
+ * `x-ailk-revalidate-signature: sha256=<lowercase hex>`. A receiver rejects a
+ * timestamp more than 5 minutes from its own clock, then recomputes the HMAC
+ * over `v0:{timestamp}:{event}:` + the RAW request body and compares in
+ * constant time.
  */
 import { createHmac } from "node:crypto";
 
+import {
+  SCHEMA_ORG_TYPES,
+  SLUG_PATTERN,
+} from "@working-theory/content-adapters";
 import { createLogger } from "@working-theory/observability";
+import { localeSchema } from "@working-theory/validation";
+import { z } from "zod";
 
 import { config } from "../config/index.js";
 import { outboundFetch } from "../lib/outbound-http.js";
@@ -35,6 +53,22 @@ const log = createLogger({ service: "revalidation" });
 
 const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
 const EVENT_HEADER = "x-ailk-revalidate-event";
+const TIMESTAMP_HEADER = "x-ailk-revalidate-timestamp";
+
+/**
+ * The bounds on the three fields that become the site's cache tags
+ * (`content:{workspace}:{type}:{slug}:{locale}`). `type` and `slug` are exactly
+ * the content routes' `addressParamsSchema` shapes and `locale` is the BCP-47
+ * subset `resolveLocale` produces, so the publish path can never trip this
+ * after its write has committed. None admits a `:`, which is what stops a
+ * crafted `type` colliding with another page's tag (#6005 M3); the receiver
+ * applies the same shapes.
+ */
+const targetFieldsSchema = z.object({
+  type: z.enum(SCHEMA_ORG_TYPES),
+  slug: z.string().regex(SLUG_PATTERN),
+  locale: localeSchema,
+});
 
 /**
  * Backoff before attempt 2 and attempt 3. Three attempts total, no fourth:
@@ -69,14 +103,21 @@ function isRetryableStatus(status: number): boolean {
 }
 
 /**
- * Tells the site to revalidate one piece of content. Resolves in every case —
- * success, exhausted retries, or unconfigured — so an `await` in the publish
- * path can never fail the publish it follows.
+ * Tells the site to revalidate one piece of content. Resolves on success,
+ * exhausted retries, or unconfigured, so an `await` in the publish path cannot
+ * fail the publish it follows. Rejects only when `type`, `slug` or `locale` is
+ * out of bounds, before anything is signed or sent.
  */
 export async function notifyRevalidate(
   target: RevalidateTarget,
   options: RevalidateOptions,
 ): Promise<void> {
+  targetFieldsSchema.parse({
+    type: target.type,
+    slug: target.slug,
+    locale: target.locale,
+  });
+
   const url = config.CONTENT_REVALIDATE_URL;
   const secret = config.CONTENT_REVALIDATE_SECRET;
 
@@ -100,8 +141,11 @@ export async function notifyRevalidate(
     slug: target.slug,
     locale: target.locale,
   });
+  // Taken once per call and shared by every attempt: the retry schedule's
+  // 32.5 s worst case sits well inside the receiver's 5-minute tolerance.
+  const timestamp = String(Math.floor(Date.now() / 1000));
   const signature = createHmac("sha256", secret)
-    .update(body, "utf8")
+    .update(`v0:${timestamp}:${options.event}:${body}`, "utf8")
     .digest("hex");
 
   let attempt = 0;
@@ -117,8 +161,9 @@ export async function notifyRevalidate(
         method: "POST",
         headers: {
           "content-type": "application/json",
-          [SIGNATURE_HEADER]: `sha256=${signature}`,
+          [TIMESTAMP_HEADER]: timestamp,
           [EVENT_HEADER]: options.event,
+          [SIGNATURE_HEADER]: `sha256=${signature}`,
         },
         body,
         // The SSRF gate is waived deliberately and narrowly: this URL comes