intent-envelope-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# intent-envelope-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Enforce an intent envelope on an MCP server. A tool call outside the envelope is refused
+before it reaches the server.
+
+Your MCP client launches this instead of the server it wants. Every tool call crosses
+this process, is decided against the envelope, and is forwarded only if the envelope
+permits it. Nothing about the client changes, and no code in your agent changes.
+
+```
+your agent  ──►  intent-envelope-mcp  ──►  the MCP server
+                 (decides, then forwards or refuses)
+```
+
+Implements [Intent Envelope 0.1](../../spec/v0.1.md). Apache-2.0.
+
+## Why a separate process
+
+The component that decides what an agent may do is not the component an attacker is
+talking to. An agent can be argued into anything; it cannot argue with a process that
+does not read its reasoning. The envelope is read from disk before the first message is
+accepted and is never re-read, so there is no tool call, argument, document or
+notification that changes what is permitted.
+
+## Install
+
+```sh
+npm install -g intent-envelope-mcp
+```
+
+Requires Node 22.18 or newer. The only dependency is
+[`intent-envelope`](../typescript) itself.
+
+## Use
+
+```sh
+intent-envelope-mcp --envelope ./ap-agent.json -- npx -y @acme/invoice-mcp
+```
+
+Everything after `--` is the server to govern. In a client config, wrap what you already
+had:
+
+```json
+{
+  "mcpServers": {
+    "invoices": {
+      "command": "intent-envelope-mcp",
+      "args": [
+        "--envelope", "/etc/intent-envelopes/ap-agent.json",
+        "--ledger", "/var/log/ap-agent-decisions.jsonl",
+        "--", "npx", "-y", "@acme/invoice-mcp"
+      ]
+    }
+  }
+}
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--envelope <path>` | the envelope to enforce, or `INTENT_ENVELOPE` |
+| `--ledger <path>` | append decisions as JSON lines, or `INTENT_ENVELOPE_LEDGER` |
+| `--no-filter-tools` | advertise every upstream tool, refusing the ones not granted |
+
+An envelope that fails validation stops the process with exit code 2 before it accepts a
+message. An enforcement point that starts with an envelope it cannot understand is worse
+than one that does not start, because the client assumes it is running.
+
+## What a refusal looks like
+
+A refused call returns a JSON-RPC error rather than a tool result. The tool never ran, so
+reporting it as a result that failed would be a lie the agent then reasons from.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "error": {
+    "code": -32000,
+    "message": "intent envelope: refused by tools.deny: issue_payment is on tools.deny, which no later grant overrides",
+    "data": {
+      "intent_envelope": {
+        "envelope_id": "invoice-reconciler",
+        "revision": 3,
+        "agent_identity": "invoice-reconciler",
+        "tool": "issue_payment",
+        "result": "deny",
+        "rule": "tools.deny",
+        "decided_at": "2026-11-03T16:09:44.812Z"
+      }
+    }
+  }
+}
+```
+
+Two codes, because collapsing them would turn "a named person must decide this" into
+"no":
+
+| Code | Meaning |
+| --- | --- |
+| `-32000` | refused by the envelope |
+| `-32001` | a named human must approve this call |
+
+## The ledger
+
+With `--ledger`, every decision is appended as one JSON object per line, flushed as it is
+made. Refusals are recorded, not only successes: a log holding what succeeded cannot
+answer the question an incident asks, which is what the agent tried to do.
+
+Each record names the envelope, its revision, the agent identity, the tool, the result,
+the rule that decided and when, which is enough to reconstruct a run months later against
+the exact envelope revision in force at the time.
+
+If the ledger cannot be written, enforcement continues and the failure is reported once
+on stderr. Refusing correctly while unable to log is degraded; allowing calls because a
+disk filled up would be a breach.
+
+## See it work
+
+```sh
+node demo/poisoned-invoice.mjs
+```
+
+An agent reads a supplier invoice containing instructions, believes every word, and
+carries them out in order. Nothing detects the injection, no prompt asks the model to be
+careful, and there is no classifier. The exfiltration and the payment are refused anyway.
+The invoice server's own stderr shows it ran only the two calls the envelope permitted.
+
+The document also tells the agent not to involve a human. That instruction has nothing to
+enforce it, so the mismatch escalates regardless.
+
+## What this does not do
+
+Worth being explicit, because a guardrail people misunderstand is worse than none.
+
+- **It does not wait for a human.** An escalation is recorded as an escalation and the
+  call is refused with the name of who must approve it. There is no approval channel yet,
+  so `on_no_response: allow` is **not** honoured: escalated calls are refused rather than
+  allowed, and the process says so on startup if your envelope sets it. Being stricter
+  than the envelope asked is the safe direction, but it is a difference and you should
+  know about it.
+- **Tool filtering is not the gate.** `tools/list` is filtered to what the envelope
+  grants, which reduces what the model is tempted by, but a client can call any name it
+  likes. The guarantee comes from intercepting `tools/call`, which happens whether or not
+  the tool was ever advertised. `--no-filter-tools` turns the cosmetic half off and
+  changes nothing about enforcement.
+- **It governs one server.** Run one of these per server you want governed, which is how
+  MCP client configs are shaped anyway. Calls that reach a server by some other route are
+  not governed by it, so the envelope is only as good as the chokepoint you put it in.
+- **It does not inspect prompts or model output.** It decides tool calls. An agent talked
+  into something that stays inside its envelope is not something this notices.
+- **`max_runtime_seconds` is not enforced**, because this process does not own your run
+  loop and cannot tell a slow tool from a long think.
+
+## Why a line relay rather than the MCP SDK
+
+This understands exactly two methods and relays every other line byte for byte.
+
+The protocol has two eras in circulation, one using `server/discover` with inline `_meta`
+and one using the `initialize` handshake, and it keeps growing: `subscriptions/listen`,
+`notifications/cancelled`, `InputRequiredResult`. A proxy built on a protocol library
+would have to model all of it and would break on the next addition. A relay that forwards
+what it does not recognise works across both eras and survives additions it has never
+heard of. An unparseable line is passed along untouched, because this process is not the
+arbiter of protocol validity; it is the arbiter of one question.
+
+It also keeps the dependency count at one.
+
+## Development
+
+```sh
+npm test            # end to end over real pipes, against a server that records calls
+npm run typecheck
+npm run smoke       # pack, install the tarball, run the installed binary
+npm run build
+```
+
+The suite's central assertion is not that the client saw an error. It is that the refused
+call is **absent from the upstream server's own record**. Breaking the interception so
+calls are recorded and then forwarded anyway fails eight of the sixteen tests, which is
+the behaviour a logger-pretending-to-be-a-guardrail would have.

package/dist/bin.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * The command an MCP client launches in place of the server it wants governed.
+ *
+ * Exit codes: 0 if the upstream exited cleanly, the upstream's own code if it did not,
+ * and 2 for a configuration problem here. A client that cannot tell the difference
+ * between "the server failed" and "the envelope was unreadable" cannot be debugged.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;GAMG"}

package/dist/bin.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * The command an MCP client launches in place of the server it wants governed.
+ *
+ * Exit codes: 0 if the upstream exited cleanly, the upstream's own code if it did not,
+ * and 2 for a configuration problem here. A client that cannot tell the difference
+ * between "the server failed" and "the envelope was unreadable" cannot be debugged.
+ */
+import { spawn } from 'node:child_process';
+import { ConfigError, parse } from "./config.js";
+import { fileLedger, memoryLedger } from "./ledger.js";
+import { Relay } from "./relay.js";
+const log = (message) => process.stderr.write(`[intent-envelope] ${message}\n`);
+function main() {
+    let config;
+    try {
+        config = parse(process.argv.slice(2), process.env);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            process.stderr.write(`${error.message}\n`);
+            process.exit(2);
+        }
+        // A schema failure arrives here. It names the field, which is the useful part.
+        process.stderr.write(`[intent-envelope] the envelope is not valid: ${error.message}\n`);
+        process.exit(2);
+    }
+    const { envelope, command, args } = config;
+    log(`enforcing ${envelope.id} revision ${envelope.revision ?? 1} on: ${command} ${args.join(' ')}`);
+    const upstream = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    upstream.on('error', (error) => {
+        log(`cannot start the server: ${error.message}`);
+        process.exit(2);
+    });
+    const ledger = config.ledgerPath ? fileLedger(config.ledgerPath, log) : memoryLedger();
+    const relay = new Relay({
+        envelope,
+        ledger,
+        upstream,
+        input: process.stdin,
+        output: process.stdout,
+        log,
+        filterToolList: config.filterToolList,
+    });
+    relay.start();
+    upstream.on('exit', (code, signal) => {
+        const counts = relay.summary();
+        log(`${counts.allow} allowed, ${counts.deny} refused, ${counts.escalate} escalated`);
+        if (config.ledgerPath)
+            log(`ledger: ${config.ledgerPath}`);
+        process.exit(signal ? 1 : (code ?? 0));
+    });
+}
+main();
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where the envelope and the upstream server come from.
+ *
+ * Both are supplied by whoever launches this process, never by the agent running
+ * behind it and never by anything the upstream server says. The envelope is read from
+ * disk once, before the first message is accepted, and is not re-read. There is no
+ * message an agent can send that changes what it is allowed to do.
+ */
+import { type Envelope } from 'intent-envelope';
+export interface Config {
+    envelope: Envelope;
+    envelopePath: string;
+    command: string;
+    args: string[];
+    ledgerPath?: string;
+    filterToolList: boolean;
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare const USAGE = "intent-envelope-mcp: enforce an intent envelope on an MCP server\n\n  intent-envelope-mcp --envelope <path> [options] -- <server-command> [server-args...]\n\nOptions\n  --envelope <path>    the envelope to enforce (or INTENT_ENVELOPE)\n  --ledger <path>      append decisions here as JSON lines (or INTENT_ENVELOPE_LEDGER)\n  --no-filter-tools    advertise every upstream tool, refusing the ones not granted\n  --help\n\nEverything after -- is the server to govern, run as a child process.\n\n  intent-envelope-mcp --envelope ./ap-agent.json -- npx -y @acme/invoice-mcp\n\nPoint your MCP client at this command instead of the server's own. Nothing else about\nthe client changes.";
+/**
+ * Parse argv in the shape `[options] -- command args...`.
+ *
+ * The separator is required. Guessing where options end and the server command begins
+ * invites a mistake in which an option meant for this process is handed to the server,
+ * or worse, the reverse.
+ */
+export declare function parse(argv: string[], env?: Record<string, string | undefined>): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE1D,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,KAAK,4qBAeE,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,GAAG,MAAM,CAmC1F"}

package/dist/config.js

@@ -0,0 +1,79 @@
+/**
+ * Where the envelope and the upstream server come from.
+ *
+ * Both are supplied by whoever launches this process, never by the agent running
+ * behind it and never by anything the upstream server says. The envelope is read from
+ * disk once, before the first message is accepted, and is not re-read. There is no
+ * message an agent can send that changes what it is allowed to do.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { validate } from 'intent-envelope';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+export const USAGE = `intent-envelope-mcp: enforce an intent envelope on an MCP server
+
+  intent-envelope-mcp --envelope <path> [options] -- <server-command> [server-args...]
+
+Options
+  --envelope <path>    the envelope to enforce (or INTENT_ENVELOPE)
+  --ledger <path>      append decisions here as JSON lines (or INTENT_ENVELOPE_LEDGER)
+  --no-filter-tools    advertise every upstream tool, refusing the ones not granted
+  --help
+
+Everything after -- is the server to govern, run as a child process.
+
+  intent-envelope-mcp --envelope ./ap-agent.json -- npx -y @acme/invoice-mcp
+
+Point your MCP client at this command instead of the server's own. Nothing else about
+the client changes.`;
+/**
+ * Parse argv in the shape `[options] -- command args...`.
+ *
+ * The separator is required. Guessing where options end and the server command begins
+ * invites a mistake in which an option meant for this process is handed to the server,
+ * or worse, the reverse.
+ */
+export function parse(argv, env = {}) {
+    const separator = argv.indexOf('--');
+    const flags = separator === -1 ? argv : argv.slice(0, separator);
+    const rest = separator === -1 ? [] : argv.slice(separator + 1);
+    let envelopePath = env.INTENT_ENVELOPE;
+    let ledgerPath = env.INTENT_ENVELOPE_LEDGER;
+    let filterToolList = true;
+    for (let i = 0; i < flags.length; i += 1) {
+        const flag = flags[i];
+        if (flag === '--envelope')
+            envelopePath = flags[++i];
+        else if (flag === '--ledger')
+            ledgerPath = flags[++i];
+        else if (flag === '--no-filter-tools')
+            filterToolList = false;
+        else if (flag === '--help' || flag === '-h')
+            throw new ConfigError(USAGE);
+        else
+            throw new ConfigError(`unknown option ${flag}\n\n${USAGE}`);
+    }
+    if (!envelopePath)
+        throw new ConfigError(`no envelope given\n\n${USAGE}`);
+    if (rest.length === 0)
+        throw new ConfigError(`no server command given after --\n\n${USAGE}`);
+    const path = resolve(envelopePath);
+    let envelope;
+    try {
+        envelope = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new ConfigError(`cannot read the envelope at ${path}: ${reason}`);
+    }
+    // Fail closed. An enforcement point that starts with an envelope it cannot understand
+    // is worse than one that does not start, because the client will assume it is running.
+    validate(envelope);
+    return { envelope, envelopePath: path, command: rest[0], args: rest.slice(1), ledgerPath, filterToolList };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Enforce an intent envelope on an MCP server, in the wire protocol itself.
+ *
+ * The command in bin.ts is the usual way to use this. These exports are for embedding
+ * the relay in a host that already owns its own process and streams.
+ */
+export { ConfigError, USAGE, parse, type Config } from './config.ts';
+export { fileLedger, memoryLedger, type Ledger } from './ledger.ts';
+export { DENIED, ESCALATION_REQUIRED, Relay, type RelayOptions } from './relay.ts';
+export declare const VERSION = "0.2.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAEnF,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Enforce an intent envelope on an MCP server, in the wire protocol itself.
+ *
+ * The command in bin.ts is the usual way to use this. These exports are for embedding
+ * the relay in a host that already owns its own process and streams.
+ */
+export { ConfigError, USAGE, parse } from "./config.js";
+export { fileLedger, memoryLedger } from "./ledger.js";
+export { DENIED, ESCALATION_REQUIRED, Relay } from "./relay.js";
+export const VERSION = '0.2.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAe,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AAEnF,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/dist/ledger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Every decision, appended as it is made.
+ *
+ * Refusals are recorded, not only successes. A log holding what succeeded cannot answer
+ * the question an incident asks, which is what the agent tried to do.
+ *
+ * One JSON object per line, append only, flushed per decision. A ledger that buffers
+ * loses exactly the records an operator wants when a process is killed mid-run, and the
+ * run where that happens is the interesting one.
+ */
+import type { Decision, DecisionRecord } from 'intent-envelope';
+export interface Ledger {
+    record(decision: Decision): void;
+    entries(): DecisionRecord[];
+}
+/** Keeps decisions in memory only. Used by the tests and when no path is configured. */
+export declare function memoryLedger(): Ledger;
+/**
+ * Appends to a file as well as keeping them in memory.
+ *
+ * A failed write must not take the enforcement point down with it: refusing calls
+ * correctly while unable to log is a degraded state, but silently allowing them because
+ * a disk filled up is a breach. So a write failure is reported once, to stderr, and
+ * enforcement carries on.
+ */
+export declare function fileLedger(path: string, onError?: (message: string) => void): Ledger;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEhE,MAAM,WAAW,MAAM;IACrB,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACjC,OAAO,IAAI,cAAc,EAAE,CAAC;CAC7B;AAED,wFAAwF;AACxF,wBAAgB,YAAY,IAAI,MAAM,CAQrC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAsBpF"}

package/dist/ledger.js

@@ -0,0 +1,51 @@
+/**
+ * Every decision, appended as it is made.
+ *
+ * Refusals are recorded, not only successes. A log holding what succeeded cannot answer
+ * the question an incident asks, which is what the agent tried to do.
+ *
+ * One JSON object per line, append only, flushed per decision. A ledger that buffers
+ * loses exactly the records an operator wants when a process is killed mid-run, and the
+ * run where that happens is the interesting one.
+ */
+import { appendFileSync } from 'node:fs';
+/** Keeps decisions in memory only. Used by the tests and when no path is configured. */
+export function memoryLedger() {
+    const held = [];
+    return {
+        record: (decision) => {
+            held.push(decision.record());
+        },
+        entries: () => held.slice(),
+    };
+}
+/**
+ * Appends to a file as well as keeping them in memory.
+ *
+ * A failed write must not take the enforcement point down with it: refusing calls
+ * correctly while unable to log is a degraded state, but silently allowing them because
+ * a disk filled up is a breach. So a write failure is reported once, to stderr, and
+ * enforcement carries on.
+ */
+export function fileLedger(path, onError) {
+    const memory = memoryLedger();
+    let warned = false;
+    return {
+        record: (decision) => {
+            memory.record(decision);
+            try {
+                appendFileSync(path, `${JSON.stringify(decision.record())}\n`, 'utf8');
+            }
+            catch (error) {
+                if (!warned) {
+                    warned = true;
+                    const reason = error instanceof Error ? error.message : String(error);
+                    (onError ?? ((m) => process.stderr.write(`${m}\n`)))(`[intent-envelope] cannot write the ledger to ${path}: ${reason}. ` +
+                        'Enforcement continues; decisions are kept in memory only.');
+                }
+            }
+        },
+        entries: () => memory.entries(),
+    };
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAQzC,wFAAwF;AACxF,MAAM,UAAU,YAAY;IAC1B,MAAM,IAAI,GAAqB,EAAE,CAAC;IAClC,OAAO;QACL,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE;YACnB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,OAAmC;IAC1E,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,OAAO;QACL,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE;YACnB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACxB,IAAI,CAAC;gBACH,cAAc,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,GAAG,IAAI,CAAC;oBACd,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACtE,CAAC,OAAO,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAC1D,gDAAgD,IAAI,KAAK,MAAM,IAAI;wBACjE,2DAA2D,CAC9D,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE;KAChC,CAAC;AACJ,CAAC"}

package/dist/relay.d.ts

@@ -0,0 +1,67 @@
+/**
+ * An enforcement point that sits in the MCP wire protocol itself.
+ *
+ * The client launches this instead of the server it wants. Every tool call crosses this
+ * process, is decided against the envelope, and is forwarded only if the envelope
+ * permits it. A refused call is never written to the upstream server's stdin, which is
+ * the only property that matters: a decision made after the call has already run is a
+ * report, not an enforcement point.
+ *
+ * Why a line relay rather than the MCP SDK
+ * ----------------------------------------
+ * This understands exactly two methods, `tools/call` and `tools/list`, and relays
+ * every other line byte for byte. That is deliberate. The protocol has two eras in
+ * circulation, one using `server/discover` with inline `_meta` and one using the
+ * `initialize` handshake, and it keeps growing: `subscriptions/listen`,
+ * `notifications/cancelled`, `InputRequiredResult`. A proxy that modelled the whole
+ * protocol would need to track all of it and would break on the next addition. A relay
+ * that forwards what it does not recognise works across both eras and survives
+ * additions it has never heard of.
+ *
+ * It also means an unparseable line is passed along untouched rather than dropped. This
+ * process is not the arbiter of protocol validity; it is the arbiter of one question,
+ * which is whether a tool call is inside the envelope.
+ *
+ * stdout discipline
+ * -----------------
+ * The transport requires that nothing but valid MCP messages reach stdout. Every log,
+ * warning and summary this process emits goes to stderr, which the specification
+ * explicitly permits and tells clients not to treat as failure.
+ */
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type Envelope } from 'intent-envelope';
+import type { Ledger } from './ledger.ts';
+/** Implementation-defined JSON-RPC server error codes, per the JSON-RPC 2.0 spec. */
+export declare const DENIED = -32000;
+export declare const ESCALATION_REQUIRED = -32001;
+export interface RelayOptions {
+    envelope: Envelope;
+    ledger: Ledger;
+    upstream: ChildProcessWithoutNullStreams;
+    /** The client's side: what this process reads requests from and writes replies to. */
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+    log?: (message: string) => void;
+    /** Hide tools the envelope does not allow from tools/list. Defence in depth only. */
+    filterToolList?: boolean;
+}
+export declare class Relay {
+    private readonly point;
+    private readonly options;
+    private readonly allowed;
+    /** ids of tools/list requests in flight, so their replies can be filtered. */
+    private readonly listRequests;
+    private closed;
+    constructor(options: RelayOptions);
+    private log;
+    private send;
+    private toUpstream;
+    private refuse;
+    /** Returns true when the line was handled here and must not reach the upstream. */
+    private interceptFromClient;
+    /** Filter a tools/list reply down to what the envelope grants. */
+    private interceptFromUpstream;
+    start(): void;
+    summary(): Record<string, number>;
+}
+//# sourceMappingURL=relay.d.ts.map

package/dist/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAmC,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,qFAAqF;AACrF,eAAO,MAAM,MAAM,SAAS,CAAC;AAC7B,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAW1C,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,8BAA8B,CAAC;IACzC,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAyCD,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,YAAY;IAmBjC,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,MAAM;IAiBd,mFAAmF;IACnF,OAAO,CAAC,mBAAmB;IA4B3B,kEAAkE;IAClE,OAAO,CAAC,qBAAqB;IAgB7B,KAAK,IAAI,IAAI;IA+Bb,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAGlC"}