cursedbelt-server 1.0.0

package/src/server/middleware/localOrigin.ts

@@ -0,0 +1,139 @@
+/**
+ * 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: string, extra: ReadonlySet<string>): boolean {
+  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)
+  );
+}
+
+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[];
+}
+
+/** The hostname of a Host header value (`127.0.0.1:4747`, `[::1]:4747`). */
+function hostnameOf(hostHeader: string): string {
+  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: Request, opts: LocalOriginOpts | string = {}): string | null {
+  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: string;
+    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/src/server/middleware/rateLimit.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { clientIp, createRateLimiter } from './rateLimit';
+
+/**
+ * `x-forwarded-for` is written by the caller. If the limiter keys on it without
+ * knowing how many proxies it actually trusts, an attacker gets a brand-new
+ * bucket on every request just by varying the header — which is the whole
+ * protection, gone. These lock the trust model down.
+ */
+const app = (opts: Parameters<typeof createRateLimiter>[0]) => {
+  const a = new Hono();
+  a.use('*', createRateLimiter(opts));
+  a.get('/', (c) => c.text('ok'));
+  return a;
+};
+
+const hit = (a: Hono, xff?: string) =>
+  a.request('/', { headers: xff ? { 'x-forwarded-for': xff } : {} });
+
+describe('createRateLimiter — forwarded headers are not trusted by default', () => {
+  it('cannot be bypassed by varying x-forwarded-for', async () => {
+    const a = app({ limit: 2, windowMs: 60_000 });
+    expect((await hit(a, '1.1.1.1')).status).toBe(200);
+    expect((await hit(a, '2.2.2.2')).status).toBe(200);
+    // A third request with yet another forged address must NOT get a fresh bucket.
+    expect((await hit(a, '3.3.3.3')).status).toBe(429);
+    expect((await hit(a, '4.4.4.4')).status).toBe(429);
+  });
+
+  it('still limits when no forwarded header is present at all', async () => {
+    const a = app({ limit: 1, windowMs: 60_000 });
+    expect((await hit(a)).status).toBe(200);
+    expect((await hit(a)).status).toBe(429);
+  });
+});
+
+describe('clientIp — trust is explicit and read right-to-left', () => {
+  const ctx = (xff?: string, xri?: string) => {
+    const headers = new Headers();
+    if (xff) headers.set('x-forwarded-for', xff);
+    if (xri) headers.set('x-real-ip', xri);
+    // Minimal Context stand-in: clientIp only reads headers, and getConnInfo
+    // throws without a real Bun socket (→ the documented 'unknown' fallback).
+    return { req: { header: (n: string) => headers.get(n) ?? undefined } } as never;
+  };
+
+  it('ignores the chain entirely with no trusted hops (the default)', () => {
+    expect(clientIp(ctx('9.9.9.9'))).toBe('unknown');
+    expect(clientIp(ctx('9.9.9.9'), { trustedProxyHops: 0 })).toBe('unknown');
+  });
+
+  it('with one trusted hop takes the entry that hop observed — the RIGHTMOST', () => {
+    // "forged, forged, <what our nginx saw>" — the attacker can prepend freely.
+    expect(clientIp(ctx('1.1.1.1, 2.2.2.2, 203.0.113.7'), { trustedProxyHops: 1 })).toBe('203.0.113.7');
+  });
+
+  it('counts hops from the right for deeper chains', () => {
+    expect(clientIp(ctx('1.1.1.1, 203.0.113.7, 10.0.0.1'), { trustedProxyHops: 2 })).toBe('203.0.113.7');
+  });
+
+  it('does not fall back to the attacker-controlled leftmost entry when the chain is short', () => {
+    // Two trusted hops declared but only one entry sent: believing '1.1.1.1'
+    // would be trusting exactly the forgeable part.
+    expect(clientIp(ctx('1.1.1.1'), { trustedProxyHops: 2 })).toBe('unknown');
+  });
+
+  it('uses x-real-ip only when hops are trusted', () => {
+    expect(clientIp(ctx(undefined, '203.0.113.9'), { trustedProxyHops: 1 })).toBe('203.0.113.9');
+    expect(clientIp(ctx(undefined, '203.0.113.9'))).toBe('unknown');
+  });
+});

package/src/server/middleware/rateLimit.ts

@@ -0,0 +1,125 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { getConnInfo } from 'hono/bun';
+import { ApiError, toErrorEnvelope } from '../errors';
+
+/** 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 function clientIp(c: Context, options: ClientIpOptions = {}): string {
+  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';
+  }
+}
+
+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 function createRateLimiter(opts: RateLimitOpts): MiddlewareHandler {
+  const {
+    limit,
+    windowMs,
+    message = 'Too many requests. Please try again later.',
+    keyFn,
+    trustedProxyHops = 0,
+  } = opts;
+  const hits = new Map<string, number[]>();
+  let lastSweep = Date.now();
+
+  const sweep = (now: number): void => {
+    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/src/server/middleware/requestLogger.ts

@@ -0,0 +1,95 @@
+import type { Database } from 'bun:sqlite';
+import type { MiddlewareHandler } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { CursedbeltEnv } from '../context';
+import { isApiError } from '../errors';
+import { createMetricsBuffer, type MetricsBuffer } from '../metrics/metricsBuffer';
+import { normalizeRoute } from '../metrics/normalizeRoute';
+
+/**
+ * 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;
+}
+
+function statusOfThrown(err: unknown): number {
+  if (isApiError(err)) return err.status;
+  if (err instanceof HTTPException) return err.status;
+  return 500;
+}
+
+export function requestLogger(
+  db: Database,
+  opts: RequestLoggerOpts = {},
+): MiddlewareHandler<CursedbeltEnv> {
+  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: unknown;
+    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/src/server/middleware/securityHeaders.ts

@@ -0,0 +1,78 @@
+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}.
+ */
+
+// Derive the option types from Hono itself (it does not export them by name).
+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>;
+}
+
+// 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: CspDirectives = {
+  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: SecurityHeadersOpts = {}): MiddlewareHandler {
+  // 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,
+  });
+}