create-ailk 0.7.0 → 0.9.0

package/templates/apps/web/app/api/revalidate/__tests__/route.test.ts

@@ -15,6 +15,10 @@
  *   - AC-2 — the 503 → 401 → 400 ladder (NFR2), each rung asserting that
  *     revalidateTag was not called, and the unset-secret rung asserting
  *     exactly one log line.
+ *   - #5902 — the signed material is `v0:{timestamp}:{event}:{rawBody}`; a
+ *     timestamp outside the 5-minute tolerance, a missing or flipped event,
+ *     and a pre-#5902 body-only signature are all 401; a type, slug or locale
+ *     outside its bounded shape is 400.
  *   - AC-3 — the AC-WCE-02 publish-to-live harness, env-gated and SKIPPED by
  *     default (D12). It needs a live CONTENT_ADAPTER=database deployment; see
  *     the block at the bottom of this file.
@@ -60,6 +64,12 @@ const mockRevalidateTag = revalidateTag as jest.Mock;
 const SECRET = "test-secret-the-right-one";
 const WRONG_SECRET = "test-secret-the-other-one";
 
+const TOLERANCE_SECONDS = 5 * 60;
+
+function nowSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
 const VALID_BODY = {
   workspaceId: "ws_fixture",
   type: "Service",
@@ -69,22 +79,32 @@ const VALID_BODY = {
 
 /**
  * The fake signer — AC-1's "proved by test against a fake signer". It is the
- * #5851 wire contract written out here independently: HMAC-SHA256 over the
- * exact body bytes, lowercase hex, `sha256=` prefix.
+ * #5851 wire contract as amended by #5902, written out here independently:
+ * HMAC-SHA256 over `v0:{timestamp}:{event}:{rawBody}`, lowercase hex,
+ * `sha256=` prefix.
  */
-function sign(rawBody: string, secret: string): string {
-  return `sha256=${createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
+function sign(
+  rawBody: string,
+  secret: string,
+  timestamp: string,
+  event = "publish",
+): string {
+  return `sha256=${createHmac("sha256", secret).update(`v0:${timestamp}:${event}:${rawBody}`, "utf8").digest("hex")}`;
 }
 
 function makeRequest(opts: {
   rawBody: string;
   signature?: string;
-  event?: string;
+  event?: string | undefined;
+  timestamp?: string | undefined;
   requestId?: string;
 }): Request {
   const headers: Record<string, string> = {
     "content-type": "application/json",
   };
+  if (opts.timestamp !== undefined) {
+    headers["x-ailk-revalidate-timestamp"] = opts.timestamp;
+  }
   if (opts.signature !== undefined) {
     headers["x-ailk-revalidate-signature"] = opts.signature;
   }
@@ -101,14 +121,31 @@ function makeRequest(opts: {
   });
 }
 
-/** A correctly-signed POST of `body` under `secret`. */
+/** A correctly-signed POST of `body` under `secret`, timestamped now. */
 function signedRequest(
   body: unknown,
   secret: string,
   event = "publish",
+  timestamp = String(nowSeconds()),
 ): Request {
   const rawBody = JSON.stringify(body);
-  return makeRequest({ rawBody, signature: sign(rawBody, secret), event });
+  return makeRequest({
+    rawBody,
+    signature: sign(rawBody, secret, timestamp, event),
+    event,
+    timestamp,
+  });
+}
+
+/** A request signed over `rawBody` exactly — for bodies JSON.stringify would not produce. */
+function signedRaw(rawBody: string, secret = SECRET): Request {
+  const timestamp = String(nowSeconds());
+  return makeRequest({
+    rawBody,
+    signature: sign(rawBody, secret, timestamp),
+    event: "publish",
+    timestamp,
+  });
 }
 
 describe("POST /api/revalidate", () => {
@@ -162,7 +199,7 @@ describe("POST /api/revalidate", () => {
     it("purges tags built from the body's own type/slug/locale", async () => {
       const body = {
         workspaceId: "ws_other",
-        type: "Article",
+        type: "BlogPosting",
         slug: "another-slug",
         locale: "fr",
       };
@@ -170,11 +207,15 @@ describe("POST /api/revalidate", () => {
       await POST(signedRequest(body, SECRET));
 
       expect(mockRevalidateTag).toHaveBeenCalledWith(
-        contentPageTag({ type: "Article", slug: "another-slug", locale: "fr" }),
+        contentPageTag({
+          type: "BlogPosting",
+          slug: "another-slug",
+          locale: "fr",
+        }),
         { expire: 0 },
       );
       expect(mockRevalidateTag).toHaveBeenCalledWith(
-        contentListTag({ type: "Article" }),
+        contentListTag({ type: "BlogPosting" }),
         { expire: 0 },
       );
     });
@@ -193,18 +234,6 @@ describe("POST /api/revalidate", () => {
       expect(mockRevalidateTag.mock.calls).toEqual(publishCalls);
     });
 
-    it("accepts a request with no event header, logging it as unknown (FR7)", async () => {
-      const rawBody = JSON.stringify(VALID_BODY);
-      const response = await POST(
-        makeRequest({ rawBody, signature: sign(rawBody, SECRET) }),
-      );
-
-      expect(response.status).toBe(200);
-      expect(mockRevalidateTag).toHaveBeenCalledTimes(2);
-      expect(console.info).toHaveBeenCalledTimes(1);
-      expect((console.info as jest.Mock).mock.calls[0][0]).toContain("unknown");
-    });
-
     it("is idempotent under retry — a second identical delivery purges the same tags (NFR3)", async () => {
       await POST(signedRequest(VALID_BODY, SECRET));
       const firstCalls = mockRevalidateTag.mock.calls;
@@ -218,11 +247,13 @@ describe("POST /api/revalidate", () => {
 
     it("logs one line prefixed [revalidate] carrying the correlation id (FR8, D8)", async () => {
       const rawBody = JSON.stringify(VALID_BODY);
+      const timestamp = String(nowSeconds());
       await POST(
         makeRequest({
           rawBody,
-          signature: sign(rawBody, SECRET),
+          signature: sign(rawBody, SECRET, timestamp),
           event: "publish",
+          timestamp,
           requestId: "req-abc-123",
         }),
       );
@@ -235,9 +266,12 @@ describe("POST /api/revalidate", () => {
 
     it("never logs the secret or the signature header value (FR9)", async () => {
       const rawBody = JSON.stringify(VALID_BODY);
-      const signature = sign(rawBody, SECRET);
+      const timestamp = String(nowSeconds());
+      const signature = sign(rawBody, SECRET, timestamp);
 
-      await POST(makeRequest({ rawBody, signature, event: "publish" }));
+      await POST(
+        makeRequest({ rawBody, signature, event: "publish", timestamp }),
+      );
 
       const logged = [
         ...(console.info as jest.Mock).mock.calls,
@@ -396,6 +430,7 @@ describe("POST /api/revalidate", () => {
         makeRequest({
           rawBody: JSON.stringify(VALID_BODY),
           event: "publish",
+          timestamp: String(nowSeconds()),
         }),
       );
 
@@ -408,18 +443,24 @@ describe("POST /api/revalidate", () => {
 
     it("returns 401 when the signature header is malformed", async () => {
       const rawBody = JSON.stringify(VALID_BODY);
+      const timestamp = String(nowSeconds());
 
       for (const malformed of [
         "not-a-signature",
         "sha256=short",
         `sha1=${"a".repeat(64)}`,
         `sha256=${"A".repeat(64)}`, // uppercase hex is not the wire encoding
-        sign(rawBody, SECRET).slice("sha256=".length), // prefix stripped
+        sign(rawBody, SECRET, timestamp).slice("sha256=".length), // prefix stripped
       ]) {
         mockRevalidateTag.mockClear();
 
         const response = await POST(
-          makeRequest({ rawBody, signature: malformed, event: "publish" }),
+          makeRequest({
+            rawBody,
+            signature: malformed,
+            event: "publish",
+            timestamp,
+          }),
         );
 
         expect(response.status).toBe(401);
@@ -437,12 +478,14 @@ describe("POST /api/revalidate", () => {
     it("returns 401 when the body was altered after signing", async () => {
       const signedOver = JSON.stringify(VALID_BODY);
       const delivered = JSON.stringify({ ...VALID_BODY, slug: "tampered" });
+      const timestamp = String(nowSeconds());
 
       const response = await POST(
         makeRequest({
           rawBody: delivered,
-          signature: sign(signedOver, SECRET),
+          signature: sign(signedOver, SECRET, timestamp),
           event: "publish",
+          timestamp,
         }),
       );
 
@@ -461,13 +504,7 @@ describe("POST /api/revalidate", () => {
       ]) {
         mockRevalidateTag.mockClear();
 
-        const response = await POST(
-          makeRequest({
-            rawBody,
-            signature: sign(rawBody, SECRET),
-            event: "publish",
-          }),
-        );
+        const response = await POST(signedRaw(rawBody));
 
         expect(response.status).toBe(400);
         await expect(response.json()).resolves.toEqual({
@@ -478,15 +515,7 @@ describe("POST /api/revalidate", () => {
     });
 
     it("prefers 401 over 400 — a wrong-key request with a malformed body is 401, never 400 (NFR2)", async () => {
-      const rawBody = "not json at all";
-
-      const response = await POST(
-        makeRequest({
-          rawBody,
-          signature: sign(rawBody, WRONG_SECRET),
-          event: "publish",
-        }),
-      );
+      const response = await POST(signedRaw("not json at all", WRONG_SECRET));
 
       expect(response.status).toBe(401);
       await expect(response.json()).resolves.toEqual({
@@ -506,6 +535,169 @@ describe("POST /api/revalidate", () => {
       expect((await POST(signedRequest(VALID_BODY, SECRET))).status).toBe(200);
     });
   });
+
+  // --- #5902: replay window, signed event, bounded fields ------------------
+
+  describe("#5902 — the timestamp and event are signed, and the fields are bounded", () => {
+    it("accepts a timestamp just inside the 5-minute tolerance, either side", async () => {
+      for (const offset of [-(TOLERANCE_SECONDS - 5), TOLERANCE_SECONDS - 5]) {
+        const response = await POST(
+          signedRequest(
+            VALID_BODY,
+            SECRET,
+            "publish",
+            String(nowSeconds() + offset),
+          ),
+        );
+        expect(response.status).toBe(200);
+      }
+    });
+
+    it("rejects a correctly-signed replay older than the tolerance with 401", async () => {
+      const stale = String(nowSeconds() - TOLERANCE_SECONDS - 1);
+
+      const response = await POST(
+        signedRequest(VALID_BODY, SECRET, "publish", stale),
+      );
+
+      expect(response.status).toBe(401);
+      await expect(response.json()).resolves.toEqual({
+        error: "invalid_signature",
+      });
+      expect(mockRevalidateTag).not.toHaveBeenCalled();
+    });
+
+    it("rejects a correctly-signed timestamp too far in the future with 401", async () => {
+      const future = String(nowSeconds() + TOLERANCE_SECONDS + 1);
+
+      const response = await POST(
+        signedRequest(VALID_BODY, SECRET, "publish", future),
+      );
+
+      expect(response.status).toBe(401);
+      expect(mockRevalidateTag).not.toHaveBeenCalled();
+    });
+
+    it("rejects a missing or non-numeric timestamp header with 401", async () => {
+      const rawBody = JSON.stringify(VALID_BODY);
+
+      for (const timestamp of [undefined, "", "abc", "1e9", "-1", "12.5"]) {
+        mockRevalidateTag.mockClear();
+
+        const response = await POST(
+          makeRequest({
+            rawBody,
+            signature: sign(rawBody, SECRET, timestamp ?? ""),
+            event: "publish",
+            timestamp,
+          }),
+        );
+
+        expect(response.status).toBe(401);
+        expect(mockRevalidateTag).not.toHaveBeenCalled();
+      }
+    });
+
+    it("rejects a timestamp altered after signing with 401", async () => {
+      const rawBody = JSON.stringify(VALID_BODY);
+      const signedAt = String(nowSeconds() - 60);
+
+      const response = await POST(
+        makeRequest({
+          rawBody,
+          signature: sign(rawBody, SECRET, signedAt),
+          event: "publish",
+          timestamp: String(nowSeconds()),
+        }),
+      );
+
+      expect(response.status).toBe(401);
+      expect(mockRevalidateTag).not.toHaveBeenCalled();
+    });
+
+    it("rejects an event header flipped after signing with 401", async () => {
+      const rawBody = JSON.stringify(VALID_BODY);
+      const timestamp = String(nowSeconds());
+
+      const response = await POST(
+        makeRequest({
+          rawBody,
+          signature: sign(rawBody, SECRET, timestamp, "publish"),
+          event: "unpublish",
+          timestamp,
+        }),
+      );
+
+      expect(response.status).toBe(401);
+      expect(mockRevalidateTag).not.toHaveBeenCalled();
+    });
+
+    it("rejects a missing or unknown event header with 401, logging it as unknown", async () => {
+      const rawBody = JSON.stringify(VALID_BODY);
+      const timestamp = String(nowSeconds());
+
+      for (const event of [undefined, "", "delete"]) {
+        mockRevalidateTag.mockClear();
+        (console.warn as jest.Mock).mockClear();
+
+        const response = await POST(
+          makeRequest({
+            rawBody,
+            signature: sign(rawBody, SECRET, timestamp, event ?? ""),
+            event,
+            timestamp,
+          }),
+        );
+
+        expect(response.status).toBe(401);
+        expect(mockRevalidateTag).not.toHaveBeenCalled();
+        expect((console.warn as jest.Mock).mock.calls[0][0]).toContain(
+          "unknown",
+        );
+      }
+    });
+
+    it("rejects the pre-#5902 body-only signature with 401", async () => {
+      const rawBody = JSON.stringify(VALID_BODY);
+      const bodyOnly = `sha256=${createHmac("sha256", SECRET).update(rawBody, "utf8").digest("hex")}`;
+
+      const response = await POST(
+        makeRequest({
+          rawBody,
+          signature: bodyOnly,
+          event: "publish",
+          timestamp: String(nowSeconds()),
+        }),
+      );
+
+      expect(response.status).toBe(401);
+      expect(mockRevalidateTag).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ["type", "page"], // not a registered page type
+      ["type", "Service:some-slug:en"], // collides with another page's tag (#6005 M3)
+      ["type", "S".repeat(300)], // would exceed Next's 256-character tag limit
+      ["slug", "Bad Slug"],
+      ["slug", "a:b"],
+      ["slug", "a".repeat(260)], // page tag over Next's 256-character limit
+      ["locale", "english"],
+      ["locale", "en:x"],
+    ])(
+      "returns 400 for a correctly-signed body with an out-of-bounds %s (%j)",
+      async (field, value) => {
+        const response = await POST(
+          signedRequest({ ...VALID_BODY, [field]: value }, SECRET),
+        );
+
+        expect(response.status).toBe(400);
+        await expect(response.json()).resolves.toEqual({
+          error: "invalid_body",
+        });
+        expect(mockRevalidateTag).not.toHaveBeenCalled();
+      },
+    );
+  });
 });
 
 // --- AC-3: the AC-WCE-02 publish-to-live harness (D12) --------------------

package/templates/apps/web/app/api/revalidate/route.ts

@@ -10,37 +10,75 @@
  * database handle; it purges cache keys for a read path that goes through
  * apps/api (ADR 0002, headless-first).
  *
- * The wire contract is #5851's, consumed verbatim (D1): POST; body the
- * four-key JSON { workspaceId, type, slug, locale }; headers
+ * The wire contract is #5851's as amended by #5902 (its spec's D1/D2): POST;
+ * body the four-key JSON { workspaceId, type, slug, locale }; headers
+ * `x-ailk-revalidate-timestamp: <unix seconds>`,
+ * `x-ailk-revalidate-event: publish | unpublish` and
  * `x-ailk-revalidate-signature: sha256=<lowercase hex>` — HMAC-SHA256 over
- * the exact body bytes — and `x-ailk-revalidate-event: publish | unpublish`.
+ * `v0:{timestamp}:{event}:{rawBody}`.
  *
  * The order is 503 → 401 → 400, and the signature is verified over the RAW
  * body before it is parsed (D2). Re-serialising a parsed object changes the
  * bytes, and answering 400 before 401 would hand an unauthenticated caller a
- * JSON-parser oracle.
+ * JSON-parser oracle. A timestamp more than 5 minutes from this server's
+ * clock, or an event other than publish/unpublish, is a 401 like a bad
+ * signature: both are inside the signed material.
  *
  * Both events take one code path (D6): purging the page tag is what makes an
  * unpublished page disappear, and purging the list tag drops it from the
- * index — the same two purges a publish needs. The event header is logged and
- * never branched on.
+ * index — the same two purges a publish needs. The event header is signed,
+ * logged and otherwise never branched on.
  *
- * No replay window, by design and on the wire (D7): #5851 signs the body
- * bytes alone, so there is no timestamp to check a window against, and the
- * only action a replay causes — a second revalidateTag on an already-purged
- * tag — is a no-op. #5902 is the open amendment that would give this receiver
- * a timestamp; D7 is reopened with it.
+ * Replay window (D7, reopened and closed by #5902): a captured delivery
+ * verifies for 5 minutes and no longer, the Slack receiver's tolerance
+ * (apps/api/src/routes/slack/actions.ts). Within the window a replay is a
+ * second revalidateTag on an already-purged tag — a no-op — so the receiver
+ * still keeps no seen-set.
+ *
+ * `type`, `slug` and `locale` are held to the sender's bounded shapes before
+ * they become cache tags (#5902, #6005 M3): none can carry a `:`, so no body
+ * can forge another page's tag. A page tag over Next's 256-character limit is
+ * a 400 too — the read path cannot cache under such a tag either.
  *
  * PII / secret boundary (FR9): no log line carries the secret, the signature
  * header value, the request body, or page content.
  */
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 
+import {
+  SCHEMA_ORG_TYPES,
+  SLUG_PATTERN,
+} from "@working-theory/content-adapters";
 import { contentListTag, contentPageTag } from "@working-theory/page-renderer";
+import { localeSchema } from "@working-theory/validation";
 import { revalidateTag } from "next/cache";
+import { z } from "zod";
 
 const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
 const EVENT_HEADER = "x-ailk-revalidate-event";
+const TIMESTAMP_HEADER = "x-ailk-revalidate-timestamp";
+
+/** How far the signed timestamp may sit from this server's clock, either way. */
+const SIGNATURE_TOLERANCE_SECONDS = 5 * 60;
+
+/** Unix seconds as the sender writes them: digits only, no sign or exponent. */
+const TIMESTAMP_SHAPE = /^[0-9]{1,12}$/;
+
+/**
+ * The sender's bounds (apps/api/src/services/revalidation.ts), applied again
+ * here because this route is unauthenticated until the MAC verifies and the
+ * values become cache tags. `workspaceId` is logged, never tagged, so it stays
+ * a plain string.
+ */
+const bodySchema = z.object({
+  workspaceId: z.string(),
+  type: z.enum(SCHEMA_ORG_TYPES),
+  slug: z.string().regex(SLUG_PATTERN),
+  locale: localeSchema,
+});
+
+/** next@16.3.3 `NEXT_CACHE_TAG_MAX_LENGTH` (dist/lib/constants.js). */
+const CACHE_TAG_MAX_LENGTH = 256;
 
 /**
  * A FORMAT guard, not a secret-dependent one — it compares the header against
@@ -48,34 +86,39 @@ const EVENT_HEADER = "x-ailk-revalidate-event";
  */
 const SIGNATURE_SHAPE = /^sha256=[0-9a-f]{64}$/;
 
-type RevalidateBody = {
-  workspaceId: string;
-  type: string;
-  slug: string;
-  locale: string;
-};
+type RevalidateBody = z.infer<typeof bodySchema>;
 
 /**
  * Line-for-line the repo's one shipped verifier
- * (apps/api/src/routes/slack/actions.ts:50-62), with the base string changed
- * from Slack's `v0:<ts>:<body>` to the raw body. The length guard is required,
+ * (apps/api/src/routes/slack/actions.ts:50-62), with Slack's `v0:<ts>:<body>`
+ * base string extended by the event (#5902). The length guard is required,
  * not decorative: timingSafeEqual throws on unequal lengths. The `sha256=`
  * prefix stays inside the compared material so a same-length `sha512=` header
  * is rejected outright rather than compared against a sha256 digest.
  */
 function isValidSignature(
   rawBody: string,
+  timestamp: string,
+  event: string,
   provided: string,
   secret: string,
 ): boolean {
-  const expected = `sha256=${createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
+  const base = `v0:${timestamp}:${event}:${rawBody}`;
+  const expected = `sha256=${createHmac("sha256", secret).update(base, "utf8").digest("hex")}`;
   const expectedBuf = Buffer.from(expected, "utf8");
   const providedBuf = Buffer.from(provided, "utf8");
   if (expectedBuf.length !== providedBuf.length) return false;
   return timingSafeEqual(expectedBuf, providedBuf);
 }
 
-/** The parsed four-key body, or null if the payload is not one (FR5). */
+/** True when `timestamp` is unix seconds within the tolerance of now. */
+function isFreshTimestamp(timestamp: string): boolean {
+  if (!TIMESTAMP_SHAPE.test(timestamp)) return false;
+  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
+  return ageSeconds <= SIGNATURE_TOLERANCE_SECONDS;
+}
+
+/** The parsed, bounded four-key body, or null if the payload is not one (FR5). */
 function parseBody(rawBody: string): RevalidateBody | null {
   let parsed: unknown;
   try {
@@ -83,22 +126,17 @@ function parseBody(rawBody: string): RevalidateBody | null {
   } catch {
     return null;
   }
-  // The array clause is belt-and-braces: the four string checks below already
-  // reject `[]`. It stays because FR5 says "a non-object" and an
-  // unauthenticated path is the wrong place to make a reader derive that.
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    return null;
-  }
-  const { workspaceId, type, slug, locale } = parsed as Record<string, unknown>;
-  if (
-    typeof workspaceId !== "string" ||
-    typeof type !== "string" ||
-    typeof slug !== "string" ||
-    typeof locale !== "string"
-  ) {
+  // z.object rejects `[]`, `null` and every non-object; the four field
+  // shapes do the rest.
+  const result = bodySchema.safeParse(parsed);
+  if (!result.success) return null;
+  // The field shapes bound type and locale but not slug's length; a page tag
+  // over Next's limit could not have been cached under, so it is not a body.
+  const { type, slug, locale } = result.data;
+  if (contentPageTag({ type, slug, locale }).length > CACHE_TAG_MAX_LENGTH) {
     return null;
   }
-  return { workspaceId, type, slug, locale };
+  return result.data;
 }
 
 export async function POST(request: Request): Promise<Response> {
@@ -145,11 +183,15 @@ export async function POST(request: Request): Promise<Response> {
   // (FR3).
   const rawBody = await request.text();
 
+  const timestamp = request.headers.get(TIMESTAMP_HEADER);
   const provided = request.headers.get(SIGNATURE_HEADER);
   if (
+    event === "unknown" ||
+    timestamp === null ||
+    !isFreshTimestamp(timestamp) ||
     provided === null ||
     !SIGNATURE_SHAPE.test(provided) ||
-    !isValidSignature(rawBody, provided, secret)
+    !isValidSignature(rawBody, timestamp, event, provided, secret)
   ) {
     log("warn", { status: 401 });
     return Response.json({ error: "invalid_signature" }, { status: 401 });

package/templates/apps/web/lib/__tests__/site-brand.test.ts

@@ -117,3 +117,82 @@ describe("SITE_NAME / SITE_BASE_URL (#4157)", () => {
     expect(SITE_NAME).toBe(FALLBACK_SITE_NAME);
   });
 });
+
+/**
+ * `siteLogo()` — the brand triad's logomark (#6820 D5). No `brand:` renders
+ * exactly today's element; a declared mark is the one rendered, with its dark
+ * source kept when it differs; a malformed mark throws naming the field on
+ * the render, not at module init.
+ */
+describe("siteLogo() — brand.logomark (#6820)", () => {
+  /** `site-logo.tsx` re-imported alongside a fresh `site-brand`. */
+  async function loadSiteLogo(): Promise<
+    typeof import("../site-logo") & typeof import("../site-brand")
+  > {
+    const brand = await loadSiteBrand();
+    return { ...brand, ...(await import("../site-logo")) };
+  }
+
+  function writeRaw(frontmatter: string): void {
+    writeFileSync(
+      join(tmpRoot, "_site.mdx"),
+      `---\nsiteName: Fixture Co\n${frontmatter}---\n`,
+    );
+    process.env["AILK_CONTENT_ROOT"] = tmpRoot;
+    delete process.env["NEXT_PUBLIC_SITE_NAME"];
+  }
+
+  it("with no brand: renders today's /logomark.svg element", async () => {
+    writeRaw("");
+    const { siteLogo, SITE_NAME } = await loadSiteLogo();
+    const logo = siteLogo();
+
+    expect(logo.type).toBe("img");
+    expect(logo.props).toStrictEqual({
+      src: "/logomark.svg",
+      alt: SITE_NAME,
+      width: 28,
+      height: 28,
+      className: "block",
+    });
+  });
+
+  it("with light === dark: renders an img with the declared src and alt", async () => {
+    writeRaw("brand:\n  logomark: { light: /acme.svg, dark: /acme.svg, alt: Acme }\n");
+    const { siteLogo } = await loadSiteLogo();
+    const logo = siteLogo();
+
+    expect(logo.type).toBe("img");
+    expect(logo.props).toStrictEqual({
+      src: "/acme.svg",
+      alt: "Acme",
+      width: 28,
+      height: 28,
+      className: "block",
+    });
+  });
+
+  it("with light !== dark: renders the Image primitive with darkSrc", async () => {
+    writeRaw("brand:\n  logomark: { light: /acme.svg, dark: /acme-dark.svg, alt: Acme }\n");
+    const { siteLogo } = await loadSiteLogo();
+    const { Image } = await import("@working-theory/ui/primitives");
+    const logo = siteLogo();
+
+    expect(logo.type).toBe(Image);
+    expect(logo.props).toStrictEqual({
+      src: "/acme.svg",
+      darkSrc: "/acme-dark.svg",
+      alt: "Acme",
+      width: 28,
+      height: 28,
+    });
+  });
+
+  it("a logomark missing alt throws naming alt, while SITE_NAME still resolves", async () => {
+    writeRaw("brand:\n  logomark: { light: /acme.svg, dark: /acme.svg }\n");
+    const { siteLogo, SITE_NAME } = await loadSiteLogo();
+
+    expect(SITE_NAME).toBe("Fixture Co");
+    expect(() => siteLogo()).toThrow(/alt/);
+  });
+});