@mmmbuto/nexuscrew 0.9.29 → 0.9.31

package/lib/notify/event-feed-acl.js

@@ -0,0 +1,95 @@
+'use strict';
+// lib/notify/event-feed-acl.js — per-peer projection of the event feed.
+//
+// The grants live in the node store and are the ONLY source of truth, read
+// fresh before every batch (a cached grant is a stale grant). Scope rules:
+//   - scope 'cell': eventsAccess AND the cell must be visible under
+//     cellVisibility. A hidden cell stays hidden through events.
+//   - scope 'node': eventsAccess AND nodeEventsAccess. nodeEventsAccess NEVER
+//     bypasses cellVisibility: cell lists inside node frames are projected by
+//     the same visibility rule, and hidden cells contribute neither names nor
+//     counts.
+
+const nodesStore = require('../nodes/store.js');
+const accessPresets = require('../nodes/access-presets.js');
+
+const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+
+function visibilityAllows(grants, cellId) {
+  const mode = grants.cellVisibility;
+  if (mode === 'all') return true;
+  if (mode === 'none') return false;
+  if (mode === 'selected') {
+    return Array.isArray(grants.cells) && typeof cellId === 'string' && grants.cells.includes(cellId);
+  }
+  return false; // malformed: denied, never guessed
+}
+
+// Effective grants of ONE peer, read fresh from the store. Unconfigured or
+// malformed records are denied everywhere (a paired peer is not, by itself,
+// allowed to read events). `revision` is the store-root access revision: the
+// signature lets the publisher detect grant changes cheaply.
+function peerGrants(store, peerNodeId) {
+  const node = (store && Array.isArray(store.nodes) ? store.nodes : [])
+    .find((n) => n && n.nodeId === peerNodeId && n.direction === 'inbound');
+  if (!node) return null;
+  const view = accessPresets.grantsOf(node);
+  const grants = {
+    eventsAccess: view.configured === true && node.eventsAccess === true,
+    nodeEventsAccess: view.configured === true && node.nodeEventsAccess === true,
+    askReplyAccess: view.configured === true && node.askReplyAccess === true,
+    cellVisibility: view.configured === true ? node.cellVisibility : 'none',
+    cells: Array.isArray(node.cells) ? [...node.cells] : [],
+    configured: view.configured === true,
+    label: view.label,
+  };
+  grants.signature = JSON.stringify({
+    e: grants.eventsAccess, n: grants.nodeEventsAccess, a: grants.askReplyAccess,
+    v: grants.cellVisibility, c: grants.cells, r: nodesStore.accessRevisionOf(store),
+  });
+  return grants;
+}
+
+// May this peer receive this envelope at all? The envelope's cellId is trusted
+// here because it was resolved by the OWNER (binding/roster), never taken from
+// a request body.
+function allowsEnvelope(grants, envelope) {
+  if (!grants || grants.configured !== true) return false;
+  if (grants.eventsAccess !== true) return false;
+  if (!envelope || typeof envelope !== 'object') return false;
+  if (envelope.scope === 'cell') {
+    if (!(typeof envelope.cellId === 'string' && CELL_ID_RE.test(envelope.cellId))) return false;
+    return visibilityAllows(grants, envelope.cellId);
+  }
+  if (envelope.scope === 'node') return grants.nodeEventsAccess === true;
+  return false;
+}
+
+// Project a list of cells (fleet frames, snapshot state) to what the peer may
+// see. Hidden cells contribute NOTHING: no names, no counts, no "there were N
+// more" hints.
+function projectCells(grants, cells) {
+  if (!Array.isArray(cells)) return [];
+  if (!grants || grants.eventsAccess !== true) return [];
+  if (grants.cellVisibility === 'all') return cells.slice(0, 1000);
+  if (grants.cellVisibility === 'selected') {
+    const allowed = new Set(Array.isArray(grants.cells) ? grants.cells : []);
+    return cells.filter((c) => c && allowed.has(c.cell));
+  }
+  return [];
+}
+
+// Full per-request decision + projection context. Returns null when the peer
+// record does not exist (unknown origin): the caller refuses.
+function resolvePeer(store, peerNodeId) {
+  const grants = peerGrants(store, peerNodeId);
+  if (!grants) return null;
+  return {
+    nodeId: peerNodeId,
+    grants,
+    allows: (envelope) => allowsEnvelope(grants, envelope),
+    projectCells: (cells) => projectCells(grants, cells),
+  };
+}
+
+module.exports = { peerGrants, allowsEnvelope, projectCells, visibilityAllows, resolvePeer, CELL_ID_RE };

package/lib/notify/event-feed-asks-routes.js

@@ -0,0 +1,144 @@
+'use strict';
+// lib/notify/event-feed-asks-routes.js — federated ask ANSWER surface.
+//
+//   POST   /event-feed/asks/:id/answer          {text, requestId}  (closed body)
+//   DELETE /event-feed/asks/:id                                    (dismiss)
+//   GET    /event-feed/asks/:id/requests/:requestId               (attempt status)
+//
+// The gate is the SAME as the stream/snapshot gate (kill-switch -> proven
+// federated origin -> exact [clientId, ownerId] -> known peer -> eventsAccess)
+// PLUS askReplyAccess plus the ask's own cell scope read from the ask store.
+// Unknown and out-of-scope ids get the SAME opaque 404: an id that does not
+// exist and an id the peer may not see must be indistinguishable. Answer and
+// dismiss run on a DEDICATED budget (6/min/peer, 30/min global) that shares
+// nothing with notify/audio/local ask creation.
+
+const express = require('express');
+const { createFeedGate } = require('./event-feed-routes.js');
+
+const ANSWER_RATE_PER_MIN = 6;
+const ANSWER_GLOBAL_PER_MIN = 30;
+
+function createAskRateLimiter({ now = Date.now } = {}) {
+  const perPeer = new Map();
+  const global = [];
+  function prune(list, t) {
+    const cutoff = t - 60000;
+    while (list.length > 0 && list[0] <= cutoff) list.shift();
+  }
+  function check(peerId) {
+    const t = now();
+    const list = perPeer.get(peerId) || [];
+    prune(list, t); prune(global, t);
+    if (list.length >= ANSWER_RATE_PER_MIN || global.length >= ANSWER_GLOBAL_PER_MIN) {
+      return { allowed: false, reason: 'answer-rate' };
+    }
+    list.push(t); perPeer.set(peerId, list); global.push(t);
+    return { allowed: true };
+  }
+  return { check };
+}
+
+function createEventFeedAsksRoutes(deps) {
+  const r = express.Router();
+  const json = express.json({ limit: '16kb' });
+  // deps: { nodesPath, localNodeId, originResolver, eventsEnabled, asks,
+  //         answerService, cellForSession, log }
+  const gate = createFeedGate(deps);
+  const rate = createAskRateLimiter({ now: deps.now });
+  const log = typeof deps.log === 'function' ? deps.log : () => {};
+
+  // Resolve the ask for THIS peer: the cell comes from the ask store (never
+  // from the request), then the peer's cell scope decides. Unknown and
+  // out-of-scope are the same opaque 404.
+  function resolveAskForPeer(peer, askId) {
+    const ask = deps.asks.get(askId);
+    if (!ask) return null;
+    const cellId = deps.cellForSession(ask.session);
+    if (!cellId || !peer.allows({ scope: 'cell', cellId })) return null;
+    return { ask, cellId };
+  }
+
+  r.post('/:id/answer', json, async (req, res) => {
+    const g = await gate(req, res);
+    if (!g) return;
+    const verdict = rate.check(g.peer.nodeId);
+    if (!verdict.allowed) return res.status(429).json({ error: 'answer rate', reason: verdict.reason });
+    if (deps.readonly && deps.readonly()) {
+      return res.status(403).json({ error: 'READONLY: mutazione bloccata' });
+    }
+    // askReplyAccess on top of the feed gate: seeing the card does not
+    // grant the action. It is re-read with the same fresh store the gate used.
+    if (g.peer.grants.askReplyAccess !== true) {
+      return res.status(403).json({ error: 'risorsa non concessa a questo nodo', reason: 'grant-required:ask-action' });
+    }
+    const askId = String(req.params.id || '');
+    const body = req.body && typeof req.body === 'object' ? req.body : {};
+    // CLOSED body: {text, requestId}. Anything that tries to choose a session,
+    // a target or an origin is a 400 before any other consideration.
+    for (const key of Object.keys(body)) {
+      if (!['text', 'requestId'].includes(key)) {
+        return res.status(400).json({ error: `campo non ammesso: "${key}"` });
+      }
+    }
+    if (typeof body.text !== 'string') return res.status(400).json({ error: 'text deve essere una stringa' });
+    const resolved = resolveAskForPeer(g.peer, askId);
+    if (!resolved) return res.status(404).json({ error: 'ask inesistente' });
+    const out = await deps.answerService.answerFederated({
+      askId, text: body.text, peerId: g.peer.nodeId, requestId: body.requestId,
+    });
+    if (out.ok) {
+      return res.json({ status: out.replay ? out.state : 'committed', requestId: body.requestId });
+    }
+    return res.status(out.code || 500).json({ error: out.error, reason: out.reason });
+  });
+
+  r.delete('/:id', async (req, res) => {
+    const g = await gate(req, res);
+    if (!g) return;
+    const verdict = rate.check(g.peer.nodeId);
+    if (!verdict.allowed) return res.status(429).json({ error: 'answer rate', reason: verdict.reason });
+    if (deps.readonly && deps.readonly()) {
+      return res.status(403).json({ error: 'READONLY: mutazione bloccata' });
+    }
+    if (g.peer.grants.askReplyAccess !== true) {
+      return res.status(403).json({ error: 'risorsa non concessa a questo nodo', reason: 'grant-required:ask-action' });
+    }
+    const askId = String(req.params.id || '');
+    const resolved = resolveAskForPeer(g.peer, askId);
+    if (!resolved) return res.status(404).json({ error: 'ask inesistente' });
+    // Local answer in flight wins: 409, and a dismissed ask is not answerable.
+    const out = deps.answerService.dismiss(askId);
+    if (!out.ok) {
+      if (out.reason === 'unknown') return res.status(404).json({ error: 'ask inesistente' });
+      if (out.reason === 'answering') return res.status(409).json({ error: 'risposta in corso: non si scarta un ask in answering' });
+      return res.status(500).json({ error: 'dismiss non riuscito' });
+    }
+    return res.json({ dismissed: true, id: askId, idempotent: out.idempotent === true });
+  });
+
+  r.get('/:id/requests/:requestId', async (req, res) => {
+    const g = await gate(req, res);
+    if (!g) return;
+    if (g.peer.grants.askReplyAccess !== true) {
+      return res.status(403).json({ error: 'risorsa non concessa a questo nodo', reason: 'grant-required:ask-action' });
+    }
+    const askId = String(req.params.id || '');
+    const requestId = String(req.params.requestId || '');
+    const resolved = resolveAskForPeer(g.peer, askId);
+    if (!resolved) return res.status(404).json({ error: 'ask inesistente' });
+    // Scoped: a peer sees ONLY its own attempts, and never the answer text of
+    // anyone — the receipt carries a digest, not a payload.
+    const entry = deps.receipts.get(g.peer.nodeId, askId, requestId);
+    if (!entry) return res.status(404).json({ error: 'ask inesistente' });
+    return res.json({
+      requestId, askId, state: entry.state,
+      ...(entry.receipt ? { receipt: entry.receipt } : {}),
+      ...(entry.updatedAt ? { updatedAt: entry.updatedAt } : {}),
+    });
+  });
+
+  return r;
+}
+
+module.exports = { createEventFeedAsksRoutes, createAskRateLimiter };

package/lib/notify/event-feed-client.js

@@ -0,0 +1,434 @@
+'use strict';
+// lib/notify/event-feed-client.js — the subscriber that runs in the CLIENT
+// server, one subscription per paired owner with eventsReceive=true.
+//
+// Hard rules: the peer is chosen ONLY from the authorized node
+// store — never a host/port/URL taken from an event; the Hydra route is opened
+// with the server-side Bearer; the FIRST access (and every reset) is a
+// SNAPSHOT, then the SSE stream resumes from the snapshot cursor; a frame
+// attributed to another owner disconnects the stream; imported events are
+// re-emitted locally ONLY — they can never re-enter a publisher, so A→B→A
+// dies by construction. Transport failures back off with jitter 5→60 s; a
+// stream silent for 60 s is aborted and resynced.
+
+const BACKOFF_MIN_MS = 5000;
+const BACKOFF_MAX_MS = 60000;
+const IDLE_TIMEOUT_MS = 60000;
+const MAX_CONSECUTIVE_RESETS = 3;
+
+// Ingress budgets: 120 frames/min and 1 MiB/min per owner, plus a separate
+// federated global window of 480 frames/min and 4 MiB/min. The counters are
+// FRAMES, not transport chunks: one read() carries a whole round, and 121
+// frames inside a single chunk must not pass as one.
+const INGRESS_WINDOW_MS = 60000;
+const INGRESS_MAX_FRAMES = 120;
+const INGRESS_MAX_BYTES = 1024 * 1024;
+const INGRESS_GLOBAL_MAX_FRAMES = 480;
+const INGRESS_GLOBAL_MAX_BYTES = 4 * 1024 * 1024;
+const INGRESS_BLOCK_BACKOFF_MS = 5000;
+
+// Snapshot caps, enforced by the CLIENT as a floor of its own: the owner
+// publishes them too, but a rogue owner is not trusted to police itself. The
+// element schema is the frame schema (bounded id, bounded element size).
+const SNAPSHOT_MAX_ASKS = 100;
+const SNAPSHOT_MAX_NOTIFY = 50;
+const SNAPSHOT_MAX_CELLS = 1000;
+const SNAPSHOT_ELEMENT_MAX_BYTES = 16 * 1024;
+const SNAPSHOT_ID_MAX_CHARS = 64;
+
+function createEventFeedClient(opts = {}) {
+  // deps: { nodesPath, token(), eventsHub, now, fetchImpl, log }
+  const fetchImpl = opts.fetchImpl || fetch;
+  const now = opts.now || Date.now;
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+  // ownerId -> view state {cursor, generation, asks, notifications, fleetState,
+  //   stale, lastError}; generation guards against obsolete fetches.
+  const views = new Map();
+  const running = new Map(); // nodeId -> {abort}
+  let stopped = false;
+  let generation = 0;
+
+  function backoffMs(peer) {
+    const fails = (peer._fails || 0) + 1;
+    peer._fails = fails;
+    const base = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * Math.pow(2, fails - 1));
+    return Math.floor(base / 2 + Math.random() * (base / 2));
+  }
+
+  function viewFor(ownerId) {
+    if (!views.has(ownerId)) {
+      views.set(ownerId, { ownerId, cursor: null, asks: [], notifications: [], fleetState: null, stale: true, generation: 0 });
+    }
+    return views.get(ownerId);
+  }
+
+  // One resync round that ended WITHOUT a usable frame counts as a reset: a
+  // peer that keeps asking to resync (409 reset-required / cursor-future, or a
+  // frame from an unknown epoch) would otherwise be re-snapshotted forever.
+  // Past the cap the view goes to the error state and the poll gate stops it;
+  // a single healthy frame clears the streak.
+  function noteReset(view) {
+    view.consecutiveResets = (view.consecutiveResets || 0) + 1;
+    if (view.consecutiveResets >= MAX_CONSECUTIVE_RESETS) {
+      view.stale = true;
+      view.lastError = 'resync-exhausted';
+    }
+  }
+
+  function routeUrl(peer, resource, query = '') {
+    // Peer identity comes from the STORE record (name + localPort + token):
+    // nothing here ever reads a target from an event frame.
+    return `http://127.0.0.1:${peer.localPort}/federation/route/_/${resource.startsWith('/') ? resource.slice(1) : resource}${query}`;
+  }
+
+  function dedupKey(envelope) { return `${envelope.ownerId}:${envelope.eventId}`; }
+  const seen = new Map(); // dedupKey -> at, bounded to the replay horizon
+
+  function markSeen(key) {
+    seen.set(key, now());
+    if (seen.size > 2000) {
+      const cutoff = now() - 16 * 60 * 1000;
+      for (const [k, at] of seen) if (at < cutoff) seen.delete(k);
+    }
+  }
+
+  // Apply a fetched snapshot ONLY if it belongs to the current generation:
+  // an obsolete fetch must never overwrite a newer view (the snapshot
+  // WINS over the previous view of the same owner).
+  function applySnapshot(ownerId, snap, gen) {
+    const view = viewFor(ownerId);
+    if (gen !== generation) return false;
+    view.cursor = snap.cursor || null;
+    view.asks = Array.isArray(snap.asks) ? snap.asks.map((a) => ({ ...a, ownerId })) : [];
+    view.notifications = Array.isArray(snap.notifications) ? snap.notifications.map((e) => ({ ...e, ownerId })) : [];
+    view.fleetState = snap.fleetState || null;
+    view.askReplyAccess = snap.askReplyAccess === true;
+    view.viewEpoch = snap.viewEpoch;
+    view.stale = false;
+    view.generation = gen;
+    return true;
+  }
+
+  // Local re-emission of ONE imported envelope: attributed to the owner, into
+  // the local SSE hub only. The hub is the browser-facing surface — this call
+  // deliberately bypasses the notifier so the imported event can never be
+  // recorded into a feed history or re-published to other peers.
+  function reemit(envelope) {
+    const key = dedupKey(envelope);
+    if (seen.has(key)) return false;
+    markSeen(key);
+    if (!envelope.frame || envelope.hop !== 1) return false;
+    const f = envelope.frame;
+    if (f.type === 'notify') {
+      opts.eventsHub.broadcast({
+        type: 'notify', title: f.title, ...(f.body ? { body: f.body } : {}),
+        urgency: f.urgency === 'high' ? 'high' : 'normal',
+        ...(f.lang ? { lang: f.lang } : {}),
+        ...(f.askId ? { askId: String(f.askId) } : {}),
+        originNode: envelope.ownerId, ownerId: envelope.ownerId,
+        ...(envelope.scope === 'cell' && envelope.cellId ? { originCell: envelope.cellId } : {}),
+        eventId: envelope.eventId, ts: Date.now(),
+      });
+    } else if (f.type === 'ask') {
+      opts.eventsHub.broadcast({ type: 'ask', ownerId: envelope.ownerId, eventId: envelope.eventId,
+        ask: { id: f.askId, question: f.question, options: f.options, session: f.session, ownerId: envelope.ownerId } });
+    } else if (f.type === 'ask-closed') {
+      opts.eventsHub.broadcast({ type: f.outcome === 'dismissed' ? 'ask-dismissed' : 'ask-answered',
+        id: f.askId, ownerId: envelope.ownerId, eventId: envelope.eventId });
+    } else if (f.type === 'file-notice') {
+      opts.eventsHub.broadcast({ type: 'notify', title: `file: ${f.name}`, ...(f.caption ? { body: f.caption } : {}),
+        originNode: envelope.ownerId, ownerId: envelope.ownerId,
+        // Stessa attribuzione di cella del ramo notify: un file e' un avviso
+        // DELLA CELLA, e senza questo campo il relay lo contava come scope nodo
+        // (budget diverso: 7 avvisi invece di 6).
+        ...(envelope.scope === 'cell' && envelope.cellId ? { originCell: envelope.cellId } : {}),
+        eventId: envelope.eventId, ts: Date.now() });
+    } else if (f.type === 'fleet-state' || f.type === 'node-state') {
+      opts.eventsHub.broadcast({ type: 'feed-state', ownerId: envelope.ownerId, eventId: envelope.eventId, state: f });
+    }
+    return true;
+  }
+
+  // One streaming session against one owner. Resolves when the stream ends.
+  // First-hop identity headers: the visited chain starts with THIS node (the
+  // owner's gate re-binds it to the token-authenticated peer, so a client can
+  // only ever claim itself) and the hop proof is minted on the owner side.
+  function identityHeaders(peer, store) {
+    return {
+      authorization: `Bearer ${peer.token}`,
+      'x-nexuscrew-visited': store.nodeId,
+    };
+  }
+
+  const ingress = { frames: [], bytes: [], globalFrames: [], globalBytes: [] };
+
+  // Admits ONE frame and returns the window that tripped, or null. The record is
+  // always written: a refused frame still happened on the wire.
+  function ingressTrip(t, bytes, ownerId) {
+    const cutoff = t - INGRESS_WINDOW_MS;
+    const slide = (list) => { while (list.length && list[0].t <= cutoff) list.shift(); };
+    slide(ingress.frames); slide(ingress.bytes); slide(ingress.globalFrames); slide(ingress.globalBytes);
+    ingress.frames.push({ t, ownerId }); ingress.bytes.push({ t, bytes, ownerId });
+    ingress.globalFrames.push({ t }); ingress.globalBytes.push({ t, bytes });
+    const ownBytes = ingress.bytes.filter((x) => x.ownerId === ownerId).reduce((a, x) => a + x.bytes, 0);
+    const globalBytes = ingress.globalBytes.reduce((a, x) => a + x.bytes, 0);
+    const ownFrames = ingress.frames.filter((x) => x.ownerId === ownerId).length;
+    if (ownFrames > INGRESS_MAX_FRAMES) return 'owner-frames';
+    if (ownBytes > INGRESS_MAX_BYTES) return 'owner-bytes';
+    if (ingress.globalFrames.length > INGRESS_GLOBAL_MAX_FRAMES) return 'global-frames';
+    if (globalBytes > INGRESS_GLOBAL_MAX_BYTES) return 'global-bytes';
+    return null;
+  }
+
+  // The block lasts until the window that tripped frees capacity — its oldest
+  // record ages out — plus a bounded backoff: the next poll must not restart
+  // while that counter is still full.
+  function ingressBlockUntil(reason, t, ownerId) {
+    const own = (list) => list.filter((x) => x.ownerId === ownerId);
+    const list = reason === 'global-frames' ? ingress.globalFrames
+      : reason === 'global-bytes' ? ingress.globalBytes
+        : reason === 'owner-bytes' ? own(ingress.bytes) : own(ingress.frames);
+    const oldest = list.length ? list[0].t : t;
+    return Math.max(oldest + INGRESS_WINDOW_MS, t) + INGRESS_BLOCK_BACKOFF_MS;
+  }
+
+  async function streamOnce(peer, ownerId, store) {
+    const view = viewFor(ownerId);
+    // The deadline expired: the peer is admitted again and the block is closed
+    // by the transition that reopens the stream, not by a silent timeout.
+    if (view.ingressBlockedUntil && view.ingressBlockedUntil <= Date.now()) {
+      view.ingressBlockedUntil = null;
+      view.ingressBlockReason = null;
+    }
+    const after = view.cursor ? `?after=${encodeURIComponent(view.cursor)}` : '';
+    const ctrl = new AbortController();
+    running.set(ownerId, { abort: () => ctrl.abort() });
+    let timer = setTimeout(() => ctrl.abort(), IDLE_TIMEOUT_MS); // 60 s without bytes
+    try {
+      const r = await fetchImpl(routeUrl(peer, '/event-feed', after), {
+        headers: identityHeaders(peer, store), signal: ctrl.signal,
+      });
+      if (r.status === 403 && (await r.json().catch(() => ({}))).reason === 'events-disabled') {
+        view.stale = true; return;
+      }
+      if (r.status === 409) { // reset-required / cursor-future: resync from a fresh snapshot
+        view.cursor = null;
+        noteReset(view);
+        return;
+      }
+      if (!r.ok) { view.stale = true; throw new Error(`event-feed HTTP ${r.status}`); }
+      peer._fails = 0;
+      const reader = r.body.getReader();
+      const dec = new TextDecoder();
+      let buffer = '';
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        // ONE idle timer, rearmed on every chunk: a stale armed timeout must
+        // never survive next to a new one.
+        clearTimeout(timer);
+        timer = setTimeout(() => ctrl.abort(), IDLE_TIMEOUT_MS);
+        const chunk = dec.decode(value, { stream: true });
+        buffer += chunk;
+        let idx;
+        while ((idx = buffer.indexOf('\n\n')) >= 0) {
+          const block = buffer.slice(0, idx); buffer = buffer.slice(idx + 2);
+          if (block.startsWith(':')) continue; // heartbeat
+          const dataLine = block.split('\n').find((l) => l.startsWith('data: '));
+          if (!dataLine) continue;
+          // Frame cap BEFORE JSON.parse.
+          if (dataLine.length > 16 * 1024) { log('event-feed-client: oversized frame, resync'); view.cursor = null; return; }
+          // Ingress budget, counted per FRAME on the wire BEFORE it is parsed or
+          // applied: over the cap this peer is disconnected by name and blocked
+          // for the rest of its window, while the other owners keep streaming.
+          const at = Date.now();
+          const trip = ingressTrip(at, Buffer.byteLength(block, 'utf8'), ownerId);
+          if (trip) {
+            view.lastError = 'ingress-budget';
+            view.ingressBlockReason = trip;
+            view.ingressBlockedUntil = ingressBlockUntil(trip, at, ownerId);
+            view.stale = true;
+            log(`event-feed-client: ${ownerId.slice(0, 8)}… ingress-budget (${trip}), blocked for ${Math.round((view.ingressBlockedUntil - at) / 1000)} s`);
+            // The transport is closed explicitly: an abandoned response would
+            // keep the socket (and the owner's writer) alive until the GC.
+            try { await reader.cancel(); } catch (_) { /* already closing */ }
+            ctrl.abort();
+            return;
+          }
+          let envelope;
+          try { envelope = JSON.parse(dataLine.slice(6)); } catch (_) { view.cursor = null; return; }
+          // Owner mismatch on a frame: disconnect, never apply.
+          if (envelope.ownerId !== ownerId) { log('event-feed-client: owner mismatch, disconnect'); return; }
+          // Sequence continuity within the same epoch; anything else resyncs.
+          const [, seqStr] = (block.split('\n').find((l) => l.startsWith('id: ')) || '').split(': ');
+          const [epochStr, sStr] = String(seqStr || '').split(':');
+          if (Number(epochStr) !== view.viewEpoch) {
+            view.cursor = null;
+            noteReset(view);
+            return;
+          }
+          if (view.lastSeq !== undefined && Number(sStr) !== view.lastSeq + 1) { view.cursor = null; return; }
+          view.lastSeq = Number(sStr);
+          view.consecutiveResets = 0; // a usable frame: the streak is over
+          view.cursor = `${epochStr}:${sStr}`;
+          reemit(envelope);
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+      running.delete(ownerId);
+    }
+  }
+
+  // Capability BEFORE subscribing: an owner without the feed capability makes
+  // the view unsupported — no fallback, no infinite backoff.
+  async function checkCapability(peer, ownerId) {
+    const view = viewFor(ownerId);
+    if (view.capabilityChecked) return true;
+    // The health endpoint of the OWNER is probed directly (same pattern as
+    // the tunnel health probe): /federation/health with the peer's token.
+    const r = await fetchImpl(`http://127.0.0.1:${peer.localPort}/federation/health`, {
+      headers: { authorization: `Bearer ${peer.token}` },
+    });
+    if (!r.ok) { view.stale = true; throw new Error(`health HTTP ${r.status}`); }
+    const body = await r.json();
+    if (body.eventFeedV1 !== true || body.instanceId !== ownerId) {
+      view.unsupported = true;
+      view.lastError = 'event-feed-unsupported';
+      // One transition log, not one per tick: the poll gate keeps this
+      // owner out from here on.
+      log(`event-feed-client: ${ownerId.slice(0, 8)}… no feed capability, subscription refused`);
+      return false;
+    }
+    view.capabilityChecked = true;
+    return true;
+  }
+
+  async function snapshotOnce(peer, ownerId, store) {
+    const view = viewFor(ownerId);
+    const gen = generation;
+    const r = await fetchImpl(routeUrl(peer, '/event-feed/snapshot'), {
+      headers: identityHeaders(peer, store),
+    });
+    if (!r.ok) { view.stale = true; throw new Error(`snapshot HTTP ${r.status}`); }
+    // Size cap BEFORE JSON.parse: a body over the server budget is refused on
+    // sight, never parsed.
+    const text = await r.text();
+    if (Buffer.byteLength(text, 'utf8') > 3 * 1024 * 1024) {
+      view.stale = true; view.lastError = 'snapshot-oversize';
+      return false;
+    }
+    const snap = JSON.parse(text);
+    // Owner mismatch on the snapshot: disconnect, never apply.
+    if (snap.ownerId !== ownerId) {
+      view.stale = true; view.lastError = 'owner-mismatch';
+      return false;
+    }
+    // Per-element sanity over EVERY list, not just the notify history: bounded
+    // id, bounded element, and the count caps. A snapshot that breaks any of
+    // them is refused whole — never applied in part.
+    const boundedId = (id) => typeof id === 'string' && id.length > 0 && id.length <= SNAPSHOT_ID_MAX_CHARS;
+    const boundedElement = (e) => !!e && typeof e === 'object'
+      && Buffer.byteLength(JSON.stringify(e), 'utf8') <= SNAPSHOT_ELEMENT_MAX_BYTES;
+    if (Array.isArray(snap.asks)
+      && (snap.asks.length > SNAPSHOT_MAX_ASKS
+        || !snap.asks.every((a) => boundedElement(a) && boundedId(a && a.id)))) {
+      view.stale = true; view.lastError = 'snapshot-element-oversize';
+      return false;
+    }
+    if (Array.isArray(snap.notifications)
+      && (snap.notifications.length > SNAPSHOT_MAX_NOTIFY
+        || !snap.notifications.every((e) => boundedElement(e) && boundedId(e && e.eventId)))) {
+      view.stale = true; view.lastError = 'snapshot-element-oversize';
+      return false;
+    }
+    if (snap.fleetState && typeof snap.fleetState === 'object') {
+      const cells = Array.isArray(snap.fleetState.cells) ? snap.fleetState.cells : [];
+      if (cells.length > SNAPSHOT_MAX_CELLS || !boundedElement(snap.fleetState)
+        || !cells.every((c) => boundedElement(c) && boundedId(c && c.cell))) {
+        view.stale = true; view.lastError = 'snapshot-element-oversize';
+        return false;
+      }
+    }
+    // A snapshot over the server budget is a floor, not a whole: resync.
+    if (snap.resyncRequired) { view.stale = true; return false; }
+    applySnapshot(ownerId, snap, gen);
+    return true;
+  }
+
+  // One reconciliation round across every enabled peer. Never throws.
+  async function poll() {
+    if (stopped) return;
+    const store = opts.loadStore();
+    if (!store) return;
+    const peers = (store.nodes || []).filter((n) => n && n.direction === 'outbound'
+      && n.eventsReceive === true && n.token && n.localPort && n.nodeId);
+    await Promise.all(peers.map(async (peer) => {
+      const ownerId = peer.nodeId;
+      if (running.has(ownerId)) return; // one loop per pair
+      const view = viewFor(ownerId);
+      try {
+        if (view.unsupported || (view.consecutiveResets || 0) >= MAX_CONSECUTIVE_RESETS
+          || (view.ingressBlockedUntil || 0) > Date.now()) return;
+        if (!view.capabilityChecked) {
+          const ok = await checkCapability(peer, ownerId);
+          if (!ok) return;
+        }
+        if (!view.cursor) {
+          const ok = await snapshotOnce(peer, ownerId, store);
+          if (!ok) return;
+        }
+        await streamOnce(peer, ownerId, store);
+      } catch (e) {
+        view.stale = true;
+        // A named feed reason (e.g. owner-mismatch) survives a later transport
+        // error: it is the reason the operator needs to see.
+        if (view.lastError !== 'owner-mismatch') {
+          view.lastError = String((e && e.message) || e);
+        }
+        const delay = backoffMs(peer);
+        log(`event-feed-client: ${ownerId.slice(0, 8)}… retry in ${delay} ms (${view.lastError})`);
+        setTimeout(() => { void poll(); }, delay);
+      }
+    }));
+  }
+
+  let pollTimer = null;
+  function start() {
+    stopped = false; generation += 1;
+    void poll();
+    // The store is written AFTER boot in real life (pairing happens later):
+    // keep scanning for newly enabled peers. Streams are long-lived, so this
+    // tick only ever picks up peers that are not running yet.
+    if (!pollTimer) {
+      pollTimer = setInterval(() => { void poll(); }, opts.pollMs || 4000);
+      if (typeof pollTimer.unref === 'function') pollTimer.unref();
+    }
+  }
+  function stop() {
+    stopped = true; generation += 1;
+    if (pollTimer) { clearInterval(pollTimer); pollTimer = null; }
+    for (const [, h] of running) { try { h.abort(); } catch (_) {} }
+  }
+
+  // Local aggregated read: connected views only, with the watermark the UI
+  // needs to initialize without racing the live stream.
+  function state() {
+    return {
+      views: [...views.entries()].map(([ownerId, v]) => ({
+        ownerId, cursor: v.cursor, viewEpoch: v.viewEpoch, stale: v.stale,
+        // Both sides of the merge matter to the UI: the answer/dismiss gate
+        // (askReplyAccess) and the ingress/error state of the view.
+        askReplyAccess: v.askReplyAccess === true,
+        lastError: v.lastError || null,
+        ingressBlockedUntil: v.ingressBlockedUntil || null,
+        ingressBlockReason: v.ingressBlockReason || null,
+        asks: v.asks, notifications: v.notifications, fleetState: v.fleetState,
+      })),
+    };
+  }
+
+  return { start, stop, poll, state, reemit, viewFor };
+}
+
+module.exports = { createEventFeedClient };