@strixgov/mcp-proxy 0.1.0 → 0.1.6

package/CHANGELOG.md

@@ -5,6 +5,258 @@ All notable changes to `@strixgov/mcp-proxy` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.6]
+
+Documentation + license-fidelity patch. No functional change to the proxy,
+the receipt format, the signing flow, or any runtime behavior.
+
+### Fixed
+- **`LICENSE` corrected to canonical Elastic License 2.0.** The Limitations
+  clause read "provide the software to **others** as a hosted or managed
+  service"; the canonical ELv2 wording is "to **third parties**." Corrected
+  byte-for-byte against Elastic's published license. The `0.1.0` release note
+  flagged this exact verification ("verify the bundled LICENSE against
+  canonical ELv2 before tagging") — the deviation shipped anyway in 0.1.0 and
+  0.1.5. Legal-text fidelity only; no change to intent or the MIT/ELv2 split.
+  **Counsel should confirm before publish.**
+- **README version labels.** Notes describing *current* behavior were tagged
+  `v0.1.0` (the floor where they were first true); a reader on npm sees
+  `0.1.5+`. Relabeled the current-behavior notes (transport scope, env-var
+  substitution, feature-table column, Mode-3 seam, single-tenant boundary) to
+  `v0.1.x`. Genuinely historical references (the `v0.1.0–v0.1.3` ephemeral-key
+  known issue, `v0.1.4+` default `storagePath`) are unchanged.
+
+### Note
+- Closes findings F-3 and F-4 of
+  `docs/reviews/mcp-proxy-publish-readiness-2026-06-07.md`. Repeatable
+  publish gate: `scripts/mcp-proxy-preflight.mjs`.
+
+## [0.1.5]
+
+Documentation-hygiene patch. No functional change to the proxy, the
+receipt format, the signing flow, or any runtime behavior.
+
+### Fixed
+- **`SECURITY.md`, `README.md`, and `CHANGELOG.md` cross-references**
+  rewritten to remove links into the maintainer's internal source tree.
+  The threat-model cross-reference in `SECURITY.md` now points reviewers
+  at `security@strixgov.com`; runbook cross-references and an internal
+  development-branch name embedded in a 0.1.0 release note have been
+  removed. Static text only — no API, no behavior, no tests changed.
+
+### Note
+- Operators on 0.1.0 are encouraged to upgrade. v0.1.0 has been
+  deprecated on npm to surface this guidance on install; `npm install
+  @strixgov/mcp-proxy@0.1.0` continues to work but emits a deprecation
+  warning pointing here.
+
+## [0.1.4]
+
+Fixes the silent-ephemeral-key footgun surfaced by the same dogfood that
+produced 0.1.1–0.1.3. With `storagePath` unset, pre-0.1.4 left
+`governMCPServer` to default both halves of persistence wrong:
+`MemoryStorage` (so the proxy's receipts vanished on exit) AND
+`generateSigningKey()` ephemeral (so the kid embedded in every on-disk
+receipt pointed at a key that didn't exist anywhere). Operators who
+worked around the storage half by pointing `storagePath` at
+`~/.strix-gateway` saw receipts they could `strix-gateway receipts list`
+but never `verify` — `kid not in keyring: strix-<serverId>` on every
+record. This release makes "the receipts I wrote yesterday are
+verifiable today" the default.
+
+### Changed
+- **Default `storagePath`** when `opts.storagePath` is undefined: now
+  resolves to `path.join(os.homedir(), ".strix-mcp-proxy", serverId)`
+  instead of leaving the value unset. Receipts persist as JSONL under
+  that path; the Ed25519 signing key persists at
+  `<storagePath>/keys/{signing-key.pem, public-jwk.json}` and is reused
+  across restarts. The default is intentionally **not**
+  `~/.strix-gateway`: the gateway CLI uses a multi-kid keyring layout
+  (`active` pointer + `<kid>/` subdirs) while the proxy uses
+  `loadOrCreateSigningKey`'s flat single-key layout, and sharing the
+  same `keys/` directory produces silently-broken receipts (the proxy's
+  flat key files are invisible to the keyring loader, or the v0.1 auto-
+  migration clobbers the gateway's `active` pointer to the proxy's kid).
+- **Audit event `signing.key.resolved`** now distinguishes
+  `source: "persistent"` (operator-supplied `storagePath`) from
+  `source: "persistent-default"` (auto-resolved per-serverId default).
+
+### Added
+- **`storagePath: null` opt-out.** Callers who genuinely want the pre-
+  0.1.4 ephemeral behavior (CI smoke runs, demos that intentionally
+  produce throwaway receipts) pass `storagePath: null` explicitly.
+  Receipts within the session remain chain-coherent; signatures are
+  unverifiable across restarts.
+
+### Test
+- `startTestProxy` helper now defaults to a per-test tmpdir so the
+  suite never writes to the developer's home directory.
+- Old `"no storagePath ⇒ in-memory ephemeral key (preserves pre-0.1.2
+  default)"` test removed and replaced with two tests pinning the new
+  default behavior + the explicit-`null` opt-out path.
+
+### Migration notes for existing operators
+- If your `notion-proxy-config.json` (or equivalent) sets
+  `"storagePath": "~/.strix-gateway"` to share storage with the
+  gateway CLI, **change it** — point at
+  `"~/.strix-mcp-proxy/<serverId>"` instead (or any path you control
+  that isn't aliased to `~/.strix-gateway`). Existing receipts at the
+  old location remain readable but their kid is unverifiable because
+  the proxy's old ephemeral key is gone. Future receipts written
+  under the new default ARE verifiable end-to-end.
+- If your code passes no `storagePath` and depended on receipts
+  vanishing on exit, add `storagePath: null` to your `startProxy`
+  call to preserve that behavior.
+
+## [0.1.3]
+
+Closes the headless-approval gap surfaced by the same dogfood run that
+produced 0.1.1 / 0.1.2. With `approval.enabled: false` (the default)
+every `APPROVAL_REQUIRED` call is silently denied; turning approval on
+defaults to `terminalApprove`, which fails closed in any non-TTY context
+including Claude Desktop's headless spawn. `@strixgov/tool-gateway`
+already shipped a `fileApprover` that works in headless contexts, but
+the proxy couldn't wire it up from JSON config because the gateway's
+`approval.prompt` field expects a function — and JSON can't carry one.
+
+### Added
+- **`approval.type` JSON config field** with three accepted values:
+  - **`"auto"`** — auto-approves every `APPROVAL_REQUIRED` call with a
+    signed `approval.approved: true` audit trail. Convenient for demos
+    where you want to show the approval-loop fires; **defeats real
+    governance** for non-trivial environments.
+  - **`"file"`** — wires up `fileApprover` from `@strixgov/tool-gateway`.
+    The proxy writes `<requestDir>/<requestId>.request.json` per
+    approval-pending call; an out-of-band approver writes
+    `<requestId>.response.json` with `{approved: true|false, approvedBy?, reason?}`.
+    Works under Claude Desktop spawn, CI, or any headless context.
+    `requestDir` defaults to `<storagePath>/approvals` when `storagePath`
+    is set, or `./.strix-approvals` otherwise. `~` and `~/` are expanded
+    to `os.homedir()` consistent with `storagePath`'s tilde handling.
+    Optional `timeoutMs` (default 5min) and `pollIntervalMs` (default
+    250ms) tunables.
+  - **`"terminal"`** — explicit alias for the legacy default. Useful
+    when an operator is testing the proxy directly from a TTY and wants
+    to see the y/N prompt.
+- Resolution order pinned and tested:
+  1. Programmatic `approval.prompt` function (always wins)
+  2. `approval.enabled === false`
+  3. `approval.autoApprove === true` (long form of `type: "auto"`)
+  4. `approval.type === "auto" | "file" | "terminal"`
+  5. Unknown `type` ⇒ startup error (fail-fast, not silent fail-closed)
+- 8 new tests covering each resolution branch.
+
+### Fixed
+- Unknown `approval.type` values now throw at startup with the message
+  `unknown approval.type 'X' — expected "terminal", "file", or "auto"`,
+  instead of silently falling through to a deny-everything state.
+
+### Migration
+- **`{enabled: false}`** (the docs-example default) is unchanged.
+- **`{enabled: true}`** (no `type`) preserves the v0.1.2 behavior
+  (defaults to `terminalApprove`, fails closed in non-TTY contexts).
+- New JSON-config-friendly shapes for headless deployments:
+  ```jsonc
+  "approval": {
+    "enabled": true,
+    "type": "file",
+    "requestDir": "~/.strix-gateway/approvals",
+    "timeoutMs": 300000
+  }
+  ```
+  or for demos:
+  ```jsonc
+  "approval": { "enabled": true, "type": "auto" }
+  ```
+
+### Verification
+- 37 tests pass under `node --test`; 1 skipped (network-gated tarball
+  install gate, opt in via `STRIX_RUN_TARBALL_INSTALL=1`).
+
+## [0.1.2]
+
+Closes the verifiability gap surfaced by a fresh dogfood run on Windows
+(May 25 2026): receipts were correctly signed and written to JSONL on
+disk, but the signing key was discarded the instant the proxy exited.
+Every receipt produced under v0.1.0 / v0.1.1 carried a `signingKeyId`
+(e.g. `strix-notion`) pointing at a key that no longer existed
+anywhere — so `@strixgov/verifier` reported `KEY_NOT_FOUND` for every
+local-mode receipt. Trust property was "tamper-evident at write time"
+but not "externally re-verifiable after restart."
+
+### Fixed
+- **`startProxy` now persists the signing keypair to disk when
+  `storagePath` is set.** Files land at:
+  - `<storagePath>/keys/signing-key.pem` (PKCS8 PEM, mode 0600)
+  - `<storagePath>/keys/public-jwk.json` (public JWK with `kid`, `kty`,
+    `crv`, `x` — mode 0644)
+  The same `kid` (e.g. `strix-notion`) is reused across restarts via
+  `loadOrCreateSigningKey()` from `@strixgov/tool-gateway`, so JSONL
+  receipts are independently verifiable after the proxy exits:
+  ```sh
+  npx @strixgov/verifier chain ~/.strix-gateway/receipts.jsonl \
+    --jwks ~/.strix-gateway/keys/public-jwk.json
+  ```
+  Caller-supplied `opts.signingKey` still wins over disk persistence —
+  operators integrating with a KMS or secrets manager are unaffected.
+  When neither `signingKey` nor `storagePath` is set, behavior matches
+  v0.1.1 (in-memory ephemeral key) — preserved as the default for tests
+  and embedded use cases.
+- A new `signing.key.resolved` audit event fires on the persistent
+  path with `{source: "persistent", kid, keyPath}` so operators can
+  confirm the disk-load happened.
+
+### Breaking changes
+- None. `startProxy` is already async; the new `loadOrCreateSigningKey`
+  call slots into the existing async flow without changing the
+  `governMCPServer` (synchronous) contract.
+
+### Notes for existing users
+- **Receipts produced under v0.1.0 / v0.1.1 remain unverifiable.** Their
+  signing keys were ephemeral and are not recoverable. Starting with
+  0.1.2, every new receipt written under a `storagePath` deployment is
+  verifiable for the life of the persisted key.
+- The first start under 0.1.2 generates a fresh keypair. Subsequent
+  starts reuse it. To force key rotation, delete `<storagePath>/keys/`
+  before restart; the next start will regenerate.
+
+### Verification
+- 4 new tests in `test/proxy-end-to-end.test.mjs`:
+  - Disk files (PEM + JWK) created with correct shape + kid
+  - kid survives a restart (the demo-story invariant)
+  - Caller-supplied `signingKey` bypasses disk persistence
+  - No-`storagePath` path preserves v0.1.1 in-memory default
+
+## [0.1.1]
+
+Bug-fix release that closes the gap surfaced when a fresh user ran the
+"5-line integration (Claude Desktop)" path end-to-end and the proxy
+exited at startup with `Cannot find package '@strixgov/capabilities-mcp-common'`.
+
+### Fixed
+- **`@strixgov/capabilities-mcp-common` is now a runtime `dependencies`
+  entry, not a `devDependencies`-only listing.** Previously, every user
+  who installed the proxy globally (`npm install -g @strixgov/mcp-proxy`)
+  also had to discover and run a second `npm install -g
+  @strixgov/capabilities-mcp-common` before the example config in the
+  README would load — because npm doesn't install devDependencies for
+  globally-installed packages. The README documents the companion pack
+  as the default capability source, so it's a hard runtime dependency.
+  This was a release blocker for the "zero-friction first run" claim
+  in the README.
+- **Clearer error when a `capabilities` import path can't be resolved.**
+  `resolveCapabilities()` now catches `ERR_MODULE_NOT_FOUND` (and the
+  related `Cannot find package` shape) and re-throws with an actionable
+  hint pointing the operator at `npm install -g <pack>`. Previously
+  the operator saw the bare Node loader error, which doesn't tell them
+  how to fix it.
+
+### Verification
+- All 25 tests under `node --test` continue to pass.
+- Manual dogfood: `npm install -g @strixgov/mcp-proxy@0.1.1` followed
+  by `strix-mcp-proxy --config <path>` resolves
+  `@strixgov/capabilities-mcp-common/notion` without a second install.
+
 ## [0.1.0]
 
 Initial release. The Strix MCP Proxy — a standalone process that
@@ -64,8 +316,7 @@ rather than a v1.0 rewrite.
     expansion, companion-pack dynamic import resolution.
   - `test/cli.test.mjs` — `--help`, `--version`, missing-arg errors,
     missing-file errors.
-- Companion-pack lookup uses `cap.name` indexing (the P0 #2 fix
-  shipped on `claude/strix-mcp-wrapping-IDXOy`) so server-prefixed
+- Companion-pack lookup uses `cap.name` indexing so server-prefixed
   tool names (`notion-fetch`, `slack_send_message`) match the pack
   rather than falling through to the MEDIUM EXECUTE heuristic.
 

package/LICENSE

@@ -13,7 +13,7 @@ to the limitations and conditions below.
 
 Limitations
 
-You may not provide the software to others as a hosted or managed service,
+You may not provide the software to third parties as a hosted or managed service,
 where the service provides users with access to any substantial set of the
 features or functionality of the software.
 

package/README.md

@@ -35,22 +35,44 @@ Tool implementations are untouched. The MCP client (Claude Desktop, mcp-cli,
 IDE integration, your own code) doesn't need to know Strix exists — it just
 spawns this proxy in place of the upstream server.
 
+> **Transport scope (v0.1.x):** the proxy wraps MCP servers that speak
+> the **stdio transport** — the `command` / `args` pattern in
+> `claude_desktop_config.json`. It does **not** intercept HTTP-based
+> hosted MCP servers (e.g. Notion's `https://mcp.notion.com/mcp`
+> Claude Desktop "Connector" pattern). If your MCP server is reachable
+> only over HTTPS, the proxy cannot govern it today; that's
+> [Posture B](https://github.com/Strixgov/strix/tree/main/docs/architecture/mcp-mode-3-enforcement-v1.md)
+> in the Mode 3 architecture and is deferred to a future release. Use
+> the local stdio version of the upstream MCP server in the meantime.
+
 ## 5-line integration (Claude Desktop)
 
+Claude Desktop's config file lives at:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` (resolves to `C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json` — outside any OneDrive Known Folder Move)
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
 ```jsonc
-// ~/Library/Application Support/Claude/claude_desktop_config.json
 {
   "mcpServers": {
     "notion": {
       "command": "strix-mcp-proxy",
-      "args": ["--config", "/Users/you/strix-proxy/notion.json"]
+      "args": ["--config", "/absolute/path/to/notion-proxy-config.json"],
+      // Env vars set here propagate to the proxy and on to the upstream
+      // MCP server via process.env (the proxy passes them through by
+      // default — see `upstream.env` below to override explicitly).
+      "env": {
+        "NOTION_TOKEN": "secret_..."
+      }
     }
   }
 }
 ```
 
-The config file at `notion.json` points the proxy at the real Notion MCP
-server and sets your policy. See [`examples/notion-proxy-config.json`](./examples/notion-proxy-config.json)
+The config file at `notion-proxy-config.json` points the proxy at the
+real Notion MCP server and sets your policy. See
+[`examples/notion-proxy-config.json`](./examples/notion-proxy-config.json)
 for a complete example.
 
 ## Config file shape
@@ -60,7 +82,14 @@ for a complete example.
   "serverId": "notion",                         // namespace for capability ids
   "upstream": {
     "command": "npx",
-    "args": ["-y", "@notionhq/notion-mcp-server"]
+    "args": ["-y", "@notionhq/notion-mcp-server"],
+    // Optional. If omitted, the proxy passes process.env through to
+    // the upstream (so env vars set in Claude Desktop's `env` block
+    // reach the upstream automatically). Setting `upstream.env`
+    // overrides that default — only the keys you list are passed.
+    "env": {
+      "NOTION_TOKEN": "secret_..."
+    }
   },
   "capabilities": "@strixgov/capabilities-mcp-common/notion",  // import path
   "policy": {
@@ -75,8 +104,13 @@ for a complete example.
     },
     "default": "DENY"
   },
-  "approval": { "enabled": false },
-  "storagePath": "~/.strix-mcp-proxy/notion"    // optional; JSONL receipts on disk
+  "approval": {
+    "enabled": true,
+    "type": "file",                             // headless-friendly approver (see "Approval modes" below)
+    "requestDir": "~/.strix-mcp-proxy/notion/approvals",
+    "timeoutMs": 300000                         // 5 minutes
+  },
+  "storagePath": "~/.strix-mcp-proxy/notion"    // optional (this IS the default for serverId="notion"); set to `null` for ephemeral
 }
 ```
 
@@ -85,6 +119,85 @@ for a complete example.
   `@strixgov/capabilities-mcp-common/github`, etc.) — resolved at startup
 - an inline array of `McpCapability` objects (caller-managed classification)
 
+### Where the upstream's secrets should live
+
+v0.1.x does **no env-var substitution inside the config file** — there
+is no `${NOTION_TOKEN}` template syntax. Two supported patterns for
+upstream secrets:
+
+1. **Set in Claude Desktop's `env` block** (recommended for
+   first-time setup) — the MCP client passes them to the proxy
+   process; the proxy passes `process.env` to the upstream by
+   default. Token never appears in `notion-proxy-config.json`, so
+   the config file is safe to check into source control (without the
+   policy values that depend on environment, of course).
+2. **Set in `upstream.env`** (recommended when the proxy is the
+   only consumer of the upstream) — explicit, narrower exposure
+   surface. Only the keys you list reach the upstream; everything
+   else from `process.env` is filtered out.
+
+On Windows specifically, prefer placing `storagePath` outside any
+OneDrive Known Folder Move directory. The default `~/.strix-mcp-proxy/`
+resolves to `C:\Users\<you>\.strix-mcp-proxy\` (a dotfile-style
+directory under the user root), which is **not** covered by Known
+Folder Move and stays local.
+
+## Approval modes
+
+The proxy's `approval` config field accepts a `type` string that maps to
+the appropriate approver from `@strixgov/tool-gateway`. The gateway's
+underlying `approval.prompt` field expects a function, which JSON config
+can't carry — `type` is the JSON-friendly bridge.
+
+| `approval.type` | What it does | When to use it |
+|---|---|---|
+| omitted, `approval.enabled: false` | No prompt — every `APPROVAL_REQUIRED` decision becomes `DENY` with `reason: "PROMPT_FAILED"`. | Default; safest if you haven't built an approval pathway yet. |
+| `"auto"` | Auto-approves every call that hits the gate. Receipt records `approval.approved: true, approvedBy: "auto"`. | Demos; smoke tests; environments where you want to show the approval-loop wired up without a real human in the loop. **Defeats meaningful governance** for production. |
+| `"file"` | Wires up `fileApprover`: proxy writes `<requestDir>/<requestId>.request.json`; an out-of-band approver writes `<requestId>.response.json` with `{approved, approvedBy?, reason?}`. | Production-leaning headless deployments — Claude Desktop, CI, containerised agents. Pair with whatever notification channel you want (Slack bot, GitHub Actions check, on-call rotation script) that ultimately writes the response file. |
+| `"terminal"` | Interactive `y/N` prompt on stdin. Fails closed (`PROMPT_FAILED → DENY`) in any non-TTY context. | Direct-CLI testing where you're running the proxy yourself and want to manually approve. **Not viable under Claude Desktop spawn** — Claude Desktop owns the stdio channel; there's no terminal to prompt to. |
+
+**Example: file-based approval under Claude Desktop.** In your
+`notion-proxy-config.json`:
+
+```jsonc
+"approval": {
+  "enabled": true,
+  "type": "file",
+  "requestDir": "~/.strix-gateway/approvals",
+  "timeoutMs": 300000        // 5 minutes
+}
+```
+
+Then write a tiny watcher that approves or denies. Example PowerShell
+sketch (one approval at a time):
+
+```powershell
+$watchDir = "$env:USERPROFILE\.strix-gateway\approvals"
+while ($true) {
+  Get-ChildItem $watchDir -Filter "*.request.json" | ForEach-Object {
+    $req = Get-Content $_.FullName | ConvertFrom-Json
+    Write-Host "PENDING: $($req.invocation.capabilityId)  actor=$($req.invocation.actorId)"
+    $answer = Read-Host "Approve? [y/N]"
+    $approved = $answer -in @("y","Y","yes")
+    $respPath = $_.FullName -replace ".request.json$", ".response.json"
+    @{ approved = $approved; approvedBy = $env:USERNAME } | ConvertTo-Json | Set-Content $respPath
+  }
+  Start-Sleep -Milliseconds 500
+}
+```
+
+Operator + audit channels (Slack, PagerDuty, ServiceNow, etc.) replace
+the `Read-Host` line — same file-shape on both ends.
+
+Resolution order if multiple approval fields are set (caller-supplied
+programmatic config wins):
+
+1. `approval.prompt` is a function ⇒ pass through (caller intent wins)
+2. `approval.enabled === false` ⇒ pass through (gate disabled)
+3. `approval.autoApprove === true` ⇒ pass through (long form of `type: "auto"`)
+4. `approval.type ∈ {"auto","file","terminal"}` ⇒ resolved
+5. Unknown `type` ⇒ startup error (fail-fast)
+
 ## CLI flags (no config file needed for simple cases)
 
 ```sh
@@ -104,7 +217,7 @@ Run `strix-mcp-proxy --help` for the full flag list.
 
 ## What ships with the proxy
 
-| Feature | v0.1.0 | v0.2.0 (planned) |
+| Feature | v0.1.x (shipped) | v0.2.0 (planned) |
 |---|---|---|
 | MCP stdio transport (consumer side) | ✓ | — |
 | MCP stdio transport (upstream side) | ✓ | — |
@@ -115,7 +228,7 @@ Run `strix-mcp-proxy --help` for the full flag list.
 | Per-capability rules + risk overrides | ✓ | — |
 | Approval gate (any approver implementation) | ✓ | — |
 | Local-mode signed receipts (in-memory or JSONL) | ✓ | — |
-| Connected mode (sync receipts to `strixgov.com`) | ✓ | — |
+| Connected mode (sync receipts to `strixgov.com`) | ✓ programmatic only via `startProxy({ connectedMode })` | ✓ JSON config |
 | Mode 1 (Observed) | ✓ | — |
 | Mode 2 (Approval-Gated) | ✓ | — |
 | **Mode 3 (Capability-Enforced) — `execution_authorization_v1` token mint + transport** | — | ✓ |
@@ -128,7 +241,7 @@ at each enforcement strength.
 ## The upgrade path to Mode 3
 
 Mode 3 — Capability-Enforced — is the upgrade, not a rewrite. The
-v0.1.0 proxy already routes every outbound call through a single
+v0.1.x proxy already routes every outbound call through a single
 `buildUpstreamIface()` seam in `src/proxy.mjs`. In v0.2.0 a new option
 (`mode: "enforced"`) will wrap that seam with the
 `execution_authorization_v1` token mint + transport step per
@@ -141,10 +254,14 @@ refuse to act on sensitive tools unless the token is present.
 
 The cryptographic primitive is already shipped — see
 [`@strixgov/mcp-token-validator`](https://www.npmjs.com/package/@strixgov/mcp-token-validator).
-v0.1.0 of the proxy does not mint these tokens yet; what it does is
+v0.1.x of the proxy does not mint these tokens yet; what it does is
 make sure the *seam* exists so v0.2.0 plugs in cleanly.
 
-## Listening to receipts
+## Listening to receipts (programmatic embedding)
+
+For embedded use cases (your own MCP host, custom orchestration, etc.)
+where you want a callback on every signed decision rather than
+polling the JSONL file:
 
 ```js
 import { startProxy } from "@strixgov/mcp-proxy";
@@ -160,14 +277,77 @@ const handle = await startProxy({
 });
 ```
 
-Every receipt is byte-compatible with [`@strixgov/verifier`](https://www.npmjs.com/package/@strixgov/verifier):
+For verifying those receipts independently, see the next section.
+
+## Verifying receipts
+
+Every receipt the proxy emits is byte-compatible with
+[`@strixgov/verifier`](https://www.npmjs.com/package/@strixgov/verifier)
+— a zero-Strix-dependency package. The verifier needs two inputs: the
+receipt JSONL file AND the public JWK that signed those receipts. How
+you get the JWK depends on whether you set `storagePath` in your config.
+
+### Default (v0.1.4+)
+
+As of v0.1.4, **`storagePath` defaults to `~/.strix-mcp-proxy/<serverId>`
+when unset**. Receipts persist as JSONL under that path; the Ed25519
+signing key persists at `<storagePath>/keys/{signing-key.pem,
+public-jwk.json}` on first start (PKCS8 PEM at `0600` / public JWK at
+`0644`) and is reused across restarts. The default partitions per
+`serverId` so multiple wrapped upstreams (notion + github + filesystem,
+say) each get their own receipts file and signing key.
+
+The verification command is one line:
 
 ```sh
-npx @strixgov/verifier chain ~/.strix-mcp-proxy/notion/receipts.jsonl
+# macOS / Linux
+npx @strixgov/verifier chain ~/.strix-mcp-proxy/notion/receipts.jsonl \
+  --jwks ~/.strix-mcp-proxy/notion/keys/public-jwk.json
+
+# Windows PowerShell
+npx '@strixgov/verifier' chain "$env:USERPROFILE\.strix-mcp-proxy\notion\receipts.jsonl" `
+  --jwks "$env:USERPROFILE\.strix-mcp-proxy\notion\keys\public-jwk.json"
+```
+
+The verifier resolves `signingKeyId` against the JWKS, recomputes the
+canonical bytes, verifies the Ed25519 signature, walks the proof chain,
+and prints `N/N receipts VERIFIED`. The verifier uses only `node:crypto`;
+no Strix-operated service is in the trust path.
+
+> **Do not alias `storagePath` to `~/.strix-gateway`.** That directory
+> is owned by the `strix-gateway` CLI's keyring, which uses a multi-kid
+> layout (`active` pointer file + `<kid>/` subdirectories). The proxy
+> writes a flat single-key layout (`signing-key.pem` + `public-jwk.json`
+> at the keys/ root) — sharing the same `keys/` dir collides silently:
+> the proxy's flat key files are invisible to the keyring loader, or
+> the v0.1 auto-migration clobbers the gateway's active pointer to the
+> proxy's kid. The default keeps these stores cleanly separated.
+
+### Explicit ephemeral mode (`storagePath: null`)
+
+If you want the pre-v0.1.4 behavior — fresh Ed25519 keypair in memory
+at every startup, never persisted — pass `storagePath: null` explicitly
+to `startProxy`. Receipts within a single proxy session remain chain-
+coherent (each receipt links to the previous one's `proofChainHash`),
+but signatures cannot be verified across restarts.
+
+For a single-session demo, extract the JWK via the programmatic
+`startProxy` handle before the proxy exits:
+
+```js
+import { startProxy } from "@strixgov/mcp-proxy";
+import fs from "node:fs/promises";
+
+const handle = await startProxy({ storagePath: null, /* …your config… */ });
+await fs.writeFile(
+  "./public-jwks.json",
+  JSON.stringify({ keys: [handle.signingKey.publicKeyJwk] }, null, 2),
+);
 ```
 
-The verifier has zero Strix runtime dependency. Strix is not on the
-trust path of receipt verification.
+Then point the verifier at that JWKS file. **For any operational use,
+let `storagePath` default (or set it explicitly) instead** — persistent
+keys are strictly better in every dimension that isn't a one-off demo.
 
 ## What this proxy is NOT
 
@@ -177,9 +357,39 @@ trust path of receipt verification.
   the library; the proxy is the standalone process. They share the
   same governance core (`@strixgov/tool-gateway`) and produce
   byte-identical receipts.
-- **Not Mode 3 today.** v0.1.0 ships Mode 1 + Mode 2. Mode 3
+- **Not an interceptor of HTTP-transport MCP servers.** v0.1.x wraps
+  the stdio transport only. Hosted HTTP MCP servers (the Claude
+  Desktop "Add Connector" URL pattern, e.g.
+  `https://mcp.notion.com/mcp`) are not in scope — the client talks
+  to them over HTTPS directly and no local process exists to wrap.
+  Use the upstream's local stdio server in the meantime; the
+  HTTP-transport story is Posture B in
+  [`docs/architecture/mcp-mode-3-enforcement-v1.md`](https://github.com/Strixgov/strix/tree/main/docs/architecture/mcp-mode-3-enforcement-v1.md).
+- **Not Mode 3 today.** v0.1.x ships Mode 1 + Mode 2. Mode 3
   enforcement is the v0.2.0 upgrade path, designed for, but not
   implemented in, this release.
+- **Not a credential vault.** Upstream tokens (`NOTION_TOKEN`,
+  `GITHUB_TOKEN`, etc.) flow through `process.env` or
+  `upstream.env` and reach the upstream MCP server as-is. The
+  proxy does not store them, and they never appear in signed
+  receipts — receipts carry only the `invocationHash` (SHA-256 of
+  the canonical-JSON of the args), not the raw args themselves.
+  Token persistence is on the roadmap — a stopgap OS-keychain
+  integration and a full OAuth credential broker are both tracked.
+
+## Known issues from real-world dogfood
+
+A handful of failure modes that real first-run integrations have hit.
+Each one has a one-line fix below.
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| Proxy exits at startup with `[strix-proxy] startup failed: Cannot find package '@strixgov/capabilities-mcp-common'` | Companion pack not installed alongside globally-installed proxy. Fixed in `0.1.1+`. | Upgrade: `npm install -g @strixgov/mcp-proxy@latest`. On older versions, install the pack the same way: `npm install -g @strixgov/capabilities-mcp-common`. |
+| Proxy starts, lists tools, but every Notion tool call gets `"decision":"DENY"` even for benign reads | Upstream is the modern `@notionhq/notion-mcp-server` (emits `API-*` tool names), but `@strixgov/capabilities-mcp-common` is at `0.1.0` (only knew the older `notion-*` names). Every call falls through to the heuristic MEDIUM classifier and gets gated. | Upgrade the pack: `npm install -g @strixgov/capabilities-mcp-common@latest` — `0.1.1+` covers both naming conventions (38 Notion tools). |
+| Proxy starts cleanly, exposes the tools list, but tool invocations silently fail (no `tools/call` in Claude Desktop logs, no receipt written) | Observed on Windows + nvm: the upstream MCP server can stall when `@modelcontextprotocol/sdk` isn't resolvable from the proxy's working directory. Cause is environmental (npx + nvm + the upstream's peer-dep resolution), not a proxy bug, but the symptom is opaque enough to be worth documenting. | Belt-and-braces: `cd <storagePath dir> && npm install @modelcontextprotocol/sdk`, then full-quit + relaunch Claude Desktop. |
+| `npx @strixgov/verifier` prints `KEY_NOT_FOUND` for a local-mode receipt | The proxy generates a local signing key (e.g. `signingKeyId: "strix-notion"`) that's not in the public JWKS at `well-known.strixgov.com`. Local mode is intentionally self-rooted. From v0.1.4+ the public JWK is persisted by default at `~/.strix-mcp-proxy/<serverId>/keys/public-jwk.json`. | Point the verifier at the persisted JWK: `npx @strixgov/verifier chain ~/.strix-mcp-proxy/<serverId>/receipts.jsonl --jwks ~/.strix-mcp-proxy/<serverId>/keys/public-jwk.json`. Receipts written under v0.1.0–v0.1.3 with `storagePath` unset (or aliased to `~/.strix-gateway`) are NOT recoverable — their keys were ephemeral. For JWKS-resolvable kids set `STRIX_API_KEY` + `STRIX_TENANT_ID` (connected mode). |
+| `strix-gateway verify` prints `kid not in keyring: strix-<serverId>` for every proxy receipt | You're running `strix-gateway` (gateway CLI) against receipts written by `@strixgov/mcp-proxy`. They are separate stores with incompatible key layouts: the gateway uses a multi-kid keyring (`active` pointer + `<kid>/` subdirs); the proxy writes a flat single-key file. If you also pointed the proxy's `storagePath` at `~/.strix-gateway`, the proxy's key was never registered in the keyring. | Use the package-matched verifier: `npx @strixgov/verifier chain ~/.strix-mcp-proxy/<serverId>/receipts.jsonl --jwks ~/.strix-mcp-proxy/<serverId>/keys/public-jwk.json`. Going forward, leave `storagePath` at its v0.1.4 default (or set it to a path you control that is NOT `~/.strix-gateway`). |
+| Proxy starts, exposes tools, allows reads, but every write or otherwise `APPROVAL_REQUIRED`-tier call returns `"decision":"DENY"` with `reason:"PROMPT_FAILED"` even though `approval.enabled` is `true` | The gateway's default approver is `terminalApprove`, which needs a TTY on stdin. Under Claude Desktop spawn the proxy's stdio is owned by the MCP protocol — there's no terminal, so the prompt fails closed. Fixed in `0.1.3+` via `approval.type: "file"` / `"auto"`. | Upgrade: `npm install -g @strixgov/mcp-proxy@latest` and set `"approval": { "enabled": true, "type": "file", "requestDir": "~/.strix-gateway/approvals" }` (real approval, headless) or `"approval": { "enabled": true, "type": "auto" }` (demo only — auto-approves everything). See "Approval modes" above. |
 
 ## Security posture
 
@@ -195,7 +405,7 @@ posture, including:
 - **Process model** — what happens on crash / mid-approval / disk
   full. Fail-closed at every boundary; the proxy will not start
   without a loadable signing key.
-- **Multi-tenant boundary** — single-tenant by design in v0.1.0;
+- **Multi-tenant boundary** — single-tenant by design in v0.1.x;
   run one proxy process per tenant for isolation.
 - **What the proxy does NOT govern** — out-of-wrapper traffic, the
   agent's internal state, the upstream's own argument handling
@@ -203,10 +413,7 @@ posture, including:
   responsibility).
 
 Report security issues via GitHub Security Advisory on
-`github.com/Strixgov/strix`. The companion operator runbook at
-[`docs/runbooks/operate-mcp-proxy.md`](https://github.com/Tarshann/strix-platform/tree/main/docs/runbooks/operate-mcp-proxy.md)
-covers daily operations, receipt-log rotation, and upgrade
-discipline.
+`github.com/Strixgov/strix`.
 
 ## License
 

package/SECURITY.md

@@ -6,9 +6,10 @@ It answers the questions a security review will ask in the first
 which threats does it cover or not cover.
 
 For the broader Strix threat model (the platform, the verifier,
-the kernel-binding guarantees), see
-[`docs/security/THREAT-MODEL.md`](https://github.com/Tarshann/strix-platform/tree/main/docs/security/THREAT-MODEL.md)
-in the source repository.
+the kernel-binding guarantees), see the threat-model documentation
+distributed with the Strix platform. Authorized reviewers and
+prospective customers can request the current version via
+security@strixgov.com.
 
 ---
 
@@ -197,7 +198,7 @@ The proxy is a single Node.js process. Crash semantics:
 | Proxy crashes mid-tool-call | Upstream call may or may not have started (depends on timing). No receipt is written. The MCP client sees a transport error. | Restart proxy. The action did not execute in any auditable sense. Re-running the same agent input replays the call from scratch. |
 | Upstream crashes during a call | Proxy receives the error from the upstream client. Receipt is written with `decision: "DENY"` (or `"ALLOW"` if policy already approved + upstream failed AFTER consume). Error propagated to client. | Standard MCP error handling on the client side. |
 | Proxy crashes mid-approval | Pending approval is lost (in-memory queue). The held action does not execute. | Restart proxy. The action would need to be re-attempted; the previous approval is gone. |
-| Disk fills up (with `storagePath` set) | New receipt writes fail. The proxy raises an error but does not fall back to silent ALLOW — fail-closed discipline. | Rotate / archive receipts.jsonl (see [`docs/runbooks/operate-mcp-proxy.md`](https://github.com/Tarshann/strix-platform/tree/main/docs/runbooks/operate-mcp-proxy.md) §3) before restarting. |
+| Disk fills up (with `storagePath` set) | New receipt writes fail. The proxy raises an error but does not fall back to silent ALLOW — fail-closed discipline. | Rotate / archive `receipts.jsonl` before restarting. |
 | Signing key not loadable | Constructor throws at startup. **The proxy does not start.** | Fix the key configuration. There is no "governance degraded but tool still runs" state. |
 
 ### 4.1 Receipt-log rotation is operator-owned
@@ -214,8 +215,7 @@ operator-side:
   `receipts.jsonl` then becomes a transient buffer that can be
   rotated aggressively.
 - Anyone running the proxy at non-trivial volume MUST decide on a
-  rotation policy before launching. See
-  [`docs/runbooks/operate-mcp-proxy.md`](https://github.com/Tarshann/strix-platform/tree/main/docs/runbooks/operate-mcp-proxy.md) §3.
+  rotation policy before launching.
 
 This is intentionally not in the proxy itself — log rotation
 strategy is a deployment decision (Node-level `logrotate-stream`?

package/examples/notion-proxy-config.json

@@ -1,4 +1,5 @@
 {
+  "_comment_upstream_env": "Two patterns for the NOTION_TOKEN. Pattern A (recommended for Claude Desktop): omit upstream.env and set NOTION_TOKEN in Claude Desktop's env block — it propagates to the upstream via process.env. Pattern B (explicit): add upstream.env here, e.g. \"env\": { \"NOTION_TOKEN\": \"secret_...\" }. See README 'Where the upstream's secrets should live' for trade-offs.",
   "serverId": "notion",
   "upstream": {
     "command": "npx",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strixgov/mcp-proxy",
-  "version": "0.1.0",
+  "version": "0.1.6",
   "description": "Strix MCP Proxy — the distribution wedge for governed agent tool execution. Point your MCP client at the proxy instead of the underlying server; every callTool is intercepted, evaluated against policy, and emits a signed Ed25519 receipt. Designed so Mode 3 (capability-enforced) is the v0.2.0 upgrade path, not a rewrite.",
   "license": "Elastic-2.0",
   "type": "module",
@@ -17,11 +17,9 @@
   "dependencies": {
     "@strixgov/mcp-adapter": "^0.1.0",
     "@strixgov/tool-gateway": "^0.4.1",
+    "@strixgov/capabilities-mcp-common": "^0.1.0",
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
-  "devDependencies": {
-    "@strixgov/capabilities-mcp-common": "0.1.0"
-  },
   "keywords": [
     "strix",
     "mcp",

package/src/config.mjs

@@ -75,7 +75,32 @@ export async function resolveCapabilities(capabilities) {
       "resolveCapabilities: 'capabilities' must be a string import path or an array",
     );
   }
-  const mod = await import(capabilities);
+  let mod;
+  try {
+    mod = await import(capabilities);
+  } catch (err) {
+    // ERR_MODULE_NOT_FOUND is the common case when a globally-installed
+    // proxy can't resolve a companion pack that wasn't installed alongside
+    // it. Surface an actionable error rather than the bare Node loader
+    // message, since "Cannot find package '...'" gives the operator no
+    // hint that the fix is `npm install -g <the-package>`.
+    if (err && (err.code === "ERR_MODULE_NOT_FOUND" || /Cannot find package/i.test(err.message))) {
+      // Best-effort: peel off the subpath so the suggested install
+      // command targets the bare package name. "@strixgov/capabilities-mcp-common/notion"
+      // → "@strixgov/capabilities-mcp-common".
+      const bare = capabilities.startsWith("@")
+        ? capabilities.split("/").slice(0, 2).join("/")
+        : capabilities.split("/")[0];
+      throw new Error(
+        `resolveCapabilities: cannot load capability pack '${capabilities}'. ` +
+          `If you installed @strixgov/mcp-proxy globally, install the pack the same way: ` +
+          `\`npm install -g ${bare}\`. ` +
+          `Otherwise add '${bare}' to your project's dependencies. ` +
+          `(underlying error: ${err.message})`,
+      );
+    }
+    throw err;
+  }
   // Look for the conventional name (foo → fooCapabilities, *Capabilities,
   // default, or the first exported array). The companion packs use the
   // `<server>Capabilities` convention, so check that first.

package/src/proxy.mjs

@@ -29,7 +29,10 @@
  * maximum coverage of the actual MCP-call surface.
  */
 
+import path from "node:path";
+import os from "node:os";
 import { governMCPServer } from "@strixgov/mcp-adapter";
+import { loadOrCreateSigningKey, fileApprover } from "@strixgov/tool-gateway";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -72,6 +75,34 @@ export async function startProxy(opts) {
     }
   }
 
+  // v0.1.4: default storagePath to ~/.strix-mcp-proxy/<serverId> when unset.
+  //
+  // Pre-0.1.4 left opts.storagePath undefined, which caused governMCPServer
+  // to default both halves of persistence wrong:
+  //   - storage = MemoryStorage (receipts vanish with the process)
+  //   - signingKey = ephemeral generateSigningKey() (kid is in every receipt
+  //     on disk, but the actual key is gone the moment the proxy exits)
+  // The combination silently produced "persistent receipts signed by a key
+  // that no longer exists anywhere", which is the worst possible state —
+  // operators who pointed storagePath at ~/.strix-gateway were getting
+  // receipts they could list but never verify.
+  //
+  // Per-serverId default (not a single shared dir) so multiple wrapped
+  // upstreams cleanly partition their receipts + keys. Intentionally NOT
+  // ~/.strix-gateway: the gateway CLI uses a multi-kid keyring layout
+  // (active pointer + <kid>/ subdirs) and the proxy uses loadOrCreateSigningKey's
+  // flat single-key layout — sharing the same keys/ dir collides silently
+  // (proxy's flat files are invisible to the keyring loader, OR a stale
+  // migration clobbers the gateway's active pointer to the proxy's kid).
+  //
+  // Opt out by passing `storagePath: null` (treated as "I really mean
+  // ephemeral"). Caller-supplied opts.signingKey still wins regardless of
+  // storage choice.
+  const resolvedStoragePath =
+    opts.storagePath === null
+      ? null
+      : opts.storagePath ?? path.join(os.homedir(), ".strix-mcp-proxy", serverId);
+
   // ─── 1. Connect to the upstream MCP server ─────────────────────────────────
   // Test mode lets callers pre-build the upstream client (e.g. with an
   // InMemoryTransport pair) so the proxy can be exercised end-to-end
@@ -97,14 +128,72 @@ export async function startProxy(opts) {
   // ─── 2. Build the iface mcp-adapter expects ───────────────────────────────
   const upstreamIface = buildUpstreamIface(upstreamClient, serverId);
 
-  // ─── 3. Wrap with governMCPServer (Mode 1/2) ───────────────────────────────
+  // ─── 3a. Resolve a persistent signing key when storagePath is set ──────────
+  // Without this, governMCPServer falls back to an in-memory ephemeral key
+  // (`generateSigningKey(\`strix-${serverId}\`)`) — meaning every restart
+  // produces a new key with the same kid and the previous key (the one that
+  // signed receipts already on disk) is gone forever. JSONL receipts on disk
+  // would then be unverifiable: the kid points at a key that doesn't exist
+  // anywhere, including the proxy that wrote them.
+  //
+  // When storagePath is set the operator clearly wants persistent receipts;
+  // it's the natural moment to also persist the signing key alongside them.
+  // The keypair is written to `<storagePath>/keys/{signing-key.pem, public-jwk.json}`
+  // with PKCS8 PEM at 0600 / public JWK at 0644 (mirrors loadOrCreateSigningKey's
+  // own discipline). Caller-supplied `opts.signingKey` still wins.
+  let resolvedSigningKey = opts.signingKey;
+  if (!resolvedSigningKey && resolvedStoragePath) {
+    resolvedSigningKey = await loadOrCreateSigningKey({
+      keyPath: path.join(resolvedStoragePath, "keys"),
+      kid: `strix-${serverId}`,
+    });
+    audit(opts, {
+      kind: "signing.key.resolved",
+      detail: {
+        source: opts.storagePath ? "persistent" : "persistent-default",
+        kid: resolvedSigningKey.kid,
+        keyPath: path.join(resolvedStoragePath, "keys"),
+      },
+    });
+  }
+
+  // ─── 3b. Resolve approval config to an approver function ───────────────────
+  // The gateway's approval expects `prompt: (cap, inv, callOpts) => Promise<...>`
+  // — a function. JSON config can't carry a function, so the proxy translates
+  // a string `approval.type` to the right approver from @strixgov/tool-gateway.
+  //
+  // Why this matters: when the proxy is spawned by Claude Desktop (or any
+  // other MCP client that owns the stdio channel), the default `terminalApprove`
+  // fails closed because stdin/stdout aren't a TTY — every APPROVAL_REQUIRED
+  // call gets denied with `PROMPT_FAILED`. Operators have to pick a headless
+  // approver explicitly. `type: "file"` is the headless default; `type: "auto"`
+  // is the demo shortcut; `type: "terminal"` is the legacy default (works only
+  // when the proxy is run from a real terminal).
+  //
+  // Supported config shapes (all under `approval`):
+  //
+  //   {enabled: false}                                  ← gate disabled, every APPROVAL_REQUIRED → DENY
+  //   {enabled: true}                                   ← terminal (legacy default; fails closed in Claude Desktop)
+  //   {enabled: true, type: "terminal"}                 ← terminal (explicit)
+  //   {enabled: true, type: "auto"}                     ← shortcut for autoApprove: true (demos)
+  //   {enabled: true, type: "file",
+  //    requestDir: "~/.strix-gateway/approvals",        ← request/response file polling (headless)
+  //    timeoutMs: 300000}
+  //   {enabled: true, autoApprove: true}                ← long form of {type: "auto"}
+  //   {enabled: true, prompt: <fn>}                     ← programmatic caller wins (always)
+  const resolvedApproval = resolveApproval(opts.approval, {
+    ...opts,
+    storagePath: resolvedStoragePath,
+  });
+
+  // ─── 3c. Wrap with governMCPServer (Mode 1/2) ──────────────────────────────
   const governed = governMCPServer(upstreamIface, {
     serverId,
     capabilities: opts.capabilities,
     policy: opts.policy ?? { default: "DENY" },
-    approval: opts.approval ?? { enabled: false },
-    storagePath: opts.storagePath,
-    signingKey: opts.signingKey,
+    approval: resolvedApproval,
+    storagePath: resolvedStoragePath,
+    signingKey: resolvedSigningKey,
     connectedMode: opts.connectedMode,
   });
 
@@ -210,3 +299,85 @@ function audit(opts, event) {
     try { opts.onAudit(event); } catch { /* swallow audit-handler errors */ }
   }
 }
+
+/**
+ * Translate the JSON-friendly `approval` config to the function-shaped
+ * approval object the gateway expects.
+ *
+ * Resolution rules (first match wins):
+ *
+ *   1. `approval.prompt` is a function       → pass through unchanged
+ *      (programmatic callers can always inject their own approver).
+ *   2. `approval.enabled === false`          → pass through unchanged
+ *      (no prompt needed; gateway denies every APPROVAL_REQUIRED).
+ *   3. `approval.autoApprove === true`       → pass through unchanged
+ *      (long-form alias for type: "auto").
+ *   4. `approval.type === "auto"`            → set autoApprove: true.
+ *   5. `approval.type === "file"`            → construct fileApprover.
+ *                                              `requestDir` defaults to
+ *                                              `<storagePath>/approvals` if
+ *                                              storagePath is set, otherwise
+ *                                              `./.strix-approvals`.
+ *                                              `~` and `$HOME` are expanded.
+ *   6. `approval.type === "terminal"`        → pass through unchanged
+ *      (gateway defaults to terminalApprove). Fails closed in non-TTY
+ *      environments — fine for direct-CLI testing, broken under
+ *      Claude Desktop spawn.
+ *   7. Unknown `approval.type`               → throw at startup so the
+ *      operator can't misconfigure silently into a fail-closed loop.
+ */
+function resolveApproval(approval, opts) {
+  if (!approval) return { enabled: false };
+
+  // Programmatic callers always win — JSON-config strings are a
+  // convenience for operators, not the source of truth.
+  if (typeof approval.prompt === "function") return approval;
+  if (approval.enabled === false) return approval;
+  if (approval.autoApprove === true) return approval;
+
+  const type = approval.type;
+  if (type === undefined || type === null) return approval;
+
+  if (type === "auto") {
+    return { ...approval, autoApprove: true };
+  }
+
+  if (type === "file") {
+    const requestDirRaw =
+      approval.requestDir ??
+      (opts.storagePath ? path.join(opts.storagePath, "approvals") : "./.strix-approvals");
+    const requestDir = expandHomeTilde(requestDirRaw);
+    return {
+      ...approval,
+      prompt: fileApprover({
+        requestDir,
+        timeoutMs: approval.timeoutMs,
+        pollIntervalMs: approval.pollIntervalMs,
+      }),
+    };
+  }
+
+  if (type === "terminal") {
+    // Pass through; gateway's default is terminalApprove. Operators who
+    // type this explicitly are accepting the non-TTY fail-closed behavior.
+    return approval;
+  }
+
+  throw new Error(
+    `startProxy: unknown approval.type '${type}' — expected "terminal", "file", or "auto"`,
+  );
+}
+
+/**
+ * Expand a leading `~` or `~/` to the OS user-home directory. Mirrors the
+ * tilde-expansion behavior in loadConfig so `~/.strix-gateway/approvals`
+ * resolves consistently across config locations.
+ */
+function expandHomeTilde(p) {
+  if (typeof p !== "string") return p;
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}