cursedbelt 2.7.0 → 3.0.0

package/src/server/middleware/localOrigin.ts

@@ -1,139 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-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

@@ -1,125 +0,0 @@
-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

@@ -1,95 +0,0 @@
-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

@@ -1,78 +0,0 @@
-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,
-  });
-}