@camstack/system 1.2.428 → 1.2.429

package/dist/kernel/moleculer/mesh-mtls/mesh-renewal.d.ts

@@ -0,0 +1,126 @@
+/**
+* Mesh leaf renewal and revocation, driven by the hub (D856).
+*
+* The rule that shapes the order: a node must never be left without a leaf that
+* works. So renewal is a handover, not a replacement:
+*
+*   1. the node makes a NEW key pair and a CSR (the key never leaves it);
+*   2. the hub signs it (CN = the node id) and RECORDS the new leaf;
+*   3. the node persists it beside the old one and reconnects with it;
+*   4. the hub waits until it SEES that node connected presenting the NEW leaf;
+*   5. only then does the hub tell the node to keep it, and put the OLD serial on
+*      the CRL.
+*
+* Failure at any step before 5 leaves the old leaf valid and not revoked, asks the
+* node to go back to it (the node also goes back by itself when no confirmation
+* arrives in time), and returns the reason. The new serial is never revoked on
+* failure: the node may still hold it, and cutting it off would be the very
+* outage this order exists to prevent.
+*
+* Every step is logged with the node id.
+*/
+import type { MeshCaSigner } from "./mesh-ca.js";
+import { type MeshCertificateRegistry } from "./mesh-certificate-registry.js";
+import type { MeshCrl } from "./mesh-crl.js";
+import type { MeshPeerLeaf } from "./mesh-peer-transport.js";
+/** The node side, as the hub calls it (the `node-certificates` capability, pinned to the node). */
+export interface NodeMeshClient {
+	prepareMeshRenewal(): Promise<{
+		readonly csrPem: string;
+	}>;
+	installMeshLeaf(input: {
+		readonly certPem: string;
+		readonly caCertPem: string;
+		readonly confirmWithinMs: number;
+	}): Promise<{
+		readonly fingerprintSha256: string;
+		readonly serial: string;
+	}>;
+	confirmMeshLeaf(input: {
+		readonly fingerprintSha256: string;
+	}): Promise<{
+		readonly confirmed: boolean;
+	}>;
+	rollbackMeshLeaf(): Promise<{
+		readonly rolledBack: boolean;
+	}>;
+}
+export interface MeshPeers {
+	/** The leaf `nodeId` presented at its last handshake, while connected. */
+	peerLeaf(nodeId: string): MeshPeerLeaf | undefined;
+	/** Close the node's mutual-TLS sockets. */
+	dropPeer(nodeId: string): number;
+}
+/** "Node X finished registering" - the hub's registration completion (D3), not a poll. */
+export interface MeshRegistrations {
+	subscribe(listener: (nodeId: string) => void): () => void;
+}
+export interface MeshLog {
+	info(message: string, extras?: {
+		tags?: Record<string, string>;
+		meta?: Record<string, unknown>;
+	}): void;
+	warn(message: string, extras?: {
+		tags?: Record<string, string>;
+		meta?: Record<string, unknown>;
+	}): void;
+	error(message: string, extras?: {
+		tags?: Record<string, string>;
+		meta?: Record<string, unknown>;
+	}): void;
+}
+export interface RenewMeshDeps {
+	readonly nodeId: string;
+	readonly client: NodeMeshClient;
+	readonly ca: MeshCaSigner;
+	readonly registry: MeshCertificateRegistry;
+	readonly crl: MeshCrl;
+	readonly peers: MeshPeers;
+	/** Registration completions: the node is usable once its manifest has landed. */
+	readonly registrations: MeshRegistrations;
+	readonly log: MeshLog;
+	/** How long to wait for the node to be back AND registered with the new leaf. */
+	readonly reconnectTimeoutMs?: number;
+	/** Gap between attempts to confirm while the node's capability is not there yet. */
+	readonly confirmRetryMs?: number;
+	readonly sleep?: (ms: number) => Promise<void>;
+	/** Single deadline timer (not a scan); a seam for specs. */
+	readonly setTimer?: (fn: () => void, ms: number) => {
+		cancel(): void;
+	};
+	readonly now?: () => number;
+}
+export type RenewMeshResult = {
+	readonly ok: true;
+	readonly oldSerial: string | null;
+	readonly newSerial: string;
+	readonly newNotAfter: number;
+} | {
+	readonly ok: false;
+	readonly stage: "prepare" | "issue" | "install" | "reconnect" | "confirm";
+	readonly reason: string;
+	/** The node is back on its previous leaf (or never left it). */
+	readonly keptPreviousLeaf: boolean;
+};
+export declare function renewMeshCertificate(deps: RenewMeshDeps): Promise<RenewMeshResult>;
+export interface RevokeMeshResult {
+	readonly nodeId: string;
+	/** Serials now on the revocation list for this node. */
+	readonly revokedSerials: readonly string[];
+	/** Live sockets that were closed. */
+	readonly disconnected: number;
+	/** What the operator does next - revoking never forgets the node. */
+	readonly next: string;
+}
+/**
+* Revoke every live mesh leaf of `nodeId` and cut its connection. The node cannot
+* reconnect: it must re-join with a new join token. The node is NOT forgotten
+* (that stays `clusterNodes.forgetNode`).
+*/
+export declare function revokeMeshCertificate(deps: {
+	readonly nodeId: string;
+	readonly registry: MeshCertificateRegistry;
+	readonly crl: MeshCrl;
+	readonly peers: MeshPeers;
+	readonly log: MeshLog;
+}): Promise<RevokeMeshResult>;

package/dist/kernel/moleculer/mesh-mtls/mesh-tls-gate.d.ts

@@ -0,0 +1,40 @@
+/**
+* The mesh TLS listener must not accept agents before the revocation registry has
+* loaded (D856): until `mesh_node_certificates` is read, the CRL is empty, so a
+* revoked leaf would be accepted - a fail-open on the one list whose job is to refuse.
+*
+* `openMeshTlsWhenRevocationsLoaded` therefore keeps the listener CLOSED while the
+* registry cannot be loaded, and retries; it opens the listener exactly once, after
+* the registry's revocations were replayed into the CRL. The hub itself talks to no
+* one over this listener, so closed means "agents wait", not "the hub is down".
+*/
+/** What the admin UI shows about the hub's mesh listener (Identity -> Certificates). */
+export type MeshTlsListenerState = {
+	readonly state: "open";
+} | {
+	readonly state: "closed";
+	readonly reason: string;
+	readonly since: number;
+};
+export declare function setProcessMeshTlsListenerState(state: MeshTlsListenerState | null): void;
+/** `null` before the gate has run at all (no mesh CA yet). */
+export declare function getProcessMeshTlsListenerState(): MeshTlsListenerState | null;
+export interface MeshTlsGateDeps<R> {
+	/** Load the registry and replay its revocations into the CRL. `null` when it cannot yet. */
+	readonly loadRegistry: () => Promise<R | null>;
+	/** Open the listener. Called until it succeeds (a failed open is retried), then never again. */
+	readonly open: (registry: R) => Promise<void>;
+	/** Run `fn` again after `ms` (an unref'd timer in production). */
+	readonly retry: (fn: () => void, ms: number) => void;
+	readonly retryMs?: number;
+	readonly onWaiting?: (attempt: number) => void;
+	readonly onError?: (error: unknown) => void;
+	/** Every change of the listener's state, for the status the admin UI reads. */
+	readonly onState?: (state: MeshTlsListenerState) => void;
+	readonly now?: () => number;
+}
+/**
+* Nothing in `run` can reject: a load or an open that throws is reported and retried, so a
+* failure can never become an unhandled rejection that leaves the listener closed in silence.
+*/
+export declare function openMeshTlsWhenRevocationsLoaded<R>(deps: MeshTlsGateDeps<R>): Promise<boolean>;

package/dist/kernel/moleculer/mesh-mtls/tls-tcp-transporter.d.ts

@@ -113,6 +113,14 @@ export interface FilteredGossip {
 * remove the payload is returned unchanged.
 */
 export declare function keepOnlyGossipNodes(payload: unknown, keep: ReadonlySet<string>): FilteredGossip;
+/** What a peer's leaf looks like, recorded at handshake. */
+interface PeerLeaf {
+	readonly serial: string;
+	readonly fingerprint: string;
+	readonly notBefore: number;
+	readonly notAfter: number;
+	readonly remoteAddress?: string;
+}
 export declare class TlsTcpTransporter extends TcpTransporterBase {
 	private tlsServer;
 	private meshTls;
@@ -120,6 +128,8 @@ export declare class TlsTcpTransporter extends TcpTransporterBase {
 	private readonly tlsSockets;
 	/** Node id (certificate CN) → serial of every peer that completed a mutual-TLS handshake. */
 	private readonly tlsPeers;
+	/** Node id → the leaf it presented at its last handshake (hub inventory, D856). */
+	private readonly peerLeaves;
 	private clearDisabled;
 	private readonly hubTlsOnly;
 	private readonly hubOnlyPeers;
@@ -172,6 +182,11 @@ export declare class TlsTcpTransporter extends TcpTransporterBase {
 	* restarted node is back), in which case its live TLS socket keeps it `tls`.
 	*/
 	forgetPeer(nodeId: string): void;
+	private rememberPeerLeaf;
+	/** The leaf `nodeId` presented at its last mutual-TLS handshake. */
+	peerLeaf(nodeId: string): PeerLeaf | undefined;
+	/** Close every live mutual-TLS socket of `nodeId` (revocation, renewal). Returns how many. */
+	dropPeer(nodeId: string): number;
 	/** True once the mutual-TLS listener is bound. */
 	isTlsListening(): boolean;
 	isClearTransportEnabled(): boolean;

package/dist/{restore-archive-DH1Pxq_1.mjs → restore-archive-AIwMHO5_.mjs}

@@ -1,4 +1,4 @@
-import { g as DATABASE_SNAPSHOT_SUFFIX } from "./dist-DHSJV4Qc.mjs";
+import { g as DATABASE_SNAPSHOT_SUFFIX } from "./dist-CSSfTM18.mjs";
 import { createCipheriv, createDecipheriv, createHash, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from "node:crypto";
 import { Buffer as Buffer$1 } from "buffer";
 import * as fsp from "node:fs/promises";

package/dist/{restore-archive-Dccm8lkA.js → restore-archive-BYUEMsog.js}

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-BQG3QFg7.js");
+const require_dist = require("./dist-Bgy_AmwX.js");
 let node_crypto = require("node:crypto");
 let buffer = require("buffer");
 let node_fs_promises = require("node:fs/promises");

package/dist/{retired-settings-keys-BfGaSeQI.js → retired-settings-keys-BTPkRLTS.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-BQG3QFg7.js");
+const require_dist = require("./dist-Bgy_AmwX.js");
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/{retired-settings-keys-CPz7zpza.mjs → retired-settings-keys-H0rYXT27.mjs}

@@ -1,4 +1,4 @@
-import { yr as asJsonObject } from "./dist-DHSJV4Qc.mjs";
+import { Dr as asJsonObject } from "./dist-CSSfTM18.mjs";
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/tls/agent-https-names.d.ts

@@ -0,0 +1,27 @@
+/**
+* Which names the hub has certified to which agent (D856): the memory behind "a name
+* already certified to another node is never signed again". Hub only.
+*/
+import type { CollectionColumn, SettingsStoreClient } from "@camstack/types";
+/**
+* @durable class=config owner=system-config
+*   write="the hub records the names it signed into an agent's HTTPS leaf, replacing that
+*     node's previous row"
+*   retention="one row per node, replaced on every issue; a forgotten node's row stays until
+*     the node is issued again or an operator clears it (it only blocks reuse of its names)"
+*/
+export declare const AGENT_HTTPS_NAMES_COLLECTION = "agent_https_names";
+export declare const AGENT_HTTPS_NAMES_COLUMNS: readonly CollectionColumn[];
+export declare class AgentHttpsNames {
+	private readonly store;
+	private readonly byNode;
+	constructor(store: SettingsStoreClient);
+	load(): Promise<void>;
+	/** Every name certified to a node other than `nodeId`. */
+	takenByOthers(nodeId: string): ReadonlySet<string>;
+	/** Free every name certified to a node that was forgotten. */
+	release(nodeId: string): Promise<boolean>;
+	record(nodeId: string, names: readonly string[]): Promise<void>;
+}
+export declare function setProcessAgentHttpsNames(names: AgentHttpsNames | null): void;
+export declare function getProcessAgentHttpsNames(): AgentHttpsNames | null;

package/dist/tls/agent-https.d.ts

@@ -0,0 +1,111 @@
+import type { HttpsLeafInfo } from "@camstack/types";
+import { type CertIdentity, type HostFacts } from "./cert-identity.js";
+export interface AgentHttpsPaths {
+	readonly dir: string;
+	/** The one atomic file: key + leaf + pinned CA. */
+	readonly bundlePath: string;
+	/** Informational copy of the leaf (public), written after the bundle. */
+	readonly certPath: string;
+	readonly pendingKeyPath: string;
+}
+export declare function agentHttpsPaths(dataDir: string): AgentHttpsPaths;
+export interface AgentHttpsMaterial {
+	readonly keyPem: string;
+	readonly certPem: string;
+	readonly caCertPem: string;
+}
+/**
+* The material on disk, or `null` while no hub-issued leaf is installed. A bundle that
+* cannot be parsed is reported through `onCorrupt` and treated as absent: a bad file must
+* never take the agent API down.
+*/
+export declare function loadAgentHttps(dataDir: string, onCorrupt?: (reason: string) => void): AgentHttpsMaterial | null;
+/** What an agent reports about itself for its certificate. */
+export interface AgentNames {
+	readonly hostnames: readonly string[];
+	readonly addresses: readonly string[];
+}
+export declare function collectAgentNames(nodeId: string, hostFacts: HostFacts): AgentNames;
+export interface AgentHttpsRequest extends AgentNames {
+	readonly csrPem: string;
+}
+/** SHA-256 of the hub local CA this agent pinned, or `null` while none is. */
+export declare function pinnedHttpsCaFingerprint(dataDir: string): string | null;
+/**
+* A fresh key pair (EC P-256, kept in `agent.key.pending`, 0600) and its CSR. The
+* key becomes `agent.key` only when the matching certificate is installed, so a
+* request that is never answered changes nothing that is being served.
+*/
+export declare function createAgentHttpsRequest(dataDir: string, nodeId: string, names: AgentNames): Promise<AgentHttpsRequest>;
+export declare class AgentHttpsInstallError extends Error {
+	constructor(message: string);
+}
+/**
+* Install the hub-signed leaf for the pending key. Refused when it is not for that key, when
+* it is not signed by the CA it came with, or - once a CA is pinned - when that CA is not the
+* one this agent already pinned (the CA that arrives with a later leaf is never trusted on its
+* own say: the first one came over the authenticated mesh, every later leaf must chain to it).
+* Key, leaf and CA are written as ONE file, atomically.
+*/
+export declare function installAgentHttps(dataDir: string, input: {
+	readonly certPem: string;
+	readonly caCertPem: string;
+	/**
+	* The hub says its local CA was rotated and this leaf chains to the new one. Honoured only
+	* because the install call itself arrived over the authenticated mesh from the hub; without
+	* it a different CA is refused.
+	*/
+	readonly caRotation?: boolean;
+}): AgentHttpsMaterial;
+/** Fingerprint, issuer, SANs and validity of a served leaf. */
+export declare function describeHttpsLeaf(certPem: string): HttpsLeafInfo;
+/** Private-network IPv4/IPv6: RFC 1918, CGNAT (Tailscale), link-local, ULA. */
+export declare function isPrivateAddress(address: string): boolean;
+/** The default docker bridge network (172.17.0.0/16): identical on every host, so it names nothing. */
+export declare function isContainerBridgeAddress(address: string): boolean;
+/** A name that cannot collide with public DNS. */
+export declare function isLocalOnlyHostname(name: string): boolean;
+export interface AcceptedSans {
+	readonly identity: CertIdentity;
+	readonly accepted: readonly string[];
+	readonly rejected: readonly string[];
+}
+/**
+* The names the hub will sign for `nodeId`: its node id and the address of its live mesh
+* socket - nothing the agent says about itself. `excluded` holds every name already taken
+* (the hub's own certificate, other nodes' leaves); `reported` is what the agent claimed,
+* listed only so it can be logged as dropped.
+*/
+export declare function acceptAgentSans(input: {
+	readonly nodeId: string;
+	/** The remote address of the agent's live mesh socket, as the HUB sees it. */
+	readonly observedAddress?: string | undefined;
+	readonly excluded?: ReadonlySet<string>;
+	readonly reported?: readonly string[];
+}): AcceptedSans;
+/** The SAN values (lower-cased) of a certificate PEM: DNS names and IP addresses. */
+export declare function certificateNames(certPem: string): ReadonlySet<string>;
+export interface IssuedAgentHttps {
+	readonly certPem: string;
+	readonly caCertPem: string;
+	readonly accepted: readonly string[];
+	readonly rejected: readonly string[];
+}
+/**
+* Hub side: sign an agent's CSR under the local CA in `<hubDataDir>/tls`. Throws when
+* there is no local CA to sign with or no name survives the policy.
+*/
+export declare function issueAgentHttpsLeaf(input: {
+	readonly hubDataDir: string;
+	readonly nodeId: string;
+	readonly csrPem: string;
+	/** What the agent reported. Never certified; only logged as dropped. */
+	readonly reportedNames?: readonly string[];
+	/** The remote address of the agent's live mesh socket, from the hub's own view. */
+	readonly observedAddress?: string | undefined;
+	/** Names already certified to OTHER nodes. */
+	readonly takenByOthers?: ReadonlySet<string>;
+	readonly now?: Date;
+}): Promise<IssuedAgentHttps>;
+/** SHA-256 of a PEM (for logs that must not print a certificate). */
+export declare function pemDigest(pem: string): string;

package/dist/tls/cert-issue.d.ts

@@ -49,3 +49,10 @@ export declare function loadCa(certPem: string, keyPem: string): Promise<CaSigne
 * Apple's `testAppTrustRoot_AnyEKU_AfterJul2019` asserts must fail.
 */
 export declare function issueLeaf(ca: CaSigner, identity: CertIdentity, commonName: string, validDays: number, now: Date): Promise<CertMaterial>;
+/**
+* A server leaf for a key pair the CALLER holds (D856): an agent sends a CSR, the
+* hub signs its public key under the local root. Same extensions as
+* {@link issueLeaf} - `CA:FALSE`, serverAuth only - so a device that trusts the
+* hub root trusts the agent. The private key never exists on the hub.
+*/
+export declare function issueLeafFromCsr(ca: CaSigner, csrPem: string, identity: CertIdentity, commonName: string, validDays: number, now: Date): Promise<string>;

package/dist/tls/index.d.ts

@@ -6,3 +6,6 @@ export { applyCertificateToListener, regenerateCertificate, revertToGeneratedCer
 export { CA_COMMON_NAME } from "./cert-issue.js";
 export { validateUploadedTls, type UploadedTlsValidation } from "./uploaded-cert.js";
 export { type TlsAccessStatus, readTlsAccessStatus, splitPemCertificates, UPLOADED_CA_FILE, writeTlsMode, readTlsMode, readExtraSans, writeExtraSans } from "./tls-status.js";
+export { acceptAgentSans, type AcceptedSans, AgentHttpsInstallError, type AgentHttpsMaterial, type AgentHttpsPaths, type AgentHttpsRequest, type AgentNames, agentHttpsPaths, certificateNames, collectAgentNames, createAgentHttpsRequest, describeHttpsLeaf, installAgentHttps, isContainerBridgeAddress, isLocalOnlyHostname, isPrivateAddress, issueAgentHttpsLeaf, type IssuedAgentHttps, loadAgentHttps, pemDigest, pinnedHttpsCaFingerprint } from "./agent-https.js";
+export { AGENT_HTTPS_NAMES_COLLECTION, AGENT_HTTPS_NAMES_COLUMNS, AgentHttpsNames, getProcessAgentHttpsNames, setProcessAgentHttpsNames } from "./agent-https-names.js";
+export { systemHostFacts } from "./cert-identity.js";