@mmmbuto/nexuscrew 0.9.20 → 0.9.21

package/lib/identity/binding-guard.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const { normalizeIdentityContext } = require('../mcp/identity-schema.js');
+
+const IDENTITY_BINDING_HEADER = 'x-nexuscrew-identity-binding';
+const IDENTITY_BINDING_MISSING = 'NEXUSCREW_IDENTITY_BINDING_MISSING';
+const IDENTITY_BINDING_INVALID = 'NEXUSCREW_IDENTITY_BINDING_INVALID';
+const IDENTITY_BINDING_MISMATCH = 'NEXUSCREW_IDENTITY_BINDING_MISMATCH';
+
+function bindingError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function resolveInstanceId(instanceId) {
+  return typeof instanceId === 'function' ? instanceId() : instanceId;
+}
+
+function expectedFromSession(session, instanceId) {
+  if (!session) return null;
+  return { instanceId: resolveInstanceId(instanceId), tmuxSession: session };
+}
+
+// Il proof child firma i timestamp come stringhe decimali (JSON del canale
+// persistito). Il contesto shared prodotto dal provider li converte, ma un
+// binding che copia il proof deve restare verificabile senza allargare lo
+// schema MCP generale: qui si accettano SOLO stringhe decimali intere.
+function canonicalTimestamp(value) {
+  if (typeof value !== 'string' || !/^[0-9]+$/.test(value)) return value;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : value;
+}
+
+function normalizeBindingContext(raw) {
+  return {
+    ...raw,
+    issuedAt: canonicalTimestamp(raw && raw.issuedAt),
+    notBefore: canonicalTimestamp(raw && raw.notBefore),
+    expiresAt: canonicalTimestamp(raw && raw.expiresAt),
+  };
+}
+
+function createIdentityBindingGuard({
+  fleetP = null, instanceId = null, now = Date.now, sharedRequired = false,
+} = {}) {
+  async function verify(req, { expected = null, localOnly = true } = {}) {
+    const raw = req && req.headers && req.headers[IDENTITY_BINDING_HEADER];
+    if (raw === undefined) {
+      if (sharedRequired) {
+        throw bindingError(IDENTITY_BINDING_MISSING, 'binding identita obbligatorio');
+      }
+      return null;
+    }
+
+    let parsed;
+    try { parsed = JSON.parse(String(raw)); } catch (_) {
+      throw bindingError(IDENTITY_BINDING_INVALID, 'binding identita non valido');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw bindingError(IDENTITY_BINDING_INVALID, 'binding identita non valido');
+    }
+
+    let context;
+    try { context = normalizeIdentityContext(normalizeBindingContext(parsed.context), { now }); } catch (_) {
+      throw bindingError(IDENTITY_BINDING_INVALID, 'binding identita non valido');
+    }
+
+    const proof = parsed.proof;
+    if (!proof || typeof proof !== 'object' || Array.isArray(proof)) {
+      throw bindingError(IDENTITY_BINDING_INVALID, 'binding identita non valido');
+    }
+
+    const localId = resolveInstanceId(instanceId);
+    if (localOnly && localId && context.ownerInstanceId !== localId) {
+      throw bindingError(IDENTITY_BINDING_MISMATCH, 'binding identita locale atteso');
+    }
+
+    if (expected) {
+      if (expected.instanceId !== undefined && context.ownerInstanceId !== expected.instanceId) {
+        throw bindingError(IDENTITY_BINDING_MISMATCH, 'binding identita nodo discordante');
+      }
+      if (expected.cell !== undefined && context.cellId !== expected.cell) {
+        throw bindingError(IDENTITY_BINDING_MISMATCH, 'binding identita cella discordante');
+      }
+      if (expected.tmuxSession !== undefined && context.tmuxSession !== expected.tmuxSession) {
+        throw bindingError(IDENTITY_BINDING_MISMATCH, 'binding identita sessione discordante');
+      }
+    }
+
+    let fleet = null;
+    try { fleet = await fleetP; } catch (_) { fleet = null; }
+    const lease = fleet && fleet.lease;
+    if (!lease || typeof lease.childIntrospect !== 'function') {
+      throw bindingError(IDENTITY_BINDING_INVALID, 'binding identita non verificabile');
+    }
+
+    const out = lease.childIntrospect(proof);
+    if (!out || out.status !== 'live' || out.cellId !== context.cellId
+      || out.incarnationId !== context.threadId
+      || Number(out.expiresAt) !== Number(context.expiresAt)) {
+      throw bindingError(IDENTITY_BINDING_INVALID, 'binding identita non valido');
+    }
+
+    return context;
+  }
+
+  return {
+    verify,
+    header: IDENTITY_BINDING_HEADER,
+    codes: {
+      missing: IDENTITY_BINDING_MISSING,
+      invalid: IDENTITY_BINDING_INVALID,
+      mismatch: IDENTITY_BINDING_MISMATCH,
+    },
+  };
+}
+
+module.exports = {
+  IDENTITY_BINDING_HEADER,
+  IDENTITY_BINDING_MISSING,
+  IDENTITY_BINDING_INVALID,
+  IDENTITY_BINDING_MISMATCH,
+  bindingError,
+  createIdentityBindingGuard,
+  expectedFromSession,
+  resolveInstanceId,
+};

package/lib/live-host/bridge.js

@@ -416,6 +416,10 @@ function createLiveBridge({
   const threadIdsByCell = new Map();
   const threadStatusCache = new Map();
   const threadStatusInFlight = new Map();
+  // R4: riserve in-process per l'avvio Live. La chiave è la cella host: una
+  // sola start provvisoria per cella alla volta, e il commit ricontrolla la
+  // tupla congelata in riserva prima di accettare il thread creato.
+  const pendingLiveByCell = new Map();
   const threadStatusCacheMs = Number.isFinite(cfg.liveThreadStatusCacheMs)
     ? Math.max(0, cfg.liveThreadStatusCacheMs) : THREAD_STATUS_CACHE_MS;
 
@@ -442,6 +446,35 @@ function createLiveBridge({
     }
   }
 
+  // Tupla dell'avvio Live come la osserva questo ponte: designazione (cella,
+  // revision, idoneità) più stato firmato del lease dell'host. Generation ed
+  // epoch arrivano dallo stesso status quando il lease manager li espone.
+  function liveTuple(snap, leaseStatus) {
+    const lease = leaseStatus && typeof leaseStatus === 'object' ? leaseStatus : { state: leaseStatus };
+    return JSON.stringify({
+      hostCell: snap ? snap.hostCell : null,
+      revision: snap ? snap.revision : null,
+      eligible: snap ? snap.eligible === true : false,
+      lease: {
+        state: lease.state == null ? null : lease.state,
+        leaseId: lease.leaseId == null ? null : lease.leaseId,
+        generation: lease.generation == null ? null : lease.generation,
+        launchEpoch: lease.launchEpoch == null ? null : lease.launchEpoch,
+      },
+    });
+  }
+
+  async function leaseTupleFor(cellId) {
+    try {
+      const fleet = await fleetP;
+      const lease = fleet && fleet.lease;
+      if (!lease || typeof lease.status !== 'function') return { state: 'unavailable' };
+      return lease.status(cellId) || { state: 'none' };
+    } catch (_) {
+      return { state: 'unavailable' };
+    }
+  }
+
   async function rosterCell(cellId) {
     const fleet = await fleetP;
     if (!fleet || fleet.available !== true) return null;
@@ -540,6 +573,14 @@ function createLiveBridge({
       ? `${intestazione}\n\n${prompt.text}`
       : intestazione;
 
+    // R4: riserva della tupla e start provvisorio. Finché il commit non
+    // ricontrolla la stessa tupla, il thread NON viene accettato: nessun tool
+    // può attraversarlo, perché il ponte non ne registra l'id.
+    if (pendingLiveByCell.has(snap.hostCell)) return none('reservation-in-flight');
+    const reservedLease = await leaseTupleFor(snap.hostCell);
+    const reservedTuple = liveTuple(snap, reservedLease);
+    pendingLiveByCell.set(snap.hostCell, reservedTuple);
+
     let started;
     try {
       started = await startThreadOnControlSocket({
@@ -557,9 +598,37 @@ function createLiveBridge({
     } catch (e) {
       const reason = e && e.code === 'ETIMEOUT' ? 'bridge-timeout' : 'bridge-socket-failed';
       log(`[live-bridge] thread ponte NON creata (${reason}): ${e.message}`);
+      pendingLiveByCell.delete(snap.hostCell);
       return none(reason, { cell: snap.hostCell, detail: String(e.message) });
     }
 
+    // R4: commit. La designazione e il lease vengono riletti e confrontati con
+    // la tupla riservata: se qualcosa è cambiato durante lo start, il thread
+    // resta scartato (zero dispatch) e l'esito lo dichiara con l'id scartato.
+    let commitSnap;
+    let commitLease;
+    try {
+      commitSnap = await readDesignation();
+      commitLease = await leaseTupleFor(snap.hostCell);
+    } catch (e) {
+      pendingLiveByCell.delete(snap.hostCell);
+      log(`[live-bridge] commit illeggibile: thread ${started.threadId} scartato (${e.message})`);
+      return none('commit-unreadable', {
+        cell: snap.hostCell, discardedThread: started.threadId, detail: String(e.message),
+      });
+    }
+    if (liveTuple(commitSnap, commitLease) !== reservedTuple) {
+      // Primato alla causa radice: se il lease è cambiato, eligible oscilla
+      // con lui, e la designazione NON è la causa.
+      const leaseOf = (value) => liveTuple({ hostCell: null, revision: null, eligible: null }, value);
+      const reason = leaseOf(commitLease) !== leaseOf(reservedLease)
+        ? 'lease-changed' : 'designation-changed';
+      pendingLiveByCell.delete(snap.hostCell);
+      log(`[live-bridge] tupla cambiata in volo (${reason}): thread ${started.threadId} scartato`);
+      return none(reason, { cell: snap.hostCell, discardedThread: started.threadId });
+    }
+    pendingLiveByCell.delete(snap.hostCell);
+
     const { text, ...promptEcho } = prompt; // il testo del prompt non viaggia in risposta
     const out = {
       mode: 'native', cell: snap.hostCell, engine,

package/lib/live-host/routes.js

@@ -19,6 +19,10 @@
 //   - Cella inattiva PRESERVA la designazione: lo store non cancella mai hostCell per
 //     inattivita; `eligible` e' derivato dal roster al momento del GET.
 //   - readonly => 403 su designate/clear.
+//
+// Fuori dal perimetro del binding MCP: designate/clear/bridge sono superficie di
+// gestione locale dell'operatore, non effetti richiesti da una cella tramite il
+// bridge. Il token del nodo resta l'autorita'; il binding shared non e' richiesto.
 
 const express = require('express');
 const { CELL_ID_RE } = require('./store.js');
@@ -51,10 +55,10 @@ function isActive(cell) {
 //     distingue «non idonea perche' morta» da «non idonea perche' in recupero».
 //   - I cinque stati (live|grace|expired|none|unavailable) restano DISTINCTI
 //     fino a chi legge: collassarli e' rifare il difetto a un piano piu' su.
-//   - FALLBACK FAIL-OPEN DICHIARATO: senza fleet.lease (installazione senza
-//     lease) eligible torna tmux-only e host.lease='unavailable'. Non e' «va
-//     bene lo stesso»: e' «la garanzia non e' disponibile qui», detto esplicito
-//     perche' un eligible=true silenzioso verrebbe letto come confermata.
+//   - FALLBACK FAIL-CLOSED: senza fleet.lease (installazione senza lease)
+//     eligible resta false e host.lease='unavailable'. L'attach locale D resta
+//     disponibile al suo percorso, ma il dispatch Live non può diventare
+//     tmux-only senza la garanzia del lease.
 //   - hostCell resta PRESERVATO in ogni caso (invariante dello store): oscilla
 //     l'idoneita', non la scelta dell'operatore.
 function hostLeaseState(fleet, hostCell) {
@@ -68,7 +72,7 @@ function hostLeaseState(fleet, hostCell) {
 function eligibleOf(fleet, cell, hostCell) {
   const leaseState = hostLeaseState(fleet, hostCell);
   if (leaseState === null) return false; // senza soggetto non c'e' idoneita'
-  if (leaseState === 'unavailable') return isActive(cell); // fail-open dichiarato
+  if (leaseState === 'unavailable') return false;
   return isActive(cell) && leaseState === 'live';
 }
 

package/lib/mcp/identity-provider.js

@@ -0,0 +1,132 @@
+'use strict';
+// Canale produttivo del contesto shared per il bridge MCP.
+//
+// Il proof child authority-backed, ottenuto da register/refresh in authority
+// mode, viene persistito accanto al token in una directory privata del nodo:
+// quello è l'unico canale condiviso fra i processi della cella (contratto:
+// nessun isolamento fra processi dello stesso UID). L'env seleziona il FILE
+// del canale ma mai l'identità: questa arriva soltanto dal proof firmato,
+// verificato online dall'hub a ogni introspezione. Senza canale non esiste
+// provider e il bridge resta sul percorso embedded legacy.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readTokenSafe } = require('../auth/token.js');
+const { cellIdFromTmuxSession, tmuxSessionForCell } = require('../fleet/definitions.js');
+const {
+  identityContextError, IDENTITY_CONTEXT_AUTHORITY_UNAVAILABLE,
+} = require('./identity-schema.js');
+
+const INTROSPECT_TIMEOUT_MS = 8000;
+
+function identityChannelDir(tokenPath) {
+  return path.join(path.dirname(tokenPath), 'mcp-identity');
+}
+
+function identityChannelPath({ tokenPath, session }) {
+  return path.join(identityChannelDir(tokenPath), `${session}.json`);
+}
+
+function readIdentityChannel(filePath) {
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch (_) { return null; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const { cellId, proof, expiresAt } = raw;
+  if (typeof cellId !== 'string' || !cellId || !proof || typeof proof !== 'object'
+    || Array.isArray(proof) || !Number.isSafeInteger(expiresAt)) return null;
+  return { cellId, proof, expiresAt };
+}
+
+function persistIdentityChannel({ tokenPath, session, cellId, proof, expiresAt }) {
+  if (!tokenPath || !session || cellIdFromTmuxSession(session) !== cellId) return false;
+  const dir = identityChannelDir(tokenPath);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const filePath = identityChannelPath({ tokenPath, session });
+  fs.writeFileSync(filePath, `${JSON.stringify({ cellId, proof, expiresAt })}\n`, { mode: 0o600 });
+  return true;
+}
+
+function sharedContextFromIntrospection(out, now) {
+  const issuedAt = Number.isSafeInteger(Number(out.issuedAt)) ? Number(out.issuedAt) : now();
+  const incarnationId = typeof out.incarnationId === 'string' ? out.incarnationId : '';
+  const tmuxSession = typeof out.tmuxSession === 'string' && out.tmuxSession
+    ? out.tmuxSession : tmuxSessionForCell(out.cellId);
+  return {
+    version: '1',
+    kind: 'mcp-v1',
+    verified: true,
+    mode: 'shared',
+    bindingId: `${out.cellId}:${incarnationId}`,
+    ownerInstanceId: out.instanceId,
+    cellId: out.cellId,
+    tmuxSession,
+    connectionId: `${out.cellId}:${incarnationId}`,
+    threadId: incarnationId,
+    origin: 'daemon',
+    audience: 'nexuscrew-mcp',
+    scopes: ['mcp:tools/call'],
+    issuedAt,
+    notBefore: issuedAt,
+    expiresAt: out.expiresAt,
+  };
+}
+
+function createMcpIdentityProvider({ config, env = process.env, fetchImpl = fetch, now = Date.now } = {}) {
+  const cfg = config || require('../config.js').loadConfig();
+  const tokenPath = cfg && cfg.tokenPath;
+  const port = cfg && cfg.port;
+  const session = env && env.NEXUSCREW_MCP_SESSION;
+  if (!tokenPath || !Number.isSafeInteger(port) || !session) return null;
+  const channelPath = identityChannelPath({ tokenPath, session });
+  if (!readIdentityChannel(channelPath)) return null;
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  async function introspectChannel() {
+    const channel = readIdentityChannel(channelPath);
+    if (!channel) return { verified: false, mode: 'shared' };
+    let response;
+    try {
+      const token = readTokenSafe(tokenPath);
+      response = await fetchImpl(`${baseUrl}/api/lease/introspect`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+        body: JSON.stringify({ proof: channel.proof }),
+        signal: AbortSignal.timeout(INTROSPECT_TIMEOUT_MS),
+      });
+    } catch (_) {
+      throw identityContextError(IDENTITY_CONTEXT_AUTHORITY_UNAVAILABLE,
+        'NEXUSCREW_MCP_IDENTITY_AUTHORITY_UNAVAILABLE: authority non raggiungibile');
+    }
+    if (response.status >= 500) {
+      throw identityContextError(IDENTITY_CONTEXT_AUTHORITY_UNAVAILABLE,
+        'NEXUSCREW_MCP_IDENTITY_AUTHORITY_UNAVAILABLE: authority non raggiungibile');
+    }
+    if (!response.ok) return { verified: false, mode: 'shared' };
+    const out = await response.json().catch(() => null);
+    if (!out || out.status !== 'live' || out.identityMode !== 'authority'
+      || out.cellId !== channel.cellId || typeof out.instanceId !== 'string' || !out.instanceId
+      || !Number.isSafeInteger(Number(out.expiresAt)) || Number(out.expiresAt) <= now()
+      || typeof out.incarnationId !== 'string' || !out.incarnationId
+      || out.incarnationId !== channel.proof.incarnationId) {
+      return { verified: false, mode: 'shared' };
+    }
+    return { context: sharedContextFromIntrospection({ ...out, expiresAt: Number(out.expiresAt) }, now()), proof: channel.proof };
+  }
+
+  async function provider({ tool } = {}) {
+    void tool; // il canale lease è per-connessione cella, non per-tool
+    const out = await introspectChannel();
+    return out.context ? out.context : out;
+  }
+  provider.currentProof = () => {
+    const channel = readIdentityChannel(channelPath);
+    return channel ? channel.proof : null;
+  };
+  return provider;
+}
+
+module.exports = {
+  createMcpIdentityProvider,
+  persistIdentityChannel,
+  identityChannelPath,
+};

package/lib/mcp/identity-schema.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const { isValidSession } = require('../files/store.js');
+
+const IDENTITY_SCHEMA_VERSION = '1';
+const IDENTITY_KINDS = Object.freeze(new Set(['connection-v1', 'thread-v1', 'mcp-v1']));
+const IDENTITY_ORIGINS = Object.freeze(new Set(['local_tui', 'remote_live', 'daemon']));
+const IDENTITY_CONTEXT_MISSING = 'NEXUSCREW_MCP_IDENTITY_CONTEXT_MISSING';
+const IDENTITY_CONTEXT_UNVERIFIED = 'NEXUSCREW_MCP_IDENTITY_CONTEXT_UNVERIFIED';
+const IDENTITY_CONTEXT_FROM_MISMATCH = 'NEXUSCREW_MCP_IDENTITY_CONTEXT_FROM_MISMATCH';
+const IDENTITY_CONTEXT_AUTHORITY_UNAVAILABLE = 'NEXUSCREW_MCP_IDENTITY_AUTHORITY_UNAVAILABLE';
+
+function identityContextError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function requiredString(value, name, { max = 128 } = {}) {
+  if (typeof value !== 'string' || !value.trim() || (max !== null && value.length > max)) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      `contesto identita online: ${name} non valido`);
+  }
+  return value.trim();
+}
+
+function timestamp(value, name) {
+  const parsed = Number.isSafeInteger(value) && value >= 0
+    ? value
+    : (typeof value === 'string' && value.trim() ? Date.parse(value) : NaN);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      `contesto identita online: ${name} non valido`);
+  }
+  return parsed;
+}
+
+function nonNegativeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      `contesto identita online: ${name} non valido`);
+  }
+  return value;
+}
+
+function normalizeLiveHost(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: liveHost non valido');
+  }
+  const out = {
+    ownerInstanceId: requiredString(raw.ownerInstanceId, 'liveHost.ownerInstanceId'),
+    cellId: requiredString(raw.cellId, 'liveHost.cellId'),
+    tmuxSession: requiredString(raw.tmuxSession, 'liveHost.tmuxSession'),
+    leaseId: requiredString(raw.leaseId, 'liveHost.leaseId'),
+    generation: nonNegativeInteger(raw.generation, 'liveHost.generation'),
+    epoch: nonNegativeInteger(raw.epoch, 'liveHost.epoch'),
+    designation: requiredString(raw.designation, 'liveHost.designation'),
+    pairingSessionId: requiredString(raw.pairingSessionId, 'liveHost.pairingSessionId'),
+  };
+  if (!isValidSession(out.tmuxSession) || out.cellId !== out.tmuxSession.slice(6)) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: liveHost cella/sessione incoerenti');
+  }
+  return Object.freeze(out);
+}
+
+function normalizeScopes(raw) {
+  if (!Array.isArray(raw) || raw.length < 1 || raw.length > 32) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: scopes non validi');
+  }
+  const scopes = raw.map((scope) => requiredString(scope, 'scope', { max: 64 }));
+  if (new Set(scopes).size !== scopes.length) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: scopes duplicati');
+  }
+  return Object.freeze(scopes);
+}
+
+function normalizeIdentityContext(raw, { now = Date.now } = {}) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING, 'contesto identita online assente');
+  }
+  if (raw.verified !== true || raw.mode !== 'shared') {
+    throw identityContextError(IDENTITY_CONTEXT_UNVERIFIED,
+      'contesto identita online non verificato: binding condiviso rifiutato');
+  }
+  if (raw.version !== IDENTITY_SCHEMA_VERSION || !IDENTITY_KINDS.has(raw.kind)) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: versione o kind non validi');
+  }
+  if (!IDENTITY_ORIGINS.has(raw.origin)) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: origin non valida');
+  }
+  const ownerInstanceId = requiredString(raw.ownerInstanceId, 'ownerInstanceId');
+  const cellId = requiredString(raw.cellId, 'cellId');
+  const tmuxSession = requiredString(raw.tmuxSession || raw.session, 'tmuxSession');
+  if (!isValidSession(tmuxSession) || cellId !== tmuxSession.slice(6)) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: cella/sessione incoerenti');
+  }
+  const bindingId = requiredString(raw.bindingId, 'bindingId');
+  const audience = requiredString(raw.audience, 'audience');
+  const connectionId = requiredString(raw.connectionId, 'connectionId');
+  if ((raw.kind === 'thread-v1' || raw.kind === 'mcp-v1')) {
+    requiredString(raw.threadId, 'threadId');
+  }
+  const scopes = normalizeScopes(raw.scopes);
+  const issuedAt = timestamp(raw.issuedAt, 'issuedAt');
+  const notBefore = timestamp(raw.notBefore, 'notBefore');
+  const expiresAt = timestamp(raw.expiresAt, 'expiresAt');
+  const clock = Number(now());
+  if (!Number.isFinite(clock) || notBefore > clock) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online non ancora valido');
+  }
+  if (expiresAt <= clock || expiresAt <= issuedAt || notBefore > expiresAt) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online scaduto o temporalmente incoerente');
+  }
+  const from = { instanceId: ownerInstanceId, cell: cellId, tmuxSession };
+  if (raw.from !== undefined && JSON.stringify(raw.from) !== JSON.stringify(from)) {
+    throw identityContextError(IDENTITY_CONTEXT_FROM_MISMATCH,
+      'contesto identita online: from discordante rifiutato');
+  }
+  const context = {
+    version: IDENTITY_SCHEMA_VERSION,
+    kind: raw.kind,
+    verified: true,
+    mode: 'shared',
+    origin: raw.origin,
+    bindingId,
+    ownerInstanceId,
+    cellId,
+    tmuxSession,
+    from,
+    audience,
+    connectionId,
+    scopes,
+    issuedAt: raw.issuedAt,
+    notBefore: raw.notBefore,
+    expiresAt: raw.expiresAt,
+  };
+  if (raw.threadId !== undefined) context.threadId = requiredString(raw.threadId, 'threadId');
+  // cwd is intentionally not subject to the short identity-field bound: it is
+  // a path claim, while the signed identity fields remain bounded above.
+  if (raw.cwd !== undefined) context.cwd = requiredString(raw.cwd, 'cwd', { max: null });
+  if (raw.liveHost !== undefined) context.liveHost = normalizeLiveHost(raw.liveHost);
+  if (raw.origin === 'remote_live' && !context.liveHost) {
+    throw identityContextError(IDENTITY_CONTEXT_MISSING,
+      'contesto identita online: liveHost obbligatorio per remote_live');
+  }
+  return Object.freeze(context);
+}
+
+module.exports = {
+  IDENTITY_SCHEMA_VERSION,
+  IDENTITY_KINDS,
+  IDENTITY_ORIGINS,
+  IDENTITY_CONTEXT_MISSING,
+  IDENTITY_CONTEXT_UNVERIFIED,
+  IDENTITY_CONTEXT_FROM_MISMATCH,
+  IDENTITY_CONTEXT_AUTHORITY_UNAVAILABLE,
+  identityContextError,
+  normalizeIdentityContext,
+};