@strixgov/mcp-proxy 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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.7]
+
+Adds the webhook approval channel. No change to the receipt format or the
+signing flow.
+
+(Version note: this feature was originally staged under 0.1.6, but
+`0.1.6` had already been published to npm on 2026-06-09 as the
+documentation + license-fidelity patch below — so the webhook channel
+ships as 0.1.7.)
+
+### Added
+- **`approval.type: "webhook"`** — Slack-compatible approval notifications
+  layered on the existing file approver (`src/webhook-approver.mjs`). Each
+  APPROVAL_REQUIRED call still writes the request file and awaits the
+  response file (timeout → DENY, unchanged); the webhook POSTs a
+  `{ text, strix }` payload telling a human what is blocked and how to
+  decide (`npx @strixgov/guard approve <requestId>`). Failure semantics are
+  load-bearing and tested: a failed notification never approves and never
+  auto-denies; a missing/invalid `webhookUrl` fails at startup, not at first
+  call. New config keys: `approval.webhookUrl` (required for the type),
+  `approval.requestDir`, `approval.pollIntervalMs`.
+
+## [0.1.6] — published 2026-06-09
+
+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

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,7 +35,7 @@ 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.0):** the proxy wraps MCP servers that speak
+> **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`
@@ -110,7 +110,19 @@ for a complete example.
     "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
+  "storagePath": "~/.strix-mcp-proxy/notion",   // optional (this IS the default for serverId="notion"); set to `null` for ephemeral
+
+  // Optional. Explicit directory for the persistent Ed25519 signing key,
+  // independent of storagePath. When set, the proxy generates or loads
+  // the key from this path on startup (PKCS8 PEM at 0600 / public JWK
+  // at 0644). Tilde is expanded via os.homedir().
+  //
+  // Useful when you want the signing key in a fixed, predictable location
+  // (e.g. a secrets volume) that is separate from the receipts store.
+  // Takes precedence over the storagePath-derived key location when both
+  // are set. If neither keyPath nor storagePath is set the key is generated
+  // in memory and not persisted.
+  "keyPath": "~/.strix-mcp-proxy/my-server/keys"
 }
 ```
 
@@ -121,7 +133,7 @@ for a complete example.
 
 ### Where the upstream's secrets should live
 
-v0.1.0 does **no env-var substitution inside the config file** — there
+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:
 
@@ -217,7 +229,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) | ✓ | — |
@@ -241,7 +253,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
@@ -254,7 +266,7 @@ 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 (programmatic embedding)
@@ -357,7 +369,7 @@ keys are strictly better in every dimension that isn't a one-off demo.
   the library; the proxy is the standalone process. They share the
   same governance core (`@strixgov/tool-gateway`) and produce
   byte-identical receipts.
-- **Not an interceptor of HTTP-transport MCP servers.** v0.1.0 wraps
+- **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
@@ -365,7 +377,7 @@ keys are strictly better in every dimension that isn't a one-off demo.
   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.0 ships Mode 1 + Mode 2. Mode 3
+- **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`,
@@ -405,7 +417,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

package/bin/strix-mcp-proxy.mjs

@@ -87,6 +87,7 @@ async function parseArgs(argv) {
       policy: cfg.policy,
       approval: cfg.approval,
       storagePath: cfg.storagePath,
+      keyPath: cfg.keyPath,
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strixgov/mcp-proxy",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",
@@ -14,11 +14,14 @@
   "bin": {
     "strix-mcp-proxy": "bin/strix-mcp-proxy.mjs"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "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"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@strixgov/capabilities-mcp-common": "workspace:^0.1.0",
+    "@strixgov/mcp-adapter": "workspace:^0.1.0",
+    "@strixgov/tool-gateway": "workspace:^0.4.1"
   },
   "keywords": [
     "strix",
@@ -52,8 +55,5 @@
   },
   "engines": {
     "node": ">=18.0.0"
-  },
-  "scripts": {
-    "test": "node --test test/*.test.mjs"
   }
-}
+}

package/src/config.mjs

@@ -15,9 +15,17 @@
  *       "default": "DENY"
  *     },
  *     "approval": { "enabled": false },
- *     "storagePath": "~/.strix-mcp-proxy/receipts"
+ *     "storagePath": "~/.strix-mcp-proxy/receipts",
+ *     "keyPath": "~/.strix-mcp-proxy/my-server/keys"
  *   }
  *
+ * `keyPath` (optional): directory for the persistent Ed25519 signing key.
+ * When present, the proxy calls loadOrCreateSigningKey({ keyPath }) on startup:
+ *   - If the key files don't exist they are generated + written there.
+ *   - If they do exist they are loaded.
+ * Tilde is expanded the same way as storagePath.
+ * Takes precedence over the storagePath-derived key location when both are set.
+ *
  * The `capabilities` field is either:
  *   - a bare import path (resolved via dynamic import; must export
  *     a named or default ReadonlyArray<McpCapability>), or
@@ -56,6 +64,9 @@ export async function loadConfig(filePath) {
   if (typeof cfg.storagePath === "string" && cfg.storagePath.startsWith("~")) {
     cfg.storagePath = cfg.storagePath.replace(/^~/, os.homedir());
   }
+  if (typeof cfg.keyPath === "string" && cfg.keyPath.startsWith("~")) {
+    cfg.keyPath = cfg.keyPath.replace(/^~/, os.homedir());
+  }
   return cfg;
 }
 
@@ -133,4 +144,35 @@ function validateConfig(cfg, abs) {
   if (cfg.policy !== undefined && (typeof cfg.policy !== "object" || cfg.policy === null)) {
     throw new Error(`loadConfig: '${abs}' 'policy' must be an object if present`);
   }
+  if (cfg.keyPath !== undefined && typeof cfg.keyPath !== "string") {
+    throw new Error(`loadConfig: '${abs}' 'keyPath' must be a string if present`);
+  }
+  if (cfg.upstreamCredentials !== undefined) {
+    if (
+      typeof cfg.upstreamCredentials !== "object" ||
+      cfg.upstreamCredentials === null ||
+      Array.isArray(cfg.upstreamCredentials)
+    ) {
+      throw new Error(
+        `loadConfig: '${abs}' 'upstreamCredentials' must be an object if present`,
+      );
+    }
+    for (const [envKey, spec] of Object.entries(cfg.upstreamCredentials)) {
+      if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+        throw new Error(
+          `loadConfig: '${abs}' 'upstreamCredentials["${envKey}"]' must be a spec object with a "from" field`,
+        );
+      }
+      if (spec.from !== "keychain" && spec.from !== "env") {
+        throw new Error(
+          `loadConfig: '${abs}' 'upstreamCredentials["${envKey}"].from' must be "keychain" or "env"`,
+        );
+      }
+      if (typeof spec.key !== "string" || !spec.key) {
+        throw new Error(
+          `loadConfig: '${abs}' 'upstreamCredentials["${envKey}"].key' must be a non-empty string`,
+        );
+      }
+    }
+  }
 }

package/src/proxy.mjs

@@ -33,6 +33,7 @@ import path from "node:path";
 import os from "node:os";
 import { governMCPServer } from "@strixgov/mcp-adapter";
 import { loadOrCreateSigningKey, fileApprover } from "@strixgov/tool-gateway";
+import { webhookApprover } from "./webhook-approver.mjs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -53,6 +54,7 @@ import {
  *   policy?: object,
  *   approval?: object,
  *   storagePath?: string,
+ *   keyPath?: string,
  *   signingKey?: object,
  *   connectedMode?: object,
  *   onReceipt?: (receipt: object) => void,
@@ -75,6 +77,41 @@ export async function startProxy(opts) {
     }
   }
 
+  // ─── 0. Resolve upstream credentials ─────────────────────────────────────
+  // When `upstreamCredentials` is supplied (from a JSON config or programmatic
+  // caller), materialise each credential from its declared source — OS keychain
+  // or env var — and merge the result into `upstream.env` before the upstream
+  // process starts.  This keeps secrets out of config files while still feeding
+  // them into the upstream server's environment at the last possible moment.
+  //
+  // Credentials are resolved before the storagePath default / signing-key logic
+  // so that any audit events emitted below see the final env shape.
+  //
+  // @strixgov/mcp-credentials is an optional peer: loaded dynamically so the
+  // proxy itself doesn't hard-depend on keytar.  When the field is absent we
+  // skip this step entirely (no import, no overhead).
+  let resolvedUpstreamEnv = opts.upstream?.env;
+  if (opts.upstreamCredentials && transportKind === "stdio") {
+    let resolveUpstreamCredentials;
+    try {
+      const mod = await import("@strixgov/mcp-credentials");
+      resolveUpstreamCredentials = mod.resolveUpstreamCredentials;
+    } catch {
+      throw new Error(
+        "startProxy: 'upstreamCredentials' requires @strixgov/mcp-credentials. " +
+          "Install it alongside the proxy: npm install @strixgov/mcp-credentials",
+      );
+    }
+    const credEnv = await resolveUpstreamCredentials(opts.upstreamCredentials);
+    // Merge: explicit upstream.env takes precedence over resolved credentials
+    // so operators can still override individual values at the shell level.
+    resolvedUpstreamEnv = { ...credEnv, ...(opts.upstream?.env ?? {}) };
+    audit(opts, {
+      kind: "credentials.resolved",
+      detail: { envKeys: Object.keys(credEnv) },
+    });
+  }
+
   // v0.1.4: default storagePath to ~/.strix-mcp-proxy/<serverId> when unset.
   //
   // Pre-0.1.4 left opts.storagePath undefined, which caused governMCPServer
@@ -119,7 +156,7 @@ export async function startProxy(opts) {
     const upstreamTransport = new StdioClientTransport({
       command: opts.upstream.command,
       args: opts.upstream.args ?? [],
-      env: opts.upstream.env ?? process.env,
+      env: resolvedUpstreamEnv ?? process.env,
     });
     await upstreamClient.connect(upstreamTransport);
     audit(opts, { kind: "upstream.connected", detail: { command: opts.upstream.command } });
@@ -142,6 +179,19 @@ export async function startProxy(opts) {
   // with PKCS8 PEM at 0600 / public JWK at 0644 (mirrors loadOrCreateSigningKey's
   // own discipline). Caller-supplied `opts.signingKey` still wins.
   let resolvedSigningKey = opts.signingKey;
+  // keyPath takes precedence over storagePath-derived key location when both
+  // are present (operators who want a stable key location independent of the
+  // receipt store can set keyPath without setting storagePath).
+  if (!resolvedSigningKey && opts.keyPath) {
+    resolvedSigningKey = await loadOrCreateSigningKey({
+      keyPath: opts.keyPath,
+      kid: `strix-${serverId}`,
+    });
+    audit(opts, {
+      kind: "signing.key.resolved",
+      detail: { source: "keyPath", kid: resolvedSigningKey.kid, keyPath: opts.keyPath },
+    });
+  }
   if (!resolvedSigningKey && resolvedStoragePath) {
     resolvedSigningKey = await loadOrCreateSigningKey({
       keyPath: path.join(resolvedStoragePath, "keys"),
@@ -179,6 +229,9 @@ export async function startProxy(opts) {
   //   {enabled: true, type: "file",
   //    requestDir: "~/.strix-gateway/approvals",        ← request/response file polling (headless)
   //    timeoutMs: 300000}
+  //   {enabled: true, type: "webhook",
+  //    webhookUrl: "https://hooks.slack.com/...",       ← file polling + Slack-compatible
+  //    requestDir: "...", timeoutMs: 300000}              notification per pending request
   //   {enabled: true, autoApprove: true}                ← long form of {type: "auto"}
   //   {enabled: true, prompt: <fn>}                     ← programmatic caller wins (always)
   const resolvedApproval = resolveApproval(opts.approval, {
@@ -363,8 +416,32 @@ function resolveApproval(approval, opts) {
     return approval;
   }
 
+  if (type === "webhook") {
+    // Slack-compatible notification layered on the file primitive: the
+    // request/response files stay the decision channel (timeout → DENY
+    // unchanged); the webhook only tells a human where to look. A failed
+    // notification never approves and never auto-denies — see
+    // webhook-approver.mjs for the full failure semantics.
+    const requestDirRaw =
+      approval.requestDir ??
+      (opts.storagePath ? path.join(opts.storagePath, "approvals") : "./.strix-approvals");
+    const requestDir = expandHomeTilde(requestDirRaw);
+    return {
+      ...approval,
+      prompt: webhookApprover({
+        webhookUrl: approval.webhookUrl,
+        serverId: opts.serverId,
+        requestDir,
+        timeoutMs: approval.timeoutMs,
+        pollIntervalMs: approval.pollIntervalMs,
+        onAudit: (event) => audit(opts, event),
+        fetchImpl: approval.fetchImpl, // programmatic/test seam; not JSON-configurable
+      }),
+    };
+  }
+
   throw new Error(
-    `startProxy: unknown approval.type '${type}' — expected "terminal", "file", or "auto"`,
+    `startProxy: unknown approval.type '${type}' — expected "terminal", "file", "webhook", or "auto"`,
   );
 }
 

package/src/types.d.ts

@@ -20,7 +20,15 @@ export interface ProxyOptions {
   approval?: {
     enabled?: boolean;
     prompt?: (cap: object, invocation: object, opts: object) => Promise<{ approved: boolean; approver?: string }>;
+    /** JSON-config approver selector: "terminal" | "file" | "webhook" | "auto". */
+    type?: "terminal" | "file" | "webhook" | "auto";
+    autoApprove?: boolean;
+    /** type "file" | "webhook": request/response directory (~ expanded). */
+    requestDir?: string;
+    /** type "webhook": Slack-compatible notification URL (http/https). Decision still flows via the response file. */
+    webhookUrl?: string;
     timeoutMs?: number;
+    pollIntervalMs?: number;
   };
   storagePath?: string;
   signingKey?: object;

package/src/webhook-approver.mjs

@@ -0,0 +1,159 @@
+/**
+ * Webhook approval channel — Slack-compatible notification on top of the
+ * gateway's file approver.
+ *
+ * Design (deliberate): the tool-gateway `fileApprover` is the headless
+ * approval PRIMITIVE — request file written, response file awaited,
+ * timeout → DENY. Its contract explicitly says network adapters belong
+ * ON TOP of that primitive, not inside it. This module is that adapter:
+ *
+ *   1. fileApprover writes `<requestId>.request.json` as always.
+ *   2. `onRequestWritten` fires a POST to `webhookUrl` with a
+ *      Slack-incoming-webhook-compatible body (`{ text }`) plus a
+ *      structured `strix` block for non-Slack consumers.
+ *   3. The DECISION still arrives as the response file — written by a
+ *      human via `npx @strixgov/guard approve <requestId>`, a Slack
+ *      workflow, a bot, or any out-of-band channel.
+ *
+ * Failure semantics (load-bearing):
+ *   - Notification failure NEVER approves and NEVER auto-denies. The
+ *     request file is already on disk; the approver keeps waiting and
+ *     the existing timeout → DENY applies. A lost Slack message must
+ *     not silently deny a legitimate call, and must never allow one.
+ *   - Missing/invalid `webhookUrl` fails at STARTUP (config error),
+ *     not at first call — an operator can't misconfigure silently
+ *     into a notification-less loop.
+ *
+ * No new dependency: uses global fetch (Node >= 18).
+ */
+
+import { fileApprover } from "@strixgov/tool-gateway";
+
+/** Max characters of the args preview embedded in the notification. */
+const ARGS_PREVIEW_MAX = 240;
+
+/**
+ * Build the Slack-compatible notification body for a pending approval.
+ * Exported for tests (pure).
+ *
+ * @param {{ requestId: string, serverId?: string, capability: object, invocation: object }} req
+ * @returns {{ text: string, strix: object }}
+ */
+export function buildWebhookPayload(req) {
+  const cap = req.capability ?? {};
+  const inv = req.invocation ?? {};
+  let argsPreview = "<none>";
+  if (inv.args !== undefined && inv.args !== null) {
+    try {
+      const s = JSON.stringify(inv.args);
+      argsPreview = s.length > ARGS_PREVIEW_MAX ? `${s.slice(0, ARGS_PREVIEW_MAX - 3)}...` : s;
+    } catch {
+      argsPreview = "<unserializable>";
+    }
+  }
+  const lines = [
+    ":shield: *Strix approval required*",
+    `*Server:* ${req.serverId ?? "unknown"}`,
+    `*Capability:* ${cap.id ?? inv.capabilityId ?? "unknown"} (risk: ${cap.risk ?? "unknown"})`,
+    `*Action:* ${inv.action ?? "unknown"}`,
+    `*Args:* \`${argsPreview}\``,
+    `*Request:* \`${req.requestId}\``,
+    "",
+    `Approve: \`npx @strixgov/guard approve ${req.requestId}\``,
+    `Deny:    \`npx @strixgov/guard deny ${req.requestId}\``,
+  ];
+  return {
+    text: lines.join("\n"),
+    // Structured mirror for non-Slack webhook consumers (Slack ignores
+    // unknown top-level keys). Contains no more than the request file does.
+    strix: {
+      kind: "approval.requested",
+      requestId: req.requestId,
+      serverId: req.serverId,
+      capabilityId: cap.id ?? inv.capabilityId,
+      risk: cap.risk,
+      action: inv.action,
+    },
+  };
+}
+
+/**
+ * Construct the webhook approver prompt function.
+ *
+ * @param {{
+ *   webhookUrl: string,
+ *   serverId?: string,
+ *   requestDir: string,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   onAudit?: (event: { kind: string, detail: object }) => void,
+ *   fetchImpl?: typeof fetch,   // test seam only
+ * }} opts
+ */
+export function webhookApprover(opts) {
+  const { webhookUrl } = opts ?? {};
+  if (typeof webhookUrl !== "string" || webhookUrl.length === 0) {
+    throw new Error(
+      'webhookApprover: approval.type "webhook" requires approval.webhookUrl',
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(webhookUrl);
+  } catch {
+    throw new Error(`webhookApprover: approval.webhookUrl is not a valid URL: '${webhookUrl}'`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(
+      `webhookApprover: approval.webhookUrl must be http(s), got '${parsed.protocol}'`,
+    );
+  }
+  const doFetch = opts.fetchImpl ?? fetch;
+  const audit = (event) => {
+    if (typeof opts.onAudit === "function") {
+      try { opts.onAudit(event); } catch { /* never let audit break approval */ }
+    }
+  };
+
+  let pendingRequest = null;
+  const inner = fileApprover({
+    requestDir: opts.requestDir,
+    timeoutMs: opts.timeoutMs,
+    pollIntervalMs: opts.pollIntervalMs,
+    onRequestWritten: async (_requestPath, requestId) => {
+      const payload = buildWebhookPayload({ ...pendingRequest, requestId });
+      try {
+        const res = await doFetch(webhookUrl, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(payload),
+        });
+        if (res.ok) {
+          audit({ kind: "approval.webhook.notified", detail: { requestId, status: res.status } });
+        } else {
+          audit({
+            kind: "approval.webhook.notify_failed",
+            detail: { requestId, status: res.status },
+          });
+        }
+      } catch (err) {
+        // Best-effort notification: the request file is the source of
+        // truth; the decision path (response file / timeout DENY) is
+        // unaffected by a lost notification.
+        audit({
+          kind: "approval.webhook.notify_failed",
+          detail: { requestId, error: err?.message ?? String(err) },
+        });
+      }
+    },
+  });
+
+  return async function webhookApproverPrompt(capability, invocation, callOpts) {
+    pendingRequest = { serverId: opts.serverId, capability, invocation };
+    try {
+      return await inner(capability, invocation, callOpts);
+    } finally {
+      pendingRequest = null;
+    }
+  };
+}