@camstack/system 1.2.419 → 1.2.420

package/dist/kernel/index.d.ts

@@ -39,7 +39,7 @@ export { buildStorageLocationRegistry } from "./storage-location-registry.js";
 export type { StorageLocationRegistry } from "./storage-location-registry.js";
 export { createBroker, deriveAgentListenPort, getBrokerTlsTransporter } from "./moleculer/broker-factory.js";
 export type { BrokerConfig } from "./moleculer/broker-factory.js";
-export { caFingerprint, caFingerprintCompact, createMeshCsrPem, enrollMeshNode, exportMeshPrivateKeyPem, getProcessNodeMeshTransport, setProcessMeshPeerTransportLookup, generateMeshCa, generateMeshKeyPair, getProcessMeshCaState, issueMeshLeafForNode, issueMeshLeafFromCsr, JoinTokenJtiStore, loadMeshCa, MESH_CA_FIELD, MESH_CA_KEY_REF, MESH_CA_SETTINGS_KEY, MeshCaKeeper, MeshCrl, mintMeshJoinToken, processMeshCrl, processJoinTokenJtiStore, requireProcessMeshCa, setProcessMeshTlsEnabler, TlsTcpTransporter, verifyMeshJoinToken, DEFAULT_HUB_TLS_TCP_PORT } from "./moleculer/mesh-mtls/index.js";
+export { caFingerprint, caFingerprintCompact, createMeshCsrPem, enrollMeshNode, exportMeshPrivateKeyPem, getProcessNodeMeshTransport, setProcessMeshPeerTransportLookup, generateMeshCa, generateMeshKeyPair, getProcessMeshCaState, issueMeshLeafForNode, issueMeshLeafFromCsr, JoinTokenJtiStore, loadMeshCa, MESH_CA_FIELD, MESH_CA_KEY_REF, MESH_CA_SETTINGS_KEY, MeshCaKeeper, MeshCrl, mintMeshJoinToken, processMeshCrl, processJoinTokenJtiStore, requireProcessMeshCa, setProcessMeshTlsEnabler, TlsTcpTransporter, verifyMeshJoinToken, DEFAULT_HUB_TLS_TCP_PORT, MESH_TLS_PORT_HELLO_FIELD } from "./moleculer/mesh-mtls/index.js";
 export type { MeshCaSigner, MeshEnrollResult, MeshPeerTransportLookup, MeshTransport, MeshJoinTokenClaims, MeshTlsMaterial } from "./moleculer/mesh-mtls/index.js";
 export { type AddonDeploySource, isAddonDeploySource } from "./moleculer/addon-deploy-source.js";
 export { createAddonService, validateProviderRegistrations } from "./moleculer/addon-service-factory.js";
@@ -62,6 +62,10 @@ export { createMeshAccessMiddleware, stripForgedIdentity } from "./moleculer/mes
 export type { MeshAccessMiddlewareOptions, MeshCallGate } from "./moleculer/mesh-access-middleware.js";
 export { AgentMeshAuthenticator, AGENT_REGISTER_NODE_ACTION, isOwnChildNodeId, isRemoteForbiddenOnAgent } from "./moleculer/agent-mesh-authenticator.js";
 export type { AgentMeshAuthenticatorDeps } from "./moleculer/agent-mesh-authenticator.js";
+export { DEFAULT_MESH_JOIN_MAX_HELD, DEFAULT_MESH_JOIN_MAX_HOLD_MS, MeshJoinHold } from "./moleculer/mesh-join-hold.js";
+export type { MeshGateVerdict, MeshHeldKind, MeshHeldVerdict, MeshJoinHoldOptions, MeshJoinHoldReport } from "./moleculer/mesh-join-hold.js";
+export { createAgentEventScope, isPeerEventPacket } from "./moleculer/agent-event-scope.js";
+export type { AgentEventScope, AgentEventScopeOptions, AgentEventScopeStats, OutboundPacket, TransitPublish } from "./moleculer/agent-event-scope.js";
 export { MeshJoinClient } from "./moleculer/mesh-join-client.js";
 export type { MeshJoinCall, MeshJoinClientOptions, MeshJoinState } from "./moleculer/mesh-join-client.js";
 export { computeHubJoinProof, computeNodeJoinProof, meshErrorType, MESH_ACTION_FORBIDDEN_TYPE, MESH_JOIN_AUTHENTICATE_ACTION, MESH_JOIN_CHALLENGE_ACTION, MESH_JOIN_CHALLENGE_INVALID_TYPE, MESH_JOIN_PROTOCOL, MESH_NODE_UNAUTHENTICATED_TYPE } from "./moleculer/mesh-join-proof.js";

package/dist/kernel/moleculer/agent-event-scope.d.ts

@@ -0,0 +1,49 @@
+/**
+* An agent's events go to the hub, and to no other node (D848).
+*
+* `getBrokerEventBus(...).emit` broadcasts `camstack.evt.<cat>` to every node
+* whose `$event-bus` subscribes to it — and every node's does
+* (`camstack.evt.**`). On an agent that meant every telemetry event
+* (`pipeline.inference-result`, `pipeline.trace`, `motion.*`: ~3,000/min per
+* agent on the 2026-10-13 cluster) was also written to every PEER agent, in
+* clear text, where the peer's inbound gate (`AgentMeshAuthenticator`, D802)
+* refused it by design: only the hub may send an agent anything. The bytes
+* were paid for nothing.
+*
+* This middleware stops them at the source: an EVENT packet an agent
+* publishes to any node other than the hub is not written. Nothing a peer
+* agent receives changes — it refused every such packet already — and the
+* hub, the only consumer, still gets every event. A packet to the agent's own
+* node id never reaches the transport (Moleculer delivers it in-process).
+*
+* Counted, never silent: {@link AgentEventScope.stats} reports what was held
+* back per peer, and the first event withheld from each peer is logged.
+*/
+import type { Middleware } from "moleculer";
+/** The part of a Moleculer `Packet` this gate reads. */
+export interface OutboundPacket {
+	readonly type: string;
+	readonly target: string | null;
+}
+/** `Transit.publish` — what a `transitPublish` hook wraps. */
+export type TransitPublish = (packet: OutboundPacket) => Promise<unknown>;
+export interface AgentEventScopeOptions {
+	/** The only node an agent's events are written to. */
+	readonly hubNodeId: string;
+	/** Told once per peer, the first time an event to it is withheld. */
+	readonly log?: (message: string) => void;
+}
+export interface AgentEventScopeStats {
+	/** EVENT packets written to the hub. */
+	readonly toHub: number;
+	/** EVENT packets withheld, per peer node id. */
+	readonly withheld: Readonly<Record<string, number>>;
+}
+export interface AgentEventScope {
+	/** Pass to `createBroker({ middlewares })` on every agent broker. */
+	readonly middleware: Middleware;
+	stats(): AgentEventScopeStats;
+}
+/** Is this an event packet addressed to a node other than the hub? */
+export declare function isPeerEventPacket(packet: OutboundPacket, hubNodeId: string): boolean;
+export declare function createAgentEventScope(opts: AgentEventScopeOptions): AgentEventScope;

package/dist/kernel/moleculer/agent-mesh-authenticator.d.ts

@@ -17,6 +17,10 @@
 *     cluster secret, `transition` when it does not — so an upgrading agent
 *     without a secret still serves the hub.
 *
+* The hub's requests that arrive while a join is in flight are HELD, not
+* refused (D848 §3, {@link MeshJoinHold}): delivered when the join proves the
+* hub, refused and reported when it fails or the bound runs out.
+*
 * Unlike the hub gate, `$process.*` is allowed from an authenticated hub:
 * the hub polls `$process.list` on agents. `$node.*` stays forbidden from
 * every remote peer. Forged `caller` / `callerAddonId` are stripped by the
@@ -26,8 +30,8 @@
 * (`docs/design/2026-10-09-mesh-mtls-plan.md`) — same residual as the hub.
 */
 import type { MeshAuthMode, MeshNodeAuthState } from "./mesh-auth-mode.js";
-import type { MeshCallVerdict } from "./mesh-authenticator.js";
 import type { MeshJoinState } from "./mesh-join-client.js";
+import { type MeshGateVerdict, type MeshJoinHoldReport } from "./mesh-join-hold.js";
 /** The child's register action on its parent agent. */
 export declare const AGENT_REGISTER_NODE_ACTION = "$agent.registerNode";
 export declare function isRemoteForbiddenOnAgent(action: string): boolean;
@@ -40,13 +44,21 @@ export interface AgentMeshAuthenticatorDeps {
 	readonly now?: () => number;
 	/** First time a peer is tolerated without proof on this connection. */
 	readonly onTolerated?: (nodeId: string, action: string) => void;
+	/** Every decision about the hub's requests held before the join settled. */
+	readonly onHoldReport?: (report: MeshJoinHoldReport) => void;
+	/** Bounds of that hold (defaults: 1000 items, 15 s). */
+	readonly maxHeld?: number;
+	readonly maxHoldMs?: number;
 }
 export declare class AgentMeshAuthenticator {
 	private readonly deps;
 	private readonly nodes;
 	private readonly hubNodeId;
 	private readonly now;
+	private readonly hold;
 	constructor(deps: AgentMeshAuthenticatorDeps);
+	/** How many of the hub's requests wait for the join right now. */
+	heldCount(): number;
 	/** Current mode: secret configured → enforce; else tolerate (upgrade path). */
 	mode(): MeshAuthMode;
 	/**
@@ -59,8 +71,8 @@ export declare class AgentMeshAuthenticator {
 	noteChildRegistered(sender: string, proof?: "authenticated" | "legacy"): void;
 	/** The peer's connection dropped. */
 	forget(nodeId: string): void;
-	admitCall(sender: string, action: string): MeshCallVerdict;
-	admitEvent(sender: string, eventName: string): MeshCallVerdict;
+	admitCall(sender: string, action: string): MeshGateVerdict;
+	admitEvent(sender: string, eventName: string): MeshGateVerdict;
 	stateOf(nodeId: string): MeshNodeAuthState;
 	authenticatedNodeIds(): readonly string[];
 	private admitSender;

package/dist/kernel/moleculer/broker-factory.d.ts

@@ -25,6 +25,12 @@ interface BrokerConfig {
 	*/
 	readonly agentListenPort?: number;
 	/**
+	* Port an ENROLLED agent listens on for the hub's mutual-TLS dial (default
+	* 6443). It is advertised to the hub in every gossip HELLO, so two
+	* nodes on one host (a dev or test cluster) need not collide on 6443.
+	*/
+	readonly agentTlsListenPort?: number;
+	/**
 	* Broker middlewares (D802): the hub passes its mesh gate
 	* (`createMeshAccessMiddleware`); an agent passes inbound access
 	* (`AgentMeshAuthenticator` + the same middleware) and its outbound join

package/dist/kernel/moleculer/mesh-access-middleware.d.ts

@@ -14,11 +14,15 @@
 * Calls a node makes to itself (`ctx.nodeID` = own) pass untouched.
 */
 import { type Middleware } from "moleculer";
-import type { MeshCallVerdict } from "./mesh-authenticator.js";
-/** Minimal surface the middleware needs — hub and agent authenticators both fit. */
+import type { MeshGateVerdict } from "./mesh-join-hold.js";
+/**
+* Minimal surface the middleware needs — hub and agent authenticators both fit.
+* Only the agent's ever answers `hold` (its hub's requests before the join
+* settles, D848): the request waits for that verdict, then runs or is refused.
+*/
 export interface MeshCallGate {
-	admitCall(sender: string, action: string): MeshCallVerdict;
-	admitEvent(sender: string, eventName: string): MeshCallVerdict;
+	admitCall(sender: string, action: string): MeshGateVerdict;
+	admitEvent(sender: string, eventName: string): MeshGateVerdict;
 }
 /**
 * The params of a request from another node, with every identity it claimed

package/dist/kernel/moleculer/mesh-join-hold.d.ts

@@ -0,0 +1,85 @@
+/**
+* What an agent does with the hub's events and calls that arrive BEFORE its
+* mesh join has settled (D848 §3).
+*
+* The agent's inbound gate admits the hub only once the mutual join has
+* proven it (`AgentMeshAuthenticator`, D802). The hub, though, starts sending
+* the moment it sees the agent's connection — a one-shot event broadcast at
+* that instant reached a gate that had not yet heard the join's answer, and
+* was refused: dropped, with only a rate-limited "mesh event refused" line.
+* An ordering fix on the hub cannot close it: the agent verifies the hub's
+* proof asynchronously, after the answer that carries it, so even an event
+* the hub sends strictly after its answer can be decoded first.
+*
+* So the agent HOLDS what the hub sends while a join is in flight, and
+* decides when the join decides:
+*  - the join proves the hub → everything held is delivered, in arrival order;
+*  - the join fails (mismatch, unverified hub, no answer) → everything held is
+*    refused, and said so with the count;
+*  - the bound runs out first ({@link MeshJoinHoldOptions.maxHoldMs} since the
+*    first item was held) → refused and said so, and nothing more is held until
+*    the next join starts;
+*  - more than {@link MeshJoinHoldOptions.maxHeld} items → the excess is refused
+*    on arrival and counted into the next report.
+*
+* The timer is the bound itself, never a wait for a node (D3): delivery is
+* driven by the join settling. Nothing held is ever dropped without a report
+* (D49).
+*/
+import type { MeshCallVerdict } from "./mesh-authenticator.js";
+/** The gate cannot answer yet: the request waits for the join. */
+export interface MeshHeldVerdict {
+	readonly verdict: "hold";
+	readonly settled: Promise<MeshCallVerdict>;
+}
+/** Every verdict a mesh gate may give (`MeshCallGate`). */
+export type MeshGateVerdict = MeshCallVerdict | MeshHeldVerdict;
+export type MeshHeldKind = "call" | "event";
+export interface MeshJoinHoldReport {
+	/** `delivered` when the join proved the hub, else `refused`. */
+	readonly outcome: "delivered" | "refused";
+	/** `authenticated`, the failed join state, or `bound` (time ran out). */
+	readonly reason: string;
+	readonly events: number;
+	readonly calls: number;
+	/** Refused on arrival because the hold was full. */
+	readonly overflow: number;
+	/** From the first held item to the decision. */
+	readonly heldForMs: number;
+}
+export interface MeshJoinHoldOptions {
+	readonly hubNodeId: string;
+	/** Most items held at once (default 1000). */
+	readonly maxHeld?: number;
+	/** Longest an item is held, from the first one (default 15 s). */
+	readonly maxHoldMs?: number;
+	readonly now?: () => number;
+	readonly onReport?: (report: MeshJoinHoldReport) => void;
+}
+export declare const DEFAULT_MESH_JOIN_MAX_HELD = 1e3;
+export declare const DEFAULT_MESH_JOIN_MAX_HOLD_MS = 15e3;
+export declare class MeshJoinHold {
+	private readonly opts;
+	private waiters;
+	private firstHeldAt;
+	private overflow;
+	private timer;
+	/** Holding is open while a join is in flight; closed after a decision or the bound. */
+	private open;
+	private readonly now;
+	constructor(opts: MeshJoinHoldOptions);
+	/** Whether a request arriving now would be held (a join is in flight). */
+	get holding(): boolean;
+	/** How many requests wait right now. */
+	get size(): number;
+	/** A join started: hold again. */
+	reopen(): void;
+	/** Hold one request; `null` when holding is closed (the caller refuses it). */
+	hold(kind: MeshHeldKind): MeshHeldVerdict | null;
+	/** The join proved the hub: deliver everything held, in order. */
+	release(): void;
+	/** The join failed, or the bound ran out: refuse everything held. */
+	refuse(reason: string): void;
+	private refusal;
+	private settle;
+}

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

@@ -7,4 +7,4 @@ export { enrollMeshNode } from "./mesh-enroll.js";
 export type { EnrollMeshNodeDeps, MeshEnrollRequest, MeshEnrollResult } from "./mesh-enroll.js";
 export { JoinTokenJtiStore, mintMeshJoinToken, processJoinTokenJtiStore, verifyMeshJoinToken, type MeshJoinTokenClaims, type MintJoinTokenInput } from "./mesh-join-token.js";
 export { getProcessMeshTlsEnabler, requestProcessMeshTlsEnable, setProcessMeshTlsEnabler, type MeshTlsEnabler } from "./mesh-tls-enabler.js";
-export { TlsTcpTransporter, type MeshTlsMaterial, type TlsTcpTransporterOptions } from "./tls-tcp-transporter.js";
+export { helloMeshTlsPort, keepOnlyGossipNodes, MESH_TLS_PORT_HELLO_FIELD, TlsTcpTransporter, type FilteredGossip, type MeshTlsMaterial, type TlsTcpTransporterOptions } from "./tls-tcp-transporter.js";

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

@@ -1,5 +1,7 @@
 import type { Server as NetServer, Socket as NetSocket } from "node:net";
 import { type MeshCrl } from "./mesh-crl.js";
+/** Field of the gossip HELLO payload carrying the sender's mesh-TLS listen port. */
+export declare const MESH_TLS_PORT_HELLO_FIELD = "meshTlsPort";
 type TcpTransporterConstructor = new (opts?: Record<string, unknown>) => TlsTcpTransporterBase;
 declare const TcpTransporterBase: TcpTransporterConstructor;
 interface TlsTcpTransporterBase {
@@ -34,6 +36,13 @@ interface TlsTcpTransporterBase {
 	registry: {
 		regenerateLocalRawInfo(force: boolean): void;
 	};
+	broker: {
+		serializer: {
+			serialize(payload: unknown, type: string): Buffer;
+			deserialize(buf: Buffer, type: string): unknown;
+		};
+	};
+	nodeID: string;
 	startTcpServer(): Promise<number>;
 	startUdpServer(): Promise<void>;
 	startTimers(): void;
@@ -43,6 +52,7 @@ interface TlsTcpTransporterBase {
 	disconnect(): Promise<void>;
 	onIncomingMessage(type: string, message: Buffer, socket?: NetSocket): unknown;
 	receive(cmd: string, data: Buffer, socket?: NetSocket): unknown;
+	publish(packet: OutgoingPacket): Promise<unknown>;
 	deserialize(type: string, data: Buffer): {
 		payload: {
 			sender?: string;
@@ -71,7 +81,38 @@ export interface TlsTcpTransporterOptions {
 	readonly crl?: MeshCrl;
 	/** Hub only (D826): never bind clear TCP or UDP discovery. */
 	readonly hubTlsOnly?: boolean;
+	/**
+	* Enrolled agent only (D848): the hub is the only mesh peer — no clear
+	* reader, TLS accepted from the hub's certificate only, nothing dialled but
+	* the hub, other nodes in the hub's gossip ignored.
+	*/
+	readonly hubOnlyPeers?: boolean;
+	/** The hub's node id (default `hub`). */
+	readonly hubNodeId?: string;
+	/**
+	* Port to dial a TLS peer on when it advertises none (default: `tlsPort`).
+	* An agent sets the hub's TLS port here; its own listener stays on `tlsPort`.
+	*/
+	readonly peerTlsPort?: number;
+}
+/** A packet on its way out (Moleculer `Packet`). */
+interface OutgoingPacket {
+	readonly type: string;
+	readonly target: string | null;
+	readonly payload: Record<string, unknown>;
+}
+/** The mesh-TLS port a gossip HELLO payload advertises, or null. */
+export declare function helloMeshTlsPort(payload: unknown): number | null;
+/** A gossip payload with only the kept nodes, and the ids that were removed. */
+export interface FilteredGossip {
+	readonly payload: unknown;
+	readonly removed: readonly string[];
 }
+/**
+* A gossip response with every node but `keep` removed. With nothing to
+* remove the payload is returned unchanged.
+*/
+export declare function keepOnlyGossipNodes(payload: unknown, keep: ReadonlySet<string>): FilteredGossip;
 export declare class TlsTcpTransporter extends TcpTransporterBase {
 	private tlsServer;
 	private meshTls;
@@ -81,19 +122,29 @@ export declare class TlsTcpTransporter extends TcpTransporterBase {
 	private readonly tlsPeers;
 	private clearDisabled;
 	private readonly hubTlsOnly;
+	private readonly hubOnlyPeers;
+	private readonly hubNodeId;
+	private readonly peerTlsPortOption;
+	/** Peers already reported as not adopted (D848) — one line each. */
+	private readonly ignoredPeers;
+	/** Node id → the mesh-TLS port its last HELLO advertised. */
+	private readonly helloTlsPorts;
 	/** Clear-text `TcpWriter.connect` captured once before the TLS wrap (A→B). */
 	private clearWriterConnect;
 	private writerTlsPatched;
 	constructor(opts?: TlsTcpTransporterOptions);
+	/** Clear TCP is never served: the TLS-only hub, or an agent whose only peer is the hub. */
+	private get tlsOnly();
 	override startTcpServer(): Promise<number>;
 	override connect(): Promise<void>;
 	/**
-	* Outbound dial uses mTLS when the peer is already known on TLS (inbound
-	* handshake), or when dialling the hub node id (agent → hub). Everyone else
-	* (runners, unenrolled agents) stays on the clear writer — the hub must not
-	* TLS-wrap every `connect` after deferred `enableMeshTls`.
+	* Outbound dial uses mTLS when dialling the hub node id (agent → hub), on a
+	* TLS-only hub (it has no clear listener, so no clear peer exists to dial —
+	* D848 closes the hub → agent clear leg), or when the peer is already known
+	* on TLS (inbound handshake).
 	*/
 	private shouldDialPeerWithTls;
+	/** The peer's advertised mesh-TLS port, else the configured dial port, else 6443. */
 	private peerTlsDialPort;
 	/**
 	* Wrap `TcpWriter.connect` so TLS peers are dialed with mutual TLS on the
@@ -135,6 +186,16 @@ export declare class TlsTcpTransporter extends TcpTransporterBase {
 	/** Close sockets whose peer serial was just revoked. */
 	dropRevokedSockets(): void;
 	override disconnect(): Promise<void>;
+	/**
+	* D848: an enrolled agent adopts no node from the hub's gossip but the hub
+	* itself, so it never learns — and therefore never dials or broadcasts to —
+	* another agent. Everything else is Moleculer's own handling.
+	*/
+	override receive(cmd: string, data: Buffer, socket?: NetSocket): unknown;
+	/** Remember the TLS port a peer's HELLO advertises (absent: an older node → the default). */
+	private noteHelloTlsPort;
+	/** A TLS-listening node says where in every HELLO it sends. */
+	override publish(packet: OutgoingPacket): Promise<unknown>;
 	override onIncomingMessage(type: string, message: Buffer, socket?: NetSocket): unknown;
 	private startTlsServerIfReady;
 	private onTlsClientConnected;