cursedbelt-server 1.0.0

package/dist/server/middleware/zValidator.js

@@ -0,0 +1,57 @@
+import { validationEnvelope } from '../errors';
+/**
+ * Read the value a target validates against. The body targets (`json`/`form`) prefer
+ * the ctgr-decoded body so a tunnelled mutation validates its real payload; the
+ * URL-bound targets (`query`/`param`) are never tunnelled (GETs go direct) and read
+ * from the live request. A query object collapses single-valued keys to a string so
+ * `z.string()`/`z.coerce.number()` field schemas see a scalar (repeated keys stay an
+ * array) — matching Hono's own validator semantics.
+ */
+async function readTarget(c, target) {
+    if (target === 'json' || target === 'form') {
+        const decoded = c.get('ctgrDecoded');
+        if (decoded)
+            return decoded.body;
+        if (target === 'json')
+            return c.req.json().catch(() => undefined);
+        return c.req.parseBody();
+    }
+    if (target === 'param')
+        return c.req.param();
+    return Object.fromEntries(Object.entries(c.req.queries()).map(([key, values]) => values.length === 1 ? [key, values[0]] : [key, values]));
+}
+/**
+ * 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 function zValidator(schema, target = 'json') {
+    const handler = async (c, next) => {
+        const raw = await readTarget(c, target);
+        const result = schema.safeParse(raw);
+        if (!result.success) {
+            return c.json(validationEnvelope(result.error), 400);
+        }
+        // Expose the parsed value both ways (typed `c.req.valid` + convenience getter).
+        c.req.addValidatedData(target, result.data);
+        c.set('validatedBody', result.data);
+        await next();
+    };
+    // The body is written against the concrete `CursedbeltEnv` (so the ctgr/validatedBody
+    // accessors type-check); the public signature is the generic, schema-typed
+    // MiddlewareHandler that flows `c.req.valid(target)` into the handler. Hono's Context
+    // is invariant in its Env, so this widening goes through `unknown` — the same cast
+    // a hand-rolled typed middleware (e.g. @hono/zod-validator) performs.
+    return handler;
+}

package/dist/server/migration/runner.d.ts

@@ -0,0 +1,42 @@
+import type { Database } from 'bun:sqlite';
+import type { Migration } from './types';
+/**
+ * The versioned SQLite migration runner — a tiny `_migrations`-sentinel runner, NOT
+ * a schema-first ORM. It replaces the old scattered guarded-`ALTER` /
+ * `addColumnIfMissing` pattern with ordered, once-only migrations whose names are
+ * recorded once applied. Business tables stay raw (`db.query` + `data JSON`); only
+ * the *plumbing* tables get Kysely types (see `../db/kysely`).
+ */
+/**
+ * Apply the recommended connection PRAGMAs. **Call this BEFORE {@link runMigrations}
+ * and OUTSIDE any transaction** — `PRAGMA foreign_keys` is silently ignored inside a
+ * transaction, and the runner wraps each migration in one. Idempotent; safe on boot.
+ *
+ * This is now a straight alias of cwip's `applyCcPragmas`: the CC storage tier pins
+ * ONE pragma profile monorepo-wide (`CC_PRAGMAS` — WAL + NORMAL + busy_timeout 5000 +
+ * foreign_keys ON + wal_autocheckpoint 1000), and the belt-local copy that used to
+ * live here was the second implementation the spec forbids. The per-pragma
+ * `PragmaOptions` overrides are gone with it — a handle that drifts from the profile
+ * is a `pragma-drift` violation, not a configuration choice.
+ *
+ * @deprecated Prefer cwip's `assertCcPragmas`, which additionally verifies each
+ * pragma took and installs the WAL transaction-lifetime guard.
+ */
+export declare function applyRecommendedPragmas(db: Database): void;
+/**
+ * Run every pending migration exactly once, in array order, each inside its own
+ * transaction, recording its `name` in `_migrations`. Returns the names actually
+ * applied this call (empty when already up to date — re-running is a no-op).
+ *
+ * Set the connection PRAGMAs first via {@link applyRecommendedPragmas} (foreign-key
+ * enforcement cannot be turned on inside the per-migration transaction).
+ */
+export declare function runMigrations(db: Database, migrations: readonly Migration[]): string[];
+/** Does `table` have a column named `column`? (via `PRAGMA table_info`). */
+export declare function columnExists(db: Database, table: string, column: string): boolean;
+/**
+ * Add a column if it is missing (idempotent). Returns true when it was added. A
+ * migration helper for the rare evolve-in-place case; the canonical schema is built
+ * fresh by `0001_initial`, so new migrations normally `CREATE` rather than `ALTER`.
+ */
+export declare function addColumnIfMissing(db: Database, table: string, column: string, ddl: string): boolean;

package/dist/server/migration/runner.js

@@ -0,0 +1,70 @@
+import { applyCcPragmas } from 'cwip/sqlite';
+/**
+ * The versioned SQLite migration runner — a tiny `_migrations`-sentinel runner, NOT
+ * a schema-first ORM. It replaces the old scattered guarded-`ALTER` /
+ * `addColumnIfMissing` pattern with ordered, once-only migrations whose names are
+ * recorded once applied. Business tables stay raw (`db.query` + `data JSON`); only
+ * the *plumbing* tables get Kysely types (see `../db/kysely`).
+ */
+/**
+ * Apply the recommended connection PRAGMAs. **Call this BEFORE {@link runMigrations}
+ * and OUTSIDE any transaction** — `PRAGMA foreign_keys` is silently ignored inside a
+ * transaction, and the runner wraps each migration in one. Idempotent; safe on boot.
+ *
+ * This is now a straight alias of cwip's `applyCcPragmas`: the CC storage tier pins
+ * ONE pragma profile monorepo-wide (`CC_PRAGMAS` — WAL + NORMAL + busy_timeout 5000 +
+ * foreign_keys ON + wal_autocheckpoint 1000), and the belt-local copy that used to
+ * live here was the second implementation the spec forbids. The per-pragma
+ * `PragmaOptions` overrides are gone with it — a handle that drifts from the profile
+ * is a `pragma-drift` violation, not a configuration choice.
+ *
+ * @deprecated Prefer cwip's `assertCcPragmas`, which additionally verifies each
+ * pragma took and installs the WAL transaction-lifetime guard.
+ */
+export function applyRecommendedPragmas(db) {
+    applyCcPragmas(db);
+}
+/**
+ * Run every pending migration exactly once, in array order, each inside its own
+ * transaction, recording its `name` in `_migrations`. Returns the names actually
+ * applied this call (empty when already up to date — re-running is a no-op).
+ *
+ * Set the connection PRAGMAs first via {@link applyRecommendedPragmas} (foreign-key
+ * enforcement cannot be turned on inside the per-migration transaction).
+ */
+export function runMigrations(db, migrations) {
+    db.run('CREATE TABLE IF NOT EXISTS _migrations (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)');
+    const applied = new Set(db.query('SELECT name FROM _migrations').all().map((r) => r.name));
+    const insert = db.prepare('INSERT INTO _migrations (name, applied_at) VALUES (?, ?)');
+    const ran = [];
+    for (const m of migrations) {
+        if (applied.has(m.name))
+            continue;
+        const apply = db.transaction(() => {
+            m.up(db);
+            insert.run(m.name, new Date().toISOString());
+        });
+        apply();
+        ran.push(m.name);
+    }
+    return ran;
+}
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** Does `table` have a column named `column`? (via `PRAGMA table_info`). */
+export function columnExists(db, table, column) {
+    const rows = db.query(`PRAGMA table_info(${quoteIdent(table)})`).all();
+    return rows.some((r) => r.name === column);
+}
+/**
+ * Add a column if it is missing (idempotent). Returns true when it was added. A
+ * migration helper for the rare evolve-in-place case; the canonical schema is built
+ * fresh by `0001_initial`, so new migrations normally `CREATE` rather than `ALTER`.
+ */
+export function addColumnIfMissing(db, table, column, ddl) {
+    if (columnExists(db, table, column))
+        return false;
+    db.run(`ALTER TABLE ${quoteIdent(table)} ADD COLUMN ${quoteIdent(column)} ${ddl}`);
+    return true;
+}

package/dist/server/migration/types.d.ts

@@ -0,0 +1,16 @@
+import type { Database } from 'bun:sqlite';
+/**
+ * One ordered, immutable schema migration. `name` is recorded in the `_migrations`
+ * sentinel once applied, so a migration's `up()` runs exactly once across the life
+ * of a database. Corrections land as NEW migrations — never edit a shipped one, and
+ * never rename one that has been applied (the name is its identity).
+ *
+ * `up()` runs inside the runner's per-migration transaction; throw to abort + roll
+ * back that migration (the sentinel row is not written, so it retries next boot).
+ */
+export interface Migration {
+    /** Unique, lexically-ordered name, e.g. `0001_initial`. Immutable once applied. */
+    readonly name: string;
+    /** Apply the migration. Runs inside the runner's transaction. */
+    up(db: Database): void;
+}

package/dist/server/migration/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/net/outboundGuard.d.ts

@@ -0,0 +1,30 @@
+export declare const OUTBOUND_URL_BLOCKED = "OUTBOUND_URL_BLOCKED";
+export interface OutboundGuardOptions {
+    /**
+     * Exact hostnames (case-insensitive) explicitly permitted even if they would
+     * otherwise be blocked — for a deliberately-configured internal integration.
+     * Empty by default: nothing internal is reachable unless a host opts in.
+     */
+    allowHosts?: readonly string[];
+    /** Permitted URL schemes. Default `['http:', 'https:']`. */
+    allowSchemes?: readonly string[];
+}
+/**
+ * Structural SSRF guard: parse `rawUrl`, enforce scheme, reject credentials, and
+ * refuse any host that is a private/loopback/link-local/reserved IP literal (in
+ * any encoding) or a well-known internal hostname. Returns the parsed URL.
+ *
+ * @throws {AppError} `OUTBOUND_URL_BLOCKED` on any violation.
+ */
+export declare const assertPublicOutboundUrl: (rawUrl: string, options?: OutboundGuardOptions) => URL;
+/**
+ * DNS-aware SSRF guard: the structural checks of {@link assertPublicOutboundUrl}
+ * PLUS a resolution pass — every address the hostname resolves to is re-checked,
+ * so a public name pointing at a private IP is refused. Still racy against an
+ * attacker who rebinds between this lookup and the actual connect, which is why
+ * the SaaS profile must also enforce network-layer egress; but it closes the
+ * naive `evil.example → 169.254.169.254` vector the structural pass cannot see.
+ *
+ * @throws {AppError} `OUTBOUND_URL_BLOCKED` on any violation.
+ */
+export declare const assertResolvedPublicUrl: (rawUrl: string, options?: OutboundGuardOptions) => Promise<URL>;

package/dist/server/net/outboundGuard.js

@@ -0,0 +1,199 @@
+/**
+ * SSRF guard for server-side outbound HTTP (03 §2.4 H-4 adjudication).
+ *
+ * The Request Builder send (`/api/system/http`) is server-side BY DESIGN: the
+ * pinned CSP's `connect-src` would block a browser-side request to an arbitrary
+ * host, so the send is performed by the server to keep the tool working without
+ * widening a single header. But moving the send server-side creates a
+ * server-side request forgery surface the CSP argument never addressed — an
+ * authenticated caller can now make the SERVER fetch:
+ *
+ *   - `http://169.254.169.254/latest/meta-data/…`  → cloud metadata → credentials
+ *   - `http://localhost:4747/…` / `http://127.0.0.1` → the station and sibling apps
+ *   - `http://10.x` / `172.16.x` / `192.168.x`      → anything on the private network
+ *   - `http://<internal-rds-or-redis-or-admin>`      → internal-only services
+ *
+ * This module is the boundary that refuses those. It is fail-CLOSED and lives in
+ * the framework (not in a leaf `sendHttp` impl) so no implementation can forget
+ * it: the mixin runs {@link assertPublicOutboundUrl} on the caller-supplied URL
+ * BEFORE any impl sees it.
+ *
+ * Two layers, because neither alone is sufficient:
+ *   1. {@link assertPublicOutboundUrl} — synchronous, structural: scheme +
+ *      credential + literal-IP-range + dangerous-hostname checks. Catches every
+ *      IP-literal vector (including the decimal/hex/octal encodings that
+ *      `new URL()` preserves and `fetch` still resolves) and the well-known
+ *      internal hostnames. This is what the request path calls on every send.
+ *   2. {@link assertResolvedPublicUrl} — async, DNS-aware: additionally resolves
+ *      the hostname and re-checks every resolved address, which is the only
+ *      defense against a public name that resolves to a private IP (DNS
+ *      rebinding). Opt-in for impls that can afford the lookup; the SaaS profile
+ *      must ALSO enforce egress at the network layer, since even this races a
+ *      rebinding attacker between resolve and connect.
+ */
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+import { AppError } from '../errors';
+export const OUTBOUND_URL_BLOCKED = 'OUTBOUND_URL_BLOCKED';
+const blocked = (reason, context) => new AppError(`Outbound request refused: ${reason}.`, {
+    code: OUTBOUND_URL_BLOCKED,
+    status: 400,
+    category: 'security',
+    // Deliberately terse context — do not echo internal topology back.
+    context,
+});
+/** Hostnames and suffixes that always resolve to a non-public / internal target. */
+const BLOCKED_HOST_EXACT = new Set(['localhost', 'metadata.google.internal', 'metadata']);
+const BLOCKED_HOST_SUFFIXES = ['.localhost', '.local', '.internal', '.intranet', '.cluster.local', '.svc'];
+/**
+ * Parse a hostname into an IPv4 the way a permissive resolver would, covering
+ * the encodings SSRF filters classically miss: dotted-decimal (`127.0.0.1`), a
+ * bare 32-bit integer (`2130706433`), and hex (`0x7f000001`). Returns the four
+ * octets, or `null` when the host is not an IPv4 literal in any of these forms.
+ */
+const looseIpv4Octets = (host) => {
+    if (isIP(host) === 4) {
+        const parts = host.split('.').map(Number);
+        return [parts[0], parts[1], parts[2], parts[3]];
+    }
+    // Bare integer or hex integer → a single 32-bit value.
+    const asInt = /^0x[0-9a-f]+$/i.test(host)
+        ? Number.parseInt(host, 16)
+        : /^[0-9]+$/.test(host)
+            ? Number.parseInt(host, 10)
+            : Number.NaN;
+    if (Number.isInteger(asInt) && asInt >= 0 && asInt <= 0xffffffff)
+        return [(asInt >>> 24) & 0xff, (asInt >>> 16) & 0xff, (asInt >>> 8) & 0xff, asInt & 0xff];
+    return null;
+};
+/** Whether an IPv4 (as octets) is in a private, loopback, link-local or reserved range. */
+const isBlockedIpv4 = ([a, b]) => {
+    if (a === 0 || a === 10 || a === 127)
+        return true; // this-host, private, loopback
+    if (a === 169 && b === 254)
+        return true; // link-local — INCLUDES 169.254.169.254 metadata
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // private
+    if (a === 192 && b === 168)
+        return true; // private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // CGNAT (100.64/10)
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // benchmarking
+    if (a >= 224)
+        return true; // multicast (224/4) + reserved (240/4) + 255.255.255.255
+    return false;
+};
+/**
+ * Extract the embedded IPv4 of an IPv4-mapped IPv6 address. `new URL` normalizes
+ * `::ffff:127.0.0.1` to the HEX form `::ffff:7f00:1`, so both the dotted and the
+ * two-hextet forms have to be handled.
+ */
+const mappedV4Octets = (head) => {
+    const rest = /^::ffff:(.+)$/i.exec(head)?.[1];
+    if (!rest)
+        return null;
+    if (rest.includes('.'))
+        return looseIpv4Octets(rest);
+    const groups = rest.split(':');
+    if (groups.length !== 2)
+        return null;
+    const hi = Number.parseInt(groups[0], 16);
+    const lo = Number.parseInt(groups[1], 16);
+    if (!Number.isInteger(hi) || !Number.isInteger(lo))
+        return null;
+    return [(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff];
+};
+/** Whether an IPv6 literal (already `net.isIP`-classified) is non-public. */
+const isBlockedIpv6 = (raw) => {
+    const head = raw.toLowerCase().replace(/^\[|\]$/g, '');
+    if (head === '::1' || head === '::')
+        return true; // loopback, unspecified
+    const mapped = mappedV4Octets(head);
+    if (mapped && isBlockedIpv4(mapped))
+        return true; // IPv4-mapped (`::ffff:…`)
+    // fe80::/10 link-local (fe80–febf) and fec0::/10 deprecated site-local (fec0–feff).
+    if (/^fe[89ab]/.test(head) || /^fe[c-f]/.test(head))
+        return true;
+    if (head.startsWith('fc') || head.startsWith('fd'))
+        return true; // fc00::/7 unique-local (incl. fd00:ec2::254 metadata)
+    if (head.startsWith('ff'))
+        return true; // ff00::/8 multicast
+    return false;
+};
+const isBlockedHostname = (host) => {
+    if (BLOCKED_HOST_EXACT.has(host))
+        return true;
+    return BLOCKED_HOST_SUFFIXES.some((suffix) => host.endsWith(suffix));
+};
+/**
+ * Structural SSRF guard: parse `rawUrl`, enforce scheme, reject credentials, and
+ * refuse any host that is a private/loopback/link-local/reserved IP literal (in
+ * any encoding) or a well-known internal hostname. Returns the parsed URL.
+ *
+ * @throws {AppError} `OUTBOUND_URL_BLOCKED` on any violation.
+ */
+export const assertPublicOutboundUrl = (rawUrl, options = {}) => {
+    const allowSchemes = options.allowSchemes ?? ['http:', 'https:'];
+    const allowHosts = new Set((options.allowHosts ?? []).map((h) => h.toLowerCase()));
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw blocked('not a valid absolute URL', {});
+    }
+    if (!allowSchemes.includes(url.protocol))
+        throw blocked(`scheme '${url.protocol}' is not allowed`, { scheme: url.protocol });
+    // Credentials in the URL are a redirect/parsing-confusion vector and never
+    // legitimate for a tool send.
+    if (url.username !== '' || url.password !== '')
+        throw blocked('credentials in URL are not allowed', {});
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (allowHosts.has(host))
+        return url; // explicit host opt-in bypasses the blocks
+    const v4 = looseIpv4Octets(host);
+    if (v4) {
+        if (isBlockedIpv4(v4))
+            throw blocked('target resolves to a private or reserved address', { host });
+        return url;
+    }
+    if (isIP(host) === 6) {
+        if (isBlockedIpv6(host))
+            throw blocked('target resolves to a private or reserved address', { host });
+        return url;
+    }
+    if (isBlockedHostname(host))
+        throw blocked('target host is internal-only', { host });
+    return url;
+};
+/**
+ * DNS-aware SSRF guard: the structural checks of {@link assertPublicOutboundUrl}
+ * PLUS a resolution pass — every address the hostname resolves to is re-checked,
+ * so a public name pointing at a private IP is refused. Still racy against an
+ * attacker who rebinds between this lookup and the actual connect, which is why
+ * the SaaS profile must also enforce network-layer egress; but it closes the
+ * naive `evil.example → 169.254.169.254` vector the structural pass cannot see.
+ *
+ * @throws {AppError} `OUTBOUND_URL_BLOCKED` on any violation.
+ */
+export const assertResolvedPublicUrl = async (rawUrl, options = {}) => {
+    const url = assertPublicOutboundUrl(rawUrl, options);
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    // A literal IP or an explicitly-allowed host needs no resolution recheck.
+    if (isIP(host) !== 0 || looseIpv4Octets(host) || (options.allowHosts ?? []).some((h) => h.toLowerCase() === host))
+        return url;
+    let addresses;
+    try {
+        addresses = await lookup(host, { all: true });
+    }
+    catch {
+        throw blocked('target hostname did not resolve', { host });
+    }
+    for (const { address } of addresses) {
+        const octets = looseIpv4Octets(address);
+        if (octets ? isBlockedIpv4(octets) : isIP(address) === 6 && isBlockedIpv6(address))
+            throw blocked('target hostname resolves to a private or reserved address', { host });
+    }
+    return url;
+};

package/dist/server/notifications/hub.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Live delivery for the notification center — the half that makes a bell badge
+ * change without anybody clicking anything.
+ *
+ * The center already has the seam (`NotificationSink`); what was missing was a
+ * transport behind it. This is that transport, as **SSE** rather than a
+ * WebSocket, and the reason is the shape of the traffic: notifications are
+ * server→client only, they must survive a laptop lid closing, and a browser
+ * reconnects an `EventSource` by itself. A WebSocket would mean writing the
+ * reconnect loop, the heartbeat and the backoff that `EventSource` already has
+ * — and `cursedbelt-server/ws` remains the right answer for anything the client
+ * needs to send back up.
+ *
+ * 🔴 **A hub is a cache of who is listening, never a queue.** A notification is
+ * already durable (it is a row) before a sink is called, so a subscriber that
+ * is asleep, disconnected or behind a proxy that ate the stream loses nothing:
+ * the next list/poll returns the same row. That is why every emit here is
+ * fire-and-forget and a failing subscriber is dropped rather than retried — the
+ * poll transport in `cursedbelt/react/notifications` is the backstop, and it is
+ * not optional.
+ */
+import type { AppNotification, NotificationSink } from "cwip/notifications";
+/** What a subscriber receives. `unread` rides alongside so a bell badge never
+ *  has to make a second request to learn its own number. */
+export type NotificationHubEvent = {
+    kind: "notification";
+    notification: AppNotification;
+} | {
+    kind: "unread";
+    userId: string;
+    count: number;
+};
+export type NotificationHubListener = (event: NotificationHubEvent) => void;
+export interface NotificationHubOptions {
+    /**
+     * Comment-line heartbeat cadence, in ms. Default 25s — under the 30s idle
+     * timeout nginx and Cloudflare both default to, which is what silently kills
+     * an otherwise healthy SSE stream. 0 disables it (tests).
+     */
+    heartbeatMs?: number;
+    /**
+     * Max concurrent streams per user. Default 8. A tab is a stream, and a
+     * browser left open for a week accumulates them; without a cap one person's
+     * tab habit is an unbounded server-side array.
+     */
+    maxStreamsPerUser?: number;
+    /** Reported when a listener throws. Never rethrown — see the module doc. */
+    onError?: (error: unknown, context: string) => void;
+}
+export interface NotificationHub {
+    /**
+     * Hand this to `createNotificationCenter({ sink })`. Every `notify*` then
+     * reaches the connected tabs of exactly the addressed user.
+     */
+    readonly sink: NotificationSink;
+    /** Register a listener for one user's events. Returns an unsubscribe fn. */
+    subscribe(userId: string, listener: NotificationHubListener): () => void;
+    /** An SSE `Response` for one user — the thing a route returns. */
+    stream(userId: string, options?: {
+        signal?: AbortSignal;
+    }): Response;
+    /** How many live subscribers a user has (all users when omitted). */
+    subscriberCount(userId?: string): number;
+    /** Drop every subscriber and stop every heartbeat (shutdown, and tests). */
+    close(): void;
+}
+export declare function createNotificationHub(options?: NotificationHubOptions): NotificationHub;

package/dist/server/notifications/hub.js

@@ -0,0 +1,187 @@
+const SSE_HEADERS = {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-store, no-transform",
+    connection: "keep-alive",
+    // nginx buffers proxied responses by default, which turns a live stream into
+    // one delivered when it ends. The fleet's box is behind nginx; this is the
+    // header that opts out, and it is inert everywhere else.
+    "x-accel-buffering": "no",
+};
+const encodeEvent = (event) => {
+    const name = event.kind;
+    const data = event.kind === "notification" ? event.notification : { count: event.count };
+    return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
+};
+export function createNotificationHub(options = {}) {
+    const heartbeatMs = options.heartbeatMs ?? 25_000;
+    const maxStreamsPerUser = options.maxStreamsPerUser ?? 8;
+    const onError = options.onError ?? (() => { });
+    /** userId → listeners. An empty set is deleted, so the map never grows with
+     *  the user table — only with who is actually connected right now. */
+    const listeners = new Map();
+    let closed = false;
+    const emit = (userId, event) => {
+        const set = listeners.get(userId);
+        if (!set)
+            return;
+        // Snapshot: a listener may unsubscribe itself while being called (a
+        // stream that has just been cancelled does exactly that).
+        for (const listener of [...set]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                onError(error, "notificationHub.listener");
+                set.delete(listener);
+            }
+        }
+        if (set.size === 0)
+            listeners.delete(userId);
+    };
+    const subscribe = (userId, listener) => {
+        if (closed)
+            return () => { };
+        let set = listeners.get(userId);
+        if (!set) {
+            set = new Set();
+            listeners.set(userId, set);
+        }
+        // Oldest-first eviction: the tab that has been open longest is the one
+        // least likely to be looked at, and dropping it costs nothing (the poll
+        // backstop still runs there).
+        while (set.size >= maxStreamsPerUser) {
+            const oldest = set.values().next().value;
+            if (!oldest)
+                break;
+            set.delete(oldest);
+            try {
+                oldest({ kind: "unread", userId, count: -1 });
+            }
+            catch (error) {
+                onError(error, "notificationHub.evict");
+            }
+        }
+        set.add(listener);
+        return () => {
+            const current = listeners.get(userId);
+            if (!current)
+                return;
+            current.delete(listener);
+            if (current.size === 0)
+                listeners.delete(userId);
+        };
+    };
+    return {
+        sink: {
+            onNotification(notification) {
+                emit(notification.userId, { kind: "notification", notification });
+            },
+            onUnread(userId, count) {
+                emit(userId, { kind: "unread", userId, count });
+            },
+        },
+        subscribe,
+        stream(userId, streamOptions = {}) {
+            let unsubscribe;
+            let heartbeat;
+            let onAbort;
+            const encoder = new TextEncoder();
+            const body = new ReadableStream({
+                start(controller) {
+                    let live = true;
+                    const send = (chunk) => {
+                        if (!live)
+                            return;
+                        try {
+                            controller.enqueue(encoder.encode(chunk));
+                        }
+                        catch (error) {
+                            // The peer went away between our check and the write. Tear the
+                            // subscription down rather than logging once per event forever.
+                            live = false;
+                            onError(error, "notificationHub.enqueue");
+                            teardown();
+                        }
+                    };
+                    const teardown = () => {
+                        live = false;
+                        unsubscribe?.();
+                        unsubscribe = undefined;
+                        if (heartbeat)
+                            clearInterval(heartbeat);
+                        heartbeat = undefined;
+                        if (onAbort)
+                            streamOptions.signal?.removeEventListener("abort", onAbort);
+                        onAbort = undefined;
+                    };
+                    // A comment line first: it flushes proxy buffers and tells the
+                    // client the stream is genuinely open before anything happens.
+                    send(": connected\n\n");
+                    unsubscribe = subscribe(userId, (event) => {
+                        // The eviction poke (count -1) is not a real event — it means
+                        // "this stream lost its slot", so close rather than report it.
+                        if (event.kind === "unread" && event.count < 0) {
+                            teardown();
+                            try {
+                                controller.close();
+                            }
+                            catch {
+                                /* already closed */
+                            }
+                            return;
+                        }
+                        send(encodeEvent(event));
+                    });
+                    if (heartbeatMs > 0) {
+                        heartbeat = setInterval(() => send(": ping\n\n"), heartbeatMs);
+                        // Never hold the process open for a heartbeat — a satellite that
+                        // is shutting down must not wait out someone's open tab.
+                        heartbeat.unref?.();
+                    }
+                    if (streamOptions.signal) {
+                        onAbort = () => {
+                            teardown();
+                            try {
+                                controller.close();
+                            }
+                            catch {
+                                /* already closed */
+                            }
+                        };
+                        streamOptions.signal.addEventListener("abort", onAbort, { once: true });
+                    }
+                },
+                cancel() {
+                    unsubscribe?.();
+                    unsubscribe = undefined;
+                    if (heartbeat)
+                        clearInterval(heartbeat);
+                    heartbeat = undefined;
+                },
+            });
+            return new Response(body, { status: 200, headers: SSE_HEADERS });
+        },
+        subscriberCount(userId) {
+            if (userId !== undefined)
+                return listeners.get(userId)?.size ?? 0;
+            let total = 0;
+            for (const set of listeners.values())
+                total += set.size;
+            return total;
+        },
+        close() {
+            closed = true;
+            for (const [userId, set] of [...listeners]) {
+                for (const listener of [...set]) {
+                    try {
+                        listener({ kind: "unread", userId, count: -1 });
+                    }
+                    catch (error) {
+                        onError(error, "notificationHub.close");
+                    }
+                }
+            }
+            listeners.clear();
+        },
+    };
+}