@suveren/gateway 0.12.0 → 0.13.0

package/lib/policy.mjs

@@ -0,0 +1,369 @@
+/**
+ * Managed-settings policy — IT-controlled overrides that an employee cannot
+ * change locally (W3 of the Windows installer track; see
+ * suveren-as/docs/work-plan.md, "Added 2026-10-02 — Windows installer").
+ *
+ * Sources, highest precedence first:
+ *   1. Windows registry `HKLM\SOFTWARE\Policies\Suveren\Gateway`, then
+ *      `HKCU\SOFTWARE\Policies\Suveren\Gateway` (HKLM wins over HKCU).
+ *      Read via `reg query` (child_process) — no native modules. Skipped
+ *      entirely on non-Windows.
+ *   2. A JSON file: `%ProgramData%\Suveren\gateway-policy.json` (Windows),
+ *      `/Library/Application Support/Suveren/gateway-policy.json` (macOS),
+ *      `/etc/suveren/gateway-policy.json` (Linux) — overridable for tests
+ *      via `SUVEREN_POLICY_FILE`.
+ *
+ * A key present in EITHER source is LOCKED: every resolver in this codebase
+ * (resolveAsUrl, resolveCaFile, resolvePinTls, resolveProxyUrl,
+ * resolveSimulation / isSimulationMode) must return the policy value
+ * regardless of env var, saved config.json, or CLI flag — see those
+ * modules' own doc comments for where this is wired in. Overall precedence:
+ * policy > env > saved config > defaults.
+ *
+ * `Proxy` is the one key that OVERRIDES an environment variable rather than
+ * merely out-ranking a saved value: on a Windows company laptop the proxy is
+ * set in system settings, not `HTTP_PROXY`/`HTTPS_PROXY` — see
+ * bundle/server.js, which sets both env vars from the policy value
+ * unconditionally when `Proxy` is locked (every other locked key has no env
+ * tier to override in the first place). `NoProxy` is read the same way but
+ * has no saved-config/CLI counterpart at all — NO_PROXY stays env-only
+ * except for this one override.
+ *
+ * Registry value names = JSON file keys (PascalCase, matching what an IT
+ * admin would see in either place): AsUrl, CaFile, PinTls, Proxy, NoProxy,
+ * Simulation, InstallMethod.
+ *
+ * Mirrored (same logic, duplicated — no shared runtime package between the
+ * CLI and the two apps, see config.mjs's doc comment for the established
+ * pattern) in `apps/mcp-server/src/lib/policy.ts` and
+ * `apps/control-plane/src/lib/policy.ts`. Keep all three in step.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const POLICY_KEYS = ['AsUrl', 'CaFile', 'PinTls', 'Proxy', 'NoProxy', 'Simulation', 'InstallMethod'];
+
+/** The documented production path, relative to the hive — never changes for
+ *  a real install. Overridable ONLY via `SUVEREN_POLICY_REGISTRY_KEY`, which
+ *  exists purely so `gateway-policy-windows-registry.test.ts` can point at a
+ *  unique per-run key instead of the real one: `pnpm -r test` runs every
+ *  workspace package in parallel, so a test writing to the REAL key would
+ *  race every OTHER package's tests reading the real registry on the same
+ *  Windows CI runner at the same time (this raced in practice — see
+ *  `SUVEREN_POLICY_REGISTRY` below for the other half of the fix). */
+const DEFAULT_REGISTRY_BASE_KEY = 'SOFTWARE\\Policies\\Suveren\\Gateway';
+
+/** The full `HIVE\base\key` path `reg query`/`reg add` operate on. A pure
+ *  function (no I/O) so a test can assert the default without mocking
+ *  anything — see gateway-policy.test.ts's "documented default paths". */
+export function registryKeyPath(hive) {
+  const baseKey = process.env.SUVEREN_POLICY_REGISTRY_KEY || DEFAULT_REGISTRY_BASE_KEY;
+  return `${hive}\\${baseKey}`;
+}
+
+/**
+ * Validate + normalize a candidate Authority Server URL — the SAME rule
+ * `config set as-url` enforces (see config.mjs's validateAsUrl), duplicated
+ * rather than imported so this module has no dependency on config.mjs (the
+ * TS mirrors of each live in different files entirely).
+ */
+function validateAsUrl(candidate) {
+  const trimmed = (candidate ?? '').trim();
+  if (!trimmed) return { ok: false, error: 'The Authority Server URL is empty.' };
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, error: `"${trimmed}" is not a valid URL.` };
+  }
+  const isLocalHttp =
+    parsed.protocol === 'http:' && (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1');
+  if (parsed.protocol !== 'https:' && !isLocalHttp) {
+    return {
+      ok: false,
+      error: `"${trimmed}" must use https:// (http:// is only allowed for http://localhost or http://127.0.0.1).`,
+    };
+  }
+  let normalized = `${parsed.origin}${parsed.pathname}${parsed.search}${parsed.hash}`;
+  if (normalized.endsWith('/') && normalized !== `${parsed.origin}/`) {
+    normalized = normalized.slice(0, -1);
+  } else if (normalized === `${parsed.origin}/`) {
+    normalized = parsed.origin;
+  }
+  return { ok: true, url: normalized };
+}
+
+/** Same rule as config.mjs's validateCaFile: must exist on disk. Resolved
+ *  against cwd like the CLI flag is — a policy-set relative path is
+ *  unusual, but behaving consistently with `config set ca-file` beats a
+ *  second rule nobody remembers. */
+function validateCaFile(candidate) {
+  const trimmed = (candidate ?? '').trim();
+  if (!trimmed) return { ok: false, error: 'The CA file path is empty.' };
+  if (!existsSync(trimmed)) return { ok: false, error: `No file at "${trimmed}".` };
+  return { ok: true, path: trimmed };
+}
+
+/** Same rule as config.mjs's validateProxyUrl: http:// or https:// only. */
+function validateProxyUrl(candidate) {
+  const trimmed = (candidate ?? '').trim();
+  if (!trimmed) return { ok: false, error: 'The proxy URL is empty.' };
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, error: `"${trimmed}" is not a valid URL.` };
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { ok: false, error: `"${trimmed}" must use http:// or https://.` };
+  }
+  return { ok: true, url: trimmed };
+}
+
+/** Accepts a JSON boolean, or the DWORD-style 0/1 (as a number OR a string,
+ *  since the registry parser below hands back numbers but a hand-edited
+ *  JSON file might use either). Returns undefined — not a default — for
+ *  anything else, so the caller can tell "not a boolean" from "false". */
+function coerceBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (value === 0) return false;
+    if (value === 1) return true;
+    return undefined;
+  }
+  if (typeof value === 'string') {
+    const v = value.trim().toLowerCase();
+    if (v === 'true' || v === '1') return true;
+    if (v === 'false' || v === '0') return false;
+  }
+  return undefined;
+}
+
+// ─── Registry (Windows only) ────────────────────────────────────────────
+
+/**
+ * Parse `reg query "HKLM\...\Gateway"` stdout. Real output looks like:
+ *
+ *   HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Suveren\Gateway
+ *       AsUrl    REG_SZ    https://as.company.internal
+ *       PinTls    REG_DWORD    0x1
+ *
+ * Value lines are 4-space-indented; columns are separated by runs of
+ * whitespace. REG_DWORD values print as hex ("0x1"), parsed to a number
+ * here so coerceBoolean can treat it like any other 0/1.
+ */
+export function parseRegQueryOutput(stdout) {
+  const out = {};
+  const lineRe = /^ {4}(\S+)\s+(REG_SZ|REG_EXPAND_SZ|REG_DWORD|REG_QWORD|REG_BINARY|REG_MULTI_SZ)\s+(.*)$/;
+  for (const line of stdout.split(/\r?\n/)) {
+    const m = lineRe.exec(line);
+    if (!m) continue;
+    const [, name, type, rawValue] = m;
+    if (!POLICY_KEYS.includes(name)) continue;
+    if (type === 'REG_DWORD' || type === 'REG_QWORD') {
+      out[name] = parseInt(rawValue, 16);
+    } else {
+      out[name] = rawValue;
+    }
+  }
+  return out;
+}
+
+/** `{ values, source }` for one registry hive, or `{ values: {}, source }`
+ *  on any failure (key absent — the normal "no policy set" case — missing
+ *  `reg` binary, or a platform that isn't Windows at all). Never throws:
+ *  an operator without IT policy must see the gateway behave exactly as it
+ *  always has.
+ *
+ *  `SUVEREN_POLICY_REGISTRY=off` skips the registry entirely, returning
+ *  `{}` without even spawning `reg` — unit tests set this globally (see
+ *  each app's vitest setup) so a real IT policy on the machine running the
+ *  suite, or another package's test writing to the registry concurrently,
+ *  cannot change what these tests see. Production never sets this. */
+function readRegistryHive(hive) {
+  const path = registryKeyPath(hive);
+  const source = `the registry policy (${path})`;
+  // Checked BEFORE the platform branch so the switch is testable on any OS,
+  // not just Windows — see gateway-policy.test.ts.
+  if (process.env.SUVEREN_POLICY_REGISTRY === 'off') return { values: {}, source };
+  if (process.platform !== 'win32') return { values: {}, source };
+  let result;
+  try {
+    result = spawnSync('reg', ['query', path], { encoding: 'utf8' });
+  } catch {
+    return { values: {}, source };
+  }
+  if (!result || result.status !== 0 || !result.stdout) return { values: {}, source };
+  return { values: parseRegQueryOutput(result.stdout), source };
+}
+
+// ─── Policy file ────────────────────────────────────────────────────────
+
+export function policyFilePath() {
+  if (process.env.SUVEREN_POLICY_FILE) return process.env.SUVEREN_POLICY_FILE;
+  if (process.platform === 'win32') {
+    const programData = process.env.ProgramData || process.env.PROGRAMDATA || 'C:\\ProgramData';
+    return join(programData, 'Suveren', 'gateway-policy.json');
+  }
+  if (process.platform === 'darwin') {
+    return '/Library/Application Support/Suveren/gateway-policy.json';
+  }
+  return '/etc/suveren/gateway-policy.json';
+}
+
+/** Throws (fail closed, audibly — same rule as config.mjs's
+ *  readConfigStrict) when the file exists but is not valid JSON. A missing
+ *  file is the normal "no policy set" case and returns `{}`. */
+function readPolicyFile() {
+  const path = policyFilePath();
+  const source = `the policy file (${path})`;
+  if (!existsSync(path)) return { values: {}, source };
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`Could not parse policy file ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const values = {};
+  for (const key of POLICY_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(data, key)) values[key] = data[key];
+  }
+  return { values, source };
+}
+
+// ─── Merge + validate ───────────────────────────────────────────────────
+
+/** First entry (in precedence order) that defines each key wins. Returns
+ *  the merged raw values plus, per key, which source they came from (for
+ *  error messages). */
+function mergeBySource(entries) {
+  const merged = {};
+  const sourceOf = {};
+  for (const key of POLICY_KEYS) {
+    for (const entry of entries) {
+      if (Object.prototype.hasOwnProperty.call(entry.values, key) && entry.values[key] !== undefined) {
+        merged[key] = entry.values[key];
+        sourceOf[key] = entry.source;
+        break;
+      }
+    }
+  }
+  return { merged, sourceOf };
+}
+
+let cached = null;
+
+/**
+ * Read + validate the effective policy. Memoized for the life of the
+ * process (registry reads spawn a child process — doing that on every
+ * `isSimulationMode()` call, which runs per tool call, would be a
+ * synchronous fork on the hot path). Policy changes take effect on the next
+ * restart anyway, same as every other setting here — see
+ * `_resetPolicyCacheForTests` for the one case that needs otherwise.
+ *
+ * Throws a named error — mentioning the key, the offending value, and which
+ * source it came from — on an invalid value, exactly like a bad `config
+ * set` input (see config.mjs's resolveAsUrl doc comment on failing closed
+ * and audibly rather than silently falling back).
+ */
+export function readPolicy() {
+  if (cached) return cached;
+
+  const hklm = readRegistryHive('HKLM');
+  const hkcu = readRegistryHive('HKCU');
+  const file = readPolicyFile(); // may throw — propagated, not swallowed
+
+  const { merged, sourceOf } = mergeBySource([hklm, hkcu, file]);
+
+  const policy = {};
+  const locked = new Set();
+
+  if (merged.AsUrl !== undefined) {
+    const v = validateAsUrl(String(merged.AsUrl));
+    if (!v.ok) {
+      throw new Error(`Invalid policy AsUrl ("${merged.AsUrl}") from ${sourceOf.AsUrl}: ${v.error}`);
+    }
+    policy.asUrl = v.url;
+    locked.add('asUrl');
+  }
+
+  if (merged.CaFile !== undefined) {
+    const v = validateCaFile(String(merged.CaFile));
+    if (!v.ok) {
+      throw new Error(`Invalid policy CaFile ("${merged.CaFile}") from ${sourceOf.CaFile}: ${v.error}`);
+    }
+    policy.caFile = v.path;
+    locked.add('caFile');
+  }
+
+  if (merged.PinTls !== undefined) {
+    const b = coerceBoolean(merged.PinTls);
+    if (b === undefined) {
+      throw new Error(
+        `Invalid policy PinTls ("${merged.PinTls}") from ${sourceOf.PinTls}: must be a boolean or 0/1.`,
+      );
+    }
+    policy.pinTls = b;
+    locked.add('pinTls');
+  }
+
+  if (merged.Proxy !== undefined) {
+    const v = validateProxyUrl(String(merged.Proxy));
+    if (!v.ok) {
+      throw new Error(`Invalid policy Proxy ("${merged.Proxy}") from ${sourceOf.Proxy}: ${v.error}`);
+    }
+    policy.proxy = v.url;
+    locked.add('proxy');
+  }
+
+  // NoProxy has no saved-config/CLI counterpart — just a string, no URL
+  // shape to validate (it's a NO_PROXY-style hostname list, same grammar as
+  // the env var itself).
+  if (merged.NoProxy !== undefined) {
+    const raw = String(merged.NoProxy).trim();
+    if (!raw) {
+      throw new Error(`Invalid policy NoProxy ("${merged.NoProxy}") from ${sourceOf.NoProxy}: must not be empty.`);
+    }
+    policy.noProxy = raw;
+    locked.add('noProxy');
+  }
+
+  if (merged.Simulation !== undefined) {
+    const b = coerceBoolean(merged.Simulation);
+    if (b === undefined) {
+      throw new Error(
+        `Invalid policy Simulation ("${merged.Simulation}") from ${sourceOf.Simulation}: must be a boolean or 0/1.`,
+      );
+    }
+    policy.simulation = b;
+    locked.add('simulation');
+  }
+
+  if (merged.InstallMethod !== undefined) {
+    const raw = String(merged.InstallMethod).trim().toLowerCase();
+    if (raw !== 'managed') {
+      throw new Error(
+        `Invalid policy InstallMethod ("${merged.InstallMethod}") from ${sourceOf.InstallMethod}: only "managed" is supported.`,
+      );
+    }
+    policy.installMethod = 'managed';
+    locked.add('installMethod');
+  }
+
+  cached = { policy, locked };
+  return cached;
+}
+
+/** Convenience: is this one key locked by policy? */
+export function isPolicyLocked(key) {
+  return readPolicy().locked.has(key);
+}
+
+/** Drop the memoized policy so the next `readPolicy()` call re-reads the
+ *  registry/file. Test-only — a real process never needs this, since
+ *  policy is only ever consulted again after a restart. */
+export function _resetPolicyCacheForTests() {
+  cached = null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suveren/gateway",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Suveren gateway — local agent gateway built in compliance with the Human Agency Protocol (HAP). Runs the UI, control plane, and MCP server in one Node process.",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -12,7 +12,8 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir, constants as osConstants } from 'node:os';
 import { existsSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
-import { resolveCaFile, resolveSimulation } from './lib/config.mjs';
+import { resolveCaFile, resolveProxyUrl, resolveSimulation } from './lib/config.mjs';
+import { readPolicy, isPolicyLocked } from './lib/policy.mjs';
 import { unsupportedNodeReason } from './lib/node-version.mjs';
 
 // Docker and the login service start this file directly, not through the CLI,
@@ -121,6 +122,43 @@ if (savedCaFile && !process.env.SUVEREN_CA_REEXEC_DONE) {
 // via `...process.env`, all the way down to individual integrations.
 delete process.env.SUVEREN_CA_REEXEC_DONE;
 
+// ─── Corporate proxy (`config set proxy <url>` / `--proxy` / IT policy) ────
+//
+// `HTTP_PROXY`/`HTTPS_PROXY` are read fresh on every outbound call (see
+// proxy-env.ts in both apps) — unlike NODE_EXTRA_CA_CERTS above, there is no
+// Node-startup-time requirement, so no re-exec dance is needed here.
+//
+// Two different precedence rules apply, because `resolveProxyUrl` already
+// folds IT policy ahead of the saved value (see config.mjs):
+//   - IT policy LOCKED (`Proxy` — see lib/policy.mjs): OVERRIDES an
+//     operator's own HTTP_PROXY/HTTPS_PROXY unconditionally — "locked"
+//     means locked even against a pre-existing env var, the one case among
+//     all the policy-able settings where there IS a meaningful env tier to
+//     override (every other locked key has none to begin with). This is
+//     the Windows-company-laptop case: the proxy lives in system settings,
+//     not an env var an employee thinks to set.
+//   - Otherwise (a plain saved `config set proxy`): fills in whichever of
+//     HTTP_PROXY/HTTPS_PROXY is still unset — an operator's own value
+//     always wins, same as every other env-vs-saved precedence here.
+const resolvedProxyUrl = resolveProxyUrl(DATA_DIR);
+if (resolvedProxyUrl) {
+  if (isPolicyLocked('proxy')) {
+    process.env.HTTP_PROXY = resolvedProxyUrl;
+    process.env.HTTPS_PROXY = resolvedProxyUrl;
+  } else {
+    process.env.HTTP_PROXY ??= resolvedProxyUrl;
+    process.env.HTTPS_PROXY ??= resolvedProxyUrl;
+  }
+}
+
+// `NoProxy` has no saved-config/CLI counterpart at all (see policy.mjs) —
+// NO_PROXY stays env-only except for this one IT-policy override, which (like
+// `Proxy` above) overrides an operator's own NO_PROXY unconditionally when set.
+const policyNoProxy = readPolicy().policy.noProxy;
+if (policyNoProxy) {
+  process.env.NO_PROXY = policyNoProxy;
+}
+
 const CP_PORT = process.env.SUVEREN_CP_PORT ?? '3400';
 const MCP_PORT = process.env.SUVEREN_MCP_PORT ?? '3430';
 const UI_DIST = process.env.HAP_UI_DIST ?? join(__dirname, 'dist', 'ui');
@@ -147,13 +185,18 @@ const env = {
   SUVEREN_PROFILES_DIR: PROFILES_DIR,
   // Single shared internal secret so CP↔MCP authenticate the bridge.
   SUVEREN_INTERNAL_SECRET: process.env.SUVEREN_INTERNAL_SECRET ?? randomHex(32),
-  // Simulation mode — same precedence as the CA bundle above: an explicit env
-  // var (set directly, or by `start --simulation` setting process.env for
-  // THIS run — see bundle/bin/suveren-gateway.js) wins; otherwise the saved
-  // config.json value, which is what `suveren-gateway simulation on|off`
-  // changes for every future start/restart, including autostart (which
-  // spawns this file directly, bypassing the CLI's own flag handling).
-  SUVEREN_SIMULATION: process.env.SUVEREN_SIMULATION ?? (resolveSimulation(DATA_DIR) ? '1' : '0'),
+  // Simulation mode — IT policy (see lib/policy.mjs) wins UNCONDITIONALLY,
+  // ahead of even an explicit env var: that is what "locked" means. Below
+  // that: an explicit env var (set directly, or by `start --simulation`
+  // setting process.env for THIS run — see bundle/bin/suveren-gateway.js)
+  // wins; otherwise the saved config.json value, which is what
+  // `suveren-gateway simulation on|off` changes for every future
+  // start/restart, including autostart (which spawns this file directly,
+  // bypassing the CLI's own flag handling).
+  SUVEREN_SIMULATION:
+    readPolicy().policy.simulation !== undefined
+      ? (readPolicy().policy.simulation ? '1' : '0')
+      : (process.env.SUVEREN_SIMULATION ?? (resolveSimulation(DATA_DIR) ? '1' : '0')),
   // Passed by the login service (see bundle/lib/autostart-templates.mjs) so the
   // control-plane knows a human is NOT sitting in front of a terminal watching
   // it start — that is when a locked gateway needs to announce itself.