intent-envelope-mcp 0.0.0 → 0.2.0

package/src/config.ts

@@ -1,89 +1,89 @@
-/**
- * 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, type Envelope } from 'intent-envelope';
-
-export interface Config {
-  envelope: Envelope;
-  envelopePath: string;
-  command: string;
-  args: string[];
-  ledgerPath?: string;
-  filterToolList: boolean;
-}
-
-export class ConfigError extends Error {
-  constructor(message: string) {
-    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: string[], env: Record<string, string | undefined> = {}): Config {
-  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: Envelope;
-  try {
-    envelope = JSON.parse(readFileSync(path, 'utf8')) as Envelope;
-  } 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 };
-}
+/**
+ * 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, type Envelope } from 'intent-envelope';
+
+export interface Config {
+  envelope: Envelope;
+  envelopePath: string;
+  command: string;
+  args: string[];
+  ledgerPath?: string;
+  filterToolList: boolean;
+}
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    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: string[], env: Record<string, string | undefined> = {}): Config {
+  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: Envelope;
+  try {
+    envelope = JSON.parse(readFileSync(path, 'utf8')) as Envelope;
+  } 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 };
+}

package/src/index.ts

@@ -1,12 +1,12 @@
-/**
- * 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 const VERSION = '0.2.0';
+/**
+ * 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 const VERSION = '0.2.0';

package/src/ledger.ts

@@ -1,61 +1,61 @@
-/**
- * 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';
-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 function memoryLedger(): Ledger {
-  const held: DecisionRecord[] = [];
-  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: string, onError?: (message: string) => void): Ledger {
-  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: string) => 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(),
-  };
-}
+/**
+ * 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';
+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 function memoryLedger(): Ledger {
+  const held: DecisionRecord[] = [];
+  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: string, onError?: (message: string) => void): Ledger {
+  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: string) => 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(),
+  };
+}