@camstack/server 1.2.572 → 1.2.573

package/dist/agent/agent-http-auth.js

@@ -16,6 +16,8 @@
  *     through the pairing surface only; everything else stays denied.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasForwardingHeader = hasForwardingHeader;
+exports.isGenuineLoopback = isGenuineLoopback;
 exports.isLoopbackAddress = isLoopbackAddress;
 exports.bearerMatchesSecret = bearerMatchesSecret;
 exports.readBearerToken = readBearerToken;
@@ -23,7 +25,29 @@ exports.isAuthorizedAgentRequest = isAuthorizedAgentRequest;
 exports.isPairingRequest = isPairingRequest;
 exports.isUnlockSessionRequest = isUnlockSessionRequest;
 exports.isUnlockInfoRequest = isUnlockInfoRequest;
+exports.isPairingProtocolRequest = isPairingProtocolRequest;
 const node_crypto_1 = require("node:crypto");
+const FORWARDING_HEADERS = [
+    'forwarded',
+    'x-forwarded-for',
+    'x-forwarded-host',
+    'x-forwarded-proto',
+    'x-forwarded-port',
+    'x-real-ip',
+    'via',
+    'cf-connecting-ip',
+];
+/** True when any header says the request was relayed (D857): then loopback proves nothing. */
+function hasForwardingHeader(headers) {
+    return FORWARDING_HEADERS.some((name) => headers[name] !== undefined);
+}
+/**
+ * A request from this machine itself: a loopback peer AND no forwarding header. A reverse proxy on
+ * the same host makes every caller look like 127.0.0.1; the header it adds is what gives it away.
+ */
+function isGenuineLoopback(input) {
+    return input.forwarded !== true && isLoopbackAddress(input.remoteAddress);
+}
 /** IPv4/IPv6 loopback (incl. the IPv4-mapped IPv6 form Node reports). */
 function isLoopbackAddress(addr) {
     if (!addr)
@@ -62,11 +86,11 @@ function readBearerToken(authorization) {
  * `sessionTokenOk` admits a hub-minted unlock session (D821).
  */
 function isAuthorizedAgentRequest(input, clusterSecret, sessionTokenOk = () => false) {
-    if (isLoopbackAddress(input.remoteAddress))
+    if (isGenuineLoopback(input))
         return true;
-    if (clusterSecret === null || clusterSecret.length === 0)
-        return false;
-    if (bearerMatchesSecret(input.authorization, clusterSecret))
+    // A secretless agent (paired by certificate, D857) is still reachable through a hub-unlocked session.
+    const hasSecret = clusterSecret !== null && clusterSecret.length > 0;
+    if (hasSecret && bearerMatchesSecret(input.authorization, clusterSecret))
         return true;
     const token = readBearerToken(input.authorization);
     return token !== null && sessionTokenOk(token);
@@ -77,7 +101,9 @@ function isAuthorizedAgentRequest(input, clusterSecret, sessionTokenOk = () => f
  * trigger the reconnect). Process control and health details are NEVER
  * part of it. Only consulted while the agent has no secret configured.
  */
-function isPairingRequest(method, urlPath) {
+function isPairingRequest(method, urlPath, 
+/** Pairing exists: the first-boot surface is read-only, writes need loopback or a hub session (D857). */
+readOnly = false) {
     const pathOnly = urlPath.split('?')[0] ?? urlPath;
     if (method === 'GET') {
         return (pathOnly === '/api/agent/status' ||
@@ -85,7 +111,7 @@ function isPairingRequest(method, urlPath) {
             pathOnly === '/api/agent/discovered-nodes' ||
             pathOnly === '/api/agent/hubs-found');
     }
-    if (method === 'POST') {
+    if (method === 'POST' && !readOnly) {
         return (pathOnly === '/api/agent/config' ||
             pathOnly === '/api/agent/restart' ||
             pathOnly === '/api/agent/hubs-found/refresh');
@@ -108,3 +134,30 @@ function isUnlockInfoRequest(method, urlPath) {
     const pathOnly = urlPath.split('?')[0] ?? urlPath;
     return method === 'GET' && pathOnly === '/api/agent/unlock-info';
 }
+const PAIRING_GET = new Set([
+    '/api/agent/pairing/hello',
+    '/api/agent/pairing/status',
+]);
+const PAIRING_POST = new Set([
+    '/api/agent/pairing/offer',
+    '/api/agent/pairing/reveal',
+    '/api/agent/pairing/poll',
+    '/api/agent/pairing/reset',
+    '/api/agent/pairing/cancel',
+    '/api/agent/pairing/confirm',
+    '/api/agent/pairing/reject',
+    '/api/agent/pairing/complete',
+]);
+/**
+ * The pairing protocol endpoints (D857): reachable from the network without a session, each
+ * authorized by what it carries (a pairing id the agent made up, a proof the mesh CA signed).
+ * `forget` is NOT among them - leaving a hub is an authenticated action.
+ */
+function isPairingProtocolRequest(method, urlPath) {
+    const pathOnly = urlPath.split('?')[0] ?? urlPath;
+    if (method === 'GET')
+        return PAIRING_GET.has(pathOnly);
+    if (method === 'POST')
+        return PAIRING_POST.has(pathOnly);
+    return false;
+}

package/dist/agent/agent-http.js

@@ -41,6 +41,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pickIpv4 = void 0;
+exports.describePairedHub = describePairedHub;
 exports.compareVersions = compareVersions;
 exports.readUiDistCandidate = readUiDistCandidate;
 exports.pickUiDist = pickUiDist;
@@ -66,6 +67,19 @@ const derive_hub_url_js_1 = require("./derive-hub-url.js");
 Object.defineProperty(exports, "pickIpv4", { enumerable: true, get: function () { return derive_hub_url_js_1.pickIpv4; } });
 const agent_addon_runtime_js_1 = require("./agent-addon-runtime.js");
 const hubs_found_js_1 = require("./hubs-found.js");
+const agent_pairing_routes_js_1 = require("./agent-pairing-routes.js");
+const agent_pairing_store_js_1 = require("./agent-pairing-store.js");
+/** The pinned CA's fingerprint, or `null` when none is pinned or the PEM cannot be read. */
+function describePairedHub(pinnedCa, hubHttpsOrigin) {
+    if (pinnedCa === null)
+        return null;
+    try {
+        return { url: hubHttpsOrigin, caFingerprint: (0, system_1.caFingerprintCompact)(pinnedCa) };
+    }
+    catch {
+        return null;
+    }
+}
 /** Dotted-numeric version compare; `null` sorts lowest. */
 function compareVersions(a, b) {
     if (a === null && b === null)
@@ -246,7 +260,14 @@ function getEffectiveConfig(configPath, nodeId) {
     };
 }
 /** Persisted fields that are credentials: never echoed by `GET /api/agent/config`. */
-const NEVER_ECHOED_CONFIG_KEYS = new Set(['secret', 'meshTls', 'joinToken']);
+const NEVER_ECHOED_CONFIG_KEYS = new Set([
+    'secret',
+    'meshTls',
+    'meshTlsPrevious',
+    'joinToken',
+]);
+/** Clock skew allowed between the hub that issued a ticket and this agent's boot instant. */
+const TICKET_BOOT_SKEW_MS = 2 * 60_000;
 const defaultRedeemJoinToken = (token, nodeId) => (0, agent_mesh_enroll_js_1.enrollAgentMesh)({ token, nodeId });
 // ---------------------------------------------------------------------------
 // Factory
@@ -264,14 +285,34 @@ async function createAgentHttpServer(getBroker, config) {
         const raw = readConfigFile(config.configPath);
         return typeof raw.secret === 'string' && raw.secret.length > 0 ? raw.secret : null;
     };
-    /** Tab sessions from hub unlock tickets — token → expiry ms. */
+    /**
+     * Tab sessions from hub unlock tickets. A session is bound to what vouched for it - the mesh CA
+     * (by fingerprint) or the cluster secret - and dies the moment that changes: forgetting the hub
+     * or pairing with another one ends every session, not just the old Bearer (D857).
+     */
     const unlockSessions = new Map();
-    const unlockJtis = new system_1.UnlockTicketJtiStore();
+    let unlockJtis = new system_1.UnlockTicketJtiStore();
+    let jtiBinding = null;
+    const bootMs = Date.now();
+    /** What would vouch for a session now: the pinned CA, else the secret, else nothing. */
+    const caBinding = () => {
+        const ca = (0, agent_pairing_store_js_1.pinnedMeshCaCert)(config.configPath);
+        return ca === null ? null : `ca:${(0, system_1.caFingerprintCompact)(ca)}`;
+    };
+    const secretBinding = () => {
+        const secret = currentSecret();
+        return secret === null ? null : `secret:${(0, system_1.hashClusterSecret)(secret)}`;
+    };
     const sessionOk = (token) => {
-        const exp = unlockSessions.get(token);
-        if (exp === undefined)
+        const entry = unlockSessions.get(token);
+        if (entry === undefined)
             return false;
-        if (exp <= Date.now()) {
+        if (entry.exp <= Date.now()) {
+            unlockSessions.delete(token);
+            return false;
+        }
+        const current = entry.binding.startsWith('ca:') ? caBinding() : secretBinding();
+        if (current !== entry.binding) {
             unlockSessions.delete(token);
             return false;
         }
@@ -282,23 +323,35 @@ async function createAgentHttpServer(getBroker, config) {
         const isProtected = pathOnly.startsWith('/api/') || pathOnly.startsWith('/health/');
         if (!isProtected)
             return;
+        if ((0, agent_http_auth_js_1.isPairingProtocolRequest)(req.method, pathOnly))
+            return;
         const secret = currentSecret();
-        if (secret !== null && (0, agent_http_auth_js_1.isUnlockSessionRequest)(req.method, pathOnly))
+        // Paired = holds the cluster secret OR a mesh certificate (D857): either closes the open surface.
+        const locked = secret !== null || (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath);
+        if (locked && (0, agent_http_auth_js_1.isUnlockSessionRequest)(req.method, pathOnly))
             return;
         if ((0, agent_http_auth_js_1.isUnlockInfoRequest)(req.method, pathOnly))
             return;
         const authInput = {
             remoteAddress: req.socket.remoteAddress ?? undefined,
+            forwarded: (0, agent_http_auth_js_1.hasForwardingHeader)(req.headers),
             ...(typeof req.headers.authorization === 'string'
                 ? { authorization: req.headers.authorization }
                 : {}),
         };
         if ((0, agent_http_auth_js_1.isAuthorizedAgentRequest)(authInput, secret, sessionOk))
             return;
-        if (secret === null && (0, agent_http_auth_js_1.isPairingRequest)(req.method, pathOnly))
+        if (!locked && (0, agent_http_auth_js_1.isPairingRequest)(req.method, pathOnly, config.pairing !== undefined))
             return;
         return reply.status(401).send({ ok: false, error: 'unauthorized' });
     });
+    if (config.pairing !== undefined) {
+        (0, agent_pairing_routes_js_1.registerAgentPairingRoutes)(app, {
+            pairing: config.pairing,
+            onForgetHub: config.onForgetHub ?? (async () => undefined),
+            log: (message) => config.log?.info(message),
+        });
+    }
     // -- Health ---------------------------------------------------------
     // PUBLIC probe: liveness only — `{ok}`, no nodeId/version/topology (a
     // public endpoint must not enumerate the deployment; same policy as the
@@ -355,6 +408,8 @@ async function createAgentHttpServer(getBroker, config) {
         // when the agent runs headless / in Docker.
         const appVersion = process.env['CAMSTACK_AGENT_APP_VERSION'] ?? null;
         const discoveredNodes = mapDiscoveredNodes(nodes, broker.nodeID);
+        // The hub this agent is paired with, for the agent UI's "Paired with" card (D857).
+        const pairedHub = describePairedHub((0, agent_pairing_store_js_1.pinnedMeshCaCert)(config.configPath), hubHttpsOrigin);
         try {
             const status = (await broker.call('$agent.status'));
             return {
@@ -367,6 +422,8 @@ async function createAgentHttpServer(getBroker, config) {
                 hubConnected,
                 hubConnectionState,
                 hasSecret: eff.hasSecret,
+                paired: (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath),
+                pairedHub,
                 meshTransport,
                 discoveredNodes,
             };
@@ -382,6 +439,8 @@ async function createAgentHttpServer(getBroker, config) {
                 hubConnected,
                 hubConnectionState,
                 hasSecret: eff.hasSecret,
+                paired: (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath),
+                pairedHub,
                 meshTransport,
                 discoveredNodes,
                 addons: [],
@@ -399,7 +458,7 @@ async function createAgentHttpServer(getBroker, config) {
             (resolvedHubAddress !== null ? (0, derive_hub_url_js_1.deriveHubUrlFromHubAddress)(resolvedHubAddress) : undefined) ??
             null;
         return {
-            paired: secret !== null,
+            paired: secret !== null || (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath),
             nodeId: config.nodeId,
             hubHttpsOrigin,
         };
@@ -407,26 +466,42 @@ async function createAgentHttpServer(getBroker, config) {
     // -- Unlock session (hub admin ticket → tab Bearer; D821) -----------
     app.post('/api/agent/session', async (req, reply) => {
         const secret = currentSecret();
-        if (secret === null) {
+        const pinnedCa = (0, agent_pairing_store_js_1.pinnedMeshCaCert)(config.configPath);
+        if (secret === null && pinnedCa === null) {
             return reply.status(400).send({ ok: false, error: 'agent is not paired' });
         }
         const ticket = typeof req.body?.ticket === 'string' ? req.body.ticket.trim() : '';
         if (ticket.length === 0) {
             return reply.status(400).send({ ok: false, error: 'ticket required' });
         }
-        const payload = (0, system_1.verifyAgentUiUnlockTicket)((0, system_1.hashClusterSecret)(secret), ticket, {
+        // Two forms are accepted in the transition release (D857): signed by the mesh CA this agent
+        // pinned (ES256), or the older HMAC under the cluster secret.
+        // Nothing issued before this process started is accepted: the one-use ledger is in memory.
+        const options = {
             expectedNodeId: config.nodeId,
-        });
-        if (payload === null) {
+            notBeforeMs: bootMs - TICKET_BOOT_SKEW_MS,
+        };
+        const es256 = pinnedCa !== null ? (0, system_1.verifyAgentUiUnlockTicketEs256)(pinnedCa, ticket, options) : null;
+        const hmac = es256 === null && secret !== null
+            ? (0, system_1.verifyAgentUiUnlockTicket)((0, system_1.hashClusterSecret)(secret), ticket, options)
+            : null;
+        const payload = es256 ?? hmac;
+        const binding = es256 !== null ? caBinding() : secretBinding();
+        if (payload === null || binding === null) {
             return reply.status(401).send({ ok: false, error: 'invalid or expired unlock ticket' });
         }
+        // A new vouching CA or secret starts a new ledger.
+        if (jtiBinding !== binding) {
+            unlockJtis = new system_1.UnlockTicketJtiStore();
+            jtiBinding = binding;
+        }
         if (!unlockJtis.consume(payload.jti, payload.exp)) {
             return reply.status(401).send({ ok: false, error: 'unlock ticket already used' });
         }
         const token = (0, node_crypto_1.randomBytes)(32).toString('base64url');
         // Session outlives the ticket so the tab keeps working after redeem.
         const sessionExp = Date.now() + 8 * 60 * 60_000;
-        unlockSessions.set(token, sessionExp);
+        unlockSessions.set(token, { exp: sessionExp, binding });
         return { ok: true, token, expiresAt: sessionExp };
     });
     // -- Processes ------------------------------------------------------
@@ -489,12 +564,15 @@ async function createAgentHttpServer(getBroker, config) {
         const clearMeshTls = body['clearMeshTls'] === true;
         const patch = Object.fromEntries(Object.entries(body).filter(([k]) => k !== 'joinToken' && k !== 'meshTls' && k !== 'clearMeshTls'));
         const existing = readConfigFile(config.configPath);
-        const alreadyPaired = typeof existing.secret === 'string' && existing.secret.length > 0;
+        const alreadyPaired = (typeof existing.secret === 'string' && existing.secret.length > 0) ||
+            (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath);
         const patchSecret = typeof patch['secret'] === 'string' && patch['secret'].trim().length > 0;
         const hasJoinToken = typeof joinToken === 'string' && joinToken.trim().length > 0;
         // First pairing (D803 / D821): hub always has a secret — require secret or
         // join token. Later edits may omit secret to keep the stored value.
-        if (!alreadyPaired && !patchSecret && !hasJoinToken) {
+        // A rename alone is not a pairing: it is allowed before the agent is paired (D857).
+        const renameOnly = Object.keys(patch).every((k) => k === 'name');
+        if (!alreadyPaired && !patchSecret && !hasJoinToken && !renameOnly) {
             return reply.status(400).send({
                 success: false,
                 error: 'Cluster secret is required — copy it from the hub System → Cluster page, or paste a join token',

package/dist/agent/agent-mesh-join.js

@@ -41,6 +41,8 @@ function createAgentMeshJoin(opts) {
     const authenticator = new system_1.AgentMeshAuthenticator({
         ownNodeId: opts.nodeId,
         hubNodeId: HUB_NODE_ID,
+        ...(opts.isVerifiedPeer !== undefined ? { isVerifiedPeer: opts.isVerifiedPeer } : {}),
+        ...(opts.isPaired !== undefined ? { isPaired: opts.isPaired } : {}),
         hasSecret: () => {
             const s = opts.secret();
             return s !== null && s.length > 0;

package/dist/agent/agent-node-certificates.js

@@ -254,6 +254,11 @@ function createAgentNodeCertificates(deps) {
             return { confirmed: true };
         },
         rollbackMeshLeaf: async () => ({ rolledBack: revert('the hub asked for a rollback') }),
+        forgetHub: async () => {
+            log.warn('The hub unpaired this agent', { tags });
+            deps.forgetHub();
+            return { ok: true };
+        },
         prepareHttpsCertificate: async () => {
             const names = (0, system_1.collectAgentNames)(nodeId, deps.hostFacts);
             const request = await (0, system_1.createAgentHttpsRequest)(deps.dataDir, nodeId, names);

package/dist/agent/agent-pairing-local.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAIRING_RESET_FILE = exports.PAIRING_PIN_FILE = void 0;
+exports.createLocalPairingAnnouncer = createLocalPairingAnnouncer;
+/**
+ * Where a pairing's one-time PIN, the agent's own code and the reset code are shown: ONLY on the
+ * agent's machine (D857).
+ *
+ * The agent's page is opened from another PC and its API is reachable by the whole LAN, so anything
+ * shown there could be read and used by anyone. The operator reads these things at the machine
+ * instead - the process console (`docker logs` for a container), a 0600 file in the data dir, and the
+ * desktop window (which asks the agent's loopback `status`) - and types the hub's code and the PIN
+ * into the page.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_1 = require("@camstack/types/node");
+exports.PAIRING_PIN_FILE = 'pairing-pin.txt';
+exports.PAIRING_RESET_FILE = 'pairing-reset.txt';
+function describe(s) {
+    const fp = s.hub.caFingerprint.slice(0, 16);
+    return [
+        `Pairing request from hub "${s.hub.nodeId}" (${s.hub.url}), CA ${fp}`,
+        `  PIN:        ${s.pin}   (type it on this agent's page with the code the HUB shows)`,
+        `  this agent's code: ${s.code ?? '(not known yet - the hub has not revealed its nonce)'}   (type it on the hub)`,
+        `  expires:    ${new Date(s.expiresAt).toISOString()}`,
+    ].join('\n');
+}
+/**
+ * Keep `pairing-pin.txt` (0600) and the console in step with the pending pairings. The file always
+ * holds exactly the live ones and is removed when none is left - and a stale one left by a previous
+ * run is removed here, at boot. A PIN is never logged anywhere else.
+ */
+function createLocalPairingAnnouncer(dataDir, log) {
+    const file = path.join(dataDir, exports.PAIRING_PIN_FILE);
+    const resetFile = path.join(dataDir, exports.PAIRING_RESET_FILE);
+    const live = new Map();
+    const flush = () => {
+        try {
+            if (live.size === 0) {
+                fs.rmSync(file, { force: true });
+                return;
+            }
+            fs.mkdirSync(dataDir, { recursive: true });
+            (0, node_1.writeOwnerOnlyFileSync)(file, `${[...live.values()].map(describe).join('\n\n')}\n`);
+        }
+        catch (err) {
+            log.warn(`could not write ${file}: ${err instanceof Error ? err.message : String(err)} - the PIN is in the console above`);
+        }
+    };
+    // A PIN file from a previous run belongs to pairings that no longer exist.
+    flush();
+    return {
+        onSecret(secret) {
+            live.set(secret.pairingId, secret);
+            // The console is the agent's own stdout: `docker logs`, the service journal, the desktop log.
+            log.warn(`\n${describe(secret)}\n  (also in ${file})`);
+            flush();
+        },
+        onCleared(pairingId) {
+            if (live.delete(pairingId))
+                flush();
+        },
+        onResetCode(code) {
+            log.warn(`\nPairing reset code: ${code}\n  (clears pairing lockouts and pending offers: POST /api/agent/pairing/reset {"code": ...}; also in ${resetFile})`);
+            try {
+                fs.mkdirSync(dataDir, { recursive: true });
+                (0, node_1.writeOwnerOnlyFileSync)(resetFile, `${code}\n`);
+            }
+            catch (err) {
+                log.warn(`could not write ${resetFile}: ${err instanceof Error ? err.message : String(err)} - the code is in the console above`);
+            }
+        },
+    };
+}

package/dist/agent/agent-pairing-routes.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLocalRequest = isLocalRequest;
+exports.registerAgentPairingRoutes = registerAgentPairingRoutes;
+const system_1 = require("@camstack/system");
+const agent_http_auth_js_1 = require("./agent-http-auth.js");
+const OFFER_WINDOW_MS = 60_000;
+const DEFAULT_OFFERS_PER_MINUTE = 10;
+const MAX_TRACKED_SOURCES = 512;
+/** True for a request from this machine itself: loopback peer, no forwarding header. */
+function isLocalRequest(req) {
+    return (0, agent_http_auth_js_1.isGenuineLoopback)({
+        remoteAddress: req.socket.remoteAddress ?? undefined,
+        forwarded: (0, agent_http_auth_js_1.hasForwardingHeader)(req.headers),
+    });
+}
+function send(reply, result) {
+    if (result.ok)
+        return result;
+    const failure = result;
+    if (failure.retryAfterMs !== undefined) {
+        void reply.header('retry-after', String(Math.ceil(failure.retryAfterMs / 1000)));
+    }
+    return reply.status(failure.status).send({
+        ok: false,
+        error: failure.error,
+        message: failure.message,
+        ...(failure.retryAfterMs !== undefined ? { retryAfterMs: failure.retryAfterMs } : {}),
+    });
+}
+function registerAgentPairingRoutes(app, deps) {
+    const { pairing } = deps;
+    const now = deps.now ?? Date.now;
+    const limit = deps.offersPerMinute ?? DEFAULT_OFFERS_PER_MINUTE;
+    const offersBySource = new Map();
+    /** At most `limit` offers per source per minute, counted before the offer is even parsed. */
+    const rateLimited = (source) => {
+        const at = now();
+        const recent = (offersBySource.get(source) ?? []).filter((t) => at - t < OFFER_WINDOW_MS);
+        if (offersBySource.size >= MAX_TRACKED_SOURCES && !offersBySource.has(source)) {
+            offersBySource.clear();
+        }
+        if (recent.length >= limit) {
+            offersBySource.set(source, recent);
+            return true;
+        }
+        offersBySource.set(source, [...recent, at]);
+        return false;
+    };
+    app.get(system_1.PAIRING_PATHS.hello, async () => pairing.hello());
+    // The network sees who asks; the agent's own machine sees the secrets.
+    app.get(system_1.PAIRING_PATHS.status, async (req) => isLocalRequest(req) ? pairing.localView() : pairing.publicView());
+    app.post(system_1.PAIRING_PATHS.offer, async (req, reply) => {
+        if (rateLimited(req.socket.remoteAddress ?? 'unknown')) {
+            deps.log(`pairing offers from ${req.socket.remoteAddress ?? 'unknown'} are rate limited`);
+            return reply.status(429).header('retry-after', '60').send({
+                ok: false,
+                error: 'rate-limited',
+                message: 'too many pairing offers from this address - wait a minute',
+            });
+        }
+        return send(reply, await pairing.offer(req.body));
+    });
+    app.post(system_1.PAIRING_PATHS.reveal, async (req, reply) => send(reply, pairing.reveal(req.body)));
+    app.post(system_1.PAIRING_PATHS.poll, async (req, reply) => send(reply, pairing.poll(req.body)));
+    app.post(system_1.PAIRING_PATHS.cancel, async (req, reply) => send(reply, pairing.cancel(req.body)));
+    app.post(system_1.PAIRING_PATHS.complete, async (req, reply) => send(reply, await pairing.complete(req.body)));
+    const contextOf = (req) => ({
+        local: isLocalRequest(req),
+        source: req.socket.remoteAddress ?? 'unknown',
+    });
+    app.post(system_1.PAIRING_PATHS.confirm, async (req, reply) => send(reply, pairing.confirm(req.body, contextOf(req))));
+    app.post(system_1.PAIRING_PATHS.reject, async (req, reply) => send(reply, pairing.reject(req.body, contextOf(req))));
+    // Clears the offer lockouts and pending offers: this machine, or the reset code printed at boot.
+    app.post(system_1.PAIRING_PATHS.reset, async (req, reply) => send(reply, pairing.reset(req.body, contextOf(req))));
+    // Authenticated by the onRequest hook (not a protocol path): this machine or a hub session.
+    app.post(system_1.PAIRING_PATHS.forget, async (_req, reply) => {
+        if (pairing.state() !== 'paired') {
+            return reply
+                .status(409)
+                .send({ ok: false, error: 'not-paired', message: 'this agent is not paired' });
+        }
+        deps.log('Forgetting the hub on request (agent UI or local call)');
+        await deps.onForgetHub();
+        return { ok: true };
+    });
+}

package/dist/agent/agent-pairing-store.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAgentPaired = isAgentPaired;
+exports.pinnedMeshCaCert = pinnedMeshCaCert;
+exports.persistPairing = persistPairing;
+exports.forgetPairing = forgetPairing;
+exports.pairedLeafFingerprint = pairedLeafFingerprint;
+/**
+ * What pairing writes to, and removes from, `agent.json` (D857). The file is
+ * 0600 on every OS; this module only ever touches the keys named below. An older
+ * `secret` field is neither read nor removed here — the operator deletes it.
+ */
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const system_1 = require("@camstack/system");
+const agent_mesh_enroll_js_1 = require("./agent-mesh-enroll.js");
+/** Keys that exist only while this agent is paired. */
+const PAIRED_KEYS = ['meshTls', 'meshTlsPrevious', 'meshSwap', 'hubAddress'];
+/** `agent.json` holds mesh material: the agent is paired. */
+function isAgentPaired(configPath) {
+    const meshTls = (0, agent_mesh_enroll_js_1.readJsonFile)(configPath)['meshTls'];
+    return (meshTls !== null &&
+        typeof meshTls === 'object' &&
+        typeof Reflect.get(meshTls, 'certPem') === 'string' &&
+        typeof Reflect.get(meshTls, 'keyPem') === 'string' &&
+        typeof Reflect.get(meshTls, 'caCertPem') === 'string');
+}
+/** The CA certificate this agent pinned at pairing, or `null` while unpaired. */
+function pinnedMeshCaCert(configPath) {
+    const meshTls = (0, agent_mesh_enroll_js_1.readJsonFile)(configPath)['meshTls'];
+    if (meshTls === null || typeof meshTls !== 'object')
+        return null;
+    const ca = Reflect.get(meshTls, 'caCertPem');
+    return typeof ca === 'string' && ca.length > 0 ? ca : null;
+}
+/** Persist a completed pairing: the leaf, its key, the pinned CA and the hub's host. */
+function persistPairing(configPath, pairing) {
+    const { joinToken: _joinToken, meshTlsPrevious: _previous, meshSwap: _swap, ...existing } = (0, agent_mesh_enroll_js_1.readJsonFile)(configPath);
+    (0, agent_mesh_enroll_js_1.writeJsonFile0600)(configPath, {
+        ...existing,
+        hubAddress: pairing.hubAddress,
+        meshTls: pairing.meshTls,
+    });
+}
+/**
+ * Leave the hub: erase the mesh material, the hub address and the HTTPS bundle
+ * the hub issued. The agent is unpaired afterwards and accepts offers again.
+ */
+function forgetPairing(configPath, dataDir) {
+    const existing = (0, agent_mesh_enroll_js_1.readJsonFile)(configPath);
+    (0, agent_mesh_enroll_js_1.writeJsonFile0600)(configPath, Object.fromEntries(Object.entries(existing).filter(([key]) => !PAIRED_KEYS.includes(key))));
+    const https = (0, system_1.agentHttpsPaths)(dataDir);
+    for (const file of [https.bundlePath, https.certPath, https.pendingKeyPath]) {
+        fs.rmSync(file, { force: true });
+    }
+}
+/** First 16 hex chars of the SHA-256 of the agent's mesh leaf, `null` while unpaired. */
+function pairedLeafFingerprint(configPath) {
+    const meshTls = (0, agent_mesh_enroll_js_1.readJsonFile)(configPath)['meshTls'];
+    const certPem = meshTls !== null && typeof meshTls === 'object' ? Reflect.get(meshTls, 'certPem') : null;
+    if (typeof certPem !== 'string')
+        return null;
+    try {
+        return new node_crypto_1.X509Certificate(certPem).fingerprint256
+            .replaceAll(':', '')
+            .toLowerCase()
+            .slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}