cursedbelt-server 1.0.0

package/src/server/metrics/metricsBuffer.ts

@@ -0,0 +1,92 @@
+import type { Database } from 'bun:sqlite';
+
+/**
+ * In-memory, batched writer for `request_metrics`. To keep request latency
+ * untouched we never write per request: rows land in a buffer and a single batched
+ * transaction flushes them on an interval (and eagerly when the buffer is large).
+ *
+ * This is the reusable successor to ca's `metricsBuffer` module, retargeted at the
+ * task-22 `request_metrics` schema (no `created_at` column — `ts` is the epoch-ms
+ * timestamp). The flush timer is `unref()`'d so it never keeps the process alive.
+ */
+
+export interface MetricRow {
+  /** Epoch ms. */
+  ts: number;
+  method: string | null;
+  /** Normalized route label (see `normalizeRoute`). */
+  route: string | null;
+  status: number | null;
+  durationMs: number | null;
+  bytesOut: number | null;
+  userId: string | null;
+}
+
+export interface MetricsBufferOptions {
+  db: Database;
+  /** Flush cadence in ms. Default: 1500. */
+  flushIntervalMs?: number;
+  /** Eager-flush threshold — caps memory if a flush stalls. Default: 5000. */
+  maxSize?: number;
+}
+
+export interface MetricsBuffer {
+  /** Enqueue one request's metrics (non-blocking; flushed in batches). */
+  record(row: MetricRow): void;
+  /** Force-flush the buffer now (also used on shutdown + in tests). */
+  flush(): void;
+  /** Stop the flush timer and drain whatever remains. */
+  stop(): void;
+  /** Rows currently buffered (not yet flushed). */
+  readonly size: number;
+}
+
+export function createMetricsBuffer(opts: MetricsBufferOptions): MetricsBuffer {
+  const { db, flushIntervalMs = 1500, maxSize = 5000 } = opts;
+  let buffer: MetricRow[] = [];
+
+  const insert = db.prepare(
+    `INSERT INTO request_metrics (id, ts, method, route, status, duration_ms, bytes_out, user_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  const insertMany = db.transaction((rows: MetricRow[]) => {
+    for (const r of rows) {
+      insert.run(
+        crypto.randomUUID(),
+        r.ts,
+        r.method,
+        r.route,
+        r.status,
+        r.durationMs,
+        r.bytesOut,
+        r.userId,
+      );
+    }
+  });
+
+  const flush = (): void => {
+    if (buffer.length === 0) return;
+    const batch = buffer;
+    buffer = [];
+    insertMany(batch);
+  };
+
+  const timer = setInterval(flush, flushIntervalMs);
+  // Never let the metrics flusher hold the event loop / process open.
+  timer.unref?.();
+
+  return {
+    record(row) {
+      buffer.push(row);
+      if (buffer.length >= maxSize) flush();
+    },
+    flush,
+    stop() {
+      clearInterval(timer);
+      flush();
+    },
+    get size() {
+      return buffer.length;
+    },
+  };
+}

package/src/server/metrics/normalizeRoute.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { normalizeRoute } from './normalizeRoute';
+
+// Probe through a real Hono app so `c.req.routePath` is the genuine matched pattern.
+async function labelFor(register: (app: Hono) => void, request: Request): Promise<string> {
+  const app = new Hono();
+  register(app);
+  const res = await app.fetch(request); // Hono may return Response or Promise<Response>
+  return res.text();
+}
+
+const probe = (c: import('hono').Context) => {
+  const { method, route } = normalizeRoute(c);
+  return c.text(`${method} ${route}`);
+};
+
+describe('normalizeRoute', () => {
+  test('uses the matched route pattern (with :params), not the concrete path', async () => {
+    const label = await labelFor(
+      (app) => app.get('/api/v1/notes/:id', probe),
+      new Request('http://x/api/v1/notes/abc-123'),
+    );
+    expect(label).toBe('GET /api/v1/notes/:id');
+  });
+
+  test('collapses dynamic-looking segments on unmatched paths (bounds cardinality)', async () => {
+    const label = await labelFor(
+      (app) => app.notFound(probe),
+      new Request('http://x/files/550e8400-e29b-41d4-a716-446655440000/raw'),
+    );
+    expect(label).toBe('GET /files/:id/raw');
+  });
+
+  test('collapses long numeric + opaque segments', async () => {
+    const label = await labelFor(
+      (app) => app.notFound(probe),
+      new Request('http://x/u/12345/blob/deadbeefdeadbeefdeadbeef'),
+    );
+    expect(label).toBe('GET /u/:id/blob/:id');
+  });
+
+  test('maps a ctgr GET-twin back to its real verb + path', async () => {
+    const label = await labelFor(
+      (app) => app.get('/api/ctgrch/notes/:id', probe),
+      new Request('http://x/api/ctgrch/notes/n1'),
+    );
+    // /ctgrch = PATCH twin → aggregates with the real PATCH /api/notes/:id
+    expect(label).toBe('PATCH /api/notes/:id');
+  });
+});

package/src/server/metrics/normalizeRoute.ts

@@ -0,0 +1,63 @@
+import type { Context } from 'hono';
+
+/**
+ * Turn a request into a stable, low-cardinality route label for metric aggregation
+ * (e.g. `/api/v1/notes/:id`). The method is tracked separately.
+ *
+ * Two wrinkles, same as the old Express normalizer:
+ *   1. ctgr GET-tunnelled mutations match the `/ctgr<xx>` twin route — we map them
+ *      back to the real verb + path so a POST and its ctgr twin aggregate together.
+ *   2. Unmatched requests (404s, static, the SPA fallback) have no matched route
+ *      pattern, so we collapse dynamic-looking segments to avoid unbounded
+ *      cardinality blowing up the metrics table.
+ */
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const LONG_HEX_RE = /^[0-9a-f]{16,}$/i;
+
+// The ctgr twin URL is `/ctgr<last-2-of-method><url>`, so the two-letter suffix
+// recovers the original verb (POST→st, PUT→ut, PATCH→ch, DELETE→te).
+const CTGR_METHOD: Record<string, string> = { st: 'POST', ut: 'PUT', ch: 'PATCH', te: 'DELETE' };
+
+function collapseSegment(seg: string): string {
+  if (!seg) return seg;
+  if (/^\d+$/.test(seg)) return ':id';
+  if (UUID_RE.test(seg)) return ':id';
+  if (LONG_HEX_RE.test(seg)) return ':id';
+  // Long opaque tokens (encoded paths, blobs) collapse so they don't explode route
+  // cardinality. Plain words stay as-is.
+  if (seg.length >= 24) return ':id';
+  return seg;
+}
+
+function collapsePath(path: string): string {
+  const parts = path.split('/').filter(Boolean).map(collapseSegment);
+  return `/${parts.join('/')}`;
+}
+
+export function normalizeRoute(c: Context): { method: string; route: string } {
+  let method = c.req.method;
+
+  // Hono's matched route pattern (with :params) is the ideal label. A wildcard
+  // (`/*`, `*`) or empty pattern means "no real match" → collapse the raw path.
+  // `c.req.routePath` THROWS when nothing matched (e.g. a 404 / the SPA fallback),
+  // so guard it — an unmatched request must still produce a metrics label.
+  let matched: string | undefined;
+  try {
+    matched = c.req.routePath;
+  } catch {
+    matched = undefined;
+  }
+  let route =
+    matched && !matched.includes('*') ? matched : collapsePath(c.req.path.split('?')[0]) || '/';
+
+  // Map a ctgr GET-twin back to its real verb + url:
+  //   /api/ctgrch/notes/:id → PATCH /api/notes/:id
+  const ctgr = route.match(/\/ctgr([a-z]{2})(?=\/|$)/i);
+  if (ctgr) {
+    method = CTGR_METHOD[ctgr[1].toLowerCase()] ?? method;
+    route = route.replace(/\/ctgr[a-z]{2}/i, '') || '/';
+  }
+
+  return { method, route };
+}

package/src/server/middleware/correlationId.ts

@@ -0,0 +1,24 @@
+import type { MiddlewareHandler } from 'hono';
+import type { CursedbeltEnv } from '../context';
+
+const HEADER = 'x-correlation-id';
+// Accept a client-supplied id only if it is a sane, header-safe token (no CRLF /
+// control chars / unbounded length) — otherwise mint a fresh one. This both
+// preserves trace ids across a proxy hop and blocks response-header injection.
+const SAFE_ID = /^[A-Za-z0-9._:-]{1,200}$/;
+
+/**
+ * Assign every request a correlation id: reuse a safe inbound `x-correlation-id`
+ * (so a trace survives the proxy hop), else mint a `crypto.randomUUID()`. Stored on
+ * `c.set('correlationId', id)` for downstream middleware (request logger, error
+ * envelope) and echoed on the response header. Mount this FIRST.
+ */
+export function correlationId(): MiddlewareHandler<CursedbeltEnv> {
+  return async (c, next) => {
+    const inbound = c.req.header(HEADER);
+    const id = inbound && SAFE_ID.test(inbound) ? inbound : crypto.randomUUID();
+    c.set('correlationId', id);
+    c.header(HEADER, id);
+    await next();
+  };
+}

package/src/server/middleware/corsAllowlist.spec.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from 'bun:test';
+import { createApp } from '../app';
+import { corsAllowlist, corsOptsFromEnv } from './corsAllowlist';
+
+const SITE = 'example.com';
+const APEX = 'https://example.com';
+const API_PATH = '/api/thing';
+
+const appWithCors = () => {
+  const app = createApp({ cors: { siteDomain: SITE, origins: ['http://localhost:5173'] } });
+  app.get(API_PATH, (c) => c.json({ ok: true }));
+  return app;
+};
+
+const preflight = (app: ReturnType<typeof createApp>, origin: string) =>
+  app.request(API_PATH, {
+    method: 'OPTIONS',
+    headers: {
+      origin,
+      'access-control-request-method': 'GET',
+      'access-control-request-headers': 'content-type',
+    },
+  });
+
+describe('corsAllowlist via createApp', () => {
+  test('preflight from the apex: allowed, credentialed, methods advertised', async () => {
+    const res = await preflight(appWithCors(), APEX);
+    expect(res.status).toBe(204);
+    expect(res.headers.get('access-control-allow-origin')).toBe(APEX);
+    expect(res.headers.get('access-control-allow-credentials')).toBe('true');
+    expect(res.headers.get('access-control-allow-methods')).toContain('POST');
+  });
+
+  test('preflight from any subdomain (present or future): allowed via siteDomain', async () => {
+    for (const origin of [
+      'https://api.example.com',
+      'https://sandbox.example.com',
+      'https://brand-new-subdomain.example.com',
+    ]) {
+      const res = await preflight(appWithCors(), origin);
+      expect(res.status).toBe(204);
+      expect(res.headers.get('access-control-allow-origin')).toBe(origin);
+    }
+  });
+
+  test('extra origins rule (dev Vite) allowed', async () => {
+    const res = await preflight(appWithCors(), 'http://localhost:5173');
+    expect(res.headers.get('access-control-allow-origin')).toBe('http://localhost:5173');
+  });
+
+  test('unknown origin: NO allow-origin header (browser-visible rejection), never *', async () => {
+    for (const origin of [
+      'https://evil.com',
+      'https://example.com.evil.com',
+      'http://example.com',
+    ]) {
+      const res = await preflight(appWithCors(), origin);
+      expect(res.headers.get('access-control-allow-origin')).toBeNull();
+    }
+  });
+
+  test('simple GET from an allowed origin echoes the origin on the response', async () => {
+    const res = await appWithCors().request(API_PATH, {
+      headers: { origin: 'https://api.example.com' },
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get('access-control-allow-origin')).toBe('https://api.example.com');
+    expect(res.headers.get('vary')).toContain('Origin');
+  });
+
+  test('no-Origin request (curl / same-origin) is untouched', async () => {
+    const res = await appWithCors().request(API_PATH);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('access-control-allow-origin')).toBeNull();
+  });
+
+  test('onReject fires with the rejected origin', async () => {
+    const rejected: string[] = [];
+    const app = createApp({ cors: { siteDomain: SITE, onReject: (o) => rejected.push(o) } });
+    app.get(API_PATH, (c) => c.json({ ok: true }));
+    await preflight(app, 'https://evil.com');
+    expect(rejected).toEqual(['https://evil.com']);
+  });
+
+  test('createApp without cors mounts nothing (same-origin deploy unchanged)', async () => {
+    const app = createApp();
+    app.get(API_PATH, (c) => c.json({ ok: true }));
+    const res = await app.request(API_PATH, { headers: { origin: APEX } });
+    expect(res.headers.get('access-control-allow-origin')).toBeNull();
+  });
+
+  test('a bad rule fails loudly at build time (boot-time typo detection)', () => {
+    expect(() => corsAllowlist({ origins: ['https://'] })).toThrow(/Invalid CORS origin rule/);
+  });
+});
+
+describe('corsOptsFromEnv', () => {
+  test('undefined when neither var set', () => {
+    expect(corsOptsFromEnv({})).toBeUndefined();
+  });
+
+  test('CORS_SITE_DOMAIN alone', () => {
+    expect(corsOptsFromEnv({ CORS_SITE_DOMAIN: 'example.com' })).toEqual({
+      siteDomain: 'example.com',
+      origins: [],
+    });
+  });
+
+  test('CORS_ORIGINS alone (legacy shape) and combined', () => {
+    expect(corsOptsFromEnv({ CORS_ORIGINS: 'https://a.com, *.b.com' })).toEqual({
+      siteDomain: undefined,
+      origins: ['https://a.com', '*.b.com'],
+    });
+    expect(
+      corsOptsFromEnv({ CORS_SITE_DOMAIN: 'example.com', CORS_ORIGINS: 'http://localhost:5173' }),
+    ).toEqual({ siteDomain: 'example.com', origins: ['http://localhost:5173'] });
+  });
+});

package/src/server/middleware/corsAllowlist.ts

@@ -0,0 +1,69 @@
+import { compileOriginMatcher, type OriginRule, parseOriginList, siteOriginRules } from 'cwip/http';
+import type { MiddlewareHandler } from 'hono';
+import { cors } from 'hono/cors';
+
+/**
+ * Cross-app CORS for the split deploy shape every cursedbelt app shares (SPA on
+ * one origin, API on another — e.g. `example.com` → `api.example.com`), built on
+ * Hono's `cors` + cwip's `compileOriginMatcher` rather than a per-app allow-list
+ * reimplementation.
+ *
+ * The one-line configuration is `siteDomain`: it allows the https apex AND every
+ * subdomain (`siteOriginRules`), so standing up a new subdomain can never break
+ * CORS again. `origins` adds exact origins / `*.domain` wildcards / RegExps on
+ * top (dev Vite ports, a partner origin). Responses to allowed origins echo the
+ * origin with `Access-Control-Allow-Credentials: true` (cookie-auth apps);
+ * disallowed origins get NO CORS headers, which is the browser-visible rejection.
+ */
+export interface CorsOpts {
+  /**
+   * The site's apex domain (`'example.com'`) — allows `https://example.com` and
+   * `https://<any-subdomain>.example.com` in one rule.
+   */
+  siteDomain?: string;
+  /** Additional origin rules: exact, `*.domain.tld` wildcard, or RegExp. */
+  origins?: OriginRule[];
+  /** Send `Access-Control-Allow-Credentials: true` (default `true` — cookie auth). */
+  credentials?: boolean;
+  /** Called with each rejected `Origin` (for logging/metrics). */
+  onReject?: (origin: string) => void;
+}
+
+/** Build the Hono middleware from {@link CorsOpts}. Compiles the matcher once. */
+export const corsAllowlist = (opts: CorsOpts): MiddlewareHandler => {
+  const rules: OriginRule[] = [
+    ...(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: Record<string, string | undefined> = process.env,
+): CorsOpts | undefined => {
+  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/src/server/middleware/errorEnvelope.ts

@@ -0,0 +1,38 @@
+import type { ErrorHandler } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import type { CursedbeltEnv } from '../context';
+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: ErrorHandler<CursedbeltEnv> = (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) as ContentfulStatusCode);
+};

package/src/server/middleware/index.ts

@@ -0,0 +1,19 @@
+// The cross-cutting cursedbelt server middleware set.
+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/src/server/middleware/localOrigin.spec.ts

@@ -0,0 +1,168 @@
+// Both halves matter equally here. A guard that refuses the attack but also
+// refuses curl would be reverted within a day, so the 'legitimate callers'
+// block is not padding — it is the reason this can ship without a login.
+
+import { describe, expect, test } from 'bun:test';
+import { crossOriginRefusal } from './localOrigin';
+
+function req(headers: Record<string, string>, url = 'http://127.0.0.1:4747/api/overview'): Request {
+	return new Request(url, { headers });
+}
+
+describe('the browser attacks that loopback binding does not stop', () => {
+	test('a cross-site POST from a website is refused (the measured CSRF vector)', () => {
+		// Verified by hand against the live daemon on 2026-08-06: this exact shape
+		// was accepted, parsed and reached field validation. `text/plain` is a
+		// SIMPLE content type, so no CORS preflight is required and the request
+		// fires; req.json() then parses it anyway.
+		const refusal = crossOriginRefusal(
+			req({
+				host: '127.0.0.1:4747',
+				origin: 'https://evil.example.com',
+				'sec-fetch-site': 'cross-site',
+				'content-type': 'text/plain',
+			}),
+		);
+		expect(refusal).toContain('evil.example.com');
+	});
+
+	test('a cross-origin Origin alone is enough — Sec-Fetch-Site may be absent', () => {
+		expect(
+			crossOriginRefusal(req({ host: '127.0.0.1:4747', origin: 'https://evil.example.com' })),
+		).toContain('local-only');
+	});
+
+	test('a cross-site GET navigation with NO Origin is still refused', () => {
+		// A cross-site GET omits Origin, so Sec-Fetch-Site is the only signal.
+		expect(
+			crossOriginRefusal(req({ host: '127.0.0.1:4747', 'sec-fetch-site': 'cross-site' })),
+		).toContain('does not serve other sites');
+	});
+
+	test('DNS rebinding is refused: a non-loopback Host cannot reach the machine API', () => {
+		// The attack that would otherwise make an attacker domain SAME-origin and
+		// lift the opaque-response limit, turning every GET into exfiltration.
+		expect(crossOriginRefusal(req({ host: 'attacker.example.com' }))).toContain('not a loopback');
+	});
+
+	test('Host is judged before Origin — a rebound host must not look same-origin', () => {
+		const refusal = crossOriginRefusal(
+			req({ host: 'rebind.example.com', origin: 'http://rebind.example.com' }),
+		);
+		expect(refusal).toContain('Host');
+	});
+
+	test('an unparseable Origin is refused rather than ignored', () => {
+		expect(crossOriginRefusal(req({ host: '127.0.0.1:4747', origin: '!!!' }))).toContain(
+			'unparseable',
+		);
+	});
+});
+
+describe('every legitimate local caller still passes', () => {
+	test('curl / a bun fetch / the server-side machine proxy — no browser headers at all', () => {
+		expect(crossOriginRefusal(req({ host: '127.0.0.1:4747' }))).toBeNull();
+	});
+
+	test('no Host header at all (HTTP/1.0, some local clients)', () => {
+		expect(crossOriginRefusal(req({}))).toBeNull();
+	});
+
+	test('the status page served from :4747 itself — same-origin', () => {
+		expect(
+			crossOriginRefusal(
+				req({
+					host: '127.0.0.1:4747',
+					origin: 'http://127.0.0.1:4747',
+					'sec-fetch-site': 'same-origin',
+				}),
+			),
+		).toBeNull();
+	});
+
+	test('a loopback SPA on ANOTHER port — cross-origin but same-site, and legitimate', () => {
+		// The wall is 'not this machine', not 'not another port'. The station SPA
+		// on :3333 and the vault UI are exactly this shape.
+		expect(
+			crossOriginRefusal(
+				req({
+					host: '127.0.0.1:4747',
+					origin: 'http://127.0.0.1:3333',
+					'sec-fetch-site': 'same-site',
+				}),
+			),
+		).toBeNull();
+	});
+
+	test('localhost and IPv6 loopback are the same machine', () => {
+		expect(crossOriginRefusal(req({ host: 'localhost:4747' }))).toBeNull();
+		expect(crossOriginRefusal(req({ host: '[::1]:4747' }))).toBeNull();
+		expect(
+			crossOriginRefusal(req({ host: '127.0.0.1:4747', origin: 'http://localhost:3333' })),
+		).toBeNull();
+	});
+
+	test('all of 127.0.0.0/8 is loopback, not just 127.0.0.1', () => {
+		expect(crossOriginRefusal(req({ host: '127.0.0.53:4747' }))).toBeNull();
+	});
+
+	test('Origin: "null" (a sandboxed iframe / file://) is not treated as a hostname', () => {
+		// It carries no origin information, so the Sec-Fetch-Site check decides.
+		expect(crossOriginRefusal(req({ host: '127.0.0.1:4747', origin: 'null' }))).toBeNull();
+		expect(
+			crossOriginRefusal(
+				req({ host: '127.0.0.1:4747', origin: 'null', 'sec-fetch-site': 'cross-site' }),
+			),
+		).toContain('does not serve other sites');
+	});
+
+	test('a host that merely CONTAINS a loopback name is not loopback', () => {
+		expect(crossOriginRefusal(req({ host: 'localhost.evil.example.com' }))).toContain(
+			'not a loopback',
+		);
+		expect(crossOriginRefusal(req({ host: '127.0.0.1.evil.example.com' }))).toContain(
+			'not a loopback',
+		);
+	});
+});
+
+describe('the label appears in the refusal, so a log line names the daemon', () => {
+	test('each daemon says which surface refused', () => {
+		// Three loopback daemons share this guard (station :4747, orch :3021,
+		// cloud :3022) and the owner reads these refusals in a log with no other
+		// context about which one spoke.
+		expect(
+			crossOriginRefusal(req({ host: '127.0.0.1:3021', origin: 'https://evil.example.com' }), 'the orchestrator engine'),
+		).toContain('the orchestrator engine');
+		expect(crossOriginRefusal(req({ host: 'attacker.example.com' }), 'the cloud dashboard')).toContain(
+			'the cloud dashboard',
+		);
+	});
+});
+
+describe('allowHosts — a local host-header proxy name', () => {
+	test('an allowed extra name passes as Host AND as Origin', () => {
+		// The dev gateway (:3300) serves the satellites under `<app>.localhost`.
+		const opts = { label: 'the cloud dashboard', allowHosts: ['cloud.localhost'] };
+		expect(crossOriginRefusal(req({ host: 'cloud.localhost:3300' }), opts)).toBeNull();
+		expect(
+			crossOriginRefusal(req({ host: 'cloud.localhost', origin: 'http://cloud.localhost' }), opts),
+		).toBeNull();
+	});
+
+	test('it is matched WHOLE — a suffix is still not loopback', () => {
+		// The trap the base rule already avoids, re-pinned for the opt-in path:
+		// allowing `cloud.localhost` must not allow `cloud.localhost.evil.com`.
+		expect(
+			crossOriginRefusal(req({ host: 'cloud.localhost.evil.example.com' }), {
+				allowHosts: ['cloud.localhost'],
+			}),
+		).toContain('not a loopback');
+	});
+
+	test('an unlisted name is refused even when another is allowed', () => {
+		expect(crossOriginRefusal(req({ host: 'orch.localhost' }), { allowHosts: ['cloud.localhost'] })).toContain(
+			'not a loopback',
+		);
+	});
+});