@hegemonart/get-design-done 1.33.0 → 1.33.6

package/scripts/lib/peer-cli/sanitize-env.cjs

@@ -0,0 +1,198 @@
+// scripts/lib/peer-cli/sanitize-env.cjs
+//
+// Plan 33.5-04 — peer-CLI environment sandbox (SC#4; CONTEXT D-03).
+//
+// ============================================================================
+// WHY THIS EXISTS
+// ============================================================================
+//
+// The two peer-CLI clients (acp-client.cjs / asp-client.cjs) spawn external
+// peer binaries (Gemini / Cursor / Copilot / Qwen / Codex) over stdio. Before
+// this module, both clients defaulted the child's environment to the FULL
+// `process.env` whenever the caller did not supply `opts.env` (acp line ~102,
+// asp line ~122). That leaks GDD's own secrets — ANTHROPIC_API_KEY, GH_TOKEN,
+// any GDD_* var — into every spawned peer, even though peers authenticate with
+// their OWN logged-in credentials and have no need for GDD's keys.
+//
+// D-03 (locked) makes the sandbox ALLOWLIST-FORWARD / DEFAULT-DENY: the child
+// env is built from (a) an OS-essential baseline (just enough for a binary to
+// launch on Windows + macOS + Linux) PLUS (b) an explicit caller allowlist read
+// from `.design/config.json#peer_cli.env_allowlist`. Everything else is dropped.
+// GDD secrets and any secret-shaped var are NEVER forwarded unless the operator
+// explicitly allowlists them — a one-line escape hatch for the rare peer that
+// genuinely needs an inherited provider key.
+//
+// No new runtime dependency (D-12): plain JS + a defensive config read that
+// mirrors registry.cjs's `readEnabledPeers` idiom.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── OS-essential baseline ────────────────────────────────────────────────────
+//
+// Exact variable names a child process generally needs to *launch* and behave
+// correctly across Windows + POSIX. Kept deliberately pragmatic: anything not
+// here (and not explicitly allowlisted) is dropped. The test only pins that
+// PATH + HOME survive, so this set can evolve without breaking the contract.
+
+const BASELINE = Object.freeze([
+  // PATH resolution (Windows uses `Path`; PATHEXT picks executable suffixes).
+  'PATH',
+  'Path',
+  'PATHEXT',
+  // Home / profile (POSIX HOME; Windows USERPROFILE + HOMEDRIVE/HOMEPATH).
+  'HOME',
+  'USERPROFILE',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  // System roots (Windows).
+  'SystemRoot',
+  'windir',
+  'SystemDrive',
+  // Temp dirs (cross-platform variants).
+  'TEMP',
+  'TMP',
+  'TMPDIR',
+  // Locale / shell.
+  'LANG',
+  'SHELL',
+  // Windows command interpreter + platform descriptors.
+  'COMSPEC',
+  'OS',
+  'NUMBER_OF_PROCESSORS',
+  'PROCESSOR_ARCHITECTURE',
+]);
+
+// Documented baseline PREFIXES — any var whose name starts with one of these is
+// treated as baseline (locale family + Node runtime knobs like NODE_OPTIONS).
+const BASELINE_PREFIXES = Object.freeze(['LC_', 'NODE_']);
+
+// ── Secret matchers (extra guard on the baseline) ─────────────────────────────
+//
+// SECRET_NAME — exact GDD-held secret variable names that must never leak.
+// SECRET_PREFIX — any GDD_* var is GDD-internal and never forwarded.
+// SECRET_SHAPE — generic secret-shaped suffixes; catches third-party keys a
+//   future baseline addition might otherwise let through.
+//
+// All three are overridden ONLY by an explicit entry in opts.allowlist
+// (explicit allowlist WINS — see sanitizeEnv below).
+
+const SECRET_NAME = Object.freeze([
+  'ANTHROPIC_API_KEY',
+  'GH_TOKEN',
+  'GITHUB_TOKEN',
+]);
+
+const SECRET_PREFIX = Object.freeze(['GDD_']);
+
+const SECRET_SHAPE = /(_KEY|_TOKEN|_SECRET|_PASSWORD|_AUTH)$/i;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function isBaseline(key) {
+  if (BASELINE.includes(key)) return true;
+  for (const pfx of BASELINE_PREFIXES) {
+    if (key.startsWith(pfx)) return true;
+  }
+  return false;
+}
+
+function isSecret(key) {
+  if (SECRET_NAME.includes(key)) return true;
+  for (const pfx of SECRET_PREFIX) {
+    if (key.startsWith(pfx)) return true;
+  }
+  return SECRET_SHAPE.test(key);
+}
+
+/**
+ * Defensively read `<cwd>/.design/config.json` and extract
+ * `peer_cli.env_allowlist` (a string[]). Returns [] on ANY failure path
+ * (file missing, unparsable, wrong shape) — never throws. Mirrors
+ * registry.cjs's `readEnabledPeers` idiom so both share a defensive reader.
+ *
+ * @param {string} [cwd] defaults to process.cwd()
+ * @returns {string[]} allowlisted env var names (deduped); empty by default
+ */
+function readPeerCliAllowlist(cwd) {
+  const root = typeof cwd === 'string' && cwd.length > 0 ? cwd : process.cwd();
+  const cfgPath = path.join(root, '.design', 'config.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(cfgPath, 'utf8');
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const peerCli = parsed && typeof parsed === 'object' ? parsed.peer_cli : null;
+  const list = peerCli && Array.isArray(peerCli.env_allowlist) ? peerCli.env_allowlist : [];
+  const out = [];
+  const seen = new Set();
+  for (const item of list) {
+    if (typeof item !== 'string' || item.length === 0) continue;
+    if (seen.has(item)) continue;
+    seen.add(item);
+    out.push(item);
+  }
+  return out;
+}
+
+// ── sanitizeEnv ─────────────────────────────────────────────────────────────--
+
+/**
+ * Build a sanitized child environment (allowlist-forward / default-deny).
+ *
+ * For each KEY in sourceEnv, forward it iff:
+ *   - KEY is explicitly in opts.allowlist (explicit allowlist WINS — even over
+ *     the secret filters), OR
+ *   - KEY is in the OS-essential BASELINE (exact name or a documented prefix)
+ *     AND KEY is NOT a GDD secret / secret-shaped var.
+ *
+ * Everything else is dropped. Pure: never mutates the input.
+ *
+ * @param {Record<string,string>} [sourceEnv=process.env]
+ * @param {{ allowlist?: string[] }} [opts]
+ * @returns {Record<string,string>}
+ */
+function sanitizeEnv(sourceEnv, opts) {
+  const src = sourceEnv && typeof sourceEnv === 'object' ? sourceEnv : process.env;
+  const o = opts && typeof opts === 'object' ? opts : {};
+  const allowlist = Array.isArray(o.allowlist) ? new Set(o.allowlist) : new Set();
+
+  const result = {};
+  for (const key of Object.keys(src)) {
+    const value = src[key];
+    // A value that is not a string (e.g. inherited prototype noise) is skipped;
+    // child env entries must be strings.
+    if (typeof value !== 'string') continue;
+
+    // Explicit allowlist wins over everything, including the secret filters.
+    if (allowlist.has(key)) {
+      result[key] = value;
+      continue;
+    }
+    // Otherwise the key must be baseline AND not secret-shaped.
+    if (isBaseline(key) && !isSecret(key)) {
+      result[key] = value;
+    }
+    // Default-deny: anything else is dropped.
+  }
+  return result;
+}
+
+module.exports = {
+  sanitizeEnv,
+  readPeerCliAllowlist,
+  BASELINE,
+  BASELINE_PREFIXES,
+  SECRET_NAME,
+  SECRET_PREFIX,
+  SECRET_SHAPE,
+};

package/scripts/lib/redact.cjs

@@ -45,11 +45,30 @@ const PATTERNS = [
     type: 'slack',
     re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
   },
-  // GitHub personal access token.
+  // GitHub personal access token (classic).
   {
     type: 'github_pat',
     re: /\bghp_[A-Za-z0-9]{36,}\b/g,
   },
+  // Google / Gemini / GCP API key (AIza…). Distinct shape — no collision
+  // with any existing pattern; placed with the specific patterns (D-07, 33.5-05).
+  {
+    type: 'gemini',
+    re: /\bAIza[0-9A-Za-z_\-]{35}\b/g,
+  },
+  // GitHub fine-grained PAT (github_pat_…). Distinct prefix from classic
+  // `ghp_` — both coexist (D-07, 33.5-05).
+  {
+    type: 'github_pat_fine_grained',
+    re: /\bgithub_pat_[0-9A-Za-z_]{22,}\b/g,
+  },
+  // GitHub server/oauth/user/refresh tokens (ghs_/gho_/ghu_/ghr_). The
+  // `[sour]` class excludes `p`, so this never collides with `ghp_` above
+  // (D-07, 33.5-05).
+  {
+    type: 'github_token',
+    re: /\bgh[sour]_[A-Za-z0-9]{36,}\b/g,
+  },
   // AWS access key ID.
   {
     type: 'aws',

package/scripts/lib/tier-resolver-openrouter.cjs

@@ -0,0 +1,343 @@
+// scripts/lib/tier-resolver-openrouter.cjs
+//
+// Plan 33.6-02 — OpenRouter tier-resolver adapter.
+//
+// `resolve(tier, opts?) → openrouter-model-id | null`
+//
+// Maps GDD's tier vocabulary (`opus` / `sonnet` / `haiku` — the same
+// VALID_TIERS the Phase-26 tier-resolver.cjs enforces, D-04) onto a concrete
+// model id from OpenRouter's DYNAMIC aggregator catalog. Two inputs decide the
+// answer, in this precedence (FIRST hit wins):
+//
+//   1. An explicit user override (`.design/config.json#openrouter_tier_overrides`,
+//      or `opts.overrides` injected for tests). A non-empty override string for
+//      the tier is returned VERBATIM and wins over the heuristic — even when that
+//      id is not present in the catalog (the user's explicit choice). (D-03)
+//   2. Otherwise the deterministic heuristic over the catalog `models[]`:
+//        opus   = top-tier CLOSED model (priciest closed-vendor id),
+//        sonnet = mid / top-OPEN (the closed model below opus, else the strongest
+//                 open model — always distinct from the opus pick),
+//        haiku  = cheap OPEN model (the cheapest open-vendor id).
+//      Deterministic for a fixed catalog (stable sort; no Date, no randomness) so
+//      the 33.6-04 golden baseline is stable.
+//   3. Otherwise (no catalog / empty models / no candidate, and no override) →
+//      null, so the CALLER falls back to the native provider via the existing
+//      scripts/lib/tier-resolver.cjs fallback chain. (D-08)
+//
+// The catalog comes from `opts.catalog` (alias `opts.models`) when injected
+// (tests — hermetic, D-07), otherwise from the 33.6-01 cache via
+// `scripts/lib/openrouter/catalog-fetcher.cjs#readCatalog`, required defensively
+// so a missing sibling module degrades to null rather than crashing import.
+//
+// NEVER throws (D-08): an unknown tier, a missing/corrupt config, a corrupt
+// cache, or garbage opts all degrade to null (or to an override when one
+// applies). Zero npm dependencies — node builtins only (D-10). `.cjs` to match
+// the Phase-26 sibling and stay require-able from .ts hooks under
+// --experimental-strip-types.
+//
+// PATTERN: mirrors scripts/lib/tier-resolver.cjs discipline (VALID_TIERS,
+// opts.models injection, never-throws, null-is-valid). This adapter has one
+// upstream (OpenRouter) and no runtime argument, so its signature is
+// `resolve(tier, opts)` rather than `resolve(runtime, tier, opts)`.
+//
+// SCOPE (D-12): OpenRouter is represented ONLY in this tier-resolution layer —
+// NOT in the install registry (scripts/lib/install/runtimes.cjs) and NOT as a
+// reference/runtime-models.md row. This adapter is the catalog's canonical
+// consumer; the router/budget-enforcer consultation + cost-tag wiring lives in
+// plan 33.6-03.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * GDD's public tier vocabulary — the same set tier-resolver.cjs enforces
+ * (D-04). `resolve` returns null for anything outside this set (no throw).
+ */
+const VALID_TIERS = Object.freeze(['opus', 'sonnet', 'haiku']);
+
+/**
+ * Vendor-namespace classification. The id prefix before the first `/` names
+ * the vendor; CLOSED = frontier/premium, OPEN = commodity/cheap. The
+ * closed-vs-open split is the heuristic's primary axis (D-03).
+ */
+const CLOSED_VENDORS = Object.freeze(['anthropic', 'openai', 'google']);
+const OPEN_VENDORS = Object.freeze(['meta-llama', 'qwen', 'mistralai', 'deepseek']);
+
+/**
+ * The internal capability buckets the heuristic computes, and their one-to-one
+ * map onto the public tiers (D-04). Exported for tests + documentation parity
+ * with reference/openrouter-tier-mapping.md.
+ */
+const TIER_BUCKETS = Object.freeze({
+  opus: 'high', // top-tier closed
+  sonnet: 'medium', // mid / top-open
+  haiku: 'low', // cheap open
+});
+
+const DEFAULT_CONFIG_PATH = path.join('.design', 'config.json');
+
+/**
+ * Best-effort read of `.design/config.json#openrouter_tier_overrides`. Returns
+ * a plain object (possibly empty); a missing file, missing key, or corrupt JSON
+ * degrades to `{}`. NEVER throws. `opts.configPath` overrides the location for
+ * tests; otherwise the path is resolved relative to `cwd` (default
+ * `process.cwd()`).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.configPath]
+ * @param {string} [opts.cwd]
+ * @returns {{ opus?: string, sonnet?: string, haiku?: string }}
+ */
+function readOpenrouterOverrides(opts) {
+  try {
+    const o = opts || {};
+    const configPath =
+      typeof o.configPath === 'string' && o.configPath.length > 0
+        ? o.configPath
+        : path.join(o.cwd || process.cwd(), DEFAULT_CONFIG_PATH);
+    if (!fs.existsSync(configPath)) return {};
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return {};
+    const ov = parsed.openrouter_tier_overrides;
+    if (!ov || typeof ov !== 'object') return {};
+    return ov;
+  } catch {
+    // Missing/corrupt config must never break resolution — degrade to no
+    // overrides so the heuristic (or null) takes over.
+    return {};
+  }
+}
+
+/**
+ * Defensive lazy read of the 33.6-01 catalog cache. Requires the sibling
+ * fetcher in a try/catch so a missing module (Wave-A ordering) degrades to
+ * null rather than crashing this module's import. Returns `Array<model>|null`.
+ *
+ * @param {string} [cachePath]
+ * @returns {Array<object>|null}
+ */
+function readCatalogDefensive(cachePath) {
+  try {
+    const fetcher = require('./openrouter/catalog-fetcher.cjs');
+    if (!fetcher || typeof fetcher.readCatalog !== 'function') return null;
+    const models = fetcher.readCatalog(
+      typeof cachePath === 'string' && cachePath.length > 0 ? { cachePath } : undefined,
+    );
+    return Array.isArray(models) ? models : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The vendor namespace of a model id (the segment before the first `/`),
+ * lower-cased. Returns '' for a malformed id.
+ */
+function vendorOf(id) {
+  if (typeof id !== 'string') return '';
+  const slash = id.indexOf('/');
+  if (slash <= 0) return '';
+  return id.slice(0, slash).toLowerCase();
+}
+
+function isClosed(id) {
+  return CLOSED_VENDORS.indexOf(vendorOf(id)) >= 0;
+}
+
+function isOpen(id) {
+  return OPEN_VENDORS.indexOf(vendorOf(id)) >= 0;
+}
+
+/**
+ * Parse a pricing string ("0.000075") to a finite Number, or null when absent
+ * / unparseable. The completion price is the heuristic's ranking key.
+ */
+function completionPrice(model) {
+  if (!model || typeof model !== 'object' || !model.pricing || typeof model.pricing !== 'object') {
+    return null;
+  }
+  const raw = model.pricing.completion;
+  const n = typeof raw === 'number' ? raw : Number.parseFloat(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+function contextLengthOf(model) {
+  const n = model && typeof model.context_length === 'number' ? model.context_length : 0;
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Keep only well-formed catalog rows: objects with a non-empty string `id`.
+ * Drops `null`, numbers, and shapeless entries so the ranking never touches a
+ * bad row.
+ */
+function sanitize(models) {
+  if (!Array.isArray(models)) return [];
+  return models.filter(
+    m => m && typeof m === 'object' && typeof m.id === 'string' && m.id.length > 0,
+  );
+}
+
+/**
+ * Stable comparator factory. `dir` = -1 sorts completion price DESCENDING
+ * (priciest first, for opus); `dir` = +1 sorts ASCENDING (cheapest first, for
+ * haiku). Models with no parseable price sort LAST regardless of direction.
+ * Ties break by context_length (more capable first for desc, less for asc),
+ * then by id ascending so the order is fully deterministic for a fixed catalog.
+ */
+function byCompletionPrice(dir) {
+  return (a, b) => {
+    const pa = completionPrice(a);
+    const pb = completionPrice(b);
+    const aMissing = pa === null;
+    const bMissing = pb === null;
+    if (aMissing && bMissing) return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    if (aMissing) return 1; // a sorts last
+    if (bMissing) return -1; // b sorts last
+    if (pa !== pb) return dir < 0 ? pb - pa : pa - pb;
+    const ca = contextLengthOf(a);
+    const cb = contextLengthOf(b);
+    if (ca !== cb) return dir < 0 ? cb - ca : ca - cb;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  };
+}
+
+/**
+ * Compute the heuristic pick for `tier` over a sanitized catalog. Returns a
+ * model id or null when no suitable candidate exists.
+ *
+ *   opus   → priciest CLOSED model (fallback: priciest model overall).
+ *   haiku  → cheapest OPEN model   (fallback: cheapest model overall).
+ *   sonnet → the next CLOSED model below the opus pick, else the strongest
+ *            (priciest) OPEN model; always distinct from the opus pick when the
+ *            catalog has >1 usable model.
+ */
+function heuristicPick(tier, clean) {
+  if (clean.length === 0) return null;
+
+  const closed = clean.filter(m => isClosed(m.id));
+  const open = clean.filter(m => isOpen(m.id));
+
+  if (tier === 'opus') {
+    const pool = closed.length > 0 ? closed : clean;
+    const ranked = pool.slice().sort(byCompletionPrice(-1));
+    return ranked.length > 0 ? ranked[0].id : null;
+  }
+
+  if (tier === 'haiku') {
+    const pool = open.length > 0 ? open : clean;
+    const ranked = pool.slice().sort(byCompletionPrice(1));
+    return ranked.length > 0 ? ranked[0].id : null;
+  }
+
+  // sonnet = MEDIUM (mid / top-open). Prefer the closed model directly below
+  // the opus pick; otherwise the strongest open model. Never collapse onto the
+  // opus pick when an alternative exists.
+  const opusPick = heuristicPick('opus', clean);
+
+  const closedDesc = closed.slice().sort(byCompletionPrice(-1));
+  // The first closed model that is NOT the opus pick (i.e. the second-priciest
+  // closed, the natural "mid closed" slot).
+  const midClosed = closedDesc.find(m => m.id !== opusPick);
+  if (midClosed) return midClosed.id;
+
+  // No second closed model — take the strongest (priciest) OPEN model.
+  const openDesc = open.slice().sort(byCompletionPrice(-1));
+  const topOpen = openDesc.find(m => m.id !== opusPick);
+  if (topOpen) return topOpen.id;
+
+  // Degenerate single-model catalog: fall back to any non-opus candidate, else
+  // the opus pick itself (better a valid id than null for a tier the caller
+  // asked for).
+  const anyOther = clean.find(m => m.id !== opusPick);
+  if (anyOther) return anyOther.id;
+  return opusPick;
+}
+
+/**
+ * Resolve a GDD tier to an OpenRouter catalog model id, or null.
+ *
+ * @param {string | null | undefined} tier
+ *   One of `opus` / `sonnet` / `haiku` (D-04). Anything else → null (no throw).
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.catalog]
+ *   Injected catalog `models[]` (tests, hermetic — D-07). Takes precedence over
+ *   the on-disk cache. `opts.models` is accepted as an interop alias.
+ * @param {Array<object>} [opts.models]
+ *   Interop alias for `opts.catalog` (mirrors tier-resolver.cjs naming).
+ * @param {{opus?:string,sonnet?:string,haiku?:string}} [opts.overrides]
+ *   Injected override map (tests). When absent, read from
+ *   `.design/config.json#openrouter_tier_overrides` (best-effort; missing/
+ *   corrupt → {}).
+ * @param {string} [opts.cachePath]
+ *   Passed through to readCatalog when no catalog is injected (tests).
+ * @param {string} [opts.configPath]
+ *   Override the .design/config.json location (tests).
+ * @param {string} [opts.cwd]
+ *   Base dir for the default config path (tests).
+ * @returns {string | null} an OpenRouter model id, or null (caller falls back
+ *   to the native provider — D-08).
+ */
+function resolve(tier, opts) {
+  try {
+    // Validate the tier FIRST — an unknown tier is null regardless of overrides
+    // or catalog (the override map is keyed by the valid tiers only).
+    if (typeof tier !== 'string' || VALID_TIERS.indexOf(tier) < 0) return null;
+
+    const o = opts && typeof opts === 'object' ? opts : {};
+
+    // 1. Override wins (D-03). Read injected map, else best-effort config.
+    const overrides =
+      o.overrides && typeof o.overrides === 'object'
+        ? o.overrides
+        : readOpenrouterOverrides({ configPath: o.configPath, cwd: o.cwd });
+    const override = overrides ? overrides[tier] : undefined;
+    if (typeof override === 'string' && override.length > 0) {
+      return override; // verbatim — wins over the heuristic, catalog-membership irrelevant
+    }
+
+    // 2. Heuristic over the catalog. Injected catalog/models take precedence;
+    //    otherwise read the cache defensively. An explicit `catalog: null`
+    //    (or `models: null`) is honored as "no catalog" and does NOT fall
+    //    through to the on-disk read — keeps injected tests hermetic.
+    let models;
+    if ('catalog' in o) {
+      models = o.catalog;
+    } else if ('models' in o) {
+      models = o.models;
+    } else {
+      models = readCatalogDefensive(o.cachePath);
+    }
+
+    const clean = sanitize(models);
+    if (clean.length === 0) return null; // 3. no catalog + no override → null (D-08)
+
+    const pick = heuristicPick(tier, clean);
+    return typeof pick === 'string' && pick.length > 0 ? pick : null;
+  } catch {
+    // Absolute backstop — resolve NEVER throws (D-08).
+    return null;
+  }
+}
+
+module.exports = {
+  resolve,
+  readOpenrouterOverrides,
+  VALID_TIERS,
+  TIER_BUCKETS,
+  CLOSED_VENDORS,
+  OPEN_VENDORS,
+  // internals surfaced for tests only — stable API = `resolve` +
+  // `readOpenrouterOverrides`.
+  _internal: {
+    vendorOf,
+    isClosed,
+    isOpen,
+    completionPrice,
+    heuristicPick,
+    sanitize,
+    readCatalogDefensive,
+  },
+};

package/scripts/lib/transports/ws.cjs

@@ -24,7 +24,9 @@
 'use strict';
 
 const http = require('node:http');
+const crypto = require('node:crypto');
 const { readFileSync, existsSync } = require('node:fs');
+const path = require('node:path');
 const { probeOptional } = require('../probe-optional.cjs');
 
 const ws = probeOptional('ws');
@@ -56,16 +58,62 @@ function* readEventsSync(path) {
   }
 }
 
+/**
+ * Defensively read `.design/config.json`. Returns the parsed object or `{}`
+ * on ANY failure (missing file, bad JSON, read error) — NEVER throws. The
+ * transport must still start when no config is present, so this mirrors the
+ * house defensive-fs idiom.
+ *
+ * @returns {Record<string, any>}
+ */
+function readDesignConfig() {
+  try {
+    const cfgPath = path.join(process.cwd(), '.design', 'config.json');
+    if (!existsSync(cfgPath)) return {};
+    const parsed = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve the bind host once, before listen (D-04). Order:
+ *   opts.host → env GDD_WS_BIND_HOST → .design/config.json#event_stream.bind_host → '127.0.0.1'
+ * The DEFAULT (no opt, no env, no config) is loopback only — remote bind is
+ * an explicit operator opt-in.
+ *
+ * @param {{ host?: unknown }} opts
+ * @returns {string}
+ */
+function resolveBindHost(opts) {
+  if (typeof opts.host === 'string' && opts.host.trim()) {
+    return opts.host.trim();
+  }
+  const envHost = process.env['GDD_WS_BIND_HOST'];
+  if (typeof envHost === 'string' && envHost.trim()) {
+    return envHost.trim();
+  }
+  const cfg = readDesignConfig();
+  const cfgHost =
+    cfg && cfg.event_stream && typeof cfg.event_stream.bind_host === 'string'
+      ? cfg.event_stream.bind_host.trim()
+      : '';
+  if (cfgHost) return cfgHost;
+  return '127.0.0.1';
+}
+
 /**
  * Start the WebSocket server. Returns a handle with `close()`.
  *
  * @param {{
  *   port: number,
  *   token: string,
+ *   host?: string,
  *   tailFrom?: string,
  *   subscribe?: (handler: (ev: unknown) => void) => () => void,
  * }} opts
- * @returns {Promise<{close: () => void, port: number}>}
+ * @returns {Promise<{close: () => void, port: number, host: string}>}
  */
 async function startServer(opts) {
   if (typeof opts.port !== 'number' || !Number.isFinite(opts.port)) {
@@ -75,6 +123,9 @@ async function startServer(opts) {
     throw new TypeError('startServer: token (string, ≥8 chars) required');
   }
 
+  // Resolve the bind host once (D-04): default 127.0.0.1 (loopback only).
+  const host = resolveBindHost(opts);
+
   const httpServer = http.createServer((_req, res) => {
     res.statusCode = 426; // Upgrade Required
     res.setHeader('Content-Type', 'text/plain');
@@ -109,7 +160,16 @@ async function startServer(opts) {
 
   httpServer.on('upgrade', (req, socket, head) => {
     const auth = req.headers['authorization'];
-    if (!auth || auth !== `Bearer ${opts.token}`) {
+    const expected = `Bearer ${opts.token}`;
+    // Constant-time compare (D-04, D-12 node:crypto built-in). The length
+    // pre-check is REQUIRED — timingSafeEqual throws on a length mismatch —
+    // and is acceptable here because the secret is the TOKEN bytes, not its
+    // length. A missing/short/mismatched token still yields the 401 close.
+    const ok =
+      typeof auth === 'string' &&
+      Buffer.byteLength(auth) === Buffer.byteLength(expected) &&
+      crypto.timingSafeEqual(Buffer.from(auth), Buffer.from(expected));
+    if (!ok) {
       socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
       socket.destroy();
       return;
@@ -142,12 +202,16 @@ async function startServer(opts) {
 
   await new Promise((resolve, reject) => {
     httpServer.once('error', reject);
-    httpServer.listen(opts.port, () => resolve(undefined));
+    httpServer.listen(opts.port, host, () => resolve(undefined));
   });
 
   const addr = httpServer.address();
   return {
     port: typeof addr === 'object' && addr ? addr.port : opts.port,
+    host:
+      typeof addr === 'object' && addr && typeof addr.address === 'string'
+        ? addr.address
+        : host,
     close() {
       try {
         unsub();