@mmmbuto/nexuscrew 0.9.77 → 0.9.78

package/lib/server.js

@@ -461,7 +461,7 @@ function createServer(opts = {}) {
   // route API: nessuna cella puo dichiararla dal body.
   const nodesPath = cfg.nodesPath || nodesStore.defaultNodesPath(cfg.home || os.homedir());
   const identityOwnerInstanceId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
-  const fleetP = selectProvider({ ...cfg, ensureTmuxProtection, identityOwnerInstanceId }).then((p) => p.fleet);
+  const fleetP = opts.fleetP || selectProvider({ ...cfg, ensureTmuxProtection, identityOwnerInstanceId }).then((p) => p.fleet);
 
   // Multi-node: nodes.json e' la fonte dati. Il proxy risolve <name>
   // -> {localPort, token} leggendo lo store ad ogni richiesta (fresh: rotazione
@@ -872,7 +872,14 @@ function createServer(opts = {}) {
   // routes never accept the NexusCrew UI bearer and expose only pair, poll and
   // self-unpair.  Operator management remains behind /api + federation ACL.
   app.use('/vl-node/v1', vlNodePublicRoutes({
-    storePath: vlNodesPath, broker: vlNodeBroker, ownerId: vlOwnerId,
+    storePath: vlNodesPath,
+    broker: vlNodeBroker,
+    ownerId: vlOwnerId,
+    cellSubmit: opts.cellSubmit || ((session, text, meta) => submitToSession(cfg.tmuxBin, session, text, {
+      engine: meta && meta.engine,
+    })),
+    fleetP,
+    readonly: proxyReadonly,
   }));
   // This route is deliberately outside the bearer-authenticated federation
   // router.  It emits a MAC only on a listener owned by the expected slot and

package/lib/vl-nodes/broker.js

@@ -2,6 +2,7 @@
 
 const crypto = require('node:crypto');
 const { NODE_ID_RE } = require('./store.js');
+const { processOutbox, createRateLimiter } = require('./outbox.js');
 
 const SESSION_RE = /^[a-f0-9]{32}$/;
 const PROTOCOL = 'vl-node/1';
@@ -154,6 +155,12 @@ function createBroker(options = {}) {
   const setTimer = options.setTimeout || setTimeout;
   const clearTimer = options.clearTimeout || clearTimeout;
   const randomBytes = options.randomBytes || crypto.randomBytes;
+  const optionsStorePath = options.storePath;
+  const optionsOwnerId = options.ownerId;
+  const optionsCellSubmit = options.cellSubmit || options.submit;
+  const optionsFleetP = options.fleetStatus || options.fleetP;
+  const optionsReadonly = options.readonly;
+  const rateLimiter = options.rateLimiter || createRateLimiter();
   const states = new Map();
 
   function ensure(node) {
@@ -172,6 +179,7 @@ function createBroker(options = {}) {
         events: [],
         eventsCursor: 0,
         eventsBytes: 0,
+        outboxCursor: null,
       };
       states.set(node.nodeId, state);
     }
@@ -265,15 +273,61 @@ function createBroker(options = {}) {
     return { ok: true, state, acknowledged };
   }
 
-  function poll(node, rawHeartbeat, { waitMs = MAX_WAIT_MS, signal = null } = {}) {
+  async function poll(node, rawHeartbeat, options = {}) {
+    const { waitMs = MAX_WAIT_MS, signal = null } = options;
     const observed = observe(node, rawHeartbeat);
-    if (!observed.ok) return Promise.resolve({ type: 'error', code: observed.code });
+    if (!observed.ok) return { type: 'error', code: observed.code };
     const state = observed.state;
     finishWaiter(state, { type: 'superseded', generation: state.generation });
-    if (observed.acknowledged) {
-      return Promise.resolve({
-        type: 'acknowledged', generation: state.generation, eventsCursor: state.eventsCursor,
+    // Identity of THIS poll. Processing the outbox waits for the
+    // directory della flotta, e nel frattempo un altro poll (seq piu'
+    // recente, sessione nuova, o forget + ri-pair) puo' superarlo. Dopo
+    // l'await l'identita' si ricontrolla: un poll superato non deve
+    // installare un waiter sopra quello piu' recente, e risponde subito.
+    const heartbeatAtEntry = state.heartbeat;
+    const generationAtEntry = state.generation;
+
+    // Ingest outbox if present
+    if (rawHeartbeat && Array.isArray(rawHeartbeat.outbox) && rawHeartbeat.outbox.length > 0) {
+      const outboxResult = await processOutbox({
+        outbox: rawHeartbeat.outbox,
+        node,
+        storePath: options.storePath || optionsStorePath,
+        ownerId: options.ownerId || optionsOwnerId,
+        fleetStatus: options.fleetStatus || options.fleetP || optionsFleetP,
+        submit: options.cellSubmit || options.submit || optionsCellSubmit,
+        now,
+        rateLimiter,
+        readonly: options.readonly || optionsReadonly,
       });
+      if (outboxResult.cursor) {
+        state.outboxCursor = outboxResult.cursor;
+      }
+      // The session, the generation or the sequence changed while
+      // questo poll attendeva la directory (oppure il nodo e' stato
+      // dimenticato): il poll e' superato. Non tocca il waiter corrente —
+      // che appartiene al poll piu' recente — e risponde subito. Un evento
+      // di forget durante l'attesa risponde revoked: il nodo non e' piu'
+      // in questa tabella.
+      if (states.get(state.nodeId) !== state
+        || state.heartbeat !== heartbeatAtEntry
+        || state.generation !== generationAtEntry) {
+        return {
+          type: states.get(state.nodeId) === state ? 'superseded' : 'revoked',
+          generation: state.generation,
+          eventsCursor: state.eventsCursor,
+          outboxCursor: state.outboxCursor,
+        };
+      }
+    }
+
+    if (observed.acknowledged) {
+      return {
+        type: 'acknowledged',
+        generation: state.generation,
+        eventsCursor: state.eventsCursor,
+        outboxCursor: state.outboxCursor,
+      };
     }
     const boundedWait = Math.max(1, Math.min(MAX_WAIT_MS, Number(waitMs) || MAX_WAIT_MS));
     return new Promise((resolve) => {
@@ -297,7 +351,11 @@ function createBroker(options = {}) {
       state.waiter = waiter;
       // Il cursore viaggia su OGNI risposta, anche su un poll scaduto a vuoto:
       // e' cosi' che il device sa quando puo' liberare il proprio buffer.
-    }).then((value) => ({ ...value, eventsCursor: state.eventsCursor }));
+    }).then((value) => ({
+      ...value,
+      eventsCursor: state.eventsCursor,
+      outboxCursor: state.outboxCursor,
+    }));
   }
 
   function dispatch(nodeId, command) {

package/lib/vl-nodes/outbox.js

@@ -0,0 +1,333 @@
+'use strict';
+
+const { deliverCellMessage } = require('../cells/deliver.js');
+const { publicCells } = require('../cells/routes.js');
+const { submitTextOk } = require('../tmux/actions.js');
+const store = require('./store.js');
+
+const MAX_OUTBOX_TEXT = 2048; // 2 KiB
+const RATE_LIMIT_MINUTE_CAP = 6;
+const RATE_LIMIT_HOUR_CAP = 20;
+const RATE_LIMIT_MINUTE_MS = 60_000;
+const RATE_LIMIT_HOUR_MS = 3_600_000;
+const MSG_ID_RE = /^[a-f0-9]{32}$/;
+const TARGET_RE = /^[a-f0-9]{16,64}:[A-Za-z0-9._-]{1,64}$/;
+// Simple cell name (`Dev`): resolves to the LOCAL cell of the hub owner.
+const SIMPLE_TARGET_RE = /^[A-Za-z0-9._-]{1,32}$/;
+
+// In-process registry of ids currently being settled, so a concurrent
+// presentation of the same id joins the first run instead of delivering again.
+const inflightSettles = new Map(); // nodeId -> Map<id, Promise<outcome>>
+
+function inflightGet(nodeId, id) {
+  return inflightSettles.get(nodeId)?.get(id) || null;
+}
+
+function inflightSet(nodeId, id, promise) {
+  if (!inflightSettles.has(nodeId)) inflightSettles.set(nodeId, new Map());
+  inflightSettles.get(nodeId).set(id, promise);
+}
+
+function inflightDelete(nodeId, id) {
+  const map = inflightSettles.get(nodeId);
+  if (!map) return;
+  map.delete(id);
+  if (!map.size) inflightSettles.delete(nodeId);
+}
+
+function hasIllegalControlChars(text) {
+  // Disallow control characters except TAB (\x09), LF (\x0a), CR (\x0d)
+  return /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text);
+}
+
+function sanitizeOutboxItem(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { item: null, error: 'invalid-item' };
+  }
+  // Deny-extra keys: only id, to, text (and from is ignored if present)
+  for (const key of Object.keys(raw)) {
+    if (key !== 'id' && key !== 'to' && key !== 'text' && key !== 'from') {
+      return { item: null, error: 'unknown-field' };
+    }
+  }
+  if (!MSG_ID_RE.test(String(raw.id || ''))) {
+    return { item: null, error: 'invalid-id' };
+  }
+  if (typeof raw.to !== 'string'
+    || !(TARGET_RE.test(raw.to) || SIMPLE_TARGET_RE.test(raw.to))) {
+    return { id: raw.id, item: null, error: 'invalid-target' };
+  }
+  if (typeof raw.text !== 'string') {
+    return { id: raw.id, item: null, error: 'invalid-text' };
+  }
+  if (Buffer.byteLength(raw.text, 'utf8') > MAX_OUTBOX_TEXT) {
+    return { id: raw.id, item: null, error: 'oversized' };
+  }
+  if (hasIllegalControlChars(raw.text)) {
+    return { id: raw.id, item: null, error: 'control-chars' };
+  }
+  // The text of a cell message is validated with the SAME rule of the send
+  // route: what a cell message must satisfy to be delivered at all.
+  if (!submitTextOk(raw.text)) {
+    return { id: raw.id, item: null, error: 'invalid-text' };
+  }
+  return {
+    item: {
+      id: raw.id,
+      to: raw.to,
+      text: raw.text,
+    },
+    error: null,
+  };
+}
+
+function createRateLimiter() {
+  const records = new Map(); // nodeId -> [timestamps]
+
+  function windowCounts(nodeId, now) {
+    const hourCutoff = now - RATE_LIMIT_HOUR_MS;
+    const hour = (records.get(nodeId) || []).filter((ts) => ts > hourCutoff);
+    records.set(nodeId, hour);
+    const minuteCutoff = now - RATE_LIMIT_MINUTE_MS;
+    return {
+      minute: hour.filter((ts) => ts > minuteCutoff).length,
+      hour: hour.length,
+    };
+  }
+
+  // Non-consuming probe: would a message from this node be admitted right now?
+  function check(nodeId, now) {
+    const { minute, hour } = windowCounts(nodeId, now);
+    return minute < RATE_LIMIT_MINUTE_CAP && hour < RATE_LIMIT_HOUR_CAP;
+  }
+
+  function checkAndConsume(nodeId, now) {
+    if (!check(nodeId, now)) return false;
+    records.get(nodeId).push(now);
+    return true;
+  }
+
+  function reset(nodeId) {
+    if (nodeId) records.delete(nodeId);
+    else records.clear();
+  }
+
+  return { check, checkAndConsume, reset };
+}
+
+async function resolveFleet(fleetSource) {
+  if (!fleetSource) return null;
+  let fleet = fleetSource;
+  if (typeof fleet === 'function') fleet = fleet();
+  if (fleet && typeof fleet.then === 'function') fleet = await fleet;
+  if (!fleet) return null;
+  if (typeof fleet.cellStatus === 'function') return await fleet.cellStatus();
+  if (typeof fleet.status === 'function') return await fleet.status();
+  return fleet;
+}
+
+// Resolve and deliver a single outbox item. Returns the FINAL outcome string
+// (`submitted` or `rejected:<reason>`). Authorization is re-evaluated
+// immediately before the submit: an ACL revoked while the fleet
+// directory was resolving ends in `rejected:acl-revoked` with no delivery.
+// The read-only gate is read the same way: a server that became read-only
+// while the directory was resolving ends in `rejected:readonly`.
+async function settleItem({ raw, node, storePath, localOwner, fleetStatus, submit, rateLimiter, currentTime, readonly }) {
+  // The gate of the send route, read from its source every time it matters:
+  // a read-only server delivers nothing. The outcome is `rejected:readonly`,
+  // exactly like the other refusals of the outbox.
+  const readOnly = () => typeof readonly === 'function' && readonly();
+  // At the entry, before every other check.
+  if (readOnly()) {
+    return 'rejected:readonly';
+  }
+  const { item, error } = sanitizeOutboxItem(raw);
+  if (error || !item) {
+    return `rejected:${error || 'invalid-message'}`;
+  }
+
+  // A simple cell name addresses the LOCAL cell of the hub owner.
+  let toOwner;
+  let toCell;
+  if (item.to.includes(':')) {
+    [toOwner, toCell] = item.to.split(':');
+  } else {
+    toOwner = localOwner;
+    toCell = item.to;
+  }
+
+  // 1. Federation: only local targets allowed (closed by default)
+  if (!localOwner || toOwner !== localOwner) {
+    return 'rejected:remote-unsupported';
+  }
+
+  const aclAllows = (cell) => {
+    const acl = store.getNodeAcl(storePath, node.nodeId, currentTime);
+    return Boolean(acl && Array.isArray(acl.allowCells) && acl.allowCells.includes(cell));
+  };
+
+  // 2. ACL pre-check (default deny) — fail fast before any async work
+  if (!aclAllows(toCell)) {
+    return 'rejected:acl-denied';
+  }
+
+  // 3. Rate limit pre-check (non-consuming probe)
+  if (rateLimiter && !rateLimiter.check(node.nodeId, currentTime)) {
+    return 'rejected:rate-limited';
+  }
+
+  // 4. Resolve target in local directory (async: the revocation window)
+  const resolvedFleet = await resolveFleet(fleetStatus);
+  // The gate is read again after the wait: a server that became read-only
+  // while the directory was resolving admits nothing, and the rate limit
+  // is not consumed for a delivery that will not happen.
+  if (readOnly()) {
+    return 'rejected:readonly';
+  }
+  const cells = publicCells(resolvedFleet, localOwner, currentTime);
+  const target = cells.find((c) => c.cell === toCell);
+  if (!target) {
+    return 'rejected:unknown-target';
+  }
+  if (!target.canReceive) {
+    return 'rejected:target-not-active';
+  }
+
+  // 5. Authorization re-evaluated immediately before the submit.
+  if (!aclAllows(toCell)) {
+    return 'rejected:acl-revoked';
+  }
+  // The last gate before the delivery: nothing is delivered by a server that
+  // is read-only at this point.
+  if (readOnly()) {
+    return 'rejected:readonly';
+  }
+  // The authoritative rate-limit consumption happens here, at delivery time.
+  if (rateLimiter && !rateLimiter.checkAndConsume(node.nodeId, currentTime)) {
+    return 'rejected:rate-limited';
+  }
+
+  // 6. Deliver through submit seam
+  const fromLabel = `VL-${node.nodeId.slice(0, 8)}@${localOwner.slice(0, 8)}`;
+  try {
+    if (typeof submit !== 'function') {
+      throw new Error('cell submit function unavailable');
+    }
+    const delivery = await deliverCellMessage(submit, target, {
+      id: item.id,
+      label: fromLabel,
+      text: item.text,
+    });
+    if (delivery && delivery.submitted === true) {
+      return 'submitted';
+    }
+    return `rejected:${delivery?.reason || 'delivery-failed'}`;
+  } catch (e) {
+    return `rejected:${String(e.message || e).slice(0, 48)}`;
+  }
+}
+
+async function processOutbox({
+  outbox,
+  node,
+  storePath,
+  ownerId,
+  fleetStatus,
+  submit,
+  now = Date.now,
+  rateLimiter,
+  readonly,
+}) {
+  if (!Array.isArray(outbox) || outbox.length === 0) {
+    return { outcomes: [], cursor: null };
+  }
+
+  const currentTime = typeof now === 'function' ? now() : now;
+  const localOwner = typeof ownerId === 'function' ? ownerId() : ownerId;
+  const outcomes = [];
+  let lastCursor = null;
+
+  // Process up to 1 message per poll (queue of 1 on wire)
+  for (const raw of outbox.slice(0, 1)) {
+    const rawId = raw && typeof raw === 'object' && typeof raw.id === 'string' ? raw.id : null;
+    const trackableId = rawId && MSG_ID_RE.test(rawId) ? rawId : null;
+    const msgId = trackableId || rawId;
+    const emit = (outcome) => {
+      outcomes.push({ id: msgId, outcome });
+      if (msgId) lastCursor = `${msgId}:${outcome}`;
+    };
+
+    let run = null;
+    if (trackableId) {
+      // An id currently being settled joins the first run instead of
+      // triggering a second delivery.
+      run = inflightGet(node.nodeId, trackableId);
+      if (!run && storePath) {
+        // An id already settled returns its previous outcome, without
+        // delivering again (TTL and caps are enforced by the store).
+        const seen = store.getSeenOutcome(storePath, node.nodeId, trackableId, currentTime);
+        if (seen !== null) {
+          emit(seen);
+          continue;
+        }
+      }
+      if (!run) {
+        const settle = settleItem({
+          raw,
+          node,
+          storePath,
+          localOwner,
+          fleetStatus,
+          submit,
+          rateLimiter,
+          currentTime,
+          readonly,
+        }).then((outcome) => {
+          if (storePath) {
+            try {
+              store.recordSeenOutcome(storePath, node.nodeId, { id: trackableId, outcome, at: currentTime }, currentTime);
+            } catch (_) { /* store issues must not corrupt the outcome */ }
+          }
+          return outcome;
+        });
+        inflightSet(node.nodeId, trackableId, settle);
+        run = settle;
+      }
+    }
+
+    if (run) {
+      let outcome;
+      try {
+        outcome = await run;
+      } finally {
+        if (trackableId) inflightDelete(node.nodeId, trackableId);
+      }
+      emit(outcome);
+      continue;
+    }
+
+    // No trackable id (invalid or missing): settle without dedup bookkeeping.
+    emit(await settleItem({
+      raw,
+      node,
+      storePath,
+      localOwner,
+      fleetStatus,
+      submit,
+      rateLimiter,
+      currentTime,
+      readonly,
+    }));
+  }
+
+  return { outcomes, cursor: lastCursor };
+}
+
+module.exports = {
+  MAX_OUTBOX_TEXT,
+  RATE_LIMIT_MINUTE_CAP,
+  RATE_LIMIT_HOUR_CAP,
+  sanitizeOutboxItem,
+  createRateLimiter,
+  processOutbox,
+};

package/lib/vl-nodes/routes.js

@@ -72,9 +72,9 @@ function jsonBodyError(error, _req, res, _next) {
   return res.status(400).json({ error: String(error?.message || error) });
 }
 
-function publicRoutes({ storePath, broker, ownerId }) {
+function publicRoutes({ storePath, broker, ownerId, cellSubmit, fleetP, readonly = () => false }) {
   const r = express.Router();
-  const body = express.json({ limit: '20kb' });
+  const body = express.json({ limit: '24kb' });
 
   r.post('/pair', body, (req, res) => {
     const localOwner = ownerId();
@@ -110,6 +110,11 @@ function publicRoutes({ storePath, broker, ownerId }) {
     const result = await broker.poll(node, req.body, {
       waitMs: Number(req.get('x-vl-wait-ms')) || MAX_WAIT_MS,
       signal: abort.signal,
+      storePath,
+      ownerId,
+      cellSubmit,
+      fleetP,
+      readonly,
     });
     if (res.headersSent || res.destroyed) return undefined;
     // Il cursore degli eventi viaggia in un HEADER, non nel corpo: la risposta
@@ -119,6 +124,9 @@ function publicRoutes({ storePath, broker, ownerId }) {
     if (Number.isSafeInteger(result.eventsCursor)) {
       res.set('x-vl-events-cursor', String(result.eventsCursor));
     }
+    if (result.outboxCursor) {
+      res.set('x-vl-outbox-cursor', String(result.outboxCursor));
+    }
     if (result.type === 'command') return res.json({ protocol: PROTOCOL, command: result.command });
     if (result.type === 'idle' || result.type === 'aborted' || result.type === 'acknowledged') {
       return res.status(204).end();
@@ -211,6 +219,31 @@ function apiRoutes({ storePath, broker, ownerId, readonly = () => false }) {
     });
   });
 
+  r.get('/:nodeId/acl', (req, res) => {
+    if (!store.NODE_ID_RE.test(String(req.params.nodeId || ''))
+      || !store.listNodes(storePath).some((node) => node.nodeId === req.params.nodeId)) {
+      return res.status(404).json({ error: 'node not paired' });
+    }
+    const acl = store.getNodeAcl(storePath, req.params.nodeId);
+    return res.json({ protocol: PROTOCOL, nodeId: req.params.nodeId, acl });
+  });
+
+  r.put('/:nodeId/acl', express.json({ limit: '8kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: acl blocked' });
+    if (!store.NODE_ID_RE.test(String(req.params.nodeId || ''))
+      || !store.listNodes(storePath).some((node) => node.nodeId === req.params.nodeId)) {
+      return res.status(404).json({ error: 'node not paired' });
+    }
+    const body = req.body;
+    if (!body || typeof body !== 'object' || !Array.isArray(body.allowCells)) {
+      return res.status(400).json({ error: 'invalid ACL payload: allowCells array required' });
+    }
+    const ok = store.setNodeAcl(storePath, req.params.nodeId, { allowCells: body.allowCells });
+    if (!ok) return res.status(400).json({ error: 'failed to set ACL' });
+    const acl = store.getNodeAcl(storePath, req.params.nodeId);
+    return res.json({ protocol: PROTOCOL, nodeId: req.params.nodeId, acl });
+  });
+
   r.delete('/:nodeId', (req, res) => {
     if (readonly()) return res.status(403).json({ error: 'READONLY: revoke blocked' });
     if (!store.removeNode(storePath, req.params.nodeId)) return res.status(404).json({ error: 'node not paired' });

package/lib/vl-nodes/store.js

@@ -11,8 +11,17 @@ const DEFAULT_INVITE_TTL_MS = 10 * 60 * 1000;
 const MAX_INVITE_TTL_MS = 60 * 60 * 1000;
 const MAX_STORE_BYTES = 256 * 1024;
 
+// Outbox outcome dedup: the broker remembers, per node, the ids it has
+// already settled (submitted or rejected) so a re-presented id gets the same
+// outcome back without a second delivery. Bounded: TTL + per-node cap + a
+// global cap that keeps the store file well under MAX_STORE_BYTES.
+const OUTBOX_SEEN_TTL_MS = 24 * 60 * 60 * 1000;
+const OUTBOX_SEEN_MAX_PER_NODE = 256;
+const OUTBOX_SEEN_MAX_TOTAL = 1024;
+const SEEN_OUTCOME_MAX = 64;
+
 function emptyStore() {
-  return { version: STORE_VERSION, invites: [], nodes: [] };
+  return { version: STORE_VERSION, invites: [], nodes: [], acl: {}, outboxSeen: {} };
 }
 
 function defaultPath(home) {
@@ -51,7 +60,63 @@ function normalizeStore(raw, now = Date.now()) {
       pairedAt: record.pairedAt,
     });
   }
-  return { version: STORE_VERSION, invites, nodes };
+  const acl = {};
+  if (raw.acl && typeof raw.acl === 'object' && !Array.isArray(raw.acl)) {
+    for (const [nodeId, nodeAcl] of Object.entries(raw.acl)) {
+      if (!seen.has(nodeId)) continue;
+      if (!nodeAcl || typeof nodeAcl !== 'object' || !Array.isArray(nodeAcl.allowCells)) continue;
+      const allowCells = nodeAcl.allowCells
+        .filter((c) => typeof c === 'string' && c.trim().length > 0 && c.trim().length <= 48)
+        .map((c) => c.trim());
+      acl[nodeId] = { allowCells };
+    }
+  }
+  const outboxSeen = normalizeSeen(raw.outboxSeen, seen, now);
+  return { version: STORE_VERSION, invites, nodes, acl, outboxSeen };
+}
+
+function normalizeSeen(rawSeen, knownNodeIds, now) {
+  const cutoff = now - OUTBOX_SEEN_TTL_MS;
+  const seen = {};
+  let total = 0;
+  if (!rawSeen || typeof rawSeen !== 'object' || Array.isArray(rawSeen)) return seen;
+  for (const [nodeId, list] of Object.entries(rawSeen)) {
+    if (!knownNodeIds.has(nodeId) || !Array.isArray(list)) continue;
+    const byId = new Map();
+    for (const entry of list) {
+      if (!entry || typeof entry !== 'object') continue;
+      if (!NODE_ID_RE.test(String(entry.id || ''))) continue;
+      if (typeof entry.outcome !== 'string' || !entry.outcome
+        || entry.outcome.length > SEEN_OUTCOME_MAX) continue;
+      if (!Number.isSafeInteger(entry.at) || entry.at <= cutoff) continue;
+      byId.set(entry.id, { id: entry.id, outcome: entry.outcome, at: entry.at });
+    }
+    const newestFirst = [...byId.values()].sort((x, y) => y.at - x.at || (x.id < y.id ? 1 : -1));
+    const capped = newestFirst.slice(0, OUTBOX_SEEN_MAX_PER_NODE);
+    if (capped.length) {
+      seen[nodeId] = capped;
+      total += capped.length;
+    }
+  }
+  // Global cap: drop the oldest entries across nodes until within budget.
+  while (total > OUTBOX_SEEN_MAX_TOTAL) {
+    let oldestNode = null;
+    let oldest = null;
+    for (const [nodeId, list] of Object.entries(seen)) {
+      for (const entry of list) {
+        if (!oldest || entry.at < oldest.at || (entry.at === oldest.at && entry.id < oldest.id)) {
+          oldest = entry;
+          oldestNode = nodeId;
+        }
+      }
+    }
+    if (!oldestNode) break;
+    const list = seen[oldestNode];
+    list.splice(list.indexOf(oldest), 1);
+    if (!list.length) delete seen[oldestNode];
+    total -= 1;
+  }
+  return seen;
 }
 
 function ownedByCurrentUser(stat) {
@@ -173,6 +238,59 @@ function removeNode(file, nodeId, now = Date.now()) {
   const kept = store.nodes.filter((node) => node.nodeId !== nodeId);
   if (kept.length === store.nodes.length) return false;
   store.nodes = kept;
+  if (store.acl && store.acl[nodeId]) {
+    delete store.acl[nodeId];
+  }
+  if (store.outboxSeen && store.outboxSeen[nodeId]) {
+    delete store.outboxSeen[nodeId];
+  }
+  atomicWriteStore(file, store, now);
+  return true;
+}
+
+function getSeenOutcome(file, nodeId, id, now = Date.now()) {
+  if (!NODE_ID_RE.test(String(nodeId || '')) || !NODE_ID_RE.test(String(id || ''))) return null;
+  const store = loadStore(file, now);
+  const list = store.outboxSeen && store.outboxSeen[nodeId];
+  if (!Array.isArray(list)) return null;
+  const entry = list.find((row) => row.id === id);
+  return entry ? entry.outcome : null;
+}
+
+function recordSeenOutcome(file, nodeId, { id, outcome, at }, now = Date.now()) {
+  if (!NODE_ID_RE.test(String(nodeId || '')) || !NODE_ID_RE.test(String(id || ''))) return false;
+  if (typeof outcome !== 'string' || !outcome || outcome.length > SEEN_OUTCOME_MAX) return false;
+  const stamp = Number.isSafeInteger(at) && at > 0 ? at : now;
+  const store = loadStore(file, now);
+  if (!store.nodes.some((node) => node.nodeId === nodeId)) return false;
+  store.outboxSeen = store.outboxSeen || {};
+  const list = Array.isArray(store.outboxSeen[nodeId])
+    ? store.outboxSeen[nodeId].filter((row) => row.id !== id)
+    : [];
+  list.push({ id, outcome, at: stamp });
+  store.outboxSeen[nodeId] = list;
+  // normalizeStore inside the writer enforces TTL + per-node + total caps.
+  atomicWriteStore(file, store, now);
+  return true;
+}
+
+function getNodeAcl(file, nodeId, now = Date.now()) {
+  if (!NODE_ID_RE.test(String(nodeId || ''))) return null;
+  const store = loadStore(file, now);
+  if (!store.nodes.some((node) => node.nodeId === nodeId)) return null;
+  return store.acl && store.acl[nodeId] ? store.acl[nodeId] : { allowCells: [] };
+}
+
+function setNodeAcl(file, nodeId, { allowCells }, now = Date.now()) {
+  if (!NODE_ID_RE.test(String(nodeId || ''))) return false;
+  if (!Array.isArray(allowCells)) return false;
+  const store = loadStore(file, now);
+  if (!store.nodes.some((node) => node.nodeId === nodeId)) return false;
+  const cleanedCells = allowCells
+    .filter((c) => typeof c === 'string' && c.trim().length > 0 && c.trim().length <= 48)
+    .map((c) => c.trim());
+  store.acl = store.acl || {};
+  store.acl[nodeId] = { allowCells: cleanedCells };
   atomicWriteStore(file, store, now);
   return true;
 }
@@ -187,6 +305,9 @@ module.exports = {
   STORE_VERSION,
   DEFAULT_INVITE_TTL_MS,
   MAX_INVITE_TTL_MS,
+  OUTBOX_SEEN_TTL_MS,
+  OUTBOX_SEEN_MAX_PER_NODE,
+  OUTBOX_SEEN_MAX_TOTAL,
   emptyStore,
   defaultPath,
   cleanLabel,
@@ -199,5 +320,9 @@ module.exports = {
   pairNode,
   authenticate,
   removeNode,
+  getNodeAcl,
+  setNodeAcl,
+  getSeenOutcome,
+  recordSeenOutcome,
   listNodes,
 };