@rindle/room 0.5.0

package/src/token.ts

@@ -0,0 +1,219 @@
+/**
+ * The room's **self-authorizing signed lease token** (RINDLE-REALTIME-DESIGN.md §10.1).
+ *
+ * The API server is the authority (§4): it authenticates the user, resolves the named
+ * query to an approved AST, and signs this token. The token then IS the lease — the
+ * room materializes on first presentation, so no pre-placement `/materialize` control
+ * call ever touches it (the §10.1 inversion; on the DO shell the Worker verifies the
+ * same signature statelessly before `get(id)`).
+ *
+ * Shape: `rt1.<base64url(payload)>.<base64url(hmac-sha256(prefix.payload))>` with
+ * payload `{ v: 1, doc, ast, sub, iat, exp, kid }`:
+ *
+ * - `doc` — the room/document id the token authorizes (a token for one room presented
+ *   to another is refused);
+ * - `ast` — the approved wire `Ast` (the client never composes this; §4's "ASTs never
+ *   cross the public wire" holds because the token is opaque TO THE CLIENT — it carries
+ *   it, it cannot mint or alter it);
+ * - `sub` — the subject (user id): the revocation key (§4.1);
+ * - `iat`/`exp` — issued-at / expiry, ms epoch. Renewal is re-authorization: clients
+ *   obtain a fresh token through the API server, never extend this one. `iat` is what
+ *   lets a revocation refuse pre-revocation tokens while a genuine re-grant (a newer
+ *   token) passes immediately;
+ * - `kid` — which shared secret signed it (rotation).
+ *
+ * HMAC via WebCrypto (`crypto.subtle`) so the exact same code verifies in Node (the
+ * test shell) and in a Cloudflare Worker/DO (P4) — no `node:crypto` import.
+ */
+
+export interface RoomTokenPayload {
+  v: 1;
+  doc: string;
+  ast: unknown;
+  sub: string;
+  iat: number;
+  exp: number;
+  kid: string;
+  /** A short fingerprint of the room's compiled scope specs at mint time
+   *  ({@link scopeSpecsHash}). Advisory, not a credential: the room's §3.3 gate is the
+   *  contract regardless. It lets the shell detect SCOPE SKEW — a room profile edited
+   *  while a room is already live arms the gate with the OLD specs (a one-shot at boot)
+   *  while fresh leases prove against the NEW ones, so every routed write silently
+   *  deopt-loops. Optional so a pre-stamp api-server / older token still verifies. */
+  scopesHash?: string;
+}
+
+export interface MintRoomTokenOptions {
+  doc: string;
+  ast: unknown;
+  /** The subject (user id) this token authorizes — the §4.1 revocation key. */
+  sub: string;
+  /** Key id + its secret (utf-8; give every room the same `keys` map). */
+  kid: string;
+  key: string;
+  /** Expiry, ms from `now`. Keep short (minutes) — the §4.1 TTL backstop. */
+  ttlMs: number;
+  /** Mint time; defaults to `Date.now()`. Injectable for tests. */
+  now?: number;
+  /** The room's {@link scopeSpecsHash} for the profile this lease serves — stamped so the
+   *  shell can flag scope skew (see {@link RoomTokenPayload.scopesHash}). Omit to not stamp. */
+  scopesHash?: string;
+}
+
+const PREFIX = "rt1";
+
+/** Canonical JSON: object keys sorted recursively (arrays keep order), so structurally
+ *  identical specs serialize identically regardless of key INSERTION order across code
+ *  versions — a cosmetic reorder must not read as a scope change. `undefined`-valued keys
+ *  are dropped, matching `JSON.stringify` and the `footprintWhere?`/`where?` optionals. */
+function canonicalJson(v: unknown): string {
+  if (v === undefined) return "null";
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(",")}]`;
+  const o = v as Record<string, unknown>;
+  const keys = Object.keys(o)
+    .filter((k) => o[k] !== undefined)
+    .sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(",")}}`;
+}
+
+/** A stable short fingerprint of the compiled scope specs — the scope-skew tripwire.
+ *  NOT security (the gate re-proves every write): FNV-1a-32 over the {@link canonicalJson}
+ *  form, 8 hex chars. Both the api-server (stamping the lease token) and the room shell
+ *  (hashing the boot-wire scopes it armed the gate with) run this over the SAME compiler
+ *  output, so an unchanged profile ⇒ equal hash and a profile edited under a live room ⇒
+ *  mismatch. A collision only costs a missed diagnostic, never correctness. Accepts either
+ *  wire's spec array (`RoomScopeSpec[]` / `RoomTableSpec[]` — structurally identical). */
+export function scopeSpecsHash(specs: readonly unknown[]): string {
+  const json = canonicalJson(specs);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < json.length; i++) {
+    h ^= json.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+function b64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// Return type inferred (`Uint8Array<ArrayBuffer>` under TS ≥5.7 libs) — an explicit
+// `Uint8Array` annotation widens to `ArrayBufferLike` and fails `crypto.subtle`'s
+// `BufferSource` under consumers compiling this source with newer lib types (the DO shell).
+function unb64url(s: string) {
+  const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/"));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// Return type inferred: this package's tsconfig has no DOM lib, so the WebCrypto
+// interface names aren't ambient — but `crypto.subtle`'s own types carry through.
+async function hmacKey(secret: string, usage: "sign" | "verify") {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    [usage],
+  );
+}
+
+/** Sign a room lease token. This runs on the API-server side (or a test playing it). */
+export async function mintRoomToken(opts: MintRoomTokenOptions): Promise<string> {
+  const now = opts.now ?? Date.now();
+  const payload: RoomTokenPayload = {
+    v: 1,
+    doc: opts.doc,
+    ast: opts.ast,
+    sub: opts.sub,
+    iat: now,
+    exp: now + opts.ttlMs,
+    kid: opts.kid,
+    // Stamped only when supplied — an unstamped mint keeps the pre-scopesHash byte shape.
+    ...(opts.scopesHash !== undefined ? { scopesHash: opts.scopesHash } : {}),
+  };
+  const body = b64url(new TextEncoder().encode(JSON.stringify(payload)));
+  const signed = `${PREFIX}.${body}`;
+  const key = await hmacKey(opts.key, "sign");
+  const sig = new Uint8Array(
+    await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(signed)),
+  );
+  return `${signed}.${b64url(sig)}`;
+}
+
+/** Why a token was refused. The `reason` is terse and safe to echo in a queryError. */
+export class RoomTokenError extends Error {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(`lease token refused: ${reason}`);
+    this.reason = reason;
+  }
+}
+
+export interface VerifyRoomTokenOptions {
+  /** The room's own doc id — a token for any other doc is refused. */
+  doc: string;
+  /** kid → shared secret. Unknown kids are refused (never "try them all"). */
+  keys: Record<string, string>;
+  /** Verification time; defaults to `Date.now()`. Injectable for tests. */
+  now?: number;
+}
+
+/**
+ * Verify a token's signature and claims; returns the payload (with the approved AST)
+ * or throws {@link RoomTokenError}. Signature is checked FIRST — no claim is trusted
+ * (not even `kid`'s existence beyond the key lookup) before the MAC passes.
+ */
+export async function verifyRoomToken(
+  token: string,
+  opts: VerifyRoomTokenOptions,
+): Promise<RoomTokenPayload> {
+  const now = opts.now ?? Date.now();
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts[0] !== PREFIX) {
+    throw new RoomTokenError("not a room token");
+  }
+  const [, body, sig] = parts;
+
+  // Parse only far enough to find `kid` (the signature covers everything, so a lying
+  // kid can only select a key that then fails the MAC).
+  let payload: RoomTokenPayload;
+  try {
+    payload = JSON.parse(new TextDecoder().decode(unb64url(body))) as RoomTokenPayload;
+  } catch {
+    throw new RoomTokenError("malformed payload");
+  }
+  const secret = typeof payload.kid === "string" ? opts.keys[payload.kid] : undefined;
+  if (secret === undefined) {
+    throw new RoomTokenError("unknown key id");
+  }
+  const key = await hmacKey(secret, "verify");
+  const ok = await crypto.subtle.verify(
+    "HMAC",
+    key,
+    unb64url(sig),
+    new TextEncoder().encode(`${PREFIX}.${body}`),
+  );
+  if (!ok) {
+    throw new RoomTokenError("bad signature");
+  }
+
+  if (payload.v !== 1) throw new RoomTokenError("unknown version");
+  if (payload.doc !== opts.doc) throw new RoomTokenError("token is for another doc");
+  if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+    throw new RoomTokenError("missing subject");
+  }
+  if (typeof payload.exp !== "number" || now >= payload.exp) {
+    throw new RoomTokenError("expired lease");
+  }
+  if (typeof payload.iat !== "number") throw new RoomTokenError("missing iat");
+  if (payload.ast === undefined || payload.ast === null) {
+    throw new RoomTokenError("missing ast");
+  }
+  return payload;
+}

package/src/wasm.ts

@@ -0,0 +1,32 @@
+// Loader for the room wasm artifact (pkg/, built by ./build.sh) — the same init-once
+// pattern as @rindle/wasm: a `--target web` ESM artifact needs one explicit init before
+// the classes are usable. Node reads the bytes from the package; a browser/Worker host
+// fetches (or passes a precompiled module).
+
+import init, { WasmRoom } from "../pkg/rindle_room.js";
+
+export { WasmRoom };
+
+let initialized: Promise<void> | null = null;
+
+/** Initialize the room wasm module (idempotent). Call once before `WasmRoom.open`.
+ *  Node: bytes are read from the package. Browser/bundler: the wasm is fetched. Pass
+ *  `moduleOrPath` to override (a `WebAssembly.Module`, URL, or bytes). */
+export function initRoomWasm(moduleOrPath?: unknown): Promise<void> {
+  if (!initialized) {
+    initialized = (async () => {
+      if (moduleOrPath !== undefined) {
+        await init({ module_or_path: moduleOrPath });
+      } else if (
+        (globalThis as { process?: { versions?: { node?: string } } }).process?.versions?.node
+      ) {
+        const { readFile } = await import("node:fs/promises");
+        const bytes = await readFile(new URL("../pkg/rindle_room_bg.wasm", import.meta.url));
+        await init({ module_or_path: bytes });
+      } else {
+        await init();
+      }
+    })();
+  }
+  return initialized;
+}