@displayxr/inline3d 1.47.6 → 1.48.0

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

package/signaling/room.mjs

@@ -0,0 +1,322 @@
+// signaling/room.mjs — the `dxr-signal/1` room logic, shared VERBATIM by the Cloudflare Worker's
+// Durable Object (worker.mjs) and the Node dev server (dev-server.mjs). Runtime-agnostic: no
+// sockets here, just "a connection said this; tell these connections that". The protocol is
+// documented in ./README.md.
+//
+// What this server knows: a room id, random per-join peer ids, and the SDP/ICE blobs it relays.
+// It never sees media (DTLS-SRTP is peer-to-peer) and holds nothing after the last peer leaves.
+
+import { CLOSE_CODES } from './limits.mjs';
+
+export const PROTOCOL = 'dxr-signal/1';
+export const ROOM_ID_RE = /^[A-Za-z0-9_-]{16,64}$/;
+export const PEER_ID_RE = /^[A-Za-z0-9_-]{8,32}$/;
+/** Default room size, and the largest a server will allow (full mesh stops scaling at 4). */
+export const DEFAULT_ROOM_CAP = 4;
+export const MAX_ROOM_CAP = 8;
+/** A single signalling message is a JSON SDP or candidate — 64 KiB is generous. */
+export const MAX_MESSAGE_BYTES = 64 * 1024;
+/** Per-connection flood guard: at most this many messages per window. */
+export const RATE_LIMIT = { messages: 300, windowMs: 10_000 };
+
+/** SHA-256 of the room id, hex — the only room-derived value that appears in a URL. */
+export async function roomKey(room) {
+  const bytes = new TextEncoder().encode(String(room));
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * One room. `conn` is anything with `send(obj)` and `close(code, reason)`; the host runtime owns
+ * the socket and calls `onMessage(conn, text)` / `onClose(conn)`.
+ *
+ * @param {object} opts
+ * @param {string} opts.key  the roomKey this room was addressed by (join must match it)
+ * @param {number} [opts.cap]  server-side participant cap (clamped to MAX_ROOM_CAP)
+ * @param {(info: object|null) => Promise<object[]|null>} [opts.iceServers]  mints short-lived
+ *        TURN credentials per join (given the connection's admission session, see gate.mjs, whose
+ *        `turn.ttl` is the TTL to mint); null/absent = the client uses its own defaults (public STUN)
+ * @param {{ onFirst?: (info: object|null) => void, onEmpty?: () => void }} [opts.hooks]  the room
+ *        went 0→1 peers (start its lifetime clock) / 1→0 (stop it)
+ * @param {() => number} [opts.now]
+ */
+export class Room {
+  constructor({ key, cap = DEFAULT_ROOM_CAP, iceServers = null, hooks = {}, now = () => Date.now() } = {}) {
+    this.key = key || null;
+    this.cap = Math.max(2, Math.min(MAX_ROOM_CAP, cap | 0 || DEFAULT_ROOM_CAP));
+    this.max = null; // set by the first joiner (<= cap)
+    this.peers = new Map(); // id -> conn
+    this.meta = new WeakMap(); // conn -> { id, count, windowAt, session }
+    this.iceServers = iceServers;
+    this.hooks = hooks || {};
+    this.now = now;
+  }
+
+  get size() {
+    return this.peers.size;
+  }
+
+  _meta(conn) {
+    let m = this.meta.get(conn);
+    if (!m) {
+      m = { id: null, count: 0, windowAt: this.now(), session: null, pending: null };
+      this.meta.set(conn, m);
+    }
+    return m;
+  }
+
+  /**
+   * Record what a connection was admitted as (gate.mjs `Session`: tier, key id, TURN decision,
+   * room lifetime). Call before its first message; absent = anonymous, TURN per server config.
+   */
+  attach(conn, session) {
+    this._meta(conn).session = session || null;
+  }
+
+  /** Re-attach a connection that already joined (Durable Object wake from hibernation). */
+  restore(conn, id, session = null) {
+    if (!PEER_ID_RE.test(id)) return;
+    this.peers.set(id, conn);
+    this.meta.set(conn, { id, count: 0, windowAt: this.now(), session: session || null, pending: null });
+  }
+
+  /**
+   * Send to a peer, respecting the protocol's ordering rule: `welcome` is the FIRST message a
+   * joined peer receives. Between a peer's slot being reserved and its welcome going out there
+   * can be an await (the TURN mint is a network call), and in that window another peer's
+   * `peer-joined` / `signal` / `peer-left` may be addressed to it. Those are held here and
+   * flushed, in order, right behind the welcome.
+   */
+  _deliver(conn, obj) {
+    const m = conn && this.meta.get(conn);
+    if (m && m.pending) m.pending.push(obj);
+    else safeSend(conn, obj);
+  }
+
+  async onMessage(conn, text) {
+    if (typeof text !== 'string') text = String(text);
+    if (text.length > MAX_MESSAGE_BYTES) return this._fail(conn, 'too-big', 'message exceeds 64 KiB');
+    let msg;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      return this._fail(conn, 'bad-message', 'not JSON');
+    }
+    if (!msg || typeof msg !== 'object') return this._fail(conn, 'bad-message', 'not an object');
+    const m = this._meta(conn);
+    const t = this.now();
+    if (t - m.windowAt > RATE_LIMIT.windowMs) {
+      m.windowAt = t;
+      m.count = 0;
+    }
+    if (++m.count > RATE_LIMIT.messages) return this._fail(conn, 'rate-limited', 'slow down', true);
+
+    switch (msg.t) {
+      case 'ping':
+        return this._deliver(conn, { t: 'pong' });
+      case 'join':
+        return this._join(conn, m, msg);
+      case 'signal':
+        // A peer is "joined" once its welcome is out; until then it has nothing to signal about.
+        if (!m.id || m.pending) return this._fail(conn, 'not-joined', 'join first');
+        if (typeof msg.to !== 'string' || !this.peers.has(msg.to) || msg.to === m.id) {
+          return safeSend(conn, { t: 'error', code: 'no-such-peer', to: msg.to ?? null });
+        }
+        return this._deliver(this.peers.get(msg.to), { t: 'signal', from: m.id, data: msg.data ?? null });
+      case 'leave':
+        this.onClose(conn);
+        try {
+          conn.close(1000, 'left');
+        } catch {
+          /* already closed */
+        }
+        return;
+      default:
+        return this._fail(conn, 'bad-message', `unknown type "${msg.t}"`);
+    }
+  }
+
+  async _join(conn, m, msg) {
+    if (m.id) return this._fail(conn, 'already-joined', 'one join per connection');
+    if (msg.v !== undefined && msg.v !== 1) return this._fail(conn, 'bad-version', `server speaks ${PROTOCOL}`, true);
+    if (!ROOM_ID_RE.test(msg.room || '')) return this._fail(conn, 'bad-room', 'room id must be 16-64 base64url chars', true);
+    if (this.key && (await roomKey(msg.room)) !== this.key) return this._fail(conn, 'bad-room', 'room does not match its key', true);
+    if (!PEER_ID_RE.test(msg.id || '')) return this._fail(conn, 'bad-id', 'peer id must be 8-32 base64url chars', true);
+    if (this.peers.has(msg.id)) return this._fail(conn, 'id-taken', 'that peer id is in the room', true);
+    if (this.max === null || this.peers.size === 0) {
+      const want = Number.isInteger(msg.max) ? msg.max : DEFAULT_ROOM_CAP;
+      this.max = Math.max(2, Math.min(this.cap, want));
+    }
+    if (this.peers.size >= this.max) {
+      safeSend(conn, { t: 'full', max: this.max });
+      try {
+        conn.close(4003, 'room full');
+      } catch {
+        /* ignore */
+      }
+      return;
+    }
+    // Reserve the slot NOW (synchronously), so a burst cannot oversubscribe the room or mint TURN
+    // credentials for peers that will be turned away — and open the hold-back queue: nothing
+    // reaches this peer before its own welcome (see _deliver). Peers that are already welcomed do
+    // not know this one, so they are told here; peers still waiting for their welcome will find
+    // it in their roster, which is read at send time. Either way each pair hears of the other
+    // exactly once.
+    const first = this.peers.size === 0;
+    for (const [, other] of this.peers) {
+      const om = this.meta.get(other);
+      if (!om || !om.pending) safeSend(other, { t: 'peer-joined', id: msg.id });
+    }
+    m.id = msg.id;
+    m.pending = [];
+    this.peers.set(msg.id, conn);
+    const s = m.session;
+    // TURN: the admission decision (budget / tier / mint rate) says whether to mint at all and
+    // for how long; a server without TURN configured has no minter. The welcome always says
+    // which, so the SDK can tell "no relay this month" (`turn-cap`) from "self-hosted, no TURN".
+    let ice = null;
+    /** @type {{status: string, reason?: string, ttl?: number}} */
+    let turn = { status: 'off', reason: 'unconfigured' };
+    if (this.iceServers) {
+      const want = s && s.turn ? s.turn : { mint: true, ttl: 0, status: 'ok' };
+      if (!want.mint) turn = { status: want.status || 'off', reason: want.reason || 'budget' };
+      else {
+        try {
+          ice = await this.iceServers(s);
+          turn = ice ? { status: want.status || 'ok', ttl: want.ttl || undefined } : { status: 'off', reason: 'unconfigured' };
+        } catch {
+          ice = null; // TURN minting failed: the client falls back to STUN, the call may still work
+          turn = { status: want.status || 'ok', reason: 'mint-failed' };
+        }
+      }
+    }
+    // The peer may have gone (closed, expired) while the mint was in flight: then its slot is
+    // already released and the others already heard `peer-left`.
+    if (this.peers.get(msg.id) !== conn || m.id !== msg.id) return;
+    const held = m.pending || [];
+    m.pending = null;
+    // The roster is read HERE, not at reservation: it is everyone in the room as this welcome
+    // goes out, including peers that joined during the mint.
+    const others = [...this.peers.keys()].filter((id) => id !== msg.id);
+    const welcome = { t: 'welcome', v: 1, id: msg.id, peers: others, max: this.max, tier: s ? s.tier : 'anon', turn };
+    if (s && s.key) welcome.key = s.key;
+    if (ice) welcome.iceServers = ice;
+    safeSend(conn, welcome);
+    // What was held during the mint, minus what the roster already says: a `peer-joined` for
+    // someone listed in `peers` would announce them twice.
+    const listed = new Set(others);
+    for (const obj of held) {
+      if (obj && obj.t === 'peer-joined' && listed.has(obj.id)) continue;
+      safeSend(conn, obj);
+    }
+    if (first) this.hooks.onFirst?.(s);
+  }
+
+  /** The socket closed (or the peer left): tell the others. Idempotent. */
+  onClose(conn) {
+    const m = this.meta.get(conn);
+    if (!m || !m.id) return;
+    const id = m.id;
+    m.id = null;
+    if (this.peers.get(id) !== conn) return;
+    this.peers.delete(id);
+    for (const other of this.peers.values()) this._deliver(other, { t: 'peer-left', id });
+    if (this.peers.size === 0) {
+      this.max = null;
+      this.hooks.onEmpty?.();
+    }
+  }
+
+  /**
+   * The room's lifetime is up (RFC §5b: 2 h anonymous, 8 h keyed): every peer gets `expired`
+   * and is closed (4004). Media already flowing peer-to-peer is not touched by this; the peers
+   * simply have no signalling for that room any more.
+   */
+  expire() {
+    const conns = [...this.peers.values()];
+    this.peers.clear();
+    this.max = null;
+    for (const conn of conns) {
+      const m = this.meta.get(conn);
+      if (m) m.id = null;
+      safeSend(conn, { t: 'expired' });
+      try {
+        conn.close(CLOSE_CODES.expired, 'expired');
+      } catch {
+        /* ignore */
+      }
+    }
+    if (conns.length) this.hooks.onEmpty?.();
+  }
+
+  _fail(conn, code, message, close = false) {
+    safeSend(conn, { t: 'error', code, message });
+    if (close) {
+      this.onClose(conn);
+      try {
+        conn.close(CLOSE_CODES[code] || 4000, code);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/**
+ * Refuse a connection before it ever reaches a room (an admission failure, gate.mjs): one
+ * `error` message, then the close code for that error. The client learns why; nothing hangs.
+ */
+export function refuseConn(conn, { code, message, retryMs = 0, closeCode }) {
+  const err = { t: 'error', code, message };
+  if (retryMs > 0) err.retryMs = retryMs;
+  safeSend(conn, err);
+  try {
+    conn.close(closeCode || CLOSE_CODES[code] || 4000, code);
+  } catch {
+    /* ignore */
+  }
+}
+
+function safeSend(conn, obj) {
+  try {
+    conn.send(obj);
+  } catch {
+    /* the socket is going away; its close handler cleans up */
+  }
+}
+
+/**
+ * Mint short-lived TURN credentials with Cloudflare Realtime TURN. Returns the `iceServers` array
+ * or null when not configured. The key id and API token live in the Worker's env (a secret), and
+ * ONLY there — clients receive credentials that expire after `ttl` seconds.
+ *
+ * `customIdentifier` tags the credential with the session's key id ('anon' otherwise), which is
+ * how Cloudflare's TURN analytics attribute relay bytes per key (turn-budget.mjs readTurnUsage).
+ * If the API ever rejects that field, the mint is retried once without it.
+ *
+ * @param {{TURN_KEY_ID?: string, TURN_KEY_API_TOKEN?: string, TURN_TTL?: string}} env
+ * @param {typeof fetch} [fetchImpl]
+ * @param {{ ttl?: number, customIdentifier?: string }} [o]  `ttl` overrides env.TURN_TTL
+ */
+export async function mintTurnCredentials(env, fetchImpl = globalThis.fetch, o = {}) {
+  if (!env || !env.TURN_KEY_ID || !env.TURN_KEY_API_TOKEN) return null;
+  const ttl = Math.max(60, Math.min(86400, (o.ttl > 0 ? o.ttl | 0 : 0) || parseInt(env.TURN_TTL || '3600', 10) || 3600));
+  const url = `https://rtc.live.cloudflare.com/v1/turn/keys/${encodeURIComponent(env.TURN_KEY_ID)}/credentials/generate-ice-servers`;
+  const post = (body) =>
+    fetchImpl(url, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${env.TURN_KEY_API_TOKEN}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  const tag = typeof o.customIdentifier === 'string' && o.customIdentifier ? o.customIdentifier.slice(0, 64) : '';
+  let res = await post(tag ? { ttl, customIdentifier: tag } : { ttl });
+  if (!res.ok && tag && res.status === 400) res = await post({ ttl });
+  if (!res.ok) throw new Error(`TURN credential mint failed: HTTP ${res.status}`);
+  const body = await res.json();
+  // Current API: { iceServers: [ {urls}, {urls, username, credential} ] }. The older
+  // `/credentials/generate` answered { iceServers: { urls, username, credential } } — accept both.
+  const s = body && body.iceServers;
+  if (Array.isArray(s)) return s;
+  if (s && s.urls) return [s];
+  return null;
+}