@camstack/server 1.1.76 → 1.2.0

package/dist/agent/agent-cap-dispatch-service.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Slice-5, Task 6 — agent-side Moleculer service for forwarding hub-dispatched
+ * cap calls to the agent's forked UDS children.
+ *
+ * The hub's `CapRouteResolver` dispatches an `agent-child-forward` route by
+ * calling `callWithServiceDiscovery(broker, AGENT_CAP_FWD_SERVICE,
+ * AGENT_CAP_FWD_ACTION, params, { nodeID: agentNodeId })`. This service
+ * receives those calls, resolves the child locally via the agent's
+ * `LocalChildRegistry`, and forwards the call over UDS.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentCapDispatchService = createAgentCapDispatchService;
+const system_1 = require("@camstack/system");
+// ---------------------------------------------------------------------------
+// ctx.params narrowing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Moleculer types `ctx.params` loosely; narrow it to `AgentCapForwardParams`
+ * by checking the required string fields without unsafe casts.
+ */
+function narrowParams(raw) {
+    if (raw === null || typeof raw !== 'object') {
+        throw new Error('$agent-cap-fwd.forward: invalid params — capName and method are required strings');
+    }
+    const capName = Reflect.get(raw, 'capName');
+    const method = Reflect.get(raw, 'method');
+    if (typeof capName !== 'string' || typeof method !== 'string') {
+        throw new Error('$agent-cap-fwd.forward: invalid params — capName and method are required strings');
+    }
+    const childId = Reflect.get(raw, 'childId');
+    const deviceId = Reflect.get(raw, 'deviceId');
+    return {
+        capName,
+        method,
+        args: Reflect.get(raw, 'args'),
+        childId: typeof childId === 'string' ? childId : undefined,
+        deviceId: typeof deviceId === 'number' ? deviceId : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates the Moleculer `ServiceSchema` for the agent-side cap-dispatch service.
+ *
+ * @param agentNodeId        The Moleculer nodeId of this agent (used in error messages).
+ * @param agentUdsRegistry   The agent's `LocalChildRegistry` (or a compatible spy in tests).
+ *                           `LocalChildRegistry` structurally satisfies `HubLocalChildDispatcher`.
+ * @param inProcessLookup    Optional resolver for caps hosted in the agent's OWN main process
+ *                           (core addons such as `platform-probe`, `metrics-provider` register
+ *                           their singleton providers in the agent's `CapabilityRegistry`, NOT
+ *                           as forked UDS children). Consulted ONLY when no UDS child provides
+ *                           the cap. Without it, agent in-process core caps are unroutable from
+ *                           the hub.
+ * @param logger             Optional scoped logger; logs the no-provider path at INFO level.
+ */
+function createAgentCapDispatchService(agentNodeId, agentUdsRegistry, inProcessLookup, logger) {
+    return {
+        name: system_1.AGENT_CAP_FWD_SERVICE,
+        actions: {
+            forward: {
+                handler: async (ctx) => {
+                    const params = narrowParams(ctx.params);
+                    const { capName, method, args, deviceId } = params;
+                    // Resolve the child: prefer the explicitly-provided childId (hub may
+                    // know it from its HubNodeRegistry), otherwise resolve locally.
+                    const childId = params.childId !== undefined
+                        ? params.childId
+                        : agentUdsRegistry.resolveChildId(capName, deviceId);
+                    if (childId == null) {
+                        // No forked UDS child owns this cap. It may instead be hosted by a
+                        // core addon running in the agent's OWN main process (platform-probe,
+                        // metrics-provider, …) — resolve it against the in-process registry.
+                        const ref = inProcessLookup?.(capName) ?? null;
+                        if (ref !== null) {
+                            return ref.invoke(method, args);
+                        }
+                        logger?.info(`agent ${agentNodeId}: no provider for cap "${capName}"${deviceId !== undefined ? ` (deviceId ${deviceId})` : ''}`);
+                        throw new Error(`agent ${agentNodeId} has no provider for cap "${capName}"${deviceId !== undefined ? ` (deviceId ${deviceId})` : ''}`);
+                    }
+                    const input = {
+                        capName,
+                        method,
+                        args,
+                        ...(deviceId !== undefined ? { deviceId } : {}),
+                    };
+                    return agentUdsRegistry.callCapOnChild(childId, input);
+                },
+            },
+        },
+    };
+}

package/dist/agent/agent-config.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAgentConfig = loadAgentConfig;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const crypto = __importStar(require("node:crypto"));
+const os = __importStar(require("node:os"));
+/**
+ * Generate a stable nodeId and persist it to the config file.
+ *
+ * Resolution order (first match wins, persisted on first boot):
+ *   1. Existing `nodeId` in the config file — survives env var changes
+ *      and host renames once seeded.
+ *   2. `CAMSTACK_NODE_ID` env var on first boot — lets dev workflows
+ *      pin a stable, human-readable nodeId (e.g. `dev-agent-0`)
+ *      without clobbering already-persisted random ids.
+ *   3. A fresh random hex (`agent-a1b2c3`) — production fallback when
+ *      no env var is set.
+ *
+ * Seeded values get written to the config file so subsequent boots
+ * round-trip exactly the same identity (Moleculer nodeID, capability
+ * routing, persisted agentSettings — all keyed by this string).
+ */
+function ensurePersistedNodeId(configPath, dataDir) {
+    const resolvedPath = path.resolve(dataDir, configPath);
+    let raw = {};
+    if (fs.existsSync(resolvedPath)) {
+        try {
+            raw = JSON.parse(fs.readFileSync(resolvedPath, 'utf-8'));
+        }
+        catch {
+            /* corrupt file */
+        }
+    }
+    if (typeof raw.nodeId === 'string' && raw.nodeId.length > 0) {
+        return raw.nodeId;
+    }
+    const envSeed = process.env.CAMSTACK_NODE_ID;
+    const id = envSeed && envSeed.length > 0 ? envSeed : `agent-${crypto.randomBytes(4).toString('hex')}`;
+    raw.nodeId = id;
+    try {
+        fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+        fs.writeFileSync(resolvedPath, JSON.stringify(raw, null, 2), 'utf-8');
+    }
+    catch {
+        /* best-effort */
+    }
+    return id;
+}
+function loadAgentConfig(configPath, dataDirOverride) {
+    const filePath = configPath ?? process.env.CAMSTACK_AGENT_CONFIG ?? 'agent.json';
+    const dataDir = dataDirOverride ?? process.env.CAMSTACK_DATA ?? './camstack-data';
+    const resolvedDataDir = path.resolve(dataDir);
+    // Name: config file takes priority over env (allows UI rename to stick).
+    // Env is the initial seed, config file is the persisted override.
+    const envName = process.env.CAMSTACK_NODE_ID ??
+        process.env.CAMSTACK_AGENT_NAME ??
+        `${os.hostname()}-${os.arch()}`;
+    // Environment variables for hub connection (optional — agent starts without)
+    const envHubAddress = process.env.CAMSTACK_HUB_ADDRESS || undefined;
+    const envSecret = process.env.CAMSTACK_CLUSTER_SECRET || undefined;
+    const configFullPath = path.resolve(resolvedDataDir, filePath);
+    const nodeId = ensurePersistedNodeId(filePath, resolvedDataDir);
+    // Read persisted config — these override env vars
+    let fileHubAddress;
+    let fileName;
+    let fileSecret;
+    if (fs.existsSync(configFullPath)) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(configFullPath, 'utf-8'));
+            fileHubAddress = typeof raw.hubAddress === 'string' ? raw.hubAddress : undefined;
+            fileName = typeof raw.name === 'string' ? raw.name : undefined;
+            fileSecret = typeof raw.secret === 'string' ? raw.secret : undefined;
+        }
+        catch {
+            /* corrupt config */
+        }
+    }
+    // Config file wins over env for all user-editable fields
+    const effectiveName = fileName ?? envName;
+    const effectiveHub = fileHubAddress ?? envHubAddress;
+    const effectiveSecret = fileSecret ?? envSecret;
+    return {
+        nodeId,
+        name: effectiveName,
+        hubAddress: effectiveHub,
+        dataDir: resolvedDataDir,
+        addonsDir: path.resolve(resolvedDataDir, 'addons'),
+        logLevel: process.env.CAMSTACK_LOG_LEVEL ?? 'info',
+        secret: effectiveSecret,
+        configPath: configFullPath,
+        statusPort: Number(process.env.CAMSTACK_STATUS_PORT) || 4444,
+    };
+}

package/dist/agent/agent-deploy-swap.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyDeployedBundle = applyDeployedBundle;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+/** Recursively remove a path, ignoring a missing target. */
+function rmrf(target) {
+    fs.rmSync(target, { recursive: true, force: true });
+}
+/**
+ * Move `from` → `to` atomically when on the same filesystem; fall back to a
+ * recursive copy + remove on a cross-device boundary (`EXDEV`). The agent's
+ * `/data` addonsDir is frequently a different filesystem from the OS temp dir,
+ * so a bare `renameSync` would throw `EXDEV` — the same fallback
+ * `AddonInstaller.applyUpdateFromStaged` uses.
+ */
+function moveDir(from, to) {
+    try {
+        fs.renameSync(from, to);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EXDEV') {
+            fs.cpSync(from, to, { recursive: true });
+            rmrf(from);
+        }
+        else {
+            throw err;
+        }
+    }
+}
+/**
+ * Atomically install a deployed addon bundle into `<addonsDir>/<addonId>`.
+ *
+ * Unlike the old `$agent.deploy` body (`rm` the live dir, THEN untar into it),
+ * this never leaves the live dir missing: extraction happens in a sibling temp
+ * dir first, the live dir is swapped in by rename, and any failure restores the
+ * previous copy. A killed/timed-out extract (the non-atomic-deploy hazard that
+ * a contaminated propagation test hit) leaves the old version fully intact.
+ *
+ * No `AddonInstaller` manifest dependency — works for any deployed addon,
+ * including ones never tracked in the agent's install manifest.
+ *
+ * @returns the live addon directory path (`<addonsDir>/<addonId>`).
+ */
+async function applyDeployedBundle(input) {
+    const { addonsDir, addonId, bundle, extract, logger } = input;
+    fs.mkdirSync(addonsDir, { recursive: true });
+    const liveDir = path.join(addonsDir, addonId);
+    // Place the temp + backup dirs as SIBLINGS of the live dir (same parent →
+    // same filesystem → atomic rename). Deriving them from the live dir's parent
+    // and basename keeps a scoped `addonId` like "@camstack/addon-pipeline" — whose
+    // slash would otherwise turn `.<addonId>.next` into a nested path — correct.
+    const liveParent = path.dirname(liveDir);
+    const liveBase = path.basename(liveDir);
+    fs.mkdirSync(liveParent, { recursive: true });
+    const token = (0, node_crypto_1.randomBytes)(6).toString('hex');
+    const nextDir = path.join(liveParent, `.${liveBase}.next.${token}`);
+    const backupDir = path.join(liveParent, `.${liveBase}.backup.${token}`);
+    // 1. Extract into a temp dir. If extraction throws (e.g. a killed untar),
+    //    drop the temp dir and rethrow — the live dir is never touched.
+    fs.mkdirSync(nextDir, { recursive: true });
+    try {
+        await extract(bundle, nextDir);
+    }
+    catch (err) {
+        rmrf(nextDir);
+        throw err;
+    }
+    // 2. Swap. Back up the live dir (if present), then move next → live. On any
+    //    failure, restore the backup so the addon stays installed at the old
+    //    version.
+    const hadLive = fs.existsSync(liveDir);
+    if (hadLive) {
+        fs.renameSync(liveDir, backupDir);
+    }
+    try {
+        moveDir(nextDir, liveDir);
+    }
+    catch (swapErr) {
+        if (hadLive) {
+            try {
+                if (fs.existsSync(liveDir))
+                    rmrf(liveDir);
+                fs.renameSync(backupDir, liveDir);
+            }
+            catch (restoreErr) {
+                logger.error(`agent deploy swap: restore of "${addonId}" failed after a failed swap — manual recovery may be needed`, {
+                    meta: {
+                        backupDir,
+                        error: restoreErr instanceof Error ? restoreErr.message : String(restoreErr),
+                    },
+                });
+            }
+        }
+        rmrf(nextDir);
+        throw swapErr;
+    }
+    // 3. Success — drop the backup.
+    if (hadLive)
+        rmrf(backupDir);
+    return { addonDir: liveDir };
+}

package/dist/agent/agent-group-runner.js

@@ -0,0 +1,175 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPackageManifestAddons = readPackageManifestAddons;
+exports.isGroupRunnerAddon = isGroupRunnerAddon;
+exports.registerGroupRunnerProviders = registerGroupRunnerProviders;
+exports.ensureGroupRunner = ensureGroupRunner;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const types_1 = require("@camstack/types");
+/**
+ * Read a package's `camstack.addons[]` declarations directly from its
+ * package.json — WITHOUT importing the addon entry module.
+ *
+ * The reload path must NOT `import()` heavy native addon entries (node-av, the
+ * onnxruntime bridge, …) on the agent's MAIN thread: doing so blocks the event
+ * loop long enough that `$agent.status` stops answering and the hub drops the
+ * node from topology — and a hung import wedges `$agent.reload` outright (the
+ * reload-wedge). A group-runner addon only needs its declaration (id,
+ * capabilities, execution) to be (re)dispatched to a runner SUBPROCESS, which
+ * loads the real module itself. Returns null on a missing/corrupt manifest.
+ */
+function readPackageManifestAddons(dir) {
+    try {
+        const pkgPath = path.join(dir, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return null;
+        // Documented JSON boundary: the package.json shape is validated field-by-field below.
+        const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        const packageName = typeof raw.name === 'string' ? raw.name : '';
+        const packageVersion = typeof raw.version === 'string' ? raw.version : '0.0.0';
+        const entries = Array.isArray(raw.camstack?.addons) ? raw.camstack.addons : [];
+        const declarations = [];
+        for (const entry of entries) {
+            if (entry !== null &&
+                typeof entry === 'object' &&
+                typeof entry.id === 'string') {
+                // Boundary cast: validated to have a string `id`; the runtime helpers
+                // (isDeployableToAgent / resolveRunnerId) read only `execution` / `id`.
+                declarations.push(entry);
+            }
+        }
+        if (!packageName || declarations.length === 0)
+            return null;
+        return { packageName, packageVersion, declarations };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a deployed addon must run in a forked group runner (one addon = one
+ * process) rather than in-process. True when the addon declares an `execution`
+ * block with a placement reachable on an agent (`any-node`/`agent-only`).
+ *
+ * The default placement is `hub-only`, so a declaration without `execution`
+ * is hub-only and not a group-runner addon — and, being hub-only, is never
+ * deployable to an agent in the first place.
+ */
+function isGroupRunnerAddon(decl) {
+    return decl.execution !== undefined && (0, types_1.resolveAddonPlacement)(decl) !== 'hub-only';
+}
+/**
+ * Register the broker-call cap proxies + `loadedAddons` bookkeeping for a group
+ * of addons whose runner is (now) live. Extracted so the boot path
+ * (`loadClusterCapableAddons`) and the reload path (`ensureGroupRunner`) share
+ * ONE implementation — preventing the two from drifting (the original cause of
+ * the in-process-reload wedge).
+ */
+function registerGroupRunnerProviders(deps, addons) {
+    for (const a of addons) {
+        for (const cap of a.capabilities) {
+            const capName = typeof cap === 'string' ? cap : cap.name;
+            const proxy = new Proxy({}, {
+                get(_target, prop) {
+                    if (prop === 'then' || typeof prop === 'symbol')
+                        return undefined;
+                    return (params) => deps.broker.call(`${a.addonId}.${capName}.${prop}`, params);
+                },
+            });
+            // Idempotent (re)registration. The reload path (`ensureGroupRunner`)
+            // re-runs this after a `$process.restart` of the SUBPROCESS, but the
+            // agent's central registry still holds the proxy from the previous
+            // registration — the subprocess restart never touched it. Since
+            // `registerProvider` throws on a duplicate `(cap, addonId)` pair (a
+            // deliberate guard against a double `registerProvider` in one init
+            // path), drop the stale proxy first so the fresh one installs cleanly.
+            // On the boot path nothing is registered yet, so this is a no-op.
+            // Without this, an in-place addon update/redeploy leaves the whole group
+            // stuck in `error` until a full agent (main-process) restart clears the
+            // registry.
+            if (deps.capabilityRegistry.hasProvider(capName, a.addonId)) {
+                deps.capabilityRegistry.unregisterProvider(capName, a.addonId);
+            }
+            deps.capabilityRegistry.registerProvider(capName, a.addonId, proxy);
+        }
+        deps.loadedAddons.set(a.addonId, {
+            id: a.addonId,
+            status: 'running',
+            version: a.version,
+            packageName: a.packageName,
+            packageVersion: a.packageVersion,
+        });
+    }
+}
+/**
+ * Ensure a group runner is live with the CURRENT on-disk addon code, then wire
+ * its providers.
+ *
+ * A redeploy's runner is already running (the deploy step swapped its on-disk
+ * code but never killed the process), and `$process.spawnRunner` throws
+ * "already running" for a live runnerId. So restart first — `$process.restart`
+ * stops the old child, evicts it from the Moleculer registry, and re-spawns it
+ * from the same dir (now holding the new code) in a subprocess, off the agent's
+ * main event loop. Only when no runner exists yet (first deploy →
+ * `{success:false, reason:'not found'}`) do we `$process.spawnRunner`.
+ *
+ * On a hard failure of both paths the addons are marked `error` (no providers
+ * registered) so `$agent.status` reports the degraded state.
+ */
+async function ensureGroupRunner(deps, groupId, addons) {
+    try {
+        const restart = await deps.broker.call('$process.restart', { name: groupId });
+        if (!restart.success) {
+            if (restart.reason !== undefined && restart.reason !== 'not found') {
+                deps.logger.warn(`group "${groupId}" restart returned "${restart.reason}" — spawning a fresh runner`);
+            }
+            await deps.broker.call('$process.spawnRunner', {
+                runnerId: groupId,
+                addons: addons.map((a) => ({ addonId: a.addonId, addonDir: a.addonDir })),
+            });
+        }
+        registerGroupRunnerProviders(deps, addons);
+        deps.logger.info(`group "${groupId}" live with ${addons.length} addon(s): ${addons.map((a) => a.addonId).join(', ')}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? (err.stack ?? err.message) : String(err);
+        deps.logger.error(`failed to ensure group "${groupId}": ${msg}`);
+        for (const a of addons) {
+            deps.loadedAddons.set(a.addonId, { id: a.addonId, status: 'error' });
+        }
+    }
+}

package/dist/agent/agent-http-auth.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Agent HTTP auth — pure request-authorization helpers for the agent's
+ * port-4444 API (mirrors the hub's /health hardening).
+ *
+ * The surface was fully unauthenticated on 0.0.0.0 — including
+ * `POST /api/agent/config`, which can rewrite `hubAddress` and the
+ * cluster secret itself. Model:
+ *   - loopback callers (the Electron renderer, in-container probes) are
+ *     always allowed — the desktop app keeps working with zero changes,
+ *   - remote callers must present `Authorization: Bearer <cluster secret>`
+ *     — the secret is the agent↔hub trust anchor and the only credential
+ *     an agent can verify without a user database,
+ *   - an UNPAIRED agent (no secret configured yet) can be set up remotely
+ *     through the pairing surface only; everything else stays denied.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLoopbackAddress = isLoopbackAddress;
+exports.bearerMatchesSecret = bearerMatchesSecret;
+exports.isAuthorizedAgentRequest = isAuthorizedAgentRequest;
+exports.isPairingRequest = isPairingRequest;
+const node_crypto_1 = require("node:crypto");
+/** IPv4/IPv6 loopback (incl. the IPv4-mapped IPv6 form Node reports). */
+function isLoopbackAddress(addr) {
+    if (!addr)
+        return false;
+    if (addr === '::1')
+        return true;
+    const v4 = addr.startsWith('::ffff:') ? addr.slice('::ffff:'.length) : addr;
+    // 127.0.0.0/8 — every octet must be numeric so '127.evil.host' fails.
+    const parts = v4.split('.');
+    if (parts.length !== 4 || parts[0] !== '127')
+        return false;
+    return parts.every((p) => /^\d{1,3}$/.test(p));
+}
+/** Timing-safe `Authorization: Bearer <secret>` compare. Empty secrets never match. */
+function bearerMatchesSecret(authorization, secret) {
+    if (secret.length === 0)
+        return false;
+    if (!authorization?.startsWith('Bearer '))
+        return false;
+    const token = Buffer.from(authorization.slice('Bearer '.length));
+    const expected = Buffer.from(secret);
+    return token.length === expected.length && (0, node_crypto_1.timingSafeEqual)(token, expected);
+}
+/**
+ * True when the request may access the protected agent API. `clusterSecret`
+ * is the CURRENTLY configured secret (`null`/empty = unpaired agent — no
+ * remote credential can be verified, so remote access is denied except for
+ * the pairing surface, which the route layer allows via {@link isPairingRequest}).
+ */
+function isAuthorizedAgentRequest(input, clusterSecret) {
+    if (isLoopbackAddress(input.remoteAddress))
+        return true;
+    if (clusterSecret === null || clusterSecret.length === 0)
+        return false;
+    return bearerMatchesSecret(input.authorization, clusterSecret);
+}
+/**
+ * The first-boot pairing surface: what a remote browser needs to configure
+ * a factory-fresh agent (read status/config, write hub address + secret,
+ * trigger the reconnect). Process control and health details are NEVER
+ * part of it. Only consulted while the agent has no secret configured.
+ */
+function isPairingRequest(method, urlPath) {
+    const pathOnly = urlPath.split('?')[0] ?? urlPath;
+    if (method === 'GET') {
+        return (pathOnly === '/api/agent/status' ||
+            pathOnly === '/api/agent/config' ||
+            pathOnly === '/api/agent/discovered-nodes');
+    }
+    if (method === 'POST') {
+        return pathOnly === '/api/agent/config' || pathOnly === '/api/agent/restart';
+    }
+    return false;
+}