fedipod 0.8.0

package/lib/store.mjs

@@ -0,0 +1,470 @@
+// store.mjs — PodStore: the agent's operational state as JSON documents in a
+// container. The container is a Storage (lib/storage.mjs) — a pod over HTTP or
+// a directory — and this file does not care which. The sync read/write surface
+// of dk's fs Store is preserved so every consumer (publisher, intake, facade,
+// …) is unchanged: reads come from an in-memory cache loaded once at boot,
+// writes update the cache and are flushed through a serialized, debounced,
+// retrying queue. Everything here is rebuildable from the /fediverse/ RDF, so
+// a lost write degrades, it doesn't destroy. Without a storage the store is
+// pure memory (tests, unconfigured boot).
+
+import crypto from 'node:crypto';
+import { sanitizeHtml } from './wire.mjs';
+
+// A display name is text, not markup: strip tags rather than allow a subset,
+// because there is no tag that belongs in one.
+const plainText = (s) => sanitizeHtml(String(s || '')).replace(/<[^>]*>/g, '').trim();
+
+// An avatar or header URL is written straight into an <img src> by the client.
+// http(s) only — `javascript:` and `data:` have no business being an avatar.
+const safeUrl = (u) => {
+  if (!u) return u;
+  try {
+    const parsed = new URL(String(u));
+    return (parsed.protocol === 'https:' || parsed.protocol === 'http:') ? String(u) : null;
+  } catch { return null; }
+};
+
+// Remote text arrives with no length of its own. `readCapped` bounds a document
+// at 5 MB, which is a sane ceiling for a fetch and an absurd one for a display
+// name — and whatever survives is then written into a document we serialize
+// WHOLE on every change. One planted actor with a megabyte of bio permanently
+// inflated actors.json, and a Follow flood re-PUT it once per commit batch.
+// Mastodon's own limits are the shape of the real world; a little over them is
+// generous rather than lossy.
+const MAX_NAME = 500;
+const MAX_SUMMARY = 5_000;
+const MAX_CONTENT = 100_000;
+const clamp = (s, n) => (typeof s === 'string' && s.length > n ? s.slice(0, n) : s);
+
+const PUT_DEBOUNCE_MS = 300;
+const PUT_RETRIES = 5;
+// This is a CACHE of other people's actor documents — every search, every
+// timeline post from a stranger, every hashtag sweep adds one, and nothing ever
+// took one out. Bounded by dropping the least recently fetched, except for
+// anyone we actually have a relationship with: losing a follower's display name
+// would be re-fetching it on the next render for nothing.
+const ACTOR_CACHE_MAX = 2000;
+const NOTIFICATIONS_MAX = 500;
+
+function prune(actors, max, contacts) {
+  const urls = Object.keys(actors);
+  if (urls.length <= max) return actors;
+  const keep = new Set([
+    ...contacts.followers.map(f => f.actor),
+    ...contacts.following.map(f => f.actor),
+  ]);
+  const droppable = urls.filter(u => !keep.has(u))
+    .sort((a, b) => String(actors[a].fetchedAt || '').localeCompare(String(actors[b].fetchedAt || '')));
+  for (const u of droppable.slice(0, urls.length - max)) delete actors[u];
+  return actors;
+}
+
+// Removing a follower is a DECISION — they unfollowed, or were ejected, or the
+// account is gone. Reconciling the local list against the pod's published one
+// would otherwise bring every one of them back, so each removal leaves a mark.
+// Bounded: the same actor leaving twice is still one entry.
+export function dropFollower(contacts, actor, why) {
+  contacts.followers = contacts.followers.filter(f => f.actor !== actor);
+  const gone = (contacts.removedFollowers || []).filter(r => r.actor !== actor);
+  gone.push({ actor, why, at: new Date().toISOString() });
+  contacts.removedFollowers = gone.slice(-500);
+  return contacts;
+}
+
+export class PodStore {
+  constructor({ storage = null, log = console.log } = {}) {
+    this.storage = storage;
+    this.log = log;
+    this.cache = new Map();        // name → parsed value
+    this.etags = new Map();        // name (or '') → last ETag, for revalidation
+    this.timers = new Map();       // name → debounce timer
+    this.dirty = new Set();        // written while held; flushed by commit/release
+    this._held = 0;
+    this.chain = Promise.resolve();  // serialized writes
+    this.verdicts = new Map();     // name → did its last write land? (read by commit)
+  }
+
+  get base() { return this.storage?.base || null; }
+
+  attach(storage) {
+    // A different tree is different state: carrying the old cache and its
+    // ETags across would serve one container's documents as another's.
+    if (this.storage && this.storage.base !== storage.base) { this.cache.clear(); this.etags.clear(); }
+    this.storage = storage;
+  }
+
+  // Load every state doc in the container into the cache. Missing container
+  // (first run) is fine — the cache just starts empty.
+  //
+  // `force` skips the container short-circuit below. A container's ETag says
+  // its CHILDREN have not changed; it does not vouch for their contents, and a
+  // peer agent rewriting a document it already had changes no containment
+  // triple. That is a fine trade for a viewer refreshing a display, and a bad
+  // one at the moment a viewer is promoted and starts acting on what it holds.
+  // Throws when the container cannot be read. An empty cache MUST mean "no
+  // state yet", never "the pod was unreachable" — the caller treats the
+  // former as a fresh install, and silently conflating them would look like
+  // an un-set-up agent every time the pod hiccups.
+  async load({ force = false } = {}) {
+    if (!this.storage) return;
+    // Revalidate rather than re-download: a viewer reloads this every few
+    // minutes and it is almost always unchanged. (Only a pod answers 304; a
+    // directory has nothing to revalidate against, so it always relists —
+    // which is a readdir, not a request.)
+    const listing = await this.storage.list('', { etag: force ? null : this.etags.get('') });
+    if (listing.notModified) return;                   // cannot happen when forced: no etag was sent
+    // A 404'd container over HTTP is "could not read", not "no state yet":
+    // setup creates this container, so once a credential exists it should
+    // answer — and a proxy fronting a dead pod 404s in exactly the same shape.
+    // A directory has no proxy to lie for it, so its absence stays an answer.
+    if (listing.missing && this.storage.kind === 'pod') {
+      throw new Error(`state container missing (HTTP 404) at ${this.base} — pod unreachable or state gone`);
+    }
+    this.etags.set('', listing.etag);
+    const names = listing.names.filter(n => n.endsWith('.json'));
+    let fetched = 0;
+    const skipped = [];
+    for (const name of names) {
+      const etag = force ? null : this.etags.get(name);
+      const r = await this.storage.read(name, { etag: etag && this.cache.has(name) ? etag : null });
+      if (r.notModified) continue;                        // ours is current
+      if (!r.ok) {
+        // One unreadable document must not restart the whole sweep — skip it,
+        // keep whatever we already hold, and try again next load (no etag is
+        // recorded, so the retry is unconditional). config.json is the
+        // exception: without it the caller cannot tell "never set up" from
+        // "could not read", and would tell the user to run setup.
+        if (name === 'config.json' && !this.cache.has(name)) {
+          throw new Error(`state doc ${name} unreadable (HTTP ${r.status})`);
+        }
+        skipped.push(`${name} (HTTP ${r.status})`);
+        continue;
+      }
+      fetched++;
+      this.etags.set(name, r.etag);
+      try { this.cache.set(name, JSON.parse(r.body)); }
+      catch (e) { this.log(`state load ${name}: unparsable (${e.message})`); }
+    }
+    if (skipped.length) this.log(`state load skipped ${skipped.length}: ${skipped.join(', ')}`);
+    this.log(`state loaded: ${this.cache.size} doc(s) from ${this.base} (${fetched} re-fetched)`);
+  }
+
+  has(name) { return this.cache.has(name); }
+
+  read(name, fallback) {
+    return this.cache.has(name) ? structuredClone(this.cache.get(name)) : fallback;
+  }
+
+  write(name, obj) {
+    this.cache.set(name, structuredClone(obj));
+    if (!this.storage) return;
+    // Held: record it and leave the writing to the commit boundary the caller
+    // already has. See hold().
+    if (this._held) { this.dirty.add(name); return; }
+    this._arm(name);
+  }
+
+  _arm(name) {
+    clearTimeout(this.timers.get(name));
+    this.timers.set(name, setTimeout(() => { this.timers.delete(name); this._put(name); }, PUT_DEBOUNCE_MS));
+    this.timers.get(name).unref?.();
+  }
+
+  // Suspend the debounce for the length of a sweep.
+  //
+  // 300ms coalesces writes that arrive together, and the inbox drain's never
+  // do: every handler awaits a signed fetch to somebody else's server first, so
+  // each item's timer fires before the next item is even read. statuses.json,
+  // actors.json and notifications.json were therefore serialized and written
+  // WHOLE once per item — fifty times in a fifty-item sweep, where the drain
+  // already commits every ten.
+  //
+  // Nested, because a drain can run a handler that starts another. release()
+  // re-arms anything still dirty rather than dropping it, so a write made by
+  // something else while the drain held the store is never stranded.
+  hold() { this._held = (this._held || 0) + 1; }
+
+  release() {
+    if (this._held) this._held -= 1;
+    if (this._held) return;
+    for (const name of [...this.dirty]) { this.dirty.delete(name); this._arm(name); }
+  }
+
+  // Resolves true when the document is on the pod, false when it is not — a
+  // caller that is about to destroy the only other copy of something needs to
+  // be able to tell. `chain` stays the bare serializer; the boolean rides on
+  // the returned promise so one failure cannot poison the queue.
+  _put(name) {
+    const done = this.chain.then(async () => {
+      const body = JSON.stringify(this.cache.get(name), null, 2) + '\n';
+      for (let attempt = 1; attempt <= PUT_RETRIES; attempt++) {
+        // A storage that throws is a bug, not a hiccup — but it must not
+        // escape into the write queue, where it would look like success.
+        const r = await this.storage.write(name, body, 'application/json')
+          .catch(e => ({ ok: false, retry: false, why: e.message }));
+        if (r.ok) return true;
+        // The storage says whether trying again could possibly help: a pod's
+        // 4xx is an answer rather than a hiccup, and a directory's EACCES will
+        // still be an EACCES in two seconds.
+        if (!r.retry) { this.log(`state write ${name} refused (${r.why}) — not retrying`); return false; }
+        if (attempt === PUT_RETRIES) { this.log(`state write ${name} gave up: ${r.why}`); return false; }
+        const ladder = Math.min(attempt * 2000, 30_000);
+        await new Promise(res => setTimeout(res, r.retryAfterMs || Math.round(ladder * (0.8 + Math.random() * 0.4))));
+      }
+      return false;
+    });
+    // Record the outcome. A write whose debounce fires on its own is not in
+    // any caller's hands: `chain` waits for it but throws its result away, so
+    // commit() reported a clean sweep for a document that had been refused —
+    // and commit()'s one caller is the inbox drain, about to delete the pod's
+    // only copy of what that document describes.
+    const tracked = done.then((ok) => { this.verdicts.set(name, ok); return ok; });
+    this.chain = tracked.then(() => {}, () => {});
+    return tracked;
+  }
+
+  // Remove a state doc from the cache AND the pod (used when key material
+  // migrates to the local machine — leaving the copy behind would defeat it).
+  async remove(name) {
+    this.cache.delete(name);
+    clearTimeout(this.timers.get(name));
+    this.timers.delete(name);
+    if (!this.storage) return true;
+    return this.storage.remove(name);
+  }
+
+  // Force every pending write out NOW and say whether they all landed.
+  // The caller that needs this is the inbox drain: taking an item out of the
+  // pod's inbox is a destructive read, so it must not happen until the result
+  // of handling it is written down. With no storage the store is pure memory
+  // and there is nothing to land, so that counts as written.
+  async commit() {
+    const pending = [];
+    // Held names too, or a sweep that suspended the debounce would delete the
+    // pod's copy of an item whose result had not been written down — the one
+    // thing commit() exists to prevent.
+    for (const name of new Set([...this.timers.keys(), ...this.dirty])) {
+      const t = this.timers.get(name);
+      if (t) { clearTimeout(t); this.timers.delete(name); }
+      this.dirty.delete(name);
+      pending.push(this._put(name));
+    }
+    await this.chain;                      // includes anything already in flight
+    await Promise.all(pending);
+    // Every verdict since the last commit, forced and self-fired alike. Cleared
+    // once read: a refusal is reported to the caller that can act on it, and
+    // does not then condemn every later commit.
+    const landed = [...this.verdicts.values()].every(Boolean);
+    this.verdicts.clear();
+    return landed;
+  }
+
+  // Flush pending debounced writes (shutdown path). Same work, result ignored.
+  async flush() { await this.commit(); }
+
+  // ---- the domain helpers, unchanged from dk's Store ----
+
+  // config: { remotePod, handle, name, issuer }  (credential lives ONLY in
+  // the local credential file, never in pod state)
+  getConfig() { return this.read('config.json', null); }
+  setConfig(cfg) { this.write('config.json', cfg); }
+
+  // queue: [{ inbox, activity, attempts, nextAt }]
+  getQueue() { return this.read('queue.json', []); }
+  setQueue(q) { this.write('queue.json', q); }
+
+  // blocklist: { domains: ["spam.example", ...], actors: ["https://host/actor", ...] }
+  // Two granularities because a whole instance is usually the wrong unit: one
+  // bad neighbour should not cost you everyone else on their server.
+  getBlocklist() {
+    const b = this.read('blocklist.json', {});
+    return { domains: b.domains || [], actors: b.actors || [] };
+  }
+  setBlocklist(b) { this.write('blocklist.json', b); }
+  // Takes an actor URL or an object URL: the actor list only ever matches the
+  // former, the domain list matches either.
+  isBlocked(url) {
+    let host;
+    try { host = new URL(url).hostname; } catch { return true; }   // unparsable → treat as hostile
+    const { domains, actors } = this.getBlocklist();
+    if (actors.includes(url)) return true;
+    return domains.some(d => host === d || host.endsWith('.' + d));
+  }
+
+  // contacts: { followers: [{actor, inbox, sharedInbox}], following: [{actor, inbox, accepted}] }
+  getContacts() { return this.read('contacts.json', { followers: [], following: [] }); }
+  setContacts(c) { this.write('contacts.json', c); }
+
+  // muted: { actors: [...] } — members whose posts a group declines to carry.
+  // A group cannot force an unfollow, so declining to amplify is the only
+  // lever it actually holds.
+  getMuted() { return this.read('muted.json', { actors: [] }); }
+  setMuted(m) { this.write('muted.json', m); }
+
+  // The client's own reading arrangements — lists, keyword filters, posts
+  // waiting to be published. None of it federates.
+  getLists() { return this.read('lists.json', []); }
+  setLists(l) { this.write('lists.json', l); }
+  getFilters() { return this.read('filters.json', []); }
+  setFilters(f) { this.write('filters.json', f); }
+  getScheduled() { return this.read('scheduled.json', []); }
+  setScheduled(s) { this.write('scheduled.json', s); }
+
+  // pending: [{ noteId, actor, at }] — posts a reviewed group has ingested but
+  // not carried, awaiting the operator.
+  getPending() { return this.read('pending.json', []); }
+  setPending(p) { this.write('pending.json', p); }
+
+  // requests: [{ actor, inbox, sharedInbox, activity, at }] — Follows a group
+  // with approveJoins has neither accepted nor rejected. The whole Follow is
+  // kept because the Accept or Reject has to name it.
+  getRequests() { return this.read('requests.json', []); }
+  setRequests(r) { this.write('requests.json', r); }
+
+  // dead letters: inbox items that failed verification or exhausted retries —
+  // kept for inspection (GET /deadletter) instead of being destroyed.
+  getDeadLetters() { return this.read('deadletter.json', []); }
+  addDeadLetter(entry) {
+    const dl = this.getDeadLetters();
+    dl.unshift({ at: new Date().toISOString(), ...entry });
+    this.write('deadletter.json', dl.slice(0, 200));
+  }
+
+  // statuses index: operational mirror of what lives in the pod as RDF, in
+  // arrival order — the Mastodon-API facade serves timelines from this.
+  // [{ noteId, actor, content, published, inReplyTo, kind: 'timeline'|'post'|'tag' }]
+  getStatuses() { return this.read('statuses.json', []); }
+  // A count must not pay for a clone: nodeinfo and the instance document are
+  // public and answer strangers, so they read the cache directly.
+  countStatuses(kind = null) {
+    const all = this.cache.get('statuses.json') || [];
+    return kind === null ? all.length : all.reduce((n, s) => n + (s.kind === kind ? 1 : 0), 0);
+  }
+  addStatus(s) {
+    const all = this.getStatuses();
+    if (all.some(x => x.noteId === s.noteId)) return;
+    // Same reason as cacheActor: statuses.json is serialized whole on every
+    // change, and remote content is only bounded by the 5 MB fetch ceiling.
+    if (typeof s.content === 'string' && s.content.length > MAX_CONTENT) {
+      s = { ...s, content: clamp(s.content, MAX_CONTENT), truncated: true };
+    }
+    all.unshift(s);
+    this.write('statuses.json', all.slice(0, 1000));
+    this.onEvent?.('status', s);            // streaming subscribers
+  }
+  updateStatus(noteId, patch) {
+    const all = this.getStatuses();
+    const i = all.findIndex(x => x.noteId === noteId);
+    if (i < 0) return null;
+    all[i] = { ...all[i], ...patch };
+    this.write('statuses.json', all);
+    return all[i];
+  }
+  removeStatus(noteId) {
+    this.write('statuses.json', this.getStatuses().filter(x => x.noteId !== noteId));
+  }
+
+  // notifications: what other actors did to us — the facade serves
+  // /api/v1/notifications from this. [{ id, type, actor, noteId?, at }]
+  // The id is a content hash, so a re-delivered activity dedupes.
+  getNotifications() { return this.read('notifications.json', []); }
+
+  // `unverified` marks one whose actor nothing vouched for — a Like or Announce
+  // arrives with no signature and, unlike a Create, has no object at the
+  // sender's origin to re-read, so the actor is whatever the body claimed.
+  //
+  // It decides what the cap evicts. The id is a content hash, so changing one
+  // character of the actor gives a fresh entry: ~500 appends into the pod's
+  // public-append inbox used to push out every real favourite, boost, mention
+  // and follow request, and notifications are the one thing nothing can rebuild
+  // — not from the pod, not from the RDF. Unverified entries are dropped first
+  // now, so a flood can only ever evict itself, and a stranger's genuine
+  // favourite still shows up, which is what recording them at all is for.
+  addNotification(n) {
+    const all = this.getNotifications();
+    const id = crypto.createHash('sha256').update(JSON.stringify(n)).digest('hex').slice(0, 16);
+    if (all.some(x => x.id === id)) return;
+    const entry = { id, at: new Date().toISOString(), ...n };
+    all.unshift(entry);
+    let kept = all;
+    if (kept.length > NOTIFICATIONS_MAX) {
+      const solid = kept.filter(x => !x.unverified);
+      const loose = kept.filter(x => x.unverified);
+      kept = solid.length >= NOTIFICATIONS_MAX
+        ? solid.slice(0, NOTIFICATIONS_MAX)
+        : [...solid, ...loose.slice(0, NOTIFICATIONS_MAX - solid.length)]
+          .sort((a, b) => String(b.at).localeCompare(String(a.at)));
+    }
+    this.write('notifications.json', kept);
+    this.onEvent?.('notification', entry);  // streaming subscribers
+  }
+
+  // uploaded media registry: opaque id → { url, mediaType, description }
+  getMedia() { return this.read('media.json', {}); }
+  setMedia(id, entry) {
+    const m = this.getMedia();
+    m[id] = entry;
+    this.write('media.json', m);
+  }
+
+  // actor-doc cache for account rendering (display name, avatar).
+  //
+  // Everything here comes from a document at someone else's origin, and the
+  // facade serves `summary` back to the client as a status account's `note`,
+  // which every Mastodon client renders as HTML. Note CONTENT was sanitized at
+  // all four of its entry points and this, the other thing a remote party
+  // writes, was not — so looking anyone up handed their markup to the client.
+  // Sanitized at the boundary where it enters our store, so nothing downstream
+  // has to remember. Names are plain text and are stripped outright.
+  getActors() { return this.read('actors.json', {}); }
+  cacheActor(url, doc) {
+    const a = this.getActors();
+    a[url] = {
+      name: clamp(plainText(doc.name || doc.preferredUsername || ''), MAX_NAME),
+      preferredUsername: clamp(plainText(doc.preferredUsername || ''), MAX_NAME),
+      icon: safeUrl(typeof doc.icon === 'object' ? doc.icon?.url : doc.icon),
+      image: safeUrl(typeof doc.image === 'object' ? doc.image?.url : doc.image),
+      summary: clamp(sanitizeHtml(doc.summary || ''), MAX_SUMMARY),
+      // A Group is an actor too, and a client that cannot tell shows it as a
+      // person. The counts are NOT in this document — they are the collections'
+      // totalItems, filled in only when someone asks about this actor by name.
+      type: doc.type || 'Person',
+      followers: doc.followers || null,
+      following: doc.following || null,
+      ...(a[url]?.counts ? { counts: a[url].counts } : {}),
+      fetchedAt: new Date().toISOString(),
+    };
+    this.write('actors.json', prune(a, ACTOR_CACHE_MAX, this.getContacts()));
+  }
+
+  // @user@host for an actor we have cached. Null when we have not, rather than
+  // a last-segment guess off the URL: that guess is what rendered a group as
+  // @actor@host, because our own actors all end in /actor.
+  handleOf(actorUrl) {
+    const user = this.getActors()[actorUrl]?.preferredUsername;
+    if (!user) return null;
+    try { return `@${user}@${new URL(actorUrl).host}`; } catch { return null; }
+  }
+
+  // Mastodon-API opaque ids ↔ URLs (snac-style: hashes are fine for clients).
+  getIds() { return this.read('ids.json', {}); }
+  // The id is a hash OF the url, so the mapping is computable — the scan was
+  // only ever finding what the hash already tells us. It ran on the status
+  // render path, once per rendered status, over a map that never shrinks.
+  //
+  // The map is still kept, because urlFor has to answer for ids a client is
+  // still holding, and it is still consulted first so an entry written under
+  // some older scheme keeps resolving.
+  idFor(url) {
+    const id = crypto.createHash('sha256').update(url).digest('hex').slice(0, 16);
+    const ids = this.getIds();
+    if (ids[id] === url) return id;                    // already known, nothing to write
+    const legacy = Object.entries(ids).find(([, u]) => u === url);
+    if (legacy) return legacy[0];                      // pre-hash entry a client may hold
+    ids[id] = url;
+    this.write('ids.json', ids);
+    return id;
+  }
+  urlFor(id) { return this.getIds()[id] || null; }
+}

package/lib/streaming.mjs

@@ -0,0 +1,154 @@
+// streaming.mjs — the Mastodon streaming API over a hand-rolled WebSocket
+// server (send-mostly; we answer pings and ignore everything else a client
+// frames at us). No dependencies — the handshake is one SHA-1 and text
+// frames are trivial to emit. Clients connect to
+//   ws://host/api/v1/streaming?access_token=…&stream=user
+// and receive {stream, event, payload} messages for new statuses and
+// notifications the moment the agent learns of them.
+
+import crypto from 'node:crypto';
+
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+// One identity's live feed is a handful of that owner's clients, so these are
+// generous. Without them a single token could hold every file descriptor open,
+// and one client that stops reading would grow its write buffer forever.
+const MAX_SOCKETS = 20;                       // matches the client-token cap
+const MAX_BUFFERED_BYTES = 1024 * 1024;       // a consumer this far behind is gone
+
+import { checkRequest } from './guard.mjs';
+
+export class Streaming {
+  constructor({ masto, log = console.log, allowed = null, gate = null, gateOptional = false }) {
+    this.masto = masto;
+    this.log = log;
+    this.allowed = allowed;
+    this.gate = gate;
+    // A pod-hosted identity is a public instance: a phone app arrives with its
+    // bearer and no way to send the operator's header, so there the bearer is
+    // the credential. Locally the gate stands in front of the socket as well.
+    this.gateOptional = gateOptional;
+    this.sockets = new Set();      // entries: { send(string), close() }
+  }
+
+  // Whether a client may open the live feed, asked of the upgrade request
+  // alone. Shared with the pod-server front, which completes the handshake
+  // before any of this runs and so must answer by closing rather than refusing.
+  authorizeUpgrade(req, url) {
+    const proto = String(req.headers['sec-websocket-protocol'] || '').split(',')[0].trim();
+    const token = url.searchParams.get('access_token') || proto;
+    const hasToken = this.masto.tokens().includes(token);
+    // WebSockets are exempt from CORS. A live bearer is the credential — a
+    // web client on its own origin connects the way it does to any Mastodon
+    // server — so with one, only the Host check stands (it is what stops DNS
+    // rebinding); without one the full Host/Origin firewall applies.
+    const bad = this.allowed ? checkRequest(req, this.allowed, { ignoreOrigin: hasToken }) : null;
+    if (bad) return `streaming refused: ${bad}`;
+    // A gate token covers every other route; an upgrade that skipped it was a
+    // hole in a control the operator had switched on. A client bearer is the
+    // other way in — a phone app has no way to send the operator's header.
+    if (this.gate && !this.gate.upgradeOk(req) && !(this.gateOptional && hasToken)) {
+      return 'streaming refused: no gate token';
+    }
+    if (!hasToken) return 'streaming refused: not a live client token';
+    if (this.sockets.size >= MAX_SOCKETS) return 'streaming refused: too many live connections';
+    return null;
+  }
+
+  // Adopt a WebSocket somebody else finished the handshake for — the pod
+  // server owns the socket, and hands over an object that already frames.
+  adopt(ws) {
+    const entry = {
+      send: (str) => {
+        // A consumer that stops reading must not keep costing memory.
+        if ((ws.bufferedAmount ?? 0) > MAX_BUFFERED_BYTES) {
+          this.sockets.delete(entry);
+          try { ws.close(); } catch { /* already gone */ }
+          return;
+        }
+        ws.send(str);
+      },
+      close: () => ws.close(),
+    };
+    this.sockets.add(entry);
+    const drop = () => this.sockets.delete(entry);
+    ws.on('close', drop);
+    ws.on('error', drop);
+    return entry;
+  }
+
+  // Let go of every client: the server is stopping, not the connection failing.
+  stop() {
+    for (const s of this.sockets) { try { s.close(); } catch { /* already gone */ } }
+    this.sockets.clear();
+  }
+
+  // Attach the upgrade handler to an http.Server.
+  attach(server) {
+    server.on('upgrade', (req, socket) => {
+      const url = new URL(req.url, 'http://localhost');
+      if (!url.pathname.startsWith('/api/v1/streaming')) { socket.destroy(); return; }
+      // WebSockets are exempt from CORS, so the Host/Origin firewall is the
+      // only thing standing between a visited page and the live feed.
+      const refusal = this.authorizeUpgrade(req, url);
+      if (refusal) {
+        this.log(refusal);
+        socket.write(refusal.includes('refused:') && !refusal.includes('token')
+          ? 'HTTP/1.1 403 Forbidden\r\n\r\n'
+          : 'HTTP/1.1 401 Unauthorized\r\n\r\n');
+        socket.destroy();
+        return;
+      }
+      const proto = String(req.headers['sec-websocket-protocol'] || '').split(',')[0].trim();
+      const accept = crypto.createHash('sha1')
+        .update(req.headers['sec-websocket-key'] + WS_MAGIC).digest('base64');
+      socket.write('HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n'
+        + `Sec-WebSocket-Accept: ${accept}\r\n`
+        + (proto ? `Sec-WebSocket-Protocol: ${proto}\r\n` : '') + '\r\n');
+      socket.setNoDelay(true);
+      const entry = {
+        send: (str) => {
+          // A consumer that stops reading must not keep costing memory.
+          if (socket.writableLength > MAX_BUFFERED_BYTES) {
+            this.sockets.delete(entry);
+            try { socket.destroy(); } catch { /* already gone */ }
+            return;
+          }
+          socket.write(this.frame(str));
+        },
+        close: () => { try { socket.end(); } catch { /* already gone */ } },
+      };
+      this.sockets.add(entry);
+      const drop = () => this.sockets.delete(entry);
+      socket.on('close', drop);
+      socket.on('error', drop);
+      socket.on('data', (buf) => {
+        if (buf.length && (buf[0] & 0x0f) === 0x9) {          // ping → pong
+          try { socket.write(Buffer.from([0x8a, 0x00])); } catch { drop(); }
+        }
+        if (buf.length && (buf[0] & 0x0f) === 0x8) { drop(); try { socket.end(); } catch {} }  // close
+      });
+    });
+  }
+
+  // Server→client unmasked text frame.
+  frame(str) {
+    const payload = Buffer.from(str);
+    let header;
+    if (payload.length < 126) header = Buffer.from([0x81, payload.length]);
+    else if (payload.length < 65536) {
+      header = Buffer.alloc(4); header[0] = 0x81; header[1] = 126; header.writeUInt16BE(payload.length, 2);
+    } else {
+      header = Buffer.alloc(10); header[0] = 0x81; header[1] = 127; header.writeBigUInt64BE(BigInt(payload.length), 2);
+    }
+    return Buffer.concat([header, payload]);
+  }
+
+  broadcast(event, payloadObj, streams = ['user']) {
+    if (!this.sockets.size) return;
+    const message = JSON.stringify({ stream: streams, event, payload: JSON.stringify(payloadObj) });
+    for (const s of this.sockets) {
+      try { s.send(message); } catch { this.sockets.delete(s); }
+    }
+  }
+}