@strixgov/mcp-proxy 0.1.0

package/SECURITY.md

@@ -0,0 +1,293 @@
+# Security posture — `@strixgov/mcp-proxy`
+
+This document is the security-team-facing surface for the package.
+It answers the questions a security review will ask in the first
+30 minutes — what does the package hold, where, for how long, and
+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.
+
+---
+
+## 1. Scope
+
+This document covers `@strixgov/mcp-proxy` — the standalone process
+that wraps an upstream MCP server. It applies to v0.1.0 and any
+patch release of that line.
+
+Out of scope:
+
+- The trust path of receipt verification — handled by
+  [`@strixgov/verifier`](https://www.npmjs.com/package/@strixgov/verifier)
+  (MIT, zero-dependency, separate trust root).
+- The execution-authorization token format — handled by
+  [`@strixgov/mcp-token-validator`](https://www.npmjs.com/package/@strixgov/mcp-token-validator),
+  which lands as the Mode 3 enforcement primitive when wiring ships
+  in v0.2.0.
+- The Strix Console + the hosted Connected Mode platform — separate
+  audit posture.
+
+---
+
+## 2. Credential boundary — where do upstream credentials live?
+
+**On disk: never, by design.** The proxy writes signed receipts
+(`receipts.jsonl`) and nothing else. No `.env` file, no credential
+cache, no token store. If you see secrets on disk, something in
+your wrapper script or logging is putting them there — not the
+proxy.
+
+**In memory: depends on which architectural position you deploy.**
+The proxy itself doesn't pin you to one of the three positions
+below; the choice is an integration decision your operator makes.
+
+### Position A — proxy holds the credential
+
+The proxy fetches an upstream credential from a secrets manager
+(or reads it from its own environment) and passes it downstream:
+as a child-process env var (stdio MCP), as an `Authorization`
+header on outbound HTTP, or as an SDK initialization parameter.
+
+| | |
+|---|---|
+| **Credential lives in** | Proxy heap + downstream sink (child env, fetch headers, SDK client object) |
+| **Lifetime** | Proxy process lifetime |
+| **Who can read it** | Anyone with `ptrace` / `/proc/<pid>/mem` access to the proxy UID |
+| **Used when** | Upstream is a binary you spawn (stdio MCP servers), OR an HTTP endpoint where the proxy is the OAuth client |
+| **Audit posture** | Proxy is in scope for credential-handling audit. Treat it as a credential-bearing system. |
+
+### Position B — proxy passes the credential through
+
+Client (e.g. Claude Code / Claude Desktop) supplies the credential
+per-request (header, bearer token). Proxy forwards it to upstream
+unchanged. Proxy sees the bytes in flight but does not retain them
+past the request.
+
+| | |
+|---|---|
+| **Credential lives in** | Per-request heap, GC'd after the response |
+| **Lifetime** | Single request |
+| **Who can read it** | Same as Position A, but only during the request window |
+| **Used when** | Upstream is hosted HTTP and supports OAuth; client is the OAuth client; transparent passthrough |
+| **Audit posture** | Proxy is not a credential-bearing system in steady state. Receipts cannot cryptographically attest actor identity beyond what the client supplies. |
+
+### Position C — proxy never sees the credential
+
+Upstream identity is resolved out-of-band: Workload Identity on
+cloud platforms, IAM role on the instance, OS keychain accessed
+directly by the upstream process, or the upstream binary resolves
+its own secrets from a secrets manager.
+
+| | |
+|---|---|
+| **Credential lives in** | Only the upstream's process / cloud metadata service |
+| **Lifetime** | Upstream lifetime |
+| **Who can read it** | Same UID as the upstream process |
+| **Used when** | Cloud-native deployments; any upstream that supports native secret resolution |
+| **Audit posture** | Cleanest. Proxy is not credential-bearing at all. The credential never crosses the proxy boundary. |
+
+### The decision rule
+
+If your auditor needs to confirm the proxy is **not** a
+credential-bearing system, the answer depends entirely on whether
+you deployed it as Position A, B, or C. The proxy itself does not
+choose for you.
+
+| If your deployment supports it | Use |
+|---|---|
+| Any major cloud / on-prem with Vault Agent or equivalent | **Position C** — cleanest audit story |
+| Upstream is hosted HTTP + supports OAuth + client can be the OAuth client + you don't need cryptographically-verified actor identity in receipts | **Position B** — proxy stays credential-free |
+| Upstream is a binary you spawn (stdio MCP) OR you need the proxy to be the identity broker | **Position A** — proxy is in scope for credential-handling audit, but the receipt's claimed actor identity can be cryptographically attested once AA-1 wiring ships |
+
+Same primitive, three deployment shapes, materially different audit
+and threat-model profiles.
+
+---
+
+## 3. What the proxy stores regardless of position
+
+The four artifacts the proxy holds in any deployment shape:
+
+| Artifact | Contents | Sensitivity | Lifetime / Location |
+|---|---|---|---|
+| `receipts.jsonl` (or in-memory) | Signed canonical payloads: `capabilityId`, `action`, `decision`, `risk`, `mode`, `policyVersion`, `tenantId`, `environment`, **`invocationHash` (SHA-256 of args+actor)**, `evidenceHash`, `proofChainHash`, `timestamp`, `signature`, `signingKeyId`. Receipt also carries `actorId`, `actorRole`, and (if approved) `approvedBy` as un-signed display fields. | **Does NOT contain raw `args`** — only a hash. See §3.1 for what this means in practice. Never contains auth credentials. | On disk at `opts.storagePath` if set; in-memory otherwise (lost on process exit) |
+| Gateway signing key | Ed25519 private key used to sign receipts | Generated per-install if not supplied; **distinct from upstream credentials** | Memory by default. Override via `opts.signingKey` to load from your secrets manager. Persistent storage is operator-managed. |
+| Policy config | Capability rules, risk overrides, fail-closed defaults | **Not secret.** Check it into source control. | Read at startup from the config file or CLI flags |
+| Approval gate state | Pending-approval queue (only if approvals enabled) | Holds pending-action metadata until decided | In-memory by default; lost on process exit unless you wire persistence |
+
+### 3.1 What the receipt does and does not contain
+
+This is the most common question. The honest answer:
+
+| The receipt stores | The receipt does NOT store |
+|---|---|
+| The **capability id** invoked (e.g. `mcp.notion.create_comment`) | The raw tool arguments — only their SHA-256 hash (`invocationHash`) |
+| The **decision** (`ALLOW` / `DENY`) | The agent's prompt or reasoning |
+| The **actor id + role** (e.g. `agent-claude-1` / `agent`) | The tool's response content |
+| The **approver identity** if approval gate fired | The upstream API response body |
+| Timestamps + signing-key id + proof-chain linkage | Auth credentials of any kind |
+
+**Practical implication for receipt sharing:** because raw args
+are NOT in the signed bytes or the on-disk record, you can share
+the receipt JSONL externally **without args-redaction concerns**.
+The signature verifies against `invocationHash`, which is derived
+deterministically from the args + actor fields the agent supplied.
+An auditor can confirm the signed receipt corresponds to a given
+args bundle by hashing their copy of the args and comparing to
+`invocationHash`. If they don't have the args, they can still
+confirm the receipt is authentic, just not what it was authorizing.
+
+This is by design — the receipt is the audit artifact; the args
+themselves are operationally-sensitive call data that the proxy
+**never persists**.
+
+### 3.2 In-memory args sensitivity
+
+While a `callTool` is in flight, the proxy DOES see the raw args
+in memory:
+
+- Args come in from the MCP client via stdio
+- Args flow through `governMCPServer` for policy evaluation +
+  hashing into `invocationHash`
+- Args are forwarded to the upstream MCP server via the proxy's
+  internal client
+
+During this window, an attacker with `ptrace` access to the proxy
+UID can read the args. After the call returns, the args are eligible
+for GC and the only persistent trace is `invocationHash`.
+
+For deployments that need additional in-memory protection (e.g.
+agent args contain regulated data even during a single call),
+combine with a hardened deployment environment: dedicated UID,
+seccomp/AppArmor profile that blocks `ptrace`, no co-tenant
+processes under the same UID. Strix-side mitigations are not the
+right layer.
+
+### 3.3 Signing key lifecycle
+
+The Ed25519 signing key the gateway uses to sign receipts is:
+
+- **Auto-generated** if not supplied (per-process; lost on restart
+  unless `opts.storagePath` is set and the key is persisted by
+  the underlying `@strixgov/tool-gateway` storage). This is fine
+  for development and Mode 1 demonstrations.
+- **Caller-supplied** when `opts.signingKey` is set, OR when an
+  operator runs the tool-gateway's key-management commands to
+  persist a key under `~/.strix/keys/`. Use this in production.
+- **Rotated** by replacing the key + publishing the old public key
+  to the JWKS for the retention window (default 2 years for EU AI
+  Act Article 12 compliance). Historical receipts remain
+  verifiable.
+
+The signing key is **not the same as the upstream credential**.
+Rotating one does not rotate the other; they have different
+lifecycles and different blast radii.
+
+---
+
+## 4. Process model — what happens on failure
+
+The proxy is a single Node.js process. Crash semantics:
+
+| Failure mode | What happens | Recovery |
+|---|---|---|
+| 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. |
+| 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
+
+`receipts.jsonl` has **no built-in rotation** in v0.1.0. A
+high-volume deployment will fill disk. Mitigation is
+operator-side:
+
+- Standard `logrotate(8)` with copytruncate is the simplest path.
+  Configure it to rotate when the file exceeds your retention
+  comfort threshold.
+- Connected Mode customers can configure the strixgov.com
+  platform to be the durable retention store; the local
+  `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.
+
+This is intentionally not in the proxy itself — log rotation
+strategy is a deployment decision (Node-level `logrotate-stream`?
+journald? Connected Mode forwarding?) and baking one in would lock
+operators out of their preferred tooling.
+
+---
+
+## 5. Multi-tenant boundary
+
+The proxy is **single-tenant by design** in v0.1.0.
+
+- One proxy process serves one set of upstream credentials, one
+  signing key, one receipt log.
+- If you run multiple agents through one proxy, they share:
+  - The same upstream credentials (Position A)
+  - The same signing key
+  - The same `receipts.jsonl`
+  - The same approval queue
+
+This is not a bug — it matches how MCP clients (Claude Desktop,
+mcp-cli, IDE integrations) configure MCP servers: one upstream
+per client config entry, with the proxy spawning one process per
+entry.
+
+**If you need per-tenant isolation:** run one proxy process per
+tenant. Each gets its own credentials, signing key, receipt log,
+and approval queue. Resource cost: small (Node process + ~30MB
+RSS). This is the recommended pattern.
+
+Future v0.2.0+ may introduce a multi-tenant variant. Until then,
+**do not share a single proxy process across tenants in
+production** without an explicit threat model that accepts the
+shared-credential + shared-signing-key implications.
+
+---
+
+## 6. What the proxy does NOT govern
+
+For audit clarity — the proxy's surface is bounded:
+
+| Surface | Governed? | Why not |
+|---|---|---|
+| MCP `callTool` requests routed through the proxy | **YES** | The whole point. |
+| MCP `listTools` / `initialize` / other protocol messages | **NO** | These are protocol overhead, not state-changing. No receipts emitted. |
+| Direct API calls the agent makes outside the proxy | **NO** | Out-of-wrapper traffic is invisible to the proxy. Mode 3 (capability enforcement) is the answer here; not shipped in v0.1.0. |
+| The agent's own internal state, prompts, or reasoning | **NO** | The proxy is at the action boundary, not upstream of the model. |
+| The upstream MCP server's internal behavior | **NO** | The proxy trusts the upstream to honor the `callTool` request it forwards. SQL injection, command injection inside the upstream's argument handling — out of scope for the proxy. Mitigation is the upstream's own argument validation. |
+| Network egress from the agent's runtime | **NO** | Network policy is the deployment's responsibility. Mode 3 Posture B (HTTP egress gating) is the architectural answer; Strix Proxy v0.1.0 is the stdio-only variant. |
+| The proxy's own logging / observability backend | **NO** | If you forward proxy logs to a SIEM, you're responsible for what ends up there. The proxy writes audit-relevant content to stderr (lifecycle events) and stdout-MCP-protocol (the protocol channel); receipts go to `receipts.jsonl` or in-memory. |
+
+---
+
+## 7. Reporting security issues
+
+Open a **GitHub Security Advisory** on the public mirror at
+`github.com/Strixgov/strix` for any of:
+
+- Cryptographic findings (signature verification bypass, key
+  recovery, canonicalization drift)
+- Credential leakage paths in the proxy code
+- Authentication / authorization gaps
+- Receipt forgery vectors
+
+For non-security operational issues, use the normal GitHub Issues
+surface or the support channels documented in
+[`COMMERCIAL.md`](./COMMERCIAL.md).
+
+---
+
+## 8. Version history of this document
+
+| Version | Date | Change |
+|---|---|---|
+| 1.0 | 2026-05-23 | Initial publication alongside `@strixgov/mcp-proxy` v0.1.0 |

package/bin/strix-mcp-proxy.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * strix-mcp-proxy — CLI entry.
+ *
+ * Two invocation modes:
+ *
+ *   strix-mcp-proxy --config ./proxy-config.json
+ *
+ *   strix-mcp-proxy \
+ *     --upstream-command npx \
+ *     --upstream-arg "-y" --upstream-arg "@notionhq/notion-mcp-server" \
+ *     --server-id notion \
+ *     --capabilities @strixgov/capabilities-mcp-common/notion \
+ *     --policy-default DENY \
+ *     --risk-low ALLOW --risk-medium APPROVAL_REQUIRED
+ *
+ * The CLI is intentionally minimal — anything elaborate goes in the
+ * config file. Operators wiring this into Claude Desktop, mcp-cli, or
+ * an IDE integration just change their existing MCP command from
+ * `<upstream>` to `strix-mcp-proxy --config <path>`.
+ *
+ * Audit events (proxy lifecycle + denied calls) print to stderr so the
+ * MCP stdio channel on stdout stays clean for the protocol.
+ */
+
+import { startProxy, loadConfig, resolveCapabilities } from "../src/index.mjs";
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+if (argv.includes("--version") || argv.includes("-v")) {
+  const { default: pkg } = await import("../package.json", { with: { type: "json" } });
+  console.log(`strix-mcp-proxy ${pkg.version}`);
+  process.exit(0);
+}
+
+try {
+  const opts = await parseArgs(argv);
+  const handle = await startProxy({
+    ...opts,
+    onAudit: (event) => {
+      // stderr: doesn't collide with the MCP stdio protocol on stdout.
+      console.error(`[strix-proxy] ${event.kind} ${JSON.stringify(event.detail)}`);
+    },
+    onReceipt: (r) => {
+      // One-line summary per receipt; full receipts persist via storagePath when set.
+      console.error(`[strix-proxy] receipt ${r.decision} ${r.capabilityId}`);
+    },
+  });
+
+  const shutdown = async (signal) => {
+    console.error(`[strix-proxy] shutting down (${signal})`);
+    try { await handle.stop(); } catch { /* best-effort */ }
+    process.exit(0);
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+} catch (err) {
+  console.error(`[strix-proxy] startup failed: ${err.message}`);
+  process.exit(1);
+}
+
+// ─── arg parsing ────────────────────────────────────────────────────────────
+
+async function parseArgs(argv) {
+  const flag = (name) => {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const flagAll = (name) => {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+      if (argv[i] === name) out.push(argv[i + 1]);
+    }
+    return out;
+  };
+
+  const configPath = flag("--config");
+  if (configPath) {
+    const cfg = await loadConfig(configPath);
+    return {
+      serverId: cfg.serverId,
+      upstream: cfg.upstream,
+      capabilities: await resolveCapabilities(cfg.capabilities),
+      policy: cfg.policy,
+      approval: cfg.approval,
+      storagePath: cfg.storagePath,
+    };
+  }
+
+  const upstreamCommand = flag("--upstream-command");
+  if (!upstreamCommand) {
+    throw new Error("missing --config or --upstream-command (run with --help)");
+  }
+  const upstreamArgs = flagAll("--upstream-arg");
+  const serverId = flag("--server-id") ?? "proxy";
+  const capabilitiesPath = flag("--capabilities");
+  const policyDefault = flag("--policy-default") ?? "DENY";
+  const riskOverrides = {};
+  for (const level of ["LOW", "MEDIUM", "HIGH", "CRITICAL"]) {
+    const v = flag(`--risk-${level.toLowerCase()}`);
+    if (v) riskOverrides[level] = v;
+  }
+  const approvalEnabled = argv.includes("--approval-enabled");
+  const storagePath = flag("--storage-path");
+
+  return {
+    serverId,
+    upstream: { command: upstreamCommand, args: upstreamArgs },
+    capabilities: capabilitiesPath ? await resolveCapabilities(capabilitiesPath) : undefined,
+    policy: {
+      riskOverrides: Object.keys(riskOverrides).length > 0 ? riskOverrides : undefined,
+      default: policyDefault,
+    },
+    approval: { enabled: approvalEnabled },
+    storagePath,
+  };
+}
+
+function printHelp() {
+  console.log(`strix-mcp-proxy — governed MCP proxy
+
+USAGE
+  strix-mcp-proxy --config <path>
+  strix-mcp-proxy --upstream-command <cmd> [--upstream-arg <a> ...] [other flags]
+
+CONFIG-FILE MODE
+  --config <path>           Path to a JSON config file (see README for shape)
+
+FLAG MODE
+  --upstream-command <cmd>  Command to spawn the upstream MCP server (e.g. "npx")
+  --upstream-arg <arg>      One arg for the upstream command (repeatable)
+  --server-id <id>          Namespace prefix for capability ids (default: "proxy")
+  --capabilities <pkg>      Companion-pack import path
+                            (e.g. @strixgov/capabilities-mcp-common/notion)
+  --policy-default <D>      Default decision for unmatched calls: ALLOW or DENY
+                            (default: DENY)
+  --risk-low <D>            Override decision for LOW-risk calls
+  --risk-medium <D>         Override decision for MEDIUM-risk calls
+  --risk-high <D>           Override decision for HIGH-risk calls
+  --risk-critical <D>       Override decision for CRITICAL-risk calls
+  --approval-enabled        Enable the approval gate (requires custom prompt)
+  --storage-path <dir>      Persist receipts to JSONL at this directory
+                            (default: in-memory)
+
+GENERAL
+  --help, -h                Show this help
+  --version, -v             Show proxy version
+
+The proxy speaks MCP over stdio toward its consumer. Configure your
+MCP-aware client (Claude Desktop, mcp-cli, etc.) to spawn this binary
+in place of the upstream MCP server you previously used directly.
+`);
+}

package/examples/notion-proxy-config.json

@@ -0,0 +1,19 @@
+{
+  "serverId": "notion",
+  "upstream": {
+    "command": "npx",
+    "args": ["-y", "@notionhq/notion-mcp-server"]
+  },
+  "capabilities": "@strixgov/capabilities-mcp-common/notion",
+  "policy": {
+    "riskOverrides": {
+      "LOW": "ALLOW",
+      "MEDIUM": "APPROVAL_REQUIRED",
+      "HIGH": "APPROVAL_REQUIRED",
+      "CRITICAL": "DENY"
+    },
+    "default": "DENY"
+  },
+  "approval": { "enabled": false },
+  "storagePath": "~/.strix-mcp-proxy/notion"
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@strixgov/mcp-proxy",
+  "version": "0.1.0",
+  "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",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./src/types.d.ts",
+      "import": "./src/index.mjs"
+    }
+  },
+  "bin": {
+    "strix-mcp-proxy": "bin/strix-mcp-proxy.mjs"
+  },
+  "dependencies": {
+    "@strixgov/mcp-adapter": "^0.1.0",
+    "@strixgov/tool-gateway": "^0.4.1",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@strixgov/capabilities-mcp-common": "0.1.0"
+  },
+  "keywords": [
+    "strix",
+    "mcp",
+    "model-context-protocol",
+    "proxy",
+    "gateway",
+    "governance",
+    "ai-agents",
+    "execution-control",
+    "signed-receipts",
+    "capability-enforcement"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Strixgov/strix",
+    "directory": "packages/strixgov-mcp-proxy"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    "README.md",
+    "CHANGELOG.md",
+    "COMMERCIAL.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/config.mjs

@@ -0,0 +1,111 @@
+/**
+ * Proxy config loader.
+ *
+ * Config file shape (JSON, no inline comments):
+ *
+ *   {
+ *     "serverId": "notion",
+ *     "upstream": {
+ *       "command": "npx",
+ *       "args": ["-y", "@notionhq/notion-mcp-server"]
+ *     },
+ *     "capabilities": "@strixgov/capabilities-mcp-common/notion",  // dynamic import path
+ *     "policy": {
+ *       "riskOverrides": { "LOW": "ALLOW", "MEDIUM": "APPROVAL_REQUIRED", "CRITICAL": "DENY" },
+ *       "default": "DENY"
+ *     },
+ *     "approval": { "enabled": false },
+ *     "storagePath": "~/.strix-mcp-proxy/receipts"
+ *   }
+ *
+ * The `capabilities` field is either:
+ *   - a bare import path (resolved via dynamic import; must export
+ *     a named or default ReadonlyArray<McpCapability>), or
+ *   - an inline array (already-classified caller-managed list)
+ *
+ * No env-var substitution in v0.1.0 — operators that need secrets
+ * inject them via `upstream.env` from the surrounding shell rather
+ * than embedding them in the config file.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<object>}
+ */
+export async function loadConfig(filePath) {
+  const abs = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(process.cwd(), filePath);
+  let raw;
+  try {
+    raw = await fs.readFile(abs, "utf-8");
+  } catch (err) {
+    throw new Error(`loadConfig: could not read '${abs}': ${err.message}`);
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`loadConfig: '${abs}' is not valid JSON: ${err.message}`);
+  }
+  validateConfig(cfg, abs);
+  if (typeof cfg.storagePath === "string" && cfg.storagePath.startsWith("~")) {
+    cfg.storagePath = cfg.storagePath.replace(/^~/, os.homedir());
+  }
+  return cfg;
+}
+
+/**
+ * Resolve the `capabilities` field of a config to an actual
+ * Array<McpCapability>. Accepts either a bare import path (resolved
+ * via dynamic import) or an inline array.
+ *
+ * @param {string | Array<object> | undefined} capabilities
+ * @returns {Promise<Array<object> | undefined>}
+ */
+export async function resolveCapabilities(capabilities) {
+  if (capabilities === undefined || capabilities === null) return undefined;
+  if (Array.isArray(capabilities)) return capabilities;
+  if (typeof capabilities !== "string") {
+    throw new TypeError(
+      "resolveCapabilities: 'capabilities' must be a string import path or an array",
+    );
+  }
+  const mod = await import(capabilities);
+  // 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.
+  const exportedArrays = Object.entries(mod).filter(([, v]) => Array.isArray(v));
+  const conventional = exportedArrays.find(([k]) => k.endsWith("Capabilities"));
+  if (conventional) return conventional[1];
+  if (Array.isArray(mod.default)) return mod.default;
+  if (exportedArrays.length === 1) return exportedArrays[0][1];
+  throw new Error(
+    `resolveCapabilities: module '${capabilities}' does not export a recognisable capability array ` +
+      `(expected a *Capabilities export, a default export, or a single array export)`,
+  );
+}
+
+// ─── internal ─────────────────────────────────────────────────────────
+
+function validateConfig(cfg, abs) {
+  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) {
+    throw new Error(`loadConfig: '${abs}' must be a JSON object`);
+  }
+  if (!cfg.upstream || typeof cfg.upstream !== "object") {
+    throw new Error(`loadConfig: '${abs}' is missing 'upstream' object`);
+  }
+  if (typeof cfg.upstream.command !== "string" || !cfg.upstream.command) {
+    throw new Error(`loadConfig: '${abs}' is missing 'upstream.command' string`);
+  }
+  if (cfg.upstream.args !== undefined && !Array.isArray(cfg.upstream.args)) {
+    throw new Error(`loadConfig: '${abs}' 'upstream.args' must be an array of strings if present`);
+  }
+  if (cfg.policy !== undefined && (typeof cfg.policy !== "object" || cfg.policy === null)) {
+    throw new Error(`loadConfig: '${abs}' 'policy' must be an object if present`);
+  }
+}

package/src/index.mjs

@@ -0,0 +1,19 @@
+/**
+ * @strixgov/mcp-proxy
+ *
+ * Public API. Two entry points:
+ *
+ *   - `startProxy(opts)` — programmatic. Used by the CLI; tests use it
+ *     with `transport: { kind: "test", ... }`.
+ *   - `loadConfig(path)` — read a proxy config JSON. CLI uses this;
+ *     consumers can use it directly to validate a config before
+ *     committing it to disk.
+ *
+ * Mode 3 (Capability-Enforced) is the v0.2.0 upgrade path. The seam
+ * is documented in src/proxy.mjs (`buildUpstreamIface`); the
+ * cryptographic primitive is already shipped at
+ * `@strixgov/mcp-token-validator`.
+ */
+
+export { startProxy } from "./proxy.mjs";
+export { loadConfig, resolveCapabilities } from "./config.mjs";