@mmmbuto/nexuscrew 0.9.28 → 0.9.30

package/lib/nodes/store.js

@@ -1,8 +1,8 @@
 'use strict';
-// lib/nodes/store.js — nodes.json secret store (design §4, §4b(4)).
+// lib/nodes/store.js — nodes.json secret store.
 //
 // nodes.json e' un SECRET STORE, non config qualunque: contiene i token dei nodi
-// remoti (iniettati dal proxy in B1). Percio' riusa lo stesso hardening di
+// Remoti (iniettati dal proxy in). Percio' riusa lo stesso hardening di
 // lib/fleet/definitions.js e del token file:
 //   - permessi 0600, scrittura atomica (tmp stessa dir + rename), rifiuto symlink
 //   - schema STRICT validato al load: garbage -> errore esplicito, MAI guess
@@ -19,6 +19,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const reversePool = require('./reverse-pool.js');
 const identity = require('./identity.js');
+const accessPresets = require('./access-presets.js');
 
 const SCHEMA_VERSION = 3;
 const PREVIOUS_SCHEMA_VERSION = 2;
@@ -28,14 +29,14 @@ const MAX_TOKEN_LEN = 4096;
 const MAX_KEYPATH_LEN = 4096;
 const MAX_SSH_LEN = 320;          // user(<=32) + '@' + host(<=255)
 
-// name: chiave strict usata anche come segmento path/route in B1 -> niente '.',
-// '/', maiuscole. Allineato al contratto §4b(2) (^[a-z0-9-]{1,32}$).
+// name: strict key also used as a path/route segment -> no '.', no '/',
+// no uppercase. Aligned with the strict name contract (^[a-z0-9-]{1,32}$).
 const NODE_NAME_RE = /^[a-z0-9-]{1,32}$/;
 // nodeId: id stabile per-installazione, hex casuale (crypto.randomBytes(16)).
 const NODE_ID_RE = /^[a-f0-9]{16,64}$/;
 // user@host: entrambe le parti argv-safe (no spazi, no leading '-' -> mai
 // interpretabile come opzione ssh). Host: hostname/FQDN/IPv4 (niente ':' -> IPv6
-// va usato via Host alias in ~/.ssh/config, fuori scope B0).
+// Va usato via Host alias in ~/.ssh/config, fuori scope).
 const SSH_USER_RE = /^[A-Za-z0-9._-]{1,32}$/;
 const SSH_HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/;
 
@@ -112,6 +113,10 @@ const NODE_KEYS = new Set([
   // Quali CELLE di questo nodo il peer puo' vedere. Distinto da `visibility`,
   // che governa il TRANSITO (attraverso chi passa il traffico) e non l'accesso.
   'cellVisibility', 'cells',
+  // eventsReceive: the CLIENT's own local choice to import an owner's feed.
+  // It is NOT a grant the owner sets, it never travels in a preset, and it
+  // only ever decides what THIS node pulls — never what a peer may read here.
+  'eventsReceive',
   // Se questo peer puo' aprire i PANNELLI delle celle di questo nodo. Distinto
   // da `cellVisibility`, che dice quali celle il peer VEDE: dietro un pannello
   // c'e' un browser con sessioni gia' autenticate, e un accesso di quel tipo non
@@ -132,13 +137,25 @@ const NODE_KEYS = new Set([
   // grant potra' pretendere la prima. `keyConflict` conserva una chiave DIVERSA
   // vista dopo il legame, senza sostituire quella legata.
   'publicKey', 'keySource', 'keyBoundAt', 'keyConflict',
-  // P0 stessa-origin, meta' remota: la porta pannello del peer inoltrata sul
+  // Stessa-origin, meta' remota: la porta pannello del peer inoltrata sul
   // NOSTRO loopback (panelLocalPort) e la sua origine remota (panelRemotePort).
   // COPPIA obbligatoria: un -L ha due estremita', mezza coppia e' un forward
   // impossibile, non "meno pannello". Campi assenti = peer accoppiato prima di
   // questa negoziazione: via storica, nessun comportamento nuovo. Le porte non
   // sono segreti (come localPort/remotePort, che stanno qui accanto).
   'panelLocalPort', 'panelRemotePort',
+  // Federated access grants: what this peer may do with the resources this node
+  // OWNS (events, asks, files) beyond cell visibility. Same shape and same rule
+  // as panelAccess/liveHostAccess: default denied, one node at a time. A peer
+  // does not gain them by being paired, and the receiving client's own choice
+  // to receive events is NOT one of them (it is local to that client).
+  'eventsAccess', 'nodeEventsAccess', 'askReplyAccess', 'filesReadAccess', 'peerOperatorAccess',
+  // Whether the grant vector was set EXPLICITLY. Grants alone cannot tell a
+  // legacy record (all defaults denied) from a deliberate vector that happens
+  // to deny everything: without this marker a legacy peer would read as a
+  // coherent "custom" preset instead of "not configured". It is provenance,
+  // not a permission — it grants nothing and handlers never read it as a role.
+  'accessConfigured',
 ]);
 
 // Nome di cella: stessa forma usata da fleet/definitions.js, cells/routes.js e
@@ -248,6 +265,7 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   const roles = parseRoles(n.roles);
   if (!roles) return null;
   if (n.rolesKnown !== undefined && typeof n.rolesKnown !== 'boolean') return null;
+  if (n.eventsReceive !== undefined && typeof n.eventsReceive !== 'boolean') return null;
   // Before 0.8.9 `roles` was filled with a local default and did not describe
   // the remote peer. Only the explicit marker makes role-based health safe.
   const rolesKnown = n.rolesKnown === true;
@@ -285,6 +303,16 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     // Stessa regola, stesso motivo: un record senza il campo non acquisisce la
     // designazione live per anzianita' del pairing.
     liveHostAccess: n.liveHostAccess === undefined ? false : n.liveHostAccess,
+    // Le cinque concessioni federate seguono la stessa regola: assenti valgono
+    // NEGATE. Nessuna migrazione silenziosa al load: il vettore va impostato da
+    // un atto esplicito (preset o edit granulare), altrimenti resta negato.
+    eventsReceive: n.eventsReceive === undefined ? false : n.eventsReceive === true,
+    eventsAccess: n.eventsAccess === undefined ? false : n.eventsAccess,
+    nodeEventsAccess: n.nodeEventsAccess === undefined ? false : n.nodeEventsAccess,
+    askReplyAccess: n.askReplyAccess === undefined ? false : n.askReplyAccess,
+    filesReadAccess: n.filesReadAccess === undefined ? false : n.filesReadAccess,
+    peerOperatorAccess: n.peerOperatorAccess === undefined ? false : n.peerOperatorAccess,
+    accessConfigured: n.accessConfigured === true,
     visibility: n.visibility || 'network',
   };
   if (!['auto', 'ssh', 'autossh', 'inbound'].includes(out.transport)) return null;
@@ -294,6 +322,12 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
   if (typeof out.shared !== 'boolean') return null;
   if (typeof out.panelAccess !== 'boolean') return null;
   if (typeof out.liveHostAccess !== 'boolean') return null;
+  if (typeof out.eventsAccess !== 'boolean') return null;
+  if (typeof out.nodeEventsAccess !== 'boolean') return null;
+  if (typeof out.askReplyAccess !== 'boolean') return null;
+  if (typeof out.filesReadAccess !== 'boolean') return null;
+  if (typeof out.peerOperatorAccess !== 'boolean') return null;
+  if (typeof out.accessConfigured !== 'boolean') return null;
   if (!['network', 'relay-only', 'selected'].includes(out.visibility)) return null;
   if (identityFile) out.identityFile = identityFile;
   // Keep the old public field while reading v1 so old callers/tests and a
@@ -303,7 +337,7 @@ function parseNode(n, schemaVersion = SCHEMA_VERSION) {
     if (!isPort(n.reversePort)) return null;
     out.reversePort = n.reversePort;
   }
-  // Coppia pannello (P0 stessa-origin remota): o entrambe le porte o nessuna.
+  // Coppia pannello (stessa-origin remota): o entrambe le porte o nessuna.
   // Una sola meta' non viene indovinata — sarebbe un -L monco. E la porta
   // locale del pannello non puo' stare su quella del control plane: ssh
   // cadrebbe con ExitOnForwardFailure portandosi via il tunnel intero.
@@ -427,7 +461,7 @@ function parseStore(raw) {
 
     if (![SCHEMA_VERSION, PREVIOUS_SCHEMA_VERSION, LEGACY_SCHEMA_VERSION].includes(d.schemaVersion)) return null;
     const rootKeys = d.schemaVersion === SCHEMA_VERSION
-      ? new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous', 'reversePoolAnchor', 'reversePoolLedgerInitialized'])
+      ? new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous', 'reversePoolAnchor', 'reversePoolLedgerInitialized', 'accessRevision'])
       : new Set(['schemaVersion', 'nodeId', 'nodes', 'rendezvous']);
     if (Object.keys(d).some((key) => !rootKeys.has(key))) return null;
     if (typeof d.nodeId !== 'string' || !NODE_ID_RE.test(d.nodeId)) return null;
@@ -461,6 +495,16 @@ function parseStore(raw) {
 
     const out = { schemaVersion: d.schemaVersion, nodeId: d.nodeId, nodes };
 
+    // Revision of the peer access policy. Absent means 0: a store written
+    // before this field existed is at revision 0 and the first explicit write
+    // advances it to 1. It is kept out of the parsed object when absent so a
+    // plain load never rewrites the file with a field nobody set.
+    if (d.accessRevision !== undefined) {
+      if (d.schemaVersion !== SCHEMA_VERSION) return null;
+      if (!Number.isInteger(d.accessRevision) || d.accessRevision < 0) return null;
+      out.accessRevision = d.accessRevision;
+    }
+
     if (d.rendezvous !== undefined && d.rendezvous !== null) {
       const rdv = parseRendezvous(d.rendezvous);
       if (!rdv) return null;
@@ -647,6 +691,101 @@ function updateNode(store, name, patch) {
   return { ...store, schemaVersion: mutationSchemaVersion(store), nodes };
 }
 
+// --- Concessioni federate: preset, CAS, inventario -------------------------
+
+function accessRevisionOf(store) {
+  return store && Number.isInteger(store.accessRevision) && store.accessRevision >= 0
+    ? store.accessRevision : 0;
+}
+
+// Pure: returns a new store with the peer's grant vector replaced by a
+// validated one. The vector is validated as a whole, so an edit that keeps
+// live hosting while dropping another admin grant is refused here too.
+function setPeerAccessGrants(store, name, grants) {
+  const idx = store.nodes.findIndex((n) => n.name === name);
+  if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
+  const check = accessPresets.validateGrants(grants);
+  if (!check.ok) throw new Error(`concessioni non valide: ${check.errors.join('; ')}`);
+  const next = { ...store.nodes[idx] };
+  next.cellVisibility = grants.cellVisibility;
+  if (grants.cellVisibility === 'selected') next.cells = [...(grants.cells || [])];
+  else delete next.cells;
+  for (const key of accessPresets.BOOLEAN_GRANTS) next[key] = grants[key] === true;
+  next.accessConfigured = true;
+  const nodes = store.nodes.slice();
+  nodes[idx] = next;
+  const out = { ...store, schemaVersion: SCHEMA_VERSION, nodes };
+  out.accessRevision = accessRevisionOf(store) + 1;
+  return out;
+}
+
+// Pure: applies a named preset to one peer.
+function setPeerAccessPreset(store, name, presetName) {
+  const idx = store.nodes.findIndex((n) => n.name === name);
+  if (idx < 0) throw new Error(`nodo sconosciuto: "${name}"`);
+  const applied = accessPresets.applyPreset(store.nodes[idx], presetName);
+  const vector = { cellVisibility: applied.cellVisibility };
+  if (applied.cells !== undefined) vector.cells = applied.cells;
+  for (const key of accessPresets.BOOLEAN_GRANTS) vector[key] = applied[key];
+  return setPeerAccessGrants(store, name, vector);
+}
+
+// Read-only inventory: what every peer is allowed to do on THIS node, with the
+// label derived from the grants. Used by `nodes show`, by the settings view and
+// by the explicit migration: a legacy peer shows up as not configured, never as
+// a preset inferred from defaults.
+function accessInventory(store) {
+  const peers = (store && store.nodes ? store.nodes : []).map((peer) => {
+    const view = accessPresets.grantsOf(peer);
+    return {
+      name: peer.name,
+      nodeId: peer.nodeId || null,
+      direction: peer.direction,
+      configured: view.configured,
+      label: view.label,
+      grants: view.grants,
+    };
+  });
+  return { revision: accessRevisionOf(store), peers };
+}
+
+// Compare-and-set write for the peer access policy: one validated read-modify-
+// write over the store file. `expectedRevision` must be an integer that matches
+// the current revision, otherwise the write is refused and the caller rereads
+// and retries — never a permissive default. The whole path is synchronous, so
+// two callers in this process cannot interleave between the read and the write.
+function setPeerAccessGrantsCas({ filePath, name, grants, expectedRevision, extraPatch }) {
+  const current = loadStoreStrict(filePath);
+  if (!Number.isInteger(expectedRevision) || accessRevisionOf(current) !== expectedRevision) {
+    return { ok: false, conflict: true, revision: accessRevisionOf(current) };
+  }
+  let next = current;
+  if (extraPatch && Object.keys(extraPatch).length > 0) next = updateNode(next, name, extraPatch);
+  next = setPeerAccessGrants(next, name, grants);
+  const written = atomicWriteStore(filePath, next);
+  return {
+    ok: true,
+    name,
+    revision: accessRevisionOf(written),
+    grants: accessPresets.grantsOf(written.nodes.find((n) => n.name === name)).grants,
+    label: accessPresets.grantsOf(written.nodes.find((n) => n.name === name)).label,
+  };
+}
+
+// Same, by preset name.
+function setPeerAccessPresetCas({ filePath, name, presetName, expectedRevision, extraPatch }) {
+  const current = loadStoreStrict(filePath);
+  if (!Number.isInteger(expectedRevision) || accessRevisionOf(current) !== expectedRevision) {
+    return { ok: false, conflict: true, revision: accessRevisionOf(current) };
+  }
+  let next = current;
+  if (extraPatch && Object.keys(extraPatch).length > 0) next = updateNode(next, name, extraPatch);
+  next = setPeerAccessPreset(next, name, presetName);
+  const written = atomicWriteStore(filePath, next);
+  const view = accessPresets.grantsOf(written.nodes.find((n) => n.name === name));
+  return { ok: true, name, revision: accessRevisionOf(written), grants: view.grants, label: view.label };
+}
+
 // The upgrade is explicit: normal legacy pairing remains schema v2 and keeps
 // working with a previous NexusCrew binary.  Enabling rotation is the only
 // path that writes the v3 anchor and therefore requires both peers to support
@@ -691,6 +830,7 @@ function redactNode(n) {
     rolesKnown: n.rolesKnown === true,
     transport: n.transport || 'ssh',
     autostart: !!n.autostart,
+    eventsReceive: n.eventsReceive === true,
     shared: n.shared === true,
     panelAccess: n.panelAccess === true,
     liveHostAccess: n.liveHostAccess === true,
@@ -758,7 +898,7 @@ function hasPairedPeers(store) {
 }
 
 // --- Migrazione esplicita da config.json (guarded, no-op se assente) ---------
-// Se config.json contiene un array `nodes` legacy (vecchio formato pre-B0),
+// Se config.json contiene un array `nodes` legacy (vecchio formato pre-),
 // lo importa in nodes.json. Guarded: no-op se config.json non ha `nodes`, o se
 // nodes.json ha gia' dei nodi (mai overwrite). Strict: un nodo legacy malformato
 // -> throw esplicito (non importa silenziosamente spazzatura).
@@ -885,6 +1025,9 @@ module.exports = {
   defaultNodesPath, loadStore, loadStoreStrict, initStore, atomicWriteStore, loadOrInitStore, emptyStore, newNodeId,
   // mutazioni
   getNode, addNode, removeNode, setNodeToken, updateNode, upgradeToReversePoolSchema, setNodeReversePool,
+  // concessioni federate (preset, CAS, inventario)
+  accessRevisionOf, setPeerAccessGrants, setPeerAccessPreset, accessInventory,
+  setPeerAccessGrantsCas, setPeerAccessPresetCas,
   // redazione
   redactNode, redactStore, hasPairedPeers,
   // migrazione

package/lib/nodes/tunnel.js

@@ -1,5 +1,5 @@
 'use strict';
-// lib/nodes/tunnel.js — SSH tunnel manager (design §4b(1), §7).
+// lib/nodes/tunnel.js — SSH tunnel manager.
 //
 // I processi ssh sono gestiti da un solo supervisor detached, avviato dal
 // lifecycle del servizio o dalle azioni PWA autenticate. argv puro (spawn con
@@ -10,7 +10,7 @@
 //     unit-testabili senza lanciare ssh.
 //   - lifecycle per-tunnel via pidfile (start/stop/restart/state): il processo
 //     ssh e' detached, la sua liveness/porta stabile e' interrogabile da
-//     `status --json` e (in B1) dal proxy. Porta STABILE da nodes.json; una
+// `status --json` e (in) dal proxy. Porta STABILE da nodes.json; una
 //     collisione fa fallire ExitOnForwardFailure -> si segnala, NON si riciclano
 //     porte a caso.
 const fs = require('node:fs');
@@ -21,7 +21,7 @@ const { spawn, spawnSync } = require('node:child_process');
 const pidf = require('../cli/pidfile.js');
 const store = require('./store.js');
 
-// Opzioni SSH comuni ai due template (ordine e valori ESATTI dal design §4b(1)).
+// SSH options shared by both templates (exact order and values).
 const SSH_BASE_OPTS = Object.freeze([
   '-N',
   '-o', 'ExitOnForwardFailure=yes',
@@ -44,7 +44,7 @@ function assertForwardSpec(node) {
   if (node.keyPath !== undefined && !store.isAbsPath(node.keyPath)) throw new Error('tunnel: keyPath non valido');
   if (node.reversePort !== undefined && !store.isPort(node.reversePort)) throw new Error('tunnel: reversePort non valida');
   if (node.localAppPort !== undefined && !store.isPort(node.localAppPort)) throw new Error('tunnel: localAppPort non valida');
-  // Coppia pannello (P0 stessa-origin remota): o entrambe o nessuna, e mai
+  // Coppia pannello (stessa-origin remota): o entrambe o nessuna, e mai
   // sulla porta locale del control plane — il bind conflitto abbatterebbe il
   // tunnel intero con ExitOnForwardFailure.
   if (node.panelLocalPort !== undefined || node.panelRemotePort !== undefined) {
@@ -61,7 +61,7 @@ function assertForwardSpec(node) {
   if (!store.parseSshTarget(node.ssh)) throw new Error('tunnel: target ssh non valido');
 }
 
-// Forward client->nodo (ruolo client). §4b(1):
+// Forward client->node (client role):
 //   ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30
 //       -o ServerAliveCountMax=3 -o BatchMode=yes -i <key>
 //       -L 127.0.0.1:<locale>:127.0.0.1:<remota> user@host
@@ -108,7 +108,7 @@ function buildReverseArgs(node, { remotePort, targetPort } = {}) {
   ]);
 }
 
-// Backoff esponenziale + jitter (design §7). Deterministico con rng iniettato.
+// Exponential backoff + jitter. Deterministic with an injected rng.
 //   delay = clamp(base * factor^attempt, 0..cap) * (1 +- jitter*(2*rand-1))
 // rng()=0.5 -> jitter nullo (ritorna il valore base clamperato); test deterministici.
 function backoffDelay(attempt, opts = {}) {
@@ -735,7 +735,7 @@ function authorizedKeysLine({ remotePort, panelRemotePort, pub } = {}) {
 // registrato in revisione: `null | stringa` comprimeva stati DIVERSI, e il
 // livello basso componeva frasi su fatti che non conosce — meta' della 0.9.5
 // e' nata li'). Gli esiti sono DATI, senza testo per l'utente: le frasi si
-// compongono al confine UI/log, mai qui. Si aggancia a P4: una chiave cifrata
+// Compongono al confine UI/log, mai qui. Si aggancia a: una chiave cifrata
 // dava `null`, indistinguibile da «file illeggibile», e il pairing ometteva
 // la riga in silenzio.
 //

package/lib/notify/ask-answer-service.js

@@ -0,0 +1,184 @@
+'use strict';
+// lib/notify/ask-answer-service.js — ONE answer cycle for BOTH the local route
+// and the federated one. There is no second path: claim (synchronous) ->
+// paste to the session FROM THE STORE (never from a body) -> commit or a
+// declared failure -> a qualified closure event (askId, revision, cell).
+//
+// Federated attempts additionally carry a durable receipt (written BEFORE the
+// paste) and an idempotency contract: the same requestId with the same text
+// after a timeout returns the stored state WITHOUT pasting again; the same id
+// with a different text is a 409. A locked ask (delivery-unknown from a
+// previous crash) refuses new pastes on EVERY path until the operator
+// reconciles explicitly: no silent retries, no TTL.
+
+const crypto = require('node:crypto');
+
+const REQUEST_ID_RE = /^[0-9a-f-]{16,64}$/i;
+
+function createAskAnswerService({ asks, paste, receipts, onClosure, labelPrefix = 'reply' } = {}) {
+  if (!asks || !paste) throw new Error('createAskAnswerService: asks e paste richiesti');
+  const emitClosure = typeof onClosure === 'function' ? onClosure : () => {};
+
+  function pasteText(askId, text, label) {
+    return `[${label} reply · ask#${askId}] ${text}`;
+  }
+
+  // The shared core. Returns {ok:true} or {ok:false, code, error, reason}.
+  async function runAnswer({ askId, text, request = null }) {
+    // A locked ask refuses new pastes on every path until reconciliation.
+    if (receipts && receipts.isBlocked(askId)) {
+      return { ok: false, code: 409, error: 'ask con esito incerto: richiede riconciliazione dell\'operatore', reason: 'delivery-unknown-block' };
+    }
+    // The receipt is authoritative AT THE POINT OF PASTE: an ask whose durable
+    // answer state is already terminal cannot produce a second paste, whichever
+    // path got here — the ask store alone is not enough, because a reconciliation
+    // can land on the receipt without closing the ask.
+    const answerState = receipts && typeof receipts.answerStateFor === 'function'
+      ? receipts.answerStateFor(askId) : null;
+    if (answerState === 'committed' || answerState === 'delivered') {
+      return { ok: false, code: 409, error: 'ask gia\' consegnato: nessun nuovo paste', reason: 'already-delivered' };
+    }
+    const claim = asks.claim(askId);
+    if (!claim.ok) {
+      // Refused BEFORE any paste: the attempt is closed here. Left `pending`, it
+      // would come back as delivery-unknown after a restart and block the ask
+      // for a paste that never happened.
+      if (request && receipts) receipts.finalize(request.peerId, askId, request.requestId, 'failed', `refused:${claim.reason}`);
+      if (claim.reason === 'unknown') return { ok: false, code: 404, error: 'ask inesistente', reason: 'unknown' };
+      if (claim.reason === 'dismissed') return { ok: false, code: 409, error: 'ask gia\' scartato (dismissed)', reason: 'dismissed' };
+      if (claim.reason === 'answering') return { ok: false, code: 409, error: 'risposta gia\' in corso da un\'altra richiesta', reason: 'answering' };
+      return { ok: false, code: 409, error: 'ask gia\' risposto', reason: 'answered' };
+    }
+    let pasted = false;
+    try {
+      pasted = await paste(claim.ask.session, pasteText(askId, text, labelPrefix));
+    } catch (_) { pasted = false; }
+    if (!pasted) {
+      asks.release(askId); // rollback: the ask stays open and contestable
+      if (request && receipts) receipts.finalize(request.peerId, askId, request.requestId, 'failed', 'paste-failed');
+      return { ok: false, code: 502, error: `paste fallito: sessione "${claim.ask.session}" non raggiungibile`, reason: 'paste-failed' };
+    }
+    const committed = asks.commit(askId, text);
+    if (request && receipts) receipts.finalize(request.peerId, askId, request.requestId, 'committed', null);
+    const finalAsk = asks.get(askId);
+    emitClosure('ask-answered', { askId, revision: (finalAsk && finalAsk.revision) || 1, cellSession: finalAsk && finalAsk.session });
+    return { ok: true, committed };
+  }
+
+  // LOCAL answer: validation and binding already happened in the route.
+  async function answerLocal({ askId, text }) {
+    return runAnswer({ askId, text });
+  }
+
+  // FEDERATED answer: the receipt lifecycle wraps the same core.
+  async function answerFederated({ askId, text, peerId, requestId }) {
+    if (!requestId || !REQUEST_ID_RE.test(String(requestId))) {
+      return { ok: false, code: 400, error: 'requestId non valido', reason: 'bad-request-id' };
+    }
+    if (!receipts) return { ok: false, code: 503, error: 'receipt store non disponibile', reason: 'no-receipts' };
+    const existing = receipts.get(peerId, askId, requestId);
+    const digest = receipts.digestOf(text);
+    if (existing) {
+      // Same id, same text: the stored state, never a second paste.
+      if (existing.digest === digest) {
+        return { ok: true, replay: true, state: existing.state };
+      }
+      // Same id, different text: never answer twice with diverging payloads.
+      return { ok: false, code: 409, error: 'stesso requestId con testo diverso', reason: 'request-conflict' };
+    }
+    // Receipt BEFORE the paste: a failed receipt write means no paste at all.
+    const receipt = receipts.attempt({ peerId, askId, requestId, text });
+    if (!receipt.ok) {
+      if (receipt.reason === 'blocked') {
+        return { ok: false, code: 409, error: 'ask con esito incerto: richiede riconciliazione dell\'operatore', reason: 'delivery-unknown-block' };
+      }
+      if (receipt.reason === 'digest-conflict') {
+        return { ok: false, code: 409, error: 'stesso requestId con testo diverso', reason: 'request-conflict' };
+      }
+      return { ok: false, code: 429, error: 'receipt store al cap', reason: 'receipt-cap' };
+    }
+    const out = await runAnswer({ askId, text, request: { peerId, requestId } });
+    if (out.ok) return { ok: true, state: 'committed' };
+    // Every refusal is answered as it is: a rejection BEFORE the paste (claim
+    // lost, ask closed, locked) finalizes the attempt as failed, and a transport
+    // failure does the same — the peer re-checks the status instead of blindly
+    // retrying.
+    return out;
+  }
+
+  // Dismiss: idempotent, refused while an answer is in flight, and refused on an
+  // ask whose delivery is still unknown — dismissing the card would hide an
+  // outcome the operator still has to reconcile.
+  function dismiss(askId) {
+    if (receipts && receipts.isBlocked(askId)) {
+      return { ok: false, code: 409, error: 'ask con esito incerto: richiede riconciliazione dell\'operatore', reason: 'delivery-unknown-block' };
+    }
+    const out = asks.dismiss(askId);
+    if (!out.ok) return out;
+    emitClosure('ask-dismissed', { askId, revision: (out.ask && out.ask.revision) || 1, cellSession: out.ask && out.ask.session });
+    return out;
+  }
+
+  // Operator reconciliation of a delivery-unknown attempt. The revision is a
+  // MANDATORY compare-and-set: a reconciliation decided on a generation that is
+  // already gone must not unlock anything, and the transition itself advances
+  // the revision so the same token cannot be replayed.
+  function reconcile({ askId, decision, expectedRevision }) {
+    if (decision !== 'mark-delivered' && decision !== 'allow-new-attempt') {
+      return { ok: false, code: 400, error: 'decision deve essere mark-delivered|allow-new-attempt', reason: 'bad-decision' };
+    }
+    if (!receipts) return { ok: false, code: 503, error: 'receipt store non disponibile', reason: 'no-receipts' };
+    const ask = asks.get(askId);
+    if (!ask) return { ok: false, code: 404, error: 'ask inesistente', reason: 'unknown' };
+    if (expectedRevision === undefined || expectedRevision === null || expectedRevision === '') {
+      return { ok: false, code: 400, error: 'expectedRevision obbligatoria', reason: 'revision-required' };
+    }
+    if (Number(expectedRevision) !== (ask.revision || 0)) {
+      return { ok: false, code: 409, error: 'revision stantia', reason: 'revision-conflict' };
+    }
+    // A paste that is still in flight is not an outcome to reconcile: its claim
+    // is HERS, and deciding here would release a claim mid-paste and let a
+    // second paste through. Refused without touching the claim.
+    // The window between this check and markReconciled is SYNCHRONOUS (there is
+    // no await in between), so no new claim can appear once the refusal is not
+    // taken: that is what makes the guard sufficient, not the receipt alone.
+    const live = receipts.reconcilableFor(askId);
+    if ((typeof asks.isAnswering === 'function' && asks.isAnswering(askId)) || live.live > 0) {
+      return {
+        ok: false, code: 409, reason: 'answering',
+        error: 'paste in corso su questa ask: riconciliazione rifiutata, il claim non si tocca',
+      };
+    }
+    // Nothing unresolved: `ok:true, changed:0` would be a false success.
+    if (live.count === 0) {
+      return { ok: false, code: 409, reason: 'nothing-to-reconcile', error: 'nessun esito incerto da riconciliare' };
+    }
+    const expect = { count: live.count, generation: live.generation };
+
+    // Restrictive write FIRST, permissive one last: the ask-store transition
+    // closes the ask (mark-delivered) or just advances the revision
+    // (allow-new-attempt), while the receipt keeps blocking the paste until its
+    // own durable write lands. A partial failure therefore never leaves a state
+    // where a paste is possible: the residue is "ask closed" or "receipt still
+    // blocked", never more permissive than the decision.
+    const moved = asks.markReconciled(askId, decision);
+    if (!moved.ok) {
+      return { ok: false, code: 500, error: 'transizione non scritta: stato invariato', reason: 'ask-transition-failed' };
+    }
+    const out = receipts.reconcile(askId, decision, expect);
+    if (!out.ok) {
+      return {
+        ok: false, code: out.reason === 'nothing-to-reconcile' || out.reason === 'generation-changed' ? 409 : 500,
+        reason: out.reason,
+        error: decision === 'mark-delivered'
+          ? 'ricevuta non riconciliata: ask comunque chiuso (nessun paste possibile)'
+          : 'ricevuta non riconciliata: blocco ancora attivo (nessun paste possibile)',
+      };
+    }
+    return { ok: true, changed: out.changed, revision: (moved.ask && moved.ask.revision) || 0 };
+  }
+
+  return { answerLocal, answerFederated, dismiss, reconcile, pasteText };
+}
+
+module.exports = { createAskAnswerService, REQUEST_ID_RE };