@mmmbuto/nexuscrew 0.9.20 → 0.9.21

package/lib/fleet/cell-lease-server.js

@@ -30,6 +30,7 @@
 // Side effect isolati e iniettabili (seams) per testabilita', come altrove nel
 // fleet (cell-exec.js, launch-broker.js). Protocollo sul socket lease:
 // line-oriented JSON, un messaggio per riga.
+//   supervisor -> server: {"type":"generation","generation":..}   (R1)
 //   supervisor -> server: {"type":"refresh"}
 //   supervisor -> server: {"type":"reconnect","generation":..,"proof":{..}}
 //   server     -> supervisor: {"type":"lease","leaseId":..,"proof":{..}}
@@ -42,6 +43,7 @@ const crypto = require('node:crypto');
 const L = require('./cell-lease.js');
 const { runtimeDir, ensureRuntimeDir } = require('./launch-broker.js');
 const { loadOrCreateVerifier, signProof, verifyProof, PROOF_TTL_MS } = require('./lease-verifier.js');
+const { validDaemonChallenge } = require('./lease-client.js');
 
 function sanitizeCell(cellId) {
   return String(cellId).replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64);
@@ -61,6 +63,7 @@ const EPOCH_RE = /^[a-f0-9]{16}$/;
 // ancora scaduto puo' ripresentarsi (la firma e l'expiry restano il gate).
 // Garanzia piu' forte (single-use cross-restart) NON promessa dal contratto.
 const JTI_CAP = 4096;
+const CHALLENGE_FRAME_LIMIT = 8 * 1024;
 
 function createLeaseManager(cfg = {}, seams = {}) {
   const dir = runtimeDir(cfg);
@@ -71,6 +74,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
   const netImpl = seams.net || net;
   const fsImpl = seams.fs || fs;
   const log = typeof cfg.log === 'function' ? cfg.log : () => {};
+  const identityAuthority = cfg.identityAuthority || null;
 
   // cellId -> entry:
   //   { launchEpoch, stablePath, stableServer, lease, socket, graceTimer, graceDeadline, lastCommit }
@@ -261,6 +265,14 @@ function createLeaseManager(cfg = {}, seams = {}) {
     const onLine = (line) => {
       let msg; try { msg = JSON.parse(line); } catch (_) { return; }
       if (!msg || typeof msg !== 'object') return;
+      if (msg.type === 'challengeProof') {
+        handleChallengeProof(cellId, entry, socket, msg);
+        return;
+      }
+      if (msg.type === 'generation') {
+        handleGeneration(cellId, entry, socket, msg);
+        return;
+      }
       if (msg.type === 'refresh') {
         // Heartbeat lato supervisore (R3.2) + IC1 (rev28/rev29): il refresh
         // committa LA deadline D — monotona, ed è l'expiry del proof che sta
@@ -288,6 +300,10 @@ function createLeaseManager(cfg = {}, seams = {}) {
     };
     const onData = (chunk) => {
       buf += chunk.toString();
+      if (Buffer.byteLength(buf, 'utf8') > CHALLENGE_FRAME_LIMIT) {
+        socket.destroy();
+        return;
+      }
       let nl;
       while ((nl = buf.indexOf('\n')) !== -1) { onLine(buf.slice(0, nl)); buf = buf.slice(nl + 1); }
     };
@@ -330,6 +346,105 @@ function createLeaseManager(cfg = {}, seams = {}) {
     try { socket.write(`${JSON.stringify(obj)}\n`); } catch (_) {}
   }
 
+  function validLaunchSubject(subject, cellId, entry) {
+    if (!subject || typeof subject !== 'object' || Array.isArray(subject)) return false;
+    const keys = Object.keys(subject);
+    if (keys.length !== 4
+      || !['ownerInstanceId', 'cellId', 'incarnationId', 'launchEpoch'].every((key) => Object.hasOwn(subject, key))) return false;
+    return ['ownerInstanceId', 'cellId', 'incarnationId', 'launchEpoch']
+      .every((key) => typeof subject[key] === 'string' && subject[key].length > 0 && subject[key].length <= 128)
+      && subject.cellId === cellId && subject.launchEpoch === entry.launchEpoch;
+  }
+
+  function setLaunchSubject(cellId, subject) {
+    if (!validCellId(cellId)) return false;
+    const entry = cells.get(cellId);
+    if (!entry || entry.subject || entry.lease || entry.socket) return false;
+    if (!validLaunchSubject(subject, cellId, entry)) return false;
+    entry.subject = { ...subject };
+    return true;
+  }
+
+  function identityRelayReason(reason) {
+    if (reason === 'expired') return 'expired';
+    if (reason === 'replay' || reason === 'challenge-replay') return 'replay';
+    if (['audience', 'daemonBootId', 'connectionId'].includes(reason)) return 'audience';
+    return 'identity-unverified';
+  }
+
+  function validChallengeProofRequest(msg) {
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return false;
+    const keys = Object.keys(msg);
+    if (keys.length !== 4 || !['type', 'requestId', 'generation', 'challenge'].every((key) => Object.hasOwn(msg, key))) return false;
+    const requestIdOk = (typeof msg.requestId === 'string' && msg.requestId.length > 0 && msg.requestId.length <= 128)
+      || Number.isSafeInteger(msg.requestId);
+    return msg.type === 'challengeProof' && requestIdOk
+      && Number.isSafeInteger(msg.generation) && msg.generation >= 0
+      && validDaemonChallenge(msg.challenge);
+  }
+
+  // R1: transizione di generazione della connessione viva. Solo stessa
+  // generazione (idempotente) o +1 (restart del supervisore); generazioni
+  // arbitrarie restano deny -> il relay fail-closed (revoked) non cambia.
+  function validGenerationRequest(msg) {
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return false;
+    const keys = Object.keys(msg);
+    return keys.length === 2 && msg.type === 'generation'
+      && Number.isSafeInteger(msg.generation) && msg.generation >= 0;
+  }
+
+  function handleGeneration(cellId, entry, socket, msg) {
+    if (!validGenerationRequest(msg)) {
+      writeSafe(socket, { type: 'generationDeny', generation: msg && Number.isSafeInteger(msg.generation) ? msg.generation : -1 });
+      return;
+    }
+    const current = cells.get(cellId);
+    if (!current || current !== entry || entry.socket !== socket
+      || !entry.lease || !L.isLive(entry.lease)) {
+      writeSafe(socket, { type: 'generationDeny', generation: msg.generation });
+      return;
+    }
+    if (msg.generation !== entry.lease.generation
+      && msg.generation !== entry.lease.generation + 1) {
+      writeSafe(socket, { type: 'generationDeny', generation: msg.generation });
+      return;
+    }
+    // R1b: l'avanzamento PRIMA dell'ACK e' voluto (at-least-once): se l'ACK
+    // si perde, il client ritenta con la STESSA generazione e qui e'
+    // idempotente (== corrente -> ACK). L'ordine inverso lascerebbe il server
+    // stantio con un client che crede di aver transizionato.
+    entry.lease.generation = msg.generation;
+    writeSafe(socket, { type: 'generationAck', generation: msg.generation });
+  }
+
+  function handleChallengeProof(cellId, entry, socket, msg) {
+    if (!validChallengeProofRequest(msg)) {
+      writeSafe(socket, { type: 'challengeProofResult', requestId: msg && msg.requestId, ok: false, reason: 'identity-unverified' });
+      return;
+    }
+    const current = cells.get(cellId);
+    if (!current || current !== entry || entry.socket !== socket
+      || !entry.lease || !L.isLive(entry.lease)
+      || entry.lease.generation !== msg.generation || !entry.subject) {
+      writeSafe(socket, { type: 'challengeProofResult', requestId: msg.requestId, ok: false, reason: 'revoked' });
+      return;
+    }
+    if (!identityAuthority || typeof identityAuthority.issueConnectionProof !== 'function') {
+      writeSafe(socket, { type: 'challengeProofResult', requestId: msg.requestId, ok: false, reason: 'authority-unavailable' });
+      return;
+    }
+    const issued = identityAuthority.issueConnectionProof({
+      subject: { ...entry.subject },
+      challenge: msg.challenge,
+    });
+    if (!issued || issued.ok !== true) {
+      const reason = identityRelayReason(issued && issued.reason);
+      writeSafe(socket, { type: 'challengeProofResult', requestId: msg.requestId, ok: false, reason });
+      return;
+    }
+    writeSafe(socket, { type: 'challengeProofResult', requestId: msg.requestId, ok: true, proof: issued.proof });
+  }
+
   function onStableConnection(cellId, socket) {
     // Endpoint stabile: reconnect (R3.3.2-4). Legge identita' + proof, valida.
     let buf = '';
@@ -509,7 +624,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
       launchEpoch: existing.launchEpoch,
       stablePath: existing.stablePath, stableServer: existing.stableServer,
       lease: existing.lease, socket: existing.socket, graceTimer: existing.graceTimer,
-      graceDeadline: existing.graceDeadline,
+      graceDeadline: existing.graceDeadline, subject: existing.subject,
     } : null;
     // openEndpoint puo' aver creato un nuovo stableServer se l'entry non ne aveva uno.
     const serverBeforeOpen = existing ? existing.stableServer : null;
@@ -550,6 +665,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
         entry.socket = existingSnapshot.socket;
         entry.graceTimer = existingSnapshot.graceTimer;
         entry.graceDeadline = existingSnapshot.graceDeadline;
+        entry.subject = existingSnapshot.subject;
         if (entry.stableServer && entry.stableServer !== serverBeforeOpen) {
           try { entry.stableServer.close(); } catch (_) {}
           entry.stableServer = serverBeforeOpen;
@@ -692,21 +808,32 @@ function createLeaseManager(cfg = {}, seams = {}) {
     }, { now });
   }
 
-  function childRegister(cellId) {
+  function childRegister(cellId, { authority = false } = {}) {
     if (!validCellId(cellId)) return { status: 'denied', reason: 'cellId' };
     if (!cells.has(cellId)) {
       // La cella non e' (ancora) tracciata dal lease del supervisore: il join e'
       // pendente. Solo register puo' rispondere cosi' (B5).
       return { status: 'pending', retryAfterMs: L.REFRESH_MS };
     }
+    const launchSubject = cells.get(cellId) && cells.get(cellId).subject;
     const reg = {
-      incarnationId: crypto.randomBytes(8).toString('hex'), // B2: per-registration
+      // In authority mode the launch subject is the single source of this value;
+      // legacy registrations keep their per-registration incarnation.
+      incarnationId: (authority === true && launchSubject && launchSubject.incarnationId)
+        || crypto.randomBytes(8).toString('hex'),
       createdAt: now(),
       lastAt: now(),
       recoveryAttempts: 0,
+      // La provenienza della registration decide se il proof child puo mai
+      // autorizzare il percorso identity shared: una registration nata dal
+      // percorso legacy resta legacy anche con firma valida.
+      authority: authority === true,
     };
     childRegs.set(cellId, reg);
-    return { status: 'registered', incarnationId: reg.incarnationId, proof: issueChildProof(cellId, reg) };
+    return {
+      status: 'registered', incarnationId: reg.incarnationId, proof: issueChildProof(cellId, reg),
+      ...(reg.authority ? { identityMode: 'authority' } : {}),
+    };
   }
 
   function childRefresh(cellId, proof) {
@@ -719,7 +846,35 @@ function createLeaseManager(cfg = {}, seams = {}) {
     if (!out.ok) return { status: 'denied', reason: out.reason };
     if (now() >= reg.lastAt + CHILD_REG_WINDOW_MS) return { status: 'expired' };
     reg.lastAt = now();
-    return { status: 'live', incarnationId: reg.incarnationId, proof: issueChildProof(cellId, reg) };
+    return {
+      status: 'live', incarnationId: reg.incarnationId, proof: issueChildProof(cellId, reg),
+      ...(reg.authority ? { identityMode: 'authority' } : {}),
+    };
+  }
+
+  // Introspezione READ-ONLY del proof child: verifica firma, expiry e stato
+  // della registration SENZA consumare nulla e senza toccare lastAt. Serve al
+  // bridge MCP per risolvere il contesto shared a ogni tools/call; un proof
+  // consumato qui resterebbe presentabile (e viceversa), perche questo gate
+  // non e' l'authorizer one-shot ma la consulta dello stato vivo.
+  function childIntrospect(proof) {
+    const out = verifyProof(liveKeys(), proof, { now, expect: { kind: 'child' } });
+    if (!out.ok) {
+      // Stessa semantica di refresh: un proof scaduto e' «expired», non un deny.
+      return out.reason === 'expired' ? { status: 'expired' } : { status: 'denied', reason: out.reason };
+    }
+    const cellId = proof && proof.cellId;
+    const reg = childRegs.get(cellId);
+    if (!reg) return { status: 'denied', reason: 'no-registration' };
+    if (reg.incarnationId !== (proof && proof.incarnationId)) {
+      return { status: 'denied', reason: 'incarnation' };
+    }
+    if (reg.authority !== true) return { status: 'denied', reason: 'legacy-registration' };
+    if (now() >= reg.lastAt + CHILD_REG_WINDOW_MS) return { status: 'expired' };
+    return {
+      status: 'live', cellId, incarnationId: reg.incarnationId,
+      issuedAt: proof.issuedAt, expiresAt: proof.expiresAt, identityMode: 'authority',
+    };
   }
 
   function childRecovery(cellId, proof) {
@@ -774,7 +929,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
 
   return {
     boot, track, attachInitial, loadPersisted, status, close, _cells: cells,
-    childRegister, childRefresh, childRecovery,
+    setLaunchSubject, childRegister, childRefresh, childRecovery, childIntrospect,
   };
 }
 

package/lib/fleet/identity-authority.js

@@ -0,0 +1,367 @@
+'use strict';
+
+// Server-only authority for the identity.v1 launch handshake.  The daemon may
+// register a challenge and the TUI may redeem a one-shot launch grant, but the
+// HMAC key never leaves this module.  This is deliberately separate from the
+// Live lease proof: a lease says that a cell is alive, while this proof binds a
+// particular daemon connection to an audience and a challenge.
+
+const crypto = require('node:crypto');
+const os = require('node:os');
+const path = require('node:path');
+const { loadOrCreateVerifier } = require('./lease-verifier.js');
+
+const CHALLENGE_TTL_MS = 15_000;
+const GRANT_TTL_MS = 60_000;
+const NONCE_BYTES = 32;
+const DEFAULT_REPLAY_LIMIT = 4096;
+const DEFAULT_CHALLENGE_LIMIT = 4096;
+const DEFAULT_REVOKE_LIMIT = 4096;
+
+const GRANT_FIELDS = Object.freeze([
+  'kind', 'ownerInstanceId', 'cellId', 'audience', 'incarnationId',
+  'launchEpoch', 'daemonBootId', 'connectionId', 'challenge', 'nonce',
+  'jti', 'issuedAt', 'expiresAt',
+]);
+const PROOF_FIELDS = Object.freeze([
+  ...GRANT_FIELDS.slice(0, 9), 'nonce', 'parentJti', 'jti', 'issuedAt', 'expiresAt', 'generation',
+]);
+
+function nonEmpty(value) { return typeof value === 'string' && value.length > 0; }
+
+function present(value) {
+  return value !== undefined && value !== null && String(value).length > 0;
+}
+
+function hexNonce(randomBytes) {
+  return randomBytes(NONCE_BYTES).toString('hex');
+}
+
+function canonical(fields, claims) {
+  const parts = [];
+  for (const field of fields) {
+    const value = claims[field];
+    if (value === undefined || value === null || String(value).length === 0) {
+      throw new Error(`claim mancante: ${field}`);
+    }
+    const bytes = Buffer.from(String(value), 'utf8');
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(bytes.length, 0);
+    parts.push(length, bytes);
+  }
+  return Buffer.concat(parts);
+}
+
+function sign(verifier, fields, claims) {
+  const proof = crypto.createHmac('sha256', verifier.secret)
+    .update(canonical(fields, claims)).digest('hex');
+  return { ...claims, proof };
+}
+
+function safeEqual(left, right) {
+  if (!nonEmpty(left) || !nonEmpty(right)) return false;
+  const a = Buffer.from(left, 'utf8');
+  const b = Buffer.from(right, 'utf8');
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+function verify(verifier, fields, candidate, { now, expected = {} } = {}) {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    return { ok: false, reason: 'malformed' };
+  }
+  for (const field of fields) if (!present(candidate[field])) return { ok: false, reason: 'malformed' };
+  if (!/^[a-f0-9]{64}$/.test(candidate.proof)) return { ok: false, reason: 'malformed' };
+  const issuedAt = Number(candidate.issuedAt);
+  const expiresAt = Number(candidate.expiresAt);
+  if (!Number.isSafeInteger(issuedAt) || !Number.isSafeInteger(expiresAt) || expiresAt <= issuedAt) {
+    return { ok: false, reason: 'malformed' };
+  }
+  if (Number(now()) >= expiresAt) return { ok: false, reason: 'expired' };
+  for (const [field, value] of Object.entries(expected)) {
+    if (value !== undefined && candidate[field] !== value) return { ok: false, reason: field };
+  }
+  const expectedProof = crypto.createHmac('sha256', verifier.secret)
+    .update(canonical(fields, candidate)).digest('hex');
+  if (!safeEqual(expectedProof, candidate.proof)) return { ok: false, reason: 'bad-proof' };
+  return { ok: true, claims: { ...candidate } };
+}
+
+function createIdentityAuthority({
+  dir = path.join(os.homedir(), '.nexuscrew', 'identity-authority'),
+  fsImpl,
+  serviceCredential,
+  daemonCredential,
+  launcherCredential,
+  subjectResolver = () => true,
+  now = Date.now,
+  randomBytes = crypto.randomBytes,
+  maxReplayEntries = DEFAULT_REPLAY_LIMIT,
+  maxChallenges = DEFAULT_CHALLENGE_LIMIT,
+  maxRevokeEntries = DEFAULT_REVOKE_LIMIT,
+  log = () => {},
+} = {}) {
+  const legacyCredential = nonEmpty(serviceCredential) ? serviceCredential : null;
+  const daemonSecret = daemonCredential || legacyCredential;
+  const launcherSecret = launcherCredential || legacyCredential;
+  if (!nonEmpty(daemonSecret) || !nonEmpty(launcherSecret)) {
+    throw new Error('identity authority: daemon e launcher credential obbligatorie');
+  }
+  if ((daemonCredential || launcherCredential) && safeEqual(daemonSecret, launcherSecret)) {
+    throw new Error('identity authority: daemon e launcher credential devono essere distinte');
+  }
+  if (typeof subjectResolver !== 'function') throw new Error('identity authority: subject resolver non valido');
+  if (!Number.isSafeInteger(maxReplayEntries) || maxReplayEntries < 1) {
+    throw new Error('identity authority: replay limit non valido');
+  }
+  if (!Number.isSafeInteger(maxChallenges) || maxChallenges < 1) {
+    throw new Error('identity authority: challenge limit non valido');
+  }
+  if (!Number.isSafeInteger(maxRevokeEntries) || maxRevokeEntries < 1) {
+    throw new Error('identity authority: revoke limit non valido');
+  }
+  // `fsImpl` is injectable only for tests; production always uses the real
+  // filesystem and the dedicated 0600 key managed by lease-verifier.js.
+  const verifier = loadOrCreateVerifier({ dir, ...(fsImpl ? { fsImpl } : {}), log });
+  // Fresh per authority incarnation and never persisted: a restart of the
+  // authority changes it, so every proof issued before the restart fails
+  // closed instead of surviving with the persisted HMAC key.
+  const generation = hexNonce(randomBytes);
+  const challenges = new Map();
+  // Bounded stores: every entry carries its own expiry, saturated stores
+  // reject instead of evicting valid entries, and only expired entries are
+  // collected on the next operation that touches the store.
+  const replay = new Map();
+  const revoked = new Map();
+
+  function sweepExpired() {
+    const tick = Number(now());
+    for (const [challenge, record] of challenges) {
+      if (tick >= record.expiresAt) challenges.delete(challenge);
+    }
+    for (const [value, expiresAt] of replay) {
+      if (tick >= expiresAt) replay.delete(value);
+    }
+    for (const [jti, expiresAt] of revoked) {
+      if (tick >= expiresAt) revoked.delete(jti);
+    }
+  }
+
+  function credentialMatches(candidate, expected) { return safeEqual(expected, candidate); }
+
+  function validConnection(args) {
+    return ['audience', 'daemonBootId', 'connectionId']
+      .every((field) => nonEmpty(args && args[field]));
+  }
+
+  function validSubject(args) {
+    return ['ownerInstanceId', 'cellId', 'incarnationId', 'launchEpoch']
+      .every((field) => nonEmpty(args && args[field]));
+  }
+
+  const strictCredentials = !!(daemonCredential || launcherCredential);
+
+  function reserveReplay(value, expiresAt) {
+    sweepExpired();
+    if (replay.has(value)) return { ok: false, reason: 'replay' };
+    if (replay.size >= maxReplayEntries) return { ok: false, reason: 'replay-store-full' };
+    replay.set(value, expiresAt);
+    return { ok: true };
+  }
+
+  function registerDaemonChallenge(args = {}) {
+    const credential = args.daemonCredential || args.serviceCredential;
+    if (!credentialMatches(credential, daemonSecret)) {
+      return { ok: false, reason: strictCredentials ? 'daemon-credential' : 'service-credential' };
+    }
+    if (!validConnection(args)) return { ok: false, reason: 'claims' };
+    sweepExpired();
+    if (challenges.has(args.challenge)) return { ok: false, reason: 'challenge-replay' };
+    if (challenges.size >= maxChallenges) return { ok: false, reason: 'challenge-store-full' };
+    const issuedAt = Number(now());
+    const challenge = (typeof args.challenge === 'string' && args.challenge) || hexNonce(randomBytes);
+    const expiresAt = Number.isSafeInteger(Number(args.expiresAt))
+      ? Number(args.expiresAt)
+      : (issuedAt + CHALLENGE_TTL_MS);
+    const record = {
+      challenge,
+      audience: args.audience,
+      daemonBootId: args.daemonBootId,
+      connectionId: args.connectionId,
+      issuedAt,
+      expiresAt,
+      used: false,
+    };
+    challenges.set(challenge, record);
+    return { ok: true, challenge, issuedAt, expiresAt: record.expiresAt };
+  }
+
+  function issueLaunchGrant(args = {}) {
+    const credential = args.launcherCredential || args.serviceCredential || args.daemonCredential;
+    if (!credentialMatches(credential, launcherSecret)
+      || (strictCredentials && !args.launcherCredential)) return { ok: false, reason: 'launcher-credential' };
+    const record = challenges.get(args.challenge);
+    if (!record) return { ok: false, reason: 'challenge' };
+    if (record.used) return { ok: false, reason: 'challenge-replay' };
+    if (Number(now()) >= record.expiresAt) return { ok: false, reason: 'challenge' };
+    const subject = args.subject || (strictCredentials ? null : args);
+    if (!validSubject(subject) || (strictCredentials && subjectResolver(subject) !== true)) {
+      return { ok: false, reason: 'subject' };
+    }
+    if (!validConnection(record)) return { ok: false, reason: 'claims' };
+    for (const field of ['audience', 'daemonBootId', 'connectionId']) {
+      if (args[field] !== undefined && args[field] !== record[field]) return { ok: false, reason: field };
+    }
+    const issuedAt = Number(now());
+    const claims = {
+      kind: 'launch-grant', ...Object.fromEntries([
+        'ownerInstanceId', 'cellId', 'incarnationId', 'launchEpoch',
+      ].map((field) => [field, subject[field]])
+        .concat(['audience', 'daemonBootId', 'connectionId']
+          .map((field) => [field, record[field]]))),
+      challenge: record.challenge,
+      nonce: (typeof args.nonce === 'string' && args.nonce) || hexNonce(randomBytes),
+      jti: hexNonce(randomBytes),
+      issuedAt,
+      expiresAt: Math.min(record.expiresAt, issuedAt + GRANT_TTL_MS),
+    };
+    if (claims.expiresAt <= issuedAt) return { ok: false, reason: 'challenge' };
+    return { ok: true, grant: sign(verifier, GRANT_FIELDS, claims) };
+  }
+
+  function issueChallengeProof({ launchGrant, challenge, nonce: candidateNonce, expiresAt: candidateExpiresAt } = {}) {
+    const checked = verify(verifier, GRANT_FIELDS, launchGrant, { now, expected: { kind: 'launch-grant', challenge } });
+    if (!checked.ok) return checked;
+    const record = challenges.get(challenge);
+    if (!record) return { ok: false, reason: 'challenge' };
+    if (record.used) return { ok: false, reason: 'challenge-replay' };
+    if (Number(now()) >= record.expiresAt) return { ok: false, reason: 'challenge' };
+    for (const field of ['audience', 'daemonBootId', 'connectionId']) {
+      if (checked.claims[field] !== record[field]) return { ok: false, reason: field };
+    }
+    if (candidateNonce !== undefined && candidateNonce !== record.challenge) {
+      return { ok: false, reason: 'nonce' };
+    }
+    const reserved = reserveReplay(checked.claims.nonce, Number(checked.claims.expiresAt));
+    if (!reserved.ok) return { ok: false, reason: reserved.reason };
+    record.used = true;
+    const issuedAt = Number(now());
+    const nonce = record.challenge;
+    const expiresAt = Number.isSafeInteger(Number(candidateExpiresAt))
+      ? Math.min(Number(candidateExpiresAt), Number(checked.claims.expiresAt))
+      : Math.min(Number(checked.claims.expiresAt), issuedAt + GRANT_TTL_MS);
+    if (expiresAt <= issuedAt) return { ok: false, reason: 'expired' };
+    const claims = {
+      kind: 'identity-proof', ...Object.fromEntries([
+        'ownerInstanceId', 'cellId', 'audience', 'incarnationId',
+        'launchEpoch', 'daemonBootId', 'connectionId', 'challenge',
+      ].map((field) => [field, checked.claims[field]])),
+      nonce,
+      parentJti: checked.claims.jti,
+      jti: hexNonce(randomBytes),
+      issuedAt,
+      expiresAt,
+      generation,
+    };
+    return { ok: true, proof: sign(verifier, PROOF_FIELDS, claims) };
+  }
+
+  function issueConnectionProof({
+    subject,
+    challenge,
+    daemonCredential,
+    launcherCredential,
+    serviceCredential,
+    expiresAt: externalExpiresAt,
+  } = {}) {
+    if (!challenge || typeof challenge !== 'object') return { ok: false, reason: 'challenge' };
+    if (!nonEmpty(challenge.nonce)) return { ok: false, reason: 'challenge' };
+    if (!Number.isSafeInteger(challenge.expiresAt)) return { ok: false, reason: 'challenge' };
+    if (externalExpiresAt !== undefined && !Number.isSafeInteger(externalExpiresAt)) {
+      return { ok: false, reason: 'challenge' };
+    }
+    const currentTick = Number(now());
+    // R2: il TTL della challenge e' SERVER-OWNED (15s dall'orologio
+    // dell'authority), non del chiamante: oltre il cap viene capito, e una
+    // challenge con issuedAt nel futuro e' rifiutata (documentato in referto).
+    if (Number.isSafeInteger(challenge.issuedAt) && challenge.issuedAt > currentTick) {
+      return { ok: false, reason: 'challenge' };
+    }
+    const effectiveExpiresAt = externalExpiresAt === undefined
+      ? Math.min(challenge.expiresAt, currentTick + CHALLENGE_TTL_MS)
+      : Math.min(challenge.expiresAt, currentTick + CHALLENGE_TTL_MS, externalExpiresAt);
+    if (currentTick >= effectiveExpiresAt) return { ok: false, reason: 'expired' };
+    const dCred = daemonCredential || serviceCredential || daemonSecret;
+    const lCred = launcherCredential || serviceCredential || launcherSecret;
+    const challengeKey = challenge.nonce;
+    const reg = registerDaemonChallenge({
+      daemonCredential: dCred,
+      audience: challenge.audience,
+      daemonBootId: challenge.daemonBootId,
+      connectionId: challenge.connectionId,
+      challenge: challengeKey,
+      expiresAt: effectiveExpiresAt,
+    });
+    if (!reg.ok) return reg;
+    const grant = issueLaunchGrant({
+      launcherCredential: lCred,
+      challenge: challengeKey,
+      subject,
+      audience: challenge.audience,
+      daemonBootId: challenge.daemonBootId,
+      connectionId: challenge.connectionId,
+    });
+    if (!grant.ok) return grant;
+    const proof = issueChallengeProof({
+      launchGrant: grant.grant,
+      challenge: challengeKey,
+      nonce: challenge.nonce,
+      expiresAt: effectiveExpiresAt,
+    });
+    return proof;
+  }
+
+  function verifyChallengeProof(proof, expected = {}) {
+    const checked = verify(verifier, PROOF_FIELDS, proof, { now, expected: { kind: 'identity-proof', ...expected } });
+    if (!checked.ok) return checked;
+    if (!safeEqual(checked.claims.generation, generation)) return { ok: false, reason: 'generation' };
+    if (revoked.has(checked.claims.jti) || revoked.has(checked.claims.parentJti)) {
+      return { ok: false, reason: 'revoked' };
+    }
+    const reserved = reserveReplay(checked.claims.nonce, Number(checked.claims.expiresAt));
+    if (!reserved.ok) return { ok: false, reason: reserved.reason };
+    return checked;
+  }
+
+  function revoke(jti, expiresAt) {
+    if (!nonEmpty(jti)) return false;
+    sweepExpired();
+    const tick = Number(now());
+    // Without an explicit horizon a revocation covers the widest proof it
+    // can still affect, then it expires like the proofs it invalidates.
+    const horizon = Number.isSafeInteger(expiresAt)
+      ? expiresAt
+      : tick + CHALLENGE_TTL_MS + GRANT_TTL_MS;
+    if (tick >= horizon) return false;
+    if (!revoked.has(jti) && revoked.size >= maxRevokeEntries) return false;
+    revoked.set(jti, Math.max(horizon, revoked.get(jti) || 0));
+    return true;
+  }
+
+  return {
+    registerDaemonChallenge,
+    issueLaunchGrant,
+    issueChallengeProof,
+    issueConnectionProof,
+    verifyChallengeProof,
+    reserveReplay,
+    revoke,
+    constants: Object.freeze({ CHALLENGE_TTL_MS, GRANT_TTL_MS, NONCE_BYTES }),
+  };
+}
+
+module.exports = {
+  createIdentityAuthority,
+  CHALLENGE_TTL_MS,
+  GRANT_TTL_MS,
+  NONCE_BYTES,
+};