@data-club/ai-hub-server 0.0.1

package/src/db/seed.ts

@@ -0,0 +1,236 @@
+/**
+ * First-boot seed.
+ *
+ * Two responsibilities, both idempotent:
+ *
+ * 1. **Super-admin seed (§8.5).** If the `user` table is empty, insert
+ *    `username = "DataClub"`, `password_hash = argon2id("admin")`,
+ *    `role = "super_admin"`, `is_initial_password = true`. Hardcoded
+ *    credentials by design — the operator changes them on first login (the
+ *    flag enforces it).
+ *
+ * 2. **Admin-setting bootstrap (§6.7 / §6.10 / §12.1).** If the singleton
+ *    `admin_setting` row doesn't exist, create it with theme defaults
+ *    (`theme_switcher_enabled = true`, `theme_default = "light"` per §7.6),
+ *    seed `service_token_signing_key` from env `SERVICE_TOKEN_SIGNING_KEY`
+ *    if set else random, seed `metrics_scrape_token` from env
+ *    `METRICS_SCRAPE_TOKEN` if set else random, encrypt and store the env
+ *    `LETTA_API_KEY`, and write `letta_base_url` / `letta_ade_url`. After
+ *    first boot the env vars for the signing key + metrics token are no
+ *    longer consulted — DB columns are authoritative.
+ *
+ * Both run inside a single SQLite transaction so a partial failure can't
+ * leave a half-seeded DB. Idempotency is enforced by the row-existence
+ * checks at the top of each branch.
+ *
+ * @see SPECIFICATIONS.md §8.5 — initial super admin seed
+ * @see SPECIFICATIONS.md §6.7 — single signing key
+ * @see SPECIFICATIONS.md §6.10 — observability / metrics token
+ * @see SPECIFICATIONS.md §12.1 — env-var semantics
+ */
+
+import { randomBytes, randomUUID } from "node:crypto";
+
+import { hashPassword } from "../auth/argon2.js";
+import type { Logger } from "../observability/logger.js";
+
+import type { DbHandle } from "./connection.js";
+import { adminSetting, user } from "./schema.js";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Hardcoded super-admin credentials (§8.5)                                  */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/** Seeded super-admin username — see §8.5. */
+export const SUPER_ADMIN_SEED_USERNAME = "DataClub";
+
+/** Seeded super-admin password — see §8.5. Operator changes on first login. */
+export const SUPER_ADMIN_SEED_PASSWORD = "admin";
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Bootstrap inputs                                                          */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Inputs the seed needs from the env (or a test harness). Kept as an explicit
+ * record so callers don't pass `process.env` directly through the seed —
+ * test harnesses can synthesize the exact shape they want without monkeying
+ * with the real environment.
+ */
+export interface SeedInputs {
+  /** Required — the AES-256 encryption key (parsed). */
+  encryptionKey: Buffer;
+  /** Optional bootstrap-only signing key. Random when undefined (§6.7). */
+  signingKeyFromEnv?: Buffer | undefined;
+  /** Optional bootstrap-only metrics token. Random when undefined (§6.10). */
+  metricsScrapeTokenFromEnv?: string | undefined;
+  /**
+   * @deprecated Kept on the interface so existing callers compile, but
+   * **no longer seeded into the DB**. The Letta API key is read at runtime
+   * from `admin_setting.letta_api_key_encrypted` with a fallback to
+   * `env.LETTA_API_KEY` when the column is empty/whitespace
+   * (`letta/client.ts:getSdk`). Letting env stay authoritative until a
+   * super-admin overrides it via the admin panel is the precedence
+   * documented in env-vars.md. v2 will drop this field.
+   */
+  lettaApiKey?: string | undefined;
+  /** Required — Letta base URL written into the row. */
+  lettaBaseUrl?: string | undefined;
+  /** Optional super-admin override for the ADE link target. */
+  lettaAdeUrl?: string | undefined;
+}
+
+/**
+ * What the seed actually wrote, so the caller can log first-boot specifics
+ * (e.g. "metrics scrape token: <random>" exactly once on stdout).
+ */
+export interface SeedReport {
+  /** `true` if the super-admin row was created on this boot. */
+  seededSuperAdmin: boolean;
+  /** `true` if the `admin_setting` row was created on this boot. */
+  seededAdminSetting: boolean;
+  /**
+   * If `seededAdminSetting && metricsScrapeTokenFromEnv was undefined`, this
+   * is the random token that was generated. The dev runner logs it once on
+   * stdout for the operator to copy. `null` otherwise.
+   */
+  randomMetricsScrapeToken: string | null;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Seed entrypoint                                                           */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Runs both seed branches in a single transaction. Idempotent — running on
+ * an already-seeded DB is a no-op (returns a report with both booleans
+ * `false` and `randomMetricsScrapeToken` null).
+ *
+ * @param handle - the DB handle.
+ * @param inputs - bootstrap-only env values.
+ * @param logger - pino logger for the once-on-first-boot notices (§6.10).
+ * @returns what was actually seeded.
+ */
+export async function runFirstBootSeed(
+  handle: DbHandle,
+  inputs: SeedInputs,
+  logger: Logger,
+): Promise<SeedReport> {
+  const report: SeedReport = {
+    seededSuperAdmin: false,
+    seededAdminSetting: false,
+    randomMetricsScrapeToken: null,
+  };
+
+  // Compute the password hash + encryption outside the transaction (Argon2
+  // is async; better-sqlite3 transactions are sync).
+  const userCount = handle.raw
+    .prepare("SELECT COUNT(*) as c FROM user")
+    .get() as { c: number };
+  const adminCount = handle.raw
+    .prepare("SELECT COUNT(*) as c FROM admin_setting")
+    .get() as { c: number };
+
+  let superAdminInsert: typeof user.$inferInsert | null = null;
+  if (userCount.c === 0) {
+    const passwordHash = await hashPassword(SUPER_ADMIN_SEED_PASSWORD);
+    superAdminInsert = {
+      id: randomUUID(),
+      username: SUPER_ADMIN_SEED_USERNAME,
+      passwordHash,
+      identitySource: "local",
+      isInitialPassword: true,
+      role: "super_admin",
+    };
+  }
+
+  let adminInsert: typeof adminSetting.$inferInsert | null = null;
+  if (adminCount.c === 0) {
+    const signingKey =
+      inputs.signingKeyFromEnv ?? randomBytes(64);
+    let metricsToken: string;
+    if (inputs.metricsScrapeTokenFromEnv) {
+      metricsToken = inputs.metricsScrapeTokenFromEnv;
+    } else {
+      metricsToken = randomBytes(32).toString("hex");
+      report.randomMetricsScrapeToken = metricsToken;
+    }
+    // **Deliberately left NULL.** `LETTA_API_KEY` is consulted at runtime
+    // as a fallback when this column is empty or whitespace (see
+    // `letta/client.ts:getSdk`). Seeding it into the DB on first boot would
+    // freeze the env value into the admin_setting row, after which
+    // changing `.env` + restart would silently have no effect — that was
+    // the rotation footgun before 2026-05. Leaving the column NULL by
+    // default means env stays authoritative until a super-admin explicitly
+    // PATCHes a value via /admin/settings; clearing the value there falls
+    // back to env again. See docs/operations/env-vars.md for the full
+    // precedence model.
+    const lettaApiKeyEncrypted: Buffer | null = null;
+    adminInsert = {
+      id: 1,
+      lettaApiKeyEncrypted,
+      lettaBaseUrl: inputs.lettaBaseUrl ?? null,
+      lettaAdeUrl: inputs.lettaAdeUrl ?? deriveLettaAdeUrl(inputs.lettaBaseUrl),
+      featureToggles: {},
+      themeSwitcherEnabled: true,
+      themeDefault: "light",
+      serviceTokenSigningKey: signingKey,
+      metricsScrapeToken: metricsToken,
+    };
+  }
+
+  if (!superAdminInsert && !adminInsert) {
+    return report;
+  }
+
+  const tx = handle.raw.transaction(() => {
+    if (superAdminInsert) {
+      handle.db.insert(user).values(superAdminInsert).run();
+      report.seededSuperAdmin = true;
+    }
+    if (adminInsert) {
+      handle.db.insert(adminSetting).values(adminInsert).run();
+      report.seededAdminSetting = true;
+    }
+  });
+  tx();
+
+  if (report.seededSuperAdmin) {
+    logger.info(
+      {
+        username: SUPER_ADMIN_SEED_USERNAME,
+        is_initial_password: true,
+      },
+      "Seeded initial super-admin user (change the password immediately on first login).",
+    );
+  }
+  if (report.randomMetricsScrapeToken) {
+    // Per §6.10: log the random metrics token once on stdout so the operator
+    // can copy it into their Prometheus / Alloy config. We embed the value
+    // in the message string rather than as a structured field because the
+    // generic pino-redaction policy (§13.3) censors token-shaped keys — and
+    // here, this is the one place where we _do_ want the operator to see it.
+    // Subsequent reads (`GET /admin/settings`, request logs) never expose it
+    // because it stays out of the structured field list. Operators rotate via
+    // `/admin/settings/rotate-metrics-token`; only the rotation response
+    // re-reveals the new value.
+    logger.info(
+      { event: "first_boot_metrics_token_generated" },
+      `Generated random METRICS_SCRAPE_TOKEN: ${report.randomMetricsScrapeToken} — copy this into your Prometheus / Alloy scrape config.`,
+    );
+  }
+
+  return report;
+}
+
+/**
+ * Derives `letta_ade_url` from `letta_base_url` by stripping a trailing
+ * `/v1` per §12.1. Returns `null` if the base url is itself null.
+ *
+ * @param baseUrl - the configured Letta base URL.
+ * @returns the ADE URL or `null`.
+ */
+function deriveLettaAdeUrl(baseUrl: string | undefined): string | null {
+  if (!baseUrl) return null;
+  return baseUrl.replace(/\/v1\/?$/, "");
+}

package/src/handlers/fetch.ts

@@ -0,0 +1,251 @@
+/**
+ * Canonical entry point: `createFetchHandler({...})`.
+ *
+ * Every per-customer wrapper mounts this through one of the adapters. The
+ * Next.js App Router adapter (`createNextRouteHandler`) is the first-class
+ * one (§6.2); the bare `createFetchHandler` is what `node:http` /
+ * `Bun.serve` / Cloudflare Workers / etc. wrap directly with a 5-line
+ * adapter on the user's side.
+ *
+ * The handler:
+ *
+ * 1. Peels `basePath` off the URL.
+ * 2. Runs the matcher against the route table.
+ * 3. Invokes the matched handler with `(req, ctx)` and a unique
+ *    `request_id` propagated through the per-request child logger.
+ * 4. Catches any thrown error, logs it, returns a generic 500.
+ *
+ * No auth check happens here — that's the role-enforcement middleware's
+ * job, and it lives inside individual handlers (or, in Step 3+, behind a
+ * `protected()` wrapper). Step 2's `POST /auth/login` does not require auth.
+ *
+ * @see SPECIFICATIONS.md §6.2 — Web-Standard Fetch handlers
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type Database from "better-sqlite3";
+
+import type { DrizzleDB } from "../db/connection.js";
+import {
+  createDefaultLettaClient,
+  type LettaClient,
+} from "../letta/client.js";
+import { resolveFilesDir } from "../letta/sandbox.js";
+import {
+  readThrottleConfigFromEnv,
+  SubprocessThrottle,
+} from "../letta/subprocessThrottle.js";
+import type { Logger } from "../observability/logger.js";
+import { ensureRotationScheduler } from "../state/rotationScheduler.js";
+
+import { buildRouteTable } from "./routeTable.js";
+import { matchRoute } from "./router.js";
+import { internalError, methodNotAllowed, notFound } from "./responses.js";
+import type { AIHubServerContext, RouteEntry } from "./types.js";
+
+/**
+ * Dependency bundle accepted by `createFetchHandler`. The fetch entry point
+ * stays decoupled from process bootstrap (env loading, DB opening,
+ * migrations) so tests can pass a tmp DB + a captured logger directly.
+ */
+export interface CreateFetchHandlerOptions {
+  /** Drizzle client. */
+  db: DrizzleDB;
+  /** Raw better-sqlite3 handle (used for `transaction()` and PRAGMAs). */
+  sqlite: Database.Database;
+  /** Pino logger with redaction wired. */
+  logger: Logger;
+  /** Parsed `AI_HUB_ENCRYPTION_KEY`. */
+  encryptionKey: Buffer;
+  /** Route prefix. Default `/api/ai-hub`. */
+  basePath?: string;
+  /**
+   * Override the route table (tests inject a stub table to assert matcher
+   * behavior in isolation). Defaults to `buildRouteTable()`.
+   */
+  routes?: ReadonlyArray<RouteEntry>;
+  /**
+   * Project-shaped Letta client. Tests pass a mock so they never call
+   * out to a real Letta. When omitted, the default reads
+   * `admin_setting.letta_base_url` + decrypted API key on each use and
+   * memoizes one SDK instance per `(apiKey, baseURL)` pair.
+   *
+   * @see SPECIFICATIONS.md §6.4
+   */
+  lettaClient?: LettaClient;
+  /**
+   * Throttle gating Letta Code subprocess spawns. Tests inject a configured
+   * instance (e.g. with a fixed `MemReader` returning low MemAvailable to
+   * drive the 503 overload path). Defaults to a fresh `SubprocessThrottle`
+   * with config from env (`AI_HUB_SUBPROCESS_RAM_THRESHOLD_PCT`,
+   * `AI_HUB_SUBPROCESS_HARD_CAP`) reading `/proc/meminfo`.
+   *
+   * @see ../letta/subprocessThrottle.ts
+   */
+  subprocessThrottle?: SubprocessThrottle;
+  /**
+   * Env-var source for runtime fallbacks (currently: the Letta API key
+   * when the DB column is empty — see `letta/client.ts:resolveApiKey`).
+   * Defaults to `process.env`. Tests pass the synthesized record they
+   * boot with so the env-fallback behavior is exercisable.
+   */
+  envSource?: Record<string, string | undefined>;
+}
+
+/**
+ * The exposed Fetch handler — `(Request) => Promise<Response>`.
+ */
+export type FetchHandler = (req: Request) => Promise<Response>;
+
+/**
+ * Builds a Fetch handler from the given dependencies.
+ *
+ * @param opts - DB, logger, encryption key, etc.
+ * @returns the per-instance Fetch handler.
+ */
+export function createFetchHandler(
+  opts: CreateFetchHandlerOptions,
+): FetchHandler {
+  const subprocessThrottle =
+    opts.subprocessThrottle ?? new SubprocessThrottle(readThrottleConfigFromEnv());
+  const envSource =
+    opts.envSource ?? (process.env as Record<string, string | undefined>);
+  // Step-12.5 — resolve the per-session sandbox + seed base directory.
+  // Creates `seeds/` + `sandboxes/` under the resolved path if missing
+  // (idempotent), so the admin agents validator + POST /sessions don't
+  // need to mkdir on the fly.
+  const filesDir = resolveFilesDir(envSource);
+  const ctx: AIHubServerContext = {
+    db: opts.db,
+    sqlite: opts.sqlite,
+    logger: opts.logger,
+    encryptionKey: opts.encryptionKey,
+    basePath: normalizeBasePath(opts.basePath ?? "/api/ai-hub"),
+    lettaClient:
+      opts.lettaClient ??
+      createDefaultLettaClient({
+        db: opts.db,
+        encryptionKey: opts.encryptionKey,
+        subprocessThrottle,
+        envSource,
+      }),
+    subprocessThrottle,
+    envSource,
+    filesDir,
+  };
+
+  // Start the rotating-message scheduler once per process. Idempotent + a
+  // no-op under tests / when `AI_HUB_DISABLE_ROTATION_SCHEDULER=1` (see
+  // `ensureRotationScheduler`), so building multiple handlers — or booting
+  // the server in vitest — never spawns competing loops.
+  ensureRotationScheduler(
+    { db: ctx.db, lettaClient: ctx.lettaClient, logger: ctx.logger },
+    envSource,
+  );
+
+  const routes = opts.routes ?? buildRouteTable();
+
+  return async (req) => {
+    const requestId = req.headers.get("x-request-id") ?? randomUUID();
+    const childLogger = ctx.logger.child({ request_id: requestId });
+    const childCtx: AIHubServerContext = { ...ctx, logger: childLogger };
+
+    const url = new URL(req.url);
+    const innerPath = stripBasePath(url.pathname, ctx.basePath);
+    if (innerPath === null) {
+      // Path is outside the basePath — the wrapper shouldn't have routed it
+      // here, but if it did we 404 cleanly rather than bubbling an
+      // ambiguous response.
+      return notFound();
+    }
+
+    const method = req.method.toUpperCase();
+    const match = matchRoute(routes, method, innerPath);
+    if (!match) {
+      // Distinguish "path doesn't exist" from "path exists, wrong method"
+      // — the React client treats them differently. We do the second-pass
+      // check by trying the wildcard method.
+      const anyMethod = matchRoute(routes, "*", innerPath);
+      if (anyMethod) return methodNotAllowed();
+      // Also check whether the same path exists for *any* method.
+      const samePath = routes.find((r) => pathMatchesRaw(r.path, innerPath));
+      return samePath ? methodNotAllowed() : notFound();
+    }
+
+    try {
+      return await match.entry.handler(req, childCtx, match.params);
+    } catch (err) {
+      childLogger.error(
+        { err: err instanceof Error ? err.message : String(err), method, path: innerPath },
+        "Unhandled error in route handler.",
+      );
+      return internalError();
+    }
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Helpers                                                                   */
+/* ────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Trims trailing slashes off `basePath` and ensures it begins with one.
+ *
+ * @param raw - the user-supplied base path.
+ * @returns the normalized base path (e.g. `"/api/ai-hub"`).
+ */
+function normalizeBasePath(raw: string): string {
+  if (!raw) return "";
+  let out = raw;
+  if (!out.startsWith("/")) out = "/" + out;
+  while (out.length > 1 && out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+}
+
+/**
+ * Returns `pathname` with `basePath` peeled off, or `null` if `pathname` is
+ * not under the prefix. An empty `basePath` returns `pathname` unchanged.
+ *
+ * @param pathname - request URL pathname.
+ * @param basePath - the configured prefix.
+ * @returns the inner path or `null`.
+ */
+function stripBasePath(pathname: string, basePath: string): string | null {
+  if (basePath === "" || basePath === "/") return pathname;
+  if (pathname === basePath) return "/";
+  if (pathname.startsWith(basePath + "/")) {
+    return pathname.slice(basePath.length);
+  }
+  return null;
+}
+
+/**
+ * Cheap "does this template match this path at all" predicate used for the
+ * 405-vs-404 disambiguation. Doesn't return params (that already happened
+ * in the main match).
+ *
+ * @param template - the route template.
+ * @param pathname - the actual path.
+ * @returns `true` when the template's segments match the path's.
+ */
+function pathMatchesRaw(template: string, pathname: string): boolean {
+  const tplParts = trimSlashes(template).split("/");
+  const pathParts = trimSlashes(pathname).split("/");
+  if (tplParts.length !== pathParts.length) return false;
+  for (let i = 0; i < tplParts.length; i++) {
+    const tp = tplParts[i] as string;
+    const pp = pathParts[i] as string;
+    if (tp.startsWith(":")) continue;
+    if (tp !== pp) return false;
+  }
+  return true;
+}
+
+/** Same trim logic as in `router.ts`; inlined here to keep this file self-contained. */
+function trimSlashes(s: string): string {
+  let out = s;
+  if (out.startsWith("/")) out = out.slice(1);
+  if (out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+}

package/src/handlers/nextjs.ts

@@ -0,0 +1,49 @@
+/**
+ * Next.js App Router adapter.
+ *
+ * Wraps `createFetchHandler` so per-customer wrapper apps can mount
+ * ai-hub-server with one line:
+ *
+ * ```ts
+ * // app/api/ai-hub/[...path]/route.ts
+ * import { createNextRouteHandler } from "@data-club/ai-hub-server";
+ *
+ * const handler = createNextRouteHandler({ ...options });
+ * export const GET = handler;
+ * export const POST = handler;
+ * export const PATCH = handler;
+ * export const DELETE = handler;
+ * ```
+ *
+ * The adapter is intentionally thin — Next.js App Router already gives us
+ * Web-Standard `Request` / `Response` objects, so this is barely more than
+ * a re-export. The reason it exists at all (rather than telling users to
+ * import `createFetchHandler` directly) is so the package owns the contract:
+ * if Next.js ever tightens its route-handler signature (e.g. adds a context
+ * arg), we adapt here without breaking every wrapper app.
+ *
+ * @see SPECIFICATIONS.md §6.2 — stack
+ * @see SPECIFICATIONS.md §14 — demo app pattern
+ */
+
+import {
+  createFetchHandler,
+  type CreateFetchHandlerOptions,
+  type FetchHandler,
+} from "./fetch.js";
+
+/**
+ * Builds a Next.js App Router-compatible route handler.
+ *
+ * Each HTTP-method export (`GET`, `POST`, …) in `route.ts` should reference
+ * the same instance — Next.js dispatches by method name, but our internal
+ * matcher does the work; sharing the instance avoids re-opening the DB.
+ *
+ * @param opts - same shape as `createFetchHandler`.
+ * @returns a function suitable for `export const GET = ...`.
+ */
+export function createNextRouteHandler(
+  opts: CreateFetchHandlerOptions,
+): FetchHandler {
+  return createFetchHandler(opts);
+}

package/src/handlers/responses.ts

@@ -0,0 +1,95 @@
+/**
+ * Small response helpers used by every handler.
+ *
+ * Centralizing them means error-shape drift can't happen — `unauthorized()`
+ * always emits the same `{ error: { code, message } }` envelope, so the
+ * React client's `AIHubError` reducer stays consistent.
+ *
+ * @see SPECIFICATIONS.md §13.4 — input safety / Zod validation
+ */
+
+/** Default JSON content-type with utf-8 charset. */
+const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+
+/**
+ * Writes `body` as JSON with the given `status`. Adds `application/json`
+ * content-type automatically.
+ *
+ * @param status - HTTP status code.
+ * @param body - JSON-serializable body.
+ * @param headers - extra headers to merge in.
+ * @returns the Response.
+ */
+export function jsonResponse(
+  status: number,
+  body: unknown,
+  headers?: Record<string, string>,
+): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "Content-Type": JSON_CONTENT_TYPE,
+      ...(headers ?? {}),
+    },
+  });
+}
+
+/**
+ * Standard error envelope. Pairs every error with a stable machine code so
+ * the React client's `AIHubError` discriminator stays useful.
+ *
+ * @param status - HTTP status code.
+ * @param code - machine-readable code matching the §7.5 `AIHubError` codes.
+ * @param message - human-readable description; safe to surface to end-users.
+ * @returns the Response.
+ */
+export function errorResponse(
+  status: number,
+  code: string,
+  message: string,
+): Response {
+  return jsonResponse(status, { error: { code, message } });
+}
+
+/** 401 with a generic invalid-credentials envelope (§13.1). */
+export function unauthorized(message = "Invalid credentials"): Response {
+  return errorResponse(401, "unauthorized", message);
+}
+
+/** 403 used for role-mismatch + shield + min-count violations (§8.6). */
+export function forbidden(
+  message = "Forbidden",
+  code = "forbidden",
+): Response {
+  return errorResponse(403, code, message);
+}
+
+/** 400 with a `validation` envelope. */
+export function validationError(message: string, code = "validation"): Response {
+  return errorResponse(400, code, message);
+}
+
+/** 409 used for state-conflict errors (e.g. `theme_switcher_disabled`). */
+export function conflictError(code: string, message: string): Response {
+  return errorResponse(409, code, message);
+}
+
+/** 501 used for Step-2 stubs that Step 3+ replaces with real handlers. */
+export function notImplemented(message = "Not implemented"): Response {
+  return errorResponse(501, "not_implemented", message);
+}
+
+/** 404 with no enumeration leakage — used for unknown paths (§8.6). */
+export function notFound(message = "Not found"): Response {
+  return errorResponse(404, "not_found", message);
+}
+
+/** 405 used by the matcher when the path matches but the method doesn't. */
+export function methodNotAllowed(message = "Method not allowed"): Response {
+  return errorResponse(405, "method_not_allowed", message);
+}
+
+/** 500 for internal-error catch-alls. The body never leaks stack traces. */
+export function internalError(message = "Internal server error"): Response {
+  return errorResponse(500, "internal", message);
+}