@camstack/system 1.2.382 → 1.2.384

package/dist/{jwt-signing-key-Dgf8sIXY.js → jwt-signing-key-BTDLP6U5.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-tnAO12ak.js");
+const require_dist = require("./dist-Cf0yAy6y.js");
 let node_crypto = require("node:crypto");
 //#region src/auth/jwt-signing-key.ts
 /**

package/dist/{jwt-signing-key-CAbozwvF.mjs → jwt-signing-key-CnNafp3J.mjs}

@@ -1,4 +1,4 @@
-import { Sr as buildSecretRef } from "./dist-CP5TTjwd.mjs";
+import { Sr as buildSecretRef } from "./dist-D8XMuZCS.mjs";
 import { randomBytes } from "node:crypto";
 //#region src/auth/jwt-signing-key.ts
 /**

package/dist/kernel/index.d.ts

@@ -37,8 +37,10 @@ export type { AddonSettingsView } from './config-manager.js';
 export { DeviceRegistry } from './device-registry.js';
 export { buildStorageLocationRegistry } from './storage-location-registry.js';
 export type { StorageLocationRegistry } from './storage-location-registry.js';
-export { createBroker, deriveAgentListenPort } from './moleculer/broker-factory.js';
+export { createBroker, deriveAgentListenPort, getBrokerTlsTransporter, } from './moleculer/broker-factory.js';
 export type { BrokerConfig } from './moleculer/broker-factory.js';
+export { applyProcessMeshClearPort, caFingerprint, caFingerprintCompact, checkProcessMeshClearPort, createMeshCsrPem, decideMeshClearPortOff, enrollMeshNode, exportMeshPrivateKeyPem, getProcessNodeMeshTransport, MESH_CLEAR_PORT_FIELD, setProcessMeshClearPortControl, 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 type { MeshCaSigner, MeshClearPortAgent, MeshClearPortControl, MeshClearPortDecision, MeshClearPortMode, MeshEnrollResult, 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';
 export { createCoreCapService, CORE_CAP_SERVICE_NAME } from './moleculer/core-cap-service.js';
@@ -57,7 +59,9 @@ export type { ClusterSecretGate, ClusterSecretVerdict } from './moleculer/cluste
 export { MeshAuthenticator, isRemoteForbiddenAction, MESH_JOIN_CHALLENGE_TTL_MS, } from './moleculer/mesh-authenticator.js';
 export type { MeshAuthenticatorDeps, MeshCallVerdict, } from './moleculer/mesh-authenticator.js';
 export { createMeshAccessMiddleware, stripForgedIdentity, } from './moleculer/mesh-access-middleware.js';
-export type { MeshAccessMiddlewareOptions } from './moleculer/mesh-access-middleware.js';
+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 { 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-mesh-authenticator.d.ts

@@ -0,0 +1,41 @@
+import { MeshAuthMode, MeshNodeAuthState } from './mesh-auth-mode.js';
+import { MeshCallVerdict } from './mesh-authenticator.js';
+import { 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;
+}
+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;
+}

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

@@ -1,4 +1,5 @@
 import { ServiceBroker, Middleware } from 'moleculer';
+import { MeshTlsMaterial, TlsTcpTransporter } from './mesh-mtls/index.js';
 interface BrokerConfig {
     readonly nodeID: string;
     readonly mode: 'hub' | 'agent' | 'test';
@@ -10,6 +11,11 @@ interface BrokerConfig {
      * 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;
     /**
@@ -22,11 +28,18 @@ interface BrokerConfig {
     readonly agentListenPort?: number;
     /**
      * Broker middlewares (D802): the hub passes its mesh gate
-     * (`createMeshAccessMiddleware`), an agent its join gate
-     * (`MeshJoinClient.middleware`). They must be given at construction —
+     * (`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.
@@ -51,5 +64,8 @@ interface BrokerConfig {
  */
 declare function deriveAgentListenPort(nodeID: string): number;
 declare function createBroker(config: BrokerConfig): ServiceBroker;
-export { createBroker, deriveAgentListenPort };
+declare function normalizeHubUrl(raw: string, defaultPort: number): string;
+/** The hub's {@link TlsTcpTransporter}, or null when the broker is not mesh-TLS. */
+declare function getBrokerTlsTransporter(broker: ServiceBroker): TlsTcpTransporter | null;
+export { createBroker, deriveAgentListenPort, getBrokerTlsTransporter, normalizeHubUrl };
 export type { BrokerConfig };

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

@@ -1,5 +1,10 @@
 import { Middleware } from 'moleculer';
-import { MeshAuthenticator } from './mesh-authenticator.js';
+import { MeshCallVerdict } from './mesh-authenticator.js';
+/** Minimal surface the middleware needs — hub and agent authenticators both fit. */
+export interface MeshCallGate {
+    admitCall(sender: string, action: string): MeshCallVerdict;
+    admitEvent(sender: string, eventName: string): MeshCallVerdict;
+}
 /**
  * The params of a request from another node, with every identity it claimed
  * removed:
@@ -17,7 +22,7 @@ interface GateLogger {
 }
 export interface MeshAccessMiddlewareOptions {
     readonly ownNodeId: string;
-    readonly authenticator: MeshAuthenticator;
+    readonly authenticator: MeshCallGate;
     readonly logger?: GateLogger;
 }
 /**

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

@@ -0,0 +1,20 @@
+/** `secret://system/global/meshCaKey` — EC P-256 PKCS#8 PEM of the hub mesh CA. */
+export declare const MESH_CA_KEY_REF: string;
+/** `system-settings` key holding the public CA certificate PEM. */
+export declare const MESH_CA_SETTINGS_KEY = "cluster.meshCa";
+/** Field inside the `cluster` section (same row as the secret). */
+export declare const MESH_CA_FIELD = "meshCa";
+/** Join-token / leaf lifetimes. */
+export declare const MESH_JOIN_TOKEN_MAX_TTL_SEC: number;
+export declare const MESH_LEAF_VALIDITY_DAYS = 30;
+export declare const MESH_CA_VALIDITY_DAYS = 3650;
+/** Hub clear TCP (existing) and TLS dual-listen port (Release A). */
+export declare const DEFAULT_HUB_TCP_PORT = 6000;
+export declare const DEFAULT_HUB_TLS_TCP_PORT = 6443;
+/** Join token payload version. */
+export declare const MESH_JOIN_TOKEN_VERSION: 1;
+/** Subject of the mesh root. Distinct from the HTTPS local CA. */
+export declare const MESH_CA_COMMON_NAME = "CamStack Mesh CA";
+/** Client + server auth EKU OIDs (mutual TLS). */
+export declare const SERVER_AUTH_OID = "1.3.6.1.5.5.7.3.1";
+export declare const CLIENT_AUTH_OID = "1.3.6.1.5.5.7.3.2";

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

@@ -0,0 +1,10 @@
+export { CLIENT_AUTH_OID, DEFAULT_HUB_TCP_PORT, DEFAULT_HUB_TLS_TCP_PORT, MESH_CA_COMMON_NAME, MESH_CA_FIELD, MESH_CA_KEY_REF, MESH_CA_SETTINGS_KEY, MESH_CA_VALIDITY_DAYS, MESH_JOIN_TOKEN_MAX_TTL_SEC, MESH_JOIN_TOKEN_VERSION, MESH_LEAF_VALIDITY_DAYS, SERVER_AUTH_OID, } from './constants.js';
+export { caFingerprint, caFingerprintCompact, createMeshCsrPem, exportMeshPrivateKeyPem, generateMeshCa, generateMeshKeyPair, issueMeshLeafForNode, issueMeshLeafFromCsr, loadMeshCa, MESH_KEY_ALGORITHM, MESH_SIGNING_ALGORITHM, subjectCn, type MeshCaSigner, type MeshLeafMaterial, } from './mesh-ca.js';
+export { clearProcessMeshCa, getProcessMeshCaState, loadOrGenerateMeshCa, MESH_CA_RETRY_MS, MeshCaKeeper, requireProcessMeshCa, setProcessMeshCa, type MeshCaKeeperDeps, type MeshCaState, } from './mesh-ca-keeper.js';
+export { clearProcessMeshCrl, MeshCrl, processMeshCrl, } from './mesh-crl.js';
+export { applyProcessMeshClearPort, checkProcessMeshClearPort, decideMeshClearPortOff, getProcessMeshClearPortControl, getProcessNodeMeshTransport, isMeshClearPortMode, MESH_CLEAR_PORT_FIELD, parseMeshClearPortMode, setProcessMeshClearPortControl, type MeshClearPortAgent, type MeshClearPortControl, type MeshClearPortDecision, type MeshClearPortMode, type MeshTransport, } from './mesh-clear-port.js';
+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';

package/dist/kernel/moleculer/mesh-mtls/mesh-ca-keeper.d.ts

@@ -0,0 +1,55 @@
+import { SecretsAccess } from '@camstack/types';
+import { MeshCaSigner } from './mesh-ca.js';
+export type MeshCaState = {
+    readonly state: 'ready';
+    readonly ca: MeshCaSigner;
+} | {
+    readonly state: 'unavailable';
+    readonly reason: string;
+};
+export declare function setProcessMeshCa(state: MeshCaState): void;
+export declare function clearProcessMeshCa(): void;
+export declare function getProcessMeshCaState(): MeshCaState;
+export declare function requireProcessMeshCa(): MeshCaSigner;
+export declare const MESH_CA_RETRY_MS = 30000;
+interface KeeperLogger {
+    info(message: string, meta?: {
+        meta?: Record<string, unknown>;
+    }): void;
+    error(message: string, meta?: {
+        meta?: Record<string, unknown>;
+    }): void;
+    warn?(message: string, meta?: {
+        meta?: Record<string, unknown>;
+    }): void;
+}
+export interface MeshCaKeeperDeps {
+    readonly secrets: SecretsAccess | null;
+    /** Read `cluster` section (may contain `meshCa` PEM). */
+    readonly readClusterSection: () => Promise<Record<string, unknown>>;
+    /** Persist the CA cert PEM under `cluster.meshCa`. */
+    readonly writeMeshCaCert: (certPem: string) => Promise<void>;
+    readonly logger: KeeperLogger;
+    readonly retryMs?: number;
+    /** Fired when the CA becomes ready (start TLS listener, etc.). */
+    readonly onReady?: (ca: MeshCaSigner) => void | Promise<void>;
+}
+export declare class MeshCaKeeper {
+    private readonly deps;
+    private retryTimer;
+    private unsubscribe;
+    private stopped;
+    constructor(deps: MeshCaKeeperDeps);
+    start(): Promise<void>;
+    stop(): void;
+    private load;
+    private apply;
+    private scheduleRetry;
+}
+export interface LoadOrGenerateMeshCaDeps {
+    readonly secrets: SecretsAccess;
+    readonly readClusterSection: () => Promise<Record<string, unknown>>;
+    readonly writeMeshCaCert: (certPem: string) => Promise<void>;
+}
+export declare function loadOrGenerateMeshCa(deps: LoadOrGenerateMeshCaDeps): Promise<MeshCaState>;
+export {};

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

@@ -0,0 +1,45 @@
+import { webcrypto as WebCrypto } from 'node:crypto';
+import { X509Certificate as PeculiarCertificate } from '@peculiar/x509';
+/** Key generation — EC P-256 (plan). WebCrypto DOM names are not in @types/node. */
+export declare const MESH_KEY_ALGORITHM: WebCrypto.EcKeyGenParams;
+/** Signing — ECDSA with SHA-256. */
+export declare const MESH_SIGNING_ALGORITHM: WebCrypto.EcdsaParams;
+export interface MeshCaSigner {
+    readonly certPem: string;
+    readonly keyPem: string;
+    readonly cert: PeculiarCertificate;
+    readonly privateKey: WebCrypto.CryptoKey;
+    readonly publicKey: WebCrypto.CryptoKey;
+}
+export interface MeshLeafMaterial {
+    readonly certPem: string;
+    readonly serialNumber: string;
+    readonly notAfter: Date;
+    readonly commonName: string;
+}
+/** SHA-256 fingerprint of the DER cert, colon-hex uppercase (Node style). */
+export declare function caFingerprint(certPem: string): string;
+/** Compact fingerprint (lowercase hex, no colons) for join-token payloads. */
+export declare function caFingerprintCompact(certPem: string): string;
+export declare function generateMeshCa(now?: Date): Promise<MeshCaSigner>;
+export declare function loadMeshCa(certPem: string, keyPem: string): Promise<MeshCaSigner>;
+/**
+ * Issue a leaf from a CSR. CN must be present; when `expectedNodeId` is set
+ * it must match. Validity: 30 days.
+ */
+export declare function issueMeshLeafFromCsr(ca: MeshCaSigner, csrPem: string, opts?: {
+    readonly expectedNodeId?: string;
+    readonly now?: Date;
+    readonly validDays?: number;
+}): Promise<MeshLeafMaterial>;
+/** Issue a leaf for a known nodeID with a freshly generated key pair (tests / hub self). */
+export declare function issueMeshLeafForNode(ca: MeshCaSigner, nodeId: string, opts?: {
+    readonly now?: Date;
+    readonly validDays?: number;
+}): Promise<MeshLeafMaterial & {
+    readonly keyPem: string;
+}>;
+export declare function subjectCn(subject: string): string | null;
+export declare function createMeshCsrPem(keys: WebCrypto.CryptoKeyPair, commonName: string): Promise<string>;
+export declare function generateMeshKeyPair(): Promise<WebCrypto.CryptoKeyPair>;
+export declare function exportMeshPrivateKeyPem(key: WebCrypto.CryptoKey): Promise<string>;

package/dist/kernel/moleculer/mesh-mtls/mesh-clear-port.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Cutover switch for the hub's clear mesh port (Release A, rollout step 3).
+ *
+ * `cluster.meshClearPort` = `on` (default — clear :6000 + UDP discovery run next
+ * to the TLS :6443 listener) or `off` (the hub stops listening on :6000 and
+ * stops UDP discovery). Turning it off is REFUSED while any online agent still
+ * reaches the hub in clear — the same spirit as D803's auto-enforce: the switch
+ * must never cut off an agent that has not enrolled.
+ *
+ * The setting is owned by `system-config`; the transporter lives in the hub's
+ * broker. They meet through this process slot (same pattern as
+ * `mesh-auth-mode.ts` / `mesh-tls-enabler.ts`).
+ */
+/** How a node reaches the hub. */
+export type MeshTransport = 'tls' | 'clear';
+export type MeshClearPortMode = 'on' | 'off';
+/** The field key inside the `cluster` section. */
+export declare const MESH_CLEAR_PORT_FIELD = "meshClearPort";
+export declare function isMeshClearPortMode(value: unknown): value is MeshClearPortMode;
+/** A stored value that is not a mode reads as `on`: never cut the mesh on a typo. */
+export declare function parseMeshClearPortMode(value: unknown): MeshClearPortMode;
+export interface MeshClearPortAgent {
+    readonly nodeId: string;
+    readonly transport: MeshTransport;
+}
+export interface MeshClearPortControl {
+    /** Agents connected right now (never the hub, never `hub/<runner>` children). */
+    listOnlineAgents(): readonly MeshClearPortAgent[];
+    /** Whether the TLS listener is up — without it, closing the clear port cuts everyone. */
+    isTlsListening(): boolean;
+    /** Close (`off`) or reopen (`on`) the clear TCP reader and UDP discovery. */
+    apply(mode: MeshClearPortMode): Promise<void>;
+    /** How one node reaches the hub, `undefined` when the hub cannot tell. */
+    transportOf(nodeId: string): MeshTransport | undefined;
+}
+export type MeshClearPortDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly blocking: readonly string[];
+    readonly error: string;
+};
+/** Pure: may the clear port be switched off right now? */
+export declare function decideMeshClearPortOff(control: Pick<MeshClearPortControl, 'listOnlineAgents' | 'isTlsListening'> | null): MeshClearPortDecision;
+/** Published by the hub's broker owner; cleared on shutdown. */
+export declare function setProcessMeshClearPortControl(control: MeshClearPortControl | null): void;
+export declare function getProcessMeshClearPortControl(): MeshClearPortControl | null;
+/** `tls` / `clear` for an agent as the hub sees it; `undefined` off the hub. */
+export declare function getProcessNodeMeshTransport(nodeId: string): MeshTransport | undefined;
+/**
+ * Validate a requested mode against the live mesh. `on` is always allowed; `off`
+ * only when {@link decideMeshClearPortOff} allows. Does NOT apply it.
+ */
+export declare function checkProcessMeshClearPort(mode: MeshClearPortMode): MeshClearPortDecision;
+/** Apply a mode that {@link checkProcessMeshClearPort} allowed. No-op where nobody can. */
+export declare function applyProcessMeshClearPort(mode: MeshClearPortMode): Promise<boolean>;

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

@@ -0,0 +1,16 @@
+/**
+ * Mesh certificate revocation list — in-memory + optional persist hook.
+ *
+ * Release A can stub persistence; the reader checks serials at handshake and
+ * a later "Forget node" closes open sockets (Release A+).
+ */
+export declare class MeshCrl {
+    private readonly serials;
+    revoke(serialNumber: string): void;
+    isRevoked(serialNumber: string): boolean;
+    list(): readonly string[];
+    /** Restore from persisted serials (system-settings). */
+    replaceAll(serials: readonly string[]): void;
+}
+export declare function processMeshCrl(): MeshCrl;
+export declare function clearProcessMeshCrl(): void;

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

@@ -0,0 +1,27 @@
+import { MeshCaSigner } from './mesh-ca.js';
+import { JoinTokenJtiStore, MeshJoinTokenClaims } from './mesh-join-token.js';
+export interface MeshEnrollRequest {
+    readonly token: string;
+    readonly csr: string;
+}
+export interface MeshEnrollSuccess {
+    readonly ok: true;
+    readonly cert: string;
+    readonly caCert: string;
+    readonly nodeId: string;
+    readonly notAfter: string;
+    readonly serialNumber: string;
+}
+export interface MeshEnrollFailure {
+    readonly ok: false;
+    readonly error: string;
+    readonly status: number;
+}
+export type MeshEnrollResult = MeshEnrollSuccess | MeshEnrollFailure;
+export interface EnrollMeshNodeDeps {
+    readonly ca: MeshCaSigner;
+    readonly jtiStore?: JoinTokenJtiStore;
+    readonly now?: Date;
+}
+export declare function enrollMeshNode(body: MeshEnrollRequest, deps: EnrollMeshNodeDeps): Promise<MeshEnrollResult>;
+export type { MeshJoinTokenClaims };

package/dist/kernel/moleculer/mesh-mtls/mesh-join-token.d.ts

@@ -0,0 +1,55 @@
+import { MESH_JOIN_TOKEN_VERSION } from './constants.js';
+import { MeshCaSigner } from './mesh-ca.js';
+export interface MeshJoinTokenClaims {
+    readonly v: typeof MESH_JOIN_TOKEN_VERSION;
+    readonly hubUrl: string;
+    readonly hubMeshAddress: string;
+    readonly caFingerprint: string;
+    readonly nodeId?: string;
+    readonly jti: string;
+    readonly exp: number;
+}
+export type MeshJoinTokenVerifyResult = {
+    readonly ok: true;
+    readonly claims: MeshJoinTokenClaims;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** In-memory + optional persist of spent `jti` until `exp`. */
+export declare class JoinTokenJtiStore {
+    private readonly spent;
+    /** True when `jti` was already consumed (and not yet expired). */
+    isSpent(jti: string, nowSec?: number): boolean;
+    /** Record a jti as used until `exp`. Returns false if already spent. */
+    consume(jti: string, exp: number, nowSec?: number): boolean;
+    /** Test helper. */
+    size(): number;
+    private gc;
+}
+export declare function processJoinTokenJtiStore(): JoinTokenJtiStore;
+export interface MintJoinTokenInput {
+    readonly ca: MeshCaSigner;
+    readonly hubUrl: string;
+    readonly hubMeshAddress: string;
+    readonly nodeId?: string;
+    /** Seconds from now; capped at {@link MESH_JOIN_TOKEN_MAX_TTL_SEC}. */
+    readonly ttlSec?: number;
+    readonly now?: Date;
+    readonly jti?: string;
+}
+export declare function mintMeshJoinToken(input: MintJoinTokenInput): Promise<string>;
+export interface VerifyJoinTokenInput {
+    readonly token: string;
+    readonly ca: MeshCaSigner;
+    readonly jtiStore?: JoinTokenJtiStore;
+    readonly now?: Date;
+    /** When true (enroll), consume the jti. Mint-path verify may skip. */
+    readonly consume?: boolean;
+    /**
+     * Expected CA fingerprint pin. When set, must match the token's
+     * `caFingerprint` (and therefore this CA) — a MITM with another CA fails.
+     */
+    readonly expectedCaFingerprint?: string;
+}
+export declare function verifyMeshJoinToken(input: VerifyJoinTokenInput): Promise<MeshJoinTokenVerifyResult>;

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

@@ -0,0 +1,5 @@
+import { MeshTlsMaterial } from './tls-tcp-transporter.js';
+export type MeshTlsEnabler = (material: MeshTlsMaterial) => void | Promise<void>;
+export declare function setProcessMeshTlsEnabler(enabler: MeshTlsEnabler | null): void;
+export declare function getProcessMeshTlsEnabler(): MeshTlsEnabler | null;
+export declare function requestProcessMeshTlsEnable(material: MeshTlsMaterial): Promise<void>;

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

@@ -0,0 +1,125 @@
+import { Server as NetServer, Socket as NetSocket } from 'node:net';
+import { MeshCrl } from './mesh-crl.js';
+interface TlsTcpTransporterBase {
+    opts: Record<string, unknown> & {
+        port?: number;
+        tlsPort?: number;
+        maxPacketSize?: number;
+    };
+    logger: {
+        info(msg: string, ...args: unknown[]): void;
+        warn(msg: string, ...args: unknown[]): void;
+        debug(msg: string, ...args: unknown[]): void;
+        error(msg: string, ...args: unknown[]): void;
+    };
+    reader: {
+        listen(): Promise<number>;
+        close(): void;
+        server: NetServer | null;
+        sockets: NetSocket[];
+    } | null;
+    udpServer: {
+        close(): void;
+    } | null;
+    writer: unknown;
+    Promise: PromiseConstructor;
+    connected: boolean;
+    nodes: {
+        localNode: {
+            port: number;
+        };
+    };
+    registry: {
+        regenerateLocalRawInfo(force: boolean): void;
+    };
+    startTcpServer(): Promise<number>;
+    startUdpServer(): Promise<void>;
+    startTimers(): void;
+    onConnected(): Promise<void>;
+    loadUrls(): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    onIncomingMessage(type: string, message: Buffer, socket?: NetSocket): unknown;
+    receive(cmd: string, data: Buffer, socket?: NetSocket): unknown;
+    deserialize(type: string, data: Buffer): {
+        payload: {
+            sender?: string;
+        };
+    };
+    incomingMessage(cmd: string, data: Buffer): unknown;
+}
+export interface MeshTlsMaterial {
+    readonly caCertPem: string;
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+export interface TlsTcpTransporterOptions {
+    readonly port?: number;
+    readonly tlsPort?: number;
+    readonly maxPacketSize?: number;
+    readonly useHostname?: boolean;
+    readonly udpDiscovery?: boolean;
+    readonly udpPort?: number;
+    readonly udpPeriod?: number;
+    readonly debug?: boolean;
+    readonly urls?: string;
+    readonly udpMaxDiscovery?: number;
+    /** When set at construction, TLS starts with the clear reader. */
+    readonly meshTls?: MeshTlsMaterial;
+    readonly crl?: MeshCrl;
+}
+declare const TlsTcpTransporter_base: new (opts?: Record<string, unknown>) => TlsTcpTransporterBase;
+export declare class TlsTcpTransporter extends TlsTcpTransporter_base {
+    private tlsServer;
+    private meshTls;
+    private readonly crl;
+    private readonly tlsSockets;
+    /** Node id (certificate CN) → serial of every peer that completed a mutual-TLS handshake. */
+    private readonly tlsPeers;
+    private clearDisabled;
+    constructor(opts?: TlsTcpTransporterOptions);
+    startTcpServer(): Promise<number>;
+    connect(): Promise<void>;
+    /**
+     * Agent / outbound: wrap `TcpWriter.connect` so peers are dialed with
+     * mutual TLS and the peer CN must match the expected node id.
+     */
+    private patchWriterForTlsClient;
+    /**
+     * Enable (or refresh) the TLS listener once the mesh CA / hub leaf are ready.
+     * Safe to call after connect — starts listening on `tlsPort` alongside clear.
+     */
+    enableMeshTls(material: MeshTlsMaterial): Promise<void>;
+    /**
+     * How `nodeId` reaches this transporter: `tls` once it completed a mutual-TLS
+     * handshake (certificate CN = node id, issued by the mesh CA — so this cannot
+     * be claimed by a clear-text peer), otherwise `clear`. Sticky until
+     * {@link forgetPeer}: Moleculer closes idle sockets while the node is still
+     * connected, and a closed socket is not a downgrade.
+     */
+    peerTransport(nodeId: string): 'tls' | 'clear';
+    /**
+     * The node disconnected: its next connection decides its transport again —
+     * unless it already re-handshook (the disconnect can be noticed after the
+     * restarted node is back), in which case its live TLS socket keeps it `tls`.
+     */
+    forgetPeer(nodeId: string): void;
+    /** True once the mutual-TLS listener is bound. */
+    isTlsListening(): boolean;
+    isClearTransportEnabled(): boolean;
+    /**
+     * Cutover: stop listening on the clear TCP port, drop the clear-text sockets
+     * already open on it and stop UDP discovery. TLS sockets (own listener, own
+     * port) are untouched. Idempotent.
+     */
+    disableClearTransport(): void;
+    /** The switch back: listen on the clear port again and restart UDP discovery. Idempotent. */
+    enableClearTransport(): Promise<void>;
+    /** Close sockets whose peer serial was just revoked. */
+    dropRevokedSockets(): void;
+    disconnect(): Promise<void>;
+    onIncomingMessage(type: string, message: Buffer, socket?: NetSocket): unknown;
+    private startTlsServerIfReady;
+    private onTlsClientConnected;
+}
+export type { NetServer };