fuli-context 0.12.0 → 0.12.2

package/src/agent-peer/coordinator-service.js

@@ -0,0 +1,258 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+
+import { certificateFingerprint, verifyDeviceSignature } from './device-identity.js';
+import { isAuthorityKey } from './origin-proof.js';
+import {
+  canonicalJson, encodeInvitation, PEER_LIMITS, PeerError, pemToDer, publicDirectoryEntry,
+  RESULT_OUTCOMES, sha256Hex, TERMINAL_STATUSES, validateAssertion,
+} from './protocol.js';
+
+const ONLINE_MS = 90_000;
+const PAIRING_FAILURE_WINDOW_MS = 10 * 60_000;
+const PAIRING_FAILURE_LIMIT = 10;
+
+// Routes messages between paired devices. It never executes anything: each
+// receiving device re-checks its own shares and identity authority.
+export function createCoordinatorService({ store, identity, authority, name, clock = Date.now,
+  randomCode = () => randomBytes(32).toString('base64url'), idFactory = randomUUID, onTrustChange = () => {} }) {
+  const iso = (offsetMs = 0) => new Date(clock() + offsetMs).toISOString();
+  const pairingFailures = [];
+  if (!isAuthorityKey(authority)) throw new PeerError('authority_unavailable', 'The coordinator needs its local origin authority', 500);
+  store.upsertNode({ id: identity.fingerprint, name, certPem: identity.certPem, authority, at: iso() });
+
+  function createInvitation({ url }) {
+    const code = randomCode();
+    const expiresAt = iso(PEER_LIMITS.invitationSeconds * 1000);
+    store.createInvitation({ codeHash: sha256Hex(code), at: iso(), expiresAt });
+    return { invitation: encodeInvitation({ url, fingerprint: identity.fingerprint, code, expiresAt, name, authority,
+      certificate: pemToDer(identity.certPem).toString('base64') }), fingerprint: identity.fingerprint, expiresAt };
+  }
+
+  function pair({ code, certPem, name: deviceName, authority: deviceAuthority }) {
+    const now = clock();
+    while (pairingFailures.length && pairingFailures[0] < now - PAIRING_FAILURE_WINDOW_MS) pairingFailures.shift();
+    if (pairingFailures.length >= PAIRING_FAILURE_LIMIT) throw new PeerError('pairing_rate_limited', 'Too many failed pairing attempts; try again later', 429);
+    const fingerprint = certificateFingerprint(certPem);
+    if (fingerprint === identity.fingerprint) throw new PeerError('invalid_pairing', 'A device cannot pair with itself', 400);
+    const codeHash = typeof code === 'string' && code.length <= 128 ? sha256Hex(code) : null;
+    const invitation = codeHash ? store.invitation(codeHash) : null;
+    const usable = invitation && !invitation.used_at && Date.parse(invitation.expires_at) > now;
+    if (!usable) {
+      pairingFailures.push(now);
+      throw new PeerError('invalid_pairing_code', 'This invitation is invalid, expired or already used', 403);
+    }
+    if (!isAuthorityKey(deviceAuthority)) throw new PeerError('invalid_pairing', 'The device did not present its origin authority', 400);
+    const label = cleanName(deviceName) || `FULI device ${fingerprint.slice(0, 8)}`;
+    store.transaction(() => {
+      if (!store.useInvitation(codeHash, fingerprint, iso())) throw new PeerError('invalid_pairing_code', 'This invitation was already used', 403);
+      store.upsertNode({ id: fingerprint, name: label, certPem,
+        authority: { keyId: deviceAuthority.keyId, publicKey: deviceAuthority.publicKey }, at: iso() });
+    });
+    onTrustChange();
+    return { nodeId: fingerprint, coordinatorNodeId: identity.fingerprint, coordinatorName: name };
+  }
+
+  function authenticate(nodeId) {
+    const node = store.node(nodeId);
+    if (!node || node.status !== 'active') throw new PeerError('device_not_trusted', 'This device is not paired or was revoked', 403);
+    store.touchNode(nodeId, iso());
+    return node;
+  }
+
+  function publishDirectory(nodeId, { agents }) {
+    if (!Array.isArray(agents) || agents.length > PEER_LIMITS.directoryAgents) throw new PeerError('invalid_directory', 'Invalid shared Agent list');
+    const entries = agents.map(publicDirectoryEntry);
+    store.setDirectory(nodeId, entries);
+    return { published: entries.length };
+  }
+
+  function directory(nodeId) {
+    const now = clock();
+    return { devices: store.nodes().filter((node) => node.status === 'active' && node.id !== nodeId).map((node) => ({
+      nodeId: node.id, name: node.name,
+      online: Boolean(node.last_seen_at) && now - Date.parse(node.last_seen_at) < ONLINE_MS,
+      agents: JSON.parse(node.directory_json),
+    })) };
+  }
+
+  function submit(nodeId, { assertion, signature }) {
+    validateAssertion(assertion, { now: clock() });
+    if (assertion.from.node !== nodeId) throw new PeerError('sender_mismatch', 'The message sender is not this device', 403);
+    const sender = store.node(nodeId);
+    if (!verifyDeviceSignature(sender.cert_pem, assertion, signature)) throw new PeerError('invalid_signature', 'The message signature is invalid', 403);
+    const target = store.node(assertion.to.node);
+    if (!target || target.status !== 'active') throw new PeerError('device_unavailable', 'The receiving device is not paired', 404);
+    const shared = JSON.parse(target.directory_json)
+      .some((entry) => entry.bindingId === assertion.to.bindingId && entry.agentId === assertion.to.agentId);
+    if (!shared) throw new PeerError('agent_not_shared', 'That Agent is not shared by the receiving device', 404);
+    const assertionJson = canonicalJson(assertion);
+    return store.transaction(() => {
+      const key = messageKey(nodeId, assertion.messageId);
+      const existing = store.message(key);
+      if (existing) {
+        if (existing.assertion_json !== assertionJson) {
+          throw new PeerError('duplicate_message', 'A different message already uses this ID', 409);
+        }
+        return statusView(existing);
+      }
+      if (store.queuedCount(target.id) >= PEER_LIMITS.queuePerNode) throw new PeerError('queue_full', 'The receiving device has too many waiting messages', 429);
+      store.insertMessage({ id: key, senderNode: nodeId, targetNode: target.id,
+        bindingId: assertion.to.bindingId, assertionJson, signature, expiresAt: assertion.expiresAt, at: iso() });
+      return statusView(store.message(key));
+    });
+  }
+
+  function claim(nodeId) {
+    return store.transaction(() => {
+      const next = store.nextQueued(nodeId, iso());
+      if (!next) return null;
+      const attemptId = idFactory();
+      // A short acceptance window: the runner may only start after its acceptance is recorded.
+      store.updateMessage(next.id, { status: 'claimed', attempt_id: attemptId, accepted_attempt: null,
+        start_attempts: next.start_attempts + 1, lease_expires_at: iso(PEER_LIMITS.acceptSeconds * 1000) }, iso(), 'claimed', attemptId);
+      const sender = store.node(next.sender_node);
+      return { messageId: next.id, attemptId, leaseSeconds: PEER_LIMITS.leaseSeconds,
+        assertion: JSON.parse(next.assertion_json), signature: next.signature,
+        sender: { nodeId: sender.id, name: sender.name, certPem: sender.cert_pem,
+          authority: sender.authority_json ? JSON.parse(sender.authority_json) : null } };
+    });
+  }
+
+  function currentAttempt(nodeId, messageId, attemptId) {
+    const message = store.message(messageId);
+    if (!message || message.target_node !== nodeId) throw new PeerError('message_not_found', 'No such message for this device', 404);
+    if (message.attempt_id !== attemptId) throw new PeerError('attempt_not_current', 'This delivery attempt is no longer current', 409);
+    return message;
+  }
+
+  function renew(nodeId, { messageId, attemptId, state }) {
+    if (!['accepted', 'starting', 'running'].includes(state)) throw new PeerError('invalid_state', 'Unknown attempt state');
+    return store.transaction(() => {
+      const message = currentAttempt(nodeId, messageId, attemptId);
+      if (!['claimed', 'running'].includes(message.status)) throw new PeerError('attempt_not_current', 'This delivery attempt is no longer active', 409);
+      if (!(Date.parse(message.lease_expires_at) > clock())) throw new PeerError('lease_expired', 'This delivery attempt lost its lease', 409);
+      const accepted = message.accepted_attempt === attemptId;
+      if (!accepted && state !== 'accepted') throw new PeerError('attempt_not_accepted', 'Accept the attempt before starting it', 409);
+      const changes = { lease_expires_at: iso(PEER_LIMITS.leaseSeconds * 1000) };
+      if (!accepted) changes.accepted_attempt = attemptId;
+      if (state === 'running' && message.status === 'claimed') changes.status = 'running';
+      store.updateMessage(messageId, changes, iso(), changes.status ? 'started' : accepted ? 'renewed' : 'accepted', attemptId);
+      return { cancel: message.cancel_requested === 1 || Date.parse(message.expires_at) <= clock() };
+    });
+  }
+
+  function result(nodeId, { messageId, attemptId, outcome, reply = null, error = null, via = null, verified = false }) {
+    if (!RESULT_OUTCOMES.has(outcome)) throw new PeerError('invalid_result', 'Unknown result outcome');
+    if (outcome === 'answered' && (typeof reply !== 'string' || !reply.trim() || reply.length > 64_000 || verified !== true)) {
+      throw new PeerError('invalid_result', 'An answer needs a verified reply');
+    }
+    return store.transaction(() => {
+      const message = currentAttempt(nodeId, messageId, attemptId);
+      if (TERMINAL_STATUSES.has(message.status) && message.status !== 'unknown') return statusView(message);
+      const detail = typeof error === 'string' ? error.slice(0, 120) : null;
+      if (outcome === 'never_started') {
+        // Only an attempt whose acceptance was never recorded is proof that nothing started.
+        // Once accepted, the receiver may have lost the acknowledgement, so the outcome is unknown.
+        const started = message.status === 'running'
+          || store.events(messageId).some((event) => event.kind === 'started' && event.detail === attemptId);
+        if (started) throw new PeerError('attempt_started', 'This attempt already started', 409);
+        if (message.accepted_attempt === attemptId) {
+          store.updateMessage(messageId, { status: 'unknown', error: 'accepted_without_start', lease_expires_at: null },
+            iso(), 'unknown', attemptId);
+        } else releaseUnstarted(message, detail);
+      } else {
+        store.updateMessage(messageId, { status: outcome, error: outcome === 'answered' ? null : detail,
+          reply: outcome === 'answered' ? reply : null, via: typeof via === 'string' ? via.slice(0, 80) : null,
+          verified: verified === true ? 1 : 0, lease_expires_at: null }, iso(), outcome, attemptId);
+      }
+      return statusView(store.message(messageId));
+    });
+  }
+
+  function addressed(nodeId, messageId) {
+    if (typeof messageId !== 'string' || messageId.length > 128) return null;
+    const sent = store.message(messageKey(nodeId, messageId));
+    if (sent) return sent;
+    const received = store.message(messageId);
+    return received?.target_node === nodeId ? received : null;
+  }
+
+  function status(nodeId, { messageId }) {
+    const message = addressed(nodeId, messageId);
+    if (!message) {
+      throw new PeerError('message_not_found', 'No such message for this device', 404);
+    }
+    return statusView(message);
+  }
+
+  function cancel(nodeId, { messageId }) {
+    return store.transaction(() => {
+      const message = typeof messageId === 'string' ? store.message(messageKey(nodeId, messageId)) : null;
+      if (!message) throw new PeerError('message_not_found', 'No such message sent by this device', 404);
+      if (message.status === 'queued') store.updateMessage(message.id, { status: 'cancelled', error: 'cancelled' }, iso(), 'cancelled');
+      else if (['claimed', 'running'].includes(message.status)) store.updateMessage(message.id, { cancel_requested: 1 }, iso(), 'cancel_requested');
+      return statusView(store.message(message.id));
+    });
+  }
+
+  function revoke(nodeId) {
+    if (nodeId === identity.fingerprint) throw new PeerError('invalid_revoke', 'The coordinator cannot revoke itself');
+    store.transaction(() => {
+      store.revokeNode(nodeId, iso());
+      for (const message of store.openForNode(nodeId)) {
+        if (message.status === 'queued') store.updateMessage(message.id, { status: 'cancelled', error: 'device_revoked' }, iso(), 'revoked');
+        else store.updateMessage(message.id, { cancel_requested: 1 }, iso(), 'cancel_requested', 'device_revoked');
+      }
+    });
+    onTrustChange();
+    return { revoked: true };
+  }
+
+  function releaseUnstarted(message, detail) {
+    const changes = message.cancel_requested ? { status: 'cancelled', error: 'cancelled' }
+      : Date.parse(message.expires_at) <= clock() ? { status: 'expired', error: 'expired' }
+      : message.start_attempts >= PEER_LIMITS.maxStartAttempts ? { status: 'failed', error: detail ?? 'start_attempts_exhausted' }
+      : { status: 'queued', error: detail };
+    store.updateMessage(message.id, { ...changes, attempt_id: null, accepted_attempt: null, lease_expires_at: null },
+      iso(), `never_started:${changes.status}`, message.attempt_id);
+  }
+
+  // An attempt the coordinator never accepted cannot have started, because a
+  // runner only starts after acceptance is confirmed. Once accepted, a lapsed
+  // lease is uncertain and becomes unknown, never "not started".
+  function sweep() {
+    store.transaction(() => {
+      for (const message of store.expiredQueued(iso())) store.updateMessage(message.id, { status: 'expired', error: 'expired' }, iso(), 'expired');
+      for (const message of store.staleLeases(iso())) {
+        if (message.accepted_attempt !== message.attempt_id) releaseUnstarted(message, 'not_accepted');
+        else store.updateMessage(message.id, { status: 'unknown', error: 'lease_expired', lease_expires_at: null }, iso(), 'unknown', message.attempt_id);
+      }
+    });
+  }
+
+  function devices() {
+    const now = clock();
+    return store.nodes().map((node) => ({ nodeId: node.id, name: node.name, status: node.status,
+      self: node.id === identity.fingerprint, pairedAt: node.paired_at, revokedAt: node.revoked_at,
+      online: node.id === identity.fingerprint || (Boolean(node.last_seen_at) && now - Date.parse(node.last_seen_at) < ONLINE_MS),
+      sharedAgents: JSON.parse(node.directory_json).length }));
+  }
+
+  return { createInvitation, pair, authenticate, publishDirectory, directory, submit, claim, renew, result,
+    status, cancel, revoke, sweep, devices, trustedCertificates: () => store.activeCertificates(),
+    openInvitations: () => store.openInvitations(iso()).length };
+}
+
+// Message IDs are chosen by senders, so the coordinator keys them per sending device.
+function messageKey(senderNode, messageId) {
+  return sha256Hex(`${senderNode}:${messageId}`);
+}
+
+function statusView(message) {
+  return { messageId: JSON.parse(message.assertion_json).messageId, status: message.status, reply: message.reply ?? null, error: message.error ?? null,
+    via: message.via ?? null, verified: message.verified === 1, updatedAt: message.updated_at };
+}
+
+export function cleanName(value) {
+  return typeof value === 'string' ? value.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 60) : '';
+}

package/src/agent-peer/coordinator-store.js

@@ -0,0 +1,95 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+// Paired devices, one-use invitations and the cross-device message queue.
+// Status changes are also appended to events, so history survives updates.
+export function createCoordinatorStore(path = ':memory:') {
+  if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const database = new DatabaseSync(path);
+  database.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA busy_timeout = 5000;
+    CREATE TABLE IF NOT EXISTS nodes (
+      id TEXT PRIMARY KEY, name TEXT NOT NULL, cert_pem TEXT NOT NULL, status TEXT NOT NULL,
+      paired_at TEXT NOT NULL, revoked_at TEXT, last_seen_at TEXT, directory_json TEXT NOT NULL DEFAULT '[]',
+      authority_json TEXT
+    );
+    CREATE TABLE IF NOT EXISTS invitations (
+      code_hash TEXT PRIMARY KEY, created_at TEXT NOT NULL, expires_at TEXT NOT NULL,
+      used_at TEXT, used_by TEXT
+    );
+    CREATE TABLE IF NOT EXISTS messages (
+      id TEXT PRIMARY KEY, sender_node TEXT NOT NULL, target_node TEXT NOT NULL, binding_id TEXT NOT NULL,
+      assertion_json TEXT NOT NULL, signature TEXT NOT NULL, status TEXT NOT NULL,
+      attempt_id TEXT, accepted_attempt TEXT, start_attempts INTEGER NOT NULL DEFAULT 0, lease_expires_at TEXT,
+      cancel_requested INTEGER NOT NULL DEFAULT 0, reply TEXT, error TEXT, via TEXT, verified INTEGER,
+      expires_at TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS messages_queue ON messages(target_node, status, created_at);
+    CREATE TABLE IF NOT EXISTS events (
+      seq INTEGER PRIMARY KEY AUTOINCREMENT, message_id TEXT, node_id TEXT, kind TEXT NOT NULL,
+      detail TEXT, at TEXT NOT NULL
+    );
+  `);
+  const transaction = (work) => {
+    database.exec('BEGIN IMMEDIATE');
+    try { const result = work(); database.exec('COMMIT'); return result; }
+    catch (error) { database.exec('ROLLBACK'); throw error; }
+  };
+  const event = (at, { messageId = null, nodeId = null, kind, detail = null }) => database.prepare(
+    'INSERT INTO events(message_id, node_id, kind, detail, at) VALUES(?,?,?,?,?)').run(messageId, nodeId, kind, detail, at);
+
+  return {
+    transaction,
+    event,
+    node: (id) => database.prepare('SELECT * FROM nodes WHERE id = ?').get(id) ?? null,
+    nodes: () => database.prepare('SELECT * FROM nodes ORDER BY paired_at').all(),
+    activeCertificates: () => database.prepare("SELECT cert_pem FROM nodes WHERE status = 'active'").all().map((row) => row.cert_pem),
+    // Only pairing (a local owner action) records a device's origin authority.
+    upsertNode({ id, name, certPem, authority = null, at }) {
+      database.prepare(`INSERT INTO nodes(id, name, cert_pem, status, paired_at, authority_json) VALUES(?,?,?,'active',?,?)
+        ON CONFLICT(id) DO UPDATE SET name = excluded.name, cert_pem = excluded.cert_pem, status = 'active',
+        revoked_at = NULL, directory_json = '[]', paired_at = excluded.paired_at, authority_json = excluded.authority_json`)
+        .run(id, name, certPem, at, authority ? JSON.stringify(authority) : null);
+      event(at, { nodeId: id, kind: 'paired' });
+    },
+    revokeNode(id, at) {
+      database.prepare("UPDATE nodes SET status = 'revoked', revoked_at = ?, directory_json = '[]' WHERE id = ?").run(at, id);
+      event(at, { nodeId: id, kind: 'revoked' });
+    },
+    touchNode: (id, at) => database.prepare('UPDATE nodes SET last_seen_at = ? WHERE id = ?').run(at, id),
+    setDirectory: (id, entries) => database.prepare('UPDATE nodes SET directory_json = ? WHERE id = ?').run(JSON.stringify(entries), id),
+    createInvitation: ({ codeHash, at, expiresAt }) => database.prepare(
+      'INSERT INTO invitations(code_hash, created_at, expires_at) VALUES(?,?,?)').run(codeHash, at, expiresAt),
+    invitation: (codeHash) => database.prepare('SELECT * FROM invitations WHERE code_hash = ?').get(codeHash) ?? null,
+    openInvitations: (at) => database.prepare(
+      'SELECT * FROM invitations WHERE used_at IS NULL AND expires_at > ?').all(at),
+    useInvitation: (codeHash, nodeId, at) => database.prepare(
+      'UPDATE invitations SET used_at = ?, used_by = ? WHERE code_hash = ? AND used_at IS NULL').run(at, nodeId, codeHash).changes === 1,
+    insertMessage(row) {
+      database.prepare(`INSERT INTO messages(id, sender_node, target_node, binding_id, assertion_json, signature,
+        status, expires_at, created_at, updated_at) VALUES(?,?,?,?,?,?,'queued',?,?,?)`).run(
+        row.id, row.senderNode, row.targetNode, row.bindingId, row.assertionJson, row.signature, row.expiresAt, row.at, row.at);
+      event(row.at, { messageId: row.id, nodeId: row.senderNode, kind: 'queued' });
+    },
+    message: (id) => database.prepare('SELECT * FROM messages WHERE id = ?').get(id) ?? null,
+    queuedCount: (targetNode) => database.prepare(
+      "SELECT count(*) AS count FROM messages WHERE target_node = ? AND status IN ('queued','claimed','running')").get(targetNode).count,
+    nextQueued: (targetNode, at) => database.prepare(`SELECT * FROM messages WHERE target_node = ? AND status = 'queued'
+      AND expires_at > ? AND cancel_requested = 0 ORDER BY created_at LIMIT 1`).get(targetNode, at) ?? null,
+    updateMessage(id, changes, at, kind, detail = null) {
+      const columns = Object.keys(changes);
+      database.prepare(`UPDATE messages SET ${columns.map((column) => `${column} = ?`).join(', ')}, updated_at = ? WHERE id = ?`)
+        .run(...columns.map((column) => changes[column]), at, id);
+      event(at, { messageId: id, kind, detail });
+    },
+    staleLeases: (at) => database.prepare(
+      "SELECT * FROM messages WHERE status IN ('claimed','running') AND lease_expires_at <= ?").all(at),
+    expiredQueued: (at) => database.prepare("SELECT * FROM messages WHERE status = 'queued' AND expires_at <= ?").all(at),
+    openForNode: (nodeId) => database.prepare(`SELECT * FROM messages WHERE (target_node = ? OR sender_node = ?)
+      AND status IN ('queued','claimed','running')`).all(nodeId, nodeId),
+    events: (messageId) => database.prepare('SELECT * FROM events WHERE message_id = ? ORDER BY seq').all(messageId),
+    close: () => database.close(),
+  };
+}

package/src/agent-peer/device-identity.js

@@ -0,0 +1,70 @@
+import 'reflect-metadata';
+import { BasicConstraintsExtension, X509CertificateGenerator } from '@peculiar/x509';
+import { createPrivateKey, randomBytes, sign, verify, webcrypto, X509Certificate } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { canonicalJson, pemToDer, sha256Hex } from './protocol.js';
+
+const KEY_FILE = 'device-key.pem';
+const CERT_FILE = 'device-cert.pem';
+const VALIDITY_MS = 10 * 365 * 24 * 60 * 60 * 1000;
+const ALGORITHM = { name: 'ECDSA', namedCurve: 'P-256', hash: 'SHA-256' };
+
+// One key pair per installation. The private key never leaves this directory;
+// other devices only ever see the self-signed certificate and its fingerprint.
+export async function loadDeviceIdentity(directory) {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const keyPath = join(directory, KEY_FILE);
+  const certPath = join(directory, CERT_FILE);
+  if (!existsSync(keyPath) || !existsSync(certPath)) {
+    const created = await createDeviceCertificate();
+    writeFileSync(keyPath, created.keyPem, { mode: 0o600 });
+    chmodSync(keyPath, 0o600);
+    writeFileSync(certPath, created.certPem, { mode: 0o644 });
+  }
+  return deviceIdentity({ keyPem: readFileSync(keyPath, 'utf8'), certPem: readFileSync(certPath, 'utf8') });
+}
+
+export function deviceIdentity({ keyPem, certPem }) {
+  const key = createPrivateKey(keyPem);
+  return Object.freeze({
+    fingerprint: certificateFingerprint(certPem),
+    certPem,
+    tlsOptions: Object.freeze({ key: keyPem, cert: certPem }),
+    sign: (value) => sign('sha256', Buffer.from(canonicalJson(value)), key).toString('base64'),
+  });
+}
+
+export function certificateFingerprint(certPem) {
+  return sha256Hex(pemToDer(certPem));
+}
+
+export function verifyDeviceSignature(certPem, value, signature) {
+  if (typeof signature !== 'string' || signature.length > 512) return false;
+  try {
+    const certificate = new X509Certificate(certPem);
+    return verify('sha256', Buffer.from(canonicalJson(value)), certificate.publicKey, Buffer.from(signature, 'base64'));
+  } catch {
+    return false;
+  }
+}
+
+export async function createDeviceCertificate({ now = Date.now() } = {}) {
+  const keys = await webcrypto.subtle.generateKey(ALGORITHM, true, ['sign', 'verify']);
+  const certificate = await X509CertificateGenerator.createSelfSigned({
+    // A unique subject keeps several paired self-signed certificates unambiguous in one trust store.
+    name: `CN=FULI device ${randomBytes(8).toString('hex')}`,
+    serialNumber: `01${randomBytes(15).toString('hex')}`,
+    notBefore: new Date(now - 24 * 60 * 60 * 1000),
+    notAfter: new Date(now + VALIDITY_MS),
+    signingAlgorithm: ALGORITHM,
+    keys,
+    extensions: [new BasicConstraintsExtension(true, undefined, true)],
+  }, webcrypto);
+  const pkcs8 = Buffer.from(await webcrypto.subtle.exportKey('pkcs8', keys.privateKey));
+  return {
+    certPem: `${certificate.toString('pem').trim()}\n`,
+    keyPem: `-----BEGIN PRIVATE KEY-----\n${pkcs8.toString('base64').match(/.{1,64}/g).join('\n')}\n-----END PRIVATE KEY-----\n`,
+  };
+}

package/src/agent-peer/http.js

@@ -0,0 +1,47 @@
+import { readJson, sendJson } from '../http/response.js';
+import { PeerError } from './protocol.js';
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+// The owner's LAN roundtable controls. They answer only on this computer's
+// loopback console, even when the console itself is reachable on the LAN.
+export async function handlePeerApiRequest({ request, response, url, peer }) {
+  if (!url.pathname.startsWith('/api/peer')) return false;
+  if (!peer) { sendJson(response, 404, { error: 'peer_unavailable', message: 'The LAN roundtable needs a local FULI installation' }); return true; }
+  const host = String(request.headers.host ?? '');
+  if (!LOOPBACK.has(request.socket?.remoteAddress) || !/^(127\.0\.0\.1|\[::1\])(:\d+)?$/.test(host)) {
+    sendJson(response, 403, { error: 'local_owner_only', message: 'LAN roundtable settings can only be changed on this computer' });
+    return true;
+  }
+  try {
+    const result = await route(request, url.pathname, peer);
+    if (result === undefined) return false;
+    sendJson(response, 200, result);
+  } catch (error) {
+    if (!(error instanceof PeerError)) throw error;
+    sendJson(response, error.status ?? 400, { error: error.code, message: error.message });
+  }
+  return true;
+}
+
+async function route(request, pathname, peer) {
+  const { method } = request;
+  if (pathname === '/api/peer' && method === 'GET') return peer.status();
+  if (pathname === '/api/peer/coordinator' && method === 'POST') {
+    const body = await readJson(request);
+    return peer.enableCoordinator({ host: body.host, port: body.port ?? 0, name: body.name });
+  }
+  if (pathname === '/api/peer/invitations' && method === 'POST') { await readJson(request); return peer.createInvitation(); }
+  if (pathname === '/api/peer/invitations/preview' && method === 'POST') {
+    return peer.previewInvitation((await readJson(request)).invitation);
+  }
+  if (pathname === '/api/peer/join' && method === 'POST') {
+    const body = await readJson(request);
+    return peer.join({ invitation: body.invitation, name: body.name });
+  }
+  if (pathname === '/api/peer/shares' && method === 'PUT') return peer.setShares({ shares: (await readJson(request)).shares });
+  const revoke = /^\/api\/peer\/devices\/([0-9a-f]{64})\/revoke$/.exec(pathname);
+  if (revoke && method === 'POST') { await readJson(request); return peer.revokeDevice(revoke[1]); }
+  if (pathname === '/api/peer/disable' && method === 'POST') { await readJson(request); return peer.disable(); }
+  return undefined;
+}

package/src/agent-peer/node-store.js

@@ -0,0 +1,127 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+// This device's side of the LAN roundtable: owner settings and shares, every
+// receiving attempt (written before any process starts), the result outbox,
+// and where messages this device sent were routed.
+export function createNodeStore(path = ':memory:') {
+  if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const database = new DatabaseSync(path);
+  database.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA busy_timeout = 5000;
+    CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value_json TEXT NOT NULL, updated_at TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS shares (
+      binding_id TEXT PRIMARY KEY, space_id TEXT NOT NULL, project_id TEXT NOT NULL, agent_id TEXT NOT NULL,
+      clients_json TEXT NOT NULL, working_directory TEXT, created_at TEXT NOT NULL, revoked_at TEXT
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS shares_active ON shares(space_id, project_id, agent_id) WHERE revoked_at IS NULL;
+    CREATE TABLE IF NOT EXISTS authorities (
+      node_id TEXT PRIMARY KEY, key_id TEXT NOT NULL, public_key TEXT NOT NULL, bound_by TEXT NOT NULL, bound_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS attempts (
+      message_id TEXT NOT NULL, attempt_id TEXT NOT NULL, state TEXT NOT NULL, binding_id TEXT,
+      detail TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY(message_id, attempt_id)
+    );
+    CREATE TABLE IF NOT EXISTS outbox (
+      message_id TEXT NOT NULL, attempt_id TEXT NOT NULL, payload_json TEXT NOT NULL,
+      created_at TEXT NOT NULL, delivered_at TEXT, PRIMARY KEY(message_id, attempt_id)
+    );
+    CREATE TABLE IF NOT EXISTS sent (
+      message_id TEXT PRIMARY KEY, target_node TEXT NOT NULL, binding_id TEXT NOT NULL, created_at TEXT NOT NULL
+    );
+  `);
+  const now = () => new Date().toISOString();
+  const transaction = (work) => {
+    database.exec('BEGIN IMMEDIATE');
+    try { const result = work(); database.exec('COMMIT'); return result; }
+    catch (error) { database.exec('ROLLBACK'); throw error; }
+  };
+  const shareKey = (share) => [share.spaceId, share.projectId, share.agentId].join('\u0000');
+  const shareView = (row) => row && ({ bindingId: row.binding_id, spaceId: row.space_id, projectId: row.project_id, agentId: row.agent_id,
+    clients: JSON.parse(row.clients_json), workingDirectory: row.working_directory ?? null, createdAt: row.created_at, revokedAt: row.revoked_at });
+
+  return {
+    setting(key) {
+      const row = database.prepare('SELECT value_json FROM settings WHERE key = ?').get(key);
+      return row ? JSON.parse(row.value_json) : null;
+    },
+    setSetting(key, value) {
+      if (value === null) database.prepare('DELETE FROM settings WHERE key = ?').run(key);
+      else database.prepare(`INSERT INTO settings(key, value_json, updated_at) VALUES(?,?,?)
+        ON CONFLICT(key) DO UPDATE SET value_json = excluded.value_json, updated_at = excluded.updated_at`)
+        .run(key, JSON.stringify(value), now());
+    },
+    shares: () => database.prepare('SELECT * FROM shares WHERE revoked_at IS NULL ORDER BY created_at').all().map(shareView),
+    share: (bindingId) => shareView(database.prepare('SELECT * FROM shares WHERE binding_id = ? AND revoked_at IS NULL').get(bindingId)),
+    // Replaces the owner's share list; a removed share is kept as revoked history.
+    replaceShares(shares, idFactory) {
+      return transaction(() => {
+        const at = now();
+        const wanted = new Map(shares.map((share) => [shareKey(share), share]));
+        for (const row of database.prepare('SELECT * FROM shares WHERE revoked_at IS NULL').all()) {
+          const key = shareKey(shareView(row));
+          const next = wanted.get(key);
+          if (!next) database.prepare('UPDATE shares SET revoked_at = ? WHERE binding_id = ?').run(at, row.binding_id);
+          else {
+            database.prepare('UPDATE shares SET clients_json = ?, working_directory = ? WHERE binding_id = ?')
+              .run(JSON.stringify(next.clients), next.workingDirectory ?? null, row.binding_id);
+            wanted.delete(key);
+          }
+        }
+        for (const share of wanted.values()) {
+          database.prepare(`INSERT INTO shares(binding_id, space_id, project_id, agent_id, clients_json, working_directory, created_at)
+            VALUES(?,?,?,?,?,?,?)`).run(idFactory(), share.spaceId, share.projectId, share.agentId, JSON.stringify(share.clients),
+            share.workingDirectory ?? null, at);
+        }
+        return this.shares();
+      });
+    },
+    authority(nodeId) {
+      const row = database.prepare('SELECT * FROM authorities WHERE node_id = ?').get(nodeId);
+      return row ? { keyId: row.key_id, publicKey: row.public_key, boundBy: row.bound_by, boundAt: row.bound_at } : null;
+    },
+    // A device's origin key is bound once. Only the local owner re-pairing a
+    // device (forgetAuthority first) can bind a different key.
+    bindAuthority(nodeId, { keyId, publicKey }, boundBy) {
+      return transaction(() => {
+        const existing = this.authority(nodeId);
+        if (existing) return { bound: existing.keyId === keyId && existing.publicKey === publicKey, authority: existing };
+        database.prepare('INSERT INTO authorities(node_id, key_id, public_key, bound_by, bound_at) VALUES(?,?,?,?,?)')
+          .run(nodeId, keyId, publicKey, boundBy, now());
+        return { bound: true, authority: this.authority(nodeId) };
+      });
+    },
+    forgetAuthority: (nodeId) => database.prepare('DELETE FROM authorities WHERE node_id = ?').run(nodeId),
+    forgetAuthorities: () => database.prepare('DELETE FROM authorities').run(),
+    attemptsFor: (messageId) => database.prepare('SELECT * FROM attempts WHERE message_id = ? ORDER BY created_at').all(messageId),
+    recordAttempt({ messageId, attemptId, bindingId }) {
+      return transaction(() => {
+        const existing = database.prepare('SELECT * FROM attempts WHERE message_id = ? AND attempt_id = ?').get(messageId, attemptId);
+        if (existing) return { inserted: false, attempt: existing };
+        const at = now();
+        database.prepare(`INSERT INTO attempts(message_id, attempt_id, state, binding_id, created_at, updated_at)
+          VALUES(?,?, 'claimed', ?,?,?)`).run(messageId, attemptId, bindingId ?? null, at, at);
+        return { inserted: true, attempt: database.prepare('SELECT * FROM attempts WHERE message_id = ? AND attempt_id = ?').get(messageId, attemptId) };
+      });
+    },
+    setAttemptState: (messageId, attemptId, state, detail = null) => database.prepare(
+      'UPDATE attempts SET state = ?, detail = coalesce(?, detail), updated_at = ? WHERE message_id = ? AND attempt_id = ?')
+      .run(state, detail, now(), messageId, attemptId),
+    unfinishedAttempts: () => database.prepare(`SELECT a.* FROM attempts a WHERE a.state IN ('claimed','accepted','starting','running')
+      AND NOT EXISTS (SELECT 1 FROM outbox o WHERE o.message_id = a.message_id AND o.attempt_id = a.attempt_id)`).all(),
+    queueResult(messageId, attemptId, payload) {
+      database.prepare(`INSERT INTO outbox(message_id, attempt_id, payload_json, created_at) VALUES(?,?,?,?)
+        ON CONFLICT(message_id, attempt_id) DO NOTHING`).run(messageId, attemptId, JSON.stringify(payload), now());
+    },
+    pendingResults: () => database.prepare('SELECT * FROM outbox WHERE delivered_at IS NULL ORDER BY created_at').all()
+      .map((row) => ({ messageId: row.message_id, attemptId: row.attempt_id, payload: JSON.parse(row.payload_json) })),
+    markDelivered: (messageId, attemptId) => database.prepare(
+      'UPDATE outbox SET delivered_at = ? WHERE message_id = ? AND attempt_id = ?').run(now(), messageId, attemptId),
+    recordSent: ({ messageId, targetNode, bindingId }) => database.prepare(
+      'INSERT OR IGNORE INTO sent(message_id, target_node, binding_id, created_at) VALUES(?,?,?,?)').run(messageId, targetNode, bindingId, now()),
+    sent: (messageId) => database.prepare('SELECT * FROM sent WHERE message_id = ?').get(messageId) ?? null,
+    close: () => database.close(),
+  };
+}