enpilink 1.0.2

package/dist/server/config/resolve.js

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import path from "node:path";
+import { coerceBool, coerceNumber, configSchema, ENV_VARS, isRuntimeKey, isSecretKey, keyMeta, RUNTIME_KEYS, schemaForKey, } from "./schema.js";
+/** A masked placeholder returned in place of any secret value. */
+export const MASKED = "••••••••";
+const FILE_NAMES = ["enpilink.config.json", "enpilink.config.ts"];
+/**
+ * Load the optional config file (JSON only — a `.ts` file is acknowledged but
+ * not executed here to avoid a runtime transpile dependency; M6 can add TS
+ * loading). Returns a flat partial keyed by {@link ConfigKey}. Never throws —
+ * a malformed/absent file yields `{}`.
+ */
+export function loadConfigFile(cwd = process.cwd()) {
+    for (const name of FILE_NAMES) {
+        const full = path.join(cwd, name);
+        if (!fs.existsSync(full)) {
+            continue;
+        }
+        if (name.endsWith(".json")) {
+            try {
+                const raw = fs.readFileSync(full, "utf8");
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object") {
+                    return { source: "file", values: parsed };
+                }
+            }
+            catch {
+                // Malformed file → ignore (defaults/db/env still apply).
+            }
+        }
+        // A `.ts` config file is recognized but not executed in M4.
+    }
+    return { source: null, values: {} };
+}
+/** Read the raw env value for a key (the mapped env var), or undefined. */
+function envValue(key) {
+    const raw = process.env[ENV_VARS[key]];
+    return raw === undefined || raw === "" ? undefined : raw;
+}
+/** Default-typed sample used to learn each key's expected runtime type. */
+const TYPE_SAMPLE = configSchema.parse({});
+/** Coerce a raw value (e.g. an env string) to the key's expected type. */
+function coerceForKey(key, raw) {
+    const expected = typeof TYPE_SAMPLE[key];
+    if (expected === "boolean") {
+        return coerceBool(raw) ?? raw;
+    }
+    if (expected === "number") {
+        return coerceNumber(raw) ?? raw;
+    }
+    return raw;
+}
+/**
+ * Resolve all config. Reads the DB (runtime keys only) when a storage adapter
+ * is provided; secrets are never read from the DB. Falls back to defaults when
+ * there is no storage. Never throws on a storage error — it degrades to
+ * file/env/default.
+ *
+ * @param storage active storage adapter, or `null` when analytics/admin is off.
+ */
+export async function resolveConfig(storage, cwd = process.cwd()) {
+    const file = loadConfigFile(cwd);
+    // DB values for runtime keys only (secrets are never persisted/read).
+    let db = {};
+    if (storage) {
+        try {
+            const all = await storage.allConfig();
+            for (const key of RUNTIME_KEYS) {
+                if (key in all && !isSecretKey(key)) {
+                    db[key] = all[key];
+                }
+            }
+        }
+        catch {
+            db = {};
+        }
+    }
+    const rawValues = {};
+    const sources = new Map();
+    const keys = Object.keys(configSchema.shape);
+    for (const key of keys) {
+        const env = envValue(key);
+        if (env !== undefined) {
+            rawValues[key] = coerceForKey(key, env);
+            sources.set(key, "env");
+            continue;
+        }
+        if (key in file.values) {
+            rawValues[key] = file.values[key];
+            sources.set(key, "file");
+            continue;
+        }
+        // Secrets are never read from the DB.
+        if (isRuntimeKey(key) && !isSecretKey(key) && key in db) {
+            rawValues[key] = db[key];
+            sources.set(key, "db");
+            continue;
+        }
+        sources.set(key, "default");
+    }
+    // Validate + fill defaults. If a supplied value is invalid, zod throws; we
+    // fall back per-key to the default so a bad DB/file value can't crash reads.
+    let values;
+    try {
+        values = configSchema.parse(rawValues);
+    }
+    catch {
+        // Re-resolve key-by-key, dropping any invalid override.
+        const safe = {};
+        for (const key of keys) {
+            const single = schemaForKey(key).safeParse(rawValues[key]);
+            if (single.success && key in rawValues) {
+                safe[key] = rawValues[key];
+            }
+            else if (sources.get(key) !== "default") {
+                sources.set(key, "default");
+            }
+        }
+        values = configSchema.parse(safe);
+    }
+    const settings = keys.map((key) => {
+        const meta = keyMeta(key);
+        const source = sources.get(key) ?? "default";
+        const secret = meta.secret;
+        // Env-locked: bootstrap keys are always read-only; runtime keys are locked
+        // when pinned by env or file (the DB write would be shadowed).
+        const envLocked = meta.tier === "bootstrap" || source === "env" || source === "file";
+        const value = secret
+            ? values[key] !== undefined && values[key] !== ""
+                ? MASKED
+                : null
+            : values[key];
+        return {
+            key,
+            tier: meta.tier,
+            value,
+            source,
+            secret,
+            envLocked,
+            env: meta.env,
+        };
+    });
+    return { values, settings };
+}
+/**
+ * Validate + coerce a single RUNTIME, non-secret value before persisting.
+ * Returns the coerced value or an error string. Rejects unknown/bootstrap/
+ * secret keys (those are handled by the caller with a clear 4xx).
+ */
+export function validateRuntimeWrite(key, rawValue) {
+    if (!isRuntimeKey(key)) {
+        return { ok: false, error: `"${key}" is not a runtime key` };
+    }
+    if (isSecretKey(key)) {
+        return { ok: false, error: `"${key}" is a secret and cannot be set here` };
+    }
+    const coerced = coerceForKey(key, rawValue);
+    const parsed = schemaForKey(key).safeParse(coerced);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: `invalid value for "${key}": ${parsed.error.issues[0]?.message ?? "validation failed"}`,
+        };
+    }
+    return { ok: true, value: parsed.data };
+}
+//# sourceMappingURL=resolve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../../src/server/config/resolve.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { StorageAdapter } from \"../storage/types.js\";\nimport {\n  type Config,\n  type ConfigKey,\n  coerceBool,\n  coerceNumber,\n  configSchema,\n  ENV_VARS,\n  isRuntimeKey,\n  isSecretKey,\n  keyMeta,\n  RUNTIME_KEYS,\n  schemaForKey,\n} from \"./schema.js\";\n\n/**\n * Config resolution (M4). Merges sources with precedence\n * **env > file (`enpilink.config.{json,ts}`) > db (runtime only) > default**\n * and reports, per key, which source supplied the value and whether the key is\n * secret / env-locked (read-only).\n *\n * Secrets (e.g. `adminAuthToken`) are NEVER read from the DB and NEVER returned\n * in plaintext — {@link resolveConfig} masks them to a placeholder and flags\n * `secret: true`. Bootstrap keys and any key pinned by env/file are\n * `envLocked: true` (the admin UI must render them read-only).\n */\n\nexport type ConfigSource = \"env\" | \"file\" | \"db\" | \"default\";\n\n/** A masked placeholder returned in place of any secret value. */\nexport const MASKED = \"••••••••\";\n\n/** A single resolved setting as exposed by the config API. */\nexport interface ResolvedSetting {\n  key: ConfigKey;\n  /** Tier: `bootstrap` (env/file only) or `runtime` (DB-editable). */\n  tier: \"bootstrap\" | \"runtime\";\n  /** The resolved value, or {@link MASKED} when secret. */\n  value: unknown;\n  /** Which source supplied the value. */\n  source: ConfigSource;\n  /** Whether this key is a secret (never returned in plaintext). */\n  secret: boolean;\n  /**\n   * Whether this key is read-only in the admin UI. True for all bootstrap keys,\n   * and for any runtime key pinned via env or file (the DB value is shadowed).\n   */\n  envLocked: boolean;\n  /** The env var that drives / can pin this key. */\n  env: string;\n}\n\n/** The full resolved config plus per-key reporting. */\nexport interface ResolvedConfig {\n  /** Effective typed values (secrets present in-process, masked only at the API). */\n  values: Config;\n  /** Per-key source + secret/env-lock reporting. */\n  settings: ResolvedSetting[];\n}\n\nconst FILE_NAMES = [\"enpilink.config.json\", \"enpilink.config.ts\"];\n\n/**\n * Load the optional config file (JSON only — a `.ts` file is acknowledged but\n * not executed here to avoid a runtime transpile dependency; M6 can add TS\n * loading). Returns a flat partial keyed by {@link ConfigKey}. Never throws —\n * a malformed/absent file yields `{}`.\n */\nexport function loadConfigFile(cwd: string = process.cwd()): {\n  source: \"file\" | null;\n  values: Partial<Record<ConfigKey, unknown>>;\n} {\n  for (const name of FILE_NAMES) {\n    const full = path.join(cwd, name);\n    if (!fs.existsSync(full)) {\n      continue;\n    }\n    if (name.endsWith(\".json\")) {\n      try {\n        const raw = fs.readFileSync(full, \"utf8\");\n        const parsed = JSON.parse(raw);\n        if (parsed && typeof parsed === \"object\") {\n          return { source: \"file\", values: parsed as Record<string, unknown> };\n        }\n      } catch {\n        // Malformed file → ignore (defaults/db/env still apply).\n      }\n    }\n    // A `.ts` config file is recognized but not executed in M4.\n  }\n  return { source: null, values: {} };\n}\n\n/** Read the raw env value for a key (the mapped env var), or undefined. */\nfunction envValue(key: ConfigKey): string | undefined {\n  const raw = process.env[ENV_VARS[key]];\n  return raw === undefined || raw === \"\" ? undefined : raw;\n}\n\n/** Default-typed sample used to learn each key's expected runtime type. */\nconst TYPE_SAMPLE = configSchema.parse({}) as Record<string, unknown>;\n\n/** Coerce a raw value (e.g. an env string) to the key's expected type. */\nfunction coerceForKey(key: ConfigKey, raw: unknown): unknown {\n  const expected = typeof TYPE_SAMPLE[key];\n  if (expected === \"boolean\") {\n    return coerceBool(raw) ?? raw;\n  }\n  if (expected === \"number\") {\n    return coerceNumber(raw) ?? raw;\n  }\n  return raw;\n}\n\n/**\n * Resolve all config. Reads the DB (runtime keys only) when a storage adapter\n * is provided; secrets are never read from the DB. Falls back to defaults when\n * there is no storage. Never throws on a storage error — it degrades to\n * file/env/default.\n *\n * @param storage active storage adapter, or `null` when analytics/admin is off.\n */\nexport async function resolveConfig(\n  storage: StorageAdapter | null,\n  cwd: string = process.cwd(),\n): Promise<ResolvedConfig> {\n  const file = loadConfigFile(cwd);\n\n  // DB values for runtime keys only (secrets are never persisted/read).\n  let db: Record<string, unknown> = {};\n  if (storage) {\n    try {\n      const all = await storage.allConfig();\n      for (const key of RUNTIME_KEYS) {\n        if (key in all && !isSecretKey(key)) {\n          db[key] = all[key];\n        }\n      }\n    } catch {\n      db = {};\n    }\n  }\n\n  const rawValues: Record<string, unknown> = {};\n  const sources = new Map<ConfigKey, ConfigSource>();\n\n  const keys = Object.keys(configSchema.shape) as ConfigKey[];\n  for (const key of keys) {\n    const env = envValue(key);\n    if (env !== undefined) {\n      rawValues[key] = coerceForKey(key, env);\n      sources.set(key, \"env\");\n      continue;\n    }\n    if (key in file.values) {\n      rawValues[key] = file.values[key];\n      sources.set(key, \"file\");\n      continue;\n    }\n    // Secrets are never read from the DB.\n    if (isRuntimeKey(key) && !isSecretKey(key) && key in db) {\n      rawValues[key] = db[key];\n      sources.set(key, \"db\");\n      continue;\n    }\n    sources.set(key, \"default\");\n  }\n\n  // Validate + fill defaults. If a supplied value is invalid, zod throws; we\n  // fall back per-key to the default so a bad DB/file value can't crash reads.\n  let values: Config;\n  try {\n    values = configSchema.parse(rawValues);\n  } catch {\n    // Re-resolve key-by-key, dropping any invalid override.\n    const safe: Record<string, unknown> = {};\n    for (const key of keys) {\n      const single = schemaForKey(key).safeParse(rawValues[key]);\n      if (single.success && key in rawValues) {\n        safe[key] = rawValues[key];\n      } else if (sources.get(key) !== \"default\") {\n        sources.set(key, \"default\");\n      }\n    }\n    values = configSchema.parse(safe);\n  }\n\n  const settings: ResolvedSetting[] = keys.map((key) => {\n    const meta = keyMeta(key);\n    const source = sources.get(key) ?? \"default\";\n    const secret = meta.secret;\n    // Env-locked: bootstrap keys are always read-only; runtime keys are locked\n    // when pinned by env or file (the DB write would be shadowed).\n    const envLocked =\n      meta.tier === \"bootstrap\" || source === \"env\" || source === \"file\";\n    const value = secret\n      ? values[key] !== undefined && values[key] !== \"\"\n        ? MASKED\n        : null\n      : (values[key] as unknown);\n    return {\n      key,\n      tier: meta.tier,\n      value,\n      source,\n      secret,\n      envLocked,\n      env: meta.env,\n    };\n  });\n\n  return { values, settings };\n}\n\n/**\n * Validate + coerce a single RUNTIME, non-secret value before persisting.\n * Returns the coerced value or an error string. Rejects unknown/bootstrap/\n * secret keys (those are handled by the caller with a clear 4xx).\n */\nexport function validateRuntimeWrite(\n  key: string,\n  rawValue: unknown,\n): { ok: true; value: unknown } | { ok: false; error: string } {\n  if (!isRuntimeKey(key)) {\n    return { ok: false, error: `\"${key}\" is not a runtime key` };\n  }\n  if (isSecretKey(key)) {\n    return { ok: false, error: `\"${key}\" is a secret and cannot be set here` };\n  }\n  const coerced = coerceForKey(key as ConfigKey, rawValue);\n  const parsed = schemaForKey(key as ConfigKey).safeParse(coerced);\n  if (!parsed.success) {\n    return {\n      ok: false,\n      error: `invalid value for \"${key}\": ${parsed.error.issues[0]?.message ?? \"validation failed\"}`,\n    };\n  }\n  return { ok: true, value: parsed.data };\n}\n"]}

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

@@ -0,0 +1,23 @@
+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`.
+ *
+ * Mounted dev-only (under the `NODE_ENV !== "production"` block in
+ * `express.ts`) at `/__enpilink/config`. Prod admin mounting (behind bearer
+ * auth) is M5.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function createConfigRouter(getStorage?: () => StorageAdapter | null): Router;

package/dist/server/config/router.js

@@ -0,0 +1,119 @@
+import express, {} from "express";
+import { getActiveStorage } from "../log-sink.js";
+import { resolveConfig, validateRuntimeWrite } from "./resolve.js";
+import { isBootstrapKey, isKnownKey, 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`.
+ *
+ * Mounted dev-only (under the `NODE_ENV !== "production"` block in
+ * `express.ts`) at `/__enpilink/config`. Prod admin mounting (behind bearer
+ * auth) is M5.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export function createConfigRouter(getStorage = getActiveStorage) {
+    const router = express.Router();
+    const base = "/__enpilink/config";
+    // GET /config — full resolved settings. Secrets masked; never 500.
+    router.get(base, async (_req, res) => {
+        try {
+            const resolved = await resolveConfig(getStorage());
+            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/audit — change history (most recent first). Never 500.
+    router.get(`${base}/audit`, async (_req, res) => {
+        const storage = getStorage();
+        if (!storage) {
+            res.json({ enabled: false, audit: [] });
+            return;
+        }
+        try {
+            const audit = await storage.getConfigAudit();
+            res.json({ enabled: true, audit });
+        }
+        catch {
+            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`,
+            });
+            return;
+        }
+        if (isBootstrapKey(key)) {
+            res.status(403).json({
+                error: `"${key}" is a bootstrap setting (env/file only) and is read-only here`,
+            });
+            return;
+        }
+        if (!isRuntimeKey(key)) {
+            res.status(403).json({ error: `"${key}" is not editable` });
+            return;
+        }
+        // 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`,
+            });
+            return;
+        }
+        const body = req.body;
+        const rawValue = body?.value;
+        const check = validateRuntimeWrite(key, rawValue);
+        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",
+            });
+            return;
+        }
+        try {
+            const actor = actorOf(req);
+            await storage.setConfig(key, check.value, actor);
+            res.json({ ok: true, key, value: check.value });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : "Failed to write config",
+            });
+        }
+    });
+    return router;
+}
+/** Best-effort actor attribution for audit rows (no auth in dev → "dev"). */
+function actorOf(req) {
+    const header = req.header("x-enpilink-actor");
+    return typeof header === "string" && header.length > 0 ? header : "dev";
+}
+//# sourceMappingURL=router.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+/** Coerce an env string (or already-typed value) into a boolean. */
+export declare function coerceBool(raw: unknown): boolean | undefined;
+/** Coerce an env string (or number) into a finite number. */
+export declare function coerceNumber(raw: unknown): number | undefined;
+/**
+ * Bootstrap (env/file-only) settings. Not DB-editable. Defaults keep the
+ * framework off-by-default and secure-by-default.
+ */
+export declare const bootstrapSchema: z.ZodObject<{
+    storage: z.ZodDefault<z.ZodString>;
+    dbPath: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    admin: z.ZodDefault<z.ZodBoolean>;
+    adminAuthToken: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Runtime (DB-editable) settings. */
+export declare const runtimeSchema: z.ZodObject<{
+    "analytics.enabled": z.ZodDefault<z.ZodBoolean>;
+    "analytics.sampleRate": z.ZodDefault<z.ZodNumber>;
+    "retention.events": z.ZodDefault<z.ZodNumber>;
+    "retention.logs": z.ZodDefault<z.ZodNumber>;
+    "flags.liveLogs": z.ZodDefault<z.ZodBoolean>;
+    "display.bucketMs": z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const configSchema: z.ZodObject<{
+    storage: z.ZodDefault<z.ZodString>;
+    dbPath: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    admin: z.ZodDefault<z.ZodBoolean>;
+    adminAuthToken: z.ZodOptional<z.ZodString>;
+    "analytics.enabled": z.ZodDefault<z.ZodBoolean>;
+    "analytics.sampleRate": z.ZodDefault<z.ZodNumber>;
+    "retention.events": z.ZodDefault<z.ZodNumber>;
+    "retention.logs": z.ZodDefault<z.ZodNumber>;
+    "flags.liveLogs": z.ZodDefault<z.ZodBoolean>;
+    "display.bucketMs": z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type BootstrapConfig = z.infer<typeof bootstrapSchema>;
+export type RuntimeConfig = z.infer<typeof runtimeSchema>;
+export type Config = z.infer<typeof configSchema>;
+/** All known config keys. */
+export type ConfigKey = keyof Config;
+export type BootstrapKey = keyof BootstrapConfig;
+export type RuntimeKey = keyof RuntimeConfig;
+/** Per-key metadata describing tier / secret / env-lock semantics. */
+export interface KeyMeta {
+    key: ConfigKey;
+    /** `bootstrap` (env/file only) or `runtime` (DB-editable). */
+    tier: "bootstrap" | "runtime";
+    /** Secret keys are env-only and NEVER persisted/returned in plaintext. */
+    secret: boolean;
+    /** The env var that drives this key (for the "set via env" hint). */
+    env: string;
+}
+/** Bootstrap keys (env/file only). */
+export declare const BOOTSTRAP_KEYS: readonly ["storage", "dbPath", "port", "admin", "adminAuthToken"];
+/** Runtime keys (DB-editable). */
+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"];
+/**
+ * Env var mapping per key. Bootstrap keys map to dedicated env vars that match
+ * the framework's existing env surface; runtime keys use an
+ * `ENPILINK_CFG_<KEY>` convention so an operator can pin (env-lock) any runtime
+ * value without colliding with the bootstrap vars.
+ */
+export declare const ENV_VARS: Record<ConfigKey, string>;
+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;
+/** Metadata for every known key. */
+export declare function keyMeta(key: ConfigKey): KeyMeta;
+/** All keys with metadata. */
+export declare function allKeyMeta(): KeyMeta[];
+/** The per-key zod schema (for validating a single runtime write). */
+export declare function schemaForKey(key: ConfigKey): z.ZodTypeAny;

package/dist/server/config/schema.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+/**
+ * Config schema for enpilink's admin / control plane (M4).
+ *
+ * Settings are split into two tiers:
+ *
+ * - **Bootstrap** keys are env/file ONLY — they configure how the process
+ *   starts (storage engine, port, whether the prod admin is enabled, the admin
+ *   auth secret). They are NOT editable from the DB / admin UI. Some are
+ *   **secret** (`adminAuthToken`) and are never persisted to the DB nor
+ *   returned in plaintext by any API.
+ * - **Runtime** keys live in the DB and are editable from the Configuration
+ *   admin page (analytics on/off + sample rate, retention, feature flags,
+ *   display prefs). They still honour the env > file > db precedence so an
+ *   operator can pin a value via env/file and lock it in the UI.
+ *
+ * Resolution precedence is **env > file > db > default** (see `resolve.ts`).
+ */
+/** A boolean parsed from an env string: `1`/`true`/`yes`/`on` (ci) → true. */
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+const FALSY = new Set(["0", "false", "no", "off"]);
+/** Coerce an env string (or already-typed value) into a boolean. */
+export function coerceBool(raw) {
+    if (typeof raw === "boolean") {
+        return raw;
+    }
+    if (typeof raw === "string") {
+        const v = raw.trim().toLowerCase();
+        if (TRUTHY.has(v)) {
+            return true;
+        }
+        if (FALSY.has(v)) {
+            return false;
+        }
+    }
+    return undefined;
+}
+/** Coerce an env string (or number) into a finite number. */
+export function coerceNumber(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        return raw;
+    }
+    if (typeof raw === "string" && raw.trim() !== "") {
+        const n = Number(raw);
+        if (Number.isFinite(n)) {
+            return n;
+        }
+    }
+    return undefined;
+}
+/**
+ * Bootstrap (env/file-only) settings. Not DB-editable. Defaults keep the
+ * framework off-by-default and secure-by-default.
+ */
+export const bootstrapSchema = z.object({
+    /** Storage engine name (`memory` | `sqlite` | custom). */
+    storage: z.string().default("memory"),
+    /** SQLite database path (only meaningful for the sqlite engine). */
+    dbPath: z.string().default("./enpilink.db"),
+    /** HTTP port the server listens on. */
+    port: z.number().int().positive().default(3000),
+    /** Whether the production admin plane is enabled (M5). Off by default. */
+    admin: z.boolean().default(false),
+    /**
+     * Bearer token guarding the prod admin plane (M5). SECRET — env-only, never
+     * persisted to the DB nor returned in plaintext.
+     */
+    adminAuthToken: z.string().optional(),
+});
+/** Runtime (DB-editable) settings. */
+export const runtimeSchema = z.object({
+    /** Whether analytics/event capture is enabled. */
+    "analytics.enabled": z.boolean().default(false),
+    /** Fraction of requests sampled `[0, 1]`. */
+    "analytics.sampleRate": z.number().min(0).max(1).default(1),
+    /** Max events retained (retention cap). */
+    "retention.events": z.number().int().nonnegative().default(5000),
+    /** Max logs retained (retention cap). */
+    "retention.logs": z.number().int().nonnegative().default(5000),
+    /** Feature flag: expose the live log stream in the dashboard. */
+    "flags.liveLogs": z.boolean().default(true),
+    /** Display preference: dashboard time-bucket width (ms). */
+    "display.bucketMs": z.number().int().positive().default(60_000),
+});
+export const configSchema = bootstrapSchema.merge(runtimeSchema);
+/** Bootstrap keys (env/file only). */
+export const BOOTSTRAP_KEYS = [
+    "storage",
+    "dbPath",
+    "port",
+    "admin",
+    "adminAuthToken",
+];
+/** Runtime keys (DB-editable). */
+export const RUNTIME_KEYS = [
+    "analytics.enabled",
+    "analytics.sampleRate",
+    "retention.events",
+    "retention.logs",
+    "flags.liveLogs",
+    "display.bucketMs",
+];
+/** Secret keys: env-only, masked + never persisted/returned in plaintext. */
+export const SECRET_KEYS = [
+    "adminAuthToken",
+];
+/**
+ * Env var mapping per key. Bootstrap keys map to dedicated env vars that match
+ * the framework's existing env surface; runtime keys use an
+ * `ENPILINK_CFG_<KEY>` convention so an operator can pin (env-lock) any runtime
+ * value without colliding with the bootstrap vars.
+ */
+export const ENV_VARS = {
+    storage: "ENPILINK_STORAGE",
+    dbPath: "ENPILINK_DB_PATH",
+    port: "PORT",
+    admin: "ENPILINK_ADMIN",
+    adminAuthToken: "ENPILINK_ADMIN_TOKEN",
+    "analytics.enabled": "ENPILINK_ANALYTICS",
+    "analytics.sampleRate": "ENPILINK_CFG_ANALYTICS_SAMPLE_RATE",
+    "retention.events": "ENPILINK_CFG_RETENTION_EVENTS",
+    "retention.logs": "ENPILINK_CFG_RETENTION_LOGS",
+    "flags.liveLogs": "ENPILINK_CFG_FLAGS_LIVE_LOGS",
+    "display.bucketMs": "ENPILINK_CFG_DISPLAY_BUCKET_MS",
+};
+const SECRET_SET = new Set(SECRET_KEYS);
+const RUNTIME_SET = new Set(RUNTIME_KEYS);
+const BOOTSTRAP_SET = new Set(BOOTSTRAP_KEYS);
+export function isSecretKey(key) {
+    return SECRET_SET.has(key);
+}
+export function isRuntimeKey(key) {
+    return RUNTIME_SET.has(key);
+}
+export function isBootstrapKey(key) {
+    return BOOTSTRAP_SET.has(key);
+}
+export function isKnownKey(key) {
+    return RUNTIME_SET.has(key) || BOOTSTRAP_SET.has(key);
+}
+/** Metadata for every known key. */
+export function keyMeta(key) {
+    return {
+        key,
+        tier: isBootstrapKey(key) ? "bootstrap" : "runtime",
+        secret: isSecretKey(key),
+        env: ENV_VARS[key],
+    };
+}
+/** All keys with metadata. */
+export function allKeyMeta() {
+    return [...BOOTSTRAP_KEYS, ...RUNTIME_KEYS].map((k) => keyMeta(k));
+}
+/** The per-key zod schema (for validating a single runtime write). */
+export function schemaForKey(key) {
+    return (configSchema.shape[key] ?? z.unknown());
+}
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/server/config/schema.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\n/**\n * Config schema for enpilink's admin / control plane (M4).\n *\n * Settings are split into two tiers:\n *\n * - **Bootstrap** keys are env/file ONLY — they configure how the process\n *   starts (storage engine, port, whether the prod admin is enabled, the admin\n *   auth secret). They are NOT editable from the DB / admin UI. Some are\n *   **secret** (`adminAuthToken`) and are never persisted to the DB nor\n *   returned in plaintext by any API.\n * - **Runtime** keys live in the DB and are editable from the Configuration\n *   admin page (analytics on/off + sample rate, retention, feature flags,\n *   display prefs). They still honour the env > file > db precedence so an\n *   operator can pin a value via env/file and lock it in the UI.\n *\n * Resolution precedence is **env > file > db > default** (see `resolve.ts`).\n */\n\n/** A boolean parsed from an env string: `1`/`true`/`yes`/`on` (ci) → true. */\nconst TRUTHY = new Set([\"1\", \"true\", \"yes\", \"on\"]);\nconst FALSY = new Set([\"0\", \"false\", \"no\", \"off\"]);\n\n/** Coerce an env string (or already-typed value) into a boolean. */\nexport function coerceBool(raw: unknown): boolean | undefined {\n  if (typeof raw === \"boolean\") {\n    return raw;\n  }\n  if (typeof raw === \"string\") {\n    const v = raw.trim().toLowerCase();\n    if (TRUTHY.has(v)) {\n      return true;\n    }\n    if (FALSY.has(v)) {\n      return false;\n    }\n  }\n  return undefined;\n}\n\n/** Coerce an env string (or number) into a finite number. */\nexport function coerceNumber(raw: unknown): number | undefined {\n  if (typeof raw === \"number\" && Number.isFinite(raw)) {\n    return raw;\n  }\n  if (typeof raw === \"string\" && raw.trim() !== \"\") {\n    const n = Number(raw);\n    if (Number.isFinite(n)) {\n      return n;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Bootstrap (env/file-only) settings. Not DB-editable. Defaults keep the\n * framework off-by-default and secure-by-default.\n */\nexport const bootstrapSchema = z.object({\n  /** Storage engine name (`memory` | `sqlite` | custom). */\n  storage: z.string().default(\"memory\"),\n  /** SQLite database path (only meaningful for the sqlite engine). */\n  dbPath: z.string().default(\"./enpilink.db\"),\n  /** HTTP port the server listens on. */\n  port: z.number().int().positive().default(3000),\n  /** Whether the production admin plane is enabled (M5). Off by default. */\n  admin: z.boolean().default(false),\n  /**\n   * Bearer token guarding the prod admin plane (M5). SECRET — env-only, never\n   * persisted to the DB nor returned in plaintext.\n   */\n  adminAuthToken: z.string().optional(),\n});\n\n/** Runtime (DB-editable) settings. */\nexport const runtimeSchema = z.object({\n  /** Whether analytics/event capture is enabled. */\n  \"analytics.enabled\": z.boolean().default(false),\n  /** Fraction of requests sampled `[0, 1]`. */\n  \"analytics.sampleRate\": z.number().min(0).max(1).default(1),\n  /** Max events retained (retention cap). */\n  \"retention.events\": z.number().int().nonnegative().default(5000),\n  /** Max logs retained (retention cap). */\n  \"retention.logs\": z.number().int().nonnegative().default(5000),\n  /** Feature flag: expose the live log stream in the dashboard. */\n  \"flags.liveLogs\": z.boolean().default(true),\n  /** Display preference: dashboard time-bucket width (ms). */\n  \"display.bucketMs\": z.number().int().positive().default(60_000),\n});\n\nexport const configSchema = bootstrapSchema.merge(runtimeSchema);\n\nexport type BootstrapConfig = z.infer<typeof bootstrapSchema>;\nexport type RuntimeConfig = z.infer<typeof runtimeSchema>;\nexport type Config = z.infer<typeof configSchema>;\n\n/** All known config keys. */\nexport type ConfigKey = keyof Config;\nexport type BootstrapKey = keyof BootstrapConfig;\nexport type RuntimeKey = keyof RuntimeConfig;\n\n/** Per-key metadata describing tier / secret / env-lock semantics. */\nexport interface KeyMeta {\n  key: ConfigKey;\n  /** `bootstrap` (env/file only) or `runtime` (DB-editable). */\n  tier: \"bootstrap\" | \"runtime\";\n  /** Secret keys are env-only and NEVER persisted/returned in plaintext. */\n  secret: boolean;\n  /** The env var that drives this key (for the \"set via env\" hint). */\n  env: string;\n}\n\n/** Bootstrap keys (env/file only). */\nexport const BOOTSTRAP_KEYS = [\n  \"storage\",\n  \"dbPath\",\n  \"port\",\n  \"admin\",\n  \"adminAuthToken\",\n] as const satisfies readonly BootstrapKey[];\n\n/** Runtime keys (DB-editable). */\nexport const RUNTIME_KEYS = [\n  \"analytics.enabled\",\n  \"analytics.sampleRate\",\n  \"retention.events\",\n  \"retention.logs\",\n  \"flags.liveLogs\",\n  \"display.bucketMs\",\n] as const satisfies readonly RuntimeKey[];\n\n/** Secret keys: env-only, masked + never persisted/returned in plaintext. */\nexport const SECRET_KEYS = [\n  \"adminAuthToken\",\n] as const satisfies readonly ConfigKey[];\n\n/**\n * Env var mapping per key. Bootstrap keys map to dedicated env vars that match\n * the framework's existing env surface; runtime keys use an\n * `ENPILINK_CFG_<KEY>` convention so an operator can pin (env-lock) any runtime\n * value without colliding with the bootstrap vars.\n */\nexport const ENV_VARS: Record<ConfigKey, string> = {\n  storage: \"ENPILINK_STORAGE\",\n  dbPath: \"ENPILINK_DB_PATH\",\n  port: \"PORT\",\n  admin: \"ENPILINK_ADMIN\",\n  adminAuthToken: \"ENPILINK_ADMIN_TOKEN\",\n  \"analytics.enabled\": \"ENPILINK_ANALYTICS\",\n  \"analytics.sampleRate\": \"ENPILINK_CFG_ANALYTICS_SAMPLE_RATE\",\n  \"retention.events\": \"ENPILINK_CFG_RETENTION_EVENTS\",\n  \"retention.logs\": \"ENPILINK_CFG_RETENTION_LOGS\",\n  \"flags.liveLogs\": \"ENPILINK_CFG_FLAGS_LIVE_LOGS\",\n  \"display.bucketMs\": \"ENPILINK_CFG_DISPLAY_BUCKET_MS\",\n};\n\nconst SECRET_SET = new Set<string>(SECRET_KEYS);\nconst RUNTIME_SET = new Set<string>(RUNTIME_KEYS);\nconst BOOTSTRAP_SET = new Set<string>(BOOTSTRAP_KEYS);\n\nexport function isSecretKey(key: string): boolean {\n  return SECRET_SET.has(key);\n}\nexport function isRuntimeKey(key: string): key is RuntimeKey {\n  return RUNTIME_SET.has(key);\n}\nexport function isBootstrapKey(key: string): key is BootstrapKey {\n  return BOOTSTRAP_SET.has(key);\n}\nexport function isKnownKey(key: string): key is ConfigKey {\n  return RUNTIME_SET.has(key) || BOOTSTRAP_SET.has(key);\n}\n\n/** Metadata for every known key. */\nexport function keyMeta(key: ConfigKey): KeyMeta {\n  return {\n    key,\n    tier: isBootstrapKey(key) ? \"bootstrap\" : \"runtime\",\n    secret: isSecretKey(key),\n    env: ENV_VARS[key],\n  };\n}\n\n/** All keys with metadata. */\nexport function allKeyMeta(): KeyMeta[] {\n  return [...BOOTSTRAP_KEYS, ...RUNTIME_KEYS].map((k) => keyMeta(k));\n}\n\n/** The per-key zod schema (for validating a single runtime write). */\nexport function schemaForKey(key: ConfigKey): z.ZodTypeAny {\n  return (\n    (configSchema.shape as Record<string, z.ZodTypeAny>)[key] ?? z.unknown()\n  );\n}\n"]}