@displayxr/inline3d 1.47.6 → 1.49.0

package/signaling/dev-server.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+// signaling/dev-server.mjs — a zero-dependency Node server for the `dxr-signal/1` protocol, for
+// local development and the test suite. Same room logic (./room.mjs) and the same admission —
+// keys, rate limits, room leases, the TURN budget (./gate.mjs) — as the Cloudflare Worker; only
+// the socket plumbing and where the counters live differ. NOT for production: one process, rooms
+// and counters in memory, no TLS.
+//
+//   node signaling/dev-server.mjs [--port 8787] [--cap 4] [--keys keys.json]
+//   → ws://localhost:8787/v1/connect?k=<sha256(room)>[&key=pk_…]
+//
+// Optional TURN (same variables as the Worker): TURN_KEY_ID, TURN_KEY_API_TOKEN, TURN_TTL. The
+// limit and budget variables (README.md) are read from the environment too; `--keys` is a JSON
+// object `{ "pk_…": { "origins": [...] } }` for keyed sessions.
+//
+// The WebSocket framing below is the minimal RFC 6455 server subset: the upgrade handshake,
+// masked client frames (text, continuation, ping/pong, close), unmasked server text frames. That
+// is all a JSON signalling channel needs, and it keeps `npm install` out of a dev loop.
+
+import { createServer } from 'node:http';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { Room, DEFAULT_ROOM_CAP, MAX_MESSAGE_BYTES, mintTurnCredentials, refuseConn } from './room.mjs';
+import { Meter, limitsFromEnv } from './limits.mjs';
+import { TurnBudget, budgetFromEnv } from './turn-budget.mjs';
+import { mapKeyStore } from './keys.mjs';
+import { createGate } from './gate.mjs';
+
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const KEY_RE = /^[0-9a-f]{64}$/;
+const IDLE_MS = 60_000;
+
+/**
+ * Start a dev server. Resolves once listening.
+ * @param {{port?: number, host?: string, cap?: number, env?: object, keys?: Map<string, object>|object,
+ *          turn?: ((session: object|null) => Promise<object[]|null>)|null, blocklist?: Set<string>,
+ *          log?: (s: string) => void}} [opts]
+ *        `turn`: a minter to use instead of Cloudflare (tests: fake TURN without a token).
+ * @returns {Promise<{port: number, url: string, rooms: Map<string, Room>, budget: TurnBudget, meters: Map<string, Meter>, close(): Promise<void>}>}
+ */
+export function startDevServer({ port = 8787, host = '127.0.0.1', cap = DEFAULT_ROOM_CAP, env = process.env, keys = null, turn = undefined, blocklist = null, log = () => {} } = {}) {
+  /** @type {Map<string, Room>} */
+  const rooms = new Map();
+  const timers = new Map(); // room key -> lifetime timer
+  const sockets = new Set();
+  const raw = new Set(); // every upgraded TCP socket, destroyed on shutdown
+  const budget = new TurnBudget({ cfg: budgetFromEnv(env) });
+  /** @type {Map<string, Meter>} */
+  const meters = new Map();
+  const meterOf = (subject) => {
+    let m = meters.get(subject);
+    if (!m) meters.set(subject, (m = new Meter()));
+    return m;
+  };
+  const gate = createGate({
+    limits: limitsFromEnv(env),
+    keys: keys ? mapKeyStore(keys) : null,
+    budget: { snapshot: () => budget.snapshot(), cfg: budget.cfg },
+    meters: { exec: (subject, cmd) => meterOf(subject).exec(cmd) },
+    blocklist: blocklist ? { has: (ip) => blocklist.has(ip) } : null,
+    salt: env.RATE_SALT || '',
+  });
+  const cfTurn = env.TURN_KEY_ID && env.TURN_KEY_API_TOKEN;
+  const minter =
+    turn !== undefined
+      ? turn
+      : cfTurn
+        ? (s) => mintTurnCredentials(env, undefined, { ttl: s && s.turn && s.turn.ttl > 0 ? s.turn.ttl : undefined, customIdentifier: (s && s.key) || 'anon' })
+        : null;
+  const ice = minter
+    ? async (s) => {
+        const r = await minter(s);
+        if (r) budget.recordMint(s ? s.key : null, s && s.turn && s.turn.ttl > 0 ? s.turn.ttl : parseInt(env.TURN_TTL || '3600', 10) || 3600);
+        return r;
+      }
+    : null;
+
+  const server = createServer((req, res) => {
+    const u = new URL(req.url, 'http://x');
+    if (u.pathname === '/' || u.pathname === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
+      res.end(JSON.stringify({ ok: true, protocol: 'dxr-signal/1', rooms: rooms.size, turn: ice ? budget.snapshot().status : 'unconfigured', keys: !!keys }));
+      return;
+    }
+    res.writeHead(426, { 'Content-Type': 'text/plain' });
+    res.end('WebSocket endpoint: /v1/connect?k=<sha256(room) hex>\n');
+  });
+
+  server.on('upgrade', (req, socket) => {
+    const u = new URL(req.url, 'http://x');
+    const key = u.searchParams.get('k') || '';
+    const wsKey = req.headers['sec-websocket-key'];
+    if (u.pathname !== '/v1/connect' || !KEY_RE.test(key) || !wsKey || String(req.headers.upgrade).toLowerCase() !== 'websocket') {
+      socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+      return;
+    }
+    const accept = createHash('sha1').update(wsKey + WS_GUID).digest('base64');
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
+        `Sec-WebSocket-Accept: ${accept}\r\n\r\n`
+    );
+    socket.setNoDelay(true);
+    raw.add(socket);
+    socket.on('close', () => raw.delete(socket));
+    let session = null;
+    let room = null;
+    let early = []; // messages that arrive while admission is still deciding (a join sent on open)
+    const conn = wrapSocket(socket, {
+      onText: (text) => (room ? room.onMessage(conn, text).catch(() => {}) : early && early.push(text)),
+      onClose: () => {
+        sockets.delete(conn);
+        if (room) {
+          room.onClose(conn);
+          if (room.size === 0 && rooms.get(key) === room) rooms.delete(key);
+        }
+        if (session) gate.release(session).catch(() => {});
+      },
+    });
+    sockets.add(conn);
+    gate
+      .admit({ ip: socket.remoteAddress || '', origin: String(req.headers.origin || ''), key: u.searchParams.get('key') || null, roomKey: key, wantTurn: !!ice })
+      .then((a) => {
+        if (!a.ok) {
+          log(`refuse ${a.code} k=${key.slice(0, 8)}…`);
+          return refuseConn(conn, a);
+        }
+        session = a.session;
+        budget.recordJoin(session.key);
+        room = rooms.get(key);
+        if (!room) {
+          const r = new Room({
+            key,
+            cap,
+            iceServers: ice,
+            hooks: {
+              onFirst: (s) => {
+                clearTimeout(timers.get(key));
+                const ttlS = s && s.roomTtlS > 0 ? s.roomTtlS : limitsFromEnv(env).anon.roomTtlS;
+                const t = setTimeout(() => r.expire(), ttlS * 1000);
+                t.unref();
+                timers.set(key, t);
+              },
+              onEmpty: () => {
+                clearTimeout(timers.get(key));
+                timers.delete(key);
+              },
+            },
+          });
+          rooms.set(key, r);
+          room = r;
+        }
+        room.attach(conn, session);
+        log(`connect k=${key.slice(0, 8)}… ${session.tier}${session.key ? ' ' + session.key : ''} (${rooms.size} rooms)`);
+        const replay = early;
+        early = null;
+        for (const text of replay) room.onMessage(conn, text).catch(() => {});
+      })
+      .catch(() => {
+        early = null;
+        refuseConn(conn, { code: 'bad-message', message: 'admission failed', closeCode: 4000 });
+      });
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      const addr = server.address();
+      const p = typeof addr === 'object' && addr ? addr.port : port;
+      resolve({
+        port: p,
+        url: `ws://${host === '0.0.0.0' ? 'localhost' : host}:${p}`,
+        rooms,
+        budget,
+        meters,
+        close: () =>
+          new Promise((done) => {
+            for (const t of timers.values()) clearTimeout(t);
+            for (const c of sockets) c.close(1001, 'server shutting down');
+            for (const s of raw) s.destroy();
+            server.close(() => done());
+          }),
+      });
+    });
+  });
+}
+
+/** Wrap a raw upgraded socket as a `{send(obj), close(code, reason)}` connection. */
+function wrapSocket(socket, { onText, onClose }) {
+  let buf = Buffer.alloc(0);
+  let frag = null; // continuation assembly: { chunks: Buffer[] }
+  let closed = false;
+  let idle = setTimeout(() => conn.close(1001, 'idle'), IDLE_MS);
+  const touch = () => {
+    clearTimeout(idle);
+    // Never re-armed after close: the client's close-frame reply still arrives as data.
+    if (!closed) idle = setTimeout(() => conn.close(1001, 'idle'), IDLE_MS);
+  };
+
+  const conn = {
+    send(obj) {
+      if (closed) return;
+      socket.write(frame(0x1, Buffer.from(JSON.stringify(obj))));
+    },
+    close(code = 1000, reason = '') {
+      if (closed) return;
+      closed = true;
+      clearTimeout(idle);
+      const r = Buffer.from(String(reason).slice(0, 100));
+      const p = Buffer.alloc(2 + r.length);
+      p.writeUInt16BE(code, 0);
+      r.copy(p, 2);
+      try {
+        socket.end(frame(0x8, p));
+      } catch {
+        /* ignore */
+      }
+      // Give the client a moment to answer the close frame, then drop the TCP socket regardless.
+      setTimeout(() => socket.destroy(), 1000).unref();
+      onClose();
+    },
+  };
+
+  socket.on('data', (chunk) => {
+    if (closed) return;
+    touch();
+    buf = Buffer.concat([buf, chunk]);
+    for (;;) {
+      if (buf.length < 2) return;
+      const fin = (buf[0] & 0x80) !== 0;
+      const op = buf[0] & 0x0f;
+      const masked = (buf[1] & 0x80) !== 0;
+      let len = buf[1] & 0x7f;
+      let off = 2;
+      if (len === 126) {
+        if (buf.length < 4) return;
+        len = buf.readUInt16BE(2);
+        off = 4;
+      } else if (len === 127) {
+        if (buf.length < 10) return;
+        const big = buf.readBigUInt64BE(2);
+        if (big > BigInt(MAX_MESSAGE_BYTES * 2)) return conn.close(1009, 'too big');
+        len = Number(big);
+        off = 10;
+      }
+      if (!masked) return conn.close(1002, 'client frames must be masked');
+      if (buf.length < off + 4 + len) return;
+      const mask = buf.subarray(off, off + 4);
+      const payload = Buffer.from(buf.subarray(off + 4, off + 4 + len));
+      for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+      buf = buf.subarray(off + 4 + len);
+
+      if (op === 0x8) return conn.close(1000, '');
+      if (op === 0x9) {
+        socket.write(frame(0xa, payload));
+        continue;
+      }
+      if (op === 0xa) continue;
+      if (op === 0x1 || op === 0x0) {
+        if (op === 0x1) frag = { chunks: [] };
+        if (!frag) return conn.close(1002, 'unexpected continuation');
+        frag.chunks.push(payload);
+        const total = frag.chunks.reduce((n, c) => n + c.length, 0);
+        if (total > MAX_MESSAGE_BYTES * 2) return conn.close(1009, 'too big');
+        if (fin) {
+          const text = Buffer.concat(frag.chunks).toString('utf8');
+          frag = null;
+          onText(text);
+        }
+        continue;
+      }
+      return conn.close(1003, 'unsupported frame');
+    }
+  });
+  socket.on('close', () => {
+    clearTimeout(idle);
+    if (!closed) {
+      closed = true;
+      clearTimeout(idle);
+      onClose();
+    }
+  });
+  socket.on('error', () => socket.destroy());
+  return conn;
+}
+
+function frame(op, payload) {
+  const len = payload.length;
+  let head;
+  if (len < 126) {
+    head = Buffer.from([0x80 | op, len]);
+  } else if (len < 65536) {
+    head = Buffer.alloc(4);
+    head[0] = 0x80 | op;
+    head[1] = 126;
+    head.writeUInt16BE(len, 2);
+  } else {
+    head = Buffer.alloc(10);
+    head[0] = 0x80 | op;
+    head[1] = 127;
+    head.writeBigUInt64BE(BigInt(len), 2);
+  }
+  return Buffer.concat([head, payload]);
+}
+
+// CLI
+// pathToFileURL: a Windows argv path (C:\…) never string-matches file:///C:/…
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const arg = (name, dflt) => {
+    const i = process.argv.indexOf(`--${name}`);
+    return i > 0 ? process.argv[i + 1] : dflt;
+  };
+  const port = parseInt(arg('port', process.env.PORT || '8787'), 10);
+  const cap = parseInt(arg('cap', '4'), 10);
+  const host = arg('host', '127.0.0.1');
+  const keysFile = arg('keys', '');
+  const keys = keysFile ? JSON.parse(readFileSync(keysFile, 'utf8')) : null;
+  startDevServer({ port, cap, host, keys, log: (s) => console.log(`[dxr-signal] ${s}`) }).then((s) => {
+    console.log(`[dxr-signal] dev server on ${s.url}/v1/connect (cap ${cap}${process.env.TURN_KEY_ID ? ', TURN on' : ''}${keys ? `, ${Object.keys(keys).length} keys` : ''})`);
+  });
+}

package/signaling/gate.mjs

@@ -0,0 +1,112 @@
+// signaling/gate.mjs — admission for one `dxr-signal/1` connect: key + origin (keys.mjs), the
+// blocklist, join rate + room leases (limits.mjs), and the TURN decision (turn-budget.mjs).
+// Shared verbatim by the Cloudflare Worker (worker.mjs) and the Node dev server (dev-server.mjs);
+// the two only differ in where the counters live (Durable Objects vs a Map), which they inject
+// as `meters` / `budget`.
+//
+// Order of checks, and why: key/origin first (a wrong key is a configuration error, answered
+// before any counter moves) → blocklist → join rate on the IP (a flood is refused before it can
+// ask about rooms) → room lease on the IP (anonymous) or the key (keyed) → TURN policy from the
+// budget, then the per-IP mint rate. Every refusal is a `{code, message, closeCode}` the caller
+// turns into one `error` message + a close, so a client always learns WHY (never a silent hang).
+
+import { limitsFor, CLOSE_CODES, HOUR_MS, subjectForIp } from './limits.mjs';
+import { resolveKey } from './keys.mjs';
+import { turnPolicy } from './turn-budget.mjs';
+
+/**
+ * @typedef {object} Session  what a connect is admitted AS (carried on the socket, never to the client verbatim)
+ * @property {'anon'|'key'} tier
+ * @property {string|null} key           the key id (billing identity), null for anonymous
+ * @property {string} ipSubject          salted IP hash subject (`ip:…`)
+ * @property {{ mint: boolean, ttl: number, status: string, reason?: string }} turn
+ * @property {number} roomTtlS           room lifetime for a room this session opens
+ * @property {{ subject: string, roomKey: string }[]} leases  what to release on close
+ */
+
+/**
+ * @param {object} o
+ * @param {{anon: object, key: object}} o.limits         from limitsFromEnv()
+ * @param {{get(id: string): Promise<object|null>}|null} o.keys   key store (null = keys unsupported → every key is 'bad-key')
+ * @param {{ snapshot(): Promise<{fraction: number, status: string}>|{fraction: number, status: string}, cfg: object }} o.budget
+ * @param {{ exec(subject: string, cmd: object): Promise<any>|any }} o.meters
+ * @param {{ has(ip: string): Promise<boolean>|boolean }|null} [o.blocklist]
+ * @param {string} [o.salt]
+ */
+export function createGate({ limits, keys, budget, meters, blocklist = null, salt = '' }) {
+  const refuse = (code, message, retryMs = 0) => ({ ok: false, code, message, closeCode: CLOSE_CODES[code] || 4000, retryMs });
+
+  return {
+    /**
+     * @param {{ ip: string, origin: string, key: string|null, roomKey: string, wantTurn?: boolean }} req
+     *        `wantTurn` false = the server has no TURN configured at all (skip the budget entirely)
+     * @returns {Promise<{ ok: true, session: Session } | { ok: false, code: string, message: string, closeCode: number, retryMs: number }>}
+     */
+    async admit({ ip, origin, key: keyParam, roomKey, wantTurn = true }) {
+      const k = await resolveKey(keyParam || null, keys, origin || '');
+      if (!k.ok) return refuse(k.code, k.message);
+      if (blocklist && (await blocklist.has(ip || ''))) return refuse('blocked', 'this address is blocked (abuse@displayxr.org)');
+      const tier = k.tier;
+      const rec = tier === 'key' ? k.key : null;
+      const lim = limitsFor(tier, rec, limits);
+      const ipSubject = await subjectForIp(ip || '', salt);
+      const leaseTtlMs = lim.roomTtlS * 1000 + HOUR_MS; // a lease outlives the room it is for
+      /** @type {Session} */
+      const session = { tier, key: rec ? rec.id : null, ipSubject, turn: { mint: false, ttl: 0, status: 'off', reason: 'unconfigured' }, roomTtlS: lim.roomTtlS, leases: [] };
+
+      // Join rate is always per IP (the tier only picks the number); the room lease is per key
+      // for keyed sessions (a customer's quota is theirs, not their users' IPs') and per IP otherwise.
+      const anonRooms = tier === 'anon' ? lim.rooms : undefined;
+      const a = await meters.exec(ipSubject, { op: 'admit', roomKey, tierName: tier, joinsPerMin: lim.joinsPerMin, rooms: anonRooms, leaseTtlMs });
+      if (!a.ok) return refuse(a.code, a.message, a.retryMs);
+      if (anonRooms !== undefined) session.leases.push({ subject: ipSubject, roomKey });
+      if (tier === 'key') {
+        const keySubject = `key:${rec.id}`;
+        const l = await meters.exec(keySubject, { op: 'acquire', roomKey, limit: lim.rooms, ttlMs: leaseTtlMs });
+        if (!l.ok) return refuse('quota', `this key has too many open rooms (${l.limit})`);
+        session.leases.push({ subject: keySubject, roomKey });
+      }
+
+      if (wantTurn) {
+        const snap = await budget.snapshot();
+        const pol = turnPolicy(snap, tier, lim, budget.cfg);
+        session.turn = { mint: pol.mint, ttl: pol.ttl, status: pol.status };
+        if (pol.reason) session.turn.reason = pol.reason;
+        if (pol.mint) {
+          // Mint rate per IP per hour (RFC §5b): over it, the session still joins — STUN-only.
+          const m = await meters.exec(ipSubject, { op: 'hit', name: `mints.${tier}`, windowMs: HOUR_MS, limit: pol.mintsPerHour });
+          if (!m.ok) session.turn = { mint: false, ttl: 0, status: pol.status, reason: 'rate' };
+        }
+      }
+      return { ok: true, session };
+    },
+
+    /** Give every lease of a session back (socket closed). Safe to call twice. */
+    async release(session) {
+      if (!session || !Array.isArray(session.leases)) return;
+      const leases = session.leases;
+      session.leases = [];
+      for (const { subject, roomKey } of leases) {
+        try {
+          await meters.exec(subject, { op: 'release', roomKey });
+        } catch {
+          /* the lease expires on its own */
+        }
+      }
+    },
+  };
+}
+
+/** A blocklist over a KV namespace (`block:<ip>` present = blocked) — or null. */
+export function kvBlocklist(kv) {
+  if (!kv) return null;
+  return {
+    async has(ip) {
+      try {
+        return !!(ip && (await kv.get(`block:${ip}`, { cacheTtl: 60 })));
+      } catch {
+        return false;
+      }
+    },
+  };
+}

package/signaling/keys.mjs

@@ -0,0 +1,123 @@
+// signaling/keys.mjs — publishable keys for the hosted `dxr-signal/1` service (RFC 0003 §5a).
+//
+// A key is PUBLIC: it sits in page source, so it is attribution + a quota bucket + an origin
+// binding that browsers enforce, never a secret. The record lives server-side (a KV namespace on
+// Cloudflare: `key:<id>` → JSON; a Map on the dev server), is issued by hand (tools/signal-keys.mjs),
+// and is checked on every connect against the request's `Origin`. Every session carries its key
+// id so usage is attributable per key from day one (billing identity; billing itself is OFF).
+
+/** `pk_` + 20–40 base62 chars. The id IS the key (there is no secret half). */
+export const KEY_RE = /^pk_[A-Za-z0-9]{20,40}$/;
+
+/**
+ * @typedef {object} KeyRecord
+ * @property {string} id            the key itself (`pk_…`)
+ * @property {string[]} origins     allowed page origins; `*` suffix wildcards one label level
+ *                                  (`https://*.example.com`), `http://localhost` matches any port
+ * @property {string} [note]        who / what it was issued for (never shown to clients)
+ * @property {string} [createdAt]   ISO date
+ * @property {boolean} [revoked]    a revoked key is refused like an unknown one
+ * @property {Partial<import('./limits.mjs').TierLimits>} [limits]  per-key overrides
+ */
+
+/** Generate a new key id. `random` = bytes → used in Node and in the Worker alike. */
+export function newKeyId(bytes = globalThis.crypto.getRandomValues(new Uint8Array(24))) {
+  const A = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let s = '';
+  for (const b of bytes) s += A[b % 62];
+  return 'pk_' + s.slice(0, 24);
+}
+
+/** Parse + validate a stored record; null if it is not a usable key record. */
+export function parseKeyRecord(id, raw) {
+  if (!KEY_RE.test(id || '')) return null;
+  let rec = raw;
+  if (typeof raw === 'string') {
+    try {
+      rec = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  if (!rec || typeof rec !== 'object') return null;
+  const origins = Array.isArray(rec.origins) ? rec.origins.filter((o) => typeof o === 'string' && o).map(normalizeOrigin) : [];
+  return {
+    id,
+    origins,
+    note: typeof rec.note === 'string' ? rec.note : '',
+    createdAt: typeof rec.createdAt === 'string' ? rec.createdAt : '',
+    revoked: !!rec.revoked,
+    limits: rec.limits && typeof rec.limits === 'object' ? { ...rec.limits } : undefined,
+  };
+}
+
+/** Lowercase scheme+host, strip a trailing slash and a default port. */
+export function normalizeOrigin(o) {
+  let s = String(o || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\/+$/, '');
+  s = s.replace(/^(https):\/\/([^/:]+):443$/, '$1://$2').replace(/^(http):\/\/([^/:]+):80$/, '$1://$2');
+  return s;
+}
+
+/**
+ * Does `origin` (the request header) match one allowed pattern?
+ *  - exact: `https://app.example.com`
+ *  - one-label wildcard: `https://*.example.com` (matches `a.example.com`, not `example.com`, not `a.b.example.com`)
+ *  - `http://localhost` / `https://localhost` / `http://127.0.0.1`: any port (dev pages)
+ *  - `*`: any origin (a key used purely for attribution / headroom)
+ * An ABSENT Origin header (a non-browser client) never matches a key with an origin list.
+ */
+export function originAllowed(origin, patterns) {
+  const o = normalizeOrigin(origin);
+  if (!o || o === 'null') return patterns.includes('*');
+  for (const raw of patterns) {
+    const p = normalizeOrigin(raw);
+    if (p === '*' || p === o) return true;
+    if (/^https?:\/\/(localhost|127\.0\.0\.1)$/.test(p) && (o === p || o.startsWith(p + ':'))) return true;
+    const m = /^(https?):\/\/\*\.(.+)$/.exec(p);
+    if (m) {
+      const n = new RegExp(`^${m[1]}:\\/\\/[a-z0-9-]+\\.${m[2].replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(:\\d+)?$`);
+      if (n.test(o)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Resolve the `key` query parameter against the key store for one connect.
+ * @param {string|null} param  the raw `?key=` value ('' / null = anonymous)
+ * @param {{ get(id: string): Promise<KeyRecord|null> }} store
+ * @param {string} origin  the request's Origin header
+ * @returns {Promise<{ ok: true, tier: 'anon' } | { ok: true, tier: 'key', key: KeyRecord } | { ok: false, code: 'bad-key'|'origin-not-allowed', message: string }>}
+ */
+export async function resolveKey(param, store, origin) {
+  if (!param) return { ok: true, tier: 'anon' };
+  if (!KEY_RE.test(param)) return { ok: false, code: 'bad-key', message: 'malformed key (pk_…)' };
+  const rec = store ? await store.get(param) : null;
+  if (!rec || rec.revoked) return { ok: false, code: 'bad-key', message: 'unknown or revoked key' };
+  if (!originAllowed(origin, rec.origins)) return { ok: false, code: 'origin-not-allowed', message: `key is not allowed from origin "${origin || '(none)'}"` };
+  return { ok: true, tier: 'key', key: rec };
+}
+
+/** A key store over a Cloudflare KV namespace (`key:<id>`), with the edge cache KV offers. */
+export function kvKeyStore(kv, { cacheTtl = 60 } = {}) {
+  if (!kv) return null;
+  return {
+    async get(id) {
+      try {
+        const raw = await kv.get(`key:${id}`, { cacheTtl });
+        return raw ? parseKeyRecord(id, raw) : null;
+      } catch {
+        return null; // a KV hiccup refuses the key (fail closed) rather than crashing the connect
+      }
+    },
+  };
+}
+
+/** A key store over a plain Map / object (dev server, tests). */
+export function mapKeyStore(map) {
+  const get = (id) => (map instanceof Map ? map.get(id) : map && map[id]);
+  return { async get(id) { const r = get(id); return r ? parseKeyRecord(id, r) : null; } };
+}