@displayxr/inline3d 1.47.5 → 1.48.0

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; } };
+}

package/signaling/limits.mjs

@@ -0,0 +1,221 @@
+// signaling/limits.mjs — rate limits and caps for the hosted `dxr-signal/1` service (RFC 0003 §5b).
+// Runtime-agnostic and pure: a `Meter` is the counters of ONE subject (a salted IP hash, or a key
+// id) — fixed-window hit counters plus "leases" (the rooms that subject currently has open). The
+// Cloudflare Worker keeps one Durable Object per subject around a Meter; the Node dev server keeps
+// them in a Map. Both call exactly the same code, so a limit cannot drift between them.
+//
+// Every number here is a starting value from the RFC table and is overridable per deployment
+// through environment variables (limitsFromEnv) and per key through the key record (`limits`).
+
+/** @typedef {{ joinsPerMin: number, rooms: number, roomTtlS: number, mintsPerHour: number, turnTtl: number }} TierLimits */
+
+/** RFC 0003 §5b starting values. `turnTtl` is §5a (anonymous 600 s, keyed 3600 s). */
+export const DEFAULT_LIMITS = Object.freeze({
+  anon: Object.freeze({ joinsPerMin: 20, rooms: 5, roomTtlS: 2 * 3600, mintsPerHour: 30, turnTtl: 600 }),
+  key: Object.freeze({ joinsPerMin: 200, rooms: 50, roomTtlS: 8 * 3600, mintsPerHour: 300, turnTtl: 3600 }),
+});
+
+/** Env var names, per tier, in `DEFAULT_LIMITS` key order (documented in README.md). */
+const ENV_NAMES = {
+  anon: { joinsPerMin: 'ANON_JOINS_PER_MIN', rooms: 'ANON_ROOMS', roomTtlS: 'ANON_ROOM_TTL', mintsPerHour: 'ANON_MINTS_PER_HOUR', turnTtl: 'ANON_TURN_TTL' },
+  key: { joinsPerMin: 'KEY_JOINS_PER_MIN', rooms: 'KEY_ROOMS', roomTtlS: 'KEY_ROOM_TTL', mintsPerHour: 'KEY_MINTS_PER_HOUR', turnTtl: 'TURN_TTL' },
+};
+
+const posInt = (v, dflt) => {
+  const n = parseInt(String(v ?? ''), 10);
+  return Number.isFinite(n) && n >= 0 ? n : dflt;
+};
+
+/** Read both tiers' limits from an env object (unset vars keep the RFC defaults). */
+export function limitsFromEnv(env = {}) {
+  const out = {};
+  for (const tier of ['anon', 'key']) {
+    const t = {};
+    for (const [k, name] of Object.entries(ENV_NAMES[tier])) t[k] = posInt(env[name], DEFAULT_LIMITS[tier][k]);
+    t.turnTtl = Math.max(60, Math.min(86400, t.turnTtl || DEFAULT_LIMITS[tier].turnTtl));
+    out[tier] = t;
+  }
+  return out;
+}
+
+/**
+ * The effective limits for one session: the tier's base, then the key record's `limits`
+ * overrides (a keyed customer can be given more — or less — headroom by hand).
+ * @param {'anon'|'key'} tier
+ * @param {{limits?: Partial<TierLimits>}|null} keyRecord
+ * @param {{anon: TierLimits, key: TierLimits}} [base]
+ * @returns {TierLimits}
+ */
+export function limitsFor(tier, keyRecord, base = DEFAULT_LIMITS) {
+  const t = { ...(base[tier] || DEFAULT_LIMITS[tier]) };
+  const o = tier === 'key' && keyRecord && keyRecord.limits && typeof keyRecord.limits === 'object' ? keyRecord.limits : null;
+  if (o) for (const k of Object.keys(t)) if (Number.isFinite(+o[k]) && +o[k] >= 0) t[k] = Math.floor(+o[k]);
+  t.turnTtl = Math.max(60, Math.min(86400, t.turnTtl || DEFAULT_LIMITS[tier].turnTtl));
+  return t;
+}
+
+export const MINUTE_MS = 60_000;
+export const HOUR_MS = 3_600_000;
+
+/**
+ * The counters of one subject. Serialisable (`toJSON` / `Meter.from`) so a Durable Object can
+ * persist it between requests and across hibernation.
+ */
+export class Meter {
+  /** @param {{ now?: () => number, state?: any }} [o] */
+  constructor({ now = () => Date.now(), state = null } = {}) {
+    this.now = now;
+    /** fixed windows: name -> { at: windowStartMs, count } */
+    this.windows = new Map();
+    /** leases: roomKey -> { count, expiresAt } — the rooms this subject currently has open */
+    this.leases = new Map();
+    if (state) this._load(state);
+  }
+
+  _load(s) {
+    if (s && s.windows && typeof s.windows === 'object') for (const [k, v] of Object.entries(s.windows)) if (v && Number.isFinite(v.at)) this.windows.set(k, { at: v.at, count: v.count | 0 });
+    if (s && s.leases && typeof s.leases === 'object') for (const [k, v] of Object.entries(s.leases)) if (v && Number.isFinite(v.expiresAt)) this.leases.set(k, { count: v.count | 0, expiresAt: v.expiresAt });
+  }
+
+  toJSON() {
+    const t = this.now();
+    const windows = {};
+    for (const [k, v] of this.windows) if (t - v.at < HOUR_MS * 2) windows[k] = v; // nothing lives longer than an hour window
+    const leases = {};
+    for (const [k, v] of this.leases) if (v.expiresAt > t && v.count > 0) leases[k] = v;
+    return { windows, leases };
+  }
+
+  static from(json, now) {
+    return new Meter({ now, state: json });
+  }
+
+  /**
+   * Count one event in a fixed window. `ok` is false once the window's count exceeds `limit`
+   * (the event is still counted: a flood keeps its own window hot).
+   * @returns {{ ok: boolean, count: number, limit: number, retryMs: number }}
+   */
+  hit(name, windowMs, limit) {
+    const t = this.now();
+    let w = this.windows.get(name);
+    if (!w || t - w.at >= windowMs) {
+      w = { at: t, count: 0 };
+      this.windows.set(name, w);
+    }
+    w.count++;
+    const ok = w.count <= limit;
+    return { ok, count: w.count, limit, retryMs: ok ? 0 : Math.max(1, windowMs - (t - w.at)) };
+  }
+
+  /** Current count in a window without counting (for diagnostics). */
+  peek(name, windowMs) {
+    const w = this.windows.get(name);
+    return w && this.now() - w.at < windowMs ? w.count : 0;
+  }
+
+  _prune() {
+    const t = this.now();
+    for (const [k, v] of this.leases) if (v.expiresAt <= t || v.count <= 0) this.leases.delete(k);
+  }
+
+  /** Distinct rooms this subject holds open (expired leases pruned). */
+  rooms() {
+    this._prune();
+    return this.leases.size;
+  }
+
+  /**
+   * Take a lease on `roomKey` (a connection into that room). Opening a NEW room is refused once
+   * the subject already holds `limit` distinct rooms; a second connection into a room it already
+   * holds is always allowed (that is the same room, not a new one). Leases expire by themselves
+   * after `ttlMs`, so a lost `release` (an evicted object, a crashed server) cannot wedge a
+   * subject for ever.
+   * @returns {{ ok: boolean, rooms: number, limit: number }}
+   */
+  acquire(roomKey, limit, ttlMs) {
+    this._prune();
+    const have = this.leases.get(roomKey);
+    if (!have && this.leases.size >= limit) return { ok: false, rooms: this.leases.size, limit };
+    const expiresAt = this.now() + Math.max(1000, ttlMs | 0 || HOUR_MS);
+    if (have) {
+      have.count++;
+      have.expiresAt = Math.max(have.expiresAt, expiresAt);
+    } else this.leases.set(roomKey, { count: 1, expiresAt });
+    return { ok: true, rooms: this.leases.size, limit };
+  }
+
+  /** Give a lease back. Idempotent for a room that is not held. */
+  release(roomKey) {
+    const have = this.leases.get(roomKey);
+    if (!have) return;
+    if (--have.count <= 0) this.leases.delete(roomKey);
+  }
+
+  /**
+   * One round trip for a join: the join-rate window, then the room lease — in that order, so a
+   * flood is answered `rate-limited` before it can even ask about rooms, and a refused join never
+   * takes a lease.
+   * @param {{ roomKey: string, tierName: string, joinsPerMin: number, rooms?: number, leaseTtlMs?: number }} o
+   *        `rooms` absent = do not lease here (the caller leases on another subject)
+   * @returns {{ ok: true } | { ok: false, code: 'rate-limited'|'quota', retryMs: number, message: string }}
+   */
+  admit({ roomKey, tierName, joinsPerMin, rooms, leaseTtlMs }) {
+    const r = this.hit(`joins.${tierName}`, MINUTE_MS, joinsPerMin);
+    if (!r.ok) return { ok: false, code: 'rate-limited', retryMs: r.retryMs, message: `too many joins (${r.limit}/min); retry in ${Math.ceil(r.retryMs / 1000)} s` };
+    if (rooms !== undefined) {
+      const l = this.acquire(roomKey, rooms, leaseTtlMs);
+      if (!l.ok) return { ok: false, code: 'quota', retryMs: 0, message: `too many open rooms (${l.limit}); leave one first` };
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Run a serialised command (the Durable Object and the dev server speak this one vocabulary).
+   * @param {{op: string} & Record<string, any>} cmd
+   */
+  exec(cmd) {
+    switch (cmd && cmd.op) {
+      case 'admit':
+        return this.admit(cmd);
+      case 'hit':
+        return this.hit(cmd.name, cmd.windowMs, cmd.limit);
+      case 'acquire':
+        return this.acquire(cmd.roomKey, cmd.limit, cmd.ttlMs);
+      case 'release':
+        this.release(cmd.roomKey);
+        return { ok: true, rooms: this.rooms() };
+      case 'peek':
+        return { rooms: this.rooms(), windows: Object.fromEntries([...this.windows].map(([k, v]) => [k, v.count])) };
+      default:
+        return { ok: false, code: 'bad-op' };
+    }
+  }
+}
+
+/**
+ * The subject id for an IP: a salted SHA-256 prefix, so rate-limit state never holds a raw
+ * address (RFC 0003 §5e). The salt is a deployment var (`RATE_SALT`); rotating it forgets every
+ * counter, which is harmless.
+ */
+export async function subjectForIp(ip, salt = '') {
+  const bytes = new TextEncoder().encode(`${salt}|${ip || ''}`);
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return 'ip:' + [...new Uint8Array(digest)].slice(0, 12).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Close codes the server uses for refusals (documented in README.md). */
+export const CLOSE_CODES = Object.freeze({
+  'bad-message': 4000,
+  'bad-version': 4000,
+  'bad-room': 4000,
+  'bad-id': 4000,
+  'id-taken': 4000,
+  'too-big': 4000,
+  'bad-key': 4001,
+  'origin-not-allowed': 4001,
+  full: 4003,
+  expired: 4004,
+  'rate-limited': 4029,
+  quota: 4030,
+  blocked: 4040,
+});