@stravica-ai/digital-operator-pa 0.1.36 → 0.1.37

package/dist/engineering-pa-cli/src/pa/cli.mjs

@@ -326,12 +326,15 @@ Exit codes (tooling standard §6):
 const WORKSPACE_USAGE = `pa workspace — workspace server lifecycle
 
 Usage:
-  pa workspace start [--port N] [--no-open]   Start the workspace server
-  pa workspace stop                            Stop the running server (refuses if supervised)
-  pa workspace restart [--port N] [--no-open]  Restart (supervisor-aware: launchctl kickstart / systemctl restart)
-  pa workspace status                          Show server status (supervisor-aware)
-  pa workspace open                            Open the workspace URL in a browser
-  pa workspace -h, --help                      Show this help
+  pa workspace start [--port N] [--host H] [--no-open]   Start the workspace server
+  pa workspace stop                                        Stop the running server (refuses if supervised)
+  pa workspace restart [--port N] [--host H] [--no-open]  Restart (supervisor-aware: launchctl kickstart / systemctl restart)
+  pa workspace status                                      Show server status (supervisor-aware)
+  pa workspace open                                        Open the workspace URL in a browser
+  pa workspace -h, --help                                  Show this help
+
+Bind host defaults to loopback (127.0.0.1). Use --host <addr> (or the
+WORKSPACE_HOST env var) to expose the workspace on another interface.
 
 When the workspace is supervised by launchd (~/Library/LaunchAgents/com.dave.workspace.plist)
 or systemd (~/.config/systemd/user/dave-workspace.service), \`stop\` is refused and \`restart\`

package/dist/engineering-pa-cli/src/secrets/vault.mjs

@@ -790,6 +790,16 @@ export async function sopsDecrypt(paths, filePath) {
  * scoped-vault fixtures use). Order is stable, duplicates deduplicated.
  * Returns an empty array on any read failure. This helper only feeds a
  * diagnostic message and must never throw over its own IO.
+ *
+ * NOTE: this reads the UNION of recipients across every creation_rule
+ * in the file. Scoped `.sops.yaml` configs typically declare one rule
+ * per encrypted file, and a caller who is a recipient in ONE scope but
+ * not another still matches this union. That is why the false-absence
+ * diagnostic surfaced on ops-01 (w-2026-09-03-dave-011): the caller's
+ * pubkey belonged to the seo-ops rule, not the hq-estate rule, but the
+ * union read showed it. Use `recipientsForTargetFile` to get the list
+ * for a specific file instead; the union stays here as a strict
+ * fallback for configs the narrow parser cannot recognise.
  */
 export function readRecipientsFromSopsConfig(sopsConfigPath) {
   let text;
@@ -812,31 +822,204 @@ export function readRecipientsFromSopsConfig(sopsConfigPath) {
   return out;
 }
 
+/**
+ * Parse creation_rules from a sops config file and return the recipient
+ * age pubkeys for the first rule whose `path_regex` matches the given
+ * encrypted file's basename. Returns null when the parser cannot pick a
+ * matching rule (caller falls back to the union read). Returns an empty
+ * array for a matching rule whose `age:` field is empty.
+ *
+ * The parser is deliberately narrow: it splits into blocks starting at
+ * `- path_regex:` lines and reads two fields per block, `path_regex`
+ * and `age`. Both inline (`age: "age1a,age1b"`) and folded multi-line
+ * (`age: >-\n  age1a\n  age1b`) shapes are handled: the two forms the
+ * estate's provisioning tooling emits. YAML this parser cannot
+ * recognise falls back to the union at the caller, so a partial config
+ * still produces a truthful message rather than a silent absence claim.
+ *
+ * Root-cause cure for w-2026-09-03-dave-011: `readRecipientsFromSopsConfig`
+ * unioned pubkeys across every creation_rule, so on ops-01 the caller
+ * key (recipient of seo-ops, not hq-estate) appeared in the printed
+ * "recipients" list, contradicting the "not in the recipient list"
+ * assertion. Scoping the recipient list to the actual target file's
+ * matching rule keeps the wording honest.
+ */
+export function recipientsForTargetFile(sopsConfigPath, targetFile) {
+  let text;
+  try {
+    text = readFileSync(sopsConfigPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  if (!targetFile) return null;
+  const targetName = basename(targetFile);
+  const lines = text.split('\n');
+  const rules = [];
+  let current = null;
+  let foldingAge = false;
+  const ruleStartRe = /^\s*-\s*path_regex:\s*(.+?)\s*$/;
+  const inlineAgeRe = /^\s*age:\s*"?([^"]*?)"?\s*$/;
+  const foldedAgeStartRe = /^\s*age:\s*>-?\s*$/;
+  const ageInlineExtract = /age1[0-9a-z]+/g;
+
+  for (const line of lines) {
+    const ruleStart = ruleStartRe.exec(line);
+    if (ruleStart) {
+      if (current) rules.push(current);
+      current = { pathRegex: ruleStart[1], age: [] };
+      foldingAge = false;
+      continue;
+    }
+    if (!current) continue;
+    if (foldingAge) {
+      // Folded block ends at a blank line, a new key at the block's
+      // indent, or a new list item. Anything else is a wrapped value.
+      const trimmed = line.trim();
+      if (trimmed === '' || /^[A-Za-z_-]+\s*:/.test(trimmed) || /^-\s/.test(trimmed)) {
+        foldingAge = false;
+        // fall through so this line can still start a new rule below
+      } else {
+        for (const match of trimmed.matchAll(ageInlineExtract)) current.age.push(match[0]);
+        continue;
+      }
+    }
+    if (foldedAgeStartRe.test(line)) {
+      foldingAge = true;
+      continue;
+    }
+    const inline = inlineAgeRe.exec(line);
+    if (inline) {
+      for (const match of inline[1].matchAll(ageInlineExtract)) current.age.push(match[0]);
+    }
+  }
+  if (current) rules.push(current);
+
+  for (const rule of rules) {
+    let re;
+    try { re = new RegExp(rule.pathRegex); } catch { continue; }
+    if (re.test(targetName)) {
+      const seen = new Set();
+      const out = [];
+      for (const k of rule.age) if (!seen.has(k)) { seen.add(k); out.push(k); }
+      return out;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read every `# public key: age1...` line from an age key file. A key
+ * file with a single identity yields one entry; a file with multiple
+ * identities yields one entry per identity, in file order (the order
+ * sops tries them when SOPS_AGE_KEY_FILE points at the file). Returns
+ * an empty array on any read failure or when no comment can be parsed.
+ * Only feeds diagnostic output: never throws over its own IO.
+ */
+export function publicKeysFromKeyFile(keyFile) {
+  let contents;
+  try {
+    contents = readFileSync(keyFile, 'utf-8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  const seen = new Set();
+  const re = /public key:\s*(age1[0-9a-z]+)/gi;
+  let m;
+  while ((m = re.exec(contents)) !== null) {
+    if (!seen.has(m[1])) {
+      seen.add(m[1]);
+      out.push(m[1]);
+    }
+  }
+  return out;
+}
+
 /**
  * Build the single stderr diagnostic line that names, without ever
  * decrypting anything, WHY a decrypt failed: the scope (or vault path),
- * the caller's age public key (never the private key, never the value),
- * and the scope's recipient list read from the sops config. Falls back
- * to a shorter form when one of those pieces cannot be recovered. The
- * caller still needs a message, and silence on this seam is the defect
- * being fixed (w-2026-09-02-dave-015 part 1).
+ * every candidate age public key the caller's key file contains (the
+ * exact set sops tries when SOPS_AGE_KEY_FILE points at that file, in
+ * file order), the target file's recipient list (scoped to the rule
+ * whose path_regex matches, when the parser can pin one, otherwise the
+ * union of all rules), and a truthful "is / is not in the list" verdict.
+ *
+ * Cures two live defects (w-2026-09-03-dave-011):
+ *   1. A file with multiple identities used to report only the first
+ *      `public key:` line. Now every identity in the key file is named.
+ *   2. The wording used to assert absence unconditionally, printing a
+ *      recipient list drawn from every creation_rule in the sops config.
+ *      When the caller's key was a recipient of ANOTHER rule the printed
+ *      list contradicted the assertion. Now the recipients are scoped
+ *      to the target's own rule, and the message states membership
+ *      truthfully: never claims absence when the list contains the key.
  */
 export function formatDecryptFailure(paths) {
   const target = paths.scope
     ? `scope "${paths.scope}"`
     : (paths.secretsFile ? `vault ${paths.secretsFile}` : 'vault');
-  let callerPub = null;
-  try {
-    callerPub = publicKeyFromKeyFile(paths.keyFile);
-  } catch { /* no key file, or unreadable: leave callerPub null */ }
-  const callerDesc = callerPub
-    ? `age key ${callerPub}`
-    : `age key at ${paths.keyFile}`;
-  const recipients = paths.sopsConfig ? readRecipientsFromSopsConfig(paths.sopsConfig) : [];
+
+  const callerPubs = paths.keyFile ? publicKeysFromKeyFile(paths.keyFile) : [];
+
+  // Prefer the recipient list of the specific target file's rule. Fall
+  // back to the union of every rule when the narrow parser cannot pin
+  // one; the wording checks membership either way, so falling back does
+  // not reintroduce the false-absence class the union alone caused.
+  let scopedRecipients = null;
+  if (paths.sopsConfig && paths.secretsFile) {
+    scopedRecipients = recipientsForTargetFile(paths.sopsConfig, paths.secretsFile);
+  }
+  const unionRecipients = paths.sopsConfig ? readRecipientsFromSopsConfig(paths.sopsConfig) : [];
+  const recipients = scopedRecipients ?? unionRecipients;
+  const recipientSet = new Set(recipients);
+  const matched = callerPubs.filter((k) => recipientSet.has(k));
+
+  const keyFileDesc = paths.keyFile ? ` (from ${paths.keyFile})` : '';
+  let callerDesc;
+  if (callerPubs.length === 0) {
+    callerDesc = paths.keyFile
+      ? `no age public key could be parsed from ${paths.keyFile}`
+      : 'no age key file path known';
+  } else if (callerPubs.length === 1) {
+    callerDesc = `age key ${callerPubs[0]}${keyFileDesc}`;
+  } else {
+    callerDesc = `age keys ${callerPubs.join(', ')}${keyFileDesc}`;
+  }
+
+  const recipientsLabel = scopedRecipients && paths.secretsFile
+    ? `recipients for ${basename(paths.secretsFile)} (from ${paths.sopsConfig})`
+    : `recipients (from ${paths.sopsConfig ?? '<no sops config>'})`;
   const recipientsDesc = recipients.length > 0
-    ? `recipients (from ${paths.sopsConfig}): ${recipients.join(', ')}`
+    ? `${recipientsLabel}: ${recipients.join(', ')}`
     : `recipients could not be read from ${paths.sopsConfig ?? '<no sops config>'}`;
-  return `Error: cannot decrypt ${target}: this host's ${callerDesc} is not in the recipient list; ${recipientsDesc}. Fix: add this host's public key to the scope's recipients, or run this verb from a host that already has decrypt access.`;
+
+  if (matched.length > 0) {
+    // Truthful branch: sops still refused even though the caller keys
+    // ARE listed as intended recipients. The two live causes are stale
+    // recipient stanzas in the encrypted store (needs `sops updatekeys`)
+    // and unreadable key file permissions.
+    const matchDesc = matched.length === 1
+      ? `${matched[0]} IS listed as a recipient`
+      : `${matched.join(', ')} ARE listed as recipients`;
+    return (
+      `Error: cannot decrypt ${target}: this host's ${matchDesc}, but sops still refused. ` +
+      'Common causes: the encrypted store predates this recipient stanza ' +
+      '(someone with decrypt access must run `sops updatekeys` on it), ' +
+      'or the key file permissions block sops from reading it. ' +
+      `${recipientsDesc}. Caller key file: ${callerDesc}.`
+    );
+  }
+  if (callerPubs.length === 0) {
+    return (
+      `Error: cannot decrypt ${target}: ${callerDesc}. ${recipientsDesc}. ` +
+      "Fix: restore your age key from backup, or run 'secrets init' to start a fresh vault."
+    );
+  }
+  return (
+    `Error: cannot decrypt ${target}: this host's ${callerDesc} is not in the recipient list; ` +
+    `${recipientsDesc}. ` +
+    "Fix: add this host's public key to the scope's recipients, or run this verb from a host that already has decrypt access."
+  );
 }
 
 /**

package/dist/engineering-pa-library-cli/src/tier-map.mjs

@@ -0,0 +1,101 @@
+// tier-map.mjs: default `library put` tier from the source path.
+//
+// The `library put` CLI used to default `--tier` to the `auto` sentinel
+// unconditionally. For content-bearing kinds like `profile.slice.upsert`
+// that meant the ingest engine's routing rules matched by CONTENT only,
+// and a slice from operator/profile/slices/ landed on the hq tier during
+// the 2026-09-03 self-push proof (w-2026-09-03-dave-017; hq commit
+// 15aacb2 carried a stray operator/profile/slices/dave-boot.md). The
+// CLI already knows the source path. The path already encodes the tier
+// for every file under operator/profile/ by estate convention, so we
+// pick the routing default from the path before the envelope is built.
+//
+// Rules (2026-09-04, w-2026-09-03-dave-017):
+//   operator/profile/career-context.md   -> stravica-operator-barry-private
+//   operator/profile/private-context.md  -> stravica-operator-barry-private
+//   operator/profile/health-context.md   -> stravica-operator-barry-private
+//   operator/profile/**  (incl. slices/) -> stravica-operator-barry
+//   (everything else)                    -> null  (caller keeps `auto`)
+//
+// Every path outside the map keeps the pre-cure `auto` default, so
+// unrelated payload kinds still content-route the way they always did.
+// This is the CLI half of the fix. The server side (a `sourcePath`
+// prefix match in the routing engine) is a companion change in the
+// remote-library repo and is not touched here.
+
+import { isAbsolute, relative } from 'node:path';
+
+/**
+ * First-match ordered list of path prefix rules. Callers use
+ * `deriveTierFromPath` rather than reading this directly.
+ */
+export const PATH_TIER_RULES = [
+  { match: (p) => p === 'operator/profile/career-context.md',  tier: 'stravica-operator-barry-private' },
+  { match: (p) => p === 'operator/profile/private-context.md', tier: 'stravica-operator-barry-private' },
+  { match: (p) => p === 'operator/profile/health-context.md',  tier: 'stravica-operator-barry-private' },
+  { match: (p) => p.startsWith('operator/profile/'),           tier: 'stravica-operator-barry' },
+];
+
+/**
+ * Normalise a caller-supplied path to a repo-relative POSIX form.
+ * Returns null when the path resolves outside the repo root: routing
+ * defaults do not apply outside the workspace, and the envelope encoder
+ * refuses that shape anyway (assertRepoRelativeSafe in envelope.mjs).
+ *
+ * @param {string} sourcePath  absolute or repo-relative
+ * @param {string} repoRoot    resolved repo root
+ * @returns {string|null}      repo-relative POSIX path, or null
+ */
+export function toRepoRelative(sourcePath, repoRoot) {
+  if (!sourcePath || !repoRoot) return null;
+  const rel = isAbsolute(sourcePath) ? relative(repoRoot, sourcePath) : sourcePath;
+  const norm = rel.replaceAll('\\', '/');
+  if (norm.startsWith('../') || norm === '..' || norm === '') return null;
+  return norm;
+}
+
+/**
+ * Match a source path against the tier map and return the derived tier,
+ * or null when no rule matches.
+ *
+ * @param {string} sourcePath
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+export function deriveTierFromPath(sourcePath, repoRoot) {
+  const rel = toRepoRelative(sourcePath, repoRoot);
+  if (!rel) return null;
+  for (const rule of PATH_TIER_RULES) {
+    if (rule.match(rel)) return rule.tier;
+  }
+  return null;
+}
+
+/**
+ * Refuse a caller-asserted tier that disagrees with the path-derived
+ * default. Returns null when the assertion is compatible (including the
+ * `auto` sentinel and paths with no mapped default). Returns a
+ * single-line reason string otherwise, ready for the CLI to print
+ * before exiting 2.
+ *
+ * The refusal exists so a `--tier hq` on an operator/profile/ path
+ * cannot silently override the operator-tier default. `auto` means
+ * "let derivation decide" and is always accepted.
+ *
+ * @param {string} sourcePath
+ * @param {string} repoRoot
+ * @param {string} assertedTier
+ * @returns {string|null}
+ */
+export function assertTierMatchesPath(sourcePath, repoRoot, assertedTier) {
+  if (!assertedTier || assertedTier === 'auto') return null;
+  const derived = deriveTierFromPath(sourcePath, repoRoot);
+  if (derived === null) return null;
+  if (derived === assertedTier) return null;
+  const rel = toRepoRelative(sourcePath, repoRoot) ?? sourcePath;
+  return (
+    `refusing to route ${rel} to tier "${assertedTier}": ` +
+    `path maps to tier "${derived}" by the profile-path default. ` +
+    'Drop --tier to accept the default, or move the file before overriding.'
+  );
+}

package/dist/engineering-pa-library-cli/src/verbs/put.mjs

@@ -11,6 +11,7 @@ import { basename } from 'node:path';
 import { buildEnvelope, subkeyIdFromRemoteKey } from '../envelope.mjs';
 import { postEvents } from '../http.mjs';
 import { parseIngestAck } from '../ack.mjs';
+import { assertTierMatchesPath, deriveTierFromPath } from '../tier-map.mjs';
 
 /**
  * @param {object} ctx
@@ -26,6 +27,26 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
     log('usage: library put <path> [--kind <kind>] [--tier auto|<tier>]');
     return 1;
   }
+
+  // Refuse a caller-forced tier that disagrees with the path-derived
+  // default (w-2026-09-03-dave-017). `auto` never triggers the refusal
+  // (auto means "let derivation choose"); an explicit tier does. The
+  // refusal is a clean exit 2 with a single-line reason so an operator
+  // sees why the CLI declined to encode the event rather than silently
+  // stamping the wrong tier.
+  const tierRefusal = assertTierMatchesPath(path, config.repoRoot, tier);
+  if (tierRefusal) {
+    log(`[library put] refused: ${tierRefusal}`);
+    return 2;
+  }
+
+  // When `--tier` is absent the CLI derives it from the path map. Paths
+  // outside the map keep today's `auto` sentinel so unrelated payload
+  // kinds still content-route the way they always did.
+  const derivedTier = tier === 'auto'
+    ? (deriveTierFromPath(path, config.repoRoot) ?? 'auto')
+    : tier;
+
   // Delete events carry no content by spec (§3.1 payload schema); the
   // operator can and typically will have removed the file locally before
   // asking the tier remote to catch up. Reading a file that does not
@@ -42,7 +63,7 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
     content,
     producer,
     kind,
-    tier,
+    tier: derivedTier,
     sourceKind: 'manual',
   });
 
@@ -56,7 +77,7 @@ export async function runPut({ config, args, fetchImpl, log = defaultLog }) {
   // RB-5 fix (2026-08-20 rehearsal). See ack.mjs for the wire contract.
   const ack = parseIngestAck(res);
   if (ack.kind === 'accepted' || ack.kind === 'deduped') {
-    log(`[library put] ${ack.kind} ${basename(path)} -> ${ack.eventId}`);
+    log(`[library put] ${ack.kind} ${basename(path)} -> ${ack.eventId} (tier: ${derivedTier})`);
     return 0;
   }
   log(`[library put] rejected ${basename(path)}: ${ack.reason}`);

package/dist/engineering-pa-workspace/src/api.mjs

@@ -686,38 +686,49 @@ function processOnboarding(body, repoRoot) {
     // Non-fatal: git may not be available or commit may fail
   }
 
-  // 7. Vault initialisation (non-fatal)
+  // 7. Vault backup instruction (no key material over HTTP).
   //
-  // NOTE (v0.1.5 — w-2026-05-18-014 follow-up): this code path still spawns
-  // a v1 stale path (`core/tools/secrets/bin/secrets`) that doesn't exist
-  // in v2 installs, and reads `~/.config/dave/age-key.txt` instead of the
-  // v2 `~/.config/stravica-pa/age-key.txt`. v0.1.5 fixes the live GET/POST
-  // /__api/secrets endpoints in-process; converting this onboarding flow
-  // to in-process requires making processOnboarding async, which is a
-  // larger refactor (callers of processOnboarding are sync). Tracked
-  // separately — see Notes in the v0.1.5 PR description.
-  var vault = { initialised: false, publicKey: null, privateKey: null, error: null };
+  // Historical note. Earlier revisions of this handler spawned a stale
+  // v1 vault binary and, on success, read `~/.config/dave/age-key.txt` off
+  // disk so the browser could render the secret key as a QR code for
+  // one-time backup. That is a private key over an unauthenticated local
+  // HTTP endpoint on a `*:4200` bind — see the P0 audit under
+  // w-2026-09-13-dave-024. No response from this endpoint ever carries
+  // private key material. The UI shows the operator a one-line instruction
+  // to run the CLI backup command instead.
+  const vault = {
+    initialised: false,
+    publicKey: null,
+    error: null,
+    backupInstruction: 'Run `pnpm exec secrets backup` from a terminal to view and store your recovery key.',
+  };
   try {
-    const vaultBin = join(repoRoot, 'core', 'tools', 'secrets', 'bin', 'secrets');
-    execSync('node "' + vaultBin + '" init', {
-      cwd: repoRoot,
-      stdio: 'pipe',
-      timeout: 30000,
-    });
-
-    // Read the private key for one-time QR backup display
-    const keyDir = join(process.env.HOME || '/tmp', '.config', 'dave');
-    const keyFile = join(keyDir, 'age-key.txt');
-    if (existsSync(keyFile)) {
-      const keyContents = readFileSync(keyFile, 'utf-8');
-      vault.initialised = true;
-      // Extract only the secret key line for QR code
-      const secretLine = keyContents.split('\n').find(function(l) { return l.startsWith('AGE-SECRET-KEY-'); });
-      vault.privateKey = secretLine || null;
-      // Read public key
-      const recipientsFile = join(repoRoot, '.vault', 'recipients.txt');
-      if (existsSync(recipientsFile)) {
-        vault.publicKey = readFileSync(recipientsFile, 'utf-8').trim();
+    const recipientsFile = join(repoRoot, '.vault', 'recipients.txt');
+    if (existsSync(recipientsFile)) {
+      // recipients.txt is a plain-text list of AGE public keys, one per
+      // line. Return the first strictly-validated `age1...` recipient
+      // rather than trusting the file contents verbatim: a bug elsewhere,
+      // a misplaced key file, or an operator paste can put arbitrary
+      // content in this path, and this endpoint is the last mile before
+      // it lands in an HTTP response body. AGE public keys are
+      // Bech32-encoded (58 characters after the `age1` prefix, all
+      // lowercase alphanumerics from Bech32's charset). AGE secret keys
+      // are prefixed `AGE-SECRET-KEY-` and are rejected by this regex.
+      const recipientsRaw = readFileSync(recipientsFile, 'utf-8');
+      const validRecipients = recipientsRaw
+        .split(/\r?\n/)
+        .map(function(line) { return line.trim(); })
+        // Public key shape: starts with `age1`, lowercase Bech32 body.
+        // The negative match on `AGE-SECRET-KEY-` is redundant given the
+        // `age1` prefix rule but stays as an explicit belt-and-braces.
+        .filter(function(line) {
+          if (!/^age1[a-z0-9]{58,}$/.test(line)) return false;
+          if (line.includes('AGE-SECRET-KEY-')) return false;
+          return true;
+        });
+      if (validRecipients.length > 0) {
+        vault.initialised = true;
+        vault.publicKey = validRecipients[0];
       }
     }
   } catch (e) {

package/dist/engineering-pa-workspace/src/guards.mjs

@@ -0,0 +1,161 @@
+/**
+ * guards.mjs — request guards for the workspace HTTP server.
+ *
+ * Three concerns:
+ *   1. Host header allowlist. Even bound to 127.0.0.1, a hostile domain that
+ *      resolves to 127.0.0.1 (DNS rebinding) can drive a browser to send a
+ *      request whose Host is the hostile domain. Requests whose Host is
+ *      not on the allowlist get 403. Enforced at the top of the outer
+ *      request handler so every route — static or API — is covered.
+ *   2. Origin allowlist on state-changing methods. Any web page open in the
+ *      operator's browser can POST to http://localhost:4200 with `mode:
+ *      no-cors`. When an Origin header is present it must match the
+ *      workspace's own origin; anything else gets 403.
+ *   3. Sec-Fetch-Site guard. Modern browsers stamp cross-site requests with
+ *      Sec-Fetch-Site: cross-site (or same-site). When the header is
+ *      present it must be `same-origin` or `none`.
+ *
+ * The websocket upgrade path shares the same allowlists — see server.mjs'
+ * server.on('upgrade', ...) hook. No WebSocket endpoint exists in the
+ * workspace today; the upgrade handler rejects all upgrades defensively so
+ * a future endpoint has to opt in explicitly. Upgrades run with
+ * `alwaysCheckOrigin: true` because RFC 6455 pins the upgrade verb to GET,
+ * which would otherwise skip the state-changing-method branch.
+ *
+ * All exports are pure functions; the HTTP wiring lives in server.mjs.
+ */
+
+/**
+ * Loopback and unspecified hosts that must not add themselves to the Host
+ * allowlist as an extra entry (they're already covered by the loopback
+ * triple, or they're a wildcard that would defeat the check).
+ */
+const NON_HOST_BINDS = new Set(['127.0.0.1', 'localhost', '::1', '::', '0.0.0.0']);
+
+/**
+ * Methods that never mutate server state. Anything outside this set is
+ * treated as state-changing for the Origin / Sec-Fetch-Site sweep. This is
+ * the CONNECT-safe form of the check; a future custom extension verb (or
+ * a HEAD that gets abused as a channel for side effects — belt and braces)
+ * still gets the CSRF gate.
+ */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * Build the Host header allowlist. Always includes localhost, 127.0.0.1
+ * and [::1] on the workspace port. When the operator has opted into a
+ * non-loopback bind (WORKSPACE_HOST env var or --host flag), that host is
+ * added too.
+ */
+export function buildAllowedHosts(port, extraHost) {
+  const hosts = new Set([
+    `localhost:${port}`,
+    `127.0.0.1:${port}`,
+    `[::1]:${port}`,
+  ]);
+  if (extraHost && !NON_HOST_BINDS.has(extraHost)) {
+    hosts.add(`${extraHost}:${port}`.toLowerCase());
+  }
+  return hosts;
+}
+
+/**
+ * Build the Origin allowlist. Same shape as the Host allowlist, but with an
+ * `http://` scheme prefix. HTTPS termination for a remote bind is out of
+ * scope for this fix.
+ */
+export function buildAllowedOrigins(port, extraHost) {
+  const origins = new Set([
+    `http://localhost:${port}`,
+    `http://127.0.0.1:${port}`,
+    `http://[::1]:${port}`,
+  ]);
+  if (extraHost && !NON_HOST_BINDS.has(extraHost)) {
+    origins.add(`http://${extraHost}:${port}`.toLowerCase());
+  }
+  return origins;
+}
+
+/**
+ * Count occurrences of a header name in `req.rawHeaders`. Node's
+ * `req.headers` normalises duplicates by joining them with a comma
+ * (silently for most headers) or picking the first (for a handful of
+ * single-value headers), so a hostile request that sends two Host headers
+ * — one aliased to the loopback, one not — could pass the normal check
+ * even though a downstream reader might see the other one. We refuse the
+ * request when any of Host / Origin / Sec-Fetch-Site occurs more than
+ * once, so the ambiguity never reaches the handler.
+ */
+function countRawHeader(rawHeaders, name) {
+  if (!Array.isArray(rawHeaders)) return 0;
+  const target = name.toLowerCase();
+  let count = 0;
+  for (let i = 0; i < rawHeaders.length; i += 2) {
+    const key = rawHeaders[i];
+    if (typeof key === 'string' && key.toLowerCase() === target) count++;
+  }
+  return count;
+}
+
+/**
+ * Check the request headers against the Host/Origin/Sec-Fetch-Site rules.
+ *
+ * Options:
+ *   - onlyCheckHost: skip the Origin / Sec-Fetch-Site branch (used by the
+ *     outer per-request pass; the inner API-branch call runs the full
+ *     check).
+ *   - alwaysCheckOrigin: always run Origin / Sec-Fetch-Site, even for
+ *     GET/HEAD/OPTIONS. Used by the upgrade handler because RFC 6455 pins
+ *     the upgrade verb to GET.
+ *
+ * Returns { ok: true } when the request passes, otherwise
+ * { ok: false, status, reason } with a 403 status and a short reason
+ * string (host | origin | sec-fetch-site | duplicate-host |
+ * duplicate-origin | duplicate-sec-fetch-site) for logging.
+ */
+export function checkRequestGuards(req, allowedHosts, allowedOrigins, options) {
+  const opts = options || {};
+  const headers = req.headers || {};
+  const raw = req.rawHeaders;
+
+  if (countRawHeader(raw, 'host') > 1) {
+    return { ok: false, status: 403, reason: 'duplicate-host' };
+  }
+  const host = typeof headers.host === 'string' ? headers.host.toLowerCase() : '';
+  if (!host || !allowedHosts.has(host)) {
+    return { ok: false, status: 403, reason: 'host' };
+  }
+  if (opts.onlyCheckHost) return { ok: true };
+
+  const method = (req.method || 'GET').toUpperCase();
+  const runOriginBranch = opts.alwaysCheckOrigin === true || !SAFE_METHODS.has(method);
+  if (runOriginBranch) {
+    if (countRawHeader(raw, 'origin') > 1) {
+      return { ok: false, status: 403, reason: 'duplicate-origin' };
+    }
+    if (countRawHeader(raw, 'sec-fetch-site') > 1) {
+      return { ok: false, status: 403, reason: 'duplicate-sec-fetch-site' };
+    }
+    const origin = typeof headers.origin === 'string' ? headers.origin.toLowerCase() : '';
+    if (origin && !allowedOrigins.has(origin)) {
+      return { ok: false, status: 403, reason: 'origin' };
+    }
+    const sfs = typeof headers['sec-fetch-site'] === 'string' ? headers['sec-fetch-site'].toLowerCase() : '';
+    if (sfs && sfs !== 'same-origin' && sfs !== 'none') {
+      return { ok: false, status: 403, reason: 'sec-fetch-site' };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Convenience: does the pathname trigger the API guard? The guard covers
+ * both the newer `/__api/*` surface and the legacy `/api/*` surface (used by
+ * the onboarding POST). Static pages under `/` still run the outer Host
+ * check but do not need the full API guard sweep — the outer pass covers
+ * them.
+ */
+export function isGuardedPath(pathname) {
+  if (!pathname) return false;
+  return pathname.startsWith('/__api/') || pathname.startsWith('/api/');
+}

package/dist/engineering-pa-workspace/src/server.mjs

@@ -16,6 +16,9 @@
  *   node server.mjs --no-open          Don't auto-open browser
  *   node server.mjs --timeout 60       Idle timeout in minutes (default: 120)
  *   node server.mjs --no-timeout       Disable idle timeout
+ *   node server.mjs --host 0.0.0.0     Bind host (default 127.0.0.1). Also
+ *                                      WORKSPACE_HOST env var. A non-loopback
+ *                                      bind prints a warning at startup.
  */
 
 import { createServer } from 'node:http';
@@ -26,6 +29,7 @@ import { resolve, join, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { handleApi } from './api.mjs';
 import { loadNav } from './nav.mjs';
+import { buildAllowedHosts, buildAllowedOrigins, checkRequestGuards, isGuardedPath } from './guards.mjs';
 import { readTeamScopeConfigSync } from '../../engineering-pa-core/src/desk/team-scope.mjs';
 import { readPreferencesSync } from '../../engineering-pa-core/src/preferences.mjs';
 import { startPoller as startStatusMonPoller } from './status-mon/poller.mjs';
@@ -90,6 +94,13 @@ let autoOpen = true;
 let timeoutMinutes = 120;
 let noTimeout = false;
 
+// Bind host. Defaults to loopback (127.0.0.1) — a request from anywhere
+// off-box gets a TCP refuse, not a 403. The operator opts into a wider bind
+// with --host <addr> or the WORKSPACE_HOST env var. When the resolved host
+// is non-loopback the startup banner names the exposure so a mistake is
+// visible in the log.
+let host = process.env.WORKSPACE_HOST || '127.0.0.1';
+
 // Read configured port from preferences if available (device-local overlay
 // wins over the shared base — see @stravica-ai/engineering-pa-core/src/preferences.mjs).
 try {
@@ -97,18 +108,41 @@ try {
   if (prefs && prefs.workspacePort) port = prefs.workspacePort;
 } catch { /* no prefs yet — use default */ }
 
-// CLI flags override preferences
+// CLI flags override preferences.
+//
+// --host <addr> is validated at the CLI edge. A missing value, an empty
+// string, or a value that looks like the next flag would otherwise fall
+// through as `undefined` and land on `server.listen(port, undefined, ...)`,
+// which Node treats as a wildcard bind — the exact exposure this fix
+// exists to close. Refuse loudly instead.
 for (let i = 0; i < args.length; i++) {
   switch (args[i]) {
     case '--port': port = parseInt(args[++i], 10); break;
     case '--no-open': autoOpen = false; break;
     case '--timeout': timeoutMinutes = parseInt(args[++i], 10); break;
     case '--no-timeout': noTimeout = true; break;
+    case '--host': {
+      const raw = args[++i];
+      if (typeof raw !== 'string' || raw.length === 0 || raw.startsWith('-')) {
+        console.error('Error: --host requires a non-empty address (received: ' + JSON.stringify(raw) + ')');
+        process.exit(1);
+      }
+      host = raw;
+      break;
+    }
   }
 }
 
 const IDLE_TIMEOUT_MS = timeoutMinutes * 60 * 1000;
 
+// Host and Origin allowlists. Built once at startup — the port and host
+// are pinned for the life of the process. `extraHost` is only added when
+// the operator has opted into a non-loopback bind; loopback binds keep the
+// allowlist to the three loopback aliases.
+const ALLOWED_HOSTS = buildAllowedHosts(port, host);
+const ALLOWED_ORIGINS = buildAllowedOrigins(port, host);
+const IS_LOOPBACK_BIND = host === '127.0.0.1' || host === 'localhost' || host === '::1';
+
 // Side-effect gate. This file is imported by tests to assert exports (Option
 // D). When it is imported (not run), we must NOT attach status-mon or bind a
 // port. Everything side-effectful below is guarded on this flag.
@@ -317,11 +351,55 @@ export function markdownPage(rawContent, filePath) {
 
 // --- HTTP server ---
 const server = createServer(async (req, res) => {
+  // Host allowlist runs on EVERY request, not only /__api/*. A DNS-rebinding
+  // attack can point a hostile domain at 127.0.0.1 and drive the browser to
+  // read repo-root files served under the static path — the API guard
+  // alone leaves that door open. Static file serving stays functional for
+  // any request whose Host is one of our own aliases; everything else is
+  // 403 before any URL parsing decides which handler runs.
+  //
+  // Absolute-form request targets (`GET http://foo/bar HTTP/1.1`) are
+  // rejected outright: Node still parses `req.url` from the request line,
+  // but the request-target authority and the Host header can then
+  // disagree, which the allowlist cannot see. Same-origin browser
+  // traffic never sends absolute-form.
+  if (typeof req.url === 'string' && /^https?:\/\//i.test(req.url)) {
+    warn('[workspace] absolute-form request target refused: ' + req.url);
+    res.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('Bad Request');
+    return;
+  }
+  const globalGuard = checkRequestGuards(req, ALLOWED_HOSTS, ALLOWED_ORIGINS, {
+    // At the outer layer we only need the Host check to cover DNS
+    // rebinding of static reads. The state-changing method guard fires
+    // again inside the API branch below, where every mutating route
+    // lives, so Origin / Sec-Fetch-Site checks are not weakened by the
+    // narrower outer pass.
+    onlyCheckHost: true,
+  });
+  if (!globalGuard.ok) {
+    warn('[workspace] global guard refused ' + req.method + ' ' + (req.url || '') + ' (' + globalGuard.reason + ')');
+    res.writeHead(globalGuard.status, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('Forbidden');
+    return;
+  }
+
   const url = new URL(req.url, 'http://localhost:' + port);
   const pathname = decodeURIComponent(url.pathname);
 
-  // API routes -- extension routes shadow core; handleApi handles the rest
+  // API routes -- extension routes shadow core; handleApi handles the rest.
+  // The full Host / Origin / Sec-Fetch-Site guard fires here so an
+  // extension route can never accept a cross-site request either. The
+  // outer pass has already validated the Host header, so this call is
+  // effectively the state-changing-method sweep.
   if (pathname.startsWith('/__api/') || pathname.startsWith('/api/')) {
+    const guard = checkRequestGuards(req, ALLOWED_HOSTS, ALLOWED_ORIGINS);
+    if (!guard.ok) {
+      warn('[workspace] guard refused ' + req.method + ' ' + pathname + ' (' + guard.reason + ')');
+      res.writeHead(guard.status, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Forbidden');
+      return;
+    }
     const extRoute = extRoutes.find(r => r.method === req.method && r.pathname === pathname);
     if (extRoute) { extRoute.handler(req, res, url, REPO_ROOT); return; }
 
@@ -464,6 +542,30 @@ const server = createServer(async (req, res) => {
   }
 });
 
+// --- Upgrade handler ---
+// The workspace does not expose a WebSocket endpoint today. Any incoming
+// upgrade is either an accident or an attempt to smuggle a state-changing
+// request past the HTTP guard, so we run the Host/Origin/Sec-Fetch-Site
+// guard first (403 to keep symmetry with the HTTP surface) and destroy the
+// socket otherwise. A future upgrade endpoint has to attach its own
+// listener and must respect the same allowlists.
+server.on('upgrade', (req, socket) => {
+  // Upgrade requests are pinned to GET by RFC 6455, so the standard
+  // state-changing-method branch would skip Origin / Sec-Fetch-Site.
+  // `alwaysCheckOrigin` forces the full sweep so a future upgrade
+  // endpoint has to opt out consciously and can never inherit a weaker
+  // check by accident.
+  const guard = checkRequestGuards(req, ALLOWED_HOSTS, ALLOWED_ORIGINS, { alwaysCheckOrigin: true });
+  if (!guard.ok) {
+    warn('[workspace] upgrade refused (guard: ' + guard.reason + ')');
+    socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+  } else {
+    warn('[workspace] upgrade refused (no upgrade handler installed)');
+    socket.write('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
+  }
+  socket.destroy();
+});
+
 // --- Extension loader ---
 // Imports operator/extensions/workspace/api.mjs (if present) and calls its
 // register(addRoute) export. Extensions can add routes or shadow core routes.
@@ -518,9 +620,12 @@ if (isMainModule && !process.env.DAVE_REPO_ROOT && process.env.WS_STATUS_MON !==
 if (isMainModule) (async function () {
   await loadExtensions();
 
-  server.listen(port, () => {
+  server.listen(port, host, () => {
     const url = 'http://localhost:' + port;
-    log('[workspace] Dave Workspace running at ' + url);
+    if (!IS_LOOPBACK_BIND) {
+      warnAlways('[workspace] WARNING: bound to ' + host + ':' + port + ' — reachable from other hosts. Set WORKSPACE_HOST=127.0.0.1 or omit --host to restore loopback-only.');
+    }
+    log('[workspace] Dave Workspace running at ' + url + ' (bind ' + host + ')');
     log('[workspace] Serving from: ' + REPO_ROOT);
     if (EXT_DIR) log('[workspace] Extensions: ' + EXT_DIR.replace(REPO_ROOT + '/', ''));
     log('[workspace] Idle timeout: ' + (noTimeout ? 'disabled (persistent)' : timeoutMinutes + ' minutes'));

package/dist/engineering-pa-workspace/src/ws.mjs

@@ -6,9 +6,9 @@
  * Manages the workspace dev server (server.mjs) as a background process.
  *
  * Usage:
- *   node ws.mjs start [--port N] [--no-open]   Start server as background daemon
- *   node ws.mjs stop                            Stop the running server
- *   node ws.mjs restart [--port N] [--no-open]  Stop then start
+ *   node ws.mjs start [--port N] [--host H] [--no-open]   Start server as background daemon
+ *   node ws.mjs stop                                        Stop the running server
+ *   node ws.mjs restart [--port N] [--host H] [--no-open]  Stop then start
  *   node ws.mjs status                          Show server status
  *   node ws.mjs open                            Open browser to server URL
  */
@@ -330,6 +330,14 @@ async function cmdStart() {
   serverArgs.push('--port', String(port));
   serverArgs.push('--no-open'); // CLI handles browser open, not server
 
+  // Bind host pass-through. Loopback is the server-side default; the CLI
+  // only forwards --host when the operator has explicitly asked for a
+  // wider bind, so an unadorned `pa workspace start` stays loopback-only.
+  const hostFlag = getFlag('--host');
+  if (hostFlag) {
+    serverArgs.push('--host', hostFlag);
+  }
+
   // Open log file for stdout/stderr
   const { openSync, close } = await import('node:fs');
   const logFd = openSync(LOG_FILE, 'w');
@@ -585,11 +593,15 @@ export { isProcessAlive, checkPort, findPortHolder };
 const USAGE = `Usage: node ws.mjs <command> [options]
 
 Commands:
-  start   [--port N] [--no-open]   Start workspace server
-  stop                              Stop workspace server
-  restart [--port N] [--no-open]   Restart workspace server
-  status                            Show server status
-  open                              Open browser to server URL`;
+  start   [--port N] [--host H] [--no-open]   Start workspace server
+  stop                                          Stop workspace server
+  restart [--port N] [--host H] [--no-open]   Restart workspace server
+  status                                        Show server status
+  open                                          Open browser to server URL
+
+Bind host defaults to loopback (127.0.0.1). Pass --host <addr> or set
+WORKSPACE_HOST to expose the workspace on another interface — a non-loopback
+bind is a deliberate opt-in and the server prints a warning at startup.`;
 
 // Only dispatch the CLI when this file is the entrypoint. When imported as a
 // module (e.g. by tests that pull in exported helpers), skip the switch so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",