create-ailk 0.24.0 → 0.26.0

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

@@ -1,413 +0,0 @@
-/**
- * @file transactional-email.test.ts — the signed auth-email relay (#5962 § D3).
- *
- * Written before the implementation. This route is the one thing `apps/web`
- * cannot do for itself — `architecture.yaml` denies `apps/web` →
- * `packages/email` — so it takes a caller-chosen recipient and a caller-chosen
- * URL. That shape is mail-relay-shaped, and the whole of what makes it
- * tolerable is asserted here rather than assumed:
- *
- *   - the rejection ORDER is 503 → 401 → 400, and the signature is verified
- *     over the RAW bytes BEFORE the body is parsed (a 400 before a 401 hands
- *     an unauthenticated caller a JSON-parser oracle);
- *   - the timestamp is inside the signed material and a skew past 300 s is a
- *     401, so a captured body cannot be replayed;
- *   - `kind` selects from FIXED templates — a caller chooses neither subject
- *     nor copy;
- *   - a budget-suppressed send still answers 202. This is the load-bearing
- *     one: an observable suppression is exactly the enumeration oracle the
- *     rest of the design closes;
- *   - no log line carries the recipient, the token, or the assembled link
- *     (§ D12's PII boundary).
- */
-
-import { createHmac } from "node:crypto";
-
-import Fastify from "fastify";
-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[]) =>
-    mockSendPasswordReset(...args),
-  sendPasswordChangedEmail: (...args: unknown[]) =>
-    mockSendPasswordChanged(...args),
-  sendEmailVerificationEmail: (...args: unknown[]) =>
-    mockSendEmailVerification(...args),
-  sendMagicLink: (...args: unknown[]) => mockSendMagicLink(...args),
-}));
-
-import { __resetAuthEmailBudget } from "../../../lib/auth-email-budget.js";
-import { transactionalEmailRoute } from "../transactional-email.js";
-
-const SECRET = "test-webhook-secret";
-const FROM = "noreply@site.example";
-
-function sign(rawBody: string, timestamp: string, secret = SECRET): string {
-  return `sha256=${createHmac("sha256", secret)
-    .update(`${timestamp}.${rawBody}`, "utf8")
-    .digest("hex")}`;
-}
-
-function bodyFor(overrides: Record<string, unknown> = {}): string {
-  return JSON.stringify({
-    kind: "password-reset",
-    userId: "user_01",
-    to: "person@example.com",
-    url: "https://site.example/api/auth/reset-password/tok?callbackURL=%2Freset-password",
-    expiresInMinutes: 60,
-    ...overrides,
-  });
-}
-
-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
-  // signature must be verified over the EXACT bytes, never a re-serialized
-  // parse.
-  app.addContentTypeParser(
-    "application/json",
-    { parseAs: "buffer" },
-    (_req, body, done) => done(null, body),
-  );
-  await app.register(transactionalEmailRoute);
-  await app.ready();
-  return app;
-}
-
-async function post(
-  app: FastifyInstance,
-  {
-    rawBody = bodyFor(),
-    timestamp = String(Math.floor(Date.now() / 1000)),
-    signature,
-  }: { rawBody?: string; timestamp?: string; signature?: string } = {},
-) {
-  return app.inject({
-    method: "POST",
-    url: "/v1/auth/transactional-email",
-    headers: {
-      "content-type": "application/json",
-      "x-ailk-auth-email-signature": signature ?? sign(rawBody, timestamp),
-      "x-ailk-auth-email-timestamp": timestamp,
-    },
-    payload: rawBody,
-  });
-}
-
-let app: FastifyInstance;
-const ORIGINAL_ENV = { ...process.env };
-
-beforeEach(async () => {
-  jest.clearAllMocks();
-  __resetAuthEmailBudget();
-  process.env.AUTH_EMAIL_WEBHOOK_SECRET = SECRET;
-  process.env.AUTH_EMAIL_FROM = FROM;
-  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();
-});
-
-afterEach(async () => {
-  await app.close();
-  process.env = { ...ORIGINAL_ENV };
-});
-
-describe("POST /v1/auth/transactional-email — the gate", () => {
-  it("answers 503 when AUTH_EMAIL_WEBHOOK_SECRET is unset, before any signature check", async () => {
-    delete process.env.AUTH_EMAIL_WEBHOOK_SECRET;
-    const res = await post(app, { signature: "sha256=" + "0".repeat(64) });
-    expect(res.statusCode).toBe(503);
-    expect(res.json()).toEqual({ error: "not_configured" });
-    expect(mockSendPasswordReset).not.toHaveBeenCalled();
-  });
-
-  it("answers 401 on a bad signature", async () => {
-    const res = await post(app, { signature: "sha256=" + "a".repeat(64) });
-    expect(res.statusCode).toBe(401);
-    expect(res.json()).toEqual({ error: "unauthorized" });
-    expect(mockSendPasswordReset).not.toHaveBeenCalled();
-  });
-
-  it("answers 401 on a signature made with a different secret", async () => {
-    const ts = String(Math.floor(Date.now() / 1000));
-    const raw = bodyFor();
-    const res = await post(app, {
-      rawBody: raw,
-      timestamp: ts,
-      signature: sign(raw, ts, "wrong-secret"),
-    });
-    expect(res.statusCode).toBe(401);
-  });
-
-  it("answers 401 on a malformed signature header shape", async () => {
-    const res = await post(app, { signature: "nonsense" });
-    expect(res.statusCode).toBe(401);
-  });
-
-  it("answers 401 when the timestamp is outside the 300 s window (replay)", async () => {
-    const stale = String(Math.floor(Date.now() / 1000) - 301);
-    const raw = bodyFor();
-    const res = await post(app, {
-      rawBody: raw,
-      timestamp: stale,
-      signature: sign(raw, stale),
-    });
-    expect(res.statusCode).toBe(401);
-    expect(mockSendPasswordReset).not.toHaveBeenCalled();
-  });
-
-  it("accepts a timestamp inside the window", async () => {
-    const recent = String(Math.floor(Date.now() / 1000) - 120);
-    const raw = bodyFor();
-    const res = await post(app, {
-      rawBody: raw,
-      timestamp: recent,
-      signature: sign(raw, recent),
-    });
-    expect(res.statusCode).toBe(202);
-  });
-
-  it("answers 401 — not 400 — for an unsigned body that is also unparseable", async () => {
-    const res = await post(app, {
-      rawBody: "{not json",
-      signature: "sha256=" + "b".repeat(64),
-    });
-    expect(res.statusCode).toBe(401);
-  });
-
-  it("answers 400 for a correctly signed body of the wrong shape", async () => {
-    const res = await post(app, { rawBody: JSON.stringify({ kind: "nope" }) });
-    expect(res.statusCode).toBe(400);
-    expect(res.json()).toEqual({ error: "validation_failed" });
-  });
-
-  it("answers 400 for a kind outside the fixed four", async () => {
-    const res = await post(app, {
-      rawBody: bodyFor({ kind: "arbitrary-marketing-blast" }),
-    });
-    expect(res.statusCode).toBe(400);
-  });
-
-  it("answers 400 for a password-reset with no url", async () => {
-    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", () => {
-  it("sends a password-reset through the fixed template and answers 202", async () => {
-    const res = await post(app);
-    expect(res.statusCode).toBe(202);
-    expect(res.json()).toEqual({ ok: true });
-    expect(mockSendPasswordReset).toHaveBeenCalledTimes(1);
-    const [input] = mockSendPasswordReset.mock.calls[0];
-    expect(input.to).toBe("person@example.com");
-    expect(input.fromAddress).toBe(FROM);
-    // The caller chooses neither subject nor copy.
-    expect(input.subject).toBeUndefined();
-  });
-
-  it("sends the password-changed notice with NO url", async () => {
-    const res = await post(app, {
-      rawBody: JSON.stringify({
-        kind: "password-changed",
-        userId: "user_01",
-        to: "person@example.com",
-      }),
-    });
-    expect(res.statusCode).toBe(202);
-    expect(mockSendPasswordChanged).toHaveBeenCalledTimes(1);
-    const [input] = mockSendPasswordChanged.mock.calls[0];
-    expect(input).not.toHaveProperty("url");
-  });
-
-  it("sends an email-verification through its OWN template, never the reset one", async () => {
-    const res = await post(app, {
-      rawBody: bodyFor({
-        kind: "email-verification",
-        url: "https://site.example/api/auth/verify-email?token=jwt",
-      }),
-    });
-    expect(res.statusCode).toBe(202);
-    expect(mockSendEmailVerification).toHaveBeenCalledTimes(1);
-    // A verification message must not claim someone asked to reset a password.
-    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,
-      error: { kind: "send_failed", message: "resend down" },
-    });
-    const res = await post(app);
-    expect(res.statusCode).toBe(202);
-    expect(res.json()).toEqual({ ok: true });
-  });
-
-  it("answers 202 with NO send once the recipient is over budget", async () => {
-    for (let i = 0; i < 3; i++) {
-      const r = await post(app);
-      expect(r.statusCode).toBe(202);
-    }
-    expect(mockSendPasswordReset).toHaveBeenCalledTimes(3);
-
-    const res = await post(app);
-    expect(res.statusCode).toBe(202);
-    expect(res.json()).toEqual({ ok: true });
-    // Suppressed — and indistinguishable from a send.
-    expect(mockSendPasswordReset).toHaveBeenCalledTimes(3);
-  });
-});
-
-describe("the PII boundary (§ D12)", () => {
-  it("logs no recipient, no token and no assembled link", 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();
-
-    const ts = String(Math.floor(Date.now() / 1000));
-    const raw = bodyFor();
-    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).not.toContain("person@example.com");
-    expect(joined).not.toContain("tok");
-    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();
-  });
-});