create-ailk 0.4.0 → 0.6.0

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

@@ -0,0 +1,273 @@
+/**
+ * POST /v1/auth/transactional-email — the signed auth-email relay (#5962 § D3).
+ *
+ * WHY THIS ROUTE EXISTS. `architecture.yaml`'s `apps/web` node carries an
+ * explicit `may_not_import_from` entry for `packages/email` ("email send is
+ * server-side only via apps/api"), and `tools/lint-architecture.ts` evaluates
+ * deny BEFORE allow — so adding an allow entry would not clear it. Better
+ * Auth's password-reset and email-verification callbacks live in `apps/web`
+ * and need to send mail. This is where that crosses.
+ *
+ * API ↔ MCP PARITY — EXEMPT, DECLARED RATHER THAN SKIPPED (§ D19).
+ * `CLAUDE.md`'s parity contract binds "every HTTP endpoint an agent could
+ * reasonably call" to a 1:1 MCP tool. This is not one: it is an internal,
+ * HMAC-signed, machine-to-machine hop whose only caller is `apps/web`'s auth
+ * callbacks, and an MCP twin would be an anonymous agent tool that sends
+ * password-reset mail to an arbitrary address — a credential-reset oracle on
+ * the free surface. The precedent for an `apps/api` route with no twin is
+ * `routes/webhooks/stripe.ts`, a signed receiver in the same shape.
+ *
+ * THE HONEST ACCOUNTING. This endpoint takes a caller-chosen recipient and a
+ * caller-chosen URL: it is mail-relay-shaped. What makes it tolerable is the
+ * whole set, not the HMAC alone — the secret is deployment-only and never
+ * `NEXT_PUBLIC_`; the timestamp is inside the signed material and bounds
+ * replay to 300 s; the route sits behind `rateLimitMiddleware` at
+ * DEFAULT_PER_IP_PER_MINUTE_STRICT; the per-recipient budget bounds volume per
+ * victim; `kind` selects from FIXED templates so a caller chooses neither
+ * subject nor copy; and `packages/email`'s CR/LF guard rejects header
+ * injection on every string field. Anyone who can sign a body can already read
+ * AUTH_EMAIL_WEBHOOK_SECRET off the web deployment — at which point they can
+ * read BETTER_AUTH_SECRET too and forge sessions directly.
+ *
+ * ORDER: 503 → 401 → 400, signature verified over the RAW body BEFORE it is
+ * parsed. The reason is `apps/web/app/api/revalidate/route.ts`'s, verbatim: "a
+ * 400 before 401 would hand an unauthenticated caller a JSON-parser oracle".
+ *
+ * PII BOUNDARY (§ D12): a log line carries `userId`, `kind`, `reason` and an
+ * error KIND. Never the recipient, never the token, never the assembled link —
+ * the link IS the credential, so a log line quoting it hands anyone with log
+ * access a live reset for an arbitrary account.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import {
+  sendEmailVerificationEmail,
+  sendPasswordChangedEmail,
+  sendPasswordResetEmail,
+} from "@working-theory/email";
+import type { FastifyPluginAsync, FastifyRequest } from "fastify";
+
+import {
+  consumeRecipientBudget,
+  siteVolumeAlert,
+  type AuthEmailKind,
+} from "../../lib/auth-email-budget.js";
+
+const SIGNATURE_HEADER = "x-ailk-auth-email-signature";
+const TIMESTAMP_HEADER = "x-ailk-auth-email-timestamp";
+
+/**
+ * A FORMAT guard, not a secret-dependent one — it compares the header against
+ * a constant pattern, never against the digest.
+ */
+const SIGNATURE_SHAPE = /^sha256=[0-9a-f]{64}$/;
+
+/**
+ * How stale a signed body may be. #5851's revalidate pair has NO replay window
+ * and #5877 § D7 accepts that, because a replayed `revalidateTag` is a no-op.
+ * A replayed EMAIL is not a no-op, so this pair closes the gap at the one seam
+ * where it matters.
+ */
+const MAX_SKEW_SECONDS = 300;
+
+const KINDS = new Set<AuthEmailKind>([
+  "password-reset",
+  "email-verification",
+  "password-changed",
+]);
+
+type RelayBody = {
+  kind: AuthEmailKind;
+  userId: string;
+  to: string;
+  url?: string;
+  expiresInMinutes?: number;
+};
+
+/**
+ * Line-for-line the repo's shipped verifier shape
+ * (`apps/web/app/api/revalidate/route.ts`), with the base string changed to
+ * `<timestamp>.<rawBody>` so the timestamp cannot be swapped independently of
+ * the body it authenticates. 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,
+  provided: string,
+  secret: string,
+): boolean {
+  const expected = `sha256=${createHmac("sha256", secret)
+    .update(`${timestamp}.${rawBody}`, "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 body, or null if the payload is not one this relay will send. */
+function parseBody(rawBody: string): RelayBody | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+  const { kind, userId, to, url, expiresInMinutes } = parsed as Record<
+    string,
+    unknown
+  >;
+  if (
+    typeof kind !== "string" ||
+    !KINDS.has(kind as AuthEmailKind) ||
+    typeof userId !== "string" ||
+    userId.length === 0 ||
+    typeof to !== "string" ||
+    to.length === 0
+  ) {
+    return null;
+  }
+  // The two link-carrying kinds need a url; the notice must NOT have one
+  // acted on even if a caller supplies it (§ D17 — the notice carries no
+  // credential, and that is enforced by the sender's input type too).
+  const needsUrl = kind === "password-reset" || kind === "email-verification";
+  if (needsUrl && (typeof url !== "string" || url.length === 0)) return null;
+  if (expiresInMinutes !== undefined && typeof expiresInMinutes !== "number") {
+    return null;
+  }
+
+  return {
+    kind: kind as AuthEmailKind,
+    userId,
+    to,
+    ...(typeof url === "string" ? { url } : {}),
+    ...(typeof expiresInMinutes === "number" ? { expiresInMinutes } : {}),
+  };
+}
+
+export const transactionalEmailRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post(
+    "/v1/auth/transactional-email",
+    async (request: FastifyRequest, reply) => {
+      // Read per request, never at module load: a module-scope const latches
+      // the value at cold start, so a secret added to a running deployment
+      // would keep returning 503 until the lambda recycles.
+      const secret = process.env.AUTH_EMAIL_WEBHOOK_SECRET;
+      const fromAddress = process.env.AUTH_EMAIL_FROM;
+
+      if (!secret || !fromAddress) {
+        request.log.warn(
+          { reason: "not_configured" },
+          "auth-email.not_configured",
+        );
+        return reply.status(503).send({ error: "not_configured" });
+      }
+
+      // Kept as the signed material — never re-serialized. The route's scope
+      // installs a buffer parser for exactly this reason.
+      const raw = request.body;
+      const rawBody = Buffer.isBuffer(raw)
+        ? raw.toString("utf8")
+        : typeof raw === "string"
+          ? raw
+          : "";
+
+      const provided = request.headers[SIGNATURE_HEADER];
+      const timestamp = request.headers[TIMESTAMP_HEADER];
+
+      if (
+        typeof provided !== "string" ||
+        typeof timestamp !== "string" ||
+        !SIGNATURE_SHAPE.test(provided) ||
+        !isValidSignature(rawBody, timestamp, provided, secret)
+      ) {
+        request.log.warn({ reason: "bad_signature" }, "auth-email.unauthorized");
+        return reply.status(401).send({ error: "unauthorized" });
+      }
+
+      // Checked AFTER the signature so an unauthenticated caller learns
+      // nothing from the skew answer, and the timestamp it bounds is one the
+      // signature already authenticated.
+      const tsSeconds = Number(timestamp);
+      const skew = Math.abs(Math.floor(Date.now() / 1000) - tsSeconds);
+      if (!Number.isFinite(tsSeconds) || skew > MAX_SKEW_SECONDS) {
+        request.log.warn({ reason: "stale_timestamp" }, "auth-email.unauthorized");
+        return reply.status(401).send({ error: "unauthorized" });
+      }
+
+      const body = parseBody(rawBody);
+      if (body === null) {
+        request.log.warn(
+          { reason: "validation_failed" },
+          "auth-email.validation_failed",
+        );
+        return reply.status(400).send({ error: "validation_failed" });
+      }
+
+      if (siteVolumeAlert()) {
+        request.log.warn(
+          { reason: "site_volume_high" },
+          "auth-email.site-volume-high",
+        );
+      }
+
+      // Over budget → skip the send, log one line, and answer exactly what a
+      // sent message answers. Suppression is NEVER observable (§ D8c).
+      if (!consumeRecipientBudget(body.to, body.kind)) {
+        request.log.warn(
+          { userId: body.userId, kind: body.kind, reason: "budget_recipient" },
+          "auth-email.suppressed",
+        );
+        return reply.status(202).send({ ok: true });
+      }
+
+      // `kind` selects from FIXED templates. A caller supplies no subject and
+      // no copy — only a recipient and, for the two link kinds, a URL.
+      const linkInput = {
+        to: body.to,
+        url: body.url ?? "",
+        fromAddress,
+        ...(body.expiresInMinutes !== undefined
+          ? { expiresInMinutes: body.expiresInMinutes }
+          : {}),
+      };
+      const result =
+        body.kind === "password-changed"
+          ? await sendPasswordChangedEmail({ to: body.to, fromAddress })
+          : body.kind === "email-verification"
+            ? await sendEmailVerificationEmail(linkInput)
+            : await sendPasswordResetEmail(linkInput);
+
+      if (!result.ok) {
+        // `error.kind` only — `error.message` can quote an address (§ D12).
+        request.log.warn(
+          {
+            userId: body.userId,
+            kind: body.kind,
+            reason: "send_failed",
+            errorKind: result.error.kind,
+          },
+          "auth-email.send_failed",
+        );
+      } else {
+        request.log.info(
+          { userId: body.userId, kind: body.kind, reason: "sent" },
+          "auth-email.sent",
+        );
+      }
+
+      // 202 on every accepted outcome, a failed send included: the visitor's
+      // answer must not distinguish "this address exists" from "it does not",
+      // and a send failure is the operator's signal (the log line above), not
+      // the caller's.
+      return reply.status(202).send({ ok: true });
+    },
+  );
+};

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

@@ -20,6 +20,29 @@ const userDataSchema = z.object({
   value: z.unknown(),
 });
 
+/**
+ * Key namespaces owned by the server. A caller may never read or write these
+ * through /v1/user/data/:key — the rows are written by trusted server paths
+ * (e.g. the Stripe webhook's dunning record, #6034 § D12) and are the
+ * SUBJECT of decisions about the caller, not the caller's own storage.
+ * Without this guard the subject of an access decision is also its author:
+ * a subscriber whose renewal has failed could read their own dunning record,
+ * PUT it back as a self-granted "active" state, and poison the record's
+ * ordering watermark so every future genuine Stripe event for that
+ * subscription is rejected as stale forever.
+ */
+const RESERVED_USER_DATA_KEY_PREFIXES = ['commerce.', 'system.'] as const;
+
+/** #6034 § D12 — a serialized `value` above this bound is refused on PUT. */
+const USER_DATA_MAX_VALUE_BYTES = 64 * 1024;
+
+/** Case-insensitive prefix match on the raw key (after Fastify's own param
+ * decoding) — `Commerce.` and `COMMERCE.` are refused too. */
+function isReservedUserDataKey(key: string): boolean {
+  const lower = key.toLowerCase();
+  return RESERVED_USER_DATA_KEY_PREFIXES.some((prefix) => lower.startsWith(prefix));
+}
+
 export const userRoutes: FastifyPluginAsync = async (fastify) => {
   /**
    * GET /v1/user/profile
@@ -136,6 +159,13 @@ export const userRoutes: FastifyPluginAsync = async (fastify) => {
 
       const { key } = request.params;
 
+      if (isReservedUserDataKey(key)) {
+        return reply.status(403).send({
+          success: false,
+          error: 'reserved-key',
+        });
+      }
+
       const userData = await prisma.userData.findUnique({
         where: {
           userId_key: { userId, key },
@@ -177,9 +207,33 @@ export const userRoutes: FastifyPluginAsync = async (fastify) => {
       }
 
       const { key } = request.params;
+
+      if (isReservedUserDataKey(key)) {
+        return reply.status(403).send({
+          success: false,
+          error: 'reserved-key',
+        });
+      }
+
       const { value } = userDataSchema.parse({ key, value: request.body });
 
       const jsonValue = value as Prisma.InputJsonValue;
+
+      // `JSON.stringify` returns `undefined` (not the string "undefined")
+      // for an `undefined` input — never pass that to `Buffer.byteLength`,
+      // which throws on a non-string. An undefined value serializes to
+      // nothing on the wire, so it never exceeds the bound.
+      const serializedValue = JSON.stringify(jsonValue);
+      if (
+        serializedValue !== undefined &&
+        Buffer.byteLength(serializedValue) > USER_DATA_MAX_VALUE_BYTES
+      ) {
+        return reply.status(400).send({
+          success: false,
+          error: 'value-too-large',
+        });
+      }
+
       const userData = await prisma.userData.upsert({
         where: {
           userId_key: { userId, key },
@@ -225,6 +279,13 @@ export const userRoutes: FastifyPluginAsync = async (fastify) => {
 
       const { key } = request.params;
 
+      if (isReservedUserDataKey(key)) {
+        return reply.status(403).send({
+          success: false,
+          error: 'reserved-key',
+        });
+      }
+
       await prisma.userData.deleteMany({
         where: { userId, key },
       });