@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.321

package/src/pure.ts

@@ -0,0 +1,66 @@
+/**
+ * `@spooky-sync/core/pure`: the side-effect-free builders of the sync protocol.
+ *
+ * Everything here is plain functions and constants over `surrealdb` value
+ * types: no wasm, no logger, no `window`/`document`/`localStorage`. Safe to
+ * import from a service worker, a dedicated worker or Node. The full client
+ * imports the same modules, so what this entry builds is byte for byte what
+ * `Sp00kyClient` sends.
+ */
+import { queryHashInput, type QueryKeyInput } from './query/hash';
+import { sha256Hex } from './utils/sha256';
+
+// Statement builders: register + snapshot, heartbeat, bodies, views.
+export * from './query/sql';
+// Query keys.
+export { queryHashInput, viewKeyInput, type QueryKeyInput } from './query/hash';
+// `_00_list_ref` table naming and user-id sanitizing (mirrors ssp-protocol).
+export {
+  ANON_LIST_REF_TABLE,
+  ANON_USER_ID,
+  DEFAULT_REF_MODE,
+  bucketIdForUser,
+  listRefTableFor,
+  sanitizeUserId,
+  type RefMode,
+} from './modules/ref-tables';
+// Membership snapshot parsing (the answer to the register read-back).
+export {
+  FAILED,
+  dedupeRecordVersions,
+  metaFromRow,
+  snapshotFromSingle,
+  type Answer,
+  type ListRefSnapshot,
+  type QueryMetaRow,
+} from './query/membership';
+// LIVE edge decoding.
+export { hashOfEdge, rowOfEdge } from './utils/edges';
+// SurrealQL string helpers.
+export {
+  surql,
+  type SealOptions,
+  type SealedQuery,
+  type SurqlHelper,
+  type TxQuery,
+} from './utils/surql';
+// Param typing the full client applies before registering.
+export { parseQueryParams } from './utils/parser';
+export { encodeRecordId, parseRecordIdString, parseDuration } from './utils/index';
+// Unverified JWT claim reading (user id, access method, impersonation).
+export {
+  decodeTokenClaims,
+  IMPERSONATION_ACCESS,
+  type TokenClaims,
+} from './modules/auth/impersonation';
+export { sha256Hex } from './utils/sha256';
+// Web Push wire types.
+export * from './push/types';
+
+/**
+ * The remote `_00_query` key of a query for one session salt: what the full
+ * client names its view (`_00_query:<key>`).
+ */
+export function queryKey(input: QueryKeyInput, sessionId: string | null): Promise<string> {
+  return sha256Hex(queryHashInput(input, sessionId));
+}

package/src/push/types.ts

@@ -0,0 +1,174 @@
+/**
+ * Web Push wire types shared by the page (`db.webPush`), the service worker
+ * bridge (`@spooky-sync/core/sw`) and the live feed. Pure: types plus a few
+ * dependency-free helpers, safe in any context.
+ *
+ * `PushPayload` mirrors `packages/push-core/src/config.rs` (`PushPayload`,
+ * `PayloadKind`, `Op`, `NotificationTemplate`). Keep the two in step.
+ */
+
+/** Payload format version this build understands. */
+export const PUSH_PAYLOAD_VERSION = 1;
+
+export type PushPayloadKind = 'rule' | 'message';
+export type PushOp = 'create' | 'update' | 'delete';
+export type PushUrgency = 'very-low' | 'low' | 'normal' | 'high';
+
+/** One button on a notification (`NotificationAction` plus a per-action `url`). */
+export interface PushNotificationAction {
+  action: string;
+  title: string;
+  icon?: string;
+  /** Opened instead of the notification's `url` when this action is clicked. */
+  url?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * What a content push shows. Every key other than `title` and `url` is passed
+ * to `showNotification` as is, unknown ones included (`vibrate`, `timestamp`,
+ * whatever a browser adds later).
+ */
+export interface PushNotification {
+  title?: string;
+  body?: string;
+  icon?: string;
+  badge?: string;
+  image?: string;
+  lang?: string;
+  dir?: string;
+  /** Defaults to the push's `topic`. */
+  tag?: string;
+  /** Opened (or focused) on click. */
+  url?: string;
+  requireInteraction?: boolean;
+  renotify?: boolean;
+  silent?: boolean;
+  actions?: PushNotificationAction[];
+  /** Merged into the notification's `data` next to the bridge's own keys. */
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * The JSON every push carries (then RFC 8291 encrypted). `notification`
+ * present: a content push the service worker shows as is. Absent: a
+ * content-free nudge, the app renders from its own data.
+ */
+export interface PushPayload {
+  v: number;
+  kind: PushPayloadKind;
+  /** Rule name (`kind: 'rule'`). */
+  rule?: string;
+  /** `_00_push_message` id (`kind: 'message'`). */
+  message?: string;
+  /** The row that fired the rule. */
+  table?: string;
+  id?: string;
+  op?: PushOp;
+  topic?: string;
+  notification?: PushNotification;
+  data?: Record<string, unknown>;
+  /** Epoch ms when the engine built it. */
+  ts: number;
+}
+
+/** Page -> service worker: the session to use for live rendering. */
+export interface BridgeTokenMessage {
+  type: 'sp00ky:token';
+  token: string;
+  userId: string;
+  /** The SurrealDB endpoint (`wss://host/rpc`), not the push endpoint. */
+  endpoint: string;
+  namespace: string;
+  database: string;
+  /** VAPID public key (base64url) the page subscribed with, for `pushsubscriptionchange`. */
+  publicKey?: string;
+  /** This browser's push endpoint, when subscribed. */
+  pushEndpoint?: string;
+}
+
+/** Page -> service worker: forget the session and close every notification. */
+export interface BridgeSignOutMessage {
+  type: 'sp00ky:signout';
+}
+
+/** Service worker -> page messages. */
+export type WebPushClientMessage =
+  /** A push arrived while this page was visible, so nothing was shown. */
+  | { type: 'sp00ky:push'; payload: PushPayload }
+  /** A notification was clicked and the bridge was told to route in-app. */
+  | { type: 'sp00ky:navigate'; url: string; payload?: PushPayload; action?: string }
+  /** The browser rotated the push subscription; the page should `sync()`. */
+  | { type: 'sp00ky:subscriptionchange'; endpoint?: string };
+
+/** `urlBase64ToUint8Array`: the VAPID key as `applicationServerKey` wants it. */
+export function base64UrlToBytes(value: string): Uint8Array {
+  const padded =
+    value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4);
+  const raw = typeof atob === 'function' ? atob(padded) : decodeBase64Fallback(padded);
+  const out = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+  return out;
+}
+
+export function bytesToBase64Url(bytes: ArrayBuffer | Uint8Array): string {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let raw = '';
+  for (let i = 0; i < view.length; i++) raw += String.fromCharCode(view[i]);
+  const b64 = typeof btoa === 'function' ? btoa(raw) : encodeBase64Fallback(raw);
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function sameBytes(
+  a: ArrayBuffer | Uint8Array | null | undefined,
+  b: ArrayBuffer | Uint8Array | null | undefined
+): boolean {
+  if (!a || !b) return false;
+  const x = a instanceof Uint8Array ? a : new Uint8Array(a);
+  const y = b instanceof Uint8Array ? b : new Uint8Array(b);
+  if (x.length !== y.length) return false;
+  for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
+  return true;
+}
+
+/** A payload this build can act on (`v` known, `kind` set). */
+export function isPushPayload(value: unknown): value is PushPayload {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as { v?: unknown; kind?: unknown };
+  return v.v === PUSH_PAYLOAD_VERSION && (v.kind === 'rule' || v.kind === 'message');
+}
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function decodeBase64Fallback(input: string): string {
+  const clean = input.replace(/=+$/, '');
+  let out = '';
+  let buffer = 0;
+  let bits = 0;
+  for (const ch of clean) {
+    const idx = B64.indexOf(ch);
+    if (idx < 0) continue;
+    buffer = (buffer << 6) | idx;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out += String.fromCharCode((buffer >> bits) & 0xff);
+    }
+  }
+  return out;
+}
+
+function encodeBase64Fallback(raw: string): string {
+  let out = '';
+  for (let i = 0; i < raw.length; i += 3) {
+    const a = raw.charCodeAt(i);
+    const b = i + 1 < raw.length ? raw.charCodeAt(i + 1) : 0;
+    const c = i + 2 < raw.length ? raw.charCodeAt(i + 2) : 0;
+    const n = (a << 16) | (b << 8) | c;
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63];
+    out += i + 1 < raw.length ? B64[(n >> 6) & 63] : '=';
+    out += i + 2 < raw.length ? B64[n & 63] : '=';
+  }
+  return out;
+}

package/src/query/anon-query-isolation.integration.test.ts

@@ -0,0 +1,337 @@
+import { Socket } from 'node:net';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { RecordId, Surreal } from 'surrealdb';
+import { liveEndpoint } from '../live/index';
+import {
+  heartbeatBatch,
+  heartbeatRowGone,
+  leaveViewsBeacon,
+  queryRowCountBatchSelect,
+  queryRowCountSelect,
+} from './sql';
+
+/**
+ * Every signed-out visitor shares the one `anon` identity, so `_00_query`
+ * tells their views apart by session: an anonymous row answers only to the
+ * sessions in its `subscribers`. A second visitor must not be able to list,
+ * read, rewrite, plant or delete the first one's view, while the first keeps
+ * its heartbeat and its registration read-back, also after a reconnect.
+ *
+ * Runs the shipped `_00_query` block and `fn::query::*` functions from
+ * `apps/cli/src` against a real SurrealDB, because the guarantee is the
+ * engine's evaluation of the table and field permissions. Boot one first, e.g.:
+ *   docker run -d --name spooky-surreal-it -p 18011:8000 \
+ *     surrealdb/surrealdb:v3.1.5 start --user root --pass root --allow-all memory
+ *
+ * Override the endpoint with SURREAL_IT_ENDPOINT. Skips if unreachable.
+ */
+const endpoint = liveEndpoint(process.env.SURREAL_IT_ENDPOINT ?? 'ws://127.0.0.1:18011');
+const NS = 'it';
+
+const cliSource = (file: string) =>
+  readFileSync(fileURLToPath(new URL(`../../../../apps/cli/src/${file}`, import.meta.url)), 'utf8');
+
+/** Just the `_00_query` block: the rest of the file needs tables and modules this test does not. */
+function queryTableSchema(): string {
+  const meta = cliSource('meta_tables_remote.surql');
+  const start = meta.indexOf('DEFINE TABLE OVERWRITE _00_query SCHEMALESS');
+  const end = meta.indexOf('-- SPOOKY LIST REF');
+  if (start < 0 || end < start)
+    throw new Error('_00_query block not found in meta_tables_remote.surql');
+  return meta.slice(start, end);
+}
+
+const ACCESS = `
+DEFINE TABLE OVERWRITE user SCHEMALESS PERMISSIONS FOR select WHERE id = $auth.id;
+DEFINE ACCESS OVERWRITE account ON DATABASE TYPE RECORD
+  SIGNUP (CREATE user SET name = $name)
+  SIGNIN (SELECT * FROM user WHERE name = $name)
+  DURATION FOR TOKEN 1h, FOR SESSION 1h;
+`;
+
+/** What the SSP writes, as root, when a session registers a view (`node.rs`, cold path). */
+const SSP_REGISTER = `
+UPSERT $id SET clientId = $sid, auth_id = $owner, surql = 'SELECT * FROM item',
+  params = { auth: { id: $authParam }, access: '' }, ttl = 1h, lastActiveAt = time::now(),
+  rowCount = 3, state = 'ready',
+  subscribers = array::append(
+    array::filter(subscribers ?? [], |$s| <string>$s.id != $sid AND <datetime>$s.seenAt + 1h > time::now()),
+    { id: $sid, seenAt: time::now() })`;
+
+/** A `_00_query:<sha256>` id, the shape the client mints (and the pagehide beacon accepts). */
+const viewId = () =>
+  new RecordId('_00_query', createHash('sha256').update(randomUUID()).digest('hex'));
+
+describe('anonymous _00_query isolation (real SurrealDB)', () => {
+  let root: Surreal;
+  let database = '';
+  let reachable = false;
+  const open: Surreal[] = [];
+
+  // A plain TCP probe: the SDK never rejects a connect to a refused port.
+  beforeAll(async () => {
+    const url = new URL(endpoint);
+    reachable = await new Promise<boolean>((resolve) => {
+      const socket = new Socket();
+      const done = (ok: boolean) => {
+        socket.destroy();
+        resolve(ok);
+      };
+      socket.setTimeout(1_000, () => done(false));
+      socket.once('error', () => done(false));
+      socket.connect(Number(url.port || 80), url.hostname, () => done(true));
+    });
+  });
+
+  beforeEach(async () => {
+    if (!reachable) return;
+    database = `anon_query_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    root = new Surreal();
+    await root.connect(endpoint, { reconnect: false });
+    await root.signin({ username: 'root', password: 'root' });
+    await root.use({ namespace: NS, database });
+    await root.query(ACCESS);
+    await root.query(queryTableSchema());
+    await root.query(cliSource('functions_remote.surql'));
+  });
+
+  afterEach(async () => {
+    if (!reachable) return;
+    for (const db of open.splice(0)) await db.close().catch(() => undefined);
+    await root.query(`REMOVE DATABASE ${database}`).catch(() => undefined);
+    await root.close();
+  });
+
+  /** A signed-out socket and its `session::id()`. */
+  async function guest(): Promise<[Surreal, string]> {
+    const db = new Surreal();
+    open.push(db);
+    await db.connect(endpoint, { reconnect: false });
+    await db.use({ namespace: NS, database });
+    const [sid] = (await db.query('RETURN <string>session::id()')) as [string];
+    return [db, sid];
+  }
+
+  /** A signed-in socket, its `session::id()`, `$auth.id` and access token. */
+  async function member(name: string): Promise<[Surreal, string, string, string]> {
+    const db = new Surreal();
+    open.push(db);
+    await db.connect(endpoint, { reconnect: false });
+    await db.use({ namespace: NS, database });
+    const tokens = (await db.signup({
+      namespace: NS,
+      database,
+      access: 'account',
+      variables: { name },
+    })) as string | { access: string };
+    const [sid, authId] = (await db.query(
+      'RETURN <string>session::id(); RETURN <string>$auth.id'
+    )) as [string, string];
+    return [db, sid, authId, typeof tokens === 'string' ? tokens : tokens.access];
+  }
+
+  /** `beaconSql`'s request: a fresh HTTP session, Bearer token only when signed in. */
+  async function beacon(sql: string, token?: string): Promise<void> {
+    const url = new URL(endpoint);
+    url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
+    url.pathname = url.pathname.replace(/\/rpc\/?$/, '') + '/sql';
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      'Content-Type': 'text/plain',
+      'surreal-ns': NS,
+      'surreal-db': database,
+    };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(url, { method: 'POST', headers, body: sql });
+    expect(res.ok).toBe(true);
+  }
+
+  const register = (id: RecordId<string>, sid: string, owner = 'anon') =>
+    root.query(SSP_REGISTER, { id, sid, owner, authParam: owner === 'anon' ? '' : owner });
+  const row = async (id: RecordId<string>) =>
+    ((await root.query('SELECT * FROM ONLY $id', { id })) as [Record<string, any> | undefined])[0];
+  const count = async () =>
+    ((await root.query('SELECT VALUE id FROM _00_query')) as [unknown[]])[0].length;
+
+  /** The client's register read-back, as `registerSelect` sends it after `fn::query::register`. */
+  const readBack = async (db: Surreal, id: RecordId<string>) =>
+    ((await db.query(queryRowCountSelect(), { in: id })) as [unknown])[0] ?? null;
+  /** The client's lifecycle tick: did the heartbeat find the row? */
+  const heartbeatFound = async (db: Surreal, id: RecordId<string>) => {
+    const beat = heartbeatBatch([id]);
+    const [result] = (await db.query(beat.sql, beat.vars)) as [unknown];
+    return !heartbeatRowGone(result);
+  };
+
+  it("a second guest cannot list, read, rewrite, release or delete the first guest's view", async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [a, sidA] = await guest();
+    const [b, sidB] = await guest();
+    const qa = viewId();
+    await register(qa, sidA);
+    const before = await row(qa);
+
+    expect(await b.query('SELECT id, surql FROM _00_query')).toEqual([[]]);
+    expect(await readBack(b, qa)).toBeNull();
+    // The membership batch read. 3.0.x answers a hidden row with an empty
+    // object, which the client skips for want of an `id`.
+    const [batch] = (await b.query(queryRowCountBatchSelect(), { ins: [qa] })) as [
+      Array<{ id?: unknown }>,
+    ];
+    expect(batch.filter((r) => r?.id)).toEqual([]);
+
+    expect(
+      await b.query(`UPDATE $id SET surql = 'SELECT * FROM secret', ttl = 1000w`, { id: qa })
+    ).toEqual([[]]);
+    expect(await heartbeatFound(b, qa)).toBe(false);
+    expect(await b.query('RETURN fn::query::unsubscribe($id)', { id: qa })).toEqual([
+      { released: false, remaining: 0 },
+    ]);
+    // Session ids are not secret (they ride on `_00_list_ref_anon`), so naming
+    // the owner's must not help, over the socket or over the beacon's HTTP path.
+    await b.query('RETURN fn::query::leave($id, [$sid])', { id: qa, sid: sidA });
+    await beacon(leaveViewsBeacon([qa], [sidA])!);
+    await b.query('DELETE $id', { id: qa });
+
+    expect(await row(qa)).toEqual(before);
+    expect(await count()).toBe(1);
+    // ...and the owner never noticed.
+    expect(await readBack(a, qa)).toEqual({ rowCount: 3, state: 'ready' });
+    expect(sidB).not.toBe(sidA);
+  });
+
+  it('no caller can plant a row, so nothing the SSP re-registers at boot comes from a client', async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [g, sidG] = await guest();
+    const [u, , authU] = await member('alice');
+    const planted = (sid: string, owner: string) =>
+      `SET auth_id = '${owner}', surql = 'SELECT * FROM item', params = {}, ttl = 1h,
+           subscribers = [{ id: '${sid}', seenAt: time::now() }]`;
+
+    await g.query(`CREATE _00_query:g1 ${planted(sidG, 'anon')}`);
+    await g.query(`UPSERT _00_query:g2 ${planted(sidG, 'anon')}`);
+    await g.query(
+      `INSERT INTO _00_query { id: 'g3', auth_id: 'anon', ttl: 1h, subscribers: [{ id: '${sidG}' }] }`
+    );
+    await u.query(`CREATE _00_query:u1 ${planted('x', authU)}`);
+    await u.query(`UPSERT _00_query:u2 ${planted('x', authU)}`);
+    expect(await count()).toBe(0);
+  });
+
+  it('the owner cannot rewrite what the SSP trusts on its own row either', async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [g, sidG] = await guest();
+    const [u, sidU, authU] = await member('alice');
+    const qg = viewId();
+    const qu = viewId();
+    await register(qg, sidG);
+    await register(qu, sidU, authU);
+    // One field per statement: a write the table rule rejects as a whole would
+    // hide whether the field itself is locked. `params.auth.id` is the identity
+    // the SSP injects into permission predicates when it rebuilds the view at
+    // boot, `surql` skips the allowlist there, and turning a user's row into an
+    // anonymous one would publish its edges to the world-readable anon table.
+    const tampers = (owner: string): Record<string, string> => ({
+      surql: `surql = 'SELECT * FROM secret'`,
+      params: `params = { auth: { id: 'user:victim' }, access: 'account' }`,
+      ttl: 'ttl = 1000w',
+      auth_id: `auth_id = '${owner === 'anon' ? 'user:victim' : 'anon'}'`,
+      clientId: `clientId = 'forged'`,
+      rowCount: 'rowCount = 0',
+      state: `state = 'materializing'`,
+      lastActiveAt: 'lastActiveAt = time::now() + 1000w',
+    });
+
+    for (const [db, id, owner] of [
+      [g, qg, 'anon'],
+      [u, qu, authU],
+    ] as const) {
+      for (const [field, set] of Object.entries(tampers(owner))) {
+        const before = await row(id);
+        await db.query(`UPDATE $id SET ${set}`, { id });
+        expect((await row(id))?.[field], `${owner} ${field}`).toEqual(before?.[field]);
+      }
+    }
+  });
+
+  it('the owning guest keeps its heartbeat and read-back, and after a reconnect gets them back by registering again', async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [a, sidA] = await guest();
+    const [b] = await guest();
+    const qa = viewId();
+    await register(qa, sidA);
+
+    expect(await readBack(a, qa)).toEqual({ rowCount: 3, state: 'ready' });
+    const [batch] = (await a.query(queryRowCountBatchSelect(), { ins: [qa] })) as [
+      Array<{ id?: unknown; rowCount?: number }>,
+    ];
+    expect(batch.map((r) => r.rowCount)).toEqual([3]);
+    const stamped = (await row(qa))?.lastActiveAt;
+    expect(await heartbeatFound(a, qa)).toBe(true);
+    expect((await row(qa))?.lastActiveAt).not.toEqual(stamped);
+
+    // A reconnect is a new session. Until it registers again its heartbeat
+    // finds nothing, which the client reads as a reclaimed view and
+    // re-registers; the SSP's registration then adds the new session.
+    await a.close();
+    const [a2, sidA2] = await guest();
+    expect(await heartbeatFound(a2, qa)).toBe(false);
+    expect(await readBack(a2, qa)).toBeNull();
+    await register(qa, sidA2);
+    expect(await heartbeatFound(a2, qa)).toBe(true);
+    expect(await readBack(a2, qa)).toEqual({ rowCount: 3, state: 'ready' });
+    expect((await row(qa))?.subscribers.map((s: { id: string }) => s.id)).toEqual([sidA, sidA2]);
+
+    // The bystander is still out.
+    expect(await heartbeatFound(b, qa)).toBe(false);
+    expect(await readBack(b, qa)).toBeNull();
+  });
+
+  it('the owning guest can still release its view', async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [a, sidA] = await guest();
+    const qa = viewId();
+    await register(qa, sidA);
+    expect(await a.query('RETURN fn::query::unsubscribe($id)', { id: qa })).toEqual([
+      { released: true, remaining: 0 },
+    ]);
+    expect(await row(qa)).toBeUndefined();
+  });
+
+  it("a signed-in user's views are untouched: other tabs share them, the pagehide leave still pulls the expiry in", async (ctx) => {
+    if (!reachable) ctx.skip();
+    const [u, sidU, authU, token] = await member('alice');
+    const [bob] = await member('bob');
+    const [g] = await guest();
+    const qu = viewId();
+    await register(qu, sidU, authU);
+
+    // A second tab of the same user is not a subscriber yet and still gets in.
+    const tab2 = new Surreal();
+    open.push(tab2);
+    await tab2.connect(endpoint, { reconnect: false });
+    await tab2.use({ namespace: NS, database });
+    await tab2.authenticate(token);
+    expect(await heartbeatFound(tab2, qu)).toBe(true);
+    expect(await readBack(tab2, qu)).toEqual({ rowCount: 3, state: 'ready' });
+
+    expect(await heartbeatFound(bob, qu)).toBe(false);
+    expect(await readBack(g, qu)).toBeNull();
+
+    // The beacon names both tabs' sessions over a fresh HTTP session.
+    const [sid2] = (await tab2.query('RETURN <string>session::id()')) as [string];
+    await beacon(leaveViewsBeacon([qu], [sidU, sid2])!, token);
+    const [left] = (await root.query(
+      'SELECT VALUE duration::secs((lastActiveAt + ttl) - time::now()) FROM ONLY $id',
+      {
+        id: qu,
+      }
+    )) as [number];
+    expect(left).toBeGreaterThan(0);
+    expect(left).toBeLessThanOrEqual(60);
+    expect((await row(qu))?.subscribers).toEqual([]);
+  });
+});

package/src/query/env.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { columnsFor, defaultEnv, listRefTable } from './env';
+import { emptyState } from '../state/client-state';
+
+const schema = { tables: [{ name: 'thing', columns: { a: { type: 'string' } } }] } as any;
+
+describe('SagaEnv', () => {
+  it('defaultEnv applies overrides', () => {
+    expect(defaultEnv(schema).outboxBatchSize).toBe(50);
+    expect(defaultEnv(schema, { outboxBatchSize: 5 }).outboxBatchSize).toBe(5);
+  });
+  it('listRefTable: per-user, anonymous when enabled, global otherwise', () => {
+    const s = emptyState({ tabId: 't' });
+    expect(listRefTable(defaultEnv(schema), { ...s, userId: 'user:abc' })).toBe('_00_list_ref_user_abc');
+    expect(listRefTable(defaultEnv(schema, { anonLive: true }), s)).toBe('_00_list_ref_anon');
+    expect(listRefTable(defaultEnv(schema), s)).toBe('_00_list_ref');
+  });
+  it('columnsFor: schema table, framework table, unknown', () => {
+    expect(columnsFor(defaultEnv(schema), 'thing')).toEqual({ a: { type: 'string' } });
+    expect(columnsFor(defaultEnv(schema), '_00_feature_flag')).toEqual({});
+    expect(columnsFor(defaultEnv(schema), 'nope')).toBeNull();
+  });
+});

package/src/query/env.ts

@@ -0,0 +1,56 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { RefMode } from '../modules/ref-tables';
+import { ANON_USER_ID, DEFAULT_REF_MODE, listRefTableFor } from '../modules/ref-tables';
+import type { ClientState } from '../state/client-state';
+import {
+  DEGRADE_AFTER_FAILURES,
+  LIST_REF_POLL_BASE_MS,
+  MATERIALIZE_DEBOUNCE_MS,
+  OUTBOX_BATCH_SIZE,
+  PUSH_TIMEOUT_MS,
+} from '../kernel/constants';
+
+/**
+ * Static configuration the sagas read. Plain data, built once by the runtime
+ * from `Sp00kyConfig`; sagas never see the config object itself.
+ */
+export interface SagaEnv {
+  readonly schema: SchemaStructure;
+  readonly refMode: RefMode;
+  readonly anonLive: boolean;
+  readonly remoteTimeoutMs: number;
+  readonly pushTimeoutMs: number;
+  readonly outboxBatchSize: number;
+  readonly degradeAfter: number;
+  readonly materializeDebounceMs: number;
+  readonly pollBaseMs: number;
+  readonly defaultTtlMs: number;
+}
+
+export function defaultEnv(schema: SchemaStructure, over: Partial<SagaEnv> = {}): SagaEnv {
+  return {
+    schema,
+    refMode: DEFAULT_REF_MODE,
+    anonLive: false,
+    remoteTimeoutMs: 60_000,
+    pushTimeoutMs: PUSH_TIMEOUT_MS,
+    outboxBatchSize: OUTBOX_BATCH_SIZE,
+    degradeAfter: DEGRADE_AFTER_FAILURES,
+    materializeDebounceMs: MATERIALIZE_DEBOUNCE_MS,
+    pollBaseMs: LIST_REF_POLL_BASE_MS,
+    defaultTtlMs: 600_000,
+    ...over,
+  };
+}
+
+/** The `_00_list_ref` table this session reads: per-user, anonymous, or global. */
+export function listRefTable(env: SagaEnv, s: ClientState): string {
+  const userId = s.userId ?? (env.anonLive ? ANON_USER_ID : null);
+  return listRefTableFor(env.refMode, userId);
+}
+
+export function columnsFor(env: SagaEnv, table: string): Record<string, unknown> | null {
+  const found = env.schema.tables.find((t) => t.name === table);
+  if (found) return found.columns as Record<string, unknown>;
+  return table.startsWith('_00_') ? {} : null;
+}