@camstack/system 1.2.432 → 1.2.434

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,12 +1,12 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM, r as __exportAll, t as __commonJSMin } from "../../chunk-CNf5ZN-e.mjs";
-import { Br as hydrateSchema, Fr as defineCustomActions, Gr as isSecretMarker, Pr as customAction, Wr as isSecretClear, _r as BaseAddon, ci as transformSecretWrite, gr as errMsg, ii as secretTreeFromSchema, qr as makeSecretMarker } from "../../dist-Bt8GTRHB.mjs";
+import { Jr as isSecretMarker, Lr as customAction, Rr as defineCustomActions, Ur as hydrateSchema, Xr as makeSecretMarker, br as BaseAddon, di as transformSecretWrite, qr as isSecretClear, si as secretTreeFromSchema, yr as errMsg } from "../../dist-CYcBqnXk.mjs";
 import { t as require_safe_buffer } from "../../safe-buffer-B1OjL1I9.mjs";
-import { a as KeyUsagesExtension, c as Pkcs10CertificateRequestGenerator, d as X509Certificate$1, f as X509CertificateGenerator, i as KeyUsageFlags, n as BasicConstraintsExtension, o as PemConverter, p as cryptoProvider, r as ExtendedKeyUsageExtension, s as Pkcs10CertificateRequest, t as AuthorityKeyIdentifierExtension, u as SubjectKeyIdentifierExtension } from "../../x509.es-CAjSsrkk.mjs";
-import { a as setProcessAgentHttpsNames, n as AGENT_HTTPS_NAMES_COLUMNS, r as AgentHttpsNames, t as AGENT_HTTPS_NAMES_COLLECTION } from "../../agent-https-names-uetr4OQl.mjs";
-import { a as MESH_CA_KEY_REF, b as setProcessClusterSecretGate, c as MESH_JOIN_TOKEN_MAX_TTL_SEC, d as CLUSTER_SECRET_REF, i as MESH_CA_FIELD, l as SERVER_AUTH_OID, n as DEFAULT_HUB_TLS_TCP_PORT, o as MESH_CA_SETTINGS_KEY, r as MESH_CA_COMMON_NAME, s as MESH_CA_VALIDITY_DAYS, t as CLIENT_AUTH_OID, v as hashClusterSecret } from "../../constants-B89vjrSm.mjs";
+import { a as KeyUsagesExtension, c as Pkcs10CertificateRequestGenerator, d as X509Certificate$1, f as X509CertificateGenerator, g as backdatedNotBefore, i as KeyUsageFlags, n as BasicConstraintsExtension, o as PemConverter, p as cryptoProvider, r as ExtendedKeyUsageExtension, s as Pkcs10CertificateRequest, t as AuthorityKeyIdentifierExtension, u as SubjectKeyIdentifierExtension } from "../../x509.es-CDvj67p1.mjs";
+import { A as AgentHttpsNames, M as setProcessAgentHttpsNames, O as AGENT_HTTPS_NAMES_COLLECTION, d as isPrivateAddress, j as getProcessAgentHttpsNames, k as AGENT_HTTPS_NAMES_COLUMNS, u as isLocalOnlyHostname } from "../../agent-https-B8lKYVtU.mjs";
+import { a as MESH_CA_KEY_REF, b as setProcessClusterSecretGate, c as MESH_JOIN_TOKEN_MAX_TTL_SEC, d as CLUSTER_SECRET_REF, i as MESH_CA_FIELD, l as SERVER_AUTH_OID, n as DEFAULT_HUB_TLS_TCP_PORT, o as MESH_CA_SETTINGS_KEY, r as MESH_CA_COMMON_NAME, s as MESH_CA_VALIDITY_DAYS, t as CLIENT_AUTH_OID, v as hashClusterSecret } from "../../constants-CrMPWOug.mjs";
 import { t as require_src } from "../../src-hG4grMU4.mjs";
 import { z } from "zod";
-import { X509Certificate, createHash, createHmac, randomBytes, timingSafeEqual, webcrypto } from "node:crypto";
+import { X509Certificate, createHash, createHmac, createPrivateKey, randomBytes, randomInt, sign, timingSafeEqual, verify, webcrypto } from "node:crypto";
 import { BlockList, isIP } from "node:net";
 import { lstat, readdir, readlink, realpath } from "node:fs/promises";
 import { posix, win32 } from "node:path";
@@ -158,6 +158,12 @@ function getProcessMeshAuthStatus() {
 */
 var AGENT_UI_UNLOCK_DOMAIN = "camstack-agent-ui-unlock/v1";
 var AGENT_UI_UNLOCK_VERSION = 1;
+/**
+* D857 (transition release): a ticket signed by the MESH CA key (ES256 JWS) is accepted by an agent
+* IN ADDITION to the HMAC ticket. The removal release mints only this form.
+*/
+var AGENT_UI_UNLOCK_TYP = "camstack-agent-ui-unlock+jwt";
+var AGENT_UI_UNLOCK_USE = "agent-ui-unlock";
 /** Ticket lifetime — long enough for a redirect hop, short enough to steal poorly. */
 var AGENT_UI_UNLOCK_TTL_MS = 5 * 6e4;
 /**
@@ -193,11 +199,18 @@ function mintAgentUiUnlockTicket(input) {
 	const payload = {
 		v: 1,
 		nodeId: input.nodeId,
+		iat: nowMs,
 		exp: nowMs + ttl,
 		jti: input.jti ?? randomBytes(16).toString("base64url")
 	};
 	const payloadB64 = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
-	return `${payloadB64}.${sign(input.secretHash, payloadB64)}`;
+	return `${payloadB64}.${sign$1(input.secretHash, payloadB64)}`;
+}
+/** A ticket is issued now-ish, lives at most the TTL, and not before `notBeforeMs`. */
+function issuedSanely(payload, nowMs, notBeforeMs) {
+	if (payload.iat > nowMs + 6e4) return false;
+	if (payload.exp - payload.iat > 3e5) return false;
+	return notBeforeMs === void 0 || payload.iat >= notBeforeMs;
 }
 /**
 * Verify a ticket under `secretHash`. Returns the payload, or `null` when the
@@ -209,7 +222,7 @@ function verifyAgentUiUnlockTicket(secretHash, ticket, options) {
 	if (dot <= 0 || dot === ticket.length - 1) return null;
 	const payloadB64 = ticket.slice(0, dot);
 	const sig = ticket.slice(dot + 1);
-	if (!sigsEqual(sign(secretHash, payloadB64), sig)) return null;
+	if (!sigsEqual(sign$1(secretHash, payloadB64), sig)) return null;
 	let parsed;
 	try {
 		parsed = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
@@ -220,6 +233,7 @@ function verifyAgentUiUnlockTicket(secretHash, ticket, options) {
 	if (payload === null) return null;
 	if (payload.exp <= nowMs) return null;
 	if (payload.nodeId !== options.expectedNodeId) return null;
+	if (!issuedSanely(payload, nowMs, options.notBeforeMs)) return null;
 	return payload;
 }
 /**
@@ -237,11 +251,29 @@ function isAllowedAgentDashboardReturnTo(returnTo, extraOrigins = []) {
 	if (url.protocol !== "http:" && url.protocol !== "https:") return false;
 	if (url.username !== "" || url.password !== "") return false;
 	if (url.pathname !== "/" && url.pathname !== "") return false;
-	if (url.port === "4444") return true;
+	const host = url.hostname.replace(/^\[|\]$/g, "");
+	const local = host === "localhost" || isPrivateAddress(host) || isLocalOnlyHostname(host);
+	if (url.port === "4444") return local;
 	const origin = url.origin;
 	return extraOrigins.some((o) => o === origin);
 }
 /** Parse a stored comma/whitespace-separated origins list. */
+/**
+* True when `returnTo` points at an address the hub itself knows for the node (`knownNames`: its id
+* and the address of its live mesh socket), or at an origin the operator listed. `knownNames` of
+* `null` (nothing recorded for the node yet) refuses.
+*/
+function isKnownAgentAddress(returnTo, knownNames, listedOrigins = []) {
+	let url;
+	try {
+		url = new URL(returnTo);
+	} catch {
+		return false;
+	}
+	if (listedOrigins.includes(url.origin)) return true;
+	if (knownNames === null) return false;
+	return knownNames.includes(url.hostname.replace(/^\[|\]$/g, "").toLowerCase());
+}
 function parseAgentDashboardOrigins(stored) {
 	if (typeof stored !== "string" || stored.trim().length === 0) return [];
 	const out = [];
@@ -255,7 +287,7 @@ function parseAgentDashboardOrigins(stored) {
 	}
 	return out;
 }
-function sign(secretHash, payloadB64) {
+function sign$1(secretHash, payloadB64) {
 	return createHmac("sha256", Buffer.from(secretHash, "utf8")).update(`${AGENT_UI_UNLOCK_DOMAIN}|${payloadB64}`, "utf8").digest("base64url");
 }
 function sigsEqual(expected, presented) {
@@ -274,15 +306,108 @@ function parsePayload(value) {
 	if (typeof nodeId !== "string" || nodeId.length === 0) return null;
 	if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
 	if (typeof jti !== "string" || jti.length === 0) return null;
+	const iat = rec["iat"];
 	return {
 		v: 1,
 		nodeId,
+		iat: typeof iat === "number" && Number.isFinite(iat) ? iat : exp - AGENT_UI_UNLOCK_TTL_MS,
+		exp,
+		jti
+	};
+}
+function b64urlJsonEs256(value) {
+	return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+function mintAgentUiUnlockTicketEs256(input) {
+	const nowMs = input.nowMs ?? Date.now();
+	const ttl = Math.min(Math.max(1e3, input.ttlMs ?? 3e5), AGENT_UI_UNLOCK_TTL_MS);
+	const payload = {
+		v: 1,
+		use: AGENT_UI_UNLOCK_USE,
+		nodeId: input.nodeId,
+		iat: nowMs,
+		exp: nowMs + ttl,
+		jti: input.jti ?? randomBytes(16).toString("base64url")
+	};
+	const signingInput = `${b64urlJsonEs256({
+		alg: "ES256",
+		typ: AGENT_UI_UNLOCK_TYP
+	})}.${b64urlJsonEs256(payload)}`;
+	return `${signingInput}.${sign("sha256", Buffer.from(signingInput, "utf8"), {
+		key: createPrivateKey(input.caKeyPem),
+		dsaEncoding: "ieee-p1363"
+	}).toString("base64url")}`;
+}
+/**
+* Verify a ticket against the mesh CA certificate the agent pinned. Returns the
+* payload, or `null` when the signature, header, shape, expiry or nodeId fails
+* (no reason string — refuse quietly).
+*/
+function verifyAgentUiUnlockTicketEs256(caCertPem, ticket, options) {
+	const nowMs = options.nowMs ?? Date.now();
+	const parts = ticket.split(".");
+	if (parts.length !== 3) return null;
+	const [headerB64, payloadB64, signatureB64] = parts;
+	if (headerB64 === void 0 || payloadB64 === void 0 || signatureB64 === void 0) return null;
+	let header;
+	let parsed;
+	try {
+		header = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf8"));
+		parsed = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+	} catch {
+		return null;
+	}
+	if (typeof header !== "object" || header === null) return null;
+	if (Reflect.get(header, "alg") !== "ES256" || Reflect.get(header, "typ") !== "camstack-agent-ui-unlock+jwt") return null;
+	let valid = false;
+	try {
+		valid = verify("sha256", Buffer.from(`${headerB64}.${payloadB64}`, "utf8"), {
+			key: new X509Certificate(caCertPem).publicKey,
+			dsaEncoding: "ieee-p1363"
+		}, Buffer.from(signatureB64, "base64url"));
+	} catch {
+		return null;
+	}
+	if (!valid) return null;
+	const payload = parsePayloadEs256(parsed);
+	if (payload === null) return null;
+	if (payload.exp <= nowMs) return null;
+	if (payload.nodeId !== options.expectedNodeId) return null;
+	if (!issuedSanely(payload, nowMs, options.notBeforeMs)) return null;
+	return payload;
+}
+function parsePayloadEs256(value) {
+	if (typeof value !== "object" || value === null) return null;
+	const rec = value;
+	if (rec["v"] !== 1) return null;
+	if (rec["use"] !== "agent-ui-unlock") return null;
+	const nodeId = rec["nodeId"];
+	const exp = rec["exp"];
+	const jti = rec["jti"];
+	if (typeof nodeId !== "string" || nodeId.length === 0) return null;
+	if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
+	if (typeof jti !== "string" || jti.length === 0) return null;
+	const iat = rec["iat"];
+	if (typeof iat !== "number" || !Number.isFinite(iat)) return null;
+	return {
+		v: 1,
+		nodeId,
+		iat,
 		exp,
 		jti
 	};
 }
 //#endregion
 //#region src/kernel/moleculer/mesh-mtls/mesh-ca.ts
+/**
+* Hub mesh CA — EC P-256, key in the keychain, cert in `cluster.meshCa`.
+*
+* Distinct from the HTTPS local CA (`tls/cert-issue.ts`, RSA): the mesh CA
+* signs node leaves (CN = nodeID) and join-token JWS (ES256). Issuance uses
+* `@peculiar/x509` over WebCrypto — same library the HTTPS path already uses
+* (installed `1.14.3`; registry latest at adoption time was `2.1.0` — stay on
+* the pinned range already shipping).
+*/
 cryptoProvider.set(webcrypto);
 var MS_PER_DAY = 864e5;
 /** Key generation — EC P-256 (plan). WebCrypto DOM names are not in @types/node. */
@@ -295,6 +420,14 @@ var MESH_SIGNING_ALGORITHM = {
 	name: "ECDSA",
 	hash: "SHA-256"
 };
+/** A node id: letters, digits, `.`, `_`, `-`; at most 63 characters; starts with a letter or digit. */
+var NODE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,62}$/i;
+/** Ids no agent may take: the hub's own, whatever the case (D857). */
+var RESERVED_NODE_IDS = new Set(["hub"]);
+/** True for an id an agent may carry: the pattern, and not a reserved name. */
+function isValidAgentNodeId(nodeId) {
+	return NODE_ID_PATTERN.test(nodeId) && !RESERVED_NODE_IDS.has(nodeId.toLowerCase());
+}
 function freshSerial() {
 	return `00${randomBytes(16).toString("hex")}`;
 }
@@ -325,7 +458,7 @@ async function generateMeshCa(now = /* @__PURE__ */ new Date()) {
 	const cert = await X509CertificateGenerator.createSelfSigned({
 		serialNumber: freshSerial(),
 		name: `CN=${MESH_CA_COMMON_NAME}`,
-		notBefore: now,
+		notBefore: backdatedNotBefore(now),
 		notAfter: new Date(now.getTime() + MESH_CA_VALIDITY_DAYS * MS_PER_DAY),
 		keys,
 		signingAlgorithm: MESH_SIGNING_ALGORITHM,
@@ -358,6 +491,7 @@ async function issueMeshLeafFromCsr(ca, csrPem, opts = {}) {
 	if (!await csr.verify(webcrypto)) throw new Error("CSR signature is invalid");
 	const cn = subjectCn(csr.subject);
 	if (cn === null || cn.length === 0) throw new Error("CSR subject has no CN");
+	if (opts.allowReserved !== true && !isValidAgentNodeId(cn)) throw new Error(`CSR CN '${cn}' is not an id an agent may carry`);
 	if (opts.expectedNodeId !== void 0 && opts.expectedNodeId !== cn) throw new Error(`CSR CN '${cn}' does not match the token nodeId '${opts.expectedNodeId}'`);
 	const now = opts.now ?? /* @__PURE__ */ new Date();
 	const validDays = opts.validDays ?? 30;
@@ -375,7 +509,7 @@ async function issueMeshLeafFromCsr(ca, csrPem, opts = {}) {
 			serialNumber,
 			subject: `CN=${cn}`,
 			issuer: ca.cert.subject,
-			notBefore: now,
+			notBefore: backdatedNotBefore(now),
 			notAfter,
 			publicKey: csr.publicKey,
 			signingKey: ca.privateKey,
@@ -394,7 +528,8 @@ async function issueMeshLeafForNode(ca, nodeId, opts = {}) {
 		...await issueMeshLeafFromCsr(ca, await createMeshCsrPem(keys, nodeId), {
 			expectedNodeId: nodeId,
 			now: opts.now,
-			validDays: opts.validDays
+			validDays: opts.validDays,
+			allowReserved: true
 		}),
 		keyPem: await exportKeyPem(keys.privateKey)
 	};
@@ -684,6 +819,7 @@ var RETENTION_MS = 90 * 864e5;
 var RENEWAL_ABANDONED = "renewal-abandoned";
 var VIAS = [
 	"enroll",
+	"pairing",
 	"renewal",
 	"boot",
 	"observed"
@@ -857,9 +993,10 @@ var MeshCertificateRegistry = class {
 	* valid just because the hub once set it aside). Returns the serials put on the CRL.
 	* A leaf revoked this way is never reinstated by `recordObserved`.
 	*/
-	async revokeAllForNode(nodeId, reason, crl) {
+	async revokeAllForNode(nodeId, reason, crl, keepFingerprint) {
 		const serials = [];
 		for (const record of this.list(nodeId)) {
+			if (keepFingerprint !== void 0 && record.fingerprint === keepFingerprint) continue;
 			if (record.revokedAt !== null && record.revokedReason !== "renewal-abandoned") continue;
 			const revoked = {
 				...record,
@@ -1309,6 +1446,10 @@ function getProcessNodeMeshTransport(nodeId) {
 function getProcessPeerLeaf(nodeId) {
 	return getProcessMeshPeerTransportLookup()?.peerLeaf?.(nodeId);
 }
+/** True when the hub's transporter holds a certificate-verified mesh peer called `nodeId` (D857). */
+function isProcessVerifiedMeshPeer(nodeId) {
+	return getProcessMeshPeerTransportLookup()?.isVerifiedPeer?.(nodeId) === true;
+}
 /** Disconnect `nodeId` (closes its mutual-TLS sockets). `0` when none were open. */
 function dropProcessPeer(nodeId) {
 	return getProcessMeshPeerTransportLookup()?.dropPeer?.(nodeId) ?? 0;
@@ -2017,7 +2158,8 @@ var SignJWT = class extends SignJWT_base {
 /**
 * Mesh join tokens — single-use JWS ES256 signed with the hub mesh CA key.
 *
-* Payload: `{ v, hubUrl, hubMeshAddress, caFingerprint, nodeId?, jti, exp }`.
+* Payload: `{ v, hubUrl, hubMeshAddress, caFingerprint, nodeId, jti, exp }`. The node id is MANDATORY
+* (D857): a token that does not name the node it is for would let its holder pick any id, `hub` included.
 * `exp` ≤ now + 1 h. `jti` is recorded until expiry so a token cannot be reused.
 */
 /** In-memory + optional persist of spent `jti` until `exp`. */
@@ -2048,6 +2190,7 @@ function processJoinTokenJtiStore() {
 	return processJtiStore;
 }
 async function mintMeshJoinToken(input) {
+	if (!isValidAgentNodeId(input.nodeId)) throw new Error(`a join token needs the node id it is for; "${input.nodeId}" is not one an agent may carry`);
 	const now = input.now ?? /* @__PURE__ */ new Date();
 	const nowSec = Math.floor(now.getTime() / 1e3);
 	const exp = nowSec + Math.min(Math.max(1, input.ttlSec ?? 3600), MESH_JOIN_TOKEN_MAX_TTL_SEC);
@@ -2057,7 +2200,7 @@ async function mintMeshJoinToken(input) {
 		hubUrl: input.hubUrl,
 		hubMeshAddress: input.hubMeshAddress,
 		caFingerprint: caFingerprintCompact(input.ca.certPem),
-		...input.nodeId !== void 0 ? { nodeId: input.nodeId } : {},
+		nodeId: input.nodeId,
 		jti,
 		exp
 	}).setProtectedHeader({
@@ -2085,7 +2228,7 @@ async function verifyMeshJoinToken(input) {
 			reason: `token signature invalid: ${msg}`
 		};
 	}
-	const claims = parseClaims(payload);
+	const claims = parseClaims$1(payload);
 	if (claims === null) return {
 		ok: false,
 		reason: "token claims malformed"
@@ -2121,7 +2264,7 @@ async function verifyMeshJoinToken(input) {
 function normalizeFp(fp) {
 	return fp.replace(/:/g, "").toLowerCase();
 }
-function parseClaims(payload) {
+function parseClaims$1(payload) {
 	if (payload["v"] !== 1) return null;
 	const hubUrl = payload["hubUrl"];
 	const hubMeshAddress = payload["hubMeshAddress"];
@@ -2134,12 +2277,13 @@ function parseClaims(payload) {
 	if (typeof jti !== "string" || jti.length === 0) return null;
 	if (exp === null) return null;
 	const nodeId = payload["nodeId"];
+	if (typeof nodeId !== "string" || !isValidAgentNodeId(nodeId)) return null;
 	return {
 		v: 1,
 		hubUrl,
 		hubMeshAddress,
 		caFingerprint: normalizeFp(caFingerprint),
-		...typeof nodeId === "string" && nodeId.length > 0 ? { nodeId } : {},
+		nodeId,
 		jti,
 		exp
 	};
@@ -87715,6 +87859,26 @@ var TlsTcpTransporter = class extends TcpTransporterBase {
 		return this.tlsPeers.has(nodeId) ? "tls" : "clear";
 	}
 	/**
+	* The certificate identity of `nodeId` (D857): its mutual-TLS handshake chained to the
+	* mesh CA this transporter was built with, its leaf CN is `nodeId`, and the leaf is not
+	* revoked now. This is the ONLY proof of "who is calling" the mesh gates accept:
+	* every inbound packet on a TLS socket is dropped unless its `sender` equals the leaf CN
+	* (see `onIncomingMessage`), so a node id in a delivered packet that is verified here was
+	* claimed by the holder of that node's private key.
+	*
+	* `undefined` for a node that reached us over clear text, never completed a handshake,
+	* or whose serial is on the CRL.
+	*/
+	verifiedPeer(nodeId) {
+		const serial = this.tlsPeers.get(nodeId);
+		if (serial === void 0) return void 0;
+		if (serial.length > 0 && this.crl.isRevoked(serial)) return void 0;
+		return {
+			nodeId,
+			serial
+		};
+	}
+	/**
 	* The node disconnected: its next connection decides its transport again —
 	* unless it already re-handshook (the disconnect can be noticed after the
 	* restarted node is back), in which case its live TLS socket keeps it `tls`.
@@ -87955,6 +88119,1174 @@ function isTlsSocket(socket) {
 	return typeof socket.getPeerCertificate === "function" && typeof socket.encrypted === "boolean" && socket.encrypted === true;
 }
 //#endregion
+//#region src/kernel/moleculer/mesh-mtls/pairing/pairing-protocol.ts
+/**
+* Agent pairing — the cryptographic core (D857).
+*
+* Pairing makes an agent hold a certificate from the hub's mesh CA, with no
+* shared secret anywhere. The hub starts it (LAN discovery or a typed
+* address); the operator confirms the SAME six digits on the hub and in the
+* agent's own page. Everything the human compares is derived here.
+*
+*   hub → agent   offer    { hub CA cert, commit = H(caFp ‖ hubNonce), hubUrl, hubMeshAddress }
+*   agent → hub   answer   { pairingId, CSR (mesh key made on the agent), agentNonce }
+*   hub → agent   reveal   { hubNonce }            (agent checks it against the commit)
+*   both          SAS      = 6 digits of H(caFp ‖ agentPublicKey ‖ hubNonce ‖ agentNonce)
+*   operator      reads the code on one screen and types it on the other, on both sides
+*   hub → agent   complete { leaf, proof }         (only after both confirmations)
+*
+* Why a commitment: a six-digit code is 20 bits. An attacker between the two
+* who could still choose a value AFTER seeing the others could grind a CA key
+* whose code equals the real one in a million tries. The hub therefore commits
+* to its nonce before it sees the agent's answer and reveals it only after,
+* so nothing the attacker controls is chosen after everything the code is
+* derived from is fixed. A substituted CA changes the code with probability
+* 999 999 / 1 000 000 per attempt, and a wrong code ends the pairing after
+* three tries.
+*
+* `proof` is an ES256 JWS by the mesh CA key over the transcript (pairing id,
+* node id, both nonces, the leaf fingerprint, the CA fingerprint). The agent
+* verifies it with the CA certificate it was OFFERED and the operator
+* confirmed — never with one that arrives in the same message.
+*/
+var PAIRING_PROTOCOL = 1;
+var PAIRING_DOMAIN = "camstack-pairing/v1";
+var PAIRING_PROOF_TYP = "camstack-pairing-complete+jwt";
+var PAIRING_PROOF_USE = "pairing-complete";
+var PAIRING_OFFER_TYP = "camstack-pairing-offer+jwt";
+var PAIRING_OFFER_USE = "pairing-offer";
+/** An offer signature older than this (or from further ahead than 60 s) is refused. */
+var PAIRING_OFFER_MAX_AGE_MS = 2 * 6e4;
+/** A pairing that is not confirmed on both sides within this window is cancelled on both. */
+var PAIRING_TTL_MS = 5 * 6e4;
+/** Wrong codes typed before the pairing is cancelled. */
+var PAIRING_MAX_CODE_ATTEMPTS = 3;
+var PAIRING_CODE_DIGITS = 6;
+/** Pending pairings an agent holds at once, one per hub CA (offer squatting, D857). */
+var PAIRING_MAX_SESSIONS = 4;
+/** The local PIN: single use, shown only on the agent's own machine. */
+var PAIRING_PIN_DIGITS = 8;
+/** A pairing proof is valid this long from `iat`, never longer. */
+var PAIRING_PROOF_MAX_LIFETIME_MS = 5 * 6e4;
+/** Agent endpoints, all under the agent API (`:4444`). */
+var PAIRING_PATHS = {
+	hello: "/api/agent/pairing/hello",
+	offer: "/api/agent/pairing/offer",
+	reveal: "/api/agent/pairing/reveal",
+	/** Public: who asks to pair - never a code, a pairing id or a PIN. */
+	status: "/api/agent/pairing/status",
+	/** The hub's poll, authorized by the pairing id: did the agent's operator confirm? */
+	poll: "/api/agent/pairing/poll",
+	complete: "/api/agent/pairing/complete",
+	/** The agent's operator: the hub's code + the local PIN (or genuine loopback). */
+	confirm: "/api/agent/pairing/confirm",
+	reject: "/api/agent/pairing/reject",
+	/** The hub withdraws its pairing, authorized by the pairing id. */
+	cancel: "/api/agent/pairing/cancel",
+	/** The agent's operator clears lockouts and pending offers (loopback, or the local reset code). */
+	reset: "/api/agent/pairing/reset",
+	forget: "/api/agent/pairing/forget"
+};
+/** A fresh single-use local PIN: digits only, uniformly random. */
+function randomPin() {
+	return String(randomInt(0, 10 ** 8)).padStart(8, "0");
+}
+function randomHex(bytes) {
+	return randomBytes(bytes).toString("hex");
+}
+function newPairingId() {
+	return randomBytes(16).toString("base64url");
+}
+/** The hub's commitment to its nonce, bound to the CA certificate it offers. */
+function computePairingCommitment(caCertPem, hubNonce) {
+	return createHash("sha256").update(`${PAIRING_DOMAIN}|commit|${caFingerprintCompact(caCertPem)}|${hubNonce}`, "utf8").digest("hex");
+}
+function commitmentsEqual(expected, presented) {
+	return constantTimeEqual(expected, presented);
+}
+/** The six digits both screens show. */
+function computePairingSas(input) {
+	const value = createHash("sha256").update([
+		PAIRING_DOMAIN,
+		"sas",
+		caFingerprintCompact(input.caCertPem),
+		input.agentPublicKeySpki,
+		input.hubNonce,
+		input.agentNonce
+	].join("|"), "utf8").digest().readUInt32BE(0) % 10 ** 6;
+	return String(value).padStart(6, "0");
+}
+function constantTimeEqual(expected, presented) {
+	if (typeof presented !== "string") return false;
+	const a = Buffer.from(expected, "utf8");
+	const b = Buffer.from(presented, "utf8");
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+async function describeCsr(csrPem) {
+	const csr = new Pkcs10CertificateRequest(csrPem);
+	if (!await csr.verify(webcrypto)) throw new Error("the agent CSR signature is invalid");
+	const cn = subjectCn(csr.subject);
+	if (cn === null || cn.length === 0) throw new Error("the agent CSR has no CN");
+	return {
+		commonName: cn,
+		publicKeySpki: Buffer.from(csr.publicKey.rawData).toString("base64")
+	};
+}
+function b64urlJson(value) {
+	return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+function leafFingerprintCompact(certPem) {
+	return createHash("sha256").update(new X509Certificate(certPem).raw).digest("hex");
+}
+function signPairingProof(caKeyPem, claims) {
+	const signingInput = `${b64urlJson({
+		alg: "ES256",
+		typ: PAIRING_PROOF_TYP
+	})}.${b64urlJson(claims)}`;
+	return `${signingInput}.${sign("sha256", Buffer.from(signingInput, "utf8"), {
+		key: createPrivateKey(caKeyPem),
+		dsaEncoding: "ieee-p1363"
+	}).toString("base64url")}`;
+}
+/**
+* The claims of `proof` when it was signed by `caCertPem`'s key, else `null`.
+* Shape, expiry and the binding to a session are the caller's to check.
+*/
+function verifyPairingProof(caCertPem, proof) {
+	const parts = proof.split(".");
+	if (parts.length !== 3) return null;
+	const [headerB64, payloadB64, signatureB64] = parts;
+	if (headerB64 === void 0 || payloadB64 === void 0 || signatureB64 === void 0) return null;
+	let header;
+	let payload;
+	try {
+		header = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf8"));
+		payload = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+	} catch {
+		return null;
+	}
+	if (header === null || typeof header !== "object") return null;
+	if (Reflect.get(header, "alg") !== "ES256" || Reflect.get(header, "typ") !== "camstack-pairing-complete+jwt") return null;
+	let valid = false;
+	try {
+		valid = verify("sha256", Buffer.from(`${headerB64}.${payloadB64}`, "utf8"), {
+			key: new X509Certificate(caCertPem).publicKey,
+			dsaEncoding: "ieee-p1363"
+		}, Buffer.from(signatureB64, "base64url"));
+	} catch {
+		return null;
+	}
+	return valid ? parseClaims(payload) : null;
+}
+function parseClaims(value) {
+	if (value === null || typeof value !== "object") return null;
+	const str = (key) => {
+		const v = Reflect.get(value, key);
+		return typeof v === "string" && v.length > 0 ? v : null;
+	};
+	const pairingId = str("pairingId");
+	const nodeId = str("nodeId");
+	const hubNonce = str("hubNonce");
+	const agentNonce = str("agentNonce");
+	const leafFingerprint = str("leafFingerprint");
+	const caFingerprint = str("caFingerprint");
+	const hubMeshAddress = str("hubMeshAddress");
+	const hubUrl = str("hubUrl");
+	const exp = Reflect.get(value, "exp");
+	const iat = Reflect.get(value, "iat");
+	if (Reflect.get(value, "v") !== 1) return null;
+	if (Reflect.get(value, "use") !== "pairing-complete") return null;
+	if (pairingId === null || nodeId === null || hubNonce === null || agentNonce === null || leafFingerprint === null || caFingerprint === null || hubMeshAddress === null || hubUrl === null || typeof exp !== "number" || !Number.isFinite(exp) || typeof iat !== "number" || !Number.isFinite(iat)) return null;
+	return {
+		v: 1,
+		use: PAIRING_PROOF_USE,
+		pairingId,
+		nodeId,
+		hubNonce,
+		agentNonce,
+		leafFingerprint,
+		caFingerprint,
+		hubMeshAddress,
+		hubUrl,
+		iat,
+		exp
+	};
+}
+/** A short public fingerprint of a public key, for the mDNS TXT record. */
+function keyFingerprintShort(publicKeySpkiB64) {
+	return createHash("sha256").update(Buffer.from(publicKeySpkiB64, "base64")).digest("hex").slice(0, 16);
+}
+function signPairingOffer(caKeyPem, claims) {
+	const signingInput = `${b64urlJson({
+		alg: "ES256",
+		typ: PAIRING_OFFER_TYP
+	})}.${b64urlJson(claims)}`;
+	return `${signingInput}.${sign("sha256", Buffer.from(signingInput, "utf8"), {
+		key: createPrivateKey(caKeyPem),
+		dsaEncoding: "ieee-p1363"
+	}).toString("base64url")}`;
+}
+/** The claims of `token` when `caCertPem`'s key signed it as a pairing offer, else `null`. */
+function verifyPairingOffer(caCertPem, token) {
+	const parts = token.split(".");
+	if (parts.length !== 3) return null;
+	const [headerB64, payloadB64, signatureB64] = parts;
+	if (headerB64 === void 0 || payloadB64 === void 0 || signatureB64 === void 0) return null;
+	let header;
+	let payload;
+	try {
+		header = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf8"));
+		payload = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+	} catch {
+		return null;
+	}
+	if (header === null || typeof header !== "object") return null;
+	if (Reflect.get(header, "alg") !== "ES256" || Reflect.get(header, "typ") !== "camstack-pairing-offer+jwt") return null;
+	let valid = false;
+	try {
+		valid = verify("sha256", Buffer.from(`${headerB64}.${payloadB64}`, "utf8"), {
+			key: new X509Certificate(caCertPem).publicKey,
+			dsaEncoding: "ieee-p1363"
+		}, Buffer.from(signatureB64, "base64url"));
+	} catch {
+		return null;
+	}
+	if (!valid || payload === null || typeof payload !== "object") return null;
+	const str = (key) => {
+		const v = Reflect.get(payload, key);
+		return typeof v === "string" && v.length > 0 ? v : null;
+	};
+	const iat = Reflect.get(payload, "iat");
+	const agentNodeId = str("agentNodeId");
+	const hubNodeId = str("hubNodeId");
+	const caFingerprint = str("caFingerprint");
+	const commitment = str("commitment");
+	const hubUrl = str("hubUrl");
+	const hubMeshAddress = str("hubMeshAddress");
+	if (Reflect.get(payload, "use") !== "pairing-offer") return null;
+	if (typeof iat !== "number" || !Number.isFinite(iat)) return null;
+	if (agentNodeId === null || hubNodeId === null || caFingerprint === null || commitment === null || hubUrl === null || hubMeshAddress === null) return null;
+	return {
+		use: PAIRING_OFFER_USE,
+		agentNodeId,
+		hubNodeId,
+		caFingerprint,
+		commitment,
+		hubUrl,
+		hubMeshAddress,
+		iat
+	};
+}
+//#endregion
+//#region src/kernel/moleculer/mesh-mtls/pairing/agent-pairing.ts
+/**
+* The agent's side of pairing (D857): up to four pending pairings (one per hub CA), their keys
+* in memory only, installed ONLY after the agent's own operator confirmed the same six digits
+* the hub shows AND proved presence at this agent with a one-time local PIN, and the hub's
+* transcript proof verified under the CA the agent was offered.
+*
+* Why a PIN: the agent's page is opened from another PC and its API is reachable by the whole
+* LAN. Anything the network can read, the network can use to "confirm" - so the code, the pairing
+* id and the PIN are shown ONLY on the agent's own machine (its console, a 0600 file, the local
+* window). A request that is not genuinely local must present the PIN of the pairing it confirms.
+*
+*   unpaired ──offer──▶ pending ──reveal──▶ (code known) ──confirm(code + PIN) + complete──▶ paired
+*                          │                                       │
+*                          └── reject / expiry / 3 wrong codes / 3 wrong PINs ──▶ unpaired
+*
+* Offers are rationed: pairings that ended without the local operator confirming them count
+* against a budget (3 per 10 minutes, then exponential lockout) and against the hub CA that made
+* them (so a loop of "offer, read the code, abort" cannot grind the six digits). A paired agent
+* refuses every offer.
+*/
+/** Abandoned offers allowed in {@link BUDGET_WINDOW_MS} before the lockout starts. */
+var BUDGET_OFFERS = 3;
+var BUDGET_WINDOW_MS = 10 * 6e4;
+var LOCKOUT_BASE_MS = 5 * 6e4;
+var LOCKOUT_MAX_MS = 60 * 6e4;
+/** Per hub CA: nothing for the first abandonment, then this x 2^(n-2), capped. */
+var CA_BACKOFF_BASE_MS = 3e4;
+var CA_BACKOFF_MAX_MS = 10 * 6e4;
+/** Wrong PINs (any session) before confirming is locked for a while. */
+var PIN_FAILURE_LIMIT = 5;
+var PIN_LOCK_MS = 2 * 6e4;
+var PIN_LOCK_MAX_MS = 60 * 6e4;
+/** Wrong PINs across ALL sources within one pairing lifetime before every pending pairing is cancelled. */
+var PIN_GLOBAL_CEILING = 200;
+var MAX_TRACKED_SOURCES = 256;
+/** Outcomes kept by pairing id so the hub can learn how its pairing ended. */
+var OUTCOME_LIMIT = 16;
+var OUTCOME_TTL_MS = 15 * 6e4;
+var MAX_FIELD = 2048;
+function fail(status, error, message, retryAfterMs) {
+	return {
+		ok: false,
+		status,
+		error,
+		message,
+		...retryAfterMs !== void 0 ? { retryAfterMs } : {}
+	};
+}
+function isText(value, max = MAX_FIELD) {
+	return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+function isHttpUrl(value) {
+	try {
+		const u = new URL(value);
+		return u.protocol === "https:" || u.protocol === "http:";
+	} catch {
+		return false;
+	}
+}
+/**
+* Clock skew tolerated between the hub that minted a CA and this agent. X.509 dates have
+* one-second resolution and a fresh CA's notBefore is the hub's "now", so an agent whose clock
+* is even a moment behind would otherwise refuse a brand-new CA. Same bound as the offer `iat`.
+*/
+var CA_CLOCK_SKEW_MS = 6e4;
+/** The hub CA must be a self-signed CA certificate, valid now (give or take the skew). */
+function readCaCertificate(pem, nowMs) {
+	try {
+		const cert = new X509Certificate(pem);
+		if (!cert.ca || !cert.verify(cert.publicKey)) return null;
+		if (Date.parse(cert.validTo) <= nowMs || Date.parse(cert.validFrom) > nowMs + CA_CLOCK_SKEW_MS) return null;
+		return cert;
+	} catch {
+		return null;
+	}
+}
+/** `host:6443` / `[::1]:6443` / `host` → the host, port dropped. */
+function hubHostFromMeshAddress(address) {
+	const trimmed = address.trim();
+	const bracketed = /^(\[[^\]]+\])(?::\d+)?$/.exec(trimmed);
+	if (bracketed?.[1] !== void 0) return bracketed[1];
+	return /^([^:]+):\d+$/.exec(trimmed)?.[1] ?? trimmed;
+}
+var AgentPairing = class {
+	deps;
+	sessions = /* @__PURE__ */ new Map();
+	/** Outcome of each recent pairing BY id (bounded): ending others never overwrites an answer. */
+	outcomes = /* @__PURE__ */ new Map();
+	/** When pairings that never reached local confirmation ended. */
+	abandoned = [];
+	lockedUntil = 0;
+	perCa = /* @__PURE__ */ new Map();
+	pinBySource = /* @__PURE__ */ new Map();
+	globalPinFailures = [];
+	resetCode;
+	/** Commitments already offered (signed offers are single use) until their signature is stale. */
+	seenCommitments = /* @__PURE__ */ new Map();
+	now;
+	constructor(deps) {
+		this.deps = deps;
+		this.now = deps.now ?? Date.now;
+		this.resetCode = randomPin();
+		deps.onResetCode?.(this.resetCode);
+	}
+	hello() {
+		this.expireIfDue();
+		const expiries = [...this.sessions.values()].map((s) => s.expiresAt);
+		return {
+			protocol: 1,
+			nodeId: this.deps.nodeId,
+			version: this.deps.version,
+			state: this.state(),
+			pendingExpiresAt: expiries.length === 0 ? null : Math.min(...expiries)
+		};
+	}
+	state() {
+		this.expireIfDue();
+		if (this.deps.isPaired()) return "paired";
+		return this.sessions.size > 0 ? "pending" : "unpaired";
+	}
+	/** Who is asking to pair, and until when. No code, no pairing id, no PIN. */
+	publicView() {
+		this.expireIfDue();
+		return {
+			state: this.state(),
+			pending: [...this.sessions.values()].map((s) => ({
+				hub: {
+					nodeId: s.hub.nodeId,
+					url: s.hub.url,
+					caFingerprint: s.hub.caFingerprint
+				},
+				expiresAt: s.expiresAt
+			}))
+		};
+	}
+	/** The view for the agent's own machine: also the pairing ids, the codes and the PINs. */
+	localView() {
+		this.expireIfDue();
+		return {
+			state: this.state(),
+			pending: [...this.sessions.values()].map((s) => ({
+				pairingId: s.pairingId,
+				hub: {
+					nodeId: s.hub.nodeId,
+					url: s.hub.url,
+					caFingerprint: s.hub.caFingerprint
+				},
+				expiresAt: s.expiresAt,
+				pin: s.pin,
+				code: s.code,
+				localConfirmed: s.localConfirmed
+			}))
+		};
+	}
+	async offer(body) {
+		this.expireIfDue();
+		if (this.deps.isPaired()) return fail(409, "already-paired", "this agent is paired — unpair it first (from the hub or here)");
+		if (!isValidAgentNodeId(this.deps.nodeId)) return fail(409, "invalid-node-id", `this agent's node id "${this.deps.nodeId}" cannot be paired - rename the agent`);
+		const request = parseOffer(body);
+		if (request === null) return fail(400, "bad-offer", "the offer is malformed");
+		if (request.protocol !== 1) return fail(400, "unsupported-protocol", `pairing protocol ${String(request.protocol)} is not supported`);
+		if (readCaCertificate(request.hubCaCertPem, this.now()) === null) return fail(400, "bad-ca", "the offered CA is not a valid self-signed CA certificate");
+		if (!/^[0-9a-f]{64}$/.test(request.commitment)) return fail(400, "bad-offer", "the commitment is malformed");
+		if (!isHttpUrl(request.hubUrl)) return fail(400, "bad-offer", "hubUrl is not an http(s) URL");
+		const caFingerprint = caFingerprintCompact(request.hubCaCertPem);
+		const refused = this.checkOfferSignature(request, caFingerprint);
+		if (refused !== null) return refused;
+		const rationed = this.rationOffer(caFingerprint);
+		if (rationed !== null) return rationed;
+		for (const existing of [...this.sessions.values()]) if (existing.hub.caFingerprint === caFingerprint) this.end(existing, "failed");
+		if (this.sessions.size >= 4 && !this.makeRoom()) return fail(409, "too-many-pending", "too many pairings are pending on this agent");
+		const keys = await generateMeshKeyPair();
+		const csrPem = await createMeshCsrPem(keys, this.deps.nodeId);
+		const keyPem = await exportMeshPrivateKeyPem(keys.privateKey);
+		const publicKeySpki = Buffer.from(await webcrypto.subtle.exportKey("spki", keys.publicKey)).toString("base64");
+		if (this.sessions.size >= 4 && !this.makeRoom()) return fail(409, "too-many-pending", "too many pairings are pending on this agent");
+		const session = {
+			pairingId: newPairingId(),
+			hub: {
+				nodeId: request.hubNodeId,
+				caCertPem: request.hubCaCertPem,
+				caFingerprint,
+				commitment: request.commitment,
+				url: request.hubUrl,
+				meshAddress: request.hubMeshAddress
+			},
+			keyPem,
+			csrPem,
+			publicKeySpki,
+			agentNonce: randomHex(32),
+			pin: randomPin(),
+			expiresAt: this.now() + PAIRING_TTL_MS,
+			hubNonce: null,
+			code: null,
+			localConfirmed: false,
+			attempts: 0,
+			touched: false,
+			createdAt: this.now()
+		};
+		this.sessions.set(session.pairingId, session);
+		this.deps.onStateChange?.();
+		this.announceLocally(session);
+		this.deps.log?.("pairing requested by a hub", {
+			hubUrl: session.hub.url,
+			caFingerprint: session.hub.caFingerprint
+		});
+		return {
+			ok: true,
+			answer: {
+				pairingId: session.pairingId,
+				csrPem,
+				agentNonce: session.agentNonce,
+				expiresAt: session.expiresAt
+			}
+		};
+	}
+	/** The hub reveals its nonce; the agent checks it against the commitment and derives the code. */
+	reveal(body) {
+		const session = this.pending(body);
+		if ("ok" in session) return session;
+		const hubNonce = field(body, "hubNonce");
+		if (!isText(hubNonce, 256)) return fail(400, "bad-reveal", "hubNonce is missing");
+		if (session.hubNonce !== null) return fail(409, "already-revealed", "the nonce was already revealed");
+		if (!commitmentsEqual(computePairingCommitment(session.hub.caCertPem, hubNonce), session.hub.commitment)) {
+			this.end(session, "failed");
+			return fail(400, "commitment-mismatch", "the revealed nonce does not match the hub commitment");
+		}
+		session.touched = true;
+		session.hubNonce = hubNonce;
+		session.code = computePairingSas({
+			caCertPem: session.hub.caCertPem,
+			agentPublicKeySpki: session.publicKeySpki,
+			hubNonce,
+			agentNonce: session.agentNonce
+		});
+		this.announceLocally(session);
+		return { ok: true };
+	}
+	/** The hub polls with the pairing id: did the agent's operator confirm, did it end? */
+	poll(body) {
+		this.expireIfDue();
+		const pairingId = field(body, "pairingId");
+		const session = typeof pairingId === "string" ? this.sessions.get(pairingId) : void 0;
+		if (session !== void 0) {
+			session.touched = true;
+			return {
+				ok: true,
+				poll: {
+					state: "pending",
+					localConfirmed: session.localConfirmed,
+					last: null
+				}
+			};
+		}
+		const known = typeof pairingId === "string" ? this.outcomeOf(pairingId) : null;
+		if (typeof pairingId === "string" && known !== null) return {
+			ok: true,
+			poll: {
+				state: "idle",
+				localConfirmed: false,
+				last: {
+					pairingId,
+					outcome: known
+				}
+			}
+		};
+		return fail(404, "no-pairing", "no such pairing is pending");
+	}
+	/**
+	* The operator typed the code the HUB shows. From the agent's own machine that is enough; from
+	* anywhere else the one-time PIN of THIS pairing (read on the agent's console) must come with
+	* it. A wrong code counts against the pairing (the third cancels it); a wrong PIN counts against
+	* the agent (five lock confirming for five minutes).
+	*/
+	confirm(body, ctx) {
+		const found = this.localTarget(body, ctx);
+		if ("ok" in found) return found;
+		const session = found;
+		if (session.code === null) return fail(409, "not-ready", "the hub has not revealed its nonce yet");
+		const code = field(body, "code");
+		if (!constantTimeEqual(session.code, typeof code === "string" ? code.trim() : code)) {
+			session.attempts += 1;
+			if (session.attempts >= 3) {
+				this.end(session, "code-mismatch");
+				return fail(403, "code-mismatch", "wrong code three times — the pairing was cancelled");
+			}
+			return fail(403, "code-mismatch", "that is not the code this agent computed");
+		}
+		session.localConfirmed = true;
+		return { ok: true };
+	}
+	reject(body, ctx) {
+		const found = this.localTarget(body, ctx);
+		if ("ok" in found) return found;
+		this.end(found, "rejected");
+		return { ok: true };
+	}
+	/** The hub withdraws its own pairing (authorized by the pairing id it was given). */
+	cancel(body) {
+		const session = this.pending(body);
+		if ("ok" in session) return session;
+		this.end(session, "rejected");
+		return { ok: true };
+	}
+	async complete(body) {
+		const session = this.pending(body);
+		if ("ok" in session) return session;
+		if (session.hubNonce === null || session.code === null) return fail(409, "not-ready", "the hub has not revealed its nonce yet");
+		if (!session.localConfirmed) return fail(409, "awaiting-local-confirmation", "the operator has not confirmed on this agent");
+		const leafPem = field(body, "leafPem");
+		const caCertPem = field(body, "caCertPem");
+		const proof = field(body, "proof");
+		if (!isText(leafPem, 16384) || !isText(caCertPem, 16384) || !isText(proof, 16384)) return fail(400, "bad-complete", "the completion is malformed");
+		const refusal = this.checkCompletion(session, leafPem, caCertPem, proof);
+		if (refusal !== null) {
+			this.end(session, "failed");
+			return refusal;
+		}
+		try {
+			await this.deps.install({
+				meshTls: {
+					certPem: leafPem,
+					keyPem: session.keyPem,
+					caCertPem: session.hub.caCertPem
+				},
+				hubAddress: hubHostFromMeshAddress(session.hub.meshAddress),
+				hubUrl: session.hub.url
+			});
+		} catch (err) {
+			this.end(session, "failed");
+			return fail(500, "install-failed", err instanceof Error ? err.message : String(err));
+		}
+		this.end(session, "completed");
+		for (const other of [...this.sessions.values()]) this.end(other, "failed", false);
+		this.deps.log?.("paired with the hub", { hubUrl: session.hub.url });
+		return { ok: true };
+	}
+	/** The agent forgot its hub (local action): the pairing slate is clean. */
+	noteUnpaired() {
+		for (const s of [...this.sessions.values()]) this.end(s, "failed", false);
+		this.deps.onStateChange?.();
+	}
+	/** Remaining lock for a source, or `null`. Loopback never calls this. */
+	sourceLock(source, at) {
+		const entry = this.pinBySource.get(source);
+		return entry !== void 0 && at < entry.lockedUntil ? entry.lockedUntil - at : null;
+	}
+	/** A wrong PIN or reset code from `source`: five in five minutes lock THAT source, doubling. */
+	noteWrongSecret(source, at) {
+		if (this.pinBySource.size >= MAX_TRACKED_SOURCES && !this.pinBySource.has(source)) this.pinBySource.clear();
+		const prev = this.pinBySource.get(source) ?? {
+			failures: [],
+			strikes: 0,
+			lockedUntil: 0
+		};
+		const failures = [...prev.failures.filter((t) => at - t < 5 * 6e4), at];
+		if (failures.length >= PIN_FAILURE_LIMIT) {
+			const lockedUntil = at + Math.min(PIN_LOCK_MAX_MS, PIN_LOCK_MS * 2 ** prev.strikes);
+			this.deps.log?.("confirming is locked for a source: too many wrong PINs", { source });
+			this.pinBySource.set(source, {
+				failures: [],
+				strikes: prev.strikes + 1,
+				lockedUntil
+			});
+		} else this.pinBySource.set(source, {
+			...prev,
+			failures
+		});
+		this.globalPinFailures = [...this.globalPinFailures.filter((t) => at - t < PAIRING_TTL_MS), at];
+		if (this.globalPinFailures.length >= PIN_GLOBAL_CEILING) {
+			this.globalPinFailures = [];
+			this.deps.log?.("too many wrong PINs overall: every pending pairing is cancelled", {});
+			for (const session of [...this.sessions.values()]) this.end(session, "failed", false);
+		}
+	}
+	/**
+	* The operator clears the lockouts, the budget and every pending offer. From this machine
+	* (genuine loopback) or with the LOCAL RESET CODE printed at boot; the code is renewed on use.
+	*/
+	reset(body, ctx) {
+		const at = this.now();
+		if (!ctx.local) {
+			const key = `reset:${ctx.source ?? "unknown"}`;
+			const locked = this.sourceLock(key, at);
+			if (locked !== null) return fail(429, "reset-locked", "too many wrong codes", locked);
+			const code = field(body, "code");
+			if (typeof code !== "string" || !constantTimeEqual(this.resetCode, code.trim())) {
+				this.noteWrongSecret(key, at);
+				return fail(401, "reset-code-required", "the reset code printed on the agent is required");
+			}
+		}
+		for (const session of [...this.sessions.values()]) this.end(session, "failed", false);
+		this.abandoned = [];
+		this.lockedUntil = 0;
+		this.perCa.clear();
+		this.pinBySource.clear();
+		this.globalPinFailures = [];
+		this.resetCode = randomPin();
+		this.deps.onResetCode?.(this.resetCode);
+		this.deps.log?.("pairing was reset by the local operator", {});
+		return { ok: true };
+	}
+	/** Verify the CA-key signature of an offer and spend its commitment. */
+	checkOfferSignature(request, caFingerprint) {
+		const claims = verifyPairingOffer(request.hubCaCertPem, request.signature);
+		const at = this.now();
+		if (claims === null || claims.use !== "pairing-offer" || claims.agentNodeId !== this.deps.nodeId || claims.hubNodeId !== request.hubNodeId || claims.caFingerprint !== caFingerprint || claims.commitment !== request.commitment || claims.hubUrl !== request.hubUrl || claims.hubMeshAddress !== request.hubMeshAddress || claims.iat > at + 6e4 || at - claims.iat > 12e4) {
+			this.deps.log?.("an offer without a valid CA signature was refused", {});
+			return fail(403, "bad-offer-signature", "the offer is not signed by the CA it presents");
+		}
+		for (const [commitment, until] of this.seenCommitments) if (until <= at) this.seenCommitments.delete(commitment);
+		if (this.seenCommitments.has(request.commitment)) return fail(409, "offer-replayed", "this offer was already used");
+		this.seenCommitments.set(request.commitment, at + PAIRING_OFFER_MAX_AGE_MS + 6e4);
+		return null;
+	}
+	/**
+	* All slots taken: a signed offer makes room by dropping the oldest pairing whose hub never showed
+	* activity (no reveal, no poll) and that no operator confirmed. `false` when there is none.
+	*/
+	makeRoom() {
+		const oldest = [...this.sessions.values()].filter((s) => !s.touched && !s.localConfirmed).toSorted((a, b) => a.createdAt - b.createdAt)[0];
+		if (oldest === void 0) return false;
+		this.deps.log?.("a pending pairing made room for a newer signed offer", { caFingerprint: oldest.hub.caFingerprint });
+		this.end(oldest, "failed", false);
+		return true;
+	}
+	/** Offers that never reached local confirmation are rationed - globally and per hub CA. */
+	rationOffer(caFingerprint) {
+		const at = this.now();
+		if (at < this.lockedUntil) {
+			this.deps.log?.("offer refused: the budget of abandoned pairings is spent", { retryAfterMs: this.lockedUntil - at });
+			return fail(429, "offer-budget", "too many pairings were abandoned recently - try again later", this.lockedUntil - at);
+		}
+		const ca = this.perCa.get(caFingerprint);
+		if (ca !== void 0 && at < ca.until) {
+			this.deps.log?.("offer refused: this hub abandoned a pairing a moment ago", {
+				caFingerprint,
+				retryAfterMs: ca.until - at
+			});
+			return fail(429, "offer-backoff", "this hub abandoned a pairing a moment ago - wait before offering again", ca.until - at);
+		}
+		return null;
+	}
+	/** A pairing ended without the local operator confirming it: it counts against the budget. */
+	noteAbandoned(session) {
+		const at = this.now();
+		this.abandoned = [...this.abandoned.filter((t) => at - t < BUDGET_WINDOW_MS), at];
+		if (this.abandoned.length >= BUDGET_OFFERS) {
+			const over = this.abandoned.length - BUDGET_OFFERS;
+			const lock = Math.min(LOCKOUT_MAX_MS, LOCKOUT_BASE_MS * 2 ** over);
+			this.lockedUntil = at + lock;
+			this.deps.log?.("pairing offers are locked: too many were abandoned", {
+				abandoned: this.abandoned.length,
+				lockMs: lock
+			});
+		}
+		const count = (this.perCa.get(session.hub.caFingerprint)?.count ?? 0) + 1;
+		const backoff = count < 2 ? 0 : Math.min(CA_BACKOFF_MAX_MS, CA_BACKOFF_BASE_MS * 2 ** (count - 2));
+		this.perCa.set(session.hub.caFingerprint, {
+			count,
+			until: at + backoff
+		});
+	}
+	/** The pairing this local request means, else the refusal. */
+	localTarget(body, ctx) {
+		this.expireIfDue();
+		if (this.sessions.size === 0) return fail(404, "no-pairing", "no pairing is pending");
+		const pin = field(body, "pin");
+		if (!ctx.local) {
+			const at = this.now();
+			const source = ctx.source ?? "unknown";
+			const locked = this.sourceLock(source, at);
+			if (locked !== null) return fail(429, "pin-locked", "too many wrong PINs - try again later", locked);
+			const match = typeof pin === "string" ? [...this.sessions.values()].find((s) => constantTimeEqual(s.pin, pin.trim())) : void 0;
+			if (match === void 0) {
+				this.noteWrongSecret(source, at);
+				return fail(401, "pin-required", "the PIN shown on this agent's own machine (console, file or local window) is required");
+			}
+			return match;
+		}
+		if (typeof pin === "string" && pin.trim().length > 0) {
+			const match = [...this.sessions.values()].find((s) => constantTimeEqual(s.pin, pin.trim()));
+			if (match !== void 0) return match;
+		}
+		const only = [...this.sessions.values()];
+		if (only.length === 1 && only[0] !== void 0) return only[0];
+		return fail(409, "ambiguous", "several pairings are pending - give the PIN of the one you mean");
+	}
+	announceLocally(session) {
+		this.deps.onLocalSecret?.({
+			pairingId: session.pairingId,
+			pin: session.pin,
+			code: session.code,
+			hub: {
+				nodeId: session.hub.nodeId,
+				url: session.hub.url,
+				caFingerprint: session.hub.caFingerprint
+			},
+			expiresAt: session.expiresAt
+		});
+	}
+	checkCompletion(session, leafPem, caCertPem, proof) {
+		if (caFingerprintOf(caCertPem) !== session.hub.caFingerprint) return fail(400, "ca-mismatch", "the completion carries a CA other than the one offered");
+		const claims = verifyPairingProof(session.hub.caCertPem, proof);
+		if (claims === null) return fail(400, "bad-proof", "the pairing proof does not verify");
+		if (claims.pairingId !== session.pairingId || claims.nodeId !== this.deps.nodeId || claims.hubNonce !== session.hubNonce || claims.agentNonce !== session.agentNonce || claims.caFingerprint !== session.hub.caFingerprint || claims.hubMeshAddress !== session.hub.meshAddress || claims.hubUrl !== session.hub.url) return fail(400, "bad-proof", "the pairing proof is for another pairing");
+		const at = this.now();
+		if (claims.exp <= at || claims.iat > at + 6e4 || claims.exp - claims.iat > 3e5) return fail(400, "bad-proof", "the pairing proof is expired or has an impossible lifetime");
+		try {
+			if (claims.leafFingerprint !== leafFingerprintCompact(leafPem)) return fail(400, "bad-leaf", "the certificate is not the one the proof names");
+			const leaf = new X509Certificate(leafPem);
+			const ca = new X509Certificate(session.hub.caCertPem);
+			if (!leaf.verify(ca.publicKey)) return fail(400, "bad-leaf", "the certificate is not signed by the offered CA");
+			if (subjectCn(leaf.subject.replaceAll("\n", ",")) !== this.deps.nodeId) return fail(400, "bad-leaf", `the certificate is not issued for "${this.deps.nodeId}"`);
+			if (!leaf.checkPrivateKey(createPrivateKey(session.keyPem))) return fail(400, "bad-leaf", "the certificate does not match this agent's private key");
+			if (Date.parse(leaf.validTo) <= this.now()) return fail(400, "bad-leaf", "the certificate is already expired");
+		} catch {
+			return fail(400, "bad-leaf", "the certificate could not be read");
+		}
+		return null;
+	}
+	/** The live session `body.pairingId` names, else the refusal. */
+	pending(body) {
+		this.expireIfDue();
+		const pairingId = field(body, "pairingId");
+		if (this.sessions.size === 0) return fail(404, "no-pairing", "no pairing is pending");
+		const session = typeof pairingId === "string" ? this.sessions.get(pairingId) : void 0;
+		if (session === void 0) return fail(403, "wrong-pairing", "that is not a pending pairing");
+		return session;
+	}
+	expireIfDue() {
+		for (const s of [...this.sessions.values()]) if (s.expiresAt <= this.now()) this.end(s, "expired");
+	}
+	outcomeOf(pairingId) {
+		const entry = this.outcomes.get(pairingId);
+		if (entry === void 0) return null;
+		if (this.now() - entry.at > OUTCOME_TTL_MS) {
+			this.outcomes.delete(pairingId);
+			return null;
+		}
+		return entry.outcome;
+	}
+	rememberOutcome(pairingId, outcome) {
+		this.outcomes.set(pairingId, {
+			outcome,
+			at: this.now()
+		});
+		while (this.outcomes.size > OUTCOME_LIMIT) {
+			const oldest = this.outcomes.keys().next().value;
+			if (oldest === void 0) break;
+			this.outcomes.delete(oldest);
+		}
+	}
+	end(session, outcome, count = true) {
+		if (!this.sessions.delete(session.pairingId)) return;
+		this.rememberOutcome(session.pairingId, outcome);
+		if (outcome === "completed") this.perCa.delete(session.hub.caFingerprint);
+		else if (count && !session.localConfirmed) this.noteAbandoned(session);
+		this.deps.onLocalSecretCleared?.(session.pairingId);
+		this.deps.onStateChange?.();
+		if (outcome !== "completed") this.deps.log?.("pairing cancelled", {
+			outcome,
+			hubUrl: session.hub.url
+		});
+	}
+};
+function field(body, key) {
+	return body !== null && typeof body === "object" ? Reflect.get(body, key) : void 0;
+}
+function caFingerprintOf(pem) {
+	try {
+		return caFingerprintCompact(pem);
+	} catch {
+		return null;
+	}
+}
+function parseOffer(body) {
+	if (body === null || typeof body !== "object") return null;
+	const protocol = Reflect.get(body, "protocol");
+	const hubNodeId = Reflect.get(body, "hubNodeId");
+	const hubCaCertPem = Reflect.get(body, "hubCaCertPem");
+	const commitment = Reflect.get(body, "commitment");
+	const hubUrl = Reflect.get(body, "hubUrl");
+	const hubMeshAddress = Reflect.get(body, "hubMeshAddress");
+	const signature = Reflect.get(body, "signature");
+	if (typeof protocol !== "number") return null;
+	if (!isText(hubNodeId, 128) || !isText(hubCaCertPem, 16384) || !isText(commitment, 128)) return null;
+	if (!isText(hubUrl) || !isText(hubMeshAddress, 255) || !isText(signature, 4096)) return null;
+	return {
+		protocol,
+		hubNodeId,
+		hubCaCertPem,
+		commitment,
+		hubUrl,
+		hubMeshAddress,
+		signature
+	};
+}
+//#endregion
+//#region src/kernel/moleculer/mesh-mtls/pairing/hub-pairing.ts
+/**
+* The hub's side of pairing (D857): starts a pairing with an agent it found
+* (mDNS) or was given an address for, computes the same six digits the agent
+* shows, and signs the agent's certificate ONLY after the operator confirmed
+* them on the hub AND the agent's own operator confirmed them there.
+*
+* Either confirmation may come first. The hub learns the agent's by polling the
+* agent's pairing status (`advance`), never by being told: nothing the agent
+* says is trusted beyond "my operator confirmed", and even that only matters
+* together with the hub's own confirmation.
+*
+* Transport-agnostic: `AgentPairingTransport` is the HTTP client in production
+* and an in-memory shim (or a man in the middle) in specs.
+*/
+/** A refusal the agent sent, kept with its machine-readable code. */
+var PairingHttpError = class extends Error {
+	status;
+	code;
+	constructor(status, code, message) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.name = "PairingHttpError";
+	}
+};
+/** Pairings kept (active and just ended) so the page can show how one ended. */
+var MAX_SESSIONS = 16;
+var PROOF_TTL_MS = Math.min(2 * 6e4, PAIRING_PROOF_MAX_LIFETIME_MS);
+var TERMINAL = new Set([
+	"paired",
+	"rejected",
+	"expired",
+	"failed"
+]);
+var HubPairing = class {
+	deps;
+	sessions = /* @__PURE__ */ new Map();
+	now;
+	constructor(deps) {
+		this.deps = deps;
+		this.now = deps.now ?? Date.now;
+	}
+	/** Offer the hub's CA to the agent at `endpoint` and derive the code. Throws an `Error` with the reason. */
+	async begin(endpoint) {
+		const ca = this.deps.ca();
+		if (ca === null) throw new Error("the mesh CA is not ready — try again in a moment");
+		const hello = await this.deps.transport.hello(endpoint);
+		if (hello.protocol !== 1) throw new Error(`the agent speaks pairing protocol ${String(hello.protocol)}, not 1`);
+		if (hello.state === "paired") throw new Error(`"${hello.nodeId}" is already paired — unpair it first`);
+		this.assertNodeIdUsable(hello.nodeId);
+		for (const s of this.sessions.values()) if (s.nodeId === hello.nodeId && !TERMINAL.has(s.state)) throw new Error(`a pairing with "${hello.nodeId}" is already in progress`);
+		const hubNonce = randomHex(32);
+		const hubUrl = await this.deps.hubUrl();
+		const hubMeshAddress = await this.deps.hubMeshAddress();
+		const commitment = computePairingCommitment(ca.certPem, hubNonce);
+		const answer = await this.deps.transport.offer(endpoint, {
+			protocol: 1,
+			hubNodeId: this.deps.hubNodeId,
+			hubCaCertPem: ca.certPem,
+			commitment,
+			hubUrl,
+			hubMeshAddress,
+			signature: signPairingOffer(ca.keyPem, {
+				use: PAIRING_OFFER_USE,
+				agentNodeId: hello.nodeId,
+				hubNodeId: this.deps.hubNodeId,
+				caFingerprint: caFingerprintCompact(ca.certPem),
+				commitment,
+				hubUrl,
+				hubMeshAddress,
+				iat: this.now()
+			})
+		});
+		try {
+			const csr = await describeCsr(answer.csrPem);
+			if (csr.commonName !== hello.nodeId) throw new Error(`the agent's CSR is for "${csr.commonName}", not "${hello.nodeId}"`);
+			await this.deps.transport.reveal(endpoint, {
+				pairingId: answer.pairingId,
+				hubNonce
+			});
+			const code = computePairingSas({
+				caCertPem: ca.certPem,
+				agentPublicKeySpki: csr.publicKeySpki,
+				hubNonce,
+				agentNonce: answer.agentNonce
+			});
+			const session = {
+				pairingId: answer.pairingId,
+				nodeId: hello.nodeId,
+				endpoint,
+				code,
+				csrPem: answer.csrPem,
+				hubNonce,
+				agentNonce: answer.agentNonce,
+				caCertPem: ca.certPem,
+				hubUrl,
+				hubMeshAddress,
+				expiresAt: Math.min(answer.expiresAt, this.now() + PAIRING_TTL_MS),
+				state: "awaiting-confirmation",
+				hubConfirmed: false,
+				agentConfirmed: false,
+				attempts: 0,
+				failure: null,
+				issued: false
+			};
+			this.remember(session);
+			this.deps.log?.("pairing started", {
+				nodeId: session.nodeId,
+				pairingId: session.pairingId
+			});
+			return this.view(session);
+		} catch (err) {
+			await this.deps.transport.reject(endpoint, answer.pairingId).catch(() => void 0);
+			throw err;
+		}
+	}
+	/** The operator typed the code the AGENT shows. A wrong one counts; the third cancels the pairing. */
+	async confirm(pairingId, code) {
+		const session = this.require(pairingId);
+		this.expireIfDue(session);
+		if (TERMINAL.has(session.state)) return this.view(session);
+		if (!constantTimeEqual(session.code, typeof code === "string" ? code.trim() : code)) {
+			session.attempts += 1;
+			if (session.attempts >= 3) await this.cancel(session, "rejected", "wrong code three times");
+			throw new Error(session.attempts >= 3 ? "wrong code three times — the pairing was cancelled" : "that is not the code the hub computed — if the agent shows a different one, someone is between them; cancel it");
+		}
+		session.hubConfirmed = true;
+		return this.advance(pairingId);
+	}
+	async reject(pairingId) {
+		const session = this.require(pairingId);
+		if (!TERMINAL.has(session.state)) await this.cancel(session, "rejected", "rejected on the hub");
+		return this.view(session);
+	}
+	get(pairingId) {
+		const session = this.sessions.get(pairingId);
+		return session === void 0 ? void 0 : this.view(session);
+	}
+	list() {
+		return [...this.sessions.values()].map((s) => this.view(s));
+	}
+	/** Active pairings, for the poller. */
+	activeIds() {
+		return [...this.sessions.values()].filter((s) => !TERMINAL.has(s.state)).map((s) => s.pairingId);
+	}
+	/**
+	* Move a pairing on: notice an expiry, a cancellation or the agent's
+	* confirmation, and complete when both sides confirmed. Never throws.
+	*/
+	async advance(pairingId) {
+		const session = this.require(pairingId);
+		if (TERMINAL.has(session.state) || session.state === "completing") return this.view(session);
+		if (this.expireIfDue(session)) {
+			await this.deps.transport.reject(session.endpoint, session.pairingId).catch(() => void 0);
+			return this.view(session);
+		}
+		try {
+			const poll = await this.deps.transport.poll(session.endpoint, session.pairingId);
+			if (poll.state === "pending") session.agentConfirmed = poll.localConfirmed;
+			else if (poll.last?.pairingId === session.pairingId && poll.last.outcome === "completed") {
+				this.finish(session, "paired", null);
+				return this.view(session);
+			} else {
+				const why = poll.last?.pairingId === session.pairingId ? poll.last.outcome : "gone";
+				this.finish(session, "failed", `the agent ended the pairing (${why})`);
+				return this.view(session);
+			}
+		} catch (err) {
+			if (err instanceof PairingHttpError && err.code === "no-pairing") {
+				this.finish(session, "failed", "the agent no longer has this pairing");
+				return this.view(session);
+			}
+			this.deps.log?.("pairing status poll failed", {
+				nodeId: session.nodeId,
+				error: err instanceof Error ? err.message : String(err)
+			});
+			return this.view(session);
+		}
+		if (session.hubConfirmed && session.agentConfirmed) await this.complete(session);
+		return this.view(session);
+	}
+	async complete(session) {
+		const ca = this.deps.ca();
+		if (ca === null || caFingerprintCompact(ca.certPem) !== caFingerprintCompact(session.caCertPem)) {
+			await this.cancel(session, "failed", "the mesh CA changed during the pairing");
+			return;
+		}
+		session.state = "completing";
+		let issuedPem = null;
+		try {
+			const leaf = await issueMeshLeafFromCsr(ca, session.csrPem, { expectedNodeId: session.nodeId });
+			issuedPem = leaf.certPem;
+			await this.deps.recordIssued(session.nodeId, leaf.certPem);
+			session.issued = true;
+			const proof = signPairingProof(ca.keyPem, {
+				v: 1,
+				use: PAIRING_PROOF_USE,
+				pairingId: session.pairingId,
+				nodeId: session.nodeId,
+				hubNonce: session.hubNonce,
+				agentNonce: session.agentNonce,
+				leafFingerprint: leafFingerprintCompact(leaf.certPem),
+				caFingerprint: caFingerprintCompact(ca.certPem),
+				hubMeshAddress: session.hubMeshAddress,
+				hubUrl: session.hubUrl,
+				iat: this.now(),
+				exp: this.now() + PROOF_TTL_MS
+			});
+			await this.deps.transport.complete(session.endpoint, {
+				pairingId: session.pairingId,
+				leafPem: leaf.certPem,
+				caCertPem: ca.certPem,
+				proof
+			});
+			await this.installed(session, leaf.certPem);
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			if (err instanceof PairingHttpError && err.code === "awaiting-local-confirmation") {
+				session.state = "awaiting-confirmation";
+				session.agentConfirmed = false;
+				return;
+			}
+			let outcome = issuedPem === null ? "absent" : await this.installOutcome(session);
+			if (outcome !== "installed" && issuedPem !== null && this.deps.isLeafPresented?.(session.nodeId, issuedPem) === true) outcome = "installed";
+			if (outcome === "installed" && issuedPem !== null) {
+				await this.installed(session, issuedPem);
+				return;
+			}
+			if (outcome === "absent" && issuedPem !== null) await this.deps.revokeLeaf?.(session.nodeId, issuedPem, "pairing did not complete").catch(() => void 0);
+			const note = outcome === "unknown" ? `unconfirmed: ${reason} - the agent could not be reached to learn whether it installed the certificate; unpair it if it shows as paired` : reason;
+			await this.cancel(session, "failed", note);
+		}
+	}
+	/** The new leaf is installed: older leaves of the node go, the new one stays. */
+	async installed(session, leafPem) {
+		await this.deps.revokeNode(session.nodeId, "superseded by pairing", leafPem).catch((err) => this.deps.log?.("older leaves of the node could not be revoked", {
+			nodeId: session.nodeId,
+			error: err instanceof Error ? err.message : String(err)
+		}));
+		this.finish(session, "paired", null);
+		this.deps.log?.("agent paired", {
+			nodeId: session.nodeId,
+			pairingId: session.pairingId
+		});
+	}
+	/** After a failed completion call: did the agent install the certificate after all? */
+	async installOutcome(session) {
+		try {
+			const poll = await this.deps.transport.poll(session.endpoint, session.pairingId);
+			if (poll.last?.pairingId === session.pairingId && poll.last.outcome === "completed") return "installed";
+			return "absent";
+		} catch (err) {
+			return "unknown";
+		}
+	}
+	assertNodeIdUsable(nodeId) {
+		if (!isValidAgentNodeId(nodeId)) throw new Error(`"${nodeId}" cannot be an agent node id (letters, digits, . _ - ; not "hub"; at most 63 characters)`);
+		if (this.deps.isNodeConnected(nodeId)) throw new Error(`a node called "${nodeId}" is already connected to this hub — unpair it first`);
+		const lower = nodeId.toLowerCase();
+		const clash = (this.deps.knownNodeIds?.() ?? []).find((known) => known !== nodeId && known.toLowerCase() === lower);
+		if (clash !== void 0) throw new Error(`"${nodeId}" differs only in case from the existing node "${clash}"`);
+	}
+	expireIfDue(session) {
+		if (TERMINAL.has(session.state) || session.expiresAt > this.now()) return false;
+		this.finish(session, "expired", "the pairing was not confirmed on both sides in time");
+		return true;
+	}
+	finish(session, state, failure) {
+		session.state = state;
+		session.failure = failure;
+	}
+	async cancel(session, state, reason) {
+		this.finish(session, state, reason);
+		await this.deps.transport.reject(session.endpoint, session.pairingId).catch(() => void 0);
+		this.deps.log?.("pairing cancelled", {
+			nodeId: session.nodeId,
+			state,
+			reason
+		});
+	}
+	require(pairingId) {
+		const session = this.sessions.get(pairingId);
+		if (session === void 0) throw new Error("no such pairing");
+		return session;
+	}
+	remember(session) {
+		this.sessions.set(session.pairingId, session);
+		if (this.sessions.size <= MAX_SESSIONS) return;
+		for (const [id, s] of this.sessions) {
+			if (this.sessions.size <= MAX_SESSIONS) break;
+			if (TERMINAL.has(s.state)) this.sessions.delete(id);
+		}
+	}
+	view(s) {
+		return {
+			pairingId: s.pairingId,
+			nodeId: s.nodeId,
+			endpoint: s.endpoint,
+			code: s.code,
+			state: s.state,
+			hubConfirmed: s.hubConfirmed,
+			agentConfirmed: s.agentConfirmed,
+			expiresAt: s.expiresAt,
+			failure: s.failure
+		};
+	}
+};
+//#endregion
 //#region src/builtins/system-config/cluster-secret-keeper.ts
 /**
 * Keeps the hub's cluster-secret gate in step with System → Cluster (D797,
@@ -88102,22 +89434,22 @@ function errText(err) {
 * agent-ui unlock tickets (D821).
 */
 var mintJoinTokenInputSchema = z.object({
-	/** Optional pinned node id for the CSR CN. */
-	nodeId: z.string().min(1).optional(),
+	/** The node id the token is for - mandatory: the CSR CN must be exactly this. */
+	nodeId: z.string().min(1),
 	/** Override hub HTTPS base (default: local-network publicEndpoint). */
 	hubUrl: z.string().url().optional(),
 	/** Override `host:6443` TLS mesh address carried in the token. */
 	hubMeshAddress: z.string().min(3).optional(),
 	/** Seconds until expiry; capped at 1 h. */
 	ttlSec: z.number().int().positive().max(3600).optional()
-}).optional();
+});
 var mintJoinTokenOutputSchema = z.object({
 	token: z.string().min(1),
 	exp: z.number().int(),
 	hubUrl: z.string(),
 	hubMeshAddress: z.string(),
 	caFingerprint: z.string(),
-	nodeId: z.string().optional()
+	nodeId: z.string()
 });
 var mintAgentUiUnlockInputSchema = z.object({
 	nodeId: z.string().min(1),
@@ -88378,7 +89710,7 @@ var SystemConfigAddon = class extends BaseAddon {
 			ca,
 			hubUrl,
 			hubMeshAddress,
-			...input.nodeId !== void 0 ? { nodeId: input.nodeId } : {},
+			nodeId: input.nodeId,
 			...input.ttlSec !== void 0 ? { ttlSec: input.ttlSec } : {}
 		});
 		return {
@@ -88387,7 +89719,7 @@ var SystemConfigAddon = class extends BaseAddon {
 			hubUrl,
 			hubMeshAddress,
 			caFingerprint: caFingerprintCompact(ca.certPem),
-			...input.nodeId !== void 0 ? { nodeId: input.nodeId } : {}
+			nodeId: input.nodeId
 		};
 	}
 	/** D821 — short-lived ticket for the agent's `:4444` unlock session. */
@@ -88399,6 +89731,8 @@ var SystemConfigAddon = class extends BaseAddon {
 		if (input.dashboardBaseUrl !== void 0) {
 			const origins = await this.readAgentDashboardOrigins();
 			if (!isAllowedAgentDashboardReturnTo(input.dashboardBaseUrl, origins)) throw new Error("dashboardBaseUrl is not an allowed agent dashboard origin (:4444 or agentDashboardOrigins)");
+			const known = getProcessAgentHttpsNames()?.namesOf(input.nodeId) ?? null;
+			if (!isKnownAgentAddress(input.dashboardBaseUrl, known, origins)) throw new Error(`dashboardBaseUrl is not an address this hub knows for "${input.nodeId}" - open the agent at its own address`);
 		}
 		const ticket = mintAgentUiUnlockTicket({
 			secretHash: hashClusterSecret(entry.value),
@@ -88677,13 +90011,13 @@ var SystemConfigAddon = class extends BaseAddon {
 	}
 };
 function parseMintJoinTokenInput(input) {
-	if (input === null || input === void 0 || typeof input !== "object") return {};
-	const out = {};
+	if (input === null || input === void 0 || typeof input !== "object") throw new Error("system-config: mintJoinToken requires { nodeId }");
 	const nodeId = Reflect.get(input, "nodeId");
+	if (typeof nodeId !== "string" || nodeId.length === 0) throw new Error("system-config: mintJoinToken requires { nodeId } - the node the token is for");
+	const out = { nodeId };
 	const hubUrl = Reflect.get(input, "hubUrl");
 	const hubMeshAddress = Reflect.get(input, "hubMeshAddress");
 	const ttlSec = Reflect.get(input, "ttlSec");
-	if (typeof nodeId === "string") out.nodeId = nodeId;
 	if (typeof hubUrl === "string") out.hubUrl = hubUrl;
 	if (typeof hubMeshAddress === "string") out.hubMeshAddress = hubMeshAddress;
 	if (typeof ttlSec === "number") out.ttlSec = ttlSec;
@@ -88710,4 +90044,4 @@ function readJwtExp(token) {
 	return typeof exp === "number" ? exp : 0;
 }
 //#endregion
-export { verifyAgentUiUnlockTicket as $, setProcessMeshCertificateRegistry as A, generateMeshCa as B, setProcessMeshTlsListenerState as C, RENEWAL_ABANDONED as D, MeshCertificateRegistry as E, requireProcessMeshCa as F, AGENT_DASHBOARD_ORIGINS_FIELD as G, issueMeshLeafForNode as H, caFingerprint as I, AGENT_UI_UNLOCK_VERSION as J, AGENT_UI_UNLOCK_DOMAIN as K, caFingerprintCompact as L, processMeshCrl as M, MeshCaKeeper as N, describeMeshLeaf as O, getProcessMeshCaState as P, parseAgentDashboardOrigins as Q, createMeshCsrPem as R, openMeshTlsWhenRevocationsLoaded as S, SYSTEM_CONFIG_CLUSTER_SECTION_ID, SystemConfigAddon, SystemConfigAddon as default, MESH_NODE_CERTIFICATES_COLUMNS as T, issueMeshLeafFromCsr as U, generateMeshKeyPair as V, loadMeshCa as W, isAllowedAgentDashboardReturnTo as X, UnlockTicketJtiStore as Y, mintAgentUiUnlockTicket as Z, onProcessNodeRegistered as _, ServiceBroker as a, requestProcessMeshEnforcement as at, revokeMeshCertificate as b, enrollMeshNode as c, setProcessMeshEnforcer as ct, processJoinTokenJtiStore as d, parseCidrList as dt, MESH_AUTH_MODE_FIELD as et, verifyMeshJoinToken as f, readCidrSetting as ft, getProcessPeerLeaf as g, getProcessNodeMeshTransport as h, Errors as i, parseMeshAuthMode as it, MeshCrl as j, getProcessMeshCertificateRegistry as k, JoinTokenJtiStore as l, createCidrMatcher as lt, emitProcessNodeRegistered as m, MESH_TLS_PORT_HELLO_FIELD as n, getProcessMeshAuthStatus as nt, Transporters as o, setProcessMeshAuthMode as ot, dropProcessPeer as p, AGENT_UI_UNLOCK_TTL_MS as q, TlsTcpTransporter as r, isMeshAuthMode as rt, setProcessMeshTlsEnabler as s, setProcessMeshAuthStatusSource as st, systemConfigMeshActions as t, getProcessMeshAuthMode as tt, mintMeshJoinToken as u, normalizeIp as ut, setProcessMeshPeerTransportLookup as v, MESH_NODE_CERTIFICATES_COLLECTION as w, getProcessMeshTlsListenerState as x, renewMeshCertificate as y, exportMeshPrivateKeyPem as z };
+export { requireProcessMeshCa as $, dropProcessPeer as A, setProcessMeshAuthStatusSource as At, openMeshTlsWhenRevocationsLoaded as B, Transporters as C, MESH_AUTH_MODE_FIELD as Ct, mintMeshJoinToken as D, parseMeshAuthMode as Dt, JoinTokenJtiStore as E, isMeshAuthMode as Et, onProcessNodeRegistered as F, readCidrSetting as Ft, RENEWAL_ABANDONED as G, MESH_NODE_CERTIFICATES_COLLECTION as H, setProcessMeshPeerTransportLookup as I, setProcessMeshCertificateRegistry as J, describeMeshLeaf as K, renewMeshCertificate as L, getProcessNodeMeshTransport as M, createCidrMatcher as Mt, getProcessPeerLeaf as N, normalizeIp as Nt, processJoinTokenJtiStore as O, requestProcessMeshEnforcement as Ot, isProcessVerifiedMeshPeer as P, parseCidrList as Pt, getProcessMeshCaState as Q, revokeMeshCertificate as R, ServiceBroker as S, SYSTEM_CONFIG_CLUSTER_SECTION_ID, verifyAgentUiUnlockTicketEs256 as St, SystemConfigAddon, SystemConfigAddon as default, enrollMeshNode as T, getProcessMeshAuthStatus as Tt, MESH_NODE_CERTIFICATES_COLUMNS as U, setProcessMeshTlsListenerState as V, MeshCertificateRegistry as W, processMeshCrl as X, MeshCrl as Y, MeshCaKeeper as Z, signPairingProof as _, isAllowedAgentDashboardReturnTo as _t, hubHostFromMeshAddress as a, generateMeshKeyPair as at, TlsTcpTransporter as b, parseAgentDashboardOrigins as bt, PAIRING_MAX_SESSIONS as c, issueMeshLeafFromCsr as ct, PAIRING_PROTOCOL as d, AGENT_UI_UNLOCK_DOMAIN as dt, caFingerprint as et, PAIRING_TTL_MS as f, AGENT_UI_UNLOCK_TTL_MS as ft, keyFingerprintShort as g, UnlockTicketJtiStore as gt, describeCsr as h, AGENT_UI_UNLOCK_VERSION as ht, AgentPairing as i, generateMeshCa as it, emitProcessNodeRegistered as j, setProcessMeshEnforcer as jt, verifyMeshJoinToken as k, setProcessMeshAuthMode as kt, PAIRING_PATHS as l, loadMeshCa as lt, computePairingSas as m, AGENT_UI_UNLOCK_USE as mt, HubPairing as n, createMeshCsrPem as nt, PAIRING_CODE_DIGITS as o, isValidAgentNodeId as ot, computePairingCommitment as p, AGENT_UI_UNLOCK_TYP as pt, getProcessMeshCertificateRegistry as q, PairingHttpError as r, exportMeshPrivateKeyPem as rt, PAIRING_MAX_CODE_ATTEMPTS as s, issueMeshLeafForNode as st, systemConfigMeshActions as t, caFingerprintCompact as tt, PAIRING_PIN_DIGITS as u, AGENT_DASHBOARD_ORIGINS_FIELD as ut, verifyPairingProof as v, mintAgentUiUnlockTicket as vt, setProcessMeshTlsEnabler as w, getProcessMeshAuthMode as wt, Errors as x, verifyAgentUiUnlockTicket as xt, MESH_TLS_PORT_HELLO_FIELD as y, mintAgentUiUnlockTicketEs256 as yt, getProcessMeshTlsListenerState as z };