create-ailk 0.5.0 → 0.6.0

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

@@ -0,0 +1,309 @@
+/**
+ * @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();
+
+jest.mock("@working-theory/email", () => ({
+  sendPasswordResetEmail: (...args: unknown[]) =>
+    mockSendPasswordReset(...args),
+  sendPasswordChangedEmail: (...args: unknown[]) =>
+    mockSendPasswordChanged(...args),
+  sendEmailVerificationEmail: (...args: unknown[]) =>
+    mockSendEmailVerification(...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,
+  });
+}
+
+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" });
+  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 three", 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);
+  });
+});
+
+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("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();
+  });
+});

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

@@ -306,6 +306,103 @@ describe('User Routes', () => {
     });
   });
 
+  describe('reserved user-data keys — #6034 § D12', () => {
+    async function buildAuthenticatedApp(): Promise<FastifyInstance> {
+      const fastify2 = require('fastify')();
+      fastify2.decorateRequest('userId', null);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
+      fastify2.addHook('preHandler', async (request: any) => {
+        request.userId = 'user_123';
+      });
+      await fastify2.register(userRoutes);
+      return fastify2;
+    }
+
+    it.each(['commerce.subscription_dunning', 'Commerce.Subscription_Dunning', 'system.anything'])(
+      'GET %s refuses 403 with zero Prisma calls',
+      async (key) => {
+        const fastify2 = await buildAuthenticatedApp();
+
+        const response = await fastify2.inject({
+          method: 'GET',
+          url: `/v1/user/data/${key}`,
+        });
+
+        expect(response.statusCode).toBe(403);
+        expect(JSON.parse(response.body)).toEqual({
+          success: false,
+          error: 'reserved-key',
+        });
+        expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+
+        await fastify2.close();
+      },
+    );
+
+    it.each(['commerce.subscription_dunning', 'Commerce.Subscription_Dunning', 'system.anything'])(
+      'PUT %s refuses 403 with zero Prisma calls',
+      async (key) => {
+        const fastify2 = await buildAuthenticatedApp();
+
+        const response = await fastify2.inject({
+          method: 'PUT',
+          url: `/v1/user/data/${key}`,
+          payload: { status: 'active' },
+        });
+
+        expect(response.statusCode).toBe(403);
+        expect(JSON.parse(response.body)).toEqual({
+          success: false,
+          error: 'reserved-key',
+        });
+        expect(prisma.userData.upsert).not.toHaveBeenCalled();
+
+        await fastify2.close();
+      },
+    );
+
+    it.each(['commerce.subscription_dunning', 'Commerce.Subscription_Dunning', 'system.anything'])(
+      'DELETE %s refuses 403 with zero Prisma calls',
+      async (key) => {
+        const fastify2 = await buildAuthenticatedApp();
+
+        const response = await fastify2.inject({
+          method: 'DELETE',
+          url: `/v1/user/data/${key}`,
+        });
+
+        expect(response.statusCode).toBe(403);
+        expect(JSON.parse(response.body)).toEqual({
+          success: false,
+          error: 'reserved-key',
+        });
+        expect(prisma.userData.deleteMany).not.toHaveBeenCalled();
+
+        await fastify2.close();
+      },
+    );
+
+    it('an unreserved key is unaffected — the existing prefs path stays green', async () => {
+      const fastify2 = await buildAuthenticatedApp();
+      (prisma.userData.upsert as jest.Mock).mockResolvedValue({
+        userId: 'user_123',
+        key: 'preferences',
+        value: { theme: 'light' },
+      });
+
+      const response = await fastify2.inject({
+        method: 'PUT',
+        url: '/v1/user/data/preferences',
+        payload: { theme: 'light' },
+      });
+
+      expect(response.statusCode).toBe(200);
+      expect(prisma.userData.upsert).toHaveBeenCalled();
+
+      await fastify2.close();
+    });
+  });
+
   describe('PUT /v1/user/data/:key', () => {
     it('should return 401 when user is not authenticated', async () => {
       const response = await app.inject({
@@ -381,6 +478,32 @@ describe('User Routes', () => {
 
       await fastify2.close();
     });
+
+    it('rejects a value whose serialized size exceeds 64 KiB — #6034 § D12', async () => {
+      const fastify2 = require('fastify')();
+      fastify2.decorateRequest('userId', null);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
+      fastify2.addHook('preHandler', async (request: any) => {
+        request.userId = 'user_123';
+      });
+      await fastify2.register(userRoutes);
+
+      const oversized = { blob: 'x'.repeat(70 * 1024) };
+
+      const response = await fastify2.inject({
+        method: 'PUT',
+        url: '/v1/user/data/preferences',
+        payload: oversized,
+      });
+
+      expect(response.statusCode).toBe(400);
+      const body = JSON.parse(response.body);
+      expect(body.success).toBe(false);
+      expect(body.error).toBe('value-too-large');
+      expect(prisma.userData.upsert).not.toHaveBeenCalled();
+
+      await fastify2.close();
+    });
   });
 
   describe('DELETE /v1/user/data/:key', () => {