cursedbelt-server 1.0.0

package/src/server/net/outboundGuard.ts

@@ -0,0 +1,205 @@
+/**
+ * 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';
+
+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[];
+}
+
+const blocked = (reason: string, context: Record<string, unknown>): AppError =>
+  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: string): [number, number, number, number] | null => {
+  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]: [number, number, number, number]): boolean => {
+  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: string): [number, number, number, number] | null => {
+  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: string): boolean => {
+  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: string): boolean => {
+  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: string, options: OutboundGuardOptions = {}): URL => {
+  const allowSchemes = options.allowSchemes ?? ['http:', 'https:'];
+  const allowHosts = new Set((options.allowHosts ?? []).map((h) => h.toLowerCase()));
+
+  let url: 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: string, options: OutboundGuardOptions = {}): Promise<URL> => {
+  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: { address: string; family: number }[];
+  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/src/server/notifications/hub.ts

@@ -0,0 +1,245 @@
+/**
+ * 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;
+}
+
+const SSE_HEADERS: Record<string, string> = {
+	"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: NotificationHubEvent): string => {
+	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: NotificationHubOptions = {}): NotificationHub {
+	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<string, Set<NotificationHubListener>>();
+	let closed = false;
+
+	const emit = (userId: string, event: NotificationHubEvent): void => {
+		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: NotificationHub["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: (() => void) | undefined;
+			let heartbeat: ReturnType<typeof setInterval> | undefined;
+			let onAbort: (() => void) | undefined;
+			const encoder = new TextEncoder();
+
+			const body = new ReadableStream<Uint8Array>({
+				start(controller) {
+					let live = true;
+					const send = (chunk: string) => {
+						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 as unknown as { unref?: () => void }).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();
+		},
+	};
+}

package/src/server/notifications/index.ts

@@ -0,0 +1,77 @@
+/**
+ * `cursedbelt-server/notifications` — the SERVER half of the fleet's one
+ * notification primitive.
+ *
+ * ── What was already here, and what was missing ─────────────────────────────
+ * The dispatch engine has lived in `cwip/notifications` for months (a
+ * persistent per-user row, `groupKey` coalescing, unread counts, deep links, a
+ * live-delivery sink) and the whole client has lived in
+ * `cursedbelt/react/notifications` (store, bell, feed, inbox, poll transport).
+ * What did NOT exist was a way to MOUNT any of it: the only mounted surface in
+ * the fleet was `orch-ui/services/notifications`, written against
+ * `@satellites/satellite-rpc` inside a package only the orchestrator consumes.
+ * So a satellite wanting a bell had two options, and both were wrong — adopt
+ * orch's rpc layer, or write the routes again.
+ *
+ * This module is the third: ordinary Hono routes, an SSE hub behind the sink
+ * the center already had, and a migration for apps using cursedbelt's runner.
+ *
+ *   const notifications = createNotificationService({ db });
+ *   notifications.mount(app, { authorize: (c) => userOf(c)?.id ?? null });
+ *
+ * and on the client:
+ *
+ *   const { store } = createNotificationsBinding();   // cursedbelt/react/notifications
+ *   <NotificationBell store={store} />
+ *
+ * ── The three properties worth knowing ──────────────────────────────────────
+ * 1. **A notification is a row before it is an event.** Delivery is a cache of
+ *    who is listening; the poll transport is the backstop and is not optional.
+ *    Nothing is lost by a closed laptop.
+ * 2. **Coalescing is a database constraint, not a debounce.** The partial
+ *    unique index on `(user_id, group_key) WHERE group_key IS NOT NULL AND
+ *    done = 0` is what makes "twenty of the same thing" one row with a count,
+ *    even under concurrent producers.
+ * 3. **The routes address the session's user and nothing else.** There is no
+ *    route that notifies somebody else; producing is server-side code calling
+ *    `center.notify*`.
+ */
+export { createNotificationHub } from "./hub";
+export type {
+	NotificationHub,
+	NotificationHubEvent,
+	NotificationHubListener,
+	NotificationHubOptions,
+} from "./hub";
+export { NOTIFICATION_MIGRATIONS, NOTIFICATIONS_TABLE } from "./migrations";
+export { mountNotificationRoutes } from "./routes";
+export type { NotificationRouteCenter, NotificationRoutesOptions } from "./routes";
+export { createNotificationService } from "./service";
+export type {
+	CreateNotificationServiceOptions,
+	NotificationService,
+	NotificationServiceMountOptions,
+} from "./service";
+// Re-exported so a server consumer needs ONE import for the whole contract —
+// the same courtesy `server/sharing` extends over `cursedbelt-core/sharing`. The
+// engine remains cwip's; this is a door, not a copy.
+export {
+	createNotificationCenter,
+	createMemoryNotificationStore,
+	createSqliteNotificationStore,
+	migrateNotificationsSchema,
+} from "cwip/notifications";
+export type {
+	AppNotification,
+	ListNotificationsQuery,
+	NotificationAudience,
+	NotificationCenter,
+	NotificationCenterOptions,
+	NotificationDraft,
+	NotificationFilter,
+	NotificationPage,
+	NotificationSeverity,
+	NotificationSink,
+	NotificationStore,
+	Notifier,
+} from "cwip/notifications";

package/src/server/notifications/migrations.ts

@@ -0,0 +1,39 @@
+/**
+ * The notification table, as a migration an app runs inside its OWN database.
+ *
+ * Same reasoning as `../sharing/migrations.ts`: the SCHEMA is shared, the DATA
+ * is local. A notification is about one app's rows and is read on the same page
+ * that reads them, so a central notification service would put a network hop in
+ * front of a badge count — and the first thing an app would do is cache it.
+ *
+ * 🔴 The DDL itself is NOT written here. `cwip/notifications` already owns it
+ * (`migrateNotificationsSchema`, which the sqlite store calls on construction),
+ * and a second copy in this file is a schema that agrees with the store until
+ * the day it doesn't. This module exists to give apps that use cursedbelt's
+ * migration RUNNER an ordered, once-only entry for it — the DDL is idempotent,
+ * so both routes converge on one table.
+ */
+import type { Database } from "bun:sqlite";
+import { migrateNotificationsSchema, type NotificationDb } from "cwip/notifications";
+import type { Migration } from "../migration/types";
+
+export const NOTIFICATIONS_TABLE = "notifications";
+
+/**
+ * Ordered migrations for the notification table.
+ *
+ *   applyRecommendedPragmas(db);
+ *   runMigrations(db, [...APP_MIGRATIONS, ...NOTIFICATION_MIGRATIONS]);
+ *
+ * An app that instead constructs `createSqliteNotificationStore(db)` gets the
+ * same table without this — the store migrates on construction. Running both is
+ * harmless and is the normal state of an app that adopted the store first.
+ */
+export const NOTIFICATION_MIGRATIONS: readonly Migration[] = [
+	{
+		name: "0001_notifications",
+		up(db: Database): void {
+			migrateNotificationsSchema(db as unknown as NotificationDb, NOTIFICATIONS_TABLE);
+		},
+	},
+];