create-ailk 0.24.0 → 0.26.0

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

@@ -1,301 +0,0 @@
-/**
- * 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,
-  sendMagicLink,
-  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",
-  "magic-link",
-]);
-
-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 three 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" ||
-    kind === "magic-link";
-  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 } : {}),
-  };
-}
-
-/**
- * One fixed template per kind. Exhaustive: a kind added to `AuthEmailKind`
- * without a branch here fails the type check.
- */
-function sendFor(
-  kind: AuthEmailKind,
-  to: string,
-  linkInput: { to: string; url: string; fromAddress: string; expiresInMinutes?: number },
-  fromAddress: string,
-) {
-  switch (kind) {
-    case "password-changed":
-      return sendPasswordChangedEmail({ to, fromAddress });
-    case "email-verification":
-      return sendEmailVerificationEmail(linkInput);
-    case "password-reset":
-      return sendPasswordResetEmail(linkInput);
-    case "magic-link":
-      // The template's copy fixes its own lifetime ("expires in 5 minutes")
-      // and its input has no expiry field, so none is forwarded (#7435 § D4).
-      return sendMagicLink({ to, url: linkInput.url, fromAddress });
-    default: {
-      const unreachable: never = kind;
-      throw new Error(`unhandled auth email kind: ${String(unreachable)}`);
-    }
-  }
-}
-
-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 three link kinds, a URL.
-      const linkInput = {
-        to: body.to,
-        url: body.url ?? "",
-        fromAddress,
-        ...(body.expiresInMinutes !== undefined
-          ? { expiresInMinutes: body.expiresInMinutes }
-          : {}),
-      };
-      const result = await sendFor(body.kind, body.to, linkInput, fromAddress);
-
-      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

@@ -1,305 +0,0 @@
-/**
- * User Data Routes
- * 
- * Handles user profile and preferences (stored locally).
- */
-import type { Prisma } from '@working-theory/database';
-import { logger } from '@working-theory/observability';
-import type { FastifyPluginAsync } from 'fastify';
-import { z } from 'zod';
-
-import { prisma } from '../../lib/prisma.js';
-
-const updateProfileSchema = z.object({
-  name: z.string().optional(),
-  image: z.string().url().optional(),
-});
-
-const userDataSchema = z.object({
-  key: z.string().min(1),
-  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
-   * Get current user's profile
-   */
-  fastify.get('/v1/user/profile', async (request, reply) => {
-    try {
-      const userId = (request as unknown as { userId?: string }).userId;
-      if (!userId) {
-        return reply.status(401).send({
-          success: false,
-          error: 'Authentication required',
-        });
-      }
-
-      const user = await prisma.user.findUnique({
-        where: { id: userId },
-        select: {
-          id: true,
-          email: true,
-          name: true,
-          image: true,
-          role: true,
-          createdAt: true,
-        },
-      });
-
-      if (!user) {
-        return reply.status(404).send({
-          success: false,
-          error: 'User not found',
-        });
-      }
-
-      return reply.send({
-        success: true,
-        data: user,
-      });
-    } catch (error) {
-      logger.error({ err: error }, '[User] Error fetching profile');
-      return reply.status(500).send({
-        success: false,
-        error: 'Internal server error',
-      });
-    }
-  });
-
-  /**
-   * PATCH /v1/user/profile
-   * Update current user's profile
-   */
-  fastify.patch('/v1/user/profile', async (request, reply) => {
-    try {
-      const userId = (request as unknown as { userId?: string }).userId;
-      if (!userId) {
-        return reply.status(401).send({
-          success: false,
-          error: 'Authentication required',
-        });
-      }
-
-      const data = updateProfileSchema.parse(request.body);
-
-      const user = await prisma.user.update({
-        where: { id: userId },
-        data: {
-          ...(data.name !== undefined && { name: data.name }),
-          ...(data.image !== undefined && { image: data.image }),
-        },
-        select: {
-          id: true,
-          email: true,
-          name: true,
-          image: true,
-          role: true,
-          updatedAt: true,
-        },
-      });
-
-      return reply.send({
-        success: true,
-        data: user,
-      });
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        return reply.status(400).send({
-          success: false,
-          error: 'Validation failed',
-          details: error.issues,
-        });
-      }
-
-      logger.error({ err: error }, '[User] Error updating profile');
-      return reply.status(500).send({
-        success: false,
-        error: 'Internal server error',
-      });
-    }
-  });
-
-  /**
-   * GET /v1/user/data/:key
-   * Get user data by key
-   */
-  fastify.get<{ Params: { key: string } }>('/v1/user/data/:key', async (request, reply) => {
-    try {
-      const userId = (request as unknown as { userId?: string }).userId;
-      if (!userId) {
-        return reply.status(401).send({
-          success: false,
-          error: 'Authentication required',
-        });
-      }
-
-      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 },
-        },
-      });
-
-      if (!userData) {
-        return reply.status(404).send({
-          success: false,
-          error: 'Data not found',
-        });
-      }
-
-      return reply.send({
-        success: true,
-        data: userData.value,
-      });
-    } catch (error) {
-      logger.error({ err: error }, '[User] Error fetching data');
-      return reply.status(500).send({
-        success: false,
-        error: 'Internal server error',
-      });
-    }
-  });
-
-  /**
-   * PUT /v1/user/data/:key
-   * Set user data by key
-   */
-  fastify.put<{ Params: { key: string } }>('/v1/user/data/:key', async (request, reply) => {
-    try {
-      const userId = (request as unknown as { userId?: string }).userId;
-      if (!userId) {
-        return reply.status(401).send({
-          success: false,
-          error: 'Authentication required',
-        });
-      }
-
-      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 },
-        },
-        update: { value: jsonValue },
-        create: { userId, key, value: jsonValue },
-      });
-
-      return reply.send({
-        success: true,
-        data: userData.value,
-      });
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        return reply.status(400).send({
-          success: false,
-          error: 'Validation failed',
-          details: error.issues,
-        });
-      }
-
-      logger.error({ err: error }, '[User] Error saving data');
-      return reply.status(500).send({
-        success: false,
-        error: 'Internal server error',
-      });
-    }
-  });
-
-  /**
-   * DELETE /v1/user/data/:key
-   * Delete user data by key
-   */
-  fastify.delete<{ Params: { key: string } }>('/v1/user/data/:key', async (request, reply) => {
-    try {
-      const userId = (request as unknown as { userId?: string }).userId;
-      if (!userId) {
-        return reply.status(401).send({
-          success: false,
-          error: 'Authentication required',
-        });
-      }
-
-      const { key } = request.params;
-
-      if (isReservedUserDataKey(key)) {
-        return reply.status(403).send({
-          success: false,
-          error: 'reserved-key',
-        });
-      }
-
-      await prisma.userData.deleteMany({
-        where: { userId, key },
-      });
-
-      return reply.send({
-        success: true,
-        message: 'Data deleted',
-      });
-    } catch (error) {
-      logger.error({ err: error }, '[User] Error deleting data');
-      return reply.status(500).send({
-        success: false,
-        error: 'Internal server error',
-      });
-    }
-  });
-};