fuli-context 0.12.0 → 0.12.2

package/src/agent-peer/origin-proof.js

@@ -0,0 +1,56 @@
+import { createPublicKey, verify } from 'node:crypto';
+
+import { canonicalJson, canonicalTime, PeerError, sha256Hex } from './protocol.js';
+
+const PROOF_VERSION = 'fuli-remote-origin/1';
+const CLOCK_SKEW_MS = 60_000;
+
+// The digest the sending Provider signs: the whole message except the proof itself.
+export function assertionDigest(assertion) {
+  const { origin: _origin, ...signed } = assertion;
+  return sha256Hex(canonicalJson(signed));
+}
+
+export function isAuthorityKey(value) {
+  return Boolean(value) && typeof value.keyId === 'string' && /^[0-9a-f]{32}$/.test(value.keyId)
+    && typeof value.publicKey === 'string' && Buffer.from(value.publicKey, 'base64url').length === 32;
+}
+
+export function authorityFromProvider(response) {
+  const key = { keyId: response?.key_id, publicKey: response?.public_key };
+  if (response?.algorithm !== 'Ed25519' || !isAuthorityKey(key)) {
+    throw new PeerError('authority_unavailable', 'The local FULI authority returned an invalid origin key', 502);
+  }
+  return key;
+}
+
+// A device signature only proves which installation relayed a message. This
+// proves the sender's own FULI authority let its current project lead send
+// exactly this message to exactly this binding, until a short expiry.
+export function verifyOriginProof(assertion, authority, { now = Date.now() } = {}) {
+  const fail = (message) => { throw new PeerError('origin_rejected', message, 403); };
+  if (!isAuthorityKey(authority)) fail('No origin authority was bound when this device was paired');
+  const proof = assertion?.origin;
+  if (typeof proof?.payload !== 'string' || typeof proof?.signature !== 'string'
+    || proof.payload.length > 4096 || proof.signature.length > 128) fail('The message has no origin proof');
+  const payload = Buffer.from(proof.payload, 'base64url');
+  const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: authority.publicKey }, format: 'jwk' });
+  let valid = false;
+  try { valid = verify(null, payload, key, Buffer.from(proof.signature, 'base64url')); } catch { valid = false; }
+  if (!valid) fail('The origin proof signature is invalid');
+  let claims;
+  try { claims = JSON.parse(payload.toString('utf8')); } catch { fail('The origin proof is malformed'); }
+  if (claims?.version !== PROOF_VERSION || claims.key_id !== authority.keyId) fail('The origin proof uses another authority');
+  if (claims.digest !== assertionDigest(assertion)) fail('The origin proof covers a different message');
+  if (claims.message_id !== assertion.messageId || claims.agent_id !== assertion.from.agentId
+    || claims.target_node !== assertion.to.node || claims.binding_id !== assertion.to.bindingId
+    || claims.expires_at !== assertion.expiresAt) fail('The origin proof does not match the message');
+  if (typeof claims.space_id !== 'string' || typeof claims.project_id !== 'string' || typeof claims.task_hash !== 'string') {
+    fail('The origin proof has no source scope');
+  }
+  const issued = canonicalTime(claims.issued_at);
+  const expires = canonicalTime(claims.expires_at);
+  if (issued === null || expires === null || issued > now + CLOCK_SKEW_MS) fail('The origin proof has invalid times');
+  if (expires <= now) throw new PeerError('origin_expired', 'The origin proof has expired', 410);
+  return { spaceId: claims.space_id, projectId: claims.project_id, agentId: claims.agent_id, taskHash: claims.task_hash };
+}

package/src/agent-peer/peer-port.js

@@ -0,0 +1,140 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { loadDeviceIdentity } from './device-identity.js';
+import { createNodeStore } from './node-store.js';
+import { assertionDigest, authorityFromProvider } from './origin-proof.js';
+import { createPeerClient } from './peer-transport.js';
+import { PEER_LIMITS, PEER_PROTOCOL, PeerError, TERMINAL_STATUSES } from './protocol.js';
+
+const ADDRESS = /^peer:([0-9a-f]{16}):([A-Za-z0-9][A-Za-z0-9._:-]{0,127})$/;
+const STATUS_POLL_MS = 2_000;
+const PROOF_MARGIN_MS = 60_000;
+
+export function peerDirectory(dataDir) {
+  return join(dataDir, 'peer');
+}
+
+// What Agents on this device use to reach shared project leads on other paired
+// devices. It never pairs, shares or listens: those stay with the local owner.
+export function createPeerPort({ dataDir, provider, spaceId, clock = Date.now, idFactory = randomUUID,
+  statusPollMs = STATUS_POLL_MS }) {
+  const directory = peerDirectory(dataDir);
+  let store = null;
+  let session = null;
+
+  const databasePath = join(directory, 'node.sqlite');
+  const nodeStore = () => (store ??= createNodeStore(databasePath));
+  // Nothing is created on disk until the owner configures the LAN roundtable.
+  const configured = () => Boolean(store) || existsSync(databasePath);
+  const membership = () => (configured() ? nodeStore().setting('membership') : null);
+
+  async function connection() {
+    const current = membership();
+    if (!current?.coordinator) throw new PeerError('peer_not_paired', 'This device is not paired with a coordinator; the owner pairs devices in Settings', 409);
+    if (session?.fingerprint === current.coordinator.fingerprint && session.url === current.coordinator.url) return session;
+    session?.client.close();
+    const identity = await loadDeviceIdentity(directory);
+    session = { fingerprint: current.coordinator.fingerprint, url: current.coordinator.url, identity,
+      client: createPeerClient({ identity, coordinator: current.coordinator }) };
+    return session;
+  }
+
+  async function post(path, body, options) {
+    return (await connection()).client.post(path, body, options);
+  }
+
+  function isRemoteAddress(to) {
+    return typeof to === 'string' && to.trim().startsWith('peer:');
+  }
+
+  async function remoteDirectory() {
+    if (!membership()?.coordinator) return null;
+    const { devices } = await post('/peer/1/directory', {});
+    const self = (await connection()).identity.fingerprint;
+    return devices.filter((device) => device.nodeId !== self);
+  }
+
+  async function remoteAgents({ query = null } = {}) {
+    let devices;
+    try { devices = await remoteDirectory(); }
+    catch (error) { return { agents: [], unavailable: error.code ?? 'coordinator_unreachable' }; }
+    if (!devices) return null;
+    const needle = query?.trim().toLowerCase();
+    const agents = devices.flatMap((device) => device.agents.map((agent) => ({
+      address: `peer:${device.nodeId.slice(0, 16)}:${agent.bindingId}`, name: agent.name, role: 'shared_project_lead',
+      employeeNumber: agent.employeeNumber, responsibility: agent.responsibility, projectName: agent.projectName,
+      device: { name: device.name, online: device.online } })))
+      .filter((agent) => !needle || [agent.name, agent.projectName, agent.responsibility, agent.device.name]
+        .some((value) => value?.toLowerCase().includes(needle)));
+    return { agents: agents.slice(0, 50) };
+  }
+
+  async function resolveRemote(to) {
+    const match = ADDRESS.exec(String(to ?? '').trim());
+    if (!match) throw new PeerError('invalid_address', 'Remote Agents are addressed as peer:<device>:<binding> from find_agents');
+    const device = (await remoteDirectory() ?? []).find((entry) => entry.nodeId.startsWith(match[1]));
+    const agent = device?.agents.find((entry) => entry.bindingId === match[2]);
+    if (!agent) throw new PeerError('agent_not_shared', 'That remote Agent is not shared any more; call find_agents again', 404);
+    return { address: match[0], node: device.nodeId, bindingId: agent.bindingId, agentId: agent.agentId,
+      name: agent.name, deviceName: device.name };
+  }
+
+  // The task token is only used with this device's own authority; the remote
+  // device receives the authority's signed statement, never the token.
+  async function send({ messageId, threadId, target, body, conversation, depth, from, taskContextToken, sourceApplication }) {
+    const { identity } = await connection();
+    const now = clock();
+    const assertion = { protocol: PEER_PROTOCOL, messageId, threadId,
+      from: { node: identity.fingerprint, agentId: from.agentId, name: from.name, client: from.client },
+      to: { node: target.node, bindingId: target.bindingId, agentId: target.agentId },
+      body, conversation, depth,
+      issuedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + PEER_LIMITS.defaultTtlSeconds * 1000 - PROOF_MARGIN_MS).toISOString() };
+    const issued = await provider.issueRemoteAgentOrigin({ personal_space_id: spaceId(), task_context_token: taskContextToken,
+      source_application: sourceApplication, message_id: messageId, digest: assertionDigest(assertion),
+      target_node: target.node, binding_id: target.bindingId, expires_at: assertion.expiresAt });
+    if (issued.agent_id !== from.agentId) throw new PeerError('origin_mismatch', 'The local authority attributed this task to another Agent', 409);
+    assertion.origin = issued.proof;
+    nodeStore().recordSent({ messageId, targetNode: target.node, bindingId: target.bindingId });
+    return post('/peer/1/messages', { assertion, signature: identity.sign(assertion) });
+  }
+
+  async function status(messageId, options) {
+    return post('/peer/1/status', { messageId }, options);
+  }
+
+  async function cancel(messageId) {
+    return post('/peer/1/cancel', { messageId });
+  }
+
+  async function waitFor(messageId, timeoutMs) {
+    const deadline = clock() + timeoutMs;
+    let last = null;
+    for (;;) {
+      try { last = await status(messageId); } catch (error) { if (!last) last = { status: 'queued', error: error.code }; }
+      if (TERMINAL_STATUSES.has(last.status) || clock() >= deadline) return last;
+      await delay(Math.min(statusPollMs, Math.max(0, deadline - clock())));
+    }
+  }
+
+  function hasSent(messageId) {
+    return configured() && Boolean(nodeStore().sent(messageId));
+  }
+
+  async function localAuthority() {
+    return authorityFromProvider(await provider.getRemoteOriginAuthority(spaceId()));
+  }
+
+  function close() {
+    session?.client.close();
+    session = null;
+    store?.close();
+    store = null;
+  }
+
+  return { configured, isRemoteAddress, remoteAgents, resolveRemote, send, status, cancel, waitFor, hasSent, localAuthority,
+    nodeStore, directory, idFactory, close };
+}

package/src/agent-peer/peer-runtime.js

@@ -0,0 +1,298 @@
+import { networkInterfaces } from 'node:os';
+import { join as joinPath } from 'node:path';
+
+import { resolvePersonalProjectPath } from '../graphiti/project-path-context.js';
+import { loadProjectTeam } from '../graphiti/project-team-view.js';
+import { startCoordinatorServer } from './coordinator-http.js';
+import { cleanName, createCoordinatorService } from './coordinator-service.js';
+import { createCoordinatorStore } from './coordinator-store.js';
+import { loadDeviceIdentity } from './device-identity.js';
+import { createPeerClient, pairWithCoordinator } from './peer-transport.js';
+import { coordinatorUrl, decodeInvitation, PeerError, shortFingerprint } from './protocol.js';
+import { createPeerRunner } from './runner.js';
+
+const PUBLISH_MS = 60_000;
+const WAKE_CLIENTS = new Set(['codex', 'claude_code']);
+
+// The local owner's LAN roundtable controls, run only by the console process.
+// Nothing here starts unless the owner turned it on; console LAN access does not.
+export function createPeerRuntime({ app, port, interfaces = networkInterfaces, allowLoopback = false,
+  claimWaitMs, resolveFolder = resolvePersonalProjectPath, onError = () => {} }) {
+  const store = () => port.nodeStore();
+  let coordinator = null;
+  let runner = null;
+  let runnerClient = null;
+  let publisher = null;
+  let leaveRetry = null;
+  let leaveWork = null;
+  let leaveAbort = null;
+  const spaceId = () => app.config.personal.spaceId;
+
+  function localAddresses() {
+    return Object.values(interfaces()).flat().filter((entry) => entry && !entry.internal
+      && (entry.family === 'IPv4' || entry.family === 4)).map((entry) => entry.address);
+  }
+
+  async function resume() {
+    if (!port.configured()) return;
+    await finishLeaving();
+    const settings = store().setting('coordinator');
+    if (settings) await startCoordinator(settings);
+    if (store().setting('membership')) await startRunner();
+  }
+
+  async function startCoordinator({ host, port: listenPort, name }) {
+    const identity = await loadDeviceIdentity(port.directory);
+    const authority = await port.localAuthority();
+    const coordinatorStore = createCoordinatorStore(joinPath(port.directory, 'coordinator.sqlite'));
+    let server = null;
+    const service = createCoordinatorService({ store: coordinatorStore, identity, authority, name,
+      onTrustChange: () => server?.refreshTrust() });
+    try {
+      server = await startCoordinatorServer({ service, identity, host, port: listenPort, claimWaitMs });
+    } catch (error) {
+      coordinatorStore.close();
+      throw new PeerError('listen_failed', `Could not listen on ${host}:${listenPort}: ${error.code ?? error.message}`, 409);
+    }
+    coordinator = { service, server, store: coordinatorStore, host, name };
+    const url = coordinatorUrl(host, server.address.port);
+    store().setSetting('coordinator', { host, port: server.address.port, name });
+    store().setSetting('membership', { role: 'coordinator', coordinator: { url, certPem: identity.certPem,
+      fingerprint: identity.fingerprint, name } });
+    store().forgetAuthority(identity.fingerprint);
+    store().bindAuthority(identity.fingerprint, authority, 'self');
+  }
+
+  async function startRunner() {
+    if (runner) return;
+    const membership = store().setting('membership');
+    const identity = await loadDeviceIdentity(port.directory);
+    runnerClient = createPeerClient({ identity, coordinator: membership.coordinator });
+    runner = createPeerRunner({ store: store(), client: runnerClient, roundtable: app.roundtable, provider: app.personal,
+      nodeId: identity.fingerprint, spaceId, onError });
+    runner.start().catch(onError);
+    await publish().catch(onError);
+    publisher = setInterval(() => publish().catch(onError), PUBLISH_MS);
+    publisher.unref();
+  }
+
+  async function stopAll() {
+    clearTimeout(leaveRetry);
+    leaveRetry = null;
+    leaveAbort?.abort();
+    await leaveWork?.catch(onError);
+    clearInterval(publisher);
+    publisher = null;
+    await runner?.stop();
+    runner = null;
+    runnerClient?.close();
+    runnerClient = null;
+    if (coordinator) {
+      await coordinator.server.close();
+      coordinator.store.close();
+      coordinator = null;
+    }
+  }
+
+  // Each share names the lead it was made for; after a handoff the old share
+  // is withheld until the owner shares the project's new lead.
+  async function shareStates() {
+    const projects = await app.personal.listPersonalProjects(spaceId()).catch(() => []);
+    const names = new Map((Array.isArray(projects) ? projects : projects?.projects ?? [])
+      .map((project) => [project.project_id ?? project.personal_project_id ?? project.id, project.profile?.name ?? project.name]));
+    return Promise.all(store().shares().filter((share) => share.spaceId === spaceId()).map(async (share) => {
+      const team = await loadProjectTeam(app, share.spaceId, share.projectId).catch(() => null);
+      const current = team?.lead?.agentId === share.agentId;
+      return { ...share, projectName: names.get(share.projectId) ?? share.projectId, lead: team?.lead ?? null,
+        state: current ? 'shared' : team?.lead ? 'lead_changed' : 'lead_unavailable' };
+    }));
+  }
+
+  async function publish() {
+    if (!runnerClient) return;
+    const agents = (await shareStates()).filter((share) => share.state === 'shared').map((share) => ({
+      bindingId: share.bindingId, agentId: share.agentId, name: share.lead.name, employeeNumber: share.lead.employeeNumber,
+      responsibility: share.lead.responsibility, projectName: share.projectName, clients: share.clients }));
+    await runner?.reconcileShares(new Set(agents.map((agent) => agent.bindingId)));
+    await runnerClient.post('/peer/1/directory/publish', { agents });
+  }
+
+  // Projects the owner may share: each with its current lead and the clients that lead may use.
+  async function shareable() {
+    const projects = await app.personal.listPersonalProjects(spaceId()).catch(() => []);
+    const list = (Array.isArray(projects) ? projects : projects?.projects ?? [])
+      .filter((project) => project.scope_type !== 'temporary').slice(0, 50);
+    const agents = await app.listProjectAgents({ personalSpaceId: spaceId() }).catch(() => []);
+    return Promise.all(list.map(async (project) => {
+      const projectId = project.project_id ?? project.personal_project_id ?? project.id;
+      const team = await loadProjectTeam(app, spaceId(), projectId).catch(() => null);
+      const allowed = (agents.find((agent) => agent.agentId === team?.lead?.agentId)?.profile.allowedClients ?? [])
+        .filter((client) => WAKE_CLIENTS.has(client));
+      return { projectId, projectName: project.profile?.name ?? project.name ?? projectId,
+        lead: team?.lead ? { agentId: team.lead.agentId, name: team.lead.name } : null, clients: allowed };
+    }));
+  }
+
+  async function status() {
+    if (!port.configured()) {
+      return { beta: true, role: null, device: null, coordinator: null, addresses: localAddresses(), devices: [],
+        openInvitations: 0, shares: [], shareable: [] };
+    }
+    const membership = store().setting('membership');
+    const identity = membership ? await loadDeviceIdentity(port.directory) : null;
+    let devices = [];
+    if (coordinator) devices = coordinator.service.devices();
+    return {
+      beta: true,
+      remoteRemovalPending: Boolean(store().setting('pendingLeave')),
+      role: membership?.role ?? null,
+      device: identity ? { fingerprint: identity.fingerprint, shortFingerprint: shortFingerprint(identity.fingerprint) } : null,
+      coordinator: membership ? { name: membership.coordinator.name, url: membership.coordinator.url,
+        shortFingerprint: shortFingerprint(membership.coordinator.fingerprint), listening: Boolean(coordinator) } : null,
+      addresses: localAddresses(),
+      devices: devices.map((device) => ({ ...device, shortFingerprint: shortFingerprint(device.nodeId) })),
+      openInvitations: coordinator ? coordinator.service.openInvitations() : 0,
+      shares: membership ? (await shareStates()).map(({ lead: _lead, ...share }) => share) : [],
+      shareable: membership ? await shareable() : [],
+    };
+  }
+
+  async function enableCoordinator({ host, port: listenPort = 0, name }) {
+    if (store().setting('membership')) throw new PeerError('already_paired', 'Turn the LAN roundtable off before changing its role', 409);
+    const allowed = localAddresses();
+    if (!(allowed.includes(host) || (allowLoopback && host === '127.0.0.1'))) {
+      throw new PeerError('invalid_address', 'Choose one of this computer\'s network addresses', 422);
+    }
+    if (!Number.isSafeInteger(listenPort) || listenPort < 0 || listenPort > 65535) throw new PeerError('invalid_address', 'Invalid port', 422);
+    await startCoordinator({ host, port: listenPort, name: cleanName(name) || 'FULI coordinator' });
+    await startRunner();
+    return status();
+  }
+
+  function createInvitation() {
+    if (!coordinator) throw new PeerError('not_coordinator', 'Only the coordinator device creates invitations', 409);
+    const settings = store().setting('coordinator');
+    return coordinator.service.createInvitation({ url: coordinatorUrl(settings.host, settings.port) });
+  }
+
+  function previewInvitation(text) {
+    const invitation = decodeInvitation(text);
+    return { name: invitation.name, url: invitation.url, fingerprint: invitation.fingerprint,
+      shortFingerprint: shortFingerprint(invitation.fingerprint), expiresAt: invitation.expiresAt };
+  }
+
+  async function join({ invitation: text, name }) {
+    if (store().setting('membership')) throw new PeerError('already_paired', 'This device is already paired', 409);
+    await finishLeaving();
+    if (store().setting('pendingLeave')) throw new PeerError('leave_pending', 'The previous coordinator is offline. Retry after it is available, or revoke this device there.', 409);
+    const invitation = decodeInvitation(text);
+    const identity = await loadDeviceIdentity(port.directory);
+    const authority = await port.localAuthority();
+    const result = await pairWithCoordinator({ identity, authority, invitation, name: cleanName(name) || 'FULI device' });
+    if (result.coordinatorNodeId !== invitation.fingerprint) throw new PeerError('invalid_pairing', 'The coordinator answered with another identity', 502);
+    store().forgetAuthority(invitation.fingerprint);
+    store().bindAuthority(invitation.fingerprint, invitation.authority, 'pairing');
+    store().setSetting('membership', { role: 'member', coordinator: { url: invitation.url, certPem: invitation.certificatePem,
+      fingerprint: invitation.fingerprint, name: invitation.name || 'FULI coordinator' } });
+    await startRunner();
+    return status();
+  }
+
+  // The owner picks each project, the clients it may be woken in and,
+  // optionally, its folder; each share is bound to that project's current lead.
+  async function setShares({ shares: wanted }) {
+    if (!Array.isArray(wanted) || wanted.length > 50) throw new PeerError('invalid_shares', 'Choose up to 50 projects', 422);
+    const projects = await app.personal.listPersonalProjects(spaceId());
+    const known = Array.isArray(projects) ? projects : projects?.projects ?? [];
+    const agents = await app.listProjectAgents({ personalSpaceId: spaceId() });
+    const shares = [];
+    for (const entry of wanted) {
+      const projectId = entry?.projectId;
+      if (typeof projectId !== 'string' || !projectId || shares.some((share) => share.projectId === projectId)) {
+        throw new PeerError('invalid_shares', 'Each shared project must be listed once', 422);
+      }
+      const team = await loadProjectTeam(app, spaceId(), projectId);
+      if (!team.lead) throw new PeerError('lead_unavailable', 'A shared project needs an active project lead', 409);
+      const allowed = (agents.find((agent) => agent.agentId === team.lead.agentId)?.profile.allowedClients ?? [])
+        .filter((client) => WAKE_CLIENTS.has(client));
+      const clients = Array.isArray(entry.clients) ? [...new Set(entry.clients)] : [];
+      if (!clients.length || !clients.every((client) => allowed.includes(client))) {
+        throw new PeerError('invalid_clients', 'Choose at least one client the project lead may use', 422);
+      }
+      shares.push({ spaceId: spaceId(), projectId, agentId: team.lead.agentId, clients,
+        workingDirectory: entry.workingDirectory ? confirmedFolder(entry.workingDirectory, projectId, known) : null });
+    }
+    store().replaceShares(shares, port.idFactory);
+    await runner?.reconcileShares();
+    await publish().catch(onError);
+    return status();
+  }
+
+  // A folder is accepted only when FULI's own project resolution maps it to this project.
+  function confirmedFolder(folder, projectId, projects) {
+    let resolved;
+    try { resolved = resolveFolder(folder, projects); }
+    catch { throw new PeerError('invalid_folder', 'Choose an existing folder of this project', 422); }
+    if (resolved.personalProjectId !== projectId) {
+      throw new PeerError('invalid_folder', 'That folder does not belong to this project', 422);
+    }
+    return folder;
+  }
+
+  async function revokeDevice(nodeId) {
+    if (!coordinator) throw new PeerError('not_coordinator', 'Only the coordinator device revokes devices', 409);
+    coordinator.service.revoke(nodeId);
+    store().forgetAuthority(nodeId);
+    return status();
+  }
+
+  // Leaves the LAN roundtable. History stays; trust, sharing and listening end.
+  async function disable() {
+    const membership = store().setting('membership');
+    // A coordinator turned on again later must not silently trust old devices.
+    for (const device of coordinator?.service.devices() ?? []) {
+      if (!device.self && device.status === 'active') coordinator.service.revoke(device.nodeId);
+    }
+    await stopAll();
+    store().replaceShares([], port.idFactory);
+    store().forgetAuthorities();
+    store().setSetting('membership', null);
+    store().setSetting('coordinator', null);
+    if (membership?.role === 'member') store().setSetting('pendingLeave', membership.coordinator);
+    await finishLeaving();
+    return status();
+  }
+
+  // Local execution stops even if the coordinator is offline. Keep only the
+  // unpairing request until it can be delivered, without resuming any shares.
+  function finishLeaving() {
+    if (leaveWork) return leaveWork;
+    leaveWork = deliverLeave().finally(() => { leaveWork = null; leaveAbort = null; });
+    return leaveWork;
+  }
+
+  async function deliverLeave() {
+    clearTimeout(leaveRetry);
+    leaveRetry = null;
+    const previous = store().setting('pendingLeave');
+    if (!previous) return;
+    leaveAbort = new AbortController();
+    const identity = await loadDeviceIdentity(port.directory);
+    const client = createPeerClient({ identity, coordinator: previous });
+    try {
+      await client.post('/peer/1/leave', {}, { timeoutMs: 2_000, signal: leaveAbort.signal });
+      store().setSetting('pendingLeave', null);
+    } catch (error) {
+      if (leaveAbort.signal.aborted) return;
+      if (error.status === 403) store().setSetting('pendingLeave', null);
+      else {
+        onError(error);
+        leaveRetry = setTimeout(() => finishLeaving().catch(onError), PUBLISH_MS);
+        leaveRetry.unref();
+      }
+    } finally { client.close(); }
+  }
+
+  return { resume, status, enableCoordinator, createInvitation, previewInvitation, join, setShares, revokeDevice, disable,
+    publish, close: stopAll, runnerActive: () => Boolean(runner) };
+}

package/src/agent-peer/peer-transport.js

@@ -0,0 +1,78 @@
+import { Agent, request as httpsRequest } from 'node:https';
+
+import { PEER_LIMITS, PeerError, parseCoordinatorUrl, sha256Hex } from './protocol.js';
+
+// Talks to exactly one coordinator: trusted only through its pinned
+// certificate, never redirected, and always presenting this device's certificate.
+export function createPeerClient({ identity, coordinator }) {
+  const origin = parseCoordinatorUrl(coordinator.url);
+  const tls = pinnedTls(identity, coordinator);
+  const agent = new Agent({ ...tls, keepAlive: true, maxSockets: 4 });
+  return {
+    post: (path, body, options = {}) => post(origin, path, body, { ...options, agent }),
+    close: () => agent.destroy(),
+  };
+}
+
+// Pairing uses its own connection: the coordinator only trusts this device after it succeeds.
+export function pairWithCoordinator({ identity, authority, invitation, name, timeoutMs = 15_000 }) {
+  const coordinator = { url: invitation.url, certPem: invitation.certificatePem, fingerprint: invitation.fingerprint };
+  return post(parseCoordinatorUrl(invitation.url), '/peer/1/pair', { code: invitation.code, name, authority },
+    { agent: false, tls: pinnedTls(identity, coordinator), timeoutMs });
+}
+
+function pinnedTls(identity, coordinator) {
+  return {
+    ...identity.tlsOptions,
+    ca: [coordinator.certPem],
+    minVersion: 'TLSv1.3',
+    checkServerIdentity: (_host, certificate) => (certificate?.raw && sha256Hex(certificate.raw) === coordinator.fingerprint
+      ? undefined : new PeerError('fingerprint_mismatch', 'The coordinator certificate does not match the paired fingerprint', 502)),
+  };
+}
+
+function post(origin, path, body, { agent, tls = {}, timeoutMs = 15_000, signal } = {}) {
+  const url = new URL(path, origin);
+  const payload = Buffer.from(JSON.stringify(body ?? {}));
+  if (payload.length > PEER_LIMITS.requestBytes) return Promise.reject(new PeerError('payload_too_large', 'Request body is too large', 413));
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      if (error) { request.destroy(); reject(error); } else resolve(value);
+    };
+    // An absolute deadline covers slow headers, a stalled body and a half-closed TLS stream alike.
+    const deadline = setTimeout(() => settle(new PeerError('coordinator_timeout', 'The coordinator did not respond in time', 504)), timeoutMs);
+    const request = httpsRequest(url, { method: 'POST', agent, ...tls, signal,
+      headers: { 'content-type': 'application/json', 'content-length': payload.length } }, (response) => {
+      let size = 0;
+      const chunks = [];
+      response.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > PEER_LIMITS.responseBytes) settle(new PeerError('response_too_large', 'Coordinator response is too large', 502));
+        else chunks.push(chunk);
+      });
+      response.on('end', () => {
+        let value;
+        try { value = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { value = undefined; }
+        const object = value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+          return object ? settle(null, object) : settle(new PeerError('invalid_response', 'The coordinator sent an invalid response', 502));
+        }
+        settle(new PeerError(typeof object?.error === 'string' ? object.error : 'coordinator_error',
+          typeof object?.message === 'string' ? object.message : `Coordinator responded ${response.statusCode}`, response.statusCode));
+      });
+      const interrupted = () => settle(new PeerError('response_interrupted', 'The coordinator response was interrupted', 502));
+      response.on('aborted', interrupted);
+      response.on('error', interrupted);
+      response.on('close', () => { if (!response.complete) interrupted(); });
+    });
+    request.on('error', (error) => settle(error instanceof PeerError ? error
+      : error.code === 'ABORT_ERR' ? new PeerError('aborted', 'The request was cancelled', 499)
+      : /CERT|SELF_SIGNED|DEPTH|SSL|TLS|ECONNRESET/.test(String(error.code)) ? new PeerError('tls_rejected', 'The secure connection was rejected', 502)
+      : new PeerError('coordinator_unreachable', 'The coordinator is unreachable', 503)));
+    request.end(payload);
+  });
+}