enpilink 1.0.2 → 1.0.4

package/dist/server/config/router.d.ts

@@ -1,23 +1,31 @@
 import { type Router } from "express";
 import type { StorageAdapter } from "../storage/types.js";
 /**
- * Config admin API (M4). Pure core — reads the SAME active
- * {@link StorageAdapter} the analytics middleware writes to, via
- * {@link getActiveStorage}. Does NOT depend on `@enpilink/console`.
+ * Config admin API. Pure core — reads the SAME active {@link StorageAdapter}
+ * the analytics middleware writes to, via {@link getActiveStorage}. Does NOT
+ * depend on `@enpilink/console`.
  *
- * Mounted dev-only (under the `NODE_ENV !== "production"` block in
- * `express.ts`) at `/__enpilink/config`. Prod admin mounting (behind bearer
- * auth) is M5.
+ * Mounted dev-only (unauth, localhost) and in the prod admin plane (behind
+ * bearer auth) at `/__enpilink/config`.
  *
  * Routes:
- * - `GET  /__enpilink/config`        — all settings (value-or-masked + source +
- *   secret/envLocked flags).
- * - `PUT  /__enpilink/config/:key`   — set a RUNTIME, non-secret key. Rejects
- *   bootstrap / secret / env-locked / unknown keys with a clear 4xx.
- * - `GET  /__enpilink/config/audit`  — recent config-change history.
+ * - `GET    /__enpilink/config`               — all settings (rich metadata +
+ *   source + secret/envLocked/modified/restartRequired flags).
+ * - `PUT    /__enpilink/config/:key`          — set a RUNTIME or RESTART-tier
+ *   key. Rejects secret / `admin` / env-locked / unknown keys with a clear 4xx.
+ * - `DELETE /__enpilink/config/:key`          — reset a key to its default
+ *   (clears the DB override). Same guardrails as PUT.
+ * - `GET    /__enpilink/config/presets`       — list presets + the values each
+ *   would set.
+ * - `POST   /__enpilink/config/preset/:name`  — apply a preset (validate +
+ *   persist + audit each runtime key; skip env-locked).
+ * - `GET    /__enpilink/config/audit`         — recent config-change history.
  *
- * Disabled-safe: when there is no active storage, reads fall back to env/file/
- * defaults (runtime keys show their defaults) and NEVER 500. Writes require a
- * storage adapter (409 when none) — there is nowhere to persist otherwise.
+ * Disabled-safe: with no active storage, reads fall back to env/file/defaults
+ * and NEVER 500. Writes require a storage adapter (409 when none).
+ *
+ * SECURITY: `admin`, `adminAuthToken`, unknown keys, and env-locked keys can
+ * NEVER be written here. `adminAuthToken` is never persisted nor returned in
+ * plaintext.
  */
 export declare function createConfigRouter(getStorage?: () => StorageAdapter | null): Router;

package/dist/server/config/router.js

@@ -1,26 +1,36 @@
 import express, {} from "express";
+import { refreshCaptureGate } from "../capture-gate.js";
 import { getActiveStorage } from "../log-sink.js";
-import { resolveConfig, validateRuntimeWrite } from "./resolve.js";
-import { isBootstrapKey, isKnownKey, isRuntimeKey, isSecretKey, } from "./schema.js";
+import { getPreset, PRESETS } from "./presets.js";
+import { resolveConfig, validateConfigWrite, } from "./resolve.js";
+import { isBootstrapKey, isKnownKey, isRestartKey, isRuntimeKey, isSecretKey, } from "./schema.js";
 /**
- * Config admin API (M4). Pure core — reads the SAME active
- * {@link StorageAdapter} the analytics middleware writes to, via
- * {@link getActiveStorage}. Does NOT depend on `@enpilink/console`.
+ * Config admin API. Pure core — reads the SAME active {@link StorageAdapter}
+ * the analytics middleware writes to, via {@link getActiveStorage}. Does NOT
+ * depend on `@enpilink/console`.
  *
- * Mounted dev-only (under the `NODE_ENV !== "production"` block in
- * `express.ts`) at `/__enpilink/config`. Prod admin mounting (behind bearer
- * auth) is M5.
+ * Mounted dev-only (unauth, localhost) and in the prod admin plane (behind
+ * bearer auth) at `/__enpilink/config`.
  *
  * Routes:
- * - `GET  /__enpilink/config`        — all settings (value-or-masked + source +
- *   secret/envLocked flags).
- * - `PUT  /__enpilink/config/:key`   — set a RUNTIME, non-secret key. Rejects
- *   bootstrap / secret / env-locked / unknown keys with a clear 4xx.
- * - `GET  /__enpilink/config/audit`  — recent config-change history.
+ * - `GET    /__enpilink/config`               — all settings (rich metadata +
+ *   source + secret/envLocked/modified/restartRequired flags).
+ * - `PUT    /__enpilink/config/:key`          — set a RUNTIME or RESTART-tier
+ *   key. Rejects secret / `admin` / env-locked / unknown keys with a clear 4xx.
+ * - `DELETE /__enpilink/config/:key`          — reset a key to its default
+ *   (clears the DB override). Same guardrails as PUT.
+ * - `GET    /__enpilink/config/presets`       — list presets + the values each
+ *   would set.
+ * - `POST   /__enpilink/config/preset/:name`  — apply a preset (validate +
+ *   persist + audit each runtime key; skip env-locked).
+ * - `GET    /__enpilink/config/audit`         — recent config-change history.
  *
- * Disabled-safe: when there is no active storage, reads fall back to env/file/
- * defaults (runtime keys show their defaults) and NEVER 500. Writes require a
- * storage adapter (409 when none) — there is nowhere to persist otherwise.
+ * Disabled-safe: with no active storage, reads fall back to env/file/defaults
+ * and NEVER 500. Writes require a storage adapter (409 when none).
+ *
+ * SECURITY: `admin`, `adminAuthToken`, unknown keys, and env-locked keys can
+ * NEVER be written here. `adminAuthToken` is never persisted nor returned in
+ * plaintext.
  */
 export function createConfigRouter(getStorage = getActiveStorage) {
     const router = express.Router();
@@ -32,11 +42,14 @@ export function createConfigRouter(getStorage = getActiveStorage) {
             res.json({ settings: resolved.settings });
         }
         catch {
-            // Last-resort: resolve with no storage so reads never fail.
             const resolved = await resolveConfig(null);
             res.json({ settings: resolved.settings });
         }
     });
+    // GET /config/presets — list presets + the values each would set.
+    router.get(`${base}/presets`, (_req, res) => {
+        res.json({ presets: Object.values(PRESETS) });
+    });
     // GET /config/audit — change history (most recent first). Never 500.
     router.get(`${base}/audit`, async (_req, res) => {
         const storage = getStorage();
@@ -52,65 +65,164 @@ export function createConfigRouter(getStorage = getActiveStorage) {
             res.json({ enabled: false, audit: [] });
         }
     });
-    // PUT /config/:key — set a runtime, non-secret key. Reject everything else.
-    router.put(`${base}/:key`, async (req, res) => {
-        const key = req.params.key;
-        if (!isKnownKey(key)) {
-            res.status(404).json({ error: `Unknown config key "${key}"` });
-            return;
-        }
-        if (isSecretKey(key)) {
-            res.status(403).json({
-                error: `"${key}" is a secret and is set via environment only`,
-            });
+    // POST /config/preset/:name — apply a runtime-only preset.
+    router.post(`${base}/preset/:name`, async (req, res) => {
+        const preset = getPreset(req.params.name);
+        if (!preset) {
+            res.status(404).json({ error: `Unknown preset "${req.params.name}"` });
             return;
         }
-        if (isBootstrapKey(key)) {
-            res.status(403).json({
-                error: `"${key}" is a bootstrap setting (env/file only) and is read-only here`,
+        const storage = getStorage();
+        if (!storage) {
+            res.status(409).json({
+                error: "No active storage; cannot apply preset",
             });
             return;
         }
-        if (!isRuntimeKey(key)) {
-            res.status(403).json({ error: `"${key}" is not editable` });
-            return;
+        const resolved = await resolveConfig(storage);
+        const byKey = new Map(resolved.settings.map((s) => [s.key, s]));
+        const actor = actorOf(req);
+        const applied = [];
+        const skipped = [];
+        for (const [key, value] of Object.entries(preset.values)) {
+            // Presets only ever touch runtime keys; double-check the guardrail.
+            if (!isRuntimeKey(key)) {
+                skipped.push({ key, reason: "not a runtime key" });
+                continue;
+            }
+            const setting = byKey.get(key);
+            if (setting?.envLocked) {
+                skipped.push({ key, reason: `pinned via ${setting.source}` });
+                continue;
+            }
+            const check = validateConfigWrite(key, value);
+            if (!check.ok) {
+                skipped.push({ key, reason: check.error });
+                continue;
+            }
+            try {
+                await storage.setConfig(key, check.value, actor);
+                applied.push({ key, value: check.value });
+            }
+            catch (err) {
+                skipped.push({
+                    key,
+                    reason: err instanceof Error ? err.message : "write failed",
+                });
+            }
         }
-        // Reject if this runtime key is currently pinned (env-locked) by env/file.
-        const resolved = await resolveConfig(getStorage());
-        const setting = resolved.settings.find((s) => s.key === key);
-        if (setting?.envLocked) {
-            res.status(409).json({
-                error: `"${key}" is pinned via ${setting.source} and cannot be changed here`,
-            });
+        // A preset may have changed analytics.enabled/sampleRate — refresh the live
+        // capture gate so it takes effect without a restart.
+        await refreshCaptureGate();
+        res.json({ ok: true, preset: preset.name, applied, skipped });
+    });
+    // PUT /config/:key — set a runtime or restart-tier key.
+    router.put(`${base}/:key`, async (req, res) => {
+        const guard = await writeGuard(req.params.key, getStorage);
+        if (!guard.ok) {
+            res.status(guard.status).json({ error: guard.error });
             return;
         }
+        const key = guard.key;
         const body = req.body;
-        const rawValue = body?.value;
-        const check = validateRuntimeWrite(key, rawValue);
+        const check = validateConfigWrite(key, body?.value);
         if (!check.ok) {
             res.status(400).json({ error: check.error });
             return;
         }
-        const storage = getStorage();
-        if (!storage) {
-            res.status(409).json({
-                error: "No active storage; cannot persist runtime config",
+        try {
+            await guard.storage.setConfig(key, check.value, actorOf(req));
+            // Refresh the live capture gate so a toggle of analytics.enabled /
+            // analytics.sampleRate takes effect immediately (no restart).
+            await refreshCaptureGate();
+            res.json({
+                ok: true,
+                key,
+                value: check.value,
+                restartRequired: isRestartKey(key),
+            });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Failed to write config",
             });
+        }
+    });
+    // DELETE /config/:key — reset to default (clear the DB override).
+    router.delete(`${base}/:key`, async (req, res) => {
+        const guard = await writeGuard(req.params.key, getStorage);
+        if (!guard.ok) {
+            res.status(guard.status).json({ error: guard.error });
             return;
         }
         try {
-            const actor = actorOf(req);
-            await storage.setConfig(key, check.value, actor);
-            res.json({ ok: true, key, value: check.value });
+            await guard.storage.clearConfig(guard.key, actorOf(req));
+            // Resetting analytics.enabled / sampleRate to default also re-gates
+            // capture live.
+            await refreshCaptureGate();
+            res.json({
+                ok: true,
+                key: guard.key,
+                reset: true,
+                restartRequired: isRestartKey(guard.key),
+            });
         }
         catch (err) {
             res.status(500).json({
-                error: err instanceof Error ? err.message : "Failed to write config",
+                error: err instanceof Error ? err.message : "Failed to reset config",
             });
         }
     });
     return router;
 }
+/**
+ * Shared guardrail for PUT + DELETE. Rejects unknown / secret / `admin` /
+ * env-locked keys and requires an active storage adapter. Only runtime and
+ * non-env-locked restart-tier keys pass.
+ */
+async function writeGuard(key, getStorage) {
+    if (!isKnownKey(key)) {
+        return { ok: false, status: 404, error: `Unknown config key "${key}"` };
+    }
+    if (isSecretKey(key)) {
+        return {
+            ok: false,
+            status: 403,
+            error: `"${key}" is a secret and is set via environment only`,
+        };
+    }
+    // Bootstrap keys are writable ONLY if they are restart-tier (port/storage/
+    // dbPath). `admin` (and any other bootstrap key) is env-only / read-only.
+    if (isBootstrapKey(key) && !isRestartKey(key)) {
+        return {
+            ok: false,
+            status: 403,
+            error: `"${key}" is environment-only and is read-only here`,
+        };
+    }
+    if (!isRuntimeKey(key) && !isRestartKey(key)) {
+        return { ok: false, status: 403, error: `"${key}" is not editable` };
+    }
+    // Reject if the key is currently pinned (env-locked) by env/file.
+    const resolved = await resolveConfig(getStorage());
+    const setting = resolved.settings.find((s) => s.key === key);
+    if (setting?.envLocked) {
+        return {
+            ok: false,
+            status: 409,
+            error: `"${key}" is pinned via ${setting.source} and cannot be changed here`,
+        };
+    }
+    const storage = getStorage();
+    if (!storage) {
+        return {
+            ok: false,
+            status: 409,
+            error: "No active storage; cannot persist config",
+        };
+    }
+    return { ok: true, key: key, storage };
+}
 /** Best-effort actor attribution for audit rows (no auth in dev → "dev"). */
 function actorOf(req) {
     const header = req.header("x-enpilink-actor");

package/dist/server/config/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../../../src/server/config/router.ts"],"names":[],"mappings":"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","sourcesContent":["import express, { type Router } from \"express\";\nimport { getActiveStorage } from \"../log-sink.js\";\nimport type { ConfigAuditEntry, StorageAdapter } from \"../storage/types.js\";\nimport { resolveConfig, validateRuntimeWrite } from \"./resolve.js\";\nimport {\n  isBootstrapKey,\n  isKnownKey,\n  isRuntimeKey,\n  isSecretKey,\n} from \"./schema.js\";\n\n/**\n * Config admin API (M4). Pure core — reads the SAME active\n * {@link StorageAdapter} the analytics middleware writes to, via\n * {@link getActiveStorage}. Does NOT depend on `@enpilink/console`.\n *\n * Mounted dev-only (under the `NODE_ENV !== \"production\"` block in\n * `express.ts`) at `/__enpilink/config`. Prod admin mounting (behind bearer\n * auth) is M5.\n *\n * Routes:\n * - `GET  /__enpilink/config`        — all settings (value-or-masked + source +\n *   secret/envLocked flags).\n * - `PUT  /__enpilink/config/:key`   — set a RUNTIME, non-secret key. Rejects\n *   bootstrap / secret / env-locked / unknown keys with a clear 4xx.\n * - `GET  /__enpilink/config/audit`  — recent config-change history.\n *\n * Disabled-safe: when there is no active storage, reads fall back to env/file/\n * defaults (runtime keys show their defaults) and NEVER 500. Writes require a\n * storage adapter (409 when none) — there is nowhere to persist otherwise.\n */\nexport function createConfigRouter(\n  getStorage: () => StorageAdapter | null = getActiveStorage,\n): Router {\n  const router = express.Router();\n  const base = \"/__enpilink/config\";\n\n  // GET /config — full resolved settings. Secrets masked; never 500.\n  router.get(base, async (_req, res) => {\n    try {\n      const resolved = await resolveConfig(getStorage());\n      res.json({ settings: resolved.settings });\n    } catch {\n      // Last-resort: resolve with no storage so reads never fail.\n      const resolved = await resolveConfig(null);\n      res.json({ settings: resolved.settings });\n    }\n  });\n\n  // GET /config/audit — change history (most recent first). Never 500.\n  router.get(`${base}/audit`, async (_req, res) => {\n    const storage = getStorage();\n    if (!storage) {\n      res.json({ enabled: false, audit: [] as ConfigAuditEntry[] });\n      return;\n    }\n    try {\n      const audit = await storage.getConfigAudit();\n      res.json({ enabled: true, audit });\n    } catch {\n      res.json({ enabled: false, audit: [] as ConfigAuditEntry[] });\n    }\n  });\n\n  // PUT /config/:key — set a runtime, non-secret key. Reject everything else.\n  router.put(`${base}/:key`, async (req, res) => {\n    const key = req.params.key;\n\n    if (!isKnownKey(key)) {\n      res.status(404).json({ error: `Unknown config key \"${key}\"` });\n      return;\n    }\n    if (isSecretKey(key)) {\n      res.status(403).json({\n        error: `\"${key}\" is a secret and is set via environment only`,\n      });\n      return;\n    }\n    if (isBootstrapKey(key)) {\n      res.status(403).json({\n        error: `\"${key}\" is a bootstrap setting (env/file only) and is read-only here`,\n      });\n      return;\n    }\n    if (!isRuntimeKey(key)) {\n      res.status(403).json({ error: `\"${key}\" is not editable` });\n      return;\n    }\n\n    // Reject if this runtime key is currently pinned (env-locked) by env/file.\n    const resolved = await resolveConfig(getStorage());\n    const setting = resolved.settings.find((s) => s.key === key);\n    if (setting?.envLocked) {\n      res.status(409).json({\n        error: `\"${key}\" is pinned via ${setting.source} and cannot be changed here`,\n      });\n      return;\n    }\n\n    const body = req.body as { value?: unknown } | undefined;\n    const rawValue = body?.value;\n    const check = validateRuntimeWrite(key, rawValue);\n    if (!check.ok) {\n      res.status(400).json({ error: check.error });\n      return;\n    }\n\n    const storage = getStorage();\n    if (!storage) {\n      res.status(409).json({\n        error: \"No active storage; cannot persist runtime config\",\n      });\n      return;\n    }\n\n    try {\n      const actor = actorOf(req);\n      await storage.setConfig(key, check.value, actor);\n      res.json({ ok: true, key, value: check.value });\n    } catch (err) {\n      res.status(500).json({\n        error: err instanceof Error ? err.message : \"Failed to write config\",\n      });\n    }\n  });\n\n  return router;\n}\n\n/** Best-effort actor attribution for audit rows (no auth in dev → \"dev\"). */\nfunction actorOf(req: express.Request): string {\n  const header = req.header(\"x-enpilink-actor\");\n  return typeof header === \"string\" && header.length > 0 ? header : \"dev\";\n}\n"]}
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../../src/server/config/router.ts"],"names":[],"mappings":"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","sourcesContent":["import express, { type Router } from \"express\";\nimport { refreshCaptureGate } from \"../capture-gate.js\";\nimport { getActiveStorage } from \"../log-sink.js\";\nimport type { ConfigAuditEntry, StorageAdapter } from \"../storage/types.js\";\nimport { getPreset, PRESETS } from \"./presets.js\";\nimport {\n  type ResolvedSetting,\n  resolveConfig,\n  validateConfigWrite,\n} from \"./resolve.js\";\nimport {\n  type ConfigKey,\n  isBootstrapKey,\n  isKnownKey,\n  isRestartKey,\n  isRuntimeKey,\n  isSecretKey,\n} from \"./schema.js\";\n\n/**\n * Config admin API. Pure core — reads the SAME active {@link StorageAdapter}\n * the analytics middleware writes to, via {@link getActiveStorage}. Does NOT\n * depend on `@enpilink/console`.\n *\n * Mounted dev-only (unauth, localhost) and in the prod admin plane (behind\n * bearer auth) at `/__enpilink/config`.\n *\n * Routes:\n * - `GET    /__enpilink/config`               — all settings (rich metadata +\n *   source + secret/envLocked/modified/restartRequired flags).\n * - `PUT    /__enpilink/config/:key`          — set a RUNTIME or RESTART-tier\n *   key. Rejects secret / `admin` / env-locked / unknown keys with a clear 4xx.\n * - `DELETE /__enpilink/config/:key`          — reset a key to its default\n *   (clears the DB override). Same guardrails as PUT.\n * - `GET    /__enpilink/config/presets`       — list presets + the values each\n *   would set.\n * - `POST   /__enpilink/config/preset/:name`  — apply a preset (validate +\n *   persist + audit each runtime key; skip env-locked).\n * - `GET    /__enpilink/config/audit`         — recent config-change history.\n *\n * Disabled-safe: with no active storage, reads fall back to env/file/defaults\n * and NEVER 500. Writes require a storage adapter (409 when none).\n *\n * SECURITY: `admin`, `adminAuthToken`, unknown keys, and env-locked keys can\n * NEVER be written here. `adminAuthToken` is never persisted nor returned in\n * plaintext.\n */\nexport function createConfigRouter(\n  getStorage: () => StorageAdapter | null = getActiveStorage,\n): Router {\n  const router = express.Router();\n  const base = \"/__enpilink/config\";\n\n  // GET /config — full resolved settings. Secrets masked; never 500.\n  router.get(base, async (_req, res) => {\n    try {\n      const resolved = await resolveConfig(getStorage());\n      res.json({ settings: resolved.settings });\n    } catch {\n      const resolved = await resolveConfig(null);\n      res.json({ settings: resolved.settings });\n    }\n  });\n\n  // GET /config/presets — list presets + the values each would set.\n  router.get(`${base}/presets`, (_req, res) => {\n    res.json({ presets: Object.values(PRESETS) });\n  });\n\n  // GET /config/audit — change history (most recent first). Never 500.\n  router.get(`${base}/audit`, async (_req, res) => {\n    const storage = getStorage();\n    if (!storage) {\n      res.json({ enabled: false, audit: [] as ConfigAuditEntry[] });\n      return;\n    }\n    try {\n      const audit = await storage.getConfigAudit();\n      res.json({ enabled: true, audit });\n    } catch {\n      res.json({ enabled: false, audit: [] as ConfigAuditEntry[] });\n    }\n  });\n\n  // POST /config/preset/:name — apply a runtime-only preset.\n  router.post(`${base}/preset/:name`, async (req, res) => {\n    const preset = getPreset(req.params.name);\n    if (!preset) {\n      res.status(404).json({ error: `Unknown preset \"${req.params.name}\"` });\n      return;\n    }\n    const storage = getStorage();\n    if (!storage) {\n      res.status(409).json({\n        error: \"No active storage; cannot apply preset\",\n      });\n      return;\n    }\n\n    const resolved = await resolveConfig(storage);\n    const byKey = new Map(resolved.settings.map((s) => [s.key, s]));\n    const actor = actorOf(req);\n\n    const applied: { key: string; value: unknown }[] = [];\n    const skipped: { key: string; reason: string }[] = [];\n\n    for (const [key, value] of Object.entries(preset.values)) {\n      // Presets only ever touch runtime keys; double-check the guardrail.\n      if (!isRuntimeKey(key)) {\n        skipped.push({ key, reason: \"not a runtime key\" });\n        continue;\n      }\n      const setting = byKey.get(key as ConfigKey);\n      if (setting?.envLocked) {\n        skipped.push({ key, reason: `pinned via ${setting.source}` });\n        continue;\n      }\n      const check = validateConfigWrite(key, value);\n      if (!check.ok) {\n        skipped.push({ key, reason: check.error });\n        continue;\n      }\n      try {\n        await storage.setConfig(key, check.value, actor);\n        applied.push({ key, value: check.value });\n      } catch (err) {\n        skipped.push({\n          key,\n          reason: err instanceof Error ? err.message : \"write failed\",\n        });\n      }\n    }\n\n    // A preset may have changed analytics.enabled/sampleRate — refresh the live\n    // capture gate so it takes effect without a restart.\n    await refreshCaptureGate();\n    res.json({ ok: true, preset: preset.name, applied, skipped });\n  });\n\n  // PUT /config/:key — set a runtime or restart-tier key.\n  router.put(`${base}/:key`, async (req, res) => {\n    const guard = await writeGuard(req.params.key, getStorage);\n    if (!guard.ok) {\n      res.status(guard.status).json({ error: guard.error });\n      return;\n    }\n    const key = guard.key;\n\n    const body = req.body as { value?: unknown } | undefined;\n    const check = validateConfigWrite(key, body?.value);\n    if (!check.ok) {\n      res.status(400).json({ error: check.error });\n      return;\n    }\n\n    try {\n      await guard.storage.setConfig(key, check.value, actorOf(req));\n      // Refresh the live capture gate so a toggle of analytics.enabled /\n      // analytics.sampleRate takes effect immediately (no restart).\n      await refreshCaptureGate();\n      res.json({\n        ok: true,\n        key,\n        value: check.value,\n        restartRequired: isRestartKey(key),\n      });\n    } catch (err) {\n      res.status(500).json({\n        error: err instanceof Error ? err.message : \"Failed to write config\",\n      });\n    }\n  });\n\n  // DELETE /config/:key — reset to default (clear the DB override).\n  router.delete(`${base}/:key`, async (req, res) => {\n    const guard = await writeGuard(req.params.key, getStorage);\n    if (!guard.ok) {\n      res.status(guard.status).json({ error: guard.error });\n      return;\n    }\n    try {\n      await guard.storage.clearConfig(guard.key, actorOf(req));\n      // Resetting analytics.enabled / sampleRate to default also re-gates\n      // capture live.\n      await refreshCaptureGate();\n      res.json({\n        ok: true,\n        key: guard.key,\n        reset: true,\n        restartRequired: isRestartKey(guard.key),\n      });\n    } catch (err) {\n      res.status(500).json({\n        error: err instanceof Error ? err.message : \"Failed to reset config\",\n      });\n    }\n  });\n\n  return router;\n}\n\ntype WriteGuardResult =\n  | { ok: true; key: ConfigKey; storage: StorageAdapter }\n  | { ok: false; status: number; error: string };\n\n/**\n * Shared guardrail for PUT + DELETE. Rejects unknown / secret / `admin` /\n * env-locked keys and requires an active storage adapter. Only runtime and\n * non-env-locked restart-tier keys pass.\n */\nasync function writeGuard(\n  key: string,\n  getStorage: () => StorageAdapter | null,\n): Promise<WriteGuardResult> {\n  if (!isKnownKey(key)) {\n    return { ok: false, status: 404, error: `Unknown config key \"${key}\"` };\n  }\n  if (isSecretKey(key)) {\n    return {\n      ok: false,\n      status: 403,\n      error: `\"${key}\" is a secret and is set via environment only`,\n    };\n  }\n  // Bootstrap keys are writable ONLY if they are restart-tier (port/storage/\n  // dbPath). `admin` (and any other bootstrap key) is env-only / read-only.\n  if (isBootstrapKey(key) && !isRestartKey(key)) {\n    return {\n      ok: false,\n      status: 403,\n      error: `\"${key}\" is environment-only and is read-only here`,\n    };\n  }\n  if (!isRuntimeKey(key) && !isRestartKey(key)) {\n    return { ok: false, status: 403, error: `\"${key}\" is not editable` };\n  }\n\n  // Reject if the key is currently pinned (env-locked) by env/file.\n  const resolved = await resolveConfig(getStorage());\n  const setting = resolved.settings.find((s: ResolvedSetting) => s.key === key);\n  if (setting?.envLocked) {\n    return {\n      ok: false,\n      status: 409,\n      error: `\"${key}\" is pinned via ${setting.source} and cannot be changed here`,\n    };\n  }\n\n  const storage = getStorage();\n  if (!storage) {\n    return {\n      ok: false,\n      status: 409,\n      error: \"No active storage; cannot persist config\",\n    };\n  }\n  return { ok: true, key: key as ConfigKey, storage };\n}\n\n/** Best-effort actor attribution for audit rows (no auth in dev → \"dev\"). */\nfunction actorOf(req: express.Request): string {\n  const header = req.header(\"x-enpilink-actor\");\n  return typeof header === \"string\" && header.length > 0 ? header : \"dev\";\n}\n"]}

package/dist/server/config/schema.d.ts

@@ -43,7 +43,16 @@ export type Config = z.infer<typeof configSchema>;
 export type ConfigKey = keyof Config;
 export type BootstrapKey = keyof BootstrapConfig;
 export type RuntimeKey = keyof RuntimeConfig;
-/** Per-key metadata describing tier / secret / env-lock semantics. */
+/**
+ * Editability classification, surfaced to the admin UI:
+ * - `runtime`  — editable live; takes effect immediately.
+ * - `restart`  — DB-editable but only takes effect after a process restart
+ *   (the non-secret bootstrap keys `port`/`storage`/`dbPath`).
+ * - `readonly` — env-only; never web-editable (the `admin` gate + the
+ *   `adminAuthToken` secret).
+ */
+export type Editable = "runtime" | "restart" | "readonly";
+/** Per-key metadata describing tier / secret / env-lock + UI presentation. */
 export interface KeyMeta {
     key: ConfigKey;
     /** `bootstrap` (env/file only) or `runtime` (DB-editable). */
@@ -52,6 +61,18 @@ export interface KeyMeta {
     secret: boolean;
     /** The env var that drives this key (for the "set via env" hint). */
     env: string;
+    /** Human-friendly label (primary heading in the UI). */
+    label: string;
+    /** One-line plain-language description of what the setting does. */
+    description: string;
+    /** Functional category used to group settings in the UI. */
+    group: string;
+    /** Optional unit hint (e.g. `"ms"`, `"events"`, `"0–1 ratio"`). */
+    unit?: string;
+    /** The schema default value for this key. */
+    default: unknown;
+    /** How this key may be edited from the admin UI. */
+    editable: Editable;
 }
 /** Bootstrap keys (env/file only). */
 export declare const BOOTSTRAP_KEYS: readonly ["storage", "dbPath", "port", "admin", "adminAuthToken"];
@@ -59,6 +80,12 @@ export declare const BOOTSTRAP_KEYS: readonly ["storage", "dbPath", "port", "adm
 export declare const RUNTIME_KEYS: readonly ["analytics.enabled", "analytics.sampleRate", "retention.events", "retention.logs", "flags.liveLogs", "display.bucketMs"];
 /** Secret keys: env-only, masked + never persisted/returned in plaintext. */
 export declare const SECRET_KEYS: readonly ["adminAuthToken"];
+/**
+ * Restart-tier keys: non-secret bootstrap keys that ARE DB-editable but only
+ * take effect after a process restart. Resolution still honours env>file>db so
+ * an env/file pin locks them (read-only).
+ */
+export declare const RESTART_KEYS: readonly ["port", "storage", "dbPath"];
 /**
  * Env var mapping per key. Bootstrap keys map to dedicated env vars that match
  * the framework's existing env surface; runtime keys use an
@@ -70,6 +97,17 @@ export declare function isSecretKey(key: string): boolean;
 export declare function isRuntimeKey(key: string): key is RuntimeKey;
 export declare function isBootstrapKey(key: string): key is BootstrapKey;
 export declare function isKnownKey(key: string): key is ConfigKey;
+/** A restart-tier key: DB-editable but only effective after a restart. */
+export declare function isRestartKey(key: string): key is BootstrapKey;
+/**
+ * The editability classification for a key:
+ * - secret/admin → `readonly` (env-only, never web-editable)
+ * - other bootstrap keys (port/storage/dbPath) → `restart`
+ * - runtime keys → `runtime`
+ */
+export declare function editableOf(key: ConfigKey): Editable;
+/** The schema default value for a key (undefined for optional secrets). */
+export declare function defaultForKey(key: ConfigKey): unknown;
 /** Metadata for every known key. */
 export declare function keyMeta(key: ConfigKey): KeyMeta;
 /** All keys with metadata. */

package/dist/server/config/schema.js

@@ -83,6 +83,84 @@ export const runtimeSchema = z.object({
     "display.bucketMs": z.number().int().positive().default(60_000),
 });
 export const configSchema = bootstrapSchema.merge(runtimeSchema);
+const KEY_DESCRIPTORS = {
+    // --- Server (restart-tier bootstrap) ---
+    port: {
+        label: "Server port",
+        description: "The network port the server listens on. Changing this needs a restart to take effect.",
+        group: "Server",
+        editable: "restart",
+    },
+    storage: {
+        label: "Storage engine",
+        description: "Where analytics, logs, and settings are persisted: in-memory (resets on restart), sqlite (a local file), or postgres. Takes effect after a restart.",
+        group: "Storage",
+        editable: "restart",
+    },
+    dbPath: {
+        label: "SQLite database file",
+        description: "Path to the SQLite database file (only used when the storage engine is sqlite). Takes effect after a restart.",
+        group: "Storage",
+        editable: "restart",
+    },
+    // --- Security (read-only, env-only) ---
+    admin: {
+        label: "Production admin plane",
+        description: "Enables the admin dashboard in production. For safety this can only be turned on via environment variable, never from the web UI.",
+        group: "Security",
+        editable: "readonly",
+    },
+    adminAuthToken: {
+        label: "Admin auth token",
+        description: "Secret bearer token guarding the production admin plane. Set via environment only; never stored or shown in plaintext.",
+        group: "Security",
+        editable: "readonly",
+    },
+    // --- Analytics (runtime) ---
+    "analytics.enabled": {
+        label: "Analytics enabled",
+        description: "Record tool-call events and server logs so the dashboard can show usage and latency.",
+        group: "Analytics",
+        editable: "runtime",
+    },
+    "analytics.sampleRate": {
+        label: "Sampling rate",
+        description: "Fraction of requests to record. 1 records everything; lower values reduce overhead and storage on busy servers.",
+        group: "Analytics",
+        unit: "0–1 ratio",
+        editable: "runtime",
+    },
+    // --- Retention (runtime) ---
+    "retention.events": {
+        label: "Event retention",
+        description: "Maximum number of tool-call events kept. Oldest events are dropped once the cap is reached.",
+        group: "Retention",
+        unit: "events",
+        editable: "runtime",
+    },
+    "retention.logs": {
+        label: "Log retention",
+        description: "Maximum number of captured log lines kept. Oldest logs are dropped once the cap is reached.",
+        group: "Retention",
+        unit: "logs",
+        editable: "runtime",
+    },
+    // --- Features (runtime) ---
+    "flags.liveLogs": {
+        label: "Live log stream",
+        description: "Show the real-time server log stream in the dashboard's live-logs panel.",
+        group: "Features",
+        editable: "runtime",
+    },
+    // --- Display (runtime) ---
+    "display.bucketMs": {
+        label: "Chart time bucket",
+        description: "Default width of each time bucket in the dashboard's volume/latency charts.",
+        group: "Display",
+        unit: "ms",
+        editable: "runtime",
+    },
+};
 /** Bootstrap keys (env/file only). */
 export const BOOTSTRAP_KEYS = [
     "storage",
@@ -104,6 +182,16 @@ export const RUNTIME_KEYS = [
 export const SECRET_KEYS = [
     "adminAuthToken",
 ];
+/**
+ * Restart-tier keys: non-secret bootstrap keys that ARE DB-editable but only
+ * take effect after a process restart. Resolution still honours env>file>db so
+ * an env/file pin locks them (read-only).
+ */
+export const RESTART_KEYS = [
+    "port",
+    "storage",
+    "dbPath",
+];
 /**
  * Env var mapping per key. Bootstrap keys map to dedicated env vars that match
  * the framework's existing env surface; runtime keys use an
@@ -126,6 +214,7 @@ export const ENV_VARS = {
 const SECRET_SET = new Set(SECRET_KEYS);
 const RUNTIME_SET = new Set(RUNTIME_KEYS);
 const BOOTSTRAP_SET = new Set(BOOTSTRAP_KEYS);
+const RESTART_SET = new Set(RESTART_KEYS);
 export function isSecretKey(key) {
     return SECRET_SET.has(key);
 }
@@ -138,13 +227,45 @@ export function isBootstrapKey(key) {
 export function isKnownKey(key) {
     return RUNTIME_SET.has(key) || BOOTSTRAP_SET.has(key);
 }
+/** A restart-tier key: DB-editable but only effective after a restart. */
+export function isRestartKey(key) {
+    return RESTART_SET.has(key);
+}
+/**
+ * The editability classification for a key:
+ * - secret/admin → `readonly` (env-only, never web-editable)
+ * - other bootstrap keys (port/storage/dbPath) → `restart`
+ * - runtime keys → `runtime`
+ */
+export function editableOf(key) {
+    if (isRestartKey(key)) {
+        return "restart";
+    }
+    if (isBootstrapKey(key)) {
+        return "readonly";
+    }
+    return "runtime";
+}
+/** Default-typed sample used to read each key's schema default. */
+const DEFAULTS = configSchema.parse({});
+/** The schema default value for a key (undefined for optional secrets). */
+export function defaultForKey(key) {
+    return DEFAULTS[key];
+}
 /** Metadata for every known key. */
 export function keyMeta(key) {
+    const d = KEY_DESCRIPTORS[key];
     return {
         key,
         tier: isBootstrapKey(key) ? "bootstrap" : "runtime",
         secret: isSecretKey(key),
         env: ENV_VARS[key],
+        label: d.label,
+        description: d.description,
+        group: d.group,
+        unit: d.unit,
+        default: defaultForKey(key),
+        editable: d.editable,
     };
 }
 /** All keys with metadata. */