@camstack/system 1.2.378 → 1.2.380

package/dist/jwt-signing-key-Qhde8r82.mjs

@@ -0,0 +1,127 @@
+import { br as buildSecretRef } from "./dist-B9oFw2jh.mjs";
+import { randomBytes } from "node:crypto";
+//#region src/auth/jwt-signing-key.ts
+/**
+* The hub's session signing key — the HMAC key every JWT this hub mints
+* (sessions, SSO bridge, TOTP challenges, service tokens) is signed with.
+*
+* It lives in the keychain, owner `system` ({@link JWT_SIGNING_KEY_REF}), and
+* nowhere else: no environment variable, no `config.yaml` key (D797). The
+* hub's `local-auth` builtin loads it after the keychain booted and registers
+* it here; every `AuthManager` in the process asks this slot on every mint and
+* every verify, so a key that arrives (or changes) after construction is used
+* from the next call on.
+*
+* ## A locked keychain fails closed, visibly
+*
+* While the key cannot be read, sessions can be neither minted nor verified:
+* {@link JwtSigningKeySource.current} throws {@link JwtSigningKeyUnavailableError}
+* (a login answers that error, a bearer check reads it as "not authenticated").
+* There is deliberately NO fallback — not an env var, and not a fresh random
+* key, which would invalidate every session and every app token without
+* anyone having asked for it. A key is generated ONLY when the keychain
+* answers that none is stored (`missing`), i.e. on a fresh hub.
+*
+* Process-global through a registered symbol, like the desktop platform key,
+* so a second copy of this module (an addon bundle) sees the same key.
+*/
+/** The keychain owner of every system-held secret. */
+var SYSTEM_SECRET_OWNER = "system";
+/** `secret://system/global/jwtSigningKey`. */
+var JWT_SIGNING_KEY_REF = buildSecretRef({
+	owner: SYSTEM_SECRET_OWNER,
+	scope: { kind: "global" },
+	fieldPath: "jwtSigningKey"
+});
+/** Sessions cannot be minted or verified: the signing key is not loaded. */
+var JwtSigningKeyUnavailableError = class extends Error {
+	reason;
+	constructor(reason) {
+		super(`sessions are unavailable: the session signing key could not be read from the keychain (${reason}). Unlock the keychain (System → Secrets, or fix keychain.keyFile and restart).`);
+		this.reason = reason;
+		this.name = "JwtSigningKeyUnavailableError";
+	}
+};
+var SLOT = Symbol.for("camstack.auth.jwt-signing-key");
+var NOT_LOADED = {
+	state: "unavailable",
+	reason: "not-loaded"
+};
+function isState(value) {
+	if (value === null || typeof value !== "object") return false;
+	const state = Reflect.get(value, "state");
+	if (state === "ready") return typeof Reflect.get(value, "key") === "string";
+	return state === "unavailable" && typeof Reflect.get(value, "reason") === "string";
+}
+/** Register the loaded (or unloadable) key. Called by the hub's `local-auth`. */
+function setProcessJwtSigningKey(state) {
+	Reflect.set(globalThis, SLOT, state);
+}
+function getProcessJwtSigningKeyState() {
+	const value = Reflect.get(globalThis, SLOT);
+	return isState(value) ? value : NOT_LOADED;
+}
+/** The process slot — the default source of every `AuthManager`. */
+var processJwtSigningKey = { current() {
+	const state = getProcessJwtSigningKeyState();
+	if (state.state === "ready") return state.key;
+	throw new JwtSigningKeyUnavailableError(state.reason);
+} };
+/** A fixed key — tests, and nothing else. */
+function staticJwtSigningKey(key) {
+	return { current: () => key };
+}
+/** 32 random bytes, hex. */
+function generateJwtSigningKey() {
+	return randomBytes(32).toString("hex");
+}
+/**
+* Read the key from the keychain; generate and store one ONLY when the
+* keychain answers that none exists. Never throws.
+*/
+async function loadJwtSigningKey(deps) {
+	let entry;
+	try {
+		entry = (await deps.secrets.resolve([JWT_SIGNING_KEY_REF]))[JWT_SIGNING_KEY_REF];
+	} catch (err) {
+		return {
+			state: "unavailable",
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+	if (entry === void 0) return {
+		state: "unavailable",
+		reason: "no-answer"
+	};
+	switch (entry.kind) {
+		case "value": return {
+			state: "ready",
+			key: entry.value
+		};
+		case "unavailable": return {
+			state: "unavailable",
+			reason: entry.reason
+		};
+		case "forbidden": return {
+			state: "unavailable",
+			reason: "forbidden"
+		};
+		case "missing": {
+			const key = (deps.generate ?? generateJwtSigningKey)();
+			try {
+				await deps.secrets.put(JWT_SIGNING_KEY_REF, key);
+			} catch (err) {
+				return {
+					state: "unavailable",
+					reason: `could not store a new key: ${err instanceof Error ? err.message : String(err)}`
+				};
+			}
+			return {
+				state: "ready",
+				key
+			};
+		}
+	}
+}
+//#endregion
+export { loadJwtSigningKey as a, staticJwtSigningKey as c, getProcessJwtSigningKeyState as i, JwtSigningKeyUnavailableError as n, processJwtSigningKey as o, SYSTEM_SECRET_OWNER as r, setProcessJwtSigningKey as s, JWT_SIGNING_KEY_REF as t };

package/dist/kernel/config-manager.d.ts

@@ -82,7 +82,7 @@ export declare class ConfigManager {
      * implementation (sqlite, redis, in-memory, …) behaves identically here.
      *
      * D675: a bootstrap-owned section takes ONLY allow-listed keys from the
-     * store (a stored `auth.jwtSecret` never replaces env), and with only the
+     * store (a stale stored `auth.jwtSecret` never answers), and with only the
      * door wired this sync read THROWS — the settings view's `getSection` reads
      * the door.
      */

package/dist/kernel/config-schema.d.ts

@@ -1,11 +1,8 @@
 import { z } from 'zod';
 /** Default data directory — used when CAMSTACK_DATA env var is not set */
 export declare const DEFAULT_DATA_PATH = "camstack-data";
-/**
- * The admin password seeded on first boot when none is configured. A SEED
- * only: it never overwrites an existing account's password (`ensureAdminExists`).
- */
-export declare const DEFAULT_ADMIN_PASSWORD = "changeme";
+/** `auth.*` keys a pre-D797 config.yaml may still carry; ignored, and warned about. */
+export declare const RETIRED_AUTH_CONFIG_KEYS: readonly ["jwtSecret", "adminUsername", "adminPassword"];
 /** Bootstrap config -- loaded from config.yaml ONLY at startup.
  *  All other settings live in SQL (system_settings table). */
 export declare const bootstrapSchema: z.ZodObject<{
@@ -19,11 +16,7 @@ export declare const bootstrapSchema: z.ZodObject<{
         dataPath: z.ZodDefault<z.ZodString>;
         corsOrigins: z.ZodDefault<z.ZodPreprocess<z.ZodArray<z.ZodString>>>;
     }, z.core.$strip>>;
-    auth: z.ZodDefault<z.ZodObject<{
-        jwtSecret: z.ZodDefault<z.ZodNullable<z.ZodString>>;
-        adminUsername: z.ZodDefault<z.ZodString>;
-        adminPassword: z.ZodDefault<z.ZodString>;
-    }, z.core.$strip>>;
+    auth: z.ZodDefault<z.ZodObject<{}, z.core.$strip>>;
     hub: z.ZodDefault<z.ZodObject<{
         url: z.ZodDefault<z.ZodString>;
         token: z.ZodDefault<z.ZodString>;
@@ -38,8 +31,8 @@ export declare const bootstrapSchema: z.ZodObject<{
     bootstrap: z.ZodDefault<z.ZodObject<{
         settingsStoreAddon: z.ZodDefault<z.ZodString>;
         installSource: z.ZodOptional<z.ZodEnum<{
-            npm: "npm";
             local: "local";
+            npm: "npm";
             symlink: "symlink";
         }>>;
         requiredAddons: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/kernel/index.d.ts

@@ -52,7 +52,8 @@ export { HubNodeRegistry } from './moleculer/node-registry.js';
 export type { CallFn, NodeRootPackageInfo, RegisteredAddonManifest, RegisteredNativeCap, RegisterNodeParams, RegisterNodeResult, NodeCapEntry, NodeNativeCapEntry, } from './moleculer/node-registry.js';
 export { callRegisterNodeWithRetry, buildNodeManifest } from './moleculer/register-node-client.js';
 export type { RegisterNodeBroker, CallRegisterNodeOptions, } from './moleculer/register-node-client.js';
-export { hashClusterSecret, clusterSecretMatches, isClusterSecretMismatchError, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, } from './moleculer/cluster-secret.js';
+export { hashClusterSecret, clusterSecretMatches, isClusterSecretMismatchError, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CLUSTER_SECRET_REF, CLUSTER_SECRET_SETTINGS_KEY, CLUSTER_SECRET_UNAVAILABLE_TYPE, checkClusterSecret, getProcessClusterSecretGate, setProcessClusterSecretGate, } from './moleculer/cluster-secret.js';
+export type { ClusterSecretGate, ClusterSecretVerdict } from './moleculer/cluster-secret.js';
 export { serializeTypedArrays } from './moleculer/typed-array-serde.js';
 export { createReadinessService, createReadinessServiceForRegistry, AGENT_READINESS_SERVICE_NAME, } from './moleculer/readiness-service.js';
 export type { ReadinessServiceDeps } from './moleculer/readiness-service.js';

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

@@ -4,8 +4,6 @@ interface BrokerConfig {
     readonly mode: 'hub' | 'agent' | 'test';
     readonly hubAddress?: string;
     readonly logLevel?: string;
-    /** Shared secret — used as Moleculer namespace to isolate the cluster on the network */
-    readonly secret?: string;
     /**
      * TCP port the hub listens on for cluster traffic.
      * Agents need a deterministic port to connect via `urls: 'hub@host:port'`

package/dist/kernel/moleculer/cluster-secret.d.ts

@@ -1,3 +1,7 @@
+/** The keychain ref of the hub's cluster secret: `secret://system/global/clusterSecret`. */
+export declare const CLUSTER_SECRET_REF: string;
+/** The `system-settings` key whose value is the cluster secret's keychain marker. */
+export declare const CLUSTER_SECRET_SETTINGS_KEY = "cluster.clusterSecret";
 /** Moleculer error `type` marking a registration rejected for a bad cluster secret. */
 export declare const CLUSTER_SECRET_MISMATCH_TYPE = "CLUSTER_SECRET_MISMATCH";
 /** Process exit code a runner uses when its registration is rejected for a bad secret. */
@@ -13,3 +17,30 @@ export declare function hashClusterSecret(secret: string): string;
 export declare function clusterSecretMatches(expectedHash: string | undefined, presentedHash: string | undefined): boolean;
 /** Recognises a cluster-secret rejection, including after a Moleculer RPC round-trip. */
 export declare function isClusterSecretMismatchError(err: unknown): boolean;
+/** Moleculer error `type` of a registration refused because the hub cannot read its own secret yet. */
+export declare const CLUSTER_SECRET_UNAVAILABLE_TYPE = "CLUSTER_SECRET_UNAVAILABLE";
+/**
+ * What the hub knows about its own cluster secret:
+ *  - `off`: none is set — every node may register (the behaviour of a hub
+ *    that never had a secret);
+ *  - `on`: set — a node must present the matching hash;
+ *  - `unknown`: one is set (the marker exists) but the keychain cannot answer
+ *    yet — registrations are refused with a RETRYABLE error until it does.
+ *    Fail closed: a locked keychain never opens the gate.
+ */
+export type ClusterSecretGate = {
+    readonly kind: 'off';
+} | {
+    readonly kind: 'on';
+    readonly hash: string;
+} | {
+    readonly kind: 'unknown';
+    readonly reason: string;
+};
+export type ClusterSecretVerdict = 'allow' | 'mismatch' | 'unavailable';
+export declare function checkClusterSecret(gate: ClusterSecretGate, presentedHash: string | undefined): ClusterSecretVerdict;
+/** Register the hub's gate. Called by `system-config`, which owns the field. */
+export declare function setProcessClusterSecretGate(gate: ClusterSecretGate): void;
+export declare function clearProcessClusterSecretGate(): void;
+/** The hub's gate; `unknown` until `system-config` loaded it. */
+export declare function getProcessClusterSecretGate(): ClusterSecretGate;

package/dist/kernel/moleculer/hub-service.d.ts

@@ -1,6 +1,7 @@
 import { ServiceSchema } from 'moleculer';
 import { LogTags } from '@camstack/types';
 import { RegisterNodeParams } from './node-registry.js';
+import { ClusterSecretGate } from './cluster-secret.js';
 interface HubServiceDeps {
     readonly getAddonConfig: (addonId: string) => unknown;
     readonly getSettings: (scope: string, key?: string) => unknown;
@@ -24,11 +25,13 @@ interface HubServiceDeps {
     /** Explicit deregistration (graceful shutdown). `$node.disconnected` covers crashes. */
     readonly onUnregisterNode?: (nodeId: string) => void;
     /**
-     * SHA-256 hash of the hub's own `CAMSTACK_CLUSTER_SECRET`, or `undefined`
-     * when no secret is configured. When set, `$hub.registerNode` rejects any
-     * node not presenting a matching `clusterSecretHash`. (Cluster-secret gate.)
+     * The hub's cluster-secret gate, read on EVERY registration (the secret
+     * lives in the keychain and may be set or changed at runtime — D797):
+     * `off` lets every node in, `on` requires the matching `clusterSecretHash`,
+     * `unknown` (the keychain cannot answer yet) refuses with a retryable error.
+     * Absent → `off` (test brokers); the hub always passes the keychain's gate.
      */
-    readonly expectedClusterSecretHash?: string;
+    readonly clusterSecretGate?: () => ClusterSecretGate;
 }
 declare function createHubService(deps: HubServiceDeps): ServiceSchema;
 export { createHubService };

package/dist/kernel/moleculer/node-registry.d.ts

@@ -56,7 +56,7 @@ interface RegisterNodeParams {
      */
     readonly nativeCaps?: readonly RegisteredNativeCap[];
     /**
-     * SHA-256 hash of the node's `CAMSTACK_CLUSTER_SECRET`. Optional — absent
+     * SHA-256 hash of the node's cluster secret. Optional — absent
      * when the node has no secret configured. Verified by the `registerNode`
      * receiver; never carries the raw secret. (Cluster-secret registration gate.)
      */

package/dist/kernel/system-settings-policy.d.ts

@@ -2,16 +2,14 @@
  * Which `system-settings` keys the STORE may answer, and which the kernel
  * loads from the door into memory at boot — D675.
  *
- * ## The store never outranks env + config.yaml for a bootstrap section
+ * ## The store never answers for a bootstrap section
  *
- * `system-settings` holds, among other things, `auth.jwtSecret`,
- * `auth.adminUsername` and `auth.adminPassword` — written there by
- * `local-auth` (and by older builds) next to `auth.tokenExpiry`. The live
- * container supplies the same three from env (`CAMSTACK_JWT_SECRET`,
- * `CAMSTACK_ADMIN_USER`, `CAMSTACK_ADMIN_PASS`). While the store layer was
- * skipped (every read since D231) env won by accident. Merging the store back
- * in "highest priority" would let a stale DB copy replace the JWT secret —
- * invalidating every token — and change the login password.
+ * `system-settings` may still hold `auth.jwtSecret`, `auth.adminUsername` and
+ * `auth.adminPassword` — written there by `local-auth` (and by older builds)
+ * next to `auth.tokenExpiry`. Since D797 none of the three is a setting at
+ * all (the signing key is the keychain's, the first-boot admin is fixed), and
+ * the stale rows must still never answer: merging them back in would let a
+ * stale DB copy stand in for a credential. The one-off ops script deletes them.
  *
  * So a bootstrap-owned section is answered from env + config.yaml ONLY, and
  * the store may add exactly the keys in {@link STORE_READABLE_BOOTSTRAP_KEYS}:

package/dist/{retired-settings-keys-BAcfvFtm.mjs → retired-settings-keys-DlZ3VV6x.mjs}

@@ -1,4 +1,4 @@
-import { _r as asJsonObject } from "./dist-Bvl5JgNt.mjs";
+import { _r as asJsonObject } from "./dist-B9oFw2jh.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/{retired-settings-keys-gTsZfpmP.js → retired-settings-keys-YOOKLA3v.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.378",
+  "version": "1.2.380",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",
@@ -38,6 +38,8 @@
         "id": "filesystem-storage",
         "category": "system",
         "name": "Filesystem Storage",
+        "icon": "assets/filesystem-storage/icon.svg",
+        "color": "#0d9488",
         "entry": "./dist/builtins/sqlite-storage/filesystem-storage.addon.js",
         "capabilities": [
           {
@@ -52,6 +54,8 @@
         "id": "sqlite-settings",
         "category": "system",
         "name": "SQLite Settings",
+        "icon": "assets/sqlite-settings/icon.svg",
+        "color": "#0d9488",
         "entry": "./dist/builtins/sqlite-storage/sqlite-settings.addon.js",
         "description": "The relational ENGINE behind the data door (SQLite WAL). Registers `data-store-provider`, an internal collection cap; the public `settings-store` door is owned by `storage-orchestrator`, which dispatches here. Callers never reach this addon directly — that is what makes the engine replaceable. It ALSO registers `vector-store` (sqlite-vec) from the same database file and the same open handle, and `database-snapshot`: the verified copy of its database that the nightly backup archives in place of the live files, written by this runner on a thread over its own connection. Runs in its OWN process (`execution.isolate`) — `better-sqlite3` `Statement.run` does not belong on the event loop that serves the API.",
         "execution": {
@@ -75,6 +79,8 @@
         "id": "winston-logging",
         "category": "system",
         "name": "Winston Logging",
+        "icon": "assets/winston-logging/icon.svg",
+        "color": "#64748b",
         "entry": "./dist/builtins/winston-logging/index.js",
         "capabilities": [
           {
@@ -86,6 +92,8 @@
         "id": "console-logging",
         "category": "system",
         "name": "Console Logging",
+        "icon": "assets/console-logging/icon.svg",
+        "color": "#64748b",
         "entry": "./dist/builtins/console-logging/index.js",
         "capabilities": [
           {
@@ -97,6 +105,8 @@
         "id": "loki-logging",
         "category": "system",
         "name": "Loki Logging",
+        "icon": "assets/loki-logging/icon.svg",
+        "color": "#64748b",
         "description": "Opt-in log destination — batches this node's log entries and pushes them to a Grafana Loki instance via /loki/api/v1/push. Registered always, inert until enabled with a URL.",
         "entry": "./dist/builtins/loki-logging/index.js",
         "capabilities": [
@@ -109,6 +119,8 @@
         "id": "hub-forwarder",
         "category": "system",
         "name": "Hub Log Forwarder",
+        "icon": "assets/hub-forwarder/icon.svg",
+        "color": "#64748b",
         "description": "Agent-only log destination — forwards every log entry to the hub via the cluster broker. Never runs on the hub itself (the hub already owns the log-receiver, registering hub-forwarder there would create a write→ingest→write feedback loop).",
         "entry": "./dist/builtins/hub-forwarder/index.js",
         "execution": {
@@ -124,6 +136,8 @@
         "id": "backup-orchestrator",
         "category": "system",
         "name": "Backup Orchestrator",
+        "icon": "assets/backup-orchestrator/icon.svg",
+        "color": "#0d9488",
         "description": "System singleton that owns the schedule, builds the archive once, and fans it out to every enabled `backup-destination` provider (local, S3, rsync, …). In-process on hub root — aggregator over a cluster collection, no native deps.",
         "entry": "./dist/builtins/backup-orchestrator/index.js",
         "protected": true,
@@ -147,6 +161,8 @@
         "id": "storage-orchestrator",
         "category": "system",
         "name": "Storage Orchestrator",
+        "icon": "assets/storage-orchestrator/icon.svg",
+        "color": "#0d9488",
         "description": "The single data door. Owns the consumer-facing `storage` cap for bytes — the `locationId → StorageLocation` map, `StorageLocationRef` resolution, dispatch to the matching `storage-provider` registrant (`filesystem-storage` today; SFTP / S3 / WebDAV plug in alongside) — AND the `settings-store` cap for rows, dispatching to the `data-store-provider` engine (`sqlite-settings` today; a vector engine plugs in alongside). Nothing reaches an engine except through this addon.",
         "entry": "./dist/builtins/storage-orchestrator/index.js",
         "protected": true,
@@ -166,6 +182,8 @@
         "id": "keychain",
         "category": "system",
         "name": "Keychain",
+        "icon": "assets/keychain/icon.svg",
+        "color": "#0d9488",
         "description": "Hub-only store of every secret value. Settings blobs hold a marker; the value lives here, AES-256-GCM under a data key wrapped by a master key whose location is configuration (config.yaml `keychain.keyFile`, the desktop OS keychain, else the data-dir default). Registers `keychain` (internal, owner-checked against the transport-stamped caller) and `keychain-admin` (System → Secrets). Boots in the infrastructure pass, right after the settings door.",
         "entry": "./dist/builtins/keychain/index.js",
         "protected": true,
@@ -182,6 +200,8 @@
         "id": "metrics-native",
         "category": "system",
         "name": "Native Metrics",
+        "icon": "assets/metrics-native/icon.svg",
+        "color": "#d97706",
         "entry": "./dist/builtins/native-metrics/native-metrics.addon.js",
         "capabilities": [
           {
@@ -193,6 +213,8 @@
         "id": "snapshot",
         "category": "system",
         "name": "Snapshot",
+        "icon": "assets/snapshot/icon.svg",
+        "color": "#7c3aed",
         "description": "Owns every camera's latest frame: the capture ladder (vendor native → ffmpeg keyframe grab off the stream-broker restream), the sharp resize, the courtesy frame for a camera that cannot answer, and the two HTTP planes the clients actually fetch bytes from. Runs in its OWN process (`execution.isolate`) — capture, transcode and byte caches do not belong on the event loop that serves the API.",
         "entry": "./dist/builtins/snapshot/index.js",
         "execution": {
@@ -210,6 +232,8 @@
         "id": "autotrack",
         "category": "system",
         "name": "PTZ Autotrack (emulated)",
+        "icon": "assets/autotrack/icon.svg",
+        "color": "#7c3aed",
         "description": "Wrapper over the `ptz-autotrack` cap — follows a subject with self-terminating `ptz.move` pulses on cameras whose firmware has no autotrack, driven by the detection pipeline's tracked boxes. The operator binds it per camera, then uses the SAME autotrack switch a native camera has: the binding chooses the implementation, never a second toggle. It refuses to move without a readable `moveImpulseMs`, and while a firmware autotrack on the same camera reports armed. Runs IN-PROCESS: it spawns nothing, carries no frames and issues a command every few seconds at most.",
         "entry": "./dist/builtins/autotrack/index.js",
         "capabilities": [
@@ -222,6 +246,8 @@
         "id": "alert-center",
         "category": "system",
         "name": "Alert Center",
+        "icon": "assets/alert-center/icon.svg",
+        "color": "#d97706",
         "entry": "./dist/builtins/alerts/index.js",
         "capabilities": [
           {
@@ -233,6 +259,8 @@
         "id": "liveness-monitor",
         "category": "system",
         "name": "Liveness Monitor",
+        "icon": "assets/liveness-monitor/icon.svg",
+        "color": "#d97706",
         "description": "Asserts that this node is actually working — it has devices, its cameras are online, and a camera that was recording has not silently stopped. Raises one persistent alert per fault and dismisses it on recovery. Exists because the hub once ran four hours with no devices and no recordings while every surface stayed quiet.",
         "entry": "./dist/builtins/liveness-monitor/index.js",
         "protected": true,
@@ -242,6 +270,8 @@
         "id": "system-config",
         "category": "system",
         "name": "System Config",
+        "icon": "assets/system-config/icon.svg",
+        "color": "#4f46e5",
         "description": "Exposes the cluster-wide yml-backed configuration sections (server, auth) via the three-level settings API. Hub-only.",
         "entry": "./dist/builtins/system-config/index.js",
         "protected": true
@@ -250,6 +280,8 @@
         "id": "calendars",
         "category": "system",
         "name": "Calendars",
+        "icon": "assets/calendars/icon.svg",
+        "color": "#4f46e5",
         "description": "Hub-only singleton that aggregates `calendar-source` providers (Home Assistant and future addon sources) and exposes listCalendars / listEvents / importFromHomeAssistant.",
         "entry": "./dist/builtins/calendars/index.js",
         "protected": true,
@@ -263,6 +295,8 @@
         "id": "addon-pages-aggregator",
         "category": "system",
         "name": "Addon Pages Aggregator",
+        "icon": "assets/addon-pages-aggregator/icon.svg",
+        "color": "#4f46e5",
         "description": "Hub-only singleton that aggregates `addon-pages-source` (collection) providers and emits the public `addon-pages.listPages` surface with versioned bundleUrls.",
         "entry": "./dist/builtins/addon-pages-aggregator/index.js",
         "protected": true,
@@ -276,6 +310,8 @@
         "id": "addon-widgets-aggregator",
         "category": "system",
         "name": "Addon Widgets Aggregator",
+        "icon": "assets/addon-widgets-aggregator/icon.svg",
+        "color": "#4f46e5",
         "description": "Hub-only singleton that aggregates `addon-widgets-source` (collection) providers and emits the public `addon-widgets.listWidgets` surface with versioned bundleUrls.",
         "entry": "./dist/builtins/addon-widgets-aggregator/index.js",
         "protected": true,
@@ -289,6 +325,8 @@
         "id": "device-manager",
         "category": "system",
         "name": "Device Manager",
+        "icon": "assets/device-manager/icon.svg",
+        "color": "#4f46e5",
         "description": "Hub-side singleton that unifies device persistence and management. Uses ctx.settings for storage — no direct SQLite access. Replaces device-persistence cap (Phase 2 will delete device-persistence once all consumers are migrated).",
         "entry": "./dist/builtins/device-manager/index.js",
         "protected": true,
@@ -308,6 +346,8 @@
         "id": "local-auth",
         "category": "system",
         "name": "Local Auth",
+        "icon": "assets/local-auth/icon.svg",
+        "color": "#e11d48",
         "description": "Built-in local username/password authentication. Implements the auth-provider capability as the default login path. OIDC and other providers can register alongside via the same capability.",
         "entry": "./dist/builtins/local-auth/index.js",
         "protected": true,
@@ -324,6 +364,8 @@
         "id": "platform-probe",
         "category": "system",
         "name": "Platform Probe (Native)",
+        "icon": "assets/platform-probe/icon.svg",
+        "color": "#d97706",
         "description": "Probes hardware and inference runtimes on the local node. Registers the `platform-probe` capability consumed by every inference addon on this node.",
         "entry": "./dist/builtins/platform-probe/index.js",
         "protected": true,
@@ -340,6 +382,8 @@
         "id": "local-network",
         "category": "system",
         "name": "Local Network",
+        "icon": "assets/local-network/icon.svg",
+        "color": "#2563eb",
         "description": "Enumerates the hub's network interfaces, classifies them (LAN / Wi-Fi / Docker / VPN / loopback), and ranks connection-endpoints for SDK clients. Hub-only — agents are not directly addressable.",
         "entry": "./dist/builtins/local-network/index.js",
         "protected": true,
@@ -353,6 +397,8 @@
         "id": "remote-access-orchestrator",
         "category": "system",
         "name": "Remote Access Orchestrator",
+        "icon": "assets/remote-access-orchestrator/icon.svg",
+        "color": "#2563eb",
         "description": "Hub-only singleton facade over the network-access collection (Cloudflare Tunnel, ngrok, …). Surfaces a unified provider list to the admin UI's Remote Access page.",
         "entry": "./dist/builtins/remote-access-orchestrator/index.js",
         "protected": true,
@@ -366,6 +412,8 @@
         "id": "core-blocks",
         "category": "system",
         "name": "Core Blocks",
+        "icon": "assets/core-blocks/icon.svg",
+        "color": "#ea580c",
         "description": "Store and type-check user-authored TypeScript that owns devices with an addon's own ctx. Admin-only: a block is a plugin with no review step, so it is process-isolated when it runs. This slice stores and serves; execution is the runner.",
         "entry": "./dist/builtins/core-blocks/index.js",
         "protected": true,
@@ -379,6 +427,8 @@
         "id": "composer",
         "category": "system",
         "name": "Composer",
+        "icon": "assets/composer/icon.svg",
+        "color": "#ea580c",
         "description": "Runs every DECLARATIVE composition (a core block whose source is `composition`): declares the composed device under the shared Blocks integration, registers its caps natively, and derives each field from other devices' state by `from` / expression — event-driven, no polling. Hub-only. Runs in its OWN runner (`execution.isolate` + `group: composer`): frame-free and low-crash, grouped with no device provider or data plane.",
         "entry": "./dist/builtins/composer/index.js",
         "protected": true,
@@ -398,9 +448,10 @@
         "id": "camera-grid",
         "category": "system",
         "name": "Camera Grids",
+        "icon": "assets/camera-grid/icon.svg",
+        "color": "#7c3aed",
         "description": "Composite cameras: several cameras composed into one fixed picture and emitted as an ordinary camera — recorded, played back and bound like any other. The composition runs only while something is consuming it; object detection is switched off on a new grid because the cameras it is composed from are already analysed. Runs in its OWN process (`execution.isolate`): it spawns an ffmpeg per live composition and relays its bytes, and neither belongs on the event loop that serves the API.",
         "entry": "./dist/builtins/camera-grid/index.js",
-        "color": "#7c3aed",
         "instanceMode": "unique",
         "execution": {
           "isolate": true,
@@ -419,7 +470,8 @@
     ]
   },
   "files": [
-    "dist"
+    "dist",
+    "assets"
   ],
   "scripts": {
     "copy:hook": "node -e \"const fs=require('fs'),p=require('path');const dst=p.join('dist');fs.mkdirSync(dst,{recursive:true});fs.copyFileSync(p.join('src','kernel','moleculer','framework-resolver-hook.mjs'),p.join(dst,'framework-resolver-hook.mjs'));console.log('copied framework-resolver-hook.mjs ->',dst)\"",