@spooky-sync/core 0.0.1-canary.33 → 0.0.1-canary.331

package/dist/worker-edges.js

@@ -0,0 +1,480 @@
+import { DateTime, Duration, RecordId } from "surrealdb";
+import { RecordId as RecordId$1, baseFieldOfParam, cyrb53 } from "@spooky-sync/query-builder";
+
+//#region src/query/hash.ts
+/** Session-salted: two tabs of one user must not share a remote view. */
+const queryHashInput = (input, sessionId) => JSON.stringify({
+	surql: input.surql,
+	params: input.params,
+	sessionId
+});
+/** Session-independent: survives reload and bucket switch. */
+const viewKeyInput = (input) => JSON.stringify({
+	surql: input.surql,
+	params: input.params
+});
+
+//#endregion
+//#region src/utils/sha256.ts
+/**
+* Lowercase hex SHA-256 of a UTF-8 string, through WebCrypto.
+*
+* Pure and dependency free so it can live in `@spooky-sync/core/pure` and run
+* in a service worker, a dedicated worker or Node (`globalThis.crypto` is
+* there on Node 19+). Query keys are `sha256Hex(JSON.stringify(..))`, see
+* `query/hash.ts`.
+*/
+async function sha256Hex(input) {
+	const bytes = new TextEncoder().encode(input);
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+//#endregion
+//#region src/utils/surql.ts
+const surql = {
+	seal(query, options) {
+		if (typeof query === "string") return `${query};`;
+		const txQuery = query;
+		const idx = options?.resultIndex ?? txQuery.statementCount - 1;
+		return {
+			sql: `${txQuery.sql};`,
+			extract(results) {
+				return results[idx + 1];
+			}
+		};
+	},
+	tx(queries) {
+		return {
+			__brand: "TxQuery",
+			sql: `BEGIN TRANSACTION;\n${queries.join(";")};\nCOMMIT TRANSACTION`,
+			statementCount: queries.length
+		};
+	},
+	selectById(idVar, returnValues) {
+		return `SELECT ${returnValues.join(",")} FROM ONLY $${idVar}`;
+	},
+	selectByFieldsAnd(table, whereVar, returnValues) {
+		return `SELECT ${returnValues.map((rv) => typeof rv === "string" ? rv : `${rv.field} as ${rv.alias}`).join(",")} FROM ${table} WHERE ${whereVar.map((wv) => typeof wv === "string" ? `${wv} = $${wv}` : `${wv.field} = $${wv.variable}`).join(" AND ")}`;
+	},
+	create(idVar, dataVar) {
+		return `CREATE ONLY $${idVar} CONTENT $${dataVar}`;
+	},
+	createSet(idVar, keyDataVars) {
+		return `CREATE ONLY $${idVar} SET ${keyDataVars.map((keyDataVar) => typeof keyDataVar === "string" ? `${keyDataVar} = $${keyDataVar}` : "statement" in keyDataVar ? keyDataVar.statement : `${keyDataVar.key} = $${keyDataVar.variable}`).join(", ")}`;
+	},
+	upsert(idVar, dataVar) {
+		return `UPSERT ONLY $${idVar} REPLACE $${dataVar}`;
+	},
+	upsertMerge(idVar, dataVar) {
+		return `UPSERT ONLY $${idVar} MERGE $${dataVar}`;
+	},
+	updateMerge(idVar, dataVar) {
+		return `UPDATE ONLY $${idVar} MERGE $${dataVar}`;
+	},
+	updateSet(idVar, keyDataVar) {
+		return `UPDATE $${idVar} SET ${keyDataVar.map((kdv) => typeof kdv === "string" ? `${kdv} = $${kdv}` : "statement" in kdv ? kdv.statement : `${kdv.key} = $${kdv.variable}`).join(", ")}`;
+	},
+	delete(idVar) {
+		return `DELETE $${idVar}`;
+	},
+	let(name, query) {
+		return `LET $${name} = (${query})`;
+	},
+	createMutation(t, mutationIdVar, recordIdVar, dataVar, beforeRecordVar) {
+		switch (t) {
+			case "create": return dataVar ? `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}, data = $${dataVar}` : `CREATE ONLY $${mutationIdVar} SET mutationType = 'create', recordId = $${recordIdVar}`;
+			case "update": {
+				let stmt = `CREATE ONLY $${mutationIdVar} SET mutationType = 'update', recordId = $${recordIdVar}, data = $${dataVar}`;
+				if (beforeRecordVar) stmt += `, beforeRecord = $${beforeRecordVar}`;
+				return stmt;
+			}
+			case "delete": return `CREATE ONLY $${mutationIdVar} SET mutationType = 'delete', recordId = $${recordIdVar}`;
+		}
+	},
+	returnObject(entries) {
+		return `RETURN {${entries.map(({ key, variable }) => `${key}: $${variable}`).join(",")}}`;
+	}
+};
+
+//#endregion
+//#region src/modules/ref-tables.ts
+/**
+* Sentinel user id for unauthenticated clients when anonymous live queries are
+* enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+* so it can never collide with a real user id (those arrive as `user:<id>`);
+* both sides resolve it to the shared `_00_list_ref_anon` table.
+*/
+const ANON_USER_ID = "anon";
+/** The one `_00_list_ref` table every signed-out session shares. */
+const ANON_LIST_REF_TABLE = "_00_list_ref_anon";
+/**
+* Default ref-storage mode for this client build. Mirrors the SSP's
+* default (`RefMode::Dedicated`) so cross-session sync works out of the
+* box.
+*/
+const DEFAULT_REF_MODE = "dedicated";
+/**
+* Sanitize a user record id (e.g. `"user:abc"`) into the segment that
+* goes into a dedicated table name (e.g. `"abc"`). Returns `null` if
+* the id is missing the `user:` prefix or contains characters that
+* aren't valid in a SurrealDB table identifier — the server-side
+* `ssp_protocol::sanitize_user_id` uses the same predicate.
+*
+* Accepts both string ids (`"user:abc"`) and SurrealDB `RecordId`
+* objects (which only stringify cleanly via `.toString()`), since
+* `AuthService` passes the record-id object as-is to its subscribers.
+*/
+function sanitizeUserId(userId) {
+	if (userId === null || userId === void 0) return null;
+	const asString = typeof userId === "string" ? userId : typeof userId.toString === "function" ? userId.toString() : null;
+	if (!asString) return null;
+	const raw = asString.startsWith("user:") ? asString.slice(5) : asString;
+	if (raw.length === 0) return null;
+	if (!/^[A-Za-z0-9_]+$/.test(raw)) return null;
+	return raw;
+}
+/**
+* Resolve the LOCAL storage bucket id for a user. Every user gets their own
+* IndexedDB-backed local store (`indxdb://sp00ky-<bucketId>`) so cached rows,
+* query state, and the mutation outbox never leak across accounts on a shared
+* device. Signed-out sessions share the `anon` bucket.
+*
+* An id that fails sanitization still gets a DETERMINISTIC per-user bucket
+* (cyrb53 hex of the raw id) — falling back to `anon` here would put an
+* authenticated user in the shared bucket and recreate the cross-user leak.
+*/
+function bucketIdForUser(userId) {
+	if (userId === null || userId === void 0 || userId === ANON_USER_ID) return ANON_USER_ID;
+	const uid = sanitizeUserId(userId);
+	if (uid) return uid;
+	return `u${cyrb53(String(userId)).toString(16)}`;
+}
+/**
+* Returns the `_00_list_ref` table name for `(mode, userId)`. Falls
+* back to the global `_00_list_ref` when sanitization fails or in
+* single mode.
+*/
+function listRefTableFor(mode, userId) {
+	if (userId === ANON_USER_ID) return ANON_LIST_REF_TABLE;
+	if (mode === "single") return "_00_list_ref";
+	const uid = sanitizeUserId(userId);
+	return uid ? `_00_list_ref_user_${uid}` : "_00_list_ref";
+}
+
+//#endregion
+//#region src/query/sql.ts
+/** Every SurrealQL statement the query side sends, as pure builders. */
+const VIEW_TABLE = "_00_view";
+const LEGACY_VIEW_TABLE = "_00_window";
+const viewRecordId = (viewKey) => new RecordId(VIEW_TABLE, viewKey);
+/**
+* The durable `_00_view` row: the confirmed membership plus the subquery
+* children, which the GC must keep and a cold scan may paint as much as the
+* members.
+*/
+const viewRow = (ids, children, confirmed, now) => ({
+	ids,
+	children,
+	confirmed,
+	updatedAt: now
+});
+/** Every `_00_view` row: the durable view index and the GC read it. */
+const readViewRows = () => `SELECT * FROM ${VIEW_TABLE}`;
+/** Copy every legacy `_00_window` row into `_00_view` once. */
+const readLegacyViewRows = () => `SELECT * FROM ${LEGACY_VIEW_TABLE}`;
+const countViewRows = () => `SELECT count() FROM ${VIEW_TABLE} GROUP ALL`;
+const listRefSelect = (table) => `SELECT out, version FROM $in->${table} WHERE parent IS NONE`;
+const subqueryListRefSelect = (table) => `SELECT out, version FROM $in->${table} WHERE parent IS NOT NONE`;
+const queryRowCountSelect = () => "SELECT VALUE { rowCount: rowCount, state: state } FROM ONLY $in";
+const listRefBatchSelect = (table) => `SELECT in, out, version, parent FROM $ins->${table}`;
+const queryRowCountBatchSelect = () => "SELECT VALUE { id: id, rowCount: rowCount, state: state } FROM $ins";
+/** The single-query read: edges, meta, subquery children in one request. */
+const singleSnapshotSelect = (table) => `${listRefSelect(table)};\n${queryRowCountSelect()};\n${subqueryListRefSelect(table)}`;
+/** The many-query read: all edges + all metas in one request. */
+const batchSnapshotSelect = (table) => `${listRefBatchSelect(table)};\n${queryRowCountBatchSelect()}`;
+/**
+* The session's one LIVE subscription on its `_00_list_ref` table.
+*
+* `inlineBodies` adds `FETCH out`, which resolves the edge's target into the
+* notification so the body arrives with the doorbell.
+*
+* On the anon table it is filtered to this client's own edges. Every
+* signed-out session shares that table, so unfiltered each one received (and
+* the server fetched a body for) every anonymous edge change of every other
+* session, and the client then dropped all but its own. An edge carries the
+* `session::id()` of whichever socket last registered its view, which is a
+* socket of this client but not necessarily the current one: a view stays
+* registered across a reconnect, and a reload keeps its salt and its views,
+* so their older edges still name an earlier socket. `sessionIds` are those
+* earlier sockets. The current one is matched by `session::id()` itself,
+* which SurrealDB evaluates in the subscriber's own session, so the filter
+* holds before the client has learned its new id.
+*
+* The cast is load-bearing: `session::id()` is a uuid, `clientId` a string,
+* and without it nothing matches. Per-user tables need no filter.
+*/
+function listRefLive(table, opts) {
+	const join = opts.inlineBodies ? " FETCH out" : "";
+	if (table !== ANON_LIST_REF_TABLE) return { sql: `LIVE SELECT * FROM ${table}${join}` };
+	return {
+		sql: `LIVE SELECT * FROM ${table} WHERE clientId = <string>session::id() OR clientId IN $sids${join}`,
+		vars: { sids: [...opts.sessionIds] }
+	};
+}
+/** Register + read back edges/meta/children in ONE request. */
+const registerSelect = (table) => `fn::query::register($config);\n${singleSnapshotSelect(table)}`;
+const registerVars = (payload) => ({
+	config: payload,
+	in: payload.id
+});
+/** One heartbeat statement per view id; result index i answers id i. */
+function heartbeatBatch(ids) {
+	const vars = {};
+	return {
+		sql: ids.map((id, i) => {
+			vars[`id${i}`] = id;
+			return `fn::query::heartbeat($id${i})`;
+		}).join(";\n"),
+		vars
+	};
+}
+/** A heartbeat answer whose statement matched no row: the view was reclaimed. */
+const heartbeatRowGone = (result) => Array.isArray(result) && result.length === 0;
+const QUERY_ID = /^_00_query:(?:[0-9a-f]{64}|⟨[0-9a-f]{64}⟩)$/;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* The pagehide release: one bare statement for `beaconSql`, which has no params
+* channel, so ids are inlined. Only shapes the client minted itself get in, a
+* `_00_query:<sha256>` id and a UUID session id, so nothing else is ever
+* interpolated. `null` when there is nothing the server could act on: with no
+* session ids it could not tell this page's entries from anyone else's.
+*/
+function leaveViewsBeacon(ids, sessionIds) {
+	const list = ids.map((id) => String(id)).filter((id) => QUERY_ID.test(id));
+	const sids = sessionIds.filter((sid) => SESSION_ID.test(sid));
+	if (list.length === 0 || sids.length === 0) return null;
+	const sidList = sids.map((sid) => `'${sid}'`).join(", ");
+	return `FOR $id IN [${list.join(", ")}] { LET $_left = fn::query::leave($id, [${sidList}]); };`;
+}
+const bodySelect = () => "SELECT * FROM $ids";
+/** Local transaction that MERGEs many fetched bodies. */
+function upsertBodiesTx(records) {
+	const vars = {};
+	const stmts = records.map((r, i) => {
+		vars[`id${i}`] = r.id;
+		vars[`content${i}`] = r.content;
+		return surql.upsertMerge(`id${i}`, `content${i}`);
+	});
+	return {
+		query: surql.seal(surql.tx(stmts)),
+		vars
+	};
+}
+
+//#endregion
+//#region src/utils/parser.ts
+/**
+* Parse a QUERY's params. Unlike a record's fields, a param name is not always a
+* column: an `_or` branch binds under a synthetic `white__or0` (see
+* `orParamName` in @spooky-sync/query-builder), and the surql that references it
+* is already written. So resolve the column through the synthetic name, and keep
+* a param we cannot type rather than dropping it.
+*
+* Dropping was the bug: `parseParams` kept only column-named params, so every
+* `_or` query registered with `$or0`/`$or1` unbound and matched no rows at all,
+* silently (rowCount 0, errorCount 0).
+*/
+function parseQueryParams(tableSchema, params) {
+	const parsedParams = {};
+	for (const [key, value] of Object.entries(params)) {
+		if (value === void 0) continue;
+		const column = tableSchema[key] ?? tableSchema[baseFieldOfParam(key)];
+		parsedParams[key] = column ? parseValue(key, column, value) : value;
+	}
+	return parsedParams;
+}
+function parseValue(name, column, value) {
+	if (column.recordId) {
+		if (value instanceof RecordId$1) return value;
+		if (typeof value === "string") return parseRecordIdString(value);
+		throw new Error(`Invalid value for ${name}: ${value}`);
+	}
+	if (column.dateTime) {
+		if (value instanceof Date) return value;
+		if (value instanceof DateTime) return value.toDate();
+		if (typeof value === "number" || typeof value === "string") return new Date(value);
+		throw new Error(`Invalid value for ${name}: ${value}`);
+	}
+	return value;
+}
+
+//#endregion
+//#region src/utils/index.ts
+const encodeRecordId = (recordId) => {
+	return `${recordId.table.name}:${recordId.id}`;
+};
+const parseRecordIdString = (id) => {
+	const [table, ...idParts] = id.split(":");
+	return new RecordId(table, idParts.join(":"));
+};
+/**
+* 32 random bytes, hex: the secret a page proves it owns its anonymous views
+* with (`$config.owner` on `fn::query::register`). `getRandomValues` rather
+* than `randomUUID`, which a page served over plain http does not have.
+*/
+function mintOwnerSecret() {
+	const bytes = new Uint8Array(32);
+	globalThis.crypto.getRandomValues(bytes);
+	return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* Read the millisecond count off a surrealdb `Duration`. Different `surrealdb`
+* releases expose it under `milliseconds` (current) or the older private
+* `_milliseconds` field, so read whichever is set; returns 0 when neither is.
+*/
+function durationMillis(duration) {
+	const d = duration;
+	return Number(d.milliseconds || d._milliseconds || 0);
+}
+/**
+* Parse duration string or Duration object to milliseconds
+*/
+function parseDuration(duration) {
+	if (duration instanceof Duration) {
+		const ms = durationMillis(duration);
+		if (ms) return ms;
+		const str = duration.toString();
+		if (str !== "[object Object]") return parseDuration(str);
+		return 6e5;
+	}
+	if (typeof duration === "bigint") return Number(duration);
+	if (typeof duration !== "string") return 6e5;
+	const match = duration.match(/^(\d+)([smh])$/);
+	if (!match) return 6e5;
+	const val = Number.parseInt(match[1], 10);
+	switch (match[2]) {
+		case "s": return val * 1e3;
+		case "h": return val * 36e5;
+		default: return val * 6e4;
+	}
+}
+/**
+* Reject after `timeoutMs` if `promise` hasn't settled.
+*
+* Exists because a WebSocket RPC has no deadline of its own: the SurrealDB SDK
+* parks each call in a pending map and only rejects it when the socket reports
+* a close. On a half-open socket (peer gone, no `close` event, `readyState`
+* still OPEN) the call never settles at all, which wedges anything serialized
+* behind it.
+*
+* `message` MUST contain "timed out" so `classifySyncError` treats the
+* rejection as `network` — that's what makes the sync queues retry the
+* operation instead of rolling the mutation back as an application error.
+*
+* Non-positive `timeoutMs` returns `promise` unchanged. The underlying promise
+* is NOT cancelled (nothing can cancel an in-flight RPC); its eventual
+* settlement is absorbed, so attach no expectations to it after a timeout.
+*/
+function withTimeout(promise, timeoutMs, message) {
+	if (!(timeoutMs > 0)) return promise;
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(typeof message === "function" ? message() : new Error(message)), timeoutMs);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+
+//#endregion
+//#region src/query/membership.ts
+function metaFromRow(row) {
+	if (!row || typeof row !== "object") return {
+		present: false,
+		rowCount: null,
+		state: null
+	};
+	const state = row.state === "materializing" || row.state === "ready" ? row.state : null;
+	return {
+		present: true,
+		rowCount: typeof row.rowCount === "number" ? row.rowCount : null,
+		state
+	};
+}
+/** Collapse duplicate `(id, version)` pairs to one per id, keeping the highest version. */
+function dedupeRecordVersions(pairs) {
+	if (pairs.length < 2) return pairs;
+	const best = /* @__PURE__ */ new Map();
+	for (const [id, version] of pairs) {
+		const prev = best.get(id);
+		if (prev === void 0 || version > prev) best.set(id, version);
+	}
+	if (best.size === pairs.length) return pairs;
+	return Array.from(best.entries());
+}
+/**
+* A statement that did not answer (an ERR, or no result at all). Kept apart
+* from a `null` result, which is the server saying "no such row": reading a
+* failed statement as a missing row turned every timeout under load into a
+* lost view and re-registered it, over and over (whitepawn, 2026-09-16).
+*/
+const FAILED = Symbol("statement failed");
+const toPairs = (rows) => dedupeRecordVersions(Array.isArray(rows) ? rows.map((r) => [encodeRecordId(r.out), r.version]) : []);
+/**
+* Fold the single-query statement batch (edges, meta, children) into a
+* snapshot. `null` when any of the three did not answer: half an answer is
+* not one, and a missing meta would read as a lost view.
+*/
+function snapshotFromSingle(items, metaRow, children) {
+	if (!Array.isArray(items) || metaRow === FAILED || children === FAILED) return null;
+	return {
+		primary: toPairs(items),
+		subquery: toPairs(children),
+		meta: metaFromRow(metaRow)
+	};
+}
+
+//#endregion
+//#region src/utils/edges.ts
+/**
+* Reading `_00_list_ref` edges as a LIVE notification delivers them. Pure, so
+* both the full client and the wasm-free live feed (`@spooky-sync/core/live`)
+* decode the same wire shape the same way.
+*/
+/** The hash a `_00_list_ref` edge belongs to: the id part of its `in` (`_00_query:<hash>`). */
+function hashOfEdge(value) {
+	const inId = value?.in;
+	if (!inId) return null;
+	const str = inId instanceof RecordId ? String(inId.id) : String(inId).replace(/^_00_query:/, "");
+	return str.length > 0 ? str : null;
+}
+/**
+* The row an edge notification carries, when the subscription joined it on.
+*
+* Without `FETCH out` the edge's `out` is a record id and there is nothing to
+* land, so this returns null and the caller falls back to fetching the body.
+* It also returns null for a row the session may not read (the join yields
+* `out: null`) and for an edge whose target has been deleted.
+*/
+function rowOfEdge(value) {
+	const edge = value;
+	const out = edge?.out;
+	if (!out || typeof out !== "object" || Array.isArray(out) || out instanceof RecordId) return null;
+	const rid = out.id;
+	if (!(rid instanceof RecordId)) return null;
+	const id = encodeRecordId(rid);
+	const version = typeof edge?.version === "number" ? edge.version : null;
+	if (version === null) return null;
+	return {
+		id,
+		version,
+		record: out
+	};
+}
+
+//#endregion
+export { singleSnapshotSelect as A, sanitizeUserId as B, listRefSelect as C, readViewRows as D, readLegacyViewRows as E, ANON_LIST_REF_TABLE as F, sha256Hex as H, ANON_USER_ID as I, DEFAULT_REF_MODE as L, upsertBodiesTx as M, viewRecordId as N, registerSelect as O, viewRow as P, bucketIdForUser as R, listRefLive as S, queryRowCountSelect as T, queryHashInput as U, surql as V, viewKeyInput as W, countViewRows as _, metaFromRow as a, leaveViewsBeacon as b, mintOwnerSecret as c, withTimeout as d, parseQueryParams as f, bodySelect as g, batchSnapshotSelect as h, dedupeRecordVersions as i, subqueryListRefSelect as j, registerVars as k, parseDuration as l, VIEW_TABLE as m, rowOfEdge as n, snapshotFromSingle as o, LEGACY_VIEW_TABLE as p, FAILED as r, encodeRecordId as s, hashOfEdge as t, parseRecordIdString as u, heartbeatBatch as v, queryRowCountBatchSelect as w, listRefBatchSelect as x, heartbeatRowGone as y, listRefTableFor as z };

package/dist/worker-impersonation.js

@@ -0,0 +1,60 @@
+//#region src/modules/auth/impersonation.ts
+/**
+* Admin impersonation, client side.
+*
+* The server does the enforcing (see `impersonation_remote.surql` in the CLI):
+* an admin calls `fn::_00_impersonate::start`, receives a token for the
+* `_00_impersonate` access method, and authenticates with it, so `$auth.id` is
+* the target user. Everything here is state and timers around that:
+*
+* - the admin's own token is kept under {@link ORIGIN_TOKEN_KEY} so Stop (and a
+*   reload in between) can return to it;
+* - the impersonation state is derived from the token's claims, never stored
+*   separately, so it cannot disagree with the session actually in use;
+* - the token is re-signed before it expires, and the session is polled so a
+*   stop or revocation made elsewhere reaches an open WebSocket quickly.
+*/
+/** Access method impersonation tokens are issued for. */
+const IMPERSONATION_ACCESS = "_00_impersonate";
+/**
+* Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+* server still enforces the token on every request; this is only so the client
+* can act on what it already holds before a round trip completes.
+*
+* Returns nulls on any malformed input.
+*/
+function decodeTokenClaims(token) {
+	const none = {
+		access: null,
+		userId: null,
+		exp: null,
+		impersonation: null
+	};
+	try {
+		const payload = token.split(".")[1];
+		if (!payload) return none;
+		let b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+		b64 += "=".repeat((4 - b64.length % 4) % 4);
+		const json = typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("binary");
+		const claims = JSON.parse(json);
+		const ac = claims.AC ?? claims.ac;
+		const id = claims.ID ?? claims.id;
+		const access = typeof ac === "string" ? ac : null;
+		const session = claims.spky_imp;
+		const admin = claims.spky_admin;
+		return {
+			access,
+			userId: typeof id === "string" ? id : null,
+			exp: typeof claims.exp === "number" ? claims.exp : null,
+			impersonation: access === IMPERSONATION_ACCESS && typeof session === "string" && typeof admin === "string" ? {
+				session,
+				admin
+			} : null
+		};
+	} catch {
+		return none;
+	}
+}
+
+//#endregion
+export { decodeTokenClaims as n, IMPERSONATION_ACCESS as t };

package/dist/worker-ref-tables.d.ts

@@ -0,0 +1,48 @@
+//#region src/modules/ref-tables.d.ts
+type RefMode = 'single' | 'dedicated';
+/**
+ * Sentinel user id for unauthenticated clients when anonymous live queries are
+ * enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+ * so it can never collide with a real user id (those arrive as `user:<id>`);
+ * both sides resolve it to the shared `_00_list_ref_anon` table.
+ */
+declare const ANON_USER_ID = "anon";
+/** The one `_00_list_ref` table every signed-out session shares. */
+declare const ANON_LIST_REF_TABLE = "_00_list_ref_anon";
+/**
+ * Default ref-storage mode for this client build. Mirrors the SSP's
+ * default (`RefMode::Dedicated`) so cross-session sync works out of the
+ * box.
+ */
+declare const DEFAULT_REF_MODE: RefMode;
+/**
+ * Sanitize a user record id (e.g. `"user:abc"`) into the segment that
+ * goes into a dedicated table name (e.g. `"abc"`). Returns `null` if
+ * the id is missing the `user:` prefix or contains characters that
+ * aren't valid in a SurrealDB table identifier — the server-side
+ * `ssp_protocol::sanitize_user_id` uses the same predicate.
+ *
+ * Accepts both string ids (`"user:abc"`) and SurrealDB `RecordId`
+ * objects (which only stringify cleanly via `.toString()`), since
+ * `AuthService` passes the record-id object as-is to its subscribers.
+ */
+declare function sanitizeUserId(userId: unknown): string | null;
+/**
+ * Resolve the LOCAL storage bucket id for a user. Every user gets their own
+ * IndexedDB-backed local store (`indxdb://sp00ky-<bucketId>`) so cached rows,
+ * query state, and the mutation outbox never leak across accounts on a shared
+ * device. Signed-out sessions share the `anon` bucket.
+ *
+ * An id that fails sanitization still gets a DETERMINISTIC per-user bucket
+ * (cyrb53 hex of the raw id) — falling back to `anon` here would put an
+ * authenticated user in the shared bucket and recreate the cross-user leak.
+ */
+declare function bucketIdForUser(userId: unknown): string;
+/**
+ * Returns the `_00_list_ref` table name for `(mode, userId)`. Falls
+ * back to the global `_00_list_ref` when sanitization fails or in
+ * single mode.
+ */
+declare function listRefTableFor(mode: RefMode, userId: unknown): string;
+//#endregion
+export { bucketIdForUser as a, RefMode as i, ANON_USER_ID as n, listRefTableFor as o, DEFAULT_REF_MODE as r, sanitizeUserId as s, ANON_LIST_REF_TABLE as t };