cursedbelt 2.7.0 → 3.0.0

package/scripts/testPg.ts

@@ -1,107 +0,0 @@
-// cursedbelt's real-Postgres gate (04 §1) — disposable container, run, tear down.
-//
-// cwip's `test:pg` proves RLS behavior on the DOMAIN tables. This one proves
-// the SHARED CONTROL-PLANE stores — the durable job-outcome log and the revoked
-// -jti denylist that make multi-node completion and cross-node revocation true
-// rather than promised. Their SQL (`ON CONFLICT DO NOTHING`, `GREATEST`,
-// `bigint`-as-string, the compiled `IF NOT EXISTS` DDL) is a claim about
-// Postgres, and only Postgres can answer it.
-//
-//   bun run test:pg
-//
-// Same contract as cwip's: it starts `postgres:16-alpine` on an unused port,
-// points `CC_PG_URL` at it, runs only the `*.pg.test.ts` files, and removes the
-// container on the way out — pass or fail. With Docker absent it exits NON-ZERO
-// (a CI job that MEANT to run it must not pass by silently skipping) but prints
-// how to point it at an existing database instead.
-//
-// The port differs from cwip's (55433) on purpose: the two suites must be able
-// to run side by side without one tearing down the other's database.
-
-import { spawn } from 'bun';
-
-const CONTAINER = 'cc-cursedbelt-pg-control';
-const PORT = 55434;
-const URL = `postgres://postgres:postgres@localhost:${PORT}/postgres`;
-const SUITES = [
-  'src/server/drivers/pooledControlStores.pg.test.ts',
-  'src/server/drivers/pooledIdentityStore.pg.test.ts',
-  // The saas search tier (04 §3). Its whole subject — a generated tsvector, a
-  // total `websearch_to_tsquery`, FORCEd RLS, `bytea` embeddings — is answerable
-  // only by the engine.
-  'src/server/search/pgSearchProvider.pg.test.ts',
-  // The SHARED billing meter (04 item 4e). Its subject is `bigint` sums and
-  // cursors returned as STRINGS, and a multi-row `ON CONFLICT DO NOTHING` —
-  // three things only the engine can answer for, and each of which fails by
-  // producing a plausible wrong number rather than an error.
-  'src/server/runtime/meterRollup.pg.test.ts',
-  // The retention entrypoint (01 §4). Its subject is a control-plane DELETE,
-  // and the failure it guards against is the worst kind: an unscoped statement
-  // under FORCE ROW LEVEL SECURITY deletes nothing and reports success, so
-  // "the sweep ran" and "the sweep worked" are different claims and only an
-  // engine can separate them.
-  'src/server/runtime/retentionJob.pg.test.ts',
-  // The WINDOWS that sweep reads (D30). Its subject is a `bigint` column read
-  // back as a STRING — a number that passes `> 0`, fails `=== 30`, and would
-  // turn the sweep off in exactly the deployment that configured it.
-  'src/server/drivers/retentionPolicy.pg.test.ts',
-];
-
-const run = async (cmd: string[], options: { quiet?: boolean; env?: Record<string, string> } = {}): Promise<number> => {
-  const proc = spawn(cmd, {
-    stdout: options.quiet ? 'pipe' : 'inherit',
-    stderr: options.quiet ? 'pipe' : 'inherit',
-    // Bun.spawn does NOT inherit env by default — the test binary reads
-    // CC_PG_URL, so it must be passed through explicitly.
-    env: { ...process.env, ...options.env },
-  });
-  return await proc.exited;
-};
-
-const dockerAvailable = async (): Promise<boolean> => (await run(['docker', 'info'], { quiet: true })) === 0;
-
-const waitReady = async (): Promise<boolean> => {
-  for (let attempt = 0; attempt < 30; attempt += 1) {
-    if ((await run(['docker', 'exec', CONTAINER, 'pg_isready', '-U', 'postgres'], { quiet: true })) === 0) return true;
-    await Bun.sleep(1000);
-  }
-  return false;
-};
-
-const teardown = async (): Promise<void> => {
-  await run(['docker', 'rm', '-f', CONTAINER], { quiet: true });
-};
-
-const main = async (): Promise<number> => {
-  if (process.env.CC_PG_URL) return await run(['bun', 'test', ...SUITES]);
-
-  if (!(await dockerAvailable())) {
-    console.error(
-      `test:pg needs Docker (or a CC_PG_URL pointing at a throwaway Postgres).\n  CC_PG_URL=postgres://user:pass@host:5432/db bun test ${SUITES.join(' ')}`,
-    );
-    return 1;
-  }
-
-  await teardown(); // clear any leftover from an aborted run
-  console.log(`Starting ${CONTAINER} on :${PORT} …`);
-  const started = await run(
-    ['docker', 'run', '-d', '--rm', '--name', CONTAINER, '-e', 'POSTGRES_PASSWORD=postgres', '-p', `${PORT}:5432`, 'postgres:16-alpine'],
-    { quiet: true },
-  );
-  if (started !== 0) {
-    console.error('Failed to start the Postgres container.');
-    return 1;
-  }
-
-  try {
-    if (!(await waitReady())) {
-      console.error('Postgres did not become ready in time.');
-      return 1;
-    }
-    return await run(['bun', 'test', ...SUITES], { env: { CC_PG_URL: URL } });
-  } finally {
-    await teardown();
-  }
-};
-
-process.exit(await main());

package/src/client/contextSyncBroker.ts

@@ -1,130 +0,0 @@
-/**
- * `ContextSyncBroker` (03 §6.5) — instance-scoped state that must survive
- * multi-tab use.
- *
- * Selection, private-mode lock state and job progress are per-USER facts, not
- * per-tab facts. Without a broker, locking in one tab left a second tab showing
- * revealed private media until someone refreshed it — the lock looked like it
- * worked and did not.
- *
- * `VAULT_LOCKED` is therefore a **mandatory** broadcast: one tab locking locks
- * all tabs (V7 probe 9 asserts it, and also that key buffers were zeroized).
- *
- * Diffs carry a monotonic `sync_rev` so a message that arrives out of order — or
- * a tab that wakes from sleep with a stale queue — cannot roll newer state
- * backward. Local profile rides `BroadcastChannel`; saas swaps in the managed
- * WebSocket hub behind the same interface.
- */
-
-export interface SyncDiff<T = unknown> {
-  /** `<instanceId>:<key>`, or a bare app-level key like `VAULT_LOCKED`. */
-  channel: string;
-  /** Monotonic per channel. A diff at or below the last applied rev is dropped. */
-  syncRev: number;
-  value: T;
-  /** Origin tab id — a broker never applies its own echo. */
-  origin: string;
-}
-
-export interface ContextSyncBroker {
-  /** Publish a diff to every other tab. */
-  publish<T>(channel: string, value: T): void;
-  subscribe<T>(channel: string, listener: (value: T, diff: SyncDiff<T>) => void): () => void;
-  /** The last applied rev for a channel — the ordering guard's state. */
-  revOf(channel: string): number;
-  close(): void;
-  readonly tabId: string;
-}
-
-/** The transport seam: `BroadcastChannel` locally, a WebSocket hub on saas. */
-export interface SyncTransport {
-  post(diff: SyncDiff): void;
-  onMessage(listener: (diff: SyncDiff) => void): () => void;
-  close(): void;
-}
-
-export interface ContextSyncBrokerOptions {
-  /** Channel/room name. One per app instance. */
-  name: string;
-  transport?: SyncTransport;
-  /** Injected for tests; defaults to a random per-tab id. */
-  tabId?: string;
-}
-
-const broadcastChannelTransport = (name: string): SyncTransport | null => {
-  if (typeof BroadcastChannel === 'undefined') return null;
-  const channel = new BroadcastChannel(name);
-  return {
-    post: (diff) => channel.postMessage(diff),
-    onMessage: (listener) => {
-      const handler = (event: MessageEvent) => listener(event.data as SyncDiff);
-      channel.addEventListener('message', handler);
-      return () => channel.removeEventListener('message', handler);
-    },
-    close: () => channel.close(),
-  };
-};
-
-/** A no-op transport for SSR and single-context tests. */
-export const nullSyncTransport = (): SyncTransport => ({
-  post: () => {},
-  onMessage: () => () => {},
-  close: () => {},
-});
-
-export function createContextSyncBroker(options: ContextSyncBrokerOptions): ContextSyncBroker {
-  const tabId = options.tabId ?? `tab_${Math.random().toString(36).slice(2, 10)}`;
-  const transport = options.transport ?? broadcastChannelTransport(options.name) ?? nullSyncTransport();
-
-  const revs = new Map<string, number>();
-  const listeners = new Map<string, Set<(value: unknown, diff: SyncDiff) => void>>();
-
-  const unsubscribeTransport = transport.onMessage((diff) => {
-    // Never apply our own echo — a broker that re-applies its own publish
-    // double-counts every increment.
-    if (diff.origin === tabId) return;
-
-    const last = revs.get(diff.channel) ?? -1;
-    // Monotonic guard: a late or duplicated message cannot roll state backward.
-    if (diff.syncRev <= last) return;
-    revs.set(diff.channel, diff.syncRev);
-
-    for (const listener of listeners.get(diff.channel) ?? []) listener(diff.value, diff);
-  });
-
-  return {
-    tabId,
-
-    publish<T>(channel: string, value: T): void {
-      const syncRev = (revs.get(channel) ?? 0) + 1;
-      revs.set(channel, syncRev);
-      transport.post({ channel, syncRev, value, origin: tabId });
-    },
-
-    subscribe<T>(channel: string, listener: (value: T, diff: SyncDiff<T>) => void): () => void {
-      const set = listeners.get(channel) ?? new Set();
-      const typed = listener as (value: unknown, diff: SyncDiff) => void;
-      set.add(typed);
-      listeners.set(channel, set);
-      return () => {
-        set.delete(typed);
-        if (set.size === 0) listeners.delete(channel);
-      };
-    },
-
-    revOf: (channel) => revs.get(channel) ?? 0,
-
-    close() {
-      unsubscribeTransport();
-      listeners.clear();
-      transport.close();
-    },
-  };
-}
-
-/**
- * The lock channel. Named as a constant because "one tab locking locks all
- * tabs" is a probe-asserted guarantee, and a typo'd channel string would make
- * the broadcast silently no-op — the exact failure the broker exists to remove.
- */
-export const VAULT_LOCKED_CHANNEL = 'VAULT_LOCKED';

package/src/client/convertRequest.ts

@@ -1,117 +0,0 @@
-/*
- * v1 client request converter — the browser half of the ctgr GET-tunnel. When ctgr
- * mode is on, a mutating request is rewritten into one or more `/ctgr<XX>` GET twins
- * via the isomorphic codec (gzip + single base64url + integrity); a plain GET passes
- * through untouched. FormData uploads are serialized into the JSON body's `__files`
- * shape (the server reconstructs `req.files` from it) — identical to the legacy shape,
- * just fed through the optimized codec.
- */
-import {
-  type CtgrMethod,
-  encodeRequest,
-  METHOD_TO_ABBREV,
-  type SerializedFile,
-  toBase64,
-} from '../ctgr';
-import { isCtgrModeOn } from './ctgrConfig';
-
-/** One converted request ready for `fetch`: the GET-twin path + the GET init. */
-export interface CtgrFetchRequest {
-  /** `/ctgr<XX><path>?<params>` — a path; the caller prepends any API prefix. */
-  url: string;
-  init: RequestInit;
-}
-
-// 10 MB per-file cap for ctgr (GET-only) mode. base64 + URL transport inflates each
-// file and needs many sequential GETs per MB; beyond this the upload hangs/OOMs on
-// mobile. Large files require a real (non-`/f`) login.
-const CTGR_MAX_FILE_BYTES = 10 * 1024 * 1024;
-
-const SAFE_METHODS = new Set(['GET', 'HEAD']);
-
-/**
- * Convert one request for ctgr transport. Returns the chunked GET requests to send in
- * order (usually one); when ctgr mode is off, or it is already a body-less GET, the
- * original request passes through unchanged as a single entry.
- */
-export async function convertIfOnlyGETRequests(
-  url: string,
-  init: RequestInit = { method: 'GET' },
-  formData?: FormData,
-): Promise<{ requests: CtgrFetchRequest[] }> {
-  const method = (init.method ?? (formData ? 'POST' : 'GET')).toUpperCase();
-
-  if (!isCtgrModeOn() || (SAFE_METHODS.has(method) && !formData)) {
-    return { requests: [{ url, init }] };
-  }
-
-  const upper = method as CtgrMethod;
-  if (!METHOD_TO_ABBREV[upper]) {
-    throw new Error(`ctgr: "${method}" is not a tunnelable method`);
-  }
-
-  const body: unknown = formData ? await formDataToBody(formData) : bodyFromInit(init.body);
-  const getInit = toGetInit(init);
-  const { chunks } = await encodeRequest(upper, url, body);
-  return { requests: chunks.map((chunk) => ({ url: chunk.url, init: getInit })) };
-}
-
-/** Turn a FormData upload into the `__files` JSON body shape the GET path carries. */
-async function formDataToBody(formData: FormData): Promise<Record<string, unknown>> {
-  const files: SerializedFile[] = [];
-  const fields: Record<string, string> = {};
-  for (const [key, value] of formData.entries()) {
-    if (typeof value === 'object' && value !== null && 'arrayBuffer' in value) {
-      const file = value as File;
-      if (file.size > CTGR_MAX_FILE_BYTES) {
-        throw new Error(
-          `"${file.name}" (${Math.round(file.size / 1024 / 1024)} MB) is too large to upload in ` +
-            `GET-only mode — log in via /login (not /f) to upload large files`,
-        );
-      }
-      files.push({
-        field: key,
-        name: file.name,
-        type: file.type,
-        dataBase64: toBase64(new Uint8Array(await file.arrayBuffer())),
-      });
-    } else {
-      fields[key] = String(value);
-    }
-  }
-  return { __files: files, ...fields };
-}
-
-/** The request body as a JS value: a JSON string is parsed; anything else passes through. */
-function bodyFromInit(body: BodyInit | null | undefined): unknown {
-  if (typeof body !== 'string') return body ?? undefined;
-  try {
-    return JSON.parse(body);
-  } catch {
-    return body;
-  }
-}
-
-/** A GET copy of the init: no body, and the now-meaningless content-type dropped. */
-function toGetInit(init: RequestInit): RequestInit {
-  const next: RequestInit = { ...init, method: 'GET', headers: stripContentType(init.headers) };
-  delete next.body;
-  return next;
-}
-
-function stripContentType(headers: HeadersInit | undefined): HeadersInit | undefined {
-  if (!headers) return headers;
-  if (headers instanceof Headers) {
-    const next = new Headers(headers);
-    next.delete('content-type');
-    return next;
-  }
-  if (Array.isArray(headers)) {
-    return headers.filter(([key]) => key.toLowerCase() !== 'content-type');
-  }
-  const next: Record<string, string> = {};
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() !== 'content-type') next[key] = value;
-  }
-  return next;
-}

package/src/client/ctgrConfig.ts

@@ -1,29 +0,0 @@
-/*
- * Single source of truth for "GET-conversion (ctgr) mode". When on, every server
- * request is rewritten to a GET (see `convertIfOnlyGETRequests`) so the app works
- * where non-GET methods are blocked. Both the converter and the safety guard read
- * this, so they can never disagree.
- *
- * The mode is per-login-method, persisted in localStorage so it survives reloads:
- *   • the obfuscated `/f` login forces it ON (that environment is GET-only).
- *   • the standard `/login` keeps it OFF, so normal POST/PUT/PATCH/DELETE are used.
- * Default is OFF.
- */
-const CTGR_KEY = 'ctgr';
-
-export const isCtgrModeOn = (): boolean => {
-  try {
-    return localStorage.getItem(CTGR_KEY) === 'on';
-  } catch {
-    return false;
-  }
-};
-
-export const setCtgrMode = (on: boolean): void => {
-  try {
-    if (on) localStorage.setItem(CTGR_KEY, 'on');
-    else localStorage.removeItem(CTGR_KEY);
-  } catch {
-    // localStorage unavailable (private mode / SSR) — nothing to persist.
-  }
-};

package/src/client/ctgrGuard.ts

@@ -1,85 +0,0 @@
-/*
- * Safety net for GET-conversion mode. Even though every server request is supposed to
- * be rewritten to a GET (`convertIfOnlyGETRequests`), this guard sits at the actual
- * network boundary and HARD-BLOCKS any non-GET request to our own origin when the
- * mode is on — so a code path that forgot to run through the converter can never
- * sneak a real POST/PUT/DELETE/PATCH onto the wire. Catches both `fetch` and
- * `XMLHttpRequest`. This is a protection guarantee: it must never weaken.
- */
-import { isCtgrModeOn } from './ctgrConfig';
-
-// Methods that never mutate and are always safe to allow.
-const SAFE_METHODS = new Set(['GET', 'HEAD']);
-
-const urlOf = (input: RequestInfo | URL): string => {
-  if (typeof input === 'string') return input;
-  if (input instanceof URL) return input.href;
-  if (input instanceof Request) return input.url;
-  return String(input);
-};
-
-// Only guard our OWN API surface — same-origin AND under a path our app's request
-// layer actually owns (`/api/...` or a `/ctgr<XX>` twin). Restricting to these
-// prefixes (rather than "any same-origin path") matters: same-origin also covers
-// paths we don't own, like Cloudflare's `/cdn-cgi/rum` beacon, which fires a raw
-// POST on every page view — guarding it would both break RUM and fire this guard
-// for every ordinary visitor, not just a misbehaving call site.
-const isGuardedPath = (rawUrl: string): boolean => {
-  let path: string;
-  if (rawUrl.startsWith('/')) {
-    path = rawUrl;
-  } else {
-    try {
-      const u = new URL(rawUrl, window.location.href);
-      if (u.origin !== window.location.origin) return false;
-      path = u.pathname;
-    } catch {
-      return false;
-    }
-  }
-  return path.startsWith('/api/') || path.startsWith('/ctgr');
-};
-
-// Deliberately generic: this message can reach the console of ANY visitor (not just
-// a developer), so it must never describe the GET-conversion mechanism, name the
-// call sites to fix, or otherwise hint at how the transport works.
-const block = (): Error => {
-  const message = 'Service unavailable.';
-  console.error(message, new Error('blocked request'));
-  return new Error(message);
-};
-
-let installed = false;
-
-export const installCtgrGuard = (): void => {
-  if (installed || typeof window === 'undefined') return;
-  installed = true;
-
-  // ── fetch ──────────────────────────────────────────────────────────────────
-  if (typeof window.fetch === 'function') {
-    const originalFetch = window.fetch.bind(window);
-    const guardedFetch = (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
-      const method = (
-        init?.method ?? (input instanceof Request ? input.method : 'GET')
-      ).toUpperCase();
-      const url = urlOf(input);
-      if (isCtgrModeOn() && !SAFE_METHODS.has(method) && isGuardedPath(url)) {
-        return Promise.reject(block());
-      }
-      return originalFetch(input, init);
-    };
-    window.fetch = guardedFetch as typeof window.fetch;
-  }
-
-  // ── XMLHttpRequest ───────────────────────────────────────────────────────────
-  if (typeof XMLHttpRequest !== 'undefined') {
-    const originalOpen = XMLHttpRequest.prototype.open;
-    XMLHttpRequest.prototype.open = function open(method: string, url: string, ...rest: any[]) {
-      const upper = String(method).toUpperCase();
-      if (isCtgrModeOn() && !SAFE_METHODS.has(upper) && isGuardedPath(String(url))) {
-        throw block();
-      }
-      return (originalOpen as any).call(this, method, url, ...rest);
-    };
-  }
-};

package/src/client/index.ts

@@ -1,114 +0,0 @@
-/*
- * cursedbelt/client — the browser half of the cursedbelt server toolkit:
- *  • the ctgr GET-tunnel (localStorage mode flag, v1 request converter, hard-block guard),
- *    pairing with `cursedbelt/server` (`unGETify`) + the ctgr codec (`src/ctgr`, re-exported from `cursedbelt/server`);
- *  • the WS hub's auto-reconnecting channel socket (partysocket), pairing with
- *    `cursedbelt/server`'s `createWsHub`.
- */
-export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest';
-export { isCtgrModeOn, setCtgrMode } from './ctgrConfig';
-export { installCtgrGuard } from './ctgrGuard';
-export {
-  buildChannelSocketUrl,
-  type CreateChannelSocketOptions,
-  createChannelSocket,
-  parseWsMessage,
-  type ReconnectingWebSocket,
-  sendWsMessage,
-  type WsLocation,
-  type WsMessage,
-} from './ws';
-
-// ── the Dual-Layer Router's client half (03 §3.1, §4, §5) ───────────────────
-// Named, not `export * from './router'`.
-//
-// The star was the only one in this file — every other line here is an explicit
-// list — and it is the construct Bun's ESM linker is least reliable about: under
-// a large multi-entrypoint `bun test` process, a consumer importing
-// `defaultViewModulePath` from `cursedbelt/client` would fail to LINK with
-// "Export named 'defaultViewModulePath' not found", while the same import
-// succeeded when the file ran alone or with different neighbors. Naming the
-// re-exports resolves them eagerly and removes the failure mode; it also makes
-// this entry's public surface readable without opening a second file, which is
-// why the rest of it was already written this way.
-export {
-  buildClientRoutes,
-  type BuildRoutesOptions,
-  type BuiltRoutes,
-  CC_SCHEME,
-  type CCRoute,
-  type CCRouteMatch,
-  type CCRouter,
-  type CCRouterOptions,
-  type CCRouterState,
-  createCcRouter,
-  DEEP_LINK_ENTITY_PREFIXES,
-  defaultViewModulePath,
-  entityPrefixOf,
-  fillRouteTemplate,
-  generateClientRoutesModule,
-  GO_ROUTE,
-  goHref,
-  type HistoryLike,
-  type LocatorContext,
-  type LocatorFailure,
-  type LocatorResolution,
-  matchRoute,
-  parseLocator,
-  type ParsedLocator,
-  registerDeepLinkPrefixes,
-  resolveLocator,
-  routeParams,
-  toLocator,
-  type ViewLoader,
-  type ViewModulePath,
-} from './router';
-
-// ── cross-tab state sync + the mandatory lock broadcast (03 §6.5) ───────────
-export {
-  type ContextSyncBroker,
-  type ContextSyncBrokerOptions,
-  createContextSyncBroker,
-  nullSyncTransport,
-  type SyncDiff,
-  type SyncTransport,
-  VAULT_LOCKED_CHANNEL,
-} from './contextSyncBroker';
-
-// ── the live server push channel + the per-instance lifecycle host ──────────
-export * from './stream';
-
-// ── the frozen manifest codec (02 §1.1) ─────────────────────────────────────
-// The generated client boots from `manifest.gen.json`, so it needs the reader —
-// but NOT the compiler. Re-exported from the browser subpath (the codec is a
-// pure, dependency-free data mapping) so a client never has to import
-// `cursedbelt/verify` and drag the whole V0–V7 pipeline into its bundle.
-export {
-  FROZEN_MANIFEST_VERSION,
-  type FrozenInstance,
-  type FrozenManifest,
-  FrozenManifestError,
-  type FrozenPort,
-  type FrozenStagingCatalog,
-  readFrozenManifest,
-  serializeFrozenManifest,
-  toFrozenManifest,
-} from '../verify/frozenManifest';
-
-// ── the wire hub the lifecycle host feeds (03 §6.2) ─────────────────────────
-// Re-exported here rather than left reachable only through `instanceStream`'s
-// parameter types: a generated app has to CONSTRUCT the hub and one runtime per
-// instance to bind the shell, and a primitive a consumer cannot import is an
-// orphan seam by construction (law #1).
-export {
-  createInstanceRuntime,
-  createWireHub,
-  type InstanceRuntime,
-  type InstanceRuntimeOptions,
-  type LedgerEntry,
-  type LifecyclePhase,
-  type StormBreakerTrip,
-  type WireEnvelope,
-  type WireHub,
-  type WireHubOptions,
-} from '../core/wire/wireHub';