create-ailk 0.11.1 → 0.11.3

package/templates/apps/api/src/middleware/rate-limit.ts

@@ -45,8 +45,28 @@
  * call — appending to, not replacing, whatever hop this API's own edge adds,
  * so trustProxy's leftmost-address resolution still lands on the real
  * visitor.
+ *
+ * Per-visitor lead writes from a keyed spoke (#7394): a spoke's lead writes
+ * carry the visitor's IP in `x-ailk-visitor-ip`, which this middleware
+ * believes only alongside a hub-issued key in `x-ailk-visitor-forward-key`,
+ * and only on the three `FORWARDED_VISITOR_ROUTES`. A believed visitor is
+ * counted as `v<n>,<ip>` (n = the key's position in
+ * `AILK_VISITOR_FORWARD_KEYS`), and every such request also counts against
+ * its key's own `key,<n>` bucket. Both forms contain a comma, which `req.ip`
+ * never does, so no unkeyed caller can reach either bucket. Every other
+ * request keys on `req.ip`, as before. Spec:
+ * docs/specs/7394-the-leads-rate-limit-scope-spec.md.
+ *
+ * Scope namespace and env limit (#7394): a registration with a `scope` keys
+ * its buckets as `<scope>|<identity>`, so its count is not shared with any
+ * other registration, and reads its limits from
+ * `AILK_RATE_LIMIT_<SCOPE>_PER_MINUTE` / `..._PER_KEY_PER_MINUTE`, which win
+ * over the code values. A registration with no `scope` behaves as it did.
  */
 
+import { createHash, timingSafeEqual } from "node:crypto";
+import { isIP } from "node:net";
+
 import { getClock } from "@working-theory/common";
 import type {
   FastifyRequest,
@@ -66,7 +86,11 @@ export type RateLimitOptions = {
   perIpPerMinute?: number;
   /** Window duration in milliseconds. Default: 60_000 */
   windowMs?: number;
-  /** Extract the IP key from a request. Default: req.ip */
+  /**
+   * Extract the IP key from a request. Default: the identity
+   * `resolveRateLimitIdentity` returns, which is `req.ip` unless
+   * `trustedKeyDigests` is non-empty. A caller-supplied function wins.
+   */
   ipFromRequest?: (req: FastifyRequest) => string;
   /**
    * Maximum distinct entries `buckets` may hold at once, independent of the
@@ -74,6 +98,25 @@ export type RateLimitOptions = {
    * no production caller overrides this.
    */
   maxBuckets?: number;
+  /**
+   * Bucket namespace (#7394). With one, buckets are keyed
+   * `<scope>|<identity>` and the limits are read from
+   * `AILK_RATE_LIMIT_<SCOPE>_PER_MINUTE` and
+   * `AILK_RATE_LIMIT_<SCOPE>_PER_KEY_PER_MINUTE` first. Must match
+   * `/^[a-z][a-z0-9]*$/`. Without one, buckets are keyed on the bare identity.
+   */
+  scope?: string;
+  /**
+   * The hub's forwarding-key digests, from `buildTrustedKeyDigests` (#7394).
+   * Default: `[]`, which believes no forwarded visitor. A non-empty list
+   * needs a `scope`.
+   */
+  trustedKeyDigests?: readonly (Buffer | null)[];
+  /**
+   * Requests allowed per forwarding key per window, across all of that key's
+   * visitors (#7394). Default: 300.
+   */
+  perKeyPerMinute?: number;
 };
 
 type Bucket = {
@@ -98,9 +141,184 @@ export const DEFAULT_PER_IP_PER_MINUTE_STRICT = 10;
  */
 export const MAX_BUCKETS = 10_000;
 
-// Module-scoped bucket store. One entry per unique IP.
+/**
+ * The only routes on which a forwarded visitor IP is believed (#7394 DD-2):
+ * the three lead writes. Matched against `req.routeOptions.url`, the
+ * registered route pattern.
+ */
+export const FORWARDED_VISITOR_ROUTES: readonly string[] = [
+  "/v1/leads/submit",
+  "/v1/leads/subscribe",
+  "/v1/leads/callback",
+];
+
+const VISITOR_IP_HEADER = "x-ailk-visitor-ip";
+const FORWARD_KEY_HEADER = "x-ailk-visitor-forward-key";
+const MIN_FORWARD_KEY_LENGTH = 32;
+const MAX_VISITOR_IP_LENGTH = 45;
+const DEFAULT_PER_KEY_PER_MINUTE = 300;
+const SCOPE_RE = /^[a-z][a-z0-9]*$/;
+const ENV_LIMIT_RE = /^[1-9][0-9]{0,5}$/;
+
+function sha256(value: string): Buffer {
+  return createHash("sha256").update(value).digest();
+}
+
+/**
+ * Parse `AILK_VISITOR_FORWARD_KEYS` (comma-separated, one entry per spoke)
+ * into one SHA-256 digest per accepted entry. An empty entry, or one shorter
+ * than 32 characters, becomes `null` so every other entry keeps its position.
+ * A short entry is reported by its 1-based position, never its value.
+ */
+export function buildTrustedKeyDigests(
+  raw: string | undefined,
+  warn: (msg: string) => void,
+): readonly (Buffer | null)[] {
+  if (raw === undefined || raw.trim() === "") return [];
+  return raw.split(",").map((entry, index) => {
+    const key = entry.trim();
+    if (key === "") return null;
+    if (key.length < MIN_FORWARD_KEY_LENGTH) {
+      warn(
+        `AILK_VISITOR_FORWARD_KEYS entry ${index + 1} has fewer than ${MIN_FORWARD_KEY_LENGTH} characters and is ignored`,
+      );
+      return null;
+    }
+    return sha256(key);
+  });
+}
+
+/** The eight hextets of a valid IPv6 address, or `null`. */
+function expandIpv6(address: string): number[] | null {
+  let text = address;
+  const tail: number[] = [];
+  const lastColon = text.lastIndexOf(":");
+  const last = text.slice(lastColon + 1);
+  if (last.includes(".")) {
+    const octets = last.split(".").map(Number);
+    tail.push(((octets[0] ?? 0) << 8) | (octets[1] ?? 0));
+    tail.push(((octets[2] ?? 0) << 8) | (octets[3] ?? 0));
+    text = `${text.slice(0, lastColon + 1)}0`;
+  }
+  const halves = text.split("::");
+  const parse = (part: string | undefined): number[] =>
+    part ? part.split(":").map((hextet) => parseInt(hextet, 16)) : [];
+  const head = parse(halves[0]);
+  const rest = parse(halves[1]);
+  if (tail.length > 0) {
+    // The `0` placeholder stood in for the dotted tail's two hextets.
+    (halves.length > 1 ? rest : head).pop();
+  }
+  const fill = 8 - head.length - rest.length - tail.length;
+  if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
+  const hextets = [
+    ...head,
+    ...new Array<number>(fill).fill(0),
+    ...rest,
+    ...tail,
+  ];
+  return hextets.every((h) => Number.isInteger(h) && h >= 0 && h <= 0xffff)
+    ? hextets
+    : null;
+}
+
+/**
+ * Validate and normalise a forwarded visitor IP (#7394 DD-1): IPv4 as is, an
+ * IPv4-mapped IPv6 address as its IPv4 form, any other IPv6 address as its
+ * /64 prefix. `null` for anything else.
+ */
+function normaliseVisitorIp(raw: string): string | null {
+  const value = raw.trim().toLowerCase();
+  if (value.length > MAX_VISITOR_IP_LENGTH || value.includes("%")) return null;
+  const family = isIP(value);
+  if (family === 4) return value;
+  if (family !== 6) return null;
+  const hextets = expandIpv6(value);
+  if (!hextets) return null;
+  const isV4Mapped =
+    hextets.slice(0, 5).every((h) => h === 0) && hextets[5] === 0xffff;
+  if (isV4Mapped) {
+    const high = hextets[6] ?? 0;
+    const low = hextets[7] ?? 0;
+    return [high >> 8, high & 0xff, low >> 8, low & 0xff].join(".");
+  }
+  const prefix = hextets
+    .slice(0, 4)
+    .map((h) => h.toString(16).padStart(4, "0"))
+    .join(":");
+  return `${prefix}::/64`;
+}
+
+/**
+ * The rate-limit identity of a request (#7394 DD-2). A `POST` to one of
+ * `FORWARDED_VISITOR_ROUTES`, presenting a key whose digest matches a
+ * non-null slot, with a valid `x-ailk-visitor-ip`, is `v<n>,<ip>` where `n`
+ * is the first matching slot. Everything else is `req.ip`. Every slot is
+ * compared, in constant time per slot, without stopping at the first match.
+ */
+export function resolveRateLimitIdentity(
+  req: FastifyRequest,
+  trustedKeyDigests: readonly (Buffer | null)[],
+): { identity: string; keyIndex: number | null } {
+  const fallback = { identity: req.ip, keyIndex: null };
+  if (!trustedKeyDigests.some((digest) => digest !== null)) return fallback;
+  if (req.method !== "POST") return fallback;
+  if (!FORWARDED_VISITOR_ROUTES.includes(req.routeOptions.url ?? "")) {
+    return fallback;
+  }
+
+  const presented = req.headers[FORWARD_KEY_HEADER];
+  if (typeof presented !== "string" || presented === "") return fallback;
+  const presentedDigest = sha256(presented);
+  let keyIndex: number | null = null;
+  for (const [index, digest] of trustedKeyDigests.entries()) {
+    if (digest === null) continue;
+    const matched = timingSafeEqual(digest, presentedDigest);
+    if (matched && keyIndex === null) keyIndex = index;
+  }
+  if (keyIndex === null) return fallback;
+
+  const visitorIp = req.headers[VISITOR_IP_HEADER];
+  const normalised =
+    typeof visitorIp === "string" ? normaliseVisitorIp(visitorIp) : null;
+  if (normalised === null) return fallback;
+  return { identity: `v${keyIndex},${normalised}`, keyIndex };
+}
+
+/**
+ * A named scope's limit (#7394 DD-4): `AILK_RATE_LIMIT_<SCOPE>_<suffix>` when
+ * it is a whole number from 1 to 999999, else `fallback`. A set but invalid
+ * value is reported once and ignored. An unnamed registration always gets
+ * `fallback`.
+ */
+function resolveScopedLimit(
+  scope: string | undefined,
+  suffix: "PER_MINUTE" | "PER_KEY_PER_MINUTE",
+  fallback: number,
+  warn: (msg: string) => void,
+): number {
+  if (scope === undefined) return fallback;
+  const name = `AILK_RATE_LIMIT_${scope.toUpperCase()}_${suffix}`;
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  if (ENV_LIMIT_RE.test(raw)) return Number(raw);
+  warn(
+    `${name} is not a whole number from 1 to 999999 and is ignored; using ${fallback}`,
+  );
+  return fallback;
+}
+
+// Module-scoped bucket store. One entry per unique identity, per named scope
+// (#7394). Per-forwarding-key buckets live in `keyBuckets` below.
 const buckets = new Map<string, Bucket>();
 
+// Per-forwarding-key buckets (#7394 DD-8), kept apart from `buckets` so the
+// `maxBuckets` FIFO eviction can never drop one: a keyed caller churning
+// visitor IPs would otherwise push its own key bucket out and reset its
+// ceiling. At most one entry per configured key per named scope, so it
+// needs no capacity cap of its own.
+const keyBuckets = new Map<string, Bucket>();
+
 // Request counter used to trigger periodic cleanup.
 let requestsSinceLastClean = 0;
 const CLEAN_INTERVAL_REQUESTS = 100;
@@ -111,6 +329,11 @@ function evictStaleBuckets(now: number, windowMs: number): void {
       buckets.delete(ip);
     }
   }
+  for (const [key, bucket] of keyBuckets) {
+    if (now - bucket.windowStartMs >= windowMs) {
+      keyBuckets.delete(key);
+    }
+  }
   requestsSinceLastClean = 0;
 }
 
@@ -120,6 +343,7 @@ function evictStaleBuckets(now: number, windowMs: number): void {
  */
 export function __resetBuckets(): void {
   buckets.clear();
+  keyBuckets.clear();
   requestsSinceLastClean = 0;
 }
 
@@ -141,47 +365,123 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
   done,
 ) => {
   const {
-    perIpPerMinute = Number(process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE) ||
-      20,
     windowMs = 60_000,
-    ipFromRequest = (req: FastifyRequest) => req.ip,
     maxBuckets = MAX_BUCKETS,
+    scope,
+    trustedKeyDigests = [],
   } = opts;
 
+  if (scope !== undefined && !SCOPE_RE.test(scope)) {
+    done(
+      new Error(
+        `rate-limit scope ${JSON.stringify(scope)} must match ${SCOPE_RE}`,
+      ),
+    );
+    return;
+  }
+  if (trustedKeyDigests.length > 0 && scope === undefined) {
+    done(new Error("rate-limit trustedKeyDigests needs a scope"));
+    return;
+  }
+
+  const warn = (msg: string) => fastify.log.warn(msg);
+  const perIpPerMinute = resolveScopedLimit(
+    scope,
+    "PER_MINUTE",
+    opts.perIpPerMinute ??
+      (Number(process.env.AILK_RATE_LIMIT_PER_IP_PER_MINUTE) || 20),
+    warn,
+  );
+  const perKeyPerMinute = resolveScopedLimit(
+    scope,
+    "PER_KEY_PER_MINUTE",
+    opts.perKeyPerMinute ?? DEFAULT_PER_KEY_PER_MINUTE,
+    warn,
+  );
+  const { ipFromRequest } = opts;
+  const identityOf: (req: FastifyRequest) => {
+    identity: string;
+    keyIndex: number | null;
+  } = ipFromRequest
+    ? (req) => ({ identity: ipFromRequest(req), keyIndex: null })
+    : (req) => resolveRateLimitIdentity(req, trustedKeyDigests);
+  const bucketKey = (identity: string) =>
+    scope === undefined ? identity : `${scope}|${identity}`;
+
+  /** Count one request against `key`, opening a new window when needed. */
+  function hit(key: string, now: number): Bucket {
+    let bucket = buckets.get(key);
+
+    if (!bucket || now - bucket.windowStartMs >= windowMs) {
+      // A genuinely new distinct identity (not a window roll on an
+      // existing bucket) at capacity evicts the single oldest-inserted
+      // entry first — independent of the time-based eviction above,
+      // which only removes EXPIRED windows and may leave `buckets` at or
+      // above `maxBuckets` when every entry is still within its window.
+      if (!buckets.has(key) && buckets.size >= maxBuckets) {
+        const oldestKey = buckets.keys().next().value;
+        if (oldestKey !== undefined) {
+          buckets.delete(oldestKey);
+        }
+      }
+      bucket = { count: 0, windowStartMs: now };
+      buckets.set(key, bucket);
+    }
+
+    bucket.count += 1;
+    return bucket;
+  }
+
+  /** True when `key` has a bucket whose window has not yet ended. */
+  function hasOpenWindow(key: string, now: number): boolean {
+    const bucket = buckets.get(key);
+    return bucket !== undefined && now - bucket.windowStartMs < windowMs;
+  }
+
+  /** Count one request against a forwarding key's own bucket (DD-8). */
+  function hitKey(key: string, now: number): Bucket {
+    let bucket = keyBuckets.get(key);
+    if (!bucket || now - bucket.windowStartMs >= windowMs) {
+      bucket = { count: 0, windowStartMs: now };
+      keyBuckets.set(key, bucket);
+    }
+    bucket.count += 1;
+    return bucket;
+  }
+
   fastify.addHook(
     "onRequest",
     async (req: FastifyRequest, reply: FastifyReply) => {
       const now = getClock().now();
-      const ip = ipFromRequest(req);
+      const { identity: ip, keyIndex } = identityOf(req);
 
       requestsSinceLastClean += 1;
       if (requestsSinceLastClean >= CLEAN_INTERVAL_REQUESTS) {
         evictStaleBuckets(now, windowMs);
       }
 
-      let bucket = buckets.get(ip);
-
-      if (!bucket || now - bucket.windowStartMs >= windowMs) {
-        // A genuinely new distinct identity (not a window roll on an
-        // existing bucket) at capacity evicts the single oldest-inserted
-        // entry first — independent of the time-based eviction above,
-        // which only removes EXPIRED windows and may leave `buckets` at or
-        // above `maxBuckets` when every entry is still within its window.
-        if (!buckets.has(ip) && buckets.size >= maxBuckets) {
-          const oldestKey = buckets.keys().next().value;
-          if (oldestKey !== undefined) {
-            buckets.delete(oldestKey);
-          }
-        }
-        bucket = { count: 0, windowStartMs: now };
-        buckets.set(ip, bucket);
-      }
+      // #7394 DD-8: a keyed request also counts against its key's own
+      // bucket, even when the visitor bucket is already over its limit.
+      const keyBucket =
+        keyIndex === null ? undefined : hitKey(`${scope}|key,${keyIndex}`, now);
+      const keyOver =
+        keyBucket !== undefined && keyBucket.count > perKeyPerMinute;
+      // A key over its ceiling opens no NEW visitor bucket (#7394 security
+      // review R-1). Each new entry can evict the oldest one in `buckets`,
+      // another scope's counter included, so without this a key holder
+      // rotating visitor IPs could wipe every strict limiter at will. A
+      // visitor whose window is still open is counted as usual.
+      const visitorKey = bucketKey(ip);
+      const bucket =
+        keyOver && !hasOpenWindow(visitorKey, now)
+          ? undefined
+          : hit(visitorKey, now);
+      const visitorOver = bucket !== undefined && bucket.count > perIpPerMinute;
+      const tripped = visitorOver ? bucket : keyOver ? keyBucket : undefined;
 
-      bucket.count += 1;
-
-      if (bucket.count > perIpPerMinute) {
+      if (tripped) {
         const retryAfterSeconds = Math.ceil(
-          (bucket.windowStartMs + windowMs - now) / 1_000,
+          (tripped.windowStartMs + windowMs - now) / 1_000,
         );
 
         // Evict stale buckets on every 429 to cap memory under abuse.
@@ -193,7 +493,20 @@ export const rateLimitMiddleware: FastifyPluginCallback<RateLimitOptions> = (
         // will — logging the raw target would let them farm credentials out of
         // the operator's own log by tripping the limiter.
         const pathOnly = req.url.split("?")[0] ?? req.url;
-        req.log.warn({ ip, path: pathOnly, count: bucket.count }, RATE_LIMITED);
+        // A keyed 429 names the bucket that tripped and the key's position,
+        // so a misused key can be traced to its spoke; never the key itself.
+        req.log.warn(
+          {
+            ip,
+            path: pathOnly,
+            count: tripped.count,
+            ...(keyIndex !== null && {
+              bucket: visitorOver ? "visitor" : "key",
+              keyIndex,
+            }),
+          },
+          RATE_LIMITED,
+        );
 
         return reply
           .status(429)

package/templates/apps/api/src/routes/auth/__tests__/auth-tokens.functional.test.ts

@@ -42,7 +42,7 @@ const FRONTEND = "https://app.example.com";
 
 async function buildApp(): Promise<FastifyInstance> {
   const app = Fastify();
-  app.register(authPreHandlerPlugin, { frontendOrigin: FRONTEND });
+  app.register(authPreHandlerPlugin, { trustedOrigins: [FRONTEND] });
   app.register(tokenRoutes);
   await app.ready();
   return app;

package/templates/apps/api/src/routes/auth/__tests__/auth-user.functional.test.ts

@@ -37,7 +37,7 @@ const FRONTEND = "https://app.example.com";
 
 async function buildApp(): Promise<FastifyInstance> {
   const app = Fastify();
-  app.register(authPreHandlerPlugin, { frontendOrigin: FRONTEND });
+  app.register(authPreHandlerPlugin, { trustedOrigins: [FRONTEND] });
   app.register(userRoutes);
   await app.ready();
   return app;

package/templates/apps/api/src/routes/auth/__tests__/transactional-email.test.ts

@@ -29,6 +29,7 @@ import type { FastifyInstance } from "fastify";
 const mockSendPasswordReset = jest.fn();
 const mockSendPasswordChanged = jest.fn();
 const mockSendEmailVerification = jest.fn();
+const mockSendMagicLink = jest.fn();
 
 jest.mock("@working-theory/email", () => ({
   sendPasswordResetEmail: (...args: unknown[]) =>
@@ -37,6 +38,7 @@ jest.mock("@working-theory/email", () => ({
     mockSendPasswordChanged(...args),
   sendEmailVerificationEmail: (...args: unknown[]) =>
     mockSendEmailVerification(...args),
+  sendMagicLink: (...args: unknown[]) => mockSendMagicLink(...args),
 }));
 
 import { __resetAuthEmailBudget } from "../../../lib/auth-email-budget.js";
@@ -62,6 +64,18 @@ function bodyFor(overrides: Record<string, unknown> = {}): string {
   });
 }
 
+const MAGIC_LINK_URL =
+  "https://site.example/api/auth/magic-link/verify?token=mltok&callbackURL=%2Faccount";
+
+function magicLinkBody(): string {
+  return JSON.stringify({
+    kind: "magic-link",
+    userId: "user_01",
+    to: "person@example.com",
+    url: MAGIC_LINK_URL,
+  });
+}
+
 async function buildApp(): Promise<FastifyInstance> {
   const app = Fastify();
   // The raw-body parser the route's scope carries in server.ts — the
@@ -108,6 +122,7 @@ beforeEach(async () => {
   mockSendPasswordReset.mockResolvedValue({ ok: true, messageId: "m1" });
   mockSendPasswordChanged.mockResolvedValue({ ok: true, messageId: "m2" });
   mockSendEmailVerification.mockResolvedValue({ ok: true, messageId: "m3" });
+  mockSendMagicLink.mockResolvedValue({ ok: true, messageId: "m4" });
   app = await buildApp();
 });
 
@@ -185,7 +200,7 @@ describe("POST /v1/auth/transactional-email — the gate", () => {
     expect(res.json()).toEqual({ error: "validation_failed" });
   });
 
-  it("answers 400 for a kind outside the fixed three", async () => {
+  it("answers 400 for a kind outside the fixed four", async () => {
     const res = await post(app, {
       rawBody: bodyFor({ kind: "arbitrary-marketing-blast" }),
     });
@@ -196,6 +211,18 @@ describe("POST /v1/auth/transactional-email — the gate", () => {
     const res = await post(app, { rawBody: bodyFor({ url: undefined }) });
     expect(res.statusCode).toBe(400);
   });
+
+  it("answers 400 for a magic-link with no url (#7435 AC-4)", async () => {
+    const res = await post(app, {
+      rawBody: bodyFor({
+        kind: "magic-link",
+        url: undefined,
+        expiresInMinutes: undefined,
+      }),
+    });
+    expect(res.statusCode).toBe(400);
+    expect(mockSendMagicLink).not.toHaveBeenCalled();
+  });
 });
 
 describe("POST /v1/auth/transactional-email — the sends", () => {
@@ -238,6 +265,36 @@ describe("POST /v1/auth/transactional-email — the sends", () => {
     expect(mockSendPasswordReset).not.toHaveBeenCalled();
   });
 
+  it("sends a magic-link through the magic-link template with no expiry override (#7435 D4)", async () => {
+    const res = await post(app, { rawBody: magicLinkBody() });
+    expect(res.statusCode).toBe(202);
+    expect(res.json()).toEqual({ ok: true });
+    expect(mockSendMagicLink).toHaveBeenCalledTimes(1);
+    const [input] = mockSendMagicLink.mock.calls[0];
+    expect(input).toEqual({
+      to: "person@example.com",
+      url: MAGIC_LINK_URL,
+      fromAddress: FROM,
+    });
+    // A sign-in link must never arrive dressed as a reset or a verification.
+    expect(mockSendPasswordReset).not.toHaveBeenCalled();
+    expect(mockSendEmailVerification).not.toHaveBeenCalled();
+  });
+
+  it("budgets magic-link per recipient on its own key — three sends, four 202s, reset unaffected (#7435 AC-3)", async () => {
+    for (let i = 0; i < 4; i++) {
+      const r = await post(app, { rawBody: magicLinkBody() });
+      expect(r.statusCode).toBe(202);
+      expect(r.json()).toEqual({ ok: true });
+    }
+    expect(mockSendMagicLink).toHaveBeenCalledTimes(3);
+
+    // The magic-link budget neither consumes nor is consumed by reset's.
+    const reset = await post(app);
+    expect(reset.statusCode).toBe(202);
+    expect(mockSendPasswordReset).toHaveBeenCalledTimes(1);
+  });
+
   it("answers 202 even when the sender reports a failure — never an oracle", async () => {
     mockSendPasswordReset.mockResolvedValue({
       ok: false,
@@ -306,4 +363,51 @@ describe("the PII boundary (§ D12)", () => {
     expect(joined).not.toContain("site.example/api/auth");
     await loggingApp.close();
   });
+
+  it("logs no recipient, no token and no link for a magic-link send (#7435)", async () => {
+    const lines: string[] = [];
+    const capture = new Proxy(
+      {},
+      {
+        get: () => (obj: unknown, msg?: unknown) =>
+          lines.push(JSON.stringify({ obj, msg })),
+      },
+    ) as never;
+
+    const loggingApp = Fastify({ logger: false });
+    loggingApp.addContentTypeParser(
+      "application/json",
+      { parseAs: "buffer" },
+      (_req, body, done) => done(null, body),
+    );
+    loggingApp.addHook("onRequest", async (req) => {
+      // eslint-disable-next-line no-restricted-syntax -- the point of this case is to capture what the handler LOGS, and Fastify types `req.log` as a concrete Logger; there is no boundary type to fix.
+      (req as unknown as { log: unknown }).log = capture;
+    });
+    await loggingApp.register(transactionalEmailRoute);
+    await loggingApp.ready();
+
+    // Four sends: three logged as sent, the fourth as budget-suppressed.
+    for (let i = 0; i < 4; i++) {
+      const ts = String(Math.floor(Date.now() / 1000));
+      const raw = magicLinkBody();
+      await loggingApp.inject({
+        method: "POST",
+        url: "/v1/auth/transactional-email",
+        headers: {
+          "content-type": "application/json",
+          "x-ailk-auth-email-signature": sign(raw, ts),
+          "x-ailk-auth-email-timestamp": ts,
+        },
+        payload: raw,
+      });
+    }
+
+    const joined = lines.join("|");
+    expect(joined).toContain("magic-link");
+    expect(joined).not.toContain("person@example.com");
+    expect(joined).not.toContain("mltok");
+    expect(joined).not.toContain("magic-link/verify");
+    await loggingApp.close();
+  });
 });