@pleri/olam-cli 0.1.7

package/host-cp/src/process-poller.mjs

@@ -0,0 +1,250 @@
+/**
+ * process-poller.mjs — per-world docker top SSE fanout.
+ *
+ * Dual-mode: HTTP API when DOCKER_HOST != 'docker-cli'; spawnSync otherwise.
+ *
+ * NOTE: process argv may contain secrets (--api-key=, --token=). Post-v1 audit needed. (S1)
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const DOCKER_HOST = process.env.DOCKER_HOST ?? 'docker-cli';
+
+/**
+ * @typedef {{ pid: string, user: string, cpu: string, mem: string, started: string, state: string, command: string }} ProcessRow
+ */
+
+function worldContainerName(worldId) {
+  return `olam-${worldId}-devbox`;
+}
+
+/**
+ * Parse docker top JSON (Titles + Processes arrays) into normalized rows.
+ * Falls back gracefully if the response is not JSON.
+ * lstart is stored as a raw string — no Date parse (T1).
+ *
+ * @param {string} stdout
+ * @returns {ProcessRow[]}
+ */
+function parseDockerTop(stdout) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+
+  const titles = parsed?.Titles;
+  const processes = parsed?.Processes;
+  if (!Array.isArray(titles) || !Array.isArray(processes)) return [];
+
+  // Find column indices by title (case-insensitive partial match).
+  function idx(name) {
+    const n = name.toLowerCase();
+    const i = titles.findIndex((t) => typeof t === 'string' && t.toLowerCase().includes(n));
+    return i;
+  }
+
+  const pidIdx = idx('pid');
+  const userIdx = idx('user');
+  const cpuIdx = idx('cpu');
+  const memIdx = idx('mem');
+  // Accept LSTART, STARTED, STIME, or START_TIME (T1: store as raw string)
+  const startIdx = (() => {
+    for (const candidate of ['lstart', 'stime', 'start_time', 'start']) {
+      const i = idx(candidate);
+      if (i !== -1) return i;
+    }
+    return -1;
+  })();
+  const stateIdx = idx('stat');
+  const cmdIdx = (() => {
+    // CMD may be titled "CMD", "COMMAND", or "cmd"
+    const i = idx('command');
+    return i !== -1 ? i : idx('cmd');
+  })();
+
+  return processes.map((row) => ({
+    pid: pidIdx !== -1 ? String(row[pidIdx] ?? '').trim() : '',
+    user: userIdx !== -1 ? String(row[userIdx] ?? '').trim() : '',
+    cpu: cpuIdx !== -1 ? String(row[cpuIdx] ?? '').trim() : '0',
+    mem: memIdx !== -1 ? String(row[memIdx] ?? '').trim() : '0',
+    started: startIdx !== -1 ? String(row[startIdx] ?? '').trim() : '',
+    state: stateIdx !== -1 ? String(row[stateIdx] ?? '').trim() : '',
+    command: cmdIdx !== -1 ? String(row[cmdIdx] ?? '').trim() : '',
+  }));
+}
+
+/**
+ * Fetch processes for a world container.
+ * Returns {ts, processes, error?}.
+ * Non-running containers return an empty array + error field (T3).
+ *
+ * @param {string} worldId
+ * @returns {Promise<{ts: number, processes: ProcessRow[], error?: string}>}
+ */
+async function fetchProcesses(worldId) {
+  const containerName = worldContainerName(worldId);
+  // Docker's /containers/<name>/top?ps_args=<X> passes ps_args verbatim to
+  // ps(1) inside the container. The pre-2026-05-05 form `pid,user,...` was
+  // a bare comma-separated list that ps treats as a process-ID *list*, not
+  // a column selector — yielding 500 "ps: error: process ID list syntax
+  // error" from the Docker API and a misleading "container not running"
+  // chip in the SPA. Correct invocation is `ps -eo <cols>` to select all
+  // processes (`-e`) and project specific columns (`-o`). Confirmed via
+  // host-cp container against olam-dawn-arc-5703-devbox: this form returns
+  // 200 with both Titles + Processes arrays, which parseDockerTop expects.
+  //
+  // Switched lstart → stime to match the CLI path's column choice (line 98)
+  // and avoid multi-word timestamp values; the CLI path's split-on-1+ws
+  // parser would break on "Mon May 4 14:00:00 2026", and consistency between
+  // paths reduces surprise. parseDockerTop accepts either via title match.
+  const ps_args = '-eo pid,user,pcpu,pmem,stime,stat,cmd';
+
+  let stdout;
+  try {
+    if (DOCKER_HOST === 'docker-cli') {
+      // Bare-node mode: spawnSync blocks ~50ms at 5s cadence (P2 — acceptable).
+      // Use `stime` (single-word start time) instead of `lstart` to avoid
+      // multi-word timestamp values that break column-split parsing.
+      const result = spawnSync(
+        'docker',
+        ['top', containerName, 'pid', 'user', 'pcpu', 'pmem', 'stime', 'stat', 'cmd'],
+        { encoding: 'utf-8', timeout: 3000 },
+      );
+      if (result.status !== 0 || result.error) {
+        return { ts: Date.now(), processes: [], error: 'container not running' };
+      }
+      // docker top bare CLI outputs tabular text, not JSON. Wrap it for parseDockerTop.
+      stdout = result.stdout ?? '';
+      const lines = stdout.trim().split('\n');
+      if (lines.length < 1) return { ts: Date.now(), processes: [] };
+      // First line is the header row; remaining are process rows.
+      // stime is always a single word (e.g. "10:00" or "Feb11"), so splitting
+      // on 1+ whitespace is safe.
+      const titleFields = lines[0].trim().split(/\s+/);
+      const dataRows = lines.slice(1).map((line) => {
+        const parts = line.trim().split(/\s+/);
+        // CMD may contain spaces — rejoin everything after the 7th token.
+        if (parts.length > 7) {
+          return [...parts.slice(0, 6), parts.slice(6).join(' ')];
+        }
+        return parts;
+      });
+      const wrapped = JSON.stringify({ Titles: titleFields, Processes: dataRows });
+      return { ts: Date.now(), processes: parseDockerTop(wrapped) };
+    } else {
+      // Container mode: Docker HTTP API.
+      const apiBase = DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
+      const url = `${apiBase}/containers/${encodeURIComponent(containerName)}/top?ps_args=${encodeURIComponent(ps_args)}`;
+      const resp = await fetch(url, { signal: AbortSignal.timeout(3000) });
+      if (!resp.ok) {
+        return { ts: Date.now(), processes: [], error: 'container not running' };
+      }
+      stdout = await resp.text();
+      return { ts: Date.now(), processes: parseDockerTop(stdout) };
+    }
+  } catch {
+    return { ts: Date.now(), processes: [], error: 'container not running' };
+  }
+}
+
+/**
+ * Snapshot — thin wrapper over fetchProcesses.
+ *
+ * @param {string} worldId
+ */
+export async function getProcessSnapshot(worldId) {
+  return fetchProcesses(worldId);
+}
+
+// ── SSE fanout state ─────────────────────────────────────────────────
+
+/**
+ * Per-world subscriber registry.
+ * @type {Map<string, {pollTimer: ReturnType<typeof setInterval>, heartbeatTimer: ReturnType<typeof setInterval>, subscribers: Set<import('node:http').ServerResponse>}>}
+ */
+const worldPollers = new Map();
+
+/**
+ * Broadcast a payload to all subscribers for a world.
+ * @param {string} worldId
+ * @param {{ts: number, processes: ProcessRow[], error?: string}} data
+ */
+function broadcast(worldId, data) {
+  const entry = worldPollers.get(worldId);
+  if (!entry) return;
+  const payload = `event: processes\ndata: ${JSON.stringify(data)}\n\n`;
+  for (const res of entry.subscribers) {
+    try { res.write(payload); } catch { /* subscriber gone; cleanup fires on close */ }
+  }
+}
+
+/**
+ * Subscribe an SSE response to the world's process stream.
+ *
+ * SSE headers are written BEFORE adding to the Set (T2: prevents leak if close
+ * fires before headers are flushed — the cleanup handler is safe to call even
+ * with an empty Set).
+ *
+ * @param {string} worldId
+ * @param {import('node:http').ServerResponse} res
+ */
+export function subscribeToProcesses(worldId, res) {
+  // Write SSE headers synchronously before touching the subscriber Set (T2).
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  });
+
+  let entry = worldPollers.get(worldId);
+
+  if (!entry) {
+    // First subscriber — start the poll + heartbeat timers.
+    const pollTimer = setInterval(async () => {
+      const data = await fetchProcesses(worldId);
+      broadcast(worldId, data);
+    }, 5000);
+
+    const heartbeatTimer = setInterval(() => {
+      const e = worldPollers.get(worldId);
+      if (!e) return;
+      for (const r of e.subscribers) {
+        try { r.write(': heartbeat\n\n'); } catch { /* ignore */ }
+      }
+    }, 25000);
+
+    entry = { pollTimer, heartbeatTimer, subscribers: new Set() };
+    worldPollers.set(worldId, entry);
+  }
+
+  entry.subscribers.add(res);
+
+  // Send an immediate first snapshot so the client doesn't wait 5s.
+  fetchProcesses(worldId).then((data) => {
+    try { res.write(`event: processes\ndata: ${JSON.stringify(data)}\n\n`); } catch { /* gone */ }
+  });
+
+  // Cleanup on disconnect — mirrors wireRelease pattern with once-flag.
+  let cleaned = false;
+  function cleanup() {
+    if (cleaned) return;
+    cleaned = true;
+    const e = worldPollers.get(worldId);
+    if (!e) return;
+    e.subscribers.delete(res);
+    if (e.subscribers.size === 0) {
+      clearInterval(e.pollTimer);
+      clearInterval(e.heartbeatTimer);
+      worldPollers.delete(worldId);
+    }
+  }
+
+  res.on('close', cleanup);
+  res.on('finish', cleanup);
+}
+
+// Export parseDockerTop for unit tests.
+export { parseDockerTop };

package/host-cp/src/proxy.mjs

@@ -0,0 +1,245 @@
+// Phase F-2-B (B3): host CP HTTP proxy.
+//
+// Rewrites incoming requests under `/api/world/<id>/<route...>` to the
+// per-world CP at `<perWorldBase>/<route...>` with `X-Olam-Secret`
+// injected server-side.
+//
+// Pattern lifted from `packages/cloudflare-worker/src/index.ts:462-551`
+// (`proxyContainer`). CF Worker uses Workers' `fetch()`; host CP uses
+// Node's `http.request` so SSE streams flow byte-for-byte without
+// buffering. Verbatim passthrough on /hooks/* and /api/auth/* (D8) is
+// implemented in B4 (this module is JSON-API-only — B4 wraps).
+
+import http from 'node:http';
+
+/**
+ * Default upstream-request timeout for proxied per-world CP calls. SSE
+ * streams (`/api/stream`, `/hooks/*` long-poll) MUST opt out — they
+ * intentionally hold the socket open. Everything else should respond
+ * within a few seconds; if the per-world CP wedges (slow sqlite,
+ * tmux command stuck, long docker exec), this prevents the host-cp
+ * connection from hanging until the OS RSTs it. The browser sees a
+ * clean 504 instead of Safari's TypeError "Load failed", and useLanes /
+ * useReadiness can retry on a known status code.
+ *
+ * 10s matches the longest legitimate handler we've measured (cold
+ * sqlite open + readiness query) with headroom.
+ *
+ * @internal exported for test override
+ */
+export const DEFAULT_PROXY_TIMEOUT_MS = 10_000;
+
+/**
+ * Parse `/api/world/<id>/<route...>` from a request path. Returns
+ * `{ worldId, subPath }` or null if the path doesn't match.
+ *
+ * Anchored at `^/api/world/` to prevent prefix-matching from /api/worlds
+ * (the worlds-list endpoint, plural). Empty world IDs do not match.
+ *
+ * @param {string} path
+ * @returns {{ worldId: string, subPath: string } | null}
+ */
+export function parseProxyPath(path) {
+  const m = /^\/api\/world\/([^/?#]+)(\/.*|\?.*|#.*)?$/.exec(path);
+  if (!m) return null;
+  return {
+    worldId: m[1],
+    subPath: m[2] ?? '/',
+  };
+}
+
+/**
+ * Compute the per-world CP's base URL from a worldId. Today the world
+ * registry stores port offsets; the canonical port is `19080 + offset`.
+ * For B3, accept the port directly (deferring worlds.db integration to
+ * B6/B10). The caller (server.mjs) resolves worldId → port via worlds.db
+ * and passes the port here.
+ *
+ * In Docker Compose mode, host-cp is in its own network and reaches
+ * world CPs via `host.docker.internal:<port>` (compose.yaml's
+ * extra_hosts: host-gateway). On Docker Desktop this is automatic;
+ * on Linux it requires the `host-gateway` extra-host directive.
+ *
+ * @param {number} port  per-world CP host port (e.g., 20780)
+ * @param {string} [host]  optional hostname override (default 'host.docker.internal')
+ * @returns {string}
+ */
+export function perWorldBase(port, host = 'host.docker.internal') { // bare-node-allow: container-mode default; bare callers pass WORLD_HOST explicitly (server.mjs)
+  return `http://${host}:${port}`;
+}
+
+/**
+ * SSE / long-poll paths whose handlers intentionally hold the socket
+ * open. These MUST be exempt from the upstream timeout — applying it
+ * would kill the stream every 10s. Caller can override per-request via
+ * `streaming: true`.
+ *
+ * @param {string} subPath
+ * @returns {boolean}
+ */
+function isStreamingPath(subPath) {
+  // Strip query string before matching.
+  const p = subPath.split('?')[0];
+  return (
+    p === '/api/stream' ||
+    p.endsWith('/api/stream') ||
+    p.startsWith('/hooks/') ||
+    p === '/hooks' ||
+    /^\/api\/auth\/events(\/|$)/.test(p)
+  );
+}
+
+/**
+ * Proxy an incoming request to a per-world CP, injecting X-Olam-Secret.
+ *
+ * Forwards: method, path (subPath), body bytes, ALL request headers
+ * EXCEPT `host` (rewritten) and `x-olam-secret` (overwritten with the
+ * injected secret to prevent client spoofing).
+ *
+ * Returns: status code, ALL response headers (verbatim — D8 contract
+ * forwards Set-Cookie, Location, etc. unchanged), body bytes streamed
+ * via Node's http.IncomingMessage→ServerResponse pipe (no buffering).
+ *
+ * Upstream timeout: short-request handlers (≠ SSE) get an upstream
+ * socket timeout of `timeoutMs` (defaults to DEFAULT_PROXY_TIMEOUT_MS).
+ * On expiry we abort the upstream socket and respond 504 — this
+ * converts a wedged per-world CP into a deterministic status code
+ * instead of a TCP RST that Safari surfaces as `TypeError: Load
+ * failed`. Pass `streaming: true` (or hit a path matching
+ * `isStreamingPath`) to opt out.
+ *
+ * @param {object} args
+ * @param {import('node:http').IncomingMessage} args.req
+ * @param {import('node:http').ServerResponse} args.res
+ * @param {string} args.subPath              e.g., '/api/world' or '/api/stream'
+ * @param {string} args.targetBase           e.g., 'http://host.docker.internal:20780'
+ * @param {string} args.secret               the X-Olam-Secret value
+ * @param {(message: string) => void} [args.log]
+ * @param {number} [args.timeoutMs]          per-request upstream timeout; ignored for streams
+ * @param {boolean} [args.streaming]         force SSE/long-poll mode (skip timeout)
+ */
+export function proxyToWorld({
+  req,
+  res,
+  subPath,
+  targetBase,
+  secret,
+  log = console.log,
+  timeoutMs = DEFAULT_PROXY_TIMEOUT_MS,
+  streaming = false,
+}) {
+  const target = new URL(subPath, targetBase);
+  const isStream = streaming || isStreamingPath(subPath);
+
+  // Build outbound headers. Filter `host` (Node will set from URL) +
+  // overwrite `x-olam-secret` (defense against client spoofing).
+  /** @type {Record<string, string | string[]>} */
+  const outHeaders = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (v === undefined) continue;
+    const lower = k.toLowerCase();
+    if (lower === 'host' || lower === 'x-olam-secret') continue;
+    outHeaders[k] = v;
+  }
+  outHeaders['x-olam-secret'] = secret;
+  outHeaders['x-forwarded-by'] = 'olam-host-cp';
+
+  const upstreamReq = http.request(
+    target,
+    {
+      method: req.method ?? 'GET',
+      headers: outHeaders,
+    },
+    (upstreamRes) => {
+      // Once headers come back from upstream, the request is no longer
+      // "stuck" — clear the timeout so a slow stream-of-body doesn't
+      // get killed mid-flight. Streaming handlers that intentionally
+      // delay between writes still rely on the no-timeout path.
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      // Verbatim passthrough: status + ALL headers + body bytes.
+      // Use res.writeHead so the headers go out atomically with the
+      // status line (response.statusCode + setHeader split would race
+      // on early body write). statusMessage may be undefined on some
+      // upstream paths — fall back to the default.
+      res.writeHead(
+        upstreamRes.statusCode ?? 502,
+        upstreamRes.statusMessage,
+        upstreamRes.headers,
+      );
+      upstreamRes.pipe(res);
+    },
+  );
+
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = null;
+  if (!isStream && timeoutMs > 0) {
+    timer = setTimeout(() => {
+      timer = null;
+      log(`proxy: upstream timeout (${timeoutMs}ms) for ${target}`);
+      // Destroying the upstream req triggers the 'error' handler with
+      // a generic socket error; we pre-empt it with an explicit 504
+      // first so the client sees a clean status instead of the generic
+      // 502 the error handler would emit.
+      if (!res.headersSent) {
+        res.writeHead(504, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({
+          error: 'upstream_timeout',
+          message: `per-world CP did not respond within ${timeoutMs}ms`,
+          worldUrl: target.origin,
+        }));
+      } else {
+        res.end();
+      }
+      try {
+        upstreamReq.destroy(new Error('proxy upstream timeout'));
+      } catch {
+        // already destroyed
+      }
+    }, timeoutMs);
+  }
+
+  // Upstream connection error — don't leak internals to the client.
+  upstreamReq.on('error', (err) => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    log(`proxy: upstream error for ${target}: ${err.message}`);
+    if (!res.headersSent) {
+      res.writeHead(502, { 'Content-Type': 'application/json; charset=utf-8' });
+      res.end(JSON.stringify({
+        error: 'upstream_unreachable',
+        message: 'per-world CP did not respond',
+        worldUrl: target.origin,
+      }));
+    } else {
+      // Response already started (likely SSE); just close.
+      res.end();
+    }
+  });
+
+  // Client closed early (browser navigated away, Safari unloaded the
+  // EventSource, etc.). Tear down the upstream so we don't keep an
+  // open socket to the per-world CP for an answer the caller no longer
+  // wants. Without this, host-cp leaks sockets per cancelled poll.
+  res.on('close', () => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (!upstreamReq.destroyed) {
+      try {
+        upstreamReq.destroy();
+      } catch {
+        // already gone
+      }
+    }
+  });
+
+  // Pipe request body. For GET/HEAD this is a no-op (no body bytes);
+  // for POST/PUT/PATCH this streams the body upstream.
+  req.pipe(upstreamReq);
+}

package/host-cp/src/pylon-worlds-source.mjs

@@ -0,0 +1,68 @@
+/**
+ * Phase E3 (olam-dogfood-vision): PylonWorldsSource skeleton.
+ *
+ * Stub implementation of the WorldsSource contract (E1) for Pylon-
+ * managed cloud worlds. Returns `[]` for now — the actual @pleri/pylon
+ * SDK integration is intentionally deferred (T5 mitigation: design the
+ * contract before the SDK lands so consumers don't churn when it does).
+ *
+ * The class proves the interface composes: E4 wires this alongside
+ * LocalWorldsSource into the GET /api/worlds handler so a Pylon-enabled
+ * deployment fans out across both sources, dedupes by id, and returns
+ * the union. With this stub returning `[]`, an enabled-but-empty Pylon
+ * source is a strict no-op over local-only behavior.
+ *
+ * Activation: gated by `OLAM_HOST_CP_PYLON_ENABLED=1`. When the env
+ * var is unset/0/false, server.mjs (E4) does NOT instantiate this
+ * source — the local-only path is preserved verbatim. When enabled,
+ * the empty source layers additively on top of local; behavior is
+ * still observably identical until the SDK ships.
+ *
+ * Why a no-op stub instead of waiting for the SDK:
+ *   - Consumers (SPA badge logic in E5, regression tests, CLI lookup)
+ *     can be wired against the contract without blocking on the SDK.
+ *   - Forces E4's composition logic to actually fan out, dedupe, and
+ *     merge — exercising the multi-source path in CI before any cloud
+ *     traffic touches it.
+ *   - Surface-area lock-in: anything missing here surfaces as a
+ *     contract gap NOW, not after the SDK is wired.
+ *
+ * @typedef {import('./worlds-source.mjs').WorldsSource} WorldsSource
+ * @typedef {import('./worlds-source.mjs').WorldSummary} WorldSummary
+ */
+
+/**
+ * @typedef {object} PylonWorldsSourceDeps
+ * @property {boolean} enabled
+ *   When false, list() short-circuits to `[]` without any Pylon
+ *   interaction. Kept on the deps object (rather than read from
+ *   process.env at construction time) so tests can flip it without
+ *   mutating module-level env state.
+ */
+
+/**
+ * @param {PylonWorldsSourceDeps} [deps]
+ * @returns {WorldsSource}
+ */
+export function createPylonWorldsSource(deps = { enabled: false }) {
+  return {
+    name: 'pylon-cloud',
+    async list() {
+      if (!deps.enabled) return [];
+      // TODO(pylon): wire @pleri/pylon SDK. Expected shape:
+      //   const client = new PylonClient({ token: scopedToken });
+      //   const cloudWorlds = await client.worlds.list();
+      //   return cloudWorlds.map((w) => ({
+      //     id: w.id,
+      //     name: w.displayName ?? null,
+      //     status: mapPylonStatus(w.state), // 'running' | 'starting' | ...
+      //     services: mapPylonServices(w.services),
+      //     source: 'pylon-cloud',
+      //   }));
+      // Until the SDK lands, the source is intentionally empty —
+      // proving the interface composes (E4) without committing the
+      // mapping shape prematurely.
+      return [];
+    },
+  };
+}

package/host-cp/src/redact.mjs

@@ -0,0 +1,67 @@
+// Phase F-2-B (B6): redact sensitive keys from workspace YAML before
+// exposing via /api/workspaces.
+//
+// T11 mitigation. Workspace YAMLs may contain operator-set environment
+// variables that include OAuth client secrets, API keys, deployment
+// tokens, database passwords. These should NEVER cross the host-cp ↔
+// browser boundary.
+//
+// Strategy: pattern-based recursive redaction. Any object key matching
+// SENSITIVE_KEY_PATTERN replaces its value with `[redacted]`. Catches
+// the standard naming conventions while remaining permissive on
+// non-sensitive keys (we don't false-positive on legitimate config).
+//
+// The pattern is intentionally broad — it's defensive. If an operator
+// names a non-sensitive var with a `_KEY`/`_SECRET`/`_TOKEN`/`_PASSWORD`/
+// `_CREDENTIALS` suffix, it gets redacted. Operators get a clear signal
+// (the value becomes `[redacted]`) and can rename the var if needed.
+//
+// We deliberately do NOT use the `PROTECTED_ENV_KEYS` set from
+// packages/core/src/world/env-setup.ts — that set is for service-
+// discovery host/port/URL keys (POSTGRES_HOST, REDIS_URL, etc.), not
+// org secrets. The two filters address different surfaces:
+//   - PROTECTED_ENV_KEYS in core: prevents manifest from overriding
+//     service-discovery state on the world's runtime env
+//   - SENSITIVE_KEY_PATTERN here: prevents the host CP API from leaking
+//     org secrets to the browser
+// Both are needed.
+
+export const SENSITIVE_KEY_PATTERN = /(.*_KEY|.*_SECRET|.*_TOKEN|.*_PASSWORD|.*_CREDENTIALS|.*_AUTH|API_KEY|PASSWORD|SECRET|TOKEN)$/i;
+
+/**
+ * Recursively redact sensitive values in any JSON-like structure
+ * (objects, arrays, primitives). Returns a new value; does not mutate
+ * input.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function redactSensitive(value) {
+  if (Array.isArray(value)) {
+    return value.map(redactSensitive);
+  }
+  if (value !== null && typeof value === 'object') {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (SENSITIVE_KEY_PATTERN.test(k)) {
+        out[k] = '[redacted]';
+      } else {
+        out[k] = redactSensitive(v);
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Quick predicate: does this key name look sensitive? Useful for
+ * pre-screening when iterating large maps.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+export function isSensitiveKey(key) {
+  return SENSITIVE_KEY_PATTERN.test(key);
+}