@camstack/system 1.2.390 → 1.2.392

package/dist/kernel/moleculer/addon-service-factory.d.ts

@@ -1,50 +1,50 @@
-import { ServiceSchema } from 'moleculer';
-import { ICamstackAddon, AddonDeclaration } from '@camstack/types';
+import type { ServiceSchema } from "moleculer";
+import type { ICamstackAddon, AddonDeclaration } from "@camstack/types";
 /**
- * Validate that every capability declared in the addon manifest has a
- * provider registered via context.registerProvider() during initialize().
- *
- * Call after addon.initialize() to catch missing registrations at boot time
- * instead of at runtime when a consumer tries to use the capability.
- */
+* Validate that every capability declared in the addon manifest has a
+* provider registered via context.registerProvider() during initialize().
+*
+* Call after addon.initialize() to catch missing registrations at boot time
+* instead of at runtime when a consumer tries to use the capability.
+*/
 declare function validateProviderRegistrations(addonId: string, declaration: AddonDeclaration, providers: ReadonlyMap<string, unknown>, logger?: {
-    warn: (msg: string) => void;
-    debug?: (msg: string) => void;
-    info?: (msg: string) => void;
+	warn: (msg: string) => void;
+	debug?: (msg: string) => void;
+	info?: (msg: string) => void;
 }): readonly string[];
 /**
- * Optional resolver that returns method names for a capability.
- * Used by the hub to resolve methods from CapabilityDefinitions (*.cap.ts)
- * when the package.json declaration doesn't include explicit methods.
- */
+* Optional resolver that returns method names for a capability.
+* Used by the hub to resolve methods from CapabilityDefinitions (*.cap.ts)
+* when the package.json declaration doesn't include explicit methods.
+*/
 type MethodResolver = (capabilityName: string) => readonly string[];
 /**
- * Wrap an ICamstackAddon as a Moleculer ServiceSchema.
- *
- * Methods for each capability are resolved in this order:
- * 1. `declaration.capabilities[].methods` from package.json
- * 2. `methodResolver(capName)` from CapabilityRegistry definitions
- * 3. Auto-discovery: enumerate own methods on the registered provider
- *
- * Additionally, the four two-level settings methods (`getGlobalSettings`,
- * `updateGlobalSettings`, `getDeviceSettings`, `updateDeviceSettings`)
- * are auto-exposed under a
- * `settings.*` namespace if the addon implements them. This replaces the
- * former `$addonHost` Moleculer service — the hub's `addon-settings`
- * singleton provider calls `broker.call('<addonId>.settings.<method>')`.
- */
+* Wrap an ICamstackAddon as a Moleculer ServiceSchema.
+*
+* Methods for each capability are resolved in this order:
+* 1. `declaration.capabilities[].methods` from package.json
+* 2. `methodResolver(capName)` from CapabilityRegistry definitions
+* 3. Auto-discovery: enumerate own methods on the registered provider
+*
+* Additionally, the four two-level settings methods (`getGlobalSettings`,
+* `updateGlobalSettings`, `getDeviceSettings`, `updateDeviceSettings`)
+* are auto-exposed under a
+* `settings.*` namespace if the addon implements them. This replaces the
+* former `$addonHost` Moleculer service — the hub's `addon-settings`
+* singleton provider calls `broker.call('<addonId>.settings.<method>')`.
+*/
 declare function createAddonService(addon: ICamstackAddon, declaration: AddonDeclaration, options?: {
-    readonly methodResolver?: MethodResolver;
-    /** Per-action Moleculer timeout override: (capName, methodName) → ms */
-    readonly timeoutResolver?: (capName: string, methodName: string) => number | undefined;
-    readonly providers?: ReadonlyMap<string, unknown>;
-    /**
-     * Custom action catalog declared via `onInitialize()`'s `customActions`
-     * field. The service exposes them as `custom.<actionName>` moleculer
-     * actions + advertises their names via metadata so the hub can proxy
-     * dispatches into the worker when the addon runs forkable.
-     */
-    readonly customActions?: Readonly<Record<string, unknown>>;
-    readonly actionHandlers?: Readonly<Record<string, (input: unknown) => unknown | Promise<unknown>>>;
+	readonly methodResolver?: MethodResolver;
+	/** Per-action Moleculer timeout override: (capName, methodName) → ms */
+	readonly timeoutResolver?: (capName: string, methodName: string) => number | undefined;
+	readonly providers?: ReadonlyMap<string, unknown>;
+	/**
+	* Custom action catalog declared via `onInitialize()`'s `customActions`
+	* field. The service exposes them as `custom.<actionName>` moleculer
+	* actions + advertises their names via metadata so the hub can proxy
+	* dispatches into the worker when the addon runs forkable.
+	*/
+	readonly customActions?: Readonly<Record<string, unknown>>;
+	readonly actionHandlers?: Readonly<Record<string, (input: unknown) => unknown | Promise<unknown>>>;
 }): ServiceSchema;
 export { createAddonService, validateProviderRegistrations };

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

@@ -1,41 +1,68 @@
-import { MeshAuthMode, MeshNodeAuthState } from './mesh-auth-mode.js';
-import { MeshCallVerdict } from './mesh-authenticator.js';
-import { MeshJoinState } from './mesh-join-client.js';
+/**
+* AgentMeshAuthenticator — which peer may call THIS agent over the mesh
+* (D802 residual: agent inbound).
+*
+* The hub gate (`MeshAuthenticator`) is the other half of the same
+* containment. An agent reuses {@link createMeshAccessMiddleware} with this
+* admit policy:
+*
+*  1. **Hub.** Marked `authenticated` when {@link MeshJoinClient} settles a
+*     mutual challenge–response (`noteHubJoinState`). Forgotten on disconnect.
+*  2. **Own children** (`${ownNodeId}/…`). May call `$agent.registerNode`
+*     before they are authenticated (that call IS the proof — the handler
+*     checks the cluster-secret hash). A successful register marks them
+*     authenticated until disconnect.
+*  3. **Everyone else.** Refused in `enforced`, tolerated (with a warning
+*     hook) in `transition`. Mode is `enforced` when this agent holds a
+*     cluster secret, `transition` when it does not — so an upgrading agent
+*     without a secret still serves the hub.
+*
+* 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
+* shared middleware.
+*
+* Spoofing of a declared node id on clear-text Moleculer remains until mTLS
+* (`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";
 /** 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;
 export declare function isOwnChildNodeId(ownNodeId: string, sender: string): boolean;
 export interface AgentMeshAuthenticatorDeps {
-    readonly ownNodeId: string;
-    readonly hubNodeId?: string;
-    /** True when `agent.json` holds a cluster secret. */
-    readonly hasSecret: () => boolean;
-    readonly now?: () => number;
-    /** First time a peer is tolerated without proof on this connection. */
-    readonly onTolerated?: (nodeId: string, action: string) => void;
+	readonly ownNodeId: string;
+	readonly hubNodeId?: string;
+	/** True when `agent.json` holds a cluster secret. */
+	readonly hasSecret: () => boolean;
+	readonly now?: () => number;
+	/** First time a peer is tolerated without proof on this connection. */
+	readonly onTolerated?: (nodeId: string, action: string) => void;
 }
 export declare class AgentMeshAuthenticator {
-    private readonly deps;
-    private readonly nodes;
-    private readonly hubNodeId;
-    private readonly now;
-    constructor(deps: AgentMeshAuthenticatorDeps);
-    /** Current mode: secret configured → enforce; else tolerate (upgrade path). */
-    mode(): MeshAuthMode;
-    /**
-     * Reflect a settled mesh join. `authenticated` stamps the hub; a blocking
-     * failure forgets it so an impostor cannot call in; transitional states
-     * leave the hub unmarked (calls are tolerated while mode is `transition`).
-     */
-    noteHubJoinState(state: MeshJoinState): void;
-    /** A child's `$agent.registerNode` was accepted (secret hash matched or none required). */
-    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;
-    stateOf(nodeId: string): MeshNodeAuthState;
-    authenticatedNodeIds(): readonly string[];
-    private admitSender;
-    private record;
+	private readonly deps;
+	private readonly nodes;
+	private readonly hubNodeId;
+	private readonly now;
+	constructor(deps: AgentMeshAuthenticatorDeps);
+	/** Current mode: secret configured → enforce; else tolerate (upgrade path). */
+	mode(): MeshAuthMode;
+	/**
+	* Reflect a settled mesh join. `authenticated` stamps the hub; a blocking
+	* failure forgets it so an impostor cannot call in; transitional states
+	* leave the hub unmarked (calls are tolerated while mode is `transition`).
+	*/
+	noteHubJoinState(state: MeshJoinState): void;
+	/** A child's `$agent.registerNode` was accepted (secret hash matched or none required). */
+	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;
+	stateOf(nodeId: string): MeshNodeAuthState;
+	authenticatedNodeIds(): readonly string[];
+	private admitSender;
+	private record;
 }

package/dist/kernel/moleculer/agent-ui-unlock.d.ts

@@ -3,50 +3,50 @@ export declare const AGENT_UI_UNLOCK_VERSION: 1;
 /** Ticket lifetime — long enough for a redirect hop, short enough to steal poorly. */
 export declare const AGENT_UI_UNLOCK_TTL_MS: number;
 /**
- * Cluster settings key: extra origins allowed as `returnTo` for Continue-with-hub
- * (NPM hostnames that are not `:4444` on a LAN IP). Comma-separated origins.
- */
+* Cluster settings key: extra origins allowed as `returnTo` for Continue-with-hub
+* (NPM hostnames that are not `:4444` on a LAN IP). Comma-separated origins.
+*/
 export declare const AGENT_DASHBOARD_ORIGINS_FIELD = "agentDashboardOrigins";
 export interface AgentUiUnlockPayload {
-    readonly v: typeof AGENT_UI_UNLOCK_VERSION;
-    readonly nodeId: string;
-    /** Epoch ms. */
-    readonly exp: number;
-    readonly jti: string;
+	readonly v: typeof AGENT_UI_UNLOCK_VERSION;
+	readonly nodeId: string;
+	/** Epoch ms. */
+	readonly exp: number;
+	readonly jti: string;
 }
 /** In-memory spent `jti` until `exp` (ms). */
 export declare class UnlockTicketJtiStore {
-    private readonly spent;
-    isSpent(jti: string, nowMs?: number): boolean;
-    /** Record a jti as used until `exp`. Returns false if already spent. */
-    consume(jti: string, exp: number, nowMs?: number): boolean;
-    /** Test helper. */
-    size(): number;
-    private gc;
+	private readonly spent;
+	isSpent(jti: string, nowMs?: number): boolean;
+	/** Record a jti as used until `exp`. Returns false if already spent. */
+	consume(jti: string, exp: number, nowMs?: number): boolean;
+	/** Test helper. */
+	size(): number;
+	private gc;
 }
 export interface MintAgentUiUnlockTicketInput {
-    /** `hashClusterSecret(secret)` — never the raw secret. */
-    readonly secretHash: string;
-    readonly nodeId: string;
-    readonly ttlMs?: number;
-    readonly nowMs?: number;
-    readonly jti?: string;
+	/** `hashClusterSecret(secret)` — never the raw secret. */
+	readonly secretHash: string;
+	readonly nodeId: string;
+	readonly ttlMs?: number;
+	readonly nowMs?: number;
+	readonly jti?: string;
 }
 export declare function mintAgentUiUnlockTicket(input: MintAgentUiUnlockTicketInput): string;
 export interface VerifyAgentUiUnlockTicketOptions {
-    readonly expectedNodeId: string;
-    readonly nowMs?: number;
+	readonly expectedNodeId: string;
+	readonly nowMs?: number;
 }
 /**
- * Verify a ticket under `secretHash`. Returns the payload, or `null` when the
- * signature, shape, expiry or nodeId fails (no reason string — refuse quietly).
- */
+* Verify a ticket under `secretHash`. Returns the payload, or `null` when the
+* signature, shape, expiry or nodeId fails (no reason string — refuse quietly).
+*/
 export declare function verifyAgentUiUnlockTicket(secretHash: string, ticket: string, options: VerifyAgentUiUnlockTicketOptions): AgentUiUnlockPayload | null;
 /**
- * True when `returnTo` may receive a ticket redirect. Default: any http(s)
- * origin whose port is 4444. Extra origins come from
- * {@link AGENT_DASHBOARD_ORIGINS_FIELD} (exact origin match).
- */
+* True when `returnTo` may receive a ticket redirect. Default: any http(s)
+* origin whose port is 4444. Extra origins come from
+* {@link AGENT_DASHBOARD_ORIGINS_FIELD} (exact origin match).
+*/
 export declare function isAllowedAgentDashboardReturnTo(returnTo: string, extraOrigins?: readonly string[]): boolean;
 /** Parse a stored comma/whitespace-separated origins list. */
 export declare function parseAgentDashboardOrigins(stored: unknown): readonly string[];

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

@@ -1,67 +1,67 @@
-import { ServiceBroker, Middleware } from 'moleculer';
-import { MeshTlsMaterial, TlsTcpTransporter } from './mesh-mtls/index.js';
+import { ServiceBroker, type Middleware } from "moleculer";
+import { type MeshTlsMaterial, TlsTcpTransporter } from "./mesh-mtls/index.js";
 interface BrokerConfig {
-    readonly nodeID: string;
-    readonly mode: 'hub' | 'agent' | 'test';
-    readonly hubAddress?: string;
-    readonly logLevel?: string;
-    /**
-     * TCP port the hub listens on for cluster traffic.
-     * Agents need a deterministic port to connect via `urls: 'hub@host:port'`
-     * when UDP multicast discovery is disabled.
-     */
-    readonly tcpPort?: number;
-    /**
-     * Second hub listen port for mesh mTLS (Release A). Default 6443.
-     * Clear traffic stays on {@link tcpPort}; enrolled agents dial this.
-     */
-    readonly tlsPort?: number;
-    /** UDP port for cluster discovery (default: 4445). */
-    readonly udpPort?: number;
-    /**
-     * Explicit TCP port for the agent's own Moleculer reader to bind.
-     * When omitted, the port is derived deterministically from `nodeID`
-     * (see `deriveAgentListenPort`). Set this only to resolve a port
-     * collision between two agents that happen to hash to the same port
-     * on one host.
-     */
-    readonly agentListenPort?: number;
-    /**
-     * Broker middlewares (D802): the hub passes its mesh gate
-     * (`createMeshAccessMiddleware`); an agent passes inbound access
-     * (`AgentMeshAuthenticator` + the same middleware) and its outbound join
-     * gate (`MeshJoinClient.middleware`). They must be given at construction —
-     * Moleculer wraps action handlers when services register.
-     */
-    readonly middlewares?: readonly Middleware[];
-    /**
-     * Mesh mTLS material. On the hub, enables the TLS listener (may also be
-     * attached later via {@link getBrokerTlsTransporter}). On an agent, dials
-     * the hub's TLS port (6443) instead of clear 6000.
-     */
-    readonly meshTls?: MeshTlsMaterial;
+	readonly nodeID: string;
+	readonly mode: "hub" | "agent" | "test";
+	readonly hubAddress?: string;
+	readonly logLevel?: string;
+	/**
+	* TCP port the hub listens on for cluster traffic.
+	* Agents need a deterministic port to connect via `urls: 'hub@host:port'`
+	* when UDP multicast discovery is disabled.
+	*/
+	readonly tcpPort?: number;
+	/**
+	* Second hub listen port for mesh mTLS (Release A). Default 6443.
+	* Clear traffic stays on {@link tcpPort}; enrolled agents dial this.
+	*/
+	readonly tlsPort?: number;
+	/** UDP port for cluster discovery (default: 4445). */
+	readonly udpPort?: number;
+	/**
+	* Explicit TCP port for the agent's own Moleculer reader to bind.
+	* When omitted, the port is derived deterministically from `nodeID`
+	* (see `deriveAgentListenPort`). Set this only to resolve a port
+	* collision between two agents that happen to hash to the same port
+	* on one host.
+	*/
+	readonly agentListenPort?: number;
+	/**
+	* Broker middlewares (D802): the hub passes its mesh gate
+	* (`createMeshAccessMiddleware`); an agent passes inbound access
+	* (`AgentMeshAuthenticator` + the same middleware) and its outbound join
+	* gate (`MeshJoinClient.middleware`). They must be given at construction —
+	* Moleculer wraps action handlers when services register.
+	*/
+	readonly middlewares?: readonly Middleware[];
+	/**
+	* Mesh mTLS material. On the hub, enables the TLS listener (may also be
+	* attached later via {@link getBrokerTlsTransporter}). On an agent, dials
+	* the hub's TLS port (6443) instead of clear 6000.
+	*/
+	readonly meshTls?: MeshTlsMaterial;
 }
 /**
- * Derive a STABLE Moleculer reader port for an agent from its nodeID.
- *
- * Moleculer's TCP transporter keeps disconnected nodes in its
- * `NodeCatalog` (it never deletes them) and `processGossipHello` only
- * adopts a node's host/port when the node is unknown — a reconnecting
- * node's address is therefore never refreshed. With an OS-assigned
- * EPHEMERAL reader port (`port: 0`) every agent restart picks a new
- * port, so after a kill+restart under the SAME nodeID the hub (and every
- * forked group-runner that gossiped about the agent) keeps the DEAD port
- * and can never deliver the `GOSSIP_RESPONSE` carrying its INFO. The
- * agent then never re-discovers the hub's services and `ctx.api.*` calls
- * (e.g. the early `settings-store.get` in `bootCoreAddons`) poll service
- * discovery forever.
- *
- * Binding a port DERIVED FROM the nodeID makes the agent reconnect at the
- * SAME address every restart — exactly like the hub's fixed 6000 — so the
- * stale catalog entries everywhere still point at a live socket and
- * Moleculer's gossip seq self-healing completes the handshake. The nodeID
- * is the agent's persisted stable identity, so the port is stable too.
- */
+* Derive a STABLE Moleculer reader port for an agent from its nodeID.
+*
+* Moleculer's TCP transporter keeps disconnected nodes in its
+* `NodeCatalog` (it never deletes them) and `processGossipHello` only
+* adopts a node's host/port when the node is unknown — a reconnecting
+* node's address is therefore never refreshed. With an OS-assigned
+* EPHEMERAL reader port (`port: 0`) every agent restart picks a new
+* port, so after a kill+restart under the SAME nodeID the hub (and every
+* forked group-runner that gossiped about the agent) keeps the DEAD port
+* and can never deliver the `GOSSIP_RESPONSE` carrying its INFO. The
+* agent then never re-discovers the hub's services and `ctx.api.*` calls
+* (e.g. the early `settings-store.get` in `bootCoreAddons`) poll service
+* discovery forever.
+*
+* Binding a port DERIVED FROM the nodeID makes the agent reconnect at the
+* SAME address every restart — exactly like the hub's fixed 6000 — so the
+* stale catalog entries everywhere still point at a live socket and
+* Moleculer's gossip seq self-healing completes the handshake. The nodeID
+* is the agent's persisted stable identity, so the port is stable too.
+*/
 declare function deriveAgentListenPort(nodeID: string): number;
 declare function createBroker(config: BrokerConfig): ServiceBroker;
 declare function normalizeHubUrl(raw: string, defaultPort: number): string;