@mmmbuto/nexuscrew 0.7.7 → 0.8.2

package/lib/notify/push.js

@@ -0,0 +1,289 @@
+'use strict';
+// Web Push per il MCP bridge (design §2b). Chiavi VAPID generate LAZY al primo
+// uso (mai allo startup: i test che creano il server con path isolati non devono
+// scrivere in ~/.nexuscrew) e persistite in <dir>/vapid.json 0600; subscription
+// in <dir>/push.json 0600, dedup per endpoint. Su push fallito 404/410 la
+// subscription viene rimossa (MA non in READONLY: il cleanup e' una scrittura).
+// Il sender e' iniettabile (webpushImpl) cosi' i test non toccano MAI la rete;
+// la chiave PRIVATA non esce da questo modulo.
+//
+// F7 (audit, threat model SSRF): sendNotification fa una richiesta server-side.
+// Ogni endpoint e' https-only, viene risolto sia al subscribe sia immediatamente
+// prima del send, e la richiesta usa un https.Agent con lookup PINNATO agli IP
+// verificati. Cosi' un secondo lookup/DNS rebinding non puo' cambiare destinazione.
+// Redirect non seguiti: web-push usa https.request diretto; una risposta 3xx e'
+// un errore e non viene mai trasformata in una seconda richiesta.
+const path = require('node:path');
+const dns = require('node:dns');
+const https = require('node:https');
+const net = require('node:net');
+const { readJsonSafe, atomicWriteJson } = require('./persist.js');
+
+const VAPID_FILE = 'vapid.json';
+const SUBS_FILE = 'push.json';
+// Subject VAPID richiesto dallo standard (URL o mailto); nessun host interno.
+const VAPID_SUBJECT = 'mailto:nexuscrew@example.com';
+const MAX_ENDPOINT_LEN = 2048;
+const MAX_KEY_LEN = 512;
+const DEFAULT_MAX_SUBS = 32;
+
+// IPv4 non globale: private, loopback, link-local, carrier-grade NAT,
+// documentation/benchmark, multicast/reserved. Garbage -> true (fail-closed).
+function isNonGlobalV4(ip) {
+  const parts = ip.split('.').map(Number);
+  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  const [a, b] = parts;
+  if (a === 0 || a === 10 || a === 127) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 192 && b === 0) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a === 198 && b === 51 && parts[2] === 100) return true;
+  if (a === 203 && b === 0 && parts[2] === 113) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+function ipv6Words(input) {
+  let ip = String(input || '').toLowerCase();
+  const zone = ip.indexOf('%');
+  if (zone >= 0) ip = ip.slice(0, zone);
+  if (ip.includes('.')) {
+    const cut = ip.lastIndexOf(':');
+    const v4 = ip.slice(cut + 1);
+    if (net.isIP(v4) !== 4) return null;
+    const p = v4.split('.').map(Number);
+    ip = `${ip.slice(0, cut)}:${((p[0] << 8) | p[1]).toString(16)}:${((p[2] << 8) | p[3]).toString(16)}`;
+  }
+  const halves = ip.split('::');
+  if (halves.length > 2) return null;
+  const left = halves[0] ? halves[0].split(':') : [];
+  const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+  const missing = 8 - left.length - right.length;
+  if ((halves.length === 1 && missing !== 0) || missing < 0) return null;
+  const raw = halves.length === 2 ? [...left, ...Array(missing).fill('0'), ...right] : left;
+  if (raw.length !== 8 || raw.some((x) => !/^[0-9a-f]{1,4}$/.test(x))) return null;
+  return raw.map((x) => parseInt(x, 16));
+}
+
+function isNonGlobalV6(ip) {
+  const w = ipv6Words(ip);
+  if (!w) return true;
+  // unspecified/loopback e tutto lo spazio IPv4-compatible /96.
+  if (w.slice(0, 6).every((x) => x === 0)) return true;
+  // IPv4-mapped ::ffff:0:0/96: rifiuto dell'intera famiglia per evitare encoding evasivi.
+  if (w.slice(0, 5).every((x) => x === 0) && w[5] === 0xffff) return true;
+  if ((w[0] & 0xfe00) === 0xfc00) return true; // ULA fc00::/7
+  if ((w[0] & 0xffc0) === 0xfe80) return true; // link-local fe80::/10 (fe80..febf)
+  if ((w[0] & 0xffc0) === 0xfec0) return true; // site-local deprecato fec0::/10
+  if ((w[0] & 0xff00) === 0xff00) return true; // multicast
+  // IPv4-in-IPv6/transizione: rifiuto dell'intero prefisso, anche se l'IPv4
+  // incorporato appare pubblico, per evitare rappresentazioni evasive.
+  if (w[0] === 0x0064 && w[1] === 0xff9b
+    && (w.slice(2, 6).every((x) => x === 0) || w[2] === 0x0001)) return true; // NAT64
+  if (w[0] === 0x2002) return true; // 6to4
+  if (w[4] === 0 && w[5] === 0x5efe) return true; // ISATAP
+  if (w[0] === 0x2001 && (w[1] === 0x0000 || w[1] === 0x0db8)) return true; // special/documentation
+  return false;
+}
+
+function isNonGlobalIp(address) {
+  const family = net.isIP(address);
+  if (family === 4) return isNonGlobalV4(address);
+  if (family === 6) return isNonGlobalV6(address);
+  return true;
+}
+
+// Host vietati quando espressi come letterali; gli hostname passano poi dal DNS.
+function isForbiddenHost(hostname) {
+  const h = String(hostname || '').toLowerCase();
+  if (!h) return true;
+  if (h === 'localhost' || h === 'localhost.' || h.endsWith('.localhost')) return true;
+  const literal = h.startsWith('[') && h.endsWith(']') ? h.slice(1, -1) : h;
+  if (net.isIP(literal)) return isNonGlobalIp(literal);
+  return false;
+}
+
+// Validazione subscription fail-closed. {ok:true} | {ok:false, error}.
+function validateSubscription(s) {
+  if (!s || typeof s !== 'object' || Array.isArray(s)) return { ok: false, error: 'subscription non valida' };
+  if (typeof s.endpoint !== 'string' || !s.endpoint) return { ok: false, error: 'endpoint mancante' };
+  if (s.endpoint.length > MAX_ENDPOINT_LEN) return { ok: false, error: `endpoint troppo lungo (max ${MAX_ENDPOINT_LEN})` };
+  let url;
+  try { url = new URL(s.endpoint); } catch (_) { return { ok: false, error: 'endpoint non e\' un URL valido' }; }
+  if (url.protocol !== 'https:') return { ok: false, error: 'endpoint deve essere https (i push service usano solo https)' };
+  if (url.username || url.password) return { ok: false, error: 'endpoint con credenziali non ammesso' };
+  if (isForbiddenHost(url.hostname)) return { ok: false, error: 'endpoint verso host loopback/privato non ammesso' };
+  if (!s.keys || typeof s.keys !== 'object' || Array.isArray(s.keys)
+    || typeof s.keys.p256dh !== 'string' || !s.keys.p256dh || s.keys.p256dh.length > MAX_KEY_LEN
+    || typeof s.keys.auth !== 'string' || !s.keys.auth || s.keys.auth.length > MAX_KEY_LEN) {
+    return { ok: false, error: 'subscription.keys non valide (p256dh, auth)' };
+  }
+  return { ok: true };
+}
+
+async function resolvePublicEndpoint(endpoint, lookupImpl = dns.promises.lookup) {
+  const url = new URL(endpoint);
+  const host = url.hostname.startsWith('[') ? url.hostname.slice(1, -1) : url.hostname;
+  if (net.isIP(host)) {
+    if (isNonGlobalIp(host)) throw new Error('endpoint verso indirizzo non globale non ammesso');
+    return { hostname: host, addresses: [{ address: host, family: net.isIP(host) }] };
+  }
+  let answers;
+  try { answers = await lookupImpl(host, { all: true, verbatim: true }); }
+  catch (_) { throw new Error('DNS endpoint non risolvibile'); }
+  if (!Array.isArray(answers)) answers = answers ? [answers] : [];
+  if (!answers.length || answers.some((a) => !a || isNonGlobalIp(a.address))) {
+    throw new Error('DNS endpoint contiene un indirizzo non globale');
+  }
+  return {
+    hostname: host,
+    addresses: answers.map((a) => ({ address: a.address, family: a.family || net.isIP(a.address) })),
+  };
+}
+
+function pinnedAgent(resolved) {
+  let next = 0;
+  return new https.Agent({
+    keepAlive: false,
+    maxCachedSessions: 0,
+    lookup(hostname, options, callback) {
+      if (String(hostname).toLowerCase() !== resolved.hostname.toLowerCase()) {
+        callback(new Error('DNS hostname inatteso durante il send'));
+        return;
+      }
+      if (options && options.all) {
+        callback(null, resolved.addresses.map((a) => ({ ...a })));
+        return;
+      }
+      const answer = resolved.addresses[next++ % resolved.addresses.length];
+      callback(null, answer.address, answer.family);
+    },
+  });
+}
+
+function createPushService(opts = {}) {
+  if (!opts.dir) throw new Error('createPushService: dir richiesta');
+  const vapidPath = path.join(opts.dir, VAPID_FILE);
+  const subsPath = path.join(opts.dir, SUBS_FILE);
+  // F3: closure iniettata dal server — in READONLY questo modulo non scrive MAI
+  // (niente generazione VAPID, niente cleanup subscription).
+  const readonly = typeof opts.readonly === 'function' ? opts.readonly : () => false;
+  const lookupImpl = opts.lookupImpl || dns.promises.lookup;
+  const maxSubs = Number.isInteger(opts.maxSubs) && opts.maxSubs > 0 ? opts.maxSubs : DEFAULT_MAX_SUBS;
+  // Seam test: {generateVAPIDKeys, sendNotification}. Default: npm web-push.
+  // require LAZY: il modulo nativo si carica solo se il push viene davvero usato.
+  let webpush = opts.webpushImpl || null;
+  function impl() {
+    if (!webpush) webpush = require('web-push');
+    return webpush;
+  }
+
+  // --- VAPID (lazy) ---------------------------------------------------------
+  let vapid = null;
+  function loadVapid() {
+    if (vapid && vapid.publicKey && vapid.privateKey) return vapid;
+    const cur = readJsonSafe(vapidPath); // fail-closed su mode/owner/symlink (F4)
+    if (typeof cur.publicKey === 'string' && cur.publicKey
+      && typeof cur.privateKey === 'string' && cur.privateKey) {
+      vapid = { publicKey: cur.publicKey, privateKey: cur.privateKey };
+      return vapid;
+    }
+    // F3: la generazione e' una SCRITTURA — vietata in READONLY (503 esplicito,
+    // niente vapid.json fantasma).
+    if (readonly()) {
+      const e = new Error('READONLY: chiavi VAPID assenti e non generabili (riavvia senza READONLY per il primo setup push)');
+      e.status = 503;
+      throw e;
+    }
+    const keys = impl().generateVAPIDKeys();
+    vapid = { publicKey: keys.publicKey, privateKey: keys.privateKey };
+    atomicWriteJson(vapidPath, vapid);
+    return vapid;
+  }
+
+  function vapidPublicKey() { return loadVapid().publicKey; }
+
+  // --- subscription store ----------------------------------------------------
+  function readSubs() {
+    const cur = readJsonSafe(subsPath);
+    return Array.isArray(cur.subscriptions) ? cur.subscriptions : [];
+  }
+  function writeSubs(list) { atomicWriteJson(subsPath, { subscriptions: list }); }
+
+  // Persiste (dedup per endpoint: la nuova sostituisce la vecchia). Cap duro sul
+  // numero: un endpoint NUOVO oltre maxSubs viene rifiutato (reason 'cap').
+  async function subscribe(subscription) {
+    const v = validateSubscription(subscription);
+    if (!v.ok) return { ok: false, error: v.error };
+    try { await resolvePublicEndpoint(subscription.endpoint, lookupImpl); }
+    catch (e) { return { ok: false, error: e.message }; }
+    const cur = readSubs();
+    const keep = cur.filter((s) => s.endpoint !== subscription.endpoint);
+    if (keep.length === cur.length && cur.length >= maxSubs) {
+      return { ok: false, reason: 'cap', error: `troppe subscription push (max ${maxSubs}): rimuovine una prima` };
+    }
+    keep.push({ endpoint: subscription.endpoint, keys: { p256dh: subscription.keys.p256dh, auth: subscription.keys.auth } });
+    writeSubs(keep);
+    return { ok: true, count: keep.length };
+  }
+
+  function unsubscribe(endpoint) {
+    if (typeof endpoint !== 'string' || !endpoint) return { ok: false, error: 'endpoint mancante' };
+    const cur = readSubs();
+    const keep = cur.filter((s) => s.endpoint !== endpoint);
+    if (keep.length !== cur.length) writeSubs(keep);
+    return { ok: true, removed: cur.length - keep.length };
+  }
+
+  function count() { return readSubs().length; }
+
+  // Invia il payload a tutte le subscription. 404/410 (endpoint morto) -> la
+  // subscription si rimuove, MA NON in READONLY (F3: riscrivere push.json e' una
+  // scrittura persistente; la notify viene comunque consegnata alle vive).
+  // Nessuna subscription -> {sent:0} senza generare VAPID (resta lazy davvero).
+  async function sendToAll(payload) {
+    const subs = readSubs();
+    if (subs.length === 0) return { sent: 0, removed: 0 };
+    const { publicKey, privateKey } = loadVapid();
+    const body = JSON.stringify(payload);
+    let sent = 0;
+    const dead = new Set();
+    for (const sub of subs) {
+      let agent;
+      try {
+        const valid = validateSubscription(sub); // anche store legacy/manomesso: fail-closed al send
+        if (!valid.ok) throw new Error(valid.error);
+        const resolved = await resolvePublicEndpoint(sub.endpoint, lookupImpl);
+        agent = pinnedAgent(resolved);
+        const response = await impl().sendNotification(sub, body, {
+          vapidDetails: { subject: VAPID_SUBJECT, publicKey, privateKey },
+          TTL: 3600,
+          agent,
+        });
+        if (response && Number.isInteger(response.statusCode)
+          && (response.statusCode < 200 || response.statusCode > 299)) {
+          const e = new Error('redirect/risposta push non ammessa');
+          e.statusCode = response.statusCode;
+          throw e;
+        }
+        sent += 1;
+      } catch (e) {
+        const code = e && e.statusCode;
+        if (code === 404 || code === 410) dead.add(sub.endpoint);
+        // altri errori: transitori, la subscription resta (best-effort, mai throw)
+      } finally { if (agent) agent.destroy(); }
+    }
+    if (dead.size && !readonly()) writeSubs(subs.filter((s) => !dead.has(s.endpoint)));
+    return { sent, removed: dead.size };
+  }
+
+  return { vapidPublicKey, subscribe, unsubscribe, count, sendToAll, validateSubscription };
+}
+
+module.exports = {
+  createPushService, validateSubscription, isForbiddenHost,
+  isNonGlobalIp, resolvePublicEndpoint, pinnedAgent,
+};

package/lib/notify/routes.js

@@ -0,0 +1,260 @@
+'use strict';
+// Route del MCP bridge (design §2): notify, web-push, asks. Montate dentro il
+// router /api gia' dietro requireToken (server.js) — qui restano solo:
+//   - READONLY come FLOOR (F3 audit): sono gated 403 TUTTI i mutanti — answer
+//     (scrittura PTY via paste), push subscribe/unsubscribe (push.json) e la
+//     CREAZIONE di ask (persiste asks.json e genererebbe domande non
+//     risponibili dallo stesso server). L'UNICA eccezione dichiarata e' la
+//     notify: canale informativo inbound cella→operatore, effimero (broadcast SSE +
+//     push senza persistenza; anche il cleanup delle subscription morte e'
+//     sospeso in READONLY, vedi lib/notify/push.js). Le GET restano lettura
+//     pura: /push/vapid in READONLY non genera chiavi (503 se assenti).
+//   - rate-limit (F1 audit): il campo `session` e' dichiarato dal chiamante e
+//     NON e' un confine di sicurezza — il limite che conta e' GLOBALE per
+//     principal/token (un Bearer = un'installazione); il bucket per-sessione
+//     resta come fairness tra celle oneste. Stessa coppia di limiti sulla
+//     creazione ask (F5).
+//   - validazione input strict fail-closed (schema chiuso per ogni body).
+// Il paste della risposta riusa ESATTAMENTE pasteToSession (bracketed literal,
+// niente Invio, control char rifiutati): qui si sanifica il testo PRIMA.
+const express = require('express');
+const { isValidSession } = require('../files/store.js');
+
+const NOTIFY_KEYS = new Set(['title', 'body', 'urgency', 'session']);
+const ASK_KEYS = new Set(['question', 'options', 'session']);
+const RATE_MAX = 6;
+const RATE_WINDOW_MS = 60 * 1000;
+const RATE_MAX_BUCKETS = 64;
+const MAX_TITLE = 200;
+const MAX_BODY = 2000;
+// Il paste tmux accetta max 4096 char: prefisso `[human reply · ask#xxxxxxxx] `
+// (~32 char) + testo -> cap prudente sul testo.
+const MAX_ANSWER = 3900;
+const MAX_REPLY_LABEL = 48;
+
+// Sliding window in-memory per chiave. La mappa ha un cap duro (F1): entry
+// scadute potate a ogni giro, poi evizione LRU deterministica (ordine di
+// iterazione della Map = ordine di ultimo uso, re-insert ad ogni allow).
+// NB: l'evizione azzera il conteggio del bucket evitto — per questo il cap
+// per-chiave NON e' il confine di sicurezza: quello e' il bucket GLOBALE
+// (chiave fissa, mai evitto perche' sempre re-inserito per ultimo).
+function createRateLimiter({ max = RATE_MAX, windowMs = RATE_WINDOW_MS, maxBuckets = RATE_MAX_BUCKETS, now = Date.now } = {}) {
+  const hits = new Map(); // key -> [timestamps]
+  function allow(key) {
+    const t = now();
+    const list = (hits.get(key) || []).filter((x) => t - x < windowMs);
+    const allowed = list.length < max;
+    if (allowed) list.push(t);
+    hits.delete(key); hits.set(key, list); // re-insert: la Map resta in ordine LRU
+    // prune deterministico: prima le entry con finestra scaduta...
+    for (const [k, l] of hits) {
+      if (k !== key && (l.length === 0 || t - l[l.length - 1] >= windowMs)) hits.delete(k);
+    }
+    // ...poi cap duro LRU (la meno recente e' la prima in iterazione).
+    while (hits.size > maxBuckets) hits.delete(hits.keys().next().value);
+    return allowed;
+  }
+  return { allow, size: () => hits.size };
+}
+
+// Coppia di limiti F1/F5: globale per token (confine di sicurezza) + per
+// sessione (fairness). Una richiesta oltre-limite consuma comunque il budget
+// globale: anche lo spam rifiutato e' attivita' del principal.
+function createSenderLimiter(rateCfg = {}) {
+  const perSession = createRateLimiter(rateCfg);
+  const global = createRateLimiter({
+    max: rateCfg.globalMax || rateCfg.max || RATE_MAX,
+    windowMs: rateCfg.windowMs || RATE_WINDOW_MS,
+    maxBuckets: 2,
+  });
+  return (sender) => {
+    const g = global.allow('*'); // valutato SEMPRE (niente short-circuit nascosto)
+    const s = perSession.allow(sender);
+    return g && s;
+  };
+}
+
+// Control char (0x00-0x1f, 0x7f) -> spazio: il paste li rifiuta a monte, e una
+// risposta multiriga della UI deve comunque arrivare come UNA riga senza Invio.
+function sanitizePasteText(text) {
+  let out = '';
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text.charCodeAt(i);
+    out += (c <= 0x1f || c === 0x7f) ? ' ' : text[i];
+  }
+  return out.trim();
+}
+
+function replyLabel(cfg) {
+  const clean = sanitizePasteText(String((cfg && cfg.replyLabel) || 'human')).slice(0, MAX_REPLY_LABEL).trim();
+  return clean || 'human';
+}
+
+function notifyRoutes({ cfg, notifier, push, asks, paste, sessionExists }) {
+  const r = express.Router();
+  const json = express.json({ limit: '16kb' });
+
+  const readonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+  const mutGate = (_req, res, next) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: mutazione bloccata' });
+    next();
+  };
+  const allowNotify = createSenderLimiter(cfg.notifyRate || {});
+  const allowAsk = createSenderLimiter(cfg.askRate || cfg.notifyRate || {});
+
+  // --- POST /notify — broadcast UI + web-push -------------------------------
+  r.post('/notify', json, async (req, res) => {
+    try {
+      const b = req.body;
+      if (!b || typeof b !== 'object' || Array.isArray(b)) {
+        return res.status(400).json({ error: 'body deve essere un oggetto JSON' });
+      }
+      for (const k of Object.keys(b)) {
+        if (!NOTIFY_KEYS.has(k)) return res.status(400).json({ error: `chiave non ammessa: "${k}" (schema: title, body?, urgency?, session?)` });
+      }
+      if (typeof b.title !== 'string' || !b.title.trim()) {
+        return res.status(400).json({ error: 'title deve essere una stringa non vuota' });
+      }
+      if (b.title.length > MAX_TITLE) return res.status(400).json({ error: `title troppo lungo (max ${MAX_TITLE})` });
+      if (b.body !== undefined && (typeof b.body !== 'string' || b.body.length > MAX_BODY)) {
+        return res.status(400).json({ error: `body deve essere una stringa (max ${MAX_BODY})` });
+      }
+      if (b.urgency !== undefined && b.urgency !== 'normal' && b.urgency !== 'high') {
+        return res.status(400).json({ error: 'urgency deve essere "normal" o "high"' });
+      }
+      if (b.session !== undefined && !isValidSession(b.session)) {
+        return res.status(400).json({ error: 'session non valida' });
+      }
+      const sender = b.session || 'unknown';
+      if (!allowNotify(sender)) {
+        return res.status(429).json({ error: 'rate limit notify superato (limite globale per token + per sessione)' });
+      }
+      const delivered = await notifier.emit({
+        title: b.title.trim(), body: b.body, urgency: b.urgency, session: b.session,
+      });
+      res.json({ delivered });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  // --- web-push --------------------------------------------------------------
+  // GET lettura pura; in READONLY push.vapidPublicKey() NON genera chiavi e
+  // segnala 503 (e.status) se assenti — F3.
+  r.get('/push/vapid', (_req, res) => {
+    try { res.json({ publicKey: push.vapidPublicKey() }); }
+    catch (e) { res.status(e.status || 500).json({ error: String(e.message || e) }); }
+  });
+
+  r.post('/push/subscribe', mutGate, json, async (req, res) => {
+    try {
+      const sub = req.body && req.body.subscription;
+      const out = await push.subscribe(sub);
+      // F7: cap sul numero di subscription -> 429 (quota), input invalido -> 400.
+      if (!out.ok) return res.status(out.reason === 'cap' ? 429 : 400).json({ error: out.error });
+      res.json({ subscribed: true, count: out.count });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  r.delete('/push/subscribe', mutGate, json, (req, res) => {
+    try {
+      const out = push.unsubscribe(req.body && req.body.endpoint);
+      if (!out.ok) return res.status(400).json({ error: out.error });
+      res.json({ removed: out.removed });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  // --- asks ------------------------------------------------------------------
+  // F3: gated READONLY (mutGate) — crea stato durevole (asks.json) e domande
+  // che lo stesso server vieterebbe di rispondere. F5: rate-limit creazione
+  // (globale per token + per sessione) + cap duro dello store -> 429.
+  r.post('/asks', mutGate, json, async (req, res) => {
+    try {
+      const b = req.body;
+      if (!b || typeof b !== 'object' || Array.isArray(b)) {
+        return res.status(400).json({ error: 'body deve essere un oggetto JSON' });
+      }
+      for (const k of Object.keys(b)) {
+        if (!ASK_KEYS.has(k)) return res.status(400).json({ error: `chiave non ammessa: "${k}" (schema: question, options?, session)` });
+      }
+      // session obbligatoria E viva: la risposta va incollata li' — un ask senza
+      // recapito verificabile e' fail-closed subito, non al momento dell'answer.
+      if (!isValidSession(b.session)) return res.status(400).json({ error: 'session non valida' });
+      if (!sessionExists(b.session)) return res.status(404).json({ error: 'sessione tmux inesistente' });
+      // Validazione del contenuto PRIMA del rate check: gli input invalidi (400)
+      // non consumano budget; il rate scatta solo su richieste ben formate.
+      const v = asks.validate({ question: b.question, options: b.options });
+      if (!v.ok) return res.status(400).json({ error: v.error });
+      if (!allowAsk(b.session)) {
+        return res.status(429).json({ error: 'rate limit ask superato (limite globale per token + per sessione)' });
+      }
+      const out = asks.create({ question: b.question, options: b.options, session: b.session });
+      if (!out.ok) return res.status(out.reason === 'cap' ? 429 : 400).json({ error: out.error });
+      const ask = out.ask;
+      // Frame dedicato per le UI aperte (card/badge live, senza aspettare il poll)…
+      notifier.emitRaw({ type: 'ask', ask });
+      // …e ogni ask emette anche notify (UI+push, urgency high) con deep-link.
+      await notifier.emit({
+        title: `domanda da ${ask.session}`,
+        body: ask.question,
+        urgency: 'high',
+        session: ask.session,
+        url: `/#ask=${ask.id}`,
+      });
+      res.status(201).json({ id: ask.id });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  r.get('/asks', (req, res) => {
+    try { res.json({ asks: asks.list({ open: String(req.query.open || '') === '1' }) }); }
+    catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  // Answer: READONLY floor (il paste e' una scrittura PTY). F2 (audit): il
+  // ciclo e' claim atomico (open -> answering, sincrono, PRIMA dell'await del
+  // paste) -> paste -> commit su successo / release su fallimento. Una sola
+  // richiesta concorrente vince; le altre vedono 409. Paste fallito -> 502 e
+  // l'ask torna open (ri-risponibile dopo il resurrect della cella).
+  r.post('/asks/:id/answer', mutGate, json, async (req, res) => {
+    try {
+      const id = String(req.params.id || '');
+      // Validazione del testo PRIMA del claim: nessun claim da rilasciare su 400.
+      const raw = req.body && req.body.text;
+      if (typeof raw !== 'string') return res.status(400).json({ error: 'text deve essere una stringa' });
+      const text = sanitizePasteText(raw).slice(0, MAX_ANSWER);
+      if (!text && asks.get(id)) return res.status(400).json({ error: 'text vuoto dopo la sanificazione' });
+      const claim = asks.claim(id);
+      if (!claim.ok) {
+        if (claim.reason === 'unknown') return res.status(404).json({ error: 'ask inesistente' });
+        if (claim.reason === 'answering') return res.status(409).json({ error: 'risposta gia\' in corso da un\'altra richiesta' });
+        return res.status(409).json({ error: 'ask gia\' risposto' });
+      }
+      let pasted = false;
+      try {
+        pasted = await paste(claim.ask.session, `[${replyLabel(cfg)} reply · ask#${id}] ${text}`);
+      } catch (_) { pasted = false; }
+      if (!pasted) {
+        asks.release(id); // rollback: l'ask resta open e contendibile
+        return res.status(502).json({ error: `paste fallito: sessione "${claim.ask.session}" non raggiungibile` });
+      }
+      asks.commit(id, text);
+      // Le altre UI aperte tolgono la card/badge senza aspettare il poll.
+      notifier.emitRaw({ type: 'ask-answered', id });
+      res.json({ answered: true, id });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  // Body JSON malformato (express.json) -> 400 con causa, mai stack trace.
+  // eslint-disable-next-line no-unused-vars
+  r.use((err, _req, res, _next) => {
+    if (err && err.type === 'entity.parse.failed') {
+      return res.status(400).json({ error: 'body JSON non valido' });
+    }
+    if (err && err.type === 'entity.too.large') {
+      return res.status(400).json({ error: 'body troppo grande (limite 16kb)' });
+    }
+    res.status((err && err.status) || 500).json({ error: String((err && err.message) || err) });
+  });
+
+  return r;
+}
+
+module.exports = { notifyRoutes, createRateLimiter, sanitizePasteText, replyLabel };