@camstack/server 1.2.563 → 1.2.565

package/dist/agent/agent-http.js

@@ -57,6 +57,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const fastify_1 = __importDefault(require("fastify"));
 const system_1 = require("@camstack/system");
+const agent_sniffing_listener_js_1 = require("./agent-sniffing-listener.js");
 const agent_http_auth_js_1 = require("./agent-http-auth.js");
 const node_1 = require("@camstack/types/node");
 const agent_mesh_enroll_js_1 = require("./agent-mesh-enroll.js");
@@ -619,13 +620,33 @@ async function createAgentHttpServer(getBroker, config) {
 // ---------------------------------------------------------------------------
 // Start helper
 // ---------------------------------------------------------------------------
+/**
+ * Start the agent API on its port, which also speaks TLS (D856): the first byte
+ * of a connection picks the protocol, so there is no second port. Resolves with
+ * the listener (to hot-swap the certificate), or `null` when it failed to start.
+ */
 async function startAgentHttpServer(getBroker, config) {
     try {
         const app = await createAgentHttpServer(getBroker, config);
-        await app.listen({ port: config.port, host: '0.0.0.0' });
-        console.log(`[Agent] HTTP server: http://localhost:${config.port}`);
+        await app.ready();
+        const material = (0, system_1.loadAgentHttps)(config.dataDir, (reason) => config.log?.error('The HTTPS bundle on disk is unusable - serving plain HTTP only', {
+            meta: { reason },
+        }));
+        const listener = await (0, agent_sniffing_listener_js_1.startSniffingListener)({
+            httpServer: app.server,
+            port: config.port,
+            host: '0.0.0.0',
+            material: material === null ? null : { keyPem: material.keyPem, certPem: material.certPem },
+            ...(config.log !== undefined ? { log: config.log } : {}),
+            onTlsRefused: () => config.log?.warn('A TLS client reached the agent port but no HTTPS certificate is installed yet - closed'),
+        });
+        config.log?.info('Agent HTTP server listening', {
+            meta: { port: config.port, https: material !== null },
+        });
+        return listener;
     }
     catch (err) {
         console.warn(`[Agent] HTTP server failed to start on port ${config.port}:`, err);
+        return null;
     }
 }

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

@@ -37,6 +37,8 @@ exports.MeshEnrollError = void 0;
 exports.decodeJoinTokenClaims = decodeJoinTokenClaims;
 exports.hubHostFromMeshAddress = hubHostFromMeshAddress;
 exports.enrollAgentMesh = enrollAgentMesh;
+exports.readJsonFile = readJsonFile;
+exports.writeJsonFile0600 = writeJsonFile0600;
 exports.persistEnrollment = persistEnrollment;
 exports.discardPendingJoinToken = discardPendingJoinToken;
 exports.enrollAndPersist = enrollAndPersist;

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

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentNodeCertificates = createAgentNodeCertificates;
+/**
+ * The agent's side of certificate management (D856): the `node-certificates`
+ * capability, provided by the agent runtime and called by the hub through the
+ * ordinary node-pinned capability call.
+ *
+ * MESH leaf. The hub asks for a CSR; this node makes a NEW key pair (the key never
+ * leaves it) and keeps it in memory only. When the signed leaf arrives it is persisted
+ * into `agent.json` (0600) BESIDE the old one (`meshTlsPrevious`) together with the
+ * swap's state (`meshSwap`: which leaf, until when), then the agent reconnects through
+ * the same `reconnect()` the UI uses, which rebuilds the broker from the file.
+ *
+ * A swap is PENDING from install until the hub confirms. Only while it is pending may
+ * the node go back, and only to a previous leaf that is still unexpired:
+ *  - the swap state is in the file, not in memory, so it survives a restart: at boot a
+ *    swap whose deadline is still ahead re-arms its rollback timer; one whose deadline
+ *    has passed is settled (the current leaf stays, the leftovers are dropped);
+ *  - a `meshTlsPrevious` with no pending swap is a leftover and is deleted at boot and on
+ *    the next renewal, so a failed renewal can never restore a stale or expired leaf.
+ *
+ * HTTPS leaf. Same shape: key pair + CSR here, signed public key back, ONE atomic file
+ * under `<dataDir>/tls`, hot-swapped into the sniffing listener.
+ */
+const node_crypto_1 = require("node:crypto");
+const system_1 = require("@camstack/system");
+const agent_mesh_enroll_js_1 = require("./agent-mesh-enroll.js");
+/** Let the capability answer before the broker is torn down and rebuilt. */
+const RECONNECT_DELAY_MS = 400;
+/** A swap found pending at boot gets at least this long for the hub to confirm. */
+const MIN_REARM_MS = 10_000;
+function isMeshMaterial(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof Reflect.get(value, 'certPem') === 'string' &&
+        typeof Reflect.get(value, 'keyPem') === 'string' &&
+        typeof Reflect.get(value, 'caCertPem') === 'string');
+}
+function isMeshSwap(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof Reflect.get(value, 'fingerprint') === 'string' &&
+        typeof Reflect.get(value, 'deadline') === 'number');
+}
+function defaultSchedule(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return { cancel: () => clearTimeout(timer) };
+}
+function createAgentNodeCertificates(deps) {
+    const { nodeId, log } = deps;
+    const tags = { nodeId };
+    const schedule = deps.schedule ?? defaultSchedule;
+    const now = deps.now ?? Date.now;
+    let pendingKeyPem = null;
+    let rollbackTimer = null;
+    const readMesh = () => {
+        const raw = (0, agent_mesh_enroll_js_1.readJsonFile)(deps.configPath);
+        return {
+            current: isMeshMaterial(raw['meshTls']) ? raw['meshTls'] : null,
+            previous: isMeshMaterial(raw['meshTlsPrevious']) ? raw['meshTlsPrevious'] : null,
+            swap: isMeshSwap(raw['meshSwap']) ? raw['meshSwap'] : null,
+        };
+    };
+    const stillValid = (material) => {
+        try {
+            return (0, system_1.describeMeshLeaf)(material.certPem).notAfter > now();
+        }
+        catch {
+            return false;
+        }
+    };
+    /** Write `agent.json` with the swap leftovers removed and `meshTls` optionally replaced. */
+    const writeSettled = (replaceCurrent) => {
+        const raw = (0, agent_mesh_enroll_js_1.readJsonFile)(deps.configPath);
+        const { meshTlsPrevious: _p, meshSwap: _s, ...rest } = raw;
+        (0, agent_mesh_enroll_js_1.writeJsonFile0600)(deps.configPath, {
+            ...rest,
+            ...(replaceCurrent !== undefined ? { meshTls: replaceCurrent } : {}),
+        });
+    };
+    const reconnectSoon = () => {
+        schedule(() => {
+            deps.reconnect().catch((error) => {
+                log.error('Mesh leaf swap: reconnect failed', {
+                    tags,
+                    meta: { error: error instanceof Error ? error.message : String(error) },
+                });
+            });
+        }, RECONNECT_DELAY_MS);
+    };
+    /**
+     * Go back to the previous leaf. Only while a swap is PENDING and only to a leaf that is
+     * still unexpired; otherwise the file is settled as it is and `false` is returned.
+     */
+    const revert = (why) => {
+        const { current, previous, swap } = readMesh();
+        rollbackTimer?.cancel();
+        rollbackTimer = null;
+        if (swap === null) {
+            log.warn('Mesh leaf rollback refused: no swap is pending', { tags, meta: { why } });
+            if (previous !== null)
+                writeSettled(); // a leftover; never a rollback target
+            return false;
+        }
+        if (previous === null || !stillValid(previous)) {
+            log.warn('Mesh leaf rollback refused: the previous leaf is gone or expired - keeping the current one', {
+                tags,
+                meta: { why, currentValid: current !== null && stillValid(current) },
+            });
+            writeSettled();
+            return false;
+        }
+        writeSettled(previous);
+        log.warn('Mesh leaf swap: reverted to the previous leaf', { tags, meta: { why } });
+        reconnectSoon();
+        return true;
+    };
+    const armRollback = (ms) => {
+        rollbackTimer?.cancel();
+        rollbackTimer = schedule(() => {
+            revert('the hub did not confirm the new leaf in time');
+        }, ms);
+    };
+    // Boot: decide which leaf is current and drop whatever a past swap left behind.
+    const settleAtBoot = () => {
+        const { current, previous, swap } = readMesh();
+        if (previous === null && swap === null)
+            return;
+        if (swap !== null && previous !== null && swap.deadline > now()) {
+            armRollback(Math.max(MIN_REARM_MS, swap.deadline - now()));
+            log.warn('Mesh leaf swap was pending at boot - waiting for the hub to confirm', {
+                tags,
+                meta: { remainingMs: swap.deadline - now() },
+            });
+            return;
+        }
+        if (current !== null && stillValid(current)) {
+            writeSettled();
+            log.info('Mesh leaf swap leftovers removed at boot (the current leaf is valid)', { tags });
+            return;
+        }
+        if (previous !== null && stillValid(previous)) {
+            writeSettled(previous);
+            log.warn('The current mesh leaf is expired and the previous one is valid - restored it', {
+                tags,
+            });
+            reconnectSoon();
+            return;
+        }
+        writeSettled();
+        log.error('No valid mesh leaf on this node: renew it from the hub or re-join with a join token', {
+            tags,
+        });
+    };
+    settleAtBoot();
+    return {
+        getCertificates: async () => {
+            const { current } = readMesh();
+            const https = (0, system_1.loadAgentHttps)(deps.dataDir, (reason) => log.error('The HTTPS bundle on disk is unusable - serving plain HTTP only', {
+                tags,
+                meta: { reason },
+            }));
+            let mesh = null;
+            if (current !== null) {
+                const leaf = (0, system_1.describeMeshLeaf)(current.certPem);
+                mesh = {
+                    cn: leaf.cn,
+                    serial: leaf.serial,
+                    fingerprintSha256: leaf.fingerprint,
+                    notBefore: leaf.notBefore,
+                    notAfter: leaf.notAfter,
+                };
+            }
+            return {
+                nodeId,
+                mesh,
+                https: https === null
+                    ? {
+                        state: 'not-issued',
+                        reason: 'No hub-issued HTTPS certificate has been installed on this node yet.',
+                    }
+                    : { state: 'served', leaf: (0, system_1.describeHttpsLeaf)(https.certPem) },
+            };
+        },
+        prepareMeshRenewal: async () => {
+            const { current, swap } = readMesh();
+            if (current === null) {
+                throw new Error('this node is not enrolled on mesh mTLS - there is no leaf to renew');
+            }
+            if (swap !== null && swap.deadline > now()) {
+                throw new Error('a mesh leaf swap is already pending on this node');
+            }
+            // A leftover from a finished or failed swap is never a rollback target.
+            writeSettled();
+            const keys = await (0, system_1.generateMeshKeyPair)();
+            pendingKeyPem = await (0, system_1.exportMeshPrivateKeyPem)(keys.privateKey);
+            const csrPem = await (0, system_1.createMeshCsrPem)(keys, nodeId);
+            log.info('Mesh leaf renewal: new key and CSR generated', { tags });
+            return { csrPem };
+        },
+        installMeshLeaf: async (input) => {
+            const { current } = readMesh();
+            if (current === null)
+                throw new Error('this node is not enrolled on mesh mTLS');
+            if (pendingKeyPem === null) {
+                throw new Error('no pending key: prepareMeshRenewal was not called (or the node restarted)');
+            }
+            const leaf = new node_crypto_1.X509Certificate(input.certPem);
+            const ca = new node_crypto_1.X509Certificate(input.caCertPem);
+            const currentCa = new node_crypto_1.X509Certificate(current.caCertPem);
+            if (ca.fingerprint256 !== currentCa.fingerprint256) {
+                throw new Error('the CA that came with the new leaf is not the CA this node trusts');
+            }
+            if (!leaf.verify(ca.publicKey))
+                throw new Error('the new leaf is not signed by that CA');
+            if (!new RegExp(`(?:^|\\n)CN=${nodeId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\n|$)`).test(leaf.subject)) {
+                throw new Error(`the new leaf is not issued for "${nodeId}"`);
+            }
+            if (!leaf.checkPrivateKey((0, node_crypto_1.createPrivateKey)(pendingKeyPem))) {
+                throw new Error('the new leaf does not match the key this node generated');
+            }
+            const raw = (0, agent_mesh_enroll_js_1.readJsonFile)(deps.configPath);
+            const swap = {
+                fingerprint: leaf.fingerprint256,
+                deadline: now() + input.confirmWithinMs,
+            };
+            (0, agent_mesh_enroll_js_1.writeJsonFile0600)(deps.configPath, {
+                ...raw,
+                meshTls: { certPem: input.certPem, keyPem: pendingKeyPem, caCertPem: current.caCertPem },
+                meshTlsPrevious: current,
+                meshSwap: swap,
+            });
+            pendingKeyPem = null;
+            armRollback(input.confirmWithinMs);
+            log.info('Mesh leaf swap: new leaf persisted, reconnecting', {
+                tags,
+                meta: { serial: leaf.serialNumber, confirmWithinMs: input.confirmWithinMs },
+            });
+            reconnectSoon();
+            return { fingerprintSha256: leaf.fingerprint256, serial: leaf.serialNumber };
+        },
+        confirmMeshLeaf: async (input) => {
+            const { swap } = readMesh();
+            if (swap === null || swap.fingerprint !== input.fingerprintSha256) {
+                return { confirmed: false };
+            }
+            rollbackTimer?.cancel();
+            rollbackTimer = null;
+            writeSettled();
+            log.info('Mesh leaf swap: confirmed by the hub, previous leaf forgotten', { tags });
+            return { confirmed: true };
+        },
+        rollbackMeshLeaf: async () => ({ rolledBack: revert('the hub asked for a rollback') }),
+        prepareHttpsCertificate: async () => {
+            const names = (0, system_1.collectAgentNames)(nodeId, deps.hostFacts);
+            const request = await (0, system_1.createAgentHttpsRequest)(deps.dataDir, nodeId, names);
+            log.info('HTTPS certificate: new key and CSR generated', {
+                tags,
+                meta: { hostnames: names.hostnames.length, addresses: names.addresses.length },
+            });
+            return {
+                csrPem: request.csrPem,
+                hostnames: [...names.hostnames],
+                addresses: [...names.addresses],
+                pinnedCaFingerprintSha256: (0, system_1.pinnedHttpsCaFingerprint)(deps.dataDir),
+            };
+        },
+        installHttpsCertificate: async (input) => {
+            const material = (0, system_1.installAgentHttps)(deps.dataDir, input);
+            const listener = deps.getHttpsListener();
+            if (listener === null) {
+                log.warn('HTTPS certificate installed on disk but the agent HTTP listener is not up', {
+                    tags,
+                });
+            }
+            else if (!listener.setMaterial({ keyPem: material.keyPem, certPem: material.certPem })) {
+                log.error('The new HTTPS certificate was installed but the listener refused it - the previous one keeps serving', {
+                    tags,
+                });
+            }
+            const leaf = (0, system_1.describeHttpsLeaf)(material.certPem);
+            log.info('HTTPS certificate installed and hot-swapped', {
+                tags,
+                meta: {
+                    fingerprint: leaf.fingerprintSha256,
+                    notAfter: new Date(leaf.notAfter).toISOString(),
+                },
+            });
+            return leaf;
+        },
+    };
+}

package/dist/agent/agent-reconnect.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReconnectRunner = createReconnectRunner;
+function createReconnectRunner(deps) {
+    let generation = 0;
+    return async () => {
+        const mine = ++generation;
+        const superseded = () => mine !== generation;
+        try {
+            await deps.stop(deps.current());
+        }
+        catch {
+            /* already stopped */
+        }
+        if (superseded()) {
+            deps.onSuperseded?.('before-build');
+            return;
+        }
+        deps.prepare();
+        const next = deps.build();
+        if (superseded()) {
+            deps.onSuperseded?.('after-build');
+            await deps.stop(next).catch(() => undefined);
+            return;
+        }
+        deps.assign(next);
+        await deps.start(next);
+        if (superseded()) {
+            // A newer run replaced `next` while it was starting: do not leave it running.
+            deps.onSuperseded?.('after-start');
+            await deps.stop(next).catch(() => undefined);
+        }
+    };
+}

package/dist/agent/agent-sniffing-listener.js

@@ -0,0 +1,263 @@
+"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.HANDSHAKE_TIMEOUT_MS = exports.SNIFF_TIMEOUT_MS = exports.TLS_HANDSHAKE_RECORD = void 0;
+exports.startSniffingListener = startSniffingListener;
+/**
+ * One port, two protocols (D856): the agent's HTTP port also speaks TLS.
+ *
+ * The first byte of a connection decides. A TLS ClientHello starts with the
+ * handshake record type `0x16`; HTTP starts with an ASCII method letter. So a
+ * plain `curl http://agent:4444` and an `https://agent:4444` both reach the same
+ * Fastify instance on the SAME port - the container contract (ports, volumes,
+ * the templates that mirror them) does not change.
+ *
+ * Why this is safe: no HTTP method begins with 0x16 (all are upper-case ASCII
+ * letters), and no TLS record begins with a letter, so the two cannot be
+ * confused. A client that sends nothing is dropped after {@link SNIFF_TIMEOUT_MS}.
+ * A TLS client when no certificate is installed is closed (and counted), never
+ * served in the clear. Fastify's `http.Server` is used as-is: both paths hand it a
+ * socket through its `connection` event.
+ *
+ * The serving certificate is swapped with `setSecureContext` - new handshakes use
+ * it at once, existing connections keep the old one, nothing restarts.
+ */
+const net = __importStar(require("node:net"));
+const node_stream_1 = require("node:stream");
+const tls = __importStar(require("node:tls"));
+exports.TLS_HANDSHAKE_RECORD = 0x16;
+exports.SNIFF_TIMEOUT_MS = 10_000;
+exports.HANDSHAKE_TIMEOUT_MS = 10_000;
+const STALL_WARN_EVERY_MS = 60_000;
+/** On shutdown, connections still open after this long are destroyed. */
+const CLOSE_GRACE_MS = 2_000;
+/**
+ * The raw socket once its first chunk has been read. Node's HTTP parser and TLS
+ * wrapper both read a net.Socket NATIVELY (`socket._handle`), bypassing any bytes
+ * already pulled into JS - so handing them the raw socket loses the byte(s) we
+ * sniffed. This duplex replays the first chunk and then forwards the socket, and
+ * exposes the address fields the servers (and the agent's loopback check) read.
+ */
+class ReplayDuplex extends node_stream_1.Duplex {
+    socket;
+    pending;
+    constructor(socket, first) {
+        super();
+        this.socket = socket;
+        this.pending = first;
+        socket.on('data', (chunk) => {
+            if (!this.push(chunk))
+                socket.pause();
+        });
+        socket.on('end', () => this.push(null));
+        socket.on('error', (err) => this.destroy(err));
+        socket.on('close', () => this.destroy());
+        socket.on('timeout', () => this.emit('timeout'));
+    }
+    get remoteAddress() {
+        return this.socket.remoteAddress;
+    }
+    get remotePort() {
+        return this.socket.remotePort;
+    }
+    get remoteFamily() {
+        return this.socket.remoteFamily;
+    }
+    get localAddress() {
+        return this.socket.localAddress;
+    }
+    get localPort() {
+        return this.socket.localPort;
+    }
+    setTimeout(ms, callback) {
+        this.socket.setTimeout(ms);
+        if (callback !== undefined)
+            this.once('timeout', callback);
+        return this;
+    }
+    setNoDelay(noDelay) {
+        this.socket.setNoDelay(noDelay);
+        return this;
+    }
+    setKeepAlive(enable, delay) {
+        this.socket.setKeepAlive(enable, delay);
+        return this;
+    }
+    ref() {
+        this.socket.ref();
+        return this;
+    }
+    unref() {
+        this.socket.unref();
+        return this;
+    }
+    _read() {
+        if (this.pending !== null) {
+            const first = this.pending;
+            this.pending = null;
+            this.push(first);
+        }
+        this.socket.resume();
+    }
+    _write(chunk, encoding, callback) {
+        this.socket.write(chunk, encoding, callback);
+    }
+    _final(callback) {
+        this.socket.end(callback);
+    }
+    _destroy(error, callback) {
+        this.socket.destroy(error ?? undefined);
+        callback(error);
+    }
+}
+function startSniffingListener(options) {
+    // The serving context. A swap replaces it: every NEW handshake uses the new one,
+    // connections already established keep what they negotiated.
+    let secureContext = null;
+    let refused = 0;
+    const sniffTimeoutMs = options.sniffTimeoutMs ?? exports.SNIFF_TIMEOUT_MS;
+    /** Every live connection, so shutdown can end them instead of waiting on idle keep-alives. */
+    const live = new Set();
+    const track = (socket) => {
+        live.add(socket);
+        socket.once('close', () => live.delete(socket));
+    };
+    // A scanner opening many half handshakes must not fill the log: one warning a minute,
+    // with how many were suppressed.
+    let lastStallWarnAt = 0;
+    let suppressedStalls = 0;
+    const handshakeTimeoutMs = options.handshakeTimeoutMs ?? exports.HANDSHAKE_TIMEOUT_MS;
+    const setMaterial = (material) => {
+        try {
+            secureContext = tls.createSecureContext({ key: material.keyPem, cert: material.certPem });
+            return true;
+        }
+        catch (error) {
+            options.log?.error('HTTPS material rejected - the previous certificate (or plain HTTP) keeps serving', {
+                meta: { error: error instanceof Error ? error.message : String(error) },
+            });
+            return false;
+        }
+    };
+    if (options.material !== undefined && options.material !== null) {
+        setMaterial(options.material);
+    }
+    /** A server-side TLS socket over the replayed raw socket, handed to HTTP once secure. */
+    const serveTls = (replayed, context) => {
+        const secure = new tls.TLSSocket(replayed, {
+            isServer: true,
+            secureContext: context,
+            minVersion: 'TLSv1.2',
+        });
+        // The decrypted socket does not carry the peer address of the stream under it, and
+        // the agent's auth gate reads it (loopback is trusted, a remote caller is not).
+        Object.defineProperty(secure, 'remoteAddress', { value: replayed.remoteAddress });
+        Object.defineProperty(secure, 'remotePort', { value: replayed.remotePort });
+        secure.on('error', () => undefined);
+        // A client that starts a handshake and stalls must not hold a socket for ever.
+        const stalled = setTimeout(() => {
+            const at = Date.now();
+            if (at - lastStallWarnAt >= STALL_WARN_EVERY_MS) {
+                options.log?.warn('TLS handshake did not finish in time - connection destroyed', {
+                    meta: {
+                        remote: replayed.remoteAddress ?? null,
+                        afterMs: handshakeTimeoutMs,
+                        alsoSuppressed: suppressedStalls,
+                    },
+                });
+                lastStallWarnAt = at;
+                suppressedStalls = 0;
+            }
+            else {
+                suppressedStalls += 1;
+            }
+            secure.destroy();
+            replayed.destroy();
+        }, handshakeTimeoutMs);
+        secure.once('close', () => clearTimeout(stalled));
+        secure.once('secure', () => {
+            clearTimeout(stalled);
+            options.httpServer.emit('connection', secure);
+        });
+    };
+    const server = net.createServer({ pauseOnConnect: true }, (socket) => {
+        track(socket);
+        const timer = setTimeout(() => socket.destroy(), sniffTimeoutMs);
+        socket.on('error', () => undefined);
+        // `data` (not `readable`): the chunk is handed back to the stream with `unshift`
+        // before the chosen server takes the socket, so the protocol parser sees every byte.
+        socket.once('data', (chunk) => {
+            clearTimeout(timer);
+            socket.pause();
+            if (chunk[0] === exports.TLS_HANDSHAKE_RECORD) {
+                if (secureContext === null) {
+                    refused += 1;
+                    options.onTlsRefused?.();
+                    socket.destroy();
+                    return;
+                }
+                serveTls(new ReplayDuplex(socket, chunk), secureContext);
+            }
+            else {
+                options.httpServer.emit('connection', new ReplayDuplex(socket, chunk));
+            }
+        });
+        // The connection arrived paused (`pauseOnConnect`); start reading to see the first byte.
+        socket.resume();
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen({ port: options.port, host: options.host }, () => {
+            const address = server.address();
+            const port = address !== null && typeof address === 'object' ? address.port : options.port;
+            resolve({
+                port,
+                setMaterial,
+                tlsRefusedCount: () => refused,
+                close: () => new Promise((done) => {
+                    // Stop listening, give in-flight requests a moment, then end every connection:
+                    // an idle keep-alive would otherwise keep the process (and the port) alive.
+                    server.close(() => done());
+                    const grace = setTimeout(() => {
+                        for (const socket of live)
+                            socket.destroy();
+                    }, CLOSE_GRACE_MS);
+                    grace.unref?.();
+                    server.once('close', () => clearTimeout(grace));
+                }),
+            });
+        });
+    });
+}

package/dist/agent/agent-update-service.js

@@ -348,5 +348,8 @@ function writeAgentRestartMarker(dataDir, requestedBy, update) {
  * though no `loadedAddons` entry owns it.
  */
 function agentRuntimeManifestEntry() {
-    return { addonId: exports.AGENT_RUNTIME_ADDON_ID, capabilities: ['server-management'] };
+    return {
+        addonId: exports.AGENT_RUNTIME_ADDON_ID,
+        capabilities: ['server-management', 'node-certificates'],
+    };
 }