create-ailk 0.5.0 → 0.6.0

package/templates/apps/api/src/lib/auth-email-budget.ts

@@ -0,0 +1,160 @@
+/**
+ * Per-recipient hourly send budget for the auth transactional-email relay
+ * (#5962 § D8c).
+ *
+ * WHY IT IS PER RECIPIENT AND NOT PER SITE. The first draft of #5962's spec
+ * carried a second, site-wide cap. It was removed, and its removal is the
+ * point of this module's shape: Better Auth writes the `Verification` row
+ * BEFORE it invokes `sendResetPassword`, so every attacker request both feeds
+ * a site-wide counter and refreshes its window — roughly one request per 72
+ * seconds would hold a site permanently at its cap and silence reset mail for
+ * EVERY user, indefinitely. A site-wide cap an attacker can hold open is a
+ * denial of the control it implements. `siteVolumeAlert()` below replaces it
+ * with an operator SIGNAL that never refuses a send.
+ *
+ * The per-recipient budget IS a lockout weapon, narrowly: an attacker who
+ * requests three resets for one address in an hour denies that person a reset
+ * for the rest of it. Accepted for the reason
+ * `services/project-listing-resume-email.ts` gives and this module can
+ * honestly claim — the window is an hour rather than forever, it clears
+ * itself, and it is bounded to ONE victim rather than to the whole site.
+ *
+ * SINGLE-REPLICA CAVEAT, stated rather than hidden: the store is an in-process
+ * Map, so on an N-instance deployment the effective ceiling is N × the cap.
+ * Identical to the caveat `middleware/rate-limit.ts` documents for itself. The
+ * durable alternative needs a table `database/auth/schema.prisma` does not
+ * have, and #5962 adds no migration (Q16).
+ *
+ * PII: the key is `sha256(lowercased recipient + ":" + kind)`. This module is
+ * memory an operator can dump, and a plaintext address in it would be a
+ * recipient list.
+ */
+
+import { createHash } from "node:crypto";
+
+import { getClock } from "@working-theory/common";
+
+/** The three fixed message kinds the relay will send. */
+export type AuthEmailKind =
+  | "password-reset"
+  | "email-verification"
+  | "password-changed";
+
+/** Sends allowed per (recipient, kind) per hour. */
+export const RECIPIENT_HOURLY_MAX = 3;
+
+/**
+ * Sends per hour, site-wide, past which ONE operator warning is logged. Never
+ * a refusal — see the module comment.
+ */
+export const SITE_HOURLY_ALERT_THRESHOLD = 50;
+
+const WINDOW_MS = 60 * 60 * 1000;
+
+/**
+ * Cap on distinct entries, independent of the time-based window. The key is
+ * derived from a caller-supplied address, so a caller minting a fresh address
+ * per request would otherwise grow the map without bound for the lifetime of
+ * one isolate. Same reasoning, same shape, as `rate-limit.ts`'s MAX_BUCKETS.
+ */
+export const MAX_BUCKETS = 10_000;
+
+type Bucket = { count: number; windowStartMs: number };
+
+const buckets = new Map<string, Bucket>();
+
+let siteWindowStartMs = 0;
+let siteCount = 0;
+let siteAlertedThisWindow = false;
+
+export interface BudgetOptions {
+  /** Explicit clock reading. Defaults to `getClock().now()`. Tests inject it. */
+  nowMs?: number;
+  /** Entry cap. Exposed for tests only — no production caller overrides it. */
+  maxBuckets?: number;
+}
+
+function bucketKey(recipient: string, kind: AuthEmailKind): string {
+  const normalized = recipient.trim().toLowerCase();
+  return createHash("sha256").update(`${normalized}:${kind}`).digest("hex");
+}
+
+/**
+ * Counts one send against `(recipient, kind)` and reports whether it may
+ * proceed.
+ *
+ * `false` means SUPPRESS THE SEND — it never means "tell the caller". The
+ * relay answers 202 either way, because an observable suppression is the same
+ * account-enumeration oracle the rest of this flow is built to close.
+ */
+export function consumeRecipientBudget(
+  recipient: string,
+  kind: AuthEmailKind,
+  options: BudgetOptions = {},
+): boolean {
+  const now = options.nowMs ?? getClock().now();
+  const maxBuckets = options.maxBuckets ?? MAX_BUCKETS;
+  const key = bucketKey(recipient, kind);
+
+  let bucket = buckets.get(key);
+
+  if (!bucket || now - bucket.windowStartMs >= WINDOW_MS) {
+    // A genuinely new identity at capacity evicts the single oldest-inserted
+    // entry (`Map` iteration order is insertion order) before inserting
+    // itself — O(1) amortized, and no behaviour change under the cap.
+    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);
+  }
+
+  if (bucket.count >= RECIPIENT_HOURLY_MAX) return false;
+
+  bucket.count += 1;
+  return true;
+}
+
+/**
+ * Counts one send site-wide and reports whether THIS call is the one that
+ * should emit the hourly operator warning.
+ *
+ * It is a signal, not a gate: nothing in this module consults its return value
+ * to deny a send, and nothing may be added that does.
+ */
+export function siteVolumeAlert(options: BudgetOptions = {}): boolean {
+  const now = options.nowMs ?? getClock().now();
+
+  if (now - siteWindowStartMs >= WINDOW_MS) {
+    siteWindowStartMs = now;
+    siteCount = 0;
+    siteAlertedThisWindow = false;
+  }
+
+  siteCount += 1;
+
+  if (siteCount >= SITE_HOURLY_ALERT_THRESHOLD && !siteAlertedThisWindow) {
+    siteAlertedThisWindow = true;
+    return true;
+  }
+  return false;
+}
+
+/** Test-only reset. Not intended for production use. */
+export function __resetAuthEmailBudget(): void {
+  buckets.clear();
+  siteWindowStartMs = 0;
+  siteCount = 0;
+  siteAlertedThisWindow = false;
+}
+
+/** Test-only accessor for the distinct-bucket count. */
+export function __authEmailBucketCount(): number {
+  return buckets.size;
+}
+
+/** Test-only accessor proving the stored keys carry no plaintext address. */
+export function __authEmailBudgetKeys(): string[] {
+  return [...buckets.keys()];
+}

package/templates/apps/api/src/lib/content-adapter.ts

@@ -1,12 +1,13 @@
 /**
  * Shared content adapter singleton for apps/api.
  *
- * The MDX adapter is the v1 default. Set `CONTENT_ADAPTER=projection` to opt
- * into the build-time projection adapter backed by a compiled manifest.
+ * Adapter selection is NOT decided here — it is `resolveContentAdapter()`'s job
+ * (#5804, roadmap D3: one resolver, one env var). This module supplies the
+ * app's own inputs (content root, default locale, manifest path, the projection
+ * factory) and memoises the result for the process.
  *
- * Adapter selection:
- *   - (unset or any value other than "projection") → MDX adapter
- *   - "projection" → projection adapter (requires compiled manifest)
+ * `CONTENT_ADAPTER` selects: `mdx` (default) | `projection` | `database`.
+ * `CONTENT_BACKEND` is read for one more release by the resolver's shim.
  *
  * Content-root resolution order:
  *   1. `CONTENT_ROOT` env var (explicit override — recommended for production)
@@ -15,13 +16,27 @@
  *
  * Manifest-path resolution (projection only):
  *   1. `MANIFEST_PATH` env var (explicit override)
- *   2. `<content-root>/.compiled/manifest.json` (default)
+ *   2. `<content-root>/.compiled/manifest.json` (the resolver's default)
+ *
+ * `workspaceId` is supplied by the CALLER, never read here (#5852). A public
+ * read resolves its workspace through `services/public-site-resolver.ts` and
+ * passes the result in; a caller that passes none still raises the resolver's
+ * "workspaceId required" error under `CONTENT_ADAPTER=database`, rather than
+ * silently reading some other workspace's pages. There is no local ADAPTER memo
+ * slot: `resolveContentAdapter()` already memoises on the full key
+ * (kind + workspaceId + root + locale + manifest), and a second cache keyed on
+ * less than that is how one workspace's adapter reaches the next request. This
+ * module's own INPUTS — the content root and the default locale, both
+ * workspace-independent and both fixed for the process — stay memoised, so a
+ * public read costs no more filesystem work than it did before the seam widened.
  */
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 
 import {
-  createMdxAdapter,
+  resetResolvedContentAdapter,
+  resolveContentAdapter,
+  type ArtifactPrismaClient,
   type ContentAdapter,
   type MdxContentAdapter,
 } from "@working-theory/content-adapters";
@@ -30,7 +45,17 @@ import { loadManifestFromDisk } from "@working-theory/content-projection/node";
 
 import { readDefaultLocale } from "./locales.js";
 
-let cachedAdapter: ContentAdapter | undefined;
+/** Process-fixed inputs, resolved once: neither depends on the workspace. */
+let memoisedContentRoot: string | undefined;
+let memoisedDefaultLocale: string | undefined;
+
+/** Caller-supplied inputs; everything else is this module's own (#5852 D5). */
+export interface GetContentAdapterOptions {
+  /** The resolved tenant. Required by `CONTENT_ADAPTER=database`, ignored otherwise. */
+  workspaceId?: string | undefined;
+  /** apps/api's client. The database adapter never constructs one. */
+  prisma?: ArtifactPrismaClient | undefined;
+}
 
 /**
  * Resolve the content root. Honours `CONTENT_ROOT` env first, then probes the
@@ -50,37 +75,38 @@ export function getContentRoot(): string {
 }
 
 /**
- * Returns the process-wide content adapter, lazily constructed on first use.
- * Safe to call repeatedly. Adapter type is determined by `CONTENT_ADAPTER` env.
+ * Returns the content adapter for the given tenant, memoised by the resolver.
+ * Safe to call repeatedly. Adapter type is determined by `CONTENT_ADAPTER` env,
+ * read by the resolver.
  */
-export function getContentAdapter(): ContentAdapter {
-  if (!cachedAdapter) {
-    cachedAdapter = buildAdapter();
-  }
-  return cachedAdapter;
-}
-
-function buildAdapter(): ContentAdapter {
-  const contentRoot = getContentRoot();
-
-  if (process.env.CONTENT_ADAPTER === "projection") {
-    const manifestPath =
-      process.env.MANIFEST_PATH ??
-      resolve(contentRoot, ".compiled", "manifest.json");
-
-    const manifest = loadManifestFromDisk(manifestPath);
-    return createProjectionAdapter({ manifest });
-  }
+export function getContentAdapter(
+  options: GetContentAdapterOptions = {},
+): ContentAdapter {
+  memoisedContentRoot ??= getContentRoot();
+  memoisedDefaultLocale ??= readDefaultLocale();
 
-  return createMdxAdapter({ contentRoot, defaultLocale: readDefaultLocale() });
+  return resolveContentAdapter({
+    workspaceId: options.workspaceId,
+    prisma: options.prisma,
+    contentRoot: memoisedContentRoot,
+    defaultLocale: memoisedDefaultLocale,
+    manifestPath: process.env.MANIFEST_PATH,
+    // The projection adapter lives in a package that depends on
+    // content-adapters, so the resolver cannot import it without closing a
+    // cycle. apps/api depends on both, and injects it.
+    createProjectionAdapter: (manifestPath) =>
+      createProjectionAdapter({ manifest: loadManifestFromDisk(manifestPath) }),
+  });
 }
 
 /**
- * Test/utility helper — drop the cached adapter so the next call rebuilds
+ * Test/utility helper — drop the memoised adapter so the next call rebuilds
  * with current env. Not used in production.
  */
 export function resetContentAdapter(): void {
-  cachedAdapter = undefined;
+  memoisedContentRoot = undefined;
+  memoisedDefaultLocale = undefined;
+  resetResolvedContentAdapter();
 }
 
 export type { MdxContentAdapter };

package/templates/apps/api/src/lib/deliverable-asset-store.ts

@@ -0,0 +1,76 @@
+// oss: false
+/**
+ * The magnet-deliverable Asset store's data-access boundary (#6310 D16).
+ *
+ * `deliverable-fulfillment.ts` resolves `deliverables.assets[].assetKey`
+ * against the workspace-scoped `Asset` model before falling back to the
+ * legacy `DeliverableAsset` store (D1/D2), and the download route
+ * (`routes/deliverables/index.ts`) serves an `asset_`-class grant's bytes
+ * from the same model (D6). Neither caller may run a raw `prisma.asset`
+ * query directly — that access is banned by the tenant-scope
+ * `forbidden_pattern` in architecture.yaml — and neither is `lib/asset-store.ts`
+ * a fit: it is `workspace`/`multi-tenant`-owned (`MODULE_SLICES`), so a
+ * `signal-collectors` file (the route) cannot import it, and
+ * `deliverable-fulfillment.ts` ships in every scaffold regardless of module
+ * selection. This file is its own named boundary instead — modelled
+ * line-for-line on `lib/asset-store.ts` — exporting exactly two scoped
+ * reads and nothing else:
+ *
+ *   - `findDeliverableAssetIdByKey(workspaceId, key)` — the mint-time
+ *     resolution (D2): does an `Asset` exist at this workspace's `key`?
+ *   - `readDeliverableAsset(assetId, workspaceId)` — the serve-time read
+ *     (D6): the bytes, scoped by the `workspaceId` the grant carries
+ *     (D15), so a rewritten or mis-set grant can never serve another
+ *     workspace's bytes.
+ *
+ * No write, no `findMany`, no list, no unscoped read — both functions take
+ * a `workspaceId` the caller resolved server-side, never a client-supplied
+ * value, so neither can enumerate or cross a tenant boundary (NFR3).
+ */
+import { prisma } from "./prisma.js";
+
+/** What the mint-time resolution needs, and nothing more. */
+export async function findDeliverableAssetIdByKey(
+  workspaceId: string,
+  key: string,
+): Promise<string | null> {
+  const row = await prisma.asset.findFirst({
+    where: { workspaceId, key },
+    select: { id: true },
+  });
+  return row?.id ?? null;
+}
+
+/** What the serve path needs, and deliberately nothing more (no key, no workspace). */
+export type DeliverableAssetBytes = {
+  filename: string;
+  contentType: string;
+  bytes: Buffer;
+};
+
+/**
+ * Resolve one asset's bytes by id, scoped by `workspaceId` (D15). A foreign-
+ * workspace id — or any other miss — returns `null`; the caller turns that
+ * into the same uniform 404 an unknown grant gets (D6/FR5).
+ */
+export async function readDeliverableAsset(
+  assetId: string,
+  workspaceId: string | null,
+): Promise<DeliverableAssetBytes | null> {
+  if (workspaceId === null) return null;
+
+  const row = await prisma.asset.findFirst({
+    where: { id: assetId, workspaceId },
+    select: { filename: true, contentType: true, bytes: true },
+  });
+  if (!row) return null;
+
+  return {
+    ...row,
+    // Prisma maps a `Bytes` column to `Uint8Array`, and Fastify treats only
+    // a `Buffer` as a raw payload — this wraps rather than copies
+    // (`Buffer.from(buffer, byteOffset, length)` is a view), mirroring
+    // `asset-store.ts`'s own identical wrap.
+    bytes: Buffer.from(row.bytes.buffer, row.bytes.byteOffset, row.bytes.byteLength),
+  };
+}

package/templates/apps/api/src/lib/error-serializer.ts

@@ -20,6 +20,26 @@ import type { FastifyError, FastifyInstance } from "fastify";
 
 const GENERIC_INTERNAL_BODY = { error: "internal_error" } as const;
 
+/**
+ * The request target with its QUERY STRING removed (#5970 security review,
+ * finding 1).
+ *
+ * A route may carry its credential in the query — `GET
+ * /v1/requests/:id/confirm?token=…` does, because a link in an email has
+ * nowhere else to put one — and this handler logs `path` on EVERY error on
+ * EVERY route. Logging the raw target would write that credential into the
+ * API's own log the moment anything went wrong, which is precisely when logs
+ * get read, copied into tickets, and shipped to third parties.
+ *
+ * The path itself is kept: it is what makes the line useful, and a route
+ * parameter like `:id` is an identifier rather than a secret. The matching
+ * strip lives on the Fastify logger's own `req` serializer in `server.ts`.
+ */
+function pathWithoutQuery(url: string): string {
+  const queryAt = url.indexOf("?");
+  return queryAt === -1 ? url : url.slice(0, queryAt);
+}
+
 export function registerErrorSerializer(server: FastifyInstance): void {
   server.setErrorHandler(async (err: FastifyError, request, reply) => {
     // Validation errors (Fastify's schema validator) — keep structured detail.
@@ -29,7 +49,7 @@ export function registerErrorSerializer(server: FastifyInstance): void {
       request.log.warn(
         {
           method: request.method,
-          path: request.url,
+          path: pathWithoutQuery(request.url),
           validation: err.validation,
         },
         "request validation failed",
@@ -48,7 +68,7 @@ export function registerErrorSerializer(server: FastifyInstance): void {
       request.log.info(
         {
           method: request.method,
-          path: request.url,
+          path: pathWithoutQuery(request.url),
           statusCode: status,
           errName: err.name,
         },
@@ -63,7 +83,7 @@ export function registerErrorSerializer(server: FastifyInstance): void {
     request.log.error(
       {
         method: request.method,
-        path: request.url,
+        path: pathWithoutQuery(request.url),
         errName: err.name,
         errMessage: err.message,
         errStack: err.stack,

package/templates/apps/api/src/lib/outbound-http.ts

@@ -20,7 +20,11 @@
  * finding waiting to happen.
  *
  * Test-mode escape hatch — `allowPrivate: true` suppresses the SSRF gate.
- * Use only for explicit, internal-by-design traffic (typically tests).
+ * Use only for explicit, internal-by-design traffic (typically tests). One
+ * production case is sanctioned (#5851): a destination read from an
+ * operator-configured deployment environment variable that is never
+ * user-controlled, such as `CONTENT_REVALIDATE_URL`, whose legitimate value is
+ * loopback in local development and single-host deployments.
  */
 
 const DEFAULT_TIMEOUT_MS = 10_000;
@@ -29,7 +33,8 @@ export type OutboundFetchOptions = RequestInit & {
   /** Override the default 10s timeout. */
   timeoutMs?: number;
   /**
-   * Suppress the SSRF allow-list — test-mode escape hatch only.
+   * Suppress the SSRF allow-list — tests, plus the sanctioned production case
+   * in the module doc (an operator-configured deployment-env destination).
    * NEVER pass true for user-controlled URLs.
    */
   allowPrivate?: boolean;