cursedbelt-server 1.0.0

package/dist/server/middleware/corsAllowlist.js

@@ -0,0 +1,37 @@
+import { compileOriginMatcher, parseOriginList, siteOriginRules } from 'cwip/http';
+import { cors } from 'hono/cors';
+/** Build the Hono middleware from {@link CorsOpts}. Compiles the matcher once. */
+export const corsAllowlist = (opts) => {
+    const rules = [
+        ...(opts.siteDomain ? siteOriginRules(opts.siteDomain) : []),
+        ...(opts.origins ?? []),
+    ];
+    const isAllowed = compileOriginMatcher(rules);
+    return cors({
+        origin: (origin) => {
+            if (isAllowed(origin)) {
+                return origin;
+            }
+            if (origin) {
+                opts.onReject?.(origin);
+            }
+            return null;
+        },
+        credentials: opts.credentials ?? true,
+    });
+};
+/**
+ * Resolve {@link CorsOpts} from the conventional env vars, `undefined` when
+ * neither is set (same-origin deploy — no CORS middleware needed):
+ *  - `CORS_SITE_DOMAIN=example.com` — the systemic knob: apex + every subdomain.
+ *  - `CORS_ORIGINS=https://a.com,*.b.com` — exact/wildcard extras (or the whole
+ *    list, for apps that predate `CORS_SITE_DOMAIN`).
+ */
+export const corsOptsFromEnv = (env = process.env) => {
+    const siteDomain = env.CORS_SITE_DOMAIN?.trim() || undefined;
+    const origins = parseOriginList(env.CORS_ORIGINS);
+    if (!siteDomain && origins.length === 0) {
+        return undefined;
+    }
+    return { siteDomain, origins };
+};

package/dist/server/middleware/errorEnvelope.d.ts

@@ -0,0 +1,17 @@
+import type { ErrorHandler } from 'hono';
+import type { CursedbeltEnv } from '../context';
+/**
+ * Hono `onError` handler. Converts ANY thrown value into the ONE canonical rich
+ * envelope — `{ error: { name, message, code?, status?, category?, context?,
+ * isOperational, timestamp }, correlationId? }` (the shared `toErrorEnvelope` from
+ * `cwip/error`, re-exported via cursedbelt-core/errors) — plus the right HTTP status,
+ * and echoes the correlation id header so a client can quote it in a bug report.
+ * This is the Hono twin of cwip's express `errorHandler`; both funnel through the
+ * same formatter, so their JSON is byte-identical for the same thrown error.
+ *
+ *   - `ApiError` / any `AppError` → its `status` (else 500) + full summary.
+ *   - `HTTPException`             → normalized to an `ApiError` (its status + message).
+ *   - anything else               → 500 + a generic message; the real error is
+ *                                    logged with the correlation id (never leaked).
+ */
+export declare const errorEnvelope: ErrorHandler<CursedbeltEnv>;

package/dist/server/middleware/errorEnvelope.js

@@ -0,0 +1,32 @@
+import { HTTPException } from 'hono/http-exception';
+import { ApiError, isAppError, toErrorEnvelope } from '../errors';
+/**
+ * Hono `onError` handler. Converts ANY thrown value into the ONE canonical rich
+ * envelope — `{ error: { name, message, code?, status?, category?, context?,
+ * isOperational, timestamp }, correlationId? }` (the shared `toErrorEnvelope` from
+ * `cwip/error`, re-exported via cursedbelt-core/errors) — plus the right HTTP status,
+ * and echoes the correlation id header so a client can quote it in a bug report.
+ * This is the Hono twin of cwip's express `errorHandler`; both funnel through the
+ * same formatter, so their JSON is byte-identical for the same thrown error.
+ *
+ *   - `ApiError` / any `AppError` → its `status` (else 500) + full summary.
+ *   - `HTTPException`             → normalized to an `ApiError` (its status + message).
+ *   - anything else               → 500 + a generic message; the real error is
+ *                                    logged with the correlation id (never leaked).
+ */
+export const errorEnvelope = (err, c) => {
+    const cid = c.get('correlationId');
+    if (cid)
+        c.header('x-correlation-id', cid);
+    // Hono's own thrown errors carry a status + safe message — normalize to an
+    // `ApiError` so they flow through the single rich-envelope path.
+    const normalized = err instanceof HTTPException ? new ApiError(err.status, err.message || 'Error') : err;
+    // Unexpected (non-`AppError`) errors: log the real thing (with the correlation
+    // id for cross-reference). The envelope stays sanitized — `toErrorEnvelope`
+    // returns a generic 500 message for non-`AppError`s, so internals never leak.
+    if (!isAppError(normalized)) {
+        console.error(`[error]${cid ? ` [${cid}]` : ''}`, err);
+    }
+    const envelope = toErrorEnvelope(normalized, { correlationId: cid });
+    return c.json(envelope, (envelope.error.status ?? 500));
+};

package/dist/server/middleware/index.d.ts

@@ -0,0 +1,9 @@
+export { correlationId } from './correlationId';
+export { type CorsOpts, corsAllowlist, corsOptsFromEnv } from './corsAllowlist';
+export { errorEnvelope } from './errorEnvelope';
+export { crossOriginRefusal } from './localOrigin';
+export { clientIp, createRateLimiter, type RateLimitOpts } from './rateLimit';
+export { type RequestLoggerOpts, requestLogger } from './requestLogger';
+export { type CspDirectives, type SecurityHeadersOpts, securityHeaders, } from './securityHeaders';
+export { toValidationIssues, VALIDATION_ERROR_CODE, type ValidationIssue, validationEnvelope, } from '../errors';
+export { type ZValidatorTarget, zValidator } from './zValidator';

package/dist/server/middleware/index.js

@@ -0,0 +1,10 @@
+// The cross-cutting cursedbelt server middleware set.
+export { correlationId } from './correlationId';
+export { corsAllowlist, corsOptsFromEnv } from './corsAllowlist';
+export { errorEnvelope } from './errorEnvelope';
+export { crossOriginRefusal } from './localOrigin';
+export { clientIp, createRateLimiter } from './rateLimit';
+export { requestLogger } from './requestLogger';
+export { securityHeaders, } from './securityHeaders';
+export { toValidationIssues, VALIDATION_ERROR_CODE, validationEnvelope, } from '../errors';
+export { zValidator } from './zValidator';

package/dist/server/middleware/localOrigin.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The second lock on a LOOPBACK-ONLY HTTP daemon — the one binding to 127.0.0.1
+ * does not provide.
+ *
+ * ── The gap, measured 2026-08-06 against a live daemon ──────────────────────
+ * A machine-local daemon's whole trust model is "it only listens on 127.0.0.1",
+ * and for the NETWORK that is a real wall. For the owner's BROWSER it is not,
+ * for two reasons that have nothing to do with binding:
+ *
+ * 1. **CSRF.** Any page on any website can `POST http://127.0.0.1:<port>/...`.
+ *    A cross-origin POST normally trips a CORS preflight the server would fail,
+ *    but a preflight is only required for a NON-simple request — and
+ *    `<form enctype="text/plain">` is simple, so it fires with no preflight at
+ *    all. A body parser that calls `req.json()` parses it regardless of
+ *    Content-Type, and the classic `text/plain` form trick smuggles valid JSON
+ *    straight through. Verified by hand against the station daemon on :4747: a
+ *    POST carrying `Content-Type: text/plain`, `Origin: https://evil.example.com`
+ *    and `Sec-Fetch-Site: cross-site` was accepted, parsed, and reached field
+ *    validation. The attacker cannot READ the reply (no CORS headers, so it
+ *    stays opaque) — but destruction does not need a reply.
+ *
+ * 2. **DNS rebinding.** With no Host check, an attacker domain whose DNS flips
+ *    to 127.0.0.1 becomes same-origin in the browser's eyes — which lifts the
+ *    opaque-response limit above and turns every GET into an exfiltration
+ *    channel.
+ *
+ * ── What this refuses, and why it costs nothing ─────────────────────────────
+ * A refusal needs a browser-only signal to be present and WRONG. Real local
+ * clients — curl, a bun `fetch` in an agent, a server-side proxy — send no
+ * `Origin` and no `Sec-Fetch-Site`, so they are untouched. A page served from
+ * the daemon itself is same-origin. A loopback SPA on ANOTHER port is
+ * `same-site` with a loopback `Origin`, and is allowed on purpose: the wall
+ * being defended is "not the local machine", not "not another port".
+ *
+ * This deliberately does NOT add a login. Loopback + owner-only remains the
+ * design for the daemons that use it; this only closes the hole where
+ * "loopback" silently included "every website the owner visits".
+ *
+ * ── Placement ───────────────────────────────────────────────────────────────
+ * Landed in station's own tree on 2026-08-06 and lifted here the same day, when
+ * orch (:3021) and cloud (:3022) turned out to need the identical guard —
+ * STANDARDS.md §1: three copies is one too many, and a request-header security
+ * check is not app-shaped. It sits beside `corsAllowlist` and `rateLimit`
+ * because it is the same kind of thing: a pure, header-only verdict about
+ * whether a request may be served.
+ */
+export interface LocalOriginOpts {
+    /**
+     * Names the surface in the refusal text ("the machine API", "the orchestrator
+     * engine"). The owner reads these in a log line with no other context about
+     * which daemon spoke.
+     */
+    label?: string;
+    /**
+     * Extra EXACT hostnames that also mean this machine — a local host-header
+     * proxy's names (`cloud.localhost`). Matched whole, never as a suffix.
+     */
+    allowHosts?: readonly string[];
+}
+/**
+ * Why this request must be refused, or `null` to let it through.
+ *
+ * Pure and header-only so it is exhaustively testable without a socket. The
+ * caller decides the response; every current caller answers `403` with the
+ * reason as the body, and logs it — a silent refusal on a local daemon is
+ * indistinguishable from the daemon being down.
+ *
+ * @param opts see {@link LocalOriginOpts}. A bare string is accepted as the
+ *   label, since that is the only thing most callers need.
+ */
+export declare function crossOriginRefusal(req: Request, opts?: LocalOriginOpts | string): string | null;

package/dist/server/middleware/localOrigin.js

@@ -0,0 +1,119 @@
+/**
+ * The second lock on a LOOPBACK-ONLY HTTP daemon — the one binding to 127.0.0.1
+ * does not provide.
+ *
+ * ── The gap, measured 2026-08-06 against a live daemon ──────────────────────
+ * A machine-local daemon's whole trust model is "it only listens on 127.0.0.1",
+ * and for the NETWORK that is a real wall. For the owner's BROWSER it is not,
+ * for two reasons that have nothing to do with binding:
+ *
+ * 1. **CSRF.** Any page on any website can `POST http://127.0.0.1:<port>/...`.
+ *    A cross-origin POST normally trips a CORS preflight the server would fail,
+ *    but a preflight is only required for a NON-simple request — and
+ *    `<form enctype="text/plain">` is simple, so it fires with no preflight at
+ *    all. A body parser that calls `req.json()` parses it regardless of
+ *    Content-Type, and the classic `text/plain` form trick smuggles valid JSON
+ *    straight through. Verified by hand against the station daemon on :4747: a
+ *    POST carrying `Content-Type: text/plain`, `Origin: https://evil.example.com`
+ *    and `Sec-Fetch-Site: cross-site` was accepted, parsed, and reached field
+ *    validation. The attacker cannot READ the reply (no CORS headers, so it
+ *    stays opaque) — but destruction does not need a reply.
+ *
+ * 2. **DNS rebinding.** With no Host check, an attacker domain whose DNS flips
+ *    to 127.0.0.1 becomes same-origin in the browser's eyes — which lifts the
+ *    opaque-response limit above and turns every GET into an exfiltration
+ *    channel.
+ *
+ * ── What this refuses, and why it costs nothing ─────────────────────────────
+ * A refusal needs a browser-only signal to be present and WRONG. Real local
+ * clients — curl, a bun `fetch` in an agent, a server-side proxy — send no
+ * `Origin` and no `Sec-Fetch-Site`, so they are untouched. A page served from
+ * the daemon itself is same-origin. A loopback SPA on ANOTHER port is
+ * `same-site` with a loopback `Origin`, and is allowed on purpose: the wall
+ * being defended is "not the local machine", not "not another port".
+ *
+ * This deliberately does NOT add a login. Loopback + owner-only remains the
+ * design for the daemons that use it; this only closes the hole where
+ * "loopback" silently included "every website the owner visits".
+ *
+ * ── Placement ───────────────────────────────────────────────────────────────
+ * Landed in station's own tree on 2026-08-06 and lifted here the same day, when
+ * orch (:3021) and cloud (:3022) turned out to need the identical guard —
+ * STANDARDS.md §1: three copies is one too many, and a request-header security
+ * check is not app-shaped. It sits beside `corsAllowlist` and `rateLimit`
+ * because it is the same kind of thing: a pure, header-only verdict about
+ * whether a request may be served.
+ */
+/**
+ * Hosts that mean THIS machine. IPv6 arrives bracketed in a Host header.
+ *
+ * `extra` is for a daemon reached through a local host-header proxy under a
+ * name that is not itself a loopback literal — the dev gateway serves
+ * `cloud.localhost`, and note that the SUFFIX is deliberately not enough on its
+ * own (`localhost.evil.example.com` must stay refused), so each such name is
+ * listed exactly rather than pattern-matched.
+ */
+function isLoopbackHost(hostname, extra) {
+    const h = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    return (h === 'localhost' ||
+        h === '::1' ||
+        h === '0:0:0:0:0:0:0:1' ||
+        // 127.0.0.0/8 — all of it is loopback, not just 127.0.0.1.
+        /^127(\.\d{1,3}){3}$/.test(h) ||
+        extra.has(h));
+}
+/** The hostname of a Host header value (`127.0.0.1:4747`, `[::1]:4747`). */
+function hostnameOf(hostHeader) {
+    const trimmed = hostHeader.trim();
+    if (trimmed.startsWith('['))
+        return trimmed.slice(0, trimmed.indexOf(']') + 1);
+    const colon = trimmed.lastIndexOf(':');
+    return colon === -1 ? trimmed : trimmed.slice(0, colon);
+}
+/**
+ * Why this request must be refused, or `null` to let it through.
+ *
+ * Pure and header-only so it is exhaustively testable without a socket. The
+ * caller decides the response; every current caller answers `403` with the
+ * reason as the body, and logs it — a silent refusal on a local daemon is
+ * indistinguishable from the daemon being down.
+ *
+ * @param opts see {@link LocalOriginOpts}. A bare string is accepted as the
+ *   label, since that is the only thing most callers need.
+ */
+export function crossOriginRefusal(req, opts = {}) {
+    const { label = 'this daemon', allowHosts = [] } = typeof opts === 'string' ? { label: opts } : opts;
+    const extra = new Set(allowHosts.map((h) => h.toLowerCase()));
+    // ── DNS rebinding: the Host must name this machine ──────────────────────
+    // Checked first: a rebound Host is the case where the OTHER signals start
+    // looking legitimately same-origin, so it has to fail before they are read.
+    const host = req.headers.get('host');
+    if (host && !isLoopbackHost(hostnameOf(host), extra)) {
+        return `Host "${host}" is not a loopback name — ${label} answers only to 127.0.0.1/localhost`;
+    }
+    // ── CSRF: a browser told us where this came from; believe it ─────────────
+    const origin = req.headers.get('origin');
+    if (origin && origin !== 'null') {
+        let originHost;
+        try {
+            originHost = new URL(origin).hostname;
+        }
+        catch {
+            return `unparseable Origin "${origin}"`;
+        }
+        if (!isLoopbackHost(originHost, extra)) {
+            return `cross-origin request from "${origin}" — ${label} is local-only`;
+        }
+    }
+    // `same-site` is deliberately allowed: a loopback SPA on another port is
+    // cross-ORIGIN but same-SITE, and it is a legitimate local caller. Anything
+    // genuinely external reports `cross-site` and never reaches here anyway,
+    // because its Origin failed the loopback test above — this is the belt to
+    // that braces, for a browser that sends Sec-Fetch-Site but omits Origin
+    // (which is what a cross-site GET navigation does).
+    const site = req.headers.get('sec-fetch-site');
+    if (site && !['same-origin', 'same-site', 'none'].includes(site.toLowerCase())) {
+        return `Sec-Fetch-Site: ${site} — ${label} does not serve other sites`;
+    }
+    return null;
+}

package/dist/server/middleware/rateLimit.d.ts

@@ -0,0 +1,56 @@
+import type { Context, MiddlewareHandler } from 'hono';
+/** How much of the forwarded-header chain, if any, this server may believe. */
+export interface ClientIpOptions {
+    /**
+     * How many TRUSTED reverse proxies sit in front of this server.
+     *
+     * `0` (the default) means none: use the socket peer and ignore forwarded
+     * headers entirely. Set it to the real number of hops you control (nginx in
+     * front of Bun ⇒ `1`).
+     */
+    trustedProxyHops?: number;
+}
+/**
+ * The client IP for rate-limiting / logging.
+ *
+ * `X-Forwarded-For` is written by whoever is calling — a client can send any
+ * value it likes. Reading it unconditionally means an attacker gets a NEW
+ * rate-limit bucket on every request simply by varying the header, which
+ * silently removes the protection the limiter exists to provide. So forwarded
+ * headers are IGNORED unless you declare how many proxies you actually trust.
+ *
+ * When you do, the chain is read RIGHT-to-LEFT. A proxy appends the peer it saw
+ * to any existing header (nginx's `$proxy_add_x_forwarded_for`), so with one
+ * trusted hop the last entry is the address YOUR proxy observed, while
+ * everything to its left is caller-supplied and unverifiable. Taking the first
+ * entry — the previous behavior — is taking exactly the part an attacker
+ * controls.
+ *
+ * Falls back to `'unknown'` when no connection info is available (e.g.
+ * `app.fetch(new Request(...))` in tests).
+ */
+export declare function clientIp(c: Context, options?: ClientIpOptions): string;
+export interface RateLimitOpts {
+    /** Max requests allowed per window per key. */
+    limit: number;
+    /** Sliding window length in ms. */
+    windowMs: number;
+    /** 429 body message. */
+    message?: string;
+    /** Key function (default: client IP). Use to throttle per authenticated user. */
+    keyFn?: (c: Context) => string;
+    /**
+     * How many trusted reverse proxies sit in front of this server, for the
+     * default IP key. Default `0` — forwarded headers are ignored, because a
+     * caller can forge them to mint a fresh bucket per request. See
+     * {@link ClientIpOptions}.
+     */
+    trustedProxyHops?: number;
+}
+/**
+ * A sliding-window, in-memory rate limiter as Hono middleware. Keeps a timestamp log
+ * per key, prunes entries older than the window on access, and a cheap periodic
+ * sweep drops idle keys (no dangling timers). On limit: 429 + `Retry-After` + the
+ * canonical `{ error }` envelope. Used by auth routes (task 26) + vault unlock.
+ */
+export declare function createRateLimiter(opts: RateLimitOpts): MiddlewareHandler;

package/dist/server/middleware/rateLimit.js

@@ -0,0 +1,86 @@
+import { getConnInfo } from 'hono/bun';
+import { ApiError, toErrorEnvelope } from '../errors';
+/**
+ * The client IP for rate-limiting / logging.
+ *
+ * `X-Forwarded-For` is written by whoever is calling — a client can send any
+ * value it likes. Reading it unconditionally means an attacker gets a NEW
+ * rate-limit bucket on every request simply by varying the header, which
+ * silently removes the protection the limiter exists to provide. So forwarded
+ * headers are IGNORED unless you declare how many proxies you actually trust.
+ *
+ * When you do, the chain is read RIGHT-to-LEFT. A proxy appends the peer it saw
+ * to any existing header (nginx's `$proxy_add_x_forwarded_for`), so with one
+ * trusted hop the last entry is the address YOUR proxy observed, while
+ * everything to its left is caller-supplied and unverifiable. Taking the first
+ * entry — the previous behavior — is taking exactly the part an attacker
+ * controls.
+ *
+ * Falls back to `'unknown'` when no connection info is available (e.g.
+ * `app.fetch(new Request(...))` in tests).
+ */
+export function clientIp(c, options = {}) {
+    const hops = Math.max(0, Math.trunc(options.trustedProxyHops ?? 0));
+    if (hops > 0) {
+        const chain = (c.req.header('x-forwarded-for') ?? '')
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean);
+        // The entry your own trusted hop observed. If the chain is shorter than the
+        // configured hop count the client sent fewer entries than expected — fall
+        // through to the socket rather than believing the leftmost value.
+        const trusted = chain[chain.length - hops];
+        if (trusted)
+            return trusted;
+        // `x-real-ip` is single-valued and set by the same trusted proxy.
+        const xri = c.req.header('x-real-ip');
+        if (xri?.trim())
+            return xri.trim();
+    }
+    try {
+        return getConnInfo(c).remote.address ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * A sliding-window, in-memory rate limiter as Hono middleware. Keeps a timestamp log
+ * per key, prunes entries older than the window on access, and a cheap periodic
+ * sweep drops idle keys (no dangling timers). On limit: 429 + `Retry-After` + the
+ * canonical `{ error }` envelope. Used by auth routes (task 26) + vault unlock.
+ */
+export function createRateLimiter(opts) {
+    const { limit, windowMs, message = 'Too many requests. Please try again later.', keyFn, trustedProxyHops = 0, } = opts;
+    const hits = new Map();
+    let lastSweep = Date.now();
+    const sweep = (now) => {
+        const cutoff = now - windowMs;
+        for (const [key, times] of hits) {
+            const live = times.filter((t) => t > cutoff);
+            if (live.length === 0)
+                hits.delete(key);
+            else
+                hits.set(key, live);
+        }
+        lastSweep = now;
+    };
+    return async (c, next) => {
+        const key = keyFn ? keyFn(c) : clientIp(c, { trustedProxyHops });
+        const now = Date.now();
+        const cutoff = now - windowMs;
+        // Periodically evict idle keys so the map can't grow unbounded.
+        if (now - lastSweep > windowMs)
+            sweep(now);
+        const times = (hits.get(key) ?? []).filter((t) => t > cutoff);
+        if (times.length >= limit) {
+            hits.set(key, times);
+            const retryMs = (times[0] ?? now) + windowMs - now;
+            c.header('Retry-After', String(Math.max(1, Math.ceil(retryMs / 1000))));
+            return c.json(toErrorEnvelope(new ApiError(429, message, { code: 'rate_limited' })), 429);
+        }
+        times.push(now);
+        hits.set(key, times);
+        await next();
+    };
+}

package/dist/server/middleware/requestLogger.d.ts

@@ -0,0 +1,29 @@
+import type { Database } from 'bun:sqlite';
+import type { MiddlewareHandler } from 'hono';
+import type { CursedbeltEnv } from '../context';
+import { type MetricsBuffer } from '../metrics/metricsBuffer';
+/**
+ * Structured request/response logging. After each request it records one slim
+ * `request_metrics` row (via the batched {@link MetricsBuffer}, off the hot path)
+ * and, for errors (status ≥ 400) or slow requests, one `event_logs` row tagged with
+ * the correlation id. Attributes rows to `c.get('userId')` when the app's auth
+ * middleware has set it.
+ *
+ * It records metrics even when a downstream handler THROWS: the error is caught,
+ * the would-be status derived, the row written, then the error re-thrown so the
+ * error-envelope `onError` still produces the response.
+ */
+export interface RequestLoggerOpts {
+    /**
+     * The metrics buffer to write through. Provide one (and own its lifecycle via
+     * `buffer.stop()`) to share it / flush deterministically; omit to create one from
+     * `db`. Its flush timer is `unref()`'d, so an internally-created buffer is fine for
+     * long-running servers.
+     */
+    buffer?: MetricsBuffer;
+    /** Duration (ms) at/above which a 2xx request also logs an `event_logs` row. Default: 2000. */
+    slowMs?: number;
+    /** Also write `event_logs` rows for status ≥ 400. Default: true. */
+    logErrors?: boolean;
+}
+export declare function requestLogger(db: Database, opts?: RequestLoggerOpts): MiddlewareHandler<CursedbeltEnv>;

package/dist/server/middleware/requestLogger.js

@@ -0,0 +1,47 @@
+import { HTTPException } from 'hono/http-exception';
+import { isApiError } from '../errors';
+import { createMetricsBuffer } from '../metrics/metricsBuffer';
+import { normalizeRoute } from '../metrics/normalizeRoute';
+function statusOfThrown(err) {
+    if (isApiError(err))
+        return err.status;
+    if (err instanceof HTTPException)
+        return err.status;
+    return 500;
+}
+export function requestLogger(db, opts = {}) {
+    const buffer = opts.buffer ?? createMetricsBuffer({ db });
+    const slowMs = opts.slowMs ?? 2000;
+    const logErrors = opts.logErrors ?? true;
+    const insertEvent = db.prepare(`INSERT INTO event_logs
+       (id, correlation_id, event_name, type, message, details, duration_ms, user_id, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    return async (c, next) => {
+        const start = performance.now();
+        let thrown;
+        let didThrow = false;
+        try {
+            await next();
+        }
+        catch (err) {
+            thrown = err;
+            didThrow = true;
+        }
+        const durationMs = performance.now() - start;
+        const { method, route } = normalizeRoute(c);
+        const status = didThrow ? statusOfThrown(thrown) : c.res.status;
+        const lenHeader = didThrow ? null : c.res.headers.get('content-length');
+        const bytesOut = lenHeader ? Number(lenHeader) : null;
+        const userId = c.get('userId') ?? null;
+        buffer.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
+        const isError = status >= 400;
+        const isSlow = durationMs >= slowMs;
+        if ((logErrors && isError) || isSlow) {
+            const type = status >= 500 ? 'error' : isError ? 'warn' : 'info';
+            insertEvent.run(crypto.randomUUID(), c.get('correlationId') ?? null, isError ? 'http_error' : 'http_slow', type, `${method} ${route} → ${status}`, JSON.stringify({ method, route, status, durationMs: Math.round(durationMs), bytesOut }), Math.round(durationMs), userId, new Date().toISOString());
+        }
+        // Re-throw so the error-envelope onError still builds the response.
+        if (didThrow)
+            throw thrown;
+    };
+}

package/dist/server/middleware/securityHeaders.d.ts

@@ -0,0 +1,29 @@
+import type { MiddlewareHandler } from 'hono';
+import { secureHeaders } from 'hono/secure-headers';
+/**
+ * Security headers, built on Hono's `secureHeaders` (helmet-equivalent) rather than
+ * a hand-rolled header pass — robust + maintained, per the "prefer configured
+ * libraries" mandate. cursedbelt supplies sensible cross-app defaults (strict CSP,
+ * `X-Frame-Options: DENY`, COOP, HSTS in production, …); the consuming app extends
+ * just the directives it needs (CDN hosts, embed frames) via {@link SecurityHeadersOpts}.
+ */
+type SecureHeadersOptions = NonNullable<Parameters<typeof secureHeaders>[0]>;
+export type CspDirectives = NonNullable<SecureHeadersOptions['contentSecurityPolicy']>;
+export interface SecurityHeadersOpts {
+    /**
+     * Extend/override the default CSP directives. Shallow-merged per directive, so a
+     * supplied directive REPLACES that default's value (pass the full list). Set to
+     * `false` to omit the CSP header entirely.
+     */
+    csp?: CspDirectives | false;
+    /**
+     * `Strict-Transport-Security` value. Default: enabled in production
+     * (`NODE_ENV==='production'`) as `max-age=31536000; includeSubDomains`, off
+     * otherwise. Pass a string to force a value, or `false` to disable.
+     */
+    hsts?: boolean | string;
+    /** Escape hatch: any other `secureHeaders` option, merged last (wins). */
+    overrides?: Partial<SecureHeadersOptions>;
+}
+export declare function securityHeaders(opts?: SecurityHeadersOpts): MiddlewareHandler;
+export {};

package/dist/server/middleware/securityHeaders.js

@@ -0,0 +1,44 @@
+import { secureHeaders } from 'hono/secure-headers';
+// A strict baseline that works for a same-origin SPA + JSON API. Apps widen the
+// few directives they need (script/img/connect hosts, frame embeds) via `opts.csp`.
+const DEFAULT_CSP = {
+    defaultSrc: ["'self'"],
+    baseUri: ["'self'"],
+    objectSrc: ["'none'"],
+    frameAncestors: ["'none'"],
+    formAction: ["'self'"],
+    scriptSrc: ["'self'"],
+    scriptSrcAttr: ["'none'"],
+    // Inline styles are needed for Tailwind / chart / drag transforms; inline SCRIPTS
+    // stay blocked (the real XSS barrier).
+    styleSrc: ["'self'", "'unsafe-inline'"],
+    imgSrc: ["'self'", 'data:', 'blob:'],
+    fontSrc: ["'self'", 'data:'],
+    connectSrc: ["'self'"],
+    upgradeInsecureRequests: [],
+};
+export function securityHeaders(opts = {}) {
+    // A runtime escape hatch matching ca's ops convention: CSP_DISABLED=true drops CSP.
+    const cspOff = opts.csp === false || process.env.CSP_DISABLED === 'true';
+    const csp = cspOff ? undefined : { ...DEFAULT_CSP, ...(opts.csp ?? {}) };
+    const isProd = process.env.NODE_ENV === 'production';
+    const hsts = opts.hsts ?? (isProd ? 'max-age=31536000; includeSubDomains' : false);
+    return secureHeaders({
+        contentSecurityPolicy: csp,
+        xContentTypeOptions: 'nosniff',
+        // DENY (not SAMEORIGIN) to agree with CSP `frame-ancestors 'none'`.
+        xFrameOptions: 'DENY',
+        referrerPolicy: 'strict-origin-when-cross-origin',
+        crossOriginOpenerPolicy: 'same-origin',
+        // We serve cross-origin media/fonts, so keep CORP permissive.
+        crossOriginResourcePolicy: 'cross-origin',
+        // COEP breaks third-party embeds (YouTube, CDNs) — off by default.
+        crossOriginEmbedderPolicy: false,
+        originAgentCluster: true,
+        xDnsPrefetchControl: 'off',
+        xPermittedCrossDomainPolicies: 'none',
+        strictTransportSecurity: hsts,
+        removePoweredBy: true,
+        ...opts.overrides,
+    });
+}

package/dist/server/middleware/zValidator.d.ts

@@ -0,0 +1,29 @@
+import type { Env, MiddlewareHandler } from 'hono';
+import type { ZodType, z } from 'zod';
+import type { CursedbeltEnv } from '../context';
+/** The request locations a schema can validate. Mirrors Hono's body/non-body split. */
+export type ZValidatorTarget = 'json' | 'form' | 'query' | 'param';
+/**
+ * Validate a request `target` against a zod `schema`. Mount per route ahead of the
+ * handler:
+ *
+ * ```ts
+ * register('post', '/notes', zValidator(CreateNoteSchema), (c) => {
+ *   const body = c.req.valid('json'); // typed z.infer<typeof CreateNoteSchema>
+ *   // …
+ * });
+ * ```
+ *
+ * On failure responds `400` with the canonical envelope (field errors under
+ * `context.issues`); never throws, so it produces the same body whether or not the
+ * app mounts the {@link errorEnvelope} `onError` handler. On success the parsed value
+ * is available as both `c.req.valid(target)` and `c.get('validatedBody')`.
+ */
+export declare function zValidator<Schema extends ZodType, Target extends ZValidatorTarget = 'json', E extends Env = CursedbeltEnv, P extends string = string>(schema: Schema, target?: Target): MiddlewareHandler<E, P, {
+    in: {
+        [K in Target]: z.input<Schema>;
+    };
+    out: {
+        [K in Target]: z.output<Schema>;
+    };
+}>;