@camstack/server 1.2.687 → 1.2.688

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.688] - 2026-10-29
+
+### Changed
+
+- Forgetting a node now clears its per-node capability overrides and tells every node-removal-hook owner
+- Forgetting an offline node now revokes its mesh certificates, so it can no longer rejoin by itself; a revoked agent learns it was removed and resets to unpaired.
+
 ## [1.2.687] - 2026-10-29
 
 ### Changed

package/dist/agent/agent-membership-watch.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentMembershipWatch = exports.DEFAULT_MEMBERSHIP_CONFIRM_DELAY_MS = exports.DEFAULT_MEMBERSHIP_ASK_INTERVAL_MS = exports.DEFAULT_MEMBERSHIP_GRACE_MS = void 0;
+exports.DEFAULT_MEMBERSHIP_GRACE_MS = 90_000;
+exports.DEFAULT_MEMBERSHIP_ASK_INTERVAL_MS = 60_000;
+exports.DEFAULT_MEMBERSHIP_CONFIRM_DELAY_MS = 15_000;
+/** `revoked` answers in a row that destroy the pairing. */
+const REVOKED_READS_REQUIRED = 2;
+class AgentMembershipWatch {
+    deps;
+    disconnectedSince = null;
+    lastAskAt = null;
+    revokedReads = 0;
+    asking = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** One step. Resolves once any question this step asked has been handled. */
+    async tick(now) {
+        if (this.asking)
+            return;
+        if (!this.deps.isPaired() || this.deps.isConnected()) {
+            this.reset();
+            return;
+        }
+        this.disconnectedSince ??= now;
+        if (now - this.disconnectedSince < (this.deps.graceMs ?? exports.DEFAULT_MEMBERSHIP_GRACE_MS))
+            return;
+        const interval = this.revokedReads > 0
+            ? (this.deps.confirmDelayMs ?? exports.DEFAULT_MEMBERSHIP_CONFIRM_DELAY_MS)
+            : (this.deps.askIntervalMs ?? exports.DEFAULT_MEMBERSHIP_ASK_INTERVAL_MS);
+        if (this.lastAskAt !== null && now - this.lastAskAt < interval)
+            return;
+        this.lastAskAt = now;
+        this.asking = true;
+        try {
+            await this.handle(await this.deps.ask());
+        }
+        finally {
+            this.asking = false;
+        }
+    }
+    reset() {
+        this.disconnectedSince = null;
+        this.lastAskAt = null;
+        this.revokedReads = 0;
+    }
+    async handle(result) {
+        const tags = { nodeId: this.deps.nodeId };
+        if (result.kind === 'unreachable') {
+            this.revokedReads = 0;
+            this.deps.log.info('could not ask the hub whether this agent is still a member - keeping the pairing', {
+                tags,
+                meta: { error: result.error },
+            });
+            return;
+        }
+        const { status, reason } = result.answer;
+        if (status !== 'revoked') {
+            this.revokedReads = 0;
+            this.deps.log.info(`the hub answered "${status}" to the membership question - keeping the pairing`, {
+                tags,
+            });
+            return;
+        }
+        this.revokedReads += 1;
+        const why = reason ?? 'revoked';
+        if (this.revokedReads < REVOKED_READS_REQUIRED) {
+            this.deps.log.warn(`the hub says this agent's certificate is revoked (${why}) - asking once more before resetting`, {
+                tags,
+                meta: { reason: why },
+            });
+            return;
+        }
+        this.deps.log.warn(`the hub confirmed twice that this agent's certificate is revoked (${why}) - discarding the pairing and becoming pairable again`, { tags, meta: { reason: why } });
+        this.reset();
+        await this.deps.onRevoked(why);
+    }
+}
+exports.AgentMembershipWatch = AgentMembershipWatch;

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

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAgentPaired = isAgentPaired;
 exports.pinnedMeshCaCert = pinnedMeshCaCert;
 exports.persistPairing = persistPairing;
+exports.readPairedHubIdentity = readPairedHubIdentity;
 exports.forgetPairing = forgetPairing;
 exports.pairedLeafFingerprint = pairedLeafFingerprint;
 /**
@@ -48,7 +49,13 @@ const fs = __importStar(require("node:fs"));
 const system_1 = require("@camstack/system");
 const agent_json_file_js_1 = require("./agent-json-file.js");
 /** Keys that exist only while this agent is paired. */
-const PAIRED_KEYS = ['meshTls', 'meshTlsPrevious', 'meshSwap', 'hubAddress'];
+const PAIRED_KEYS = [
+    'meshTls',
+    'meshTlsPrevious',
+    'meshSwap',
+    'hubAddress',
+    'hubUrl',
+];
 /** `agent.json` holds mesh material: the agent is paired. */
 function isAgentPaired(configPath) {
     const meshTls = (0, agent_json_file_js_1.readJsonFile)(configPath)['meshTls'];
@@ -72,9 +79,32 @@ function persistPairing(configPath, pairing) {
     (0, agent_json_file_js_1.writeJsonFile0600)(configPath, {
         ...existing,
         hubAddress: pairing.hubAddress,
+        // The hub's API address the hub itself gave: where a refused agent asks "am I still a member?".
+        hubUrl: pairing.hubUrl,
         meshTls: pairing.meshTls,
     });
 }
+function readPairedHubIdentity(configPath) {
+    const config = (0, agent_json_file_js_1.readJsonFile)(configPath);
+    const meshTls = config['meshTls'];
+    if (meshTls === null || typeof meshTls !== 'object')
+        return null;
+    const certPem = Reflect.get(meshTls, 'certPem');
+    const keyPem = Reflect.get(meshTls, 'keyPem');
+    const caCertPem = Reflect.get(meshTls, 'caCertPem');
+    if (typeof certPem !== 'string' || typeof keyPem !== 'string' || typeof caCertPem !== 'string') {
+        return null;
+    }
+    const hubUrl = config['hubUrl'];
+    const hubAddress = config['hubAddress'];
+    return {
+        hubUrl: typeof hubUrl === 'string' && hubUrl.length > 0 ? hubUrl : null,
+        hubAddress: typeof hubAddress === 'string' && hubAddress.length > 0 ? hubAddress : null,
+        certPem,
+        keyPem,
+        caCertPem,
+    };
+}
 /**
  * Leave the hub: erase the mesh material, the hub address and the HTTPS bundle
  * the hub issued. The agent is unpaired afterwards and accepts offers again.

package/dist/agent/hub-membership-client.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.membershipFetch = void 0;
+exports.askHubMembership = askHubMembership;
+/**
+ * The agent asks its hub "am I still a member?" (D857).
+ *
+ * Two plain HTTPS calls (`MEMBERSHIP_PATHS`): fetch a nonce, then prove possession of the mesh leaf's
+ * private key by signing it. The hub's HTTPS certificate is NOT what this trusts - the hub may serve a
+ * private one - the answer is a JWS signed by the mesh CA key, verified here against the CA this agent
+ * pinned at pairing, bound to the nonce and the leaf. The key never leaves the process: it signs, and
+ * only the signature travels (no argv, no env).
+ *
+ * Every doubt is `unreachable`, never an answer: a hub that cannot be reached, a status other than
+ * 200, a token that does not verify. The caller changes nothing on `unreachable` (D49).
+ */
+const node_crypto_1 = require("node:crypto");
+const system_1 = require("@camstack/system");
+const undici_1 = require("undici");
+const REQUEST_TIMEOUT_MS = 8_000;
+/** Production transport: JSON POST with a timeout, TLS not verified (the answer is CA-signed). */
+const membershipFetch = (url, init) => (0, undici_1.fetch)(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    ...(init.body !== undefined ? { body: init.body } : {}),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    dispatcher: new undici_1.Agent({ connect: { rejectUnauthorized: false } }),
+});
+exports.membershipFetch = membershipFetch;
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function askHubMembership(query, doFetch = exports.membershipFetch) {
+    try {
+        const base = query.hubUrl.replace(/\/+$/, '');
+        const challenge = await doFetch(`${base}${system_1.MEMBERSHIP_PATHS.challenge}`, {
+            body: '{}',
+        });
+        if (challenge.status !== 200) {
+            return {
+                kind: 'unreachable',
+                error: `challenge answered HTTP ${challenge.status}`,
+            };
+        }
+        const nonce = Reflect.get(Object(await challenge.json()), 'nonce');
+        if (typeof nonce !== 'string' || nonce.length === 0) {
+            return { kind: 'unreachable', error: 'challenge carried no nonce' };
+        }
+        const response = await doFetch(`${base}${system_1.MEMBERSHIP_PATHS.query}`, {
+            body: JSON.stringify({
+                nodeId: query.nodeId,
+                certPem: query.certPem,
+                nonce,
+                signature: (0, system_1.signMembershipProof)(query.keyPem, query.nodeId, nonce),
+            }),
+        });
+        if (response.status !== 200) {
+            return {
+                kind: 'unreachable',
+                error: `membership answered HTTP ${response.status}`,
+            };
+        }
+        const token = Reflect.get(Object(await response.json()), 'token');
+        if (typeof token !== 'string')
+            return { kind: 'unreachable', error: 'answer carried no token' };
+        const answer = (0, system_1.verifyMembershipAnswer)(query.caCertPem, token, {
+            nodeId: query.nodeId,
+            nonce,
+            leafFingerprint: new node_crypto_1.X509Certificate(query.certPem).fingerprint256,
+        });
+        if (answer === null) {
+            return {
+                kind: 'unreachable',
+                error: 'the answer is not signed by the pinned mesh CA',
+            };
+        }
+        return { kind: 'answer', answer };
+    }
+    catch (err) {
+        return { kind: 'unreachable', error: errorMessage(err) };
+    }
+}

package/dist/agent/main.js

@@ -49,7 +49,9 @@ const agent_addon_updates_js_1 = require("./agent-addon-updates.js");
 const agent_hub_registration_js_1 = require("./agent-hub-registration.js");
 const agent_mesh_gate_js_1 = require("./agent-mesh-gate.js");
 const agent_pairing_local_js_1 = require("./agent-pairing-local.js");
+const agent_membership_watch_js_1 = require("./agent-membership-watch.js");
 const agent_pairing_store_js_1 = require("./agent-pairing-store.js");
+const hub_membership_client_js_1 = require("./hub-membership-client.js");
 const agent_config_js_1 = require("./agent-config.js");
 const agent_group_runner_js_1 = require("./agent-group-runner.js");
 const agent_http_js_1 = require("./agent-http.js");
@@ -76,6 +78,8 @@ const register_agent_cap_dispatch_js_1 = require("./register-agent-cap-dispatch.
 const system_2 = require("@camstack/system");
 /** A reconnect (stop + rebuild + start) that takes longer than this is abandoned. */
 const RECONNECT_DEADLINE_MS = 90_000;
+/** How often the agent re-evaluates whether to ask its hub "am I still a member?" (D857). */
+const MEMBERSHIP_TICK_MS = 15_000;
 const agentLogManager = new system_2.LogManager(5000);
 /**
  * Caps whose `nodeId` arg is provider DATA (`nodeIdMode: 'data'` —
@@ -992,6 +996,41 @@ async function startAgent(configPath) {
         advertise();
     };
     advertise();
+    // A hub that forgot or unpaired this agent refuses its leaf without a word. While paired but not
+    // connected, ask the hub whether the leaf is still a member; two CA-signed `revoked` answers in a
+    // row discard the pairing, anything else changes nothing (D857, D49).
+    const membershipWatch = new agent_membership_watch_js_1.AgentMembershipWatch({
+        nodeId: config.nodeId,
+        isPaired: () => (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath),
+        isConnected: () => getHubConnectionState() === 'connected',
+        ask: async () => {
+            const identity = (0, agent_pairing_store_js_1.readPairedHubIdentity)(config.configPath);
+            const hubUrl = identity?.hubUrl ??
+                (identity?.hubAddress != null ? (0, derive_hub_url_js_1.deriveHubUrlFromHubAddress)(identity.hubAddress) : undefined);
+            if (identity === null || hubUrl === undefined) {
+                return { kind: 'unreachable', error: 'no hub address on record' };
+            }
+            return (0, hub_membership_client_js_1.askHubMembership)({
+                hubUrl,
+                nodeId: config.nodeId,
+                certPem: identity.certPem,
+                keyPem: identity.keyPem,
+                caCertPem: identity.caCertPem,
+            });
+        },
+        onRevoked: (reason) => forgetHubNow(`the hub revoked this agent's certificate (${reason})`),
+        log: {
+            // The console line has no tag column: the node id rides in the text as well.
+            warn: (message, extras) => consoleLogger.warn(`${message} [nodeId=${config.nodeId}]`, extras),
+            info: (message, extras) => consoleLogger.info(`${message} [nodeId=${config.nodeId}]`, extras),
+        },
+    });
+    const membershipTimer = setInterval(() => {
+        void membershipWatch
+            .tick(Date.now())
+            .catch((err) => consoleLogger.warn(`membership check failed: ${(0, types_2.errMsg)(err)}`));
+    }, MEMBERSHIP_TICK_MS);
+    membershipTimer.unref();
     void (0, agent_http_js_1.startAgentHttpServer)(getBrokerFn, {
         log: {
             info: (message, extras) => consoleLogger.info(message, extras),

package/dist/api/core/cluster-nodes.router.js

@@ -35,6 +35,13 @@ const ForgetNodeResultSchema = zod_1.z.object({
     registryRemoved: zod_1.z.boolean(),
     /** Read back AFTER the attempt: the node is still in the cluster registry. */
     stillListed: zod_1.z.boolean(),
+    /** What happened to the node's mesh certificates: `registry-unavailable` / `failed` = NOT revoked. */
+    certificates: zod_1.z.discriminatedUnion('outcome', [
+        zod_1.z.object({ outcome: zod_1.z.literal('not-attempted') }),
+        zod_1.z.object({ outcome: zod_1.z.literal('revoked'), serials: zod_1.z.array(zod_1.z.string()) }),
+        zod_1.z.object({ outcome: zod_1.z.literal('registry-unavailable') }),
+        zod_1.z.object({ outcome: zod_1.z.literal('failed'), error: zod_1.z.string() }),
+    ]),
     /** One operator-grade sentence naming what happened. */
     message: zod_1.z.string(),
 });

package/dist/api/mesh-membership-routes.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProcessMembershipResponder = createProcessMembershipResponder;
+exports.registerMeshMembershipRoutes = registerMeshMembershipRoutes;
+const system_1 = require("@camstack/system");
+const auth_rate_limit_1 = require("../auth/auth-rate-limit");
+const WINDOW_MS = 60_000;
+const DEFAULT_PER_MINUTE = 60;
+function createProcessMembershipResponder(logger) {
+    return new system_1.MembershipResponder({
+        registry: system_1.getProcessMeshCertificateRegistry,
+        crl: system_1.processMeshCrl,
+        caKeyPem: () => {
+            const state = (0, system_1.getProcessMeshCaState)();
+            return state.state === 'ready' ? state.ca.keyPem : null;
+        },
+        log: (message, meta) => logger.warn(message, { tags: { nodeId: meta.nodeId } }),
+    });
+}
+function registerMeshMembershipRoutes(fastify, options) {
+    const responder = options.responder ?? createProcessMembershipResponder(options.logger);
+    const limiter = (0, auth_rate_limit_1.createRateLimiter)({
+        windowMs: WINDOW_MS,
+        max: options.perMinute ?? DEFAULT_PER_MINUTE,
+        ...(options.now !== undefined ? { now: options.now } : {}),
+    });
+    fastify.post(system_1.MEMBERSHIP_PATHS.challenge, async (request, reply) => {
+        const verdict = limiter.check(request.socket.remoteAddress ?? 'unknown');
+        if (!verdict.allowed) {
+            return reply
+                .status(429)
+                .header('retry-after', String(verdict.retryAfterSeconds))
+                .send({ ok: false });
+        }
+        return { nonce: responder.issueChallenge() };
+    });
+    fastify.post(system_1.MEMBERSHIP_PATHS.query, async (request, reply) => {
+        const verdict = limiter.check(request.socket.remoteAddress ?? 'unknown');
+        if (!verdict.allowed) {
+            return reply
+                .status(429)
+                .header('retry-after', String(verdict.retryAfterSeconds))
+                .send({ ok: false });
+        }
+        const outcome = responder.answer(request.body);
+        if (!outcome.ok)
+            return reply.status(outcome.status).send({ ok: false });
+        return { token: outcome.token };
+    });
+}

package/dist/api/trpc/generated-cap-mounts.js

@@ -2,7 +2,7 @@
 // AUTO-GENERATED by scripts/generate-cap-mounts.ts — DO NOT EDIT
 // Re-run: npx tsx scripts/generate-cap-mounts.ts
 //
-// Mounted: 187    Skipped (legacy): 3
+// Mounted: 188    Skipped (legacy): 3
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LEGACY_SHAPE_SKIP = void 0;
 exports.mountAllCaps = mountAllCaps;
@@ -456,6 +456,15 @@ function mountAllCaps(services) {
             null, remoteCapProxy),
         nodeCertificates: (0, generated_cap_routers_js_1.createCapRouter_nodeCertificates)((_ctx) => reg?.getSingleton('node-certificates') ??
             null, remoteCapProxy),
+        nodeRemovalHook: (0, generated_cap_routers_js_1.createCapRouter_nodeRemovalHook)((_ctx, addonId) => {
+            if (!reg)
+                return null;
+            if (addonId !== undefined) {
+                return reg.getProviderByAddonId('node-removal-hook', addonId);
+            }
+            const entries = reg.getCollectionEntries('node-removal-hook');
+            return entries[0]?.[1] ?? null;
+        }, remoteCapProxy),
         nodes: (0, generated_cap_routers_js_1.createCapRouter_nodes)((_ctx) => reg?.getSingleton('nodes') ?? null, remoteCapProxy),
         notificationOutput: (0, generated_cap_routers_js_1.createCapRouter_notificationOutput)((_ctx, addonId) => {
             if (!reg)