@permission-protocol/mcp-guard 0.1.0 → 0.2.0

package/dist/src/receipt.d.ts

@@ -1,15 +1,89 @@
 import type { Decision } from './engine.js';
-export interface Receipt {
+/**
+ * Receipt v2.
+ *
+ * A receipt is a small signed ENVELOPE — the fields a verifier decides on — plus an
+ * unsigned DISPLAY block generated from it for humans. The signature covers
+ * `SIGNING_DOMAIN + canonical JSON(envelope)`, so every authority-relevant field is
+ * bound and no field boundary can be re-interpreted. Verifiers never read `display`.
+ *
+ * Receipts never carry raw tool arguments: only their sha256 (`args_sha256`) and the
+ * argument names. Raw arguments are shown only in the authenticated approval queue.
+ */
+export declare const RECEIPT_VERSION = 2;
+export declare const SIGNING_DOMAIN = "pp-mcp-guard-receipt-v2\n";
+export type ApprovalKind = 'human' | 'policy';
+/** Who or what authorized the action. `via` names the channel or mechanism. */
+export interface Approval {
+    kind: ApprovalKind;
+    id: string;
+    via: string;
+}
+/** Scope binding for code/infra actions, as derived from a request. */
+export interface ScopeBinding {
+    scope?: string;
+    scope_ref?: string;
+    scope_sha?: string;
+}
+export interface ReceiptScope {
+    scope: string;
+    ref: string | null;
+    sha: string | null;
+}
+export interface ReceiptEnvelope {
+    v: 2;
     receipt_id: string;
-    timestamp: string;
-    agent_id: string;
-    tool_name: string;
+    method: string;
+    tool: string | null;
+    args_sha256: string;
+    scope: ReceiptScope | null;
     decision: Decision['decision'];
-    reason: string;
+    approval: Approval | null;
+    actor: string;
     rule_id: string | null;
-    request_payload_hash: string;
+    policy_sha256: string;
+    mode: 'enforce' | 'observe';
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+    key_id: string;
+}
+export interface ReceiptDisplay {
+    summary: string;
+    reason: string;
+    risk_tier: 'low' | 'medium' | 'high' | 'critical';
     target_server: string;
+    arg_keys: string[];
+    viewer_url: string;
+}
+export interface Receipt {
+    envelope: ReceiptEnvelope;
+    signature: {
+        alg: 'ed25519';
+        key_id: string;
+        value: string;
+    };
+    display: ReceiptDisplay;
+}
+export interface ReceiptInput {
+    method: string;
+    tool: string | null;
+    args: Record<string, unknown> | undefined;
+    decision: Decision;
+    approval: Approval | null;
+    actor: string;
     mode: 'enforce' | 'observe';
+    policy_sha256: string;
+    ttl_seconds: number;
+    target_server: string;
+    scope?: ScopeBinding;
+    now?: Date;
 }
-export declare function createReceipt(agentId: string, toolName: string, decision: Decision, requestPayload: unknown, targetServer?: string, mode?: 'enforce' | 'observe'): Receipt;
+export declare function signingBytes(envelope: ReceiptEnvelope): string;
+/** sha256 of the canonical JSON of the arguments the server receives. */
+export declare function hashArgs(args: Record<string, unknown> | undefined): string;
+/** Build and sign a receipt. */
+export declare function issueReceipt(input: ReceiptInput): Receipt;
+export declare function defaultReceiptsPath(): string;
+/** Log, persist and (optionally) publish a receipt. Receipts never hold raw arguments. */
 export declare function emitReceipt(receipt: Receipt, receiptsPath?: string): void;

package/dist/src/receipt.js

@@ -1,34 +1,117 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createReceipt = createReceipt;
+exports.SIGNING_DOMAIN = exports.RECEIPT_VERSION = void 0;
+exports.signingBytes = signingBytes;
+exports.hashArgs = hashArgs;
+exports.issueReceipt = issueReceipt;
+exports.defaultReceiptsPath = defaultReceiptsPath;
 exports.emitReceipt = emitReceipt;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
-const uuid_1 = require("uuid");
-function createReceipt(agentId, toolName, decision, requestPayload, targetServer = 'unknown', mode = 'enforce') {
-    const payloadStr = JSON.stringify(requestPayload ?? {});
-    const hash = (0, node_crypto_1.createHash)('sha256').update(payloadStr).digest('hex');
+const fast_json_stable_stringify_1 = __importDefault(require("fast-json-stable-stringify"));
+const signer_js_1 = require("./signer.js");
+/**
+ * Receipt v2.
+ *
+ * A receipt is a small signed ENVELOPE — the fields a verifier decides on — plus an
+ * unsigned DISPLAY block generated from it for humans. The signature covers
+ * `SIGNING_DOMAIN + canonical JSON(envelope)`, so every authority-relevant field is
+ * bound and no field boundary can be re-interpreted. Verifiers never read `display`.
+ *
+ * Receipts never carry raw tool arguments: only their sha256 (`args_sha256`) and the
+ * argument names. Raw arguments are shown only in the authenticated approval queue.
+ */
+exports.RECEIPT_VERSION = 2;
+exports.SIGNING_DOMAIN = 'pp-mcp-guard-receipt-v2\n';
+function signingBytes(envelope) {
+    return exports.SIGNING_DOMAIN + (0, fast_json_stable_stringify_1.default)(envelope);
+}
+/** sha256 of the canonical JSON of the arguments the server receives. */
+function hashArgs(args) {
+    return (0, node_crypto_1.createHash)('sha256').update((0, fast_json_stable_stringify_1.default)(args ?? {})).digest('hex');
+}
+function toScope(binding) {
+    if (!binding?.scope)
+        return null;
+    return { scope: binding.scope, ref: binding.scope_ref ?? null, sha: binding.scope_sha ?? null };
+}
+function classifyRisk(tool, argKeys) {
+    const text = `${tool} ${argKeys.join(' ')}`.toLowerCase();
+    if (/(delete|destroy|drop|truncate|wipe|remove)/.test(text))
+        return 'critical';
+    if (/(prod|deploy|release|publish|billing|payment|spend|merge|migrat|auth|admin|secret|token|password|key)/.test(text))
+        return 'high';
+    if (/(write|update|create|patch|modify|sync|email|post|notify)/.test(text))
+        return 'medium';
+    return 'low';
+}
+/** Build and sign a receipt. */
+function issueReceipt(input) {
+    const now = input.now ?? new Date();
+    const receiptId = `rcpt_mg_${now.getTime().toString(36)}_${(0, node_crypto_1.randomBytes)(6).toString('hex')}`;
+    const argKeys = Object.keys(input.args ?? {}).sort();
+    const label = input.tool ?? input.method;
+    const unsigned = {
+        v: exports.RECEIPT_VERSION,
+        receipt_id: receiptId,
+        method: input.method,
+        tool: input.tool,
+        args_sha256: hashArgs(input.args),
+        scope: toScope(input.scope),
+        decision: input.decision.decision,
+        approval: input.approval,
+        actor: input.actor,
+        rule_id: input.decision.rule_id,
+        policy_sha256: input.policy_sha256,
+        mode: input.mode,
+        issued_at: now.toISOString(),
+        expires_at: new Date(now.getTime() + input.ttl_seconds * 1000).toISOString(),
+        nonce: (0, node_crypto_1.randomBytes)(16).toString('hex'),
+    };
+    // The key id is part of the signed envelope, so resolve it before signing.
+    const envelope = { ...unsigned, key_id: (0, signer_js_1.currentKeyId)() };
+    const sig = (0, signer_js_1.signBytes)(signingBytes(envelope));
+    const viewerBase = (process.env.PP_VIEWER_BASE_URL || 'https://app.permissionprotocol.com/r').replace(/\/$/, '');
+    const by = input.approval ? ` by ${input.approval.kind} ${input.approval.id}` : '';
     return {
-        receipt_id: (0, uuid_1.v4)(),
-        timestamp: new Date().toISOString(),
-        agent_id: agentId,
-        tool_name: toolName,
-        decision: decision.decision,
-        reason: decision.reason,
-        rule_id: decision.rule_id,
-        request_payload_hash: hash,
-        target_server: targetServer,
-        mode,
+        envelope,
+        signature: { alg: signer_js_1.SIGN_ALGORITHM, key_id: sig.keyId, value: sig.value },
+        display: {
+            summary: `MCP Guard ${input.decision.decision.replace(/_/g, ' ')} "${label}"${by}`,
+            reason: input.decision.reason,
+            risk_tier: classifyRisk(label, argKeys),
+            target_server: input.target_server,
+            arg_keys: argKeys,
+            viewer_url: `${viewerBase}/${receiptId}`,
+        },
     };
 }
-function emitReceipt(receipt, receiptsPath = 'pp-receipts.jsonl') {
+function defaultReceiptsPath() {
+    return process.env.PP_SHARED_RECEIPTS_PATH || 'pp-receipts.jsonl';
+}
+/** Log, persist and (optionally) publish a receipt. Receipts never hold raw arguments. */
+function emitReceipt(receipt, receiptsPath = defaultReceiptsPath()) {
+    const e = receipt.envelope;
     const json = JSON.stringify(receipt);
-    process.stderr.write(`[mcp-guard] receipt: ${json}\n`);
+    process.stderr.write(`[mcp-guard] receipt ${e.receipt_id} ${e.decision} "${e.tool ?? e.method}"${e.approval ? ` (${e.approval.kind}:${e.approval.id})` : ''}\n`);
     try {
         (0, node_fs_1.appendFileSync)(receiptsPath, json + '\n');
     }
     catch {
         // Best effort — don't crash the proxy if file write fails
     }
+    const endpoint = process.env.PP_RECEIPT_ENDPOINT;
+    if (!endpoint)
+        return;
+    const headers = { 'Content-Type': 'application/json' };
+    if (process.env.PP_RECEIPT_TOKEN)
+        headers.Authorization = `Bearer ${process.env.PP_RECEIPT_TOKEN}`;
+    void fetch(endpoint, { method: 'POST', headers, body: json }).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[mcp-guard] receipt publish failed: ${message}\n`);
+    });
 }
 //# sourceMappingURL=receipt.js.map

package/dist/src/receipt.js.map

@@ -1 +1 @@
-{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../../src/receipt.ts"],"names":[],"mappings":";;AAkBA,sCAuBC;AAED,kCAQC;AAnDD,6CAAyC;AACzC,qCAAyC;AACzC,+BAAoC;AAgBpC,SAAgB,aAAa,CAC3B,OAAe,EACf,QAAgB,EAChB,QAAkB,EAClB,cAAuB,EACvB,eAAuB,SAAS,EAChC,OAA8B,SAAS;IAEvC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEnE,OAAO;QACL,UAAU,EAAE,IAAA,SAAM,GAAE;QACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,QAAQ,EAAE,OAAO;QACjB,SAAS,EAAE,QAAQ;QACnB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,oBAAoB,EAAE,IAAI;QAC1B,aAAa,EAAE,YAAY;QAC3B,IAAI;KACL,CAAC;AACJ,CAAC;AAED,SAAgB,WAAW,CAAC,OAAgB,EAAE,eAAuB,mBAAmB;IACtF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,IAAI,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,IAAA,wBAAc,EAAC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;AACH,CAAC"}
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../../src/receipt.ts"],"names":[],"mappings":"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"}

package/dist/src/signer.d.ts

@@ -0,0 +1,38 @@
+import { type KeyObject } from 'node:crypto';
+/**
+ * Local Ed25519 dev signer.
+ *
+ * The keypair is generated once and kept in the operator's config directory
+ * (`$PP_KEYS_DIR`, else `$XDG_CONFIG_HOME/mcp-guard/keys`, else
+ * `~/.config/mcp-guard/keys`) — never in the working directory, which is usually the
+ * agent's workspace. The directory is 0700 and the private key 0600; a key with looser
+ * permissions is refused rather than used.
+ *
+ * The key id is derived from the public key (`pp-dev-<fingerprint>`), so pinning a
+ * public key pins its id and a regenerated key can never pass as the old one.
+ *
+ * This is the dev signer of the open-core boundary; the managed PP signer replaces it.
+ */
+export declare const SIGN_ALGORITHM = "ed25519";
+export declare class KeyPermissionError extends Error {
+    readonly code = "PP_KEY_PERMISSIONS";
+}
+export declare function keysDir(): string;
+/** `pp-dev-` + the first 16 hex chars of sha256(SPKI DER). */
+export declare function keyIdForPublicKey(publicKey: KeyObject | string): string;
+/** The active signing key id. */
+export declare function currentKeyId(): string;
+/** The active public key in SPKI PEM form — what verifiers pin. */
+export declare function getPublicKeyPem(): string;
+/** Sign bytes with the dev key. Returns the hex signature and the key id it belongs to. */
+export declare function signBytes(data: string | Buffer): {
+    keyId: string;
+    value: string;
+};
+/**
+ * Write the public key to `path` (0644) so it can be committed or distributed as the
+ * pinned trust anchor. Never writes the private key.
+ */
+export declare function exportPublicKey(path: string): string;
+/** Test/teardown helper: forget the cached keypair. */
+export declare function _resetSigner(): void;

package/dist/src/signer.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyPermissionError = exports.SIGN_ALGORITHM = void 0;
+exports.keysDir = keysDir;
+exports.keyIdForPublicKey = keyIdForPublicKey;
+exports.currentKeyId = currentKeyId;
+exports.getPublicKeyPem = getPublicKeyPem;
+exports.signBytes = signBytes;
+exports.exportPublicKey = exportPublicKey;
+exports._resetSigner = _resetSigner;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Local Ed25519 dev signer.
+ *
+ * The keypair is generated once and kept in the operator's config directory
+ * (`$PP_KEYS_DIR`, else `$XDG_CONFIG_HOME/mcp-guard/keys`, else
+ * `~/.config/mcp-guard/keys`) — never in the working directory, which is usually the
+ * agent's workspace. The directory is 0700 and the private key 0600; a key with looser
+ * permissions is refused rather than used.
+ *
+ * The key id is derived from the public key (`pp-dev-<fingerprint>`), so pinning a
+ * public key pins its id and a regenerated key can never pass as the old one.
+ *
+ * This is the dev signer of the open-core boundary; the managed PP signer replaces it.
+ */
+exports.SIGN_ALGORITHM = 'ed25519';
+const PRIVATE_FILE = 'signing.private.pem';
+const PUBLIC_FILE = 'signing.public.pem';
+class KeyPermissionError extends Error {
+    code = 'PP_KEY_PERMISSIONS';
+}
+exports.KeyPermissionError = KeyPermissionError;
+function keysDir() {
+    if (process.env.PP_KEYS_DIR)
+        return process.env.PP_KEYS_DIR;
+    const base = process.env.XDG_CONFIG_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), '.config');
+    return (0, node_path_1.join)(base, 'mcp-guard', 'keys');
+}
+/** `pp-dev-` + the first 16 hex chars of sha256(SPKI DER). */
+function keyIdForPublicKey(publicKey) {
+    const key = typeof publicKey === 'string' ? (0, node_crypto_1.createPublicKey)(publicKey) : publicKey;
+    const der = key.export({ type: 'spki', format: 'der' });
+    return 'pp-dev-' + (0, node_crypto_1.createHash)('sha256').update(der).digest('hex').slice(0, 16);
+}
+let cached = null;
+function assertPrivate(path, mask) {
+    if (process.platform === 'win32')
+        return;
+    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
+    if (mode & mask) {
+        throw new KeyPermissionError(`Refusing to use signing key material at ${path}: mode ${mode.toString(8)} is readable or writable by others (key must be 0600 in a directory only you can write)`);
+    }
+}
+function ensureKeypair() {
+    const dir = keysDir();
+    if (cached && cached.dir === dir)
+        return cached;
+    const privPath = (0, node_path_1.join)(dir, PRIVATE_FILE);
+    const pubPath = (0, node_path_1.join)(dir, PUBLIC_FILE);
+    let privateKey;
+    let publicKey;
+    if ((0, node_fs_1.existsSync)(privPath)) {
+        assertPrivate(dir, 0o022);
+        assertPrivate(privPath, 0o077);
+        privateKey = (0, node_crypto_1.createPrivateKey)((0, node_fs_1.readFileSync)(privPath, 'utf-8'));
+        publicKey = (0, node_crypto_1.createPublicKey)(privateKey);
+    }
+    else {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+        try {
+            (0, node_fs_1.chmodSync)(dir, 0o700);
+        }
+        catch { /* best effort on platforms without chmod */ }
+        const pair = (0, node_crypto_1.generateKeyPairSync)('ed25519');
+        privateKey = pair.privateKey;
+        publicKey = pair.publicKey;
+        (0, node_fs_1.writeFileSync)(privPath, privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(), { mode: 0o600, flag: 'wx' });
+        (0, node_fs_1.writeFileSync)(pubPath, publicKey.export({ type: 'spki', format: 'pem' }).toString(), { mode: 0o644 });
+    }
+    cached = { dir, privateKey, publicKey, keyId: keyIdForPublicKey(publicKey) };
+    return cached;
+}
+/** The active signing key id. */
+function currentKeyId() {
+    return ensureKeypair().keyId;
+}
+/** The active public key in SPKI PEM form — what verifiers pin. */
+function getPublicKeyPem() {
+    return ensureKeypair().publicKey.export({ type: 'spki', format: 'pem' }).toString();
+}
+/** Sign bytes with the dev key. Returns the hex signature and the key id it belongs to. */
+function signBytes(data) {
+    const { privateKey, keyId } = ensureKeypair();
+    const buf = typeof data === 'string' ? Buffer.from(data) : data;
+    return { keyId, value: (0, node_crypto_1.sign)(null, buf, privateKey).toString('hex') };
+}
+/**
+ * Write the public key to `path` (0644) so it can be committed or distributed as the
+ * pinned trust anchor. Never writes the private key.
+ */
+function exportPublicKey(path) {
+    (0, node_fs_1.writeFileSync)(path, getPublicKeyPem(), { mode: 0o644 });
+    return path;
+}
+/** Test/teardown helper: forget the cached keypair. */
+function _resetSigner() {
+    cached = null;
+}
+//# sourceMappingURL=signer.js.map

package/dist/src/signer.js.map

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

package/dist/src/verify-cli.d.ts

@@ -0,0 +1 @@
+export declare function runVerify(argv: string[]): number;

package/dist/src/verify-cli.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runVerify = runVerify;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const receipt_verify_js_1 = require("./receipt-verify.js");
+const signer_js_1 = require("./signer.js");
+/**
+ * `mcp-guard verify` — the OFFLINE receipt gate a CI step runs.
+ *
+ *   mcp-guard verify --receipt-file receipt.json --pubkey pinned.pub.pem \
+ *     --scope deploy:production --scope-sha <sha>
+ *
+ * The public key must be supplied (`--pubkey`, repeatable): the gate trusts only keys it
+ * is given and never generates or discovers one. Exit 0 = authorized, 1 = refused,
+ * 2 = missing input. "No receipt = No deploy. This is intentional."
+ */
+const USAGE = 'usage: mcp-guard verify (--receipt-file <path> | --receipt-id <id> [--receipts-path <jsonl>]) --pubkey <pem> [--pubkey <pem> ...] --scope s [--scope-ref r] [--scope-sha h] [--allow-policy-approval]';
+function ciError(message) {
+    console.log(`::error::${message.replace(/\n/g, '%0A')}`);
+    console.error(message);
+}
+function parseArgs(argv) {
+    const flags = {};
+    const pubkeys = [];
+    const bools = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const key = a.slice(2);
+        if (key === 'allow-policy-approval' || key === 'help') {
+            bools.add(key);
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            flags[key] = '';
+            continue;
+        }
+        if (key === 'pubkey')
+            pubkeys.push(next);
+        else
+            flags[key] = next;
+        i++;
+    }
+    return { flags, pubkeys, bools };
+}
+function loadReceiptById(id, path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return `receipt store not found at ${path}`;
+    let found = null;
+    for (const line of (0, node_fs_1.readFileSync)(path, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (r?.envelope?.receipt_id === id)
+                found = r;
+        }
+        catch { /* skip malformed line */ }
+    }
+    return found ?? `no receipt with id "${id}" in ${path}`;
+}
+function runVerify(argv) {
+    const { flags, pubkeys, bools } = parseArgs(argv);
+    const fail = (msg) => { ciError(`No receipt = No deploy. This is intentional. (${msg})`); return 2; };
+    if (bools.has('help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    let receipt;
+    if (flags['receipt-file']) {
+        const p = (0, node_path_1.resolve)(flags['receipt-file']);
+        if (!(0, node_fs_1.existsSync)(p))
+            return fail(`receipt file not found: ${p}`);
+        try {
+            receipt = JSON.parse((0, node_fs_1.readFileSync)(p, 'utf-8'));
+        }
+        catch (e) {
+            return fail(`receipt file is not valid JSON: ${e.message}`);
+        }
+    }
+    else if (flags['receipt-id']) {
+        const r = loadReceiptById(flags['receipt-id'], (0, node_path_1.resolve)(flags['receipts-path'] || process.env.PP_SHARED_RECEIPTS_PATH || 'pp-receipts.jsonl'));
+        if (typeof r === 'string')
+            return fail(r);
+        receipt = r;
+    }
+    else {
+        return fail(USAGE);
+    }
+    if (pubkeys.length === 0)
+        return fail('--pubkey is required: the gate verifies only against keys you pin');
+    const keys = {};
+    for (const k of pubkeys) {
+        const p = (0, node_path_1.resolve)(k);
+        if (!(0, node_fs_1.existsSync)(p))
+            return fail(`public key not found: ${p}`);
+        try {
+            const pem = (0, node_fs_1.readFileSync)(p, 'utf-8');
+            keys[(0, signer_js_1.keyIdForPublicKey)(pem)] = pem;
+        }
+        catch (e) {
+            return fail(`public key ${p} is not a valid PEM: ${e.message}`);
+        }
+    }
+    for (const f of ['scope', 'scope-ref', 'scope-sha']) {
+        if (f in flags && !flags[f])
+            return fail(`--${f} needs a value`);
+    }
+    if (!flags.scope)
+        return fail('--scope is required: a gate must say which action it authorizes');
+    const expected = { scope: flags.scope };
+    if (flags['scope-ref'])
+        expected.scope_ref = flags['scope-ref'];
+    if (flags['scope-sha'])
+        expected.scope_sha = flags['scope-sha'];
+    const hasExpected = true;
+    const result = (0, receipt_verify_js_1.verifyReceipt)(receipt, keys, {
+        ...(hasExpected ? { expected } : {}),
+        allowPolicyApproval: bools.has('allow-policy-approval'),
+    });
+    const id = receipt?.envelope?.receipt_id ?? '(unknown)';
+    if (result.valid) {
+        const scope = hasExpected ? ` for ${[expected.scope, expected.scope_ref, expected.scope_sha && `@ ${expected.scope_sha}`].filter(Boolean).join(' ')}` : '';
+        console.log(`Receipt ${id} VERIFIED${scope}. Gate green.`);
+        return 0;
+    }
+    ciError(`No receipt = No deploy. This is intentional. Receipt ${id} REFUSED:\n  - ${result.reasons.join('\n  - ')}`);
+    return 1;
+}
+//# sourceMappingURL=verify-cli.js.map

package/dist/src/verify-cli.js.map

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

package/dist/src/verify-core.d.ts

@@ -0,0 +1,22 @@
+import { type KeyObject } from 'node:crypto';
+/**
+ * The cryptographic core every verifier in mcp-guard uses: Ed25519 detached-signature
+ * checks against PINNED keys, and single-use tracking. Receipt v2 verification and the
+ * enforcement module's authorization tokens both build on these two primitives.
+ */
+/** key_id → public key (PEM or KeyObject). Only keys in this map are trusted. */
+export type PinnedKeys = Record<string, string | KeyObject>;
+/**
+ * Verify `signatureHex` over `bytes` with the pinned key for `keyId`.
+ * Returns a reason string on failure, or null when the signature verifies.
+ */
+export declare function verifyDetached(bytes: string, signatureHex: unknown, keyId: unknown, keys: PinnedKeys): string | null;
+/** Remembers used nonces so an authorization is honored at most once per process. */
+export declare class ReplayCache {
+    private readonly max;
+    private readonly seen;
+    constructor(max?: number);
+    /** Record `key`; returns false when it was already used. */
+    use(key: string): boolean;
+    has(key: string): boolean;
+}

package/dist/src/verify-core.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplayCache = void 0;
+exports.verifyDetached = verifyDetached;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Verify `signatureHex` over `bytes` with the pinned key for `keyId`.
+ * Returns a reason string on failure, or null when the signature verifies.
+ */
+function verifyDetached(bytes, signatureHex, keyId, keys) {
+    if (typeof keyId !== 'string' || !Object.prototype.hasOwnProperty.call(keys, keyId)) {
+        return `untrusted key_id "${String(keyId)}"`;
+    }
+    if (typeof signatureHex !== 'string' || !/^[0-9a-f]+$/i.test(signatureHex) || signatureHex.length % 2 !== 0) {
+        return 'signature is not hex';
+    }
+    try {
+        const key = keys[keyId];
+        const ok = (0, node_crypto_1.verify)(null, Buffer.from(bytes), typeof key === 'string' ? (0, node_crypto_1.createPublicKey)(key) : key, Buffer.from(signatureHex, 'hex'));
+        return ok ? null : 'signature does not verify against the pinned key';
+    }
+    catch (err) {
+        return `signature verification threw (${err instanceof Error ? err.message : String(err)})`;
+    }
+}
+/** Remembers used nonces so an authorization is honored at most once per process. */
+class ReplayCache {
+    max;
+    seen = new Set();
+    constructor(max = 10_000) {
+        this.max = max;
+    }
+    /** Record `key`; returns false when it was already used. */
+    use(key) {
+        if (this.seen.has(key))
+            return false;
+        this.seen.add(key);
+        if (this.seen.size > this.max) {
+            const oldest = this.seen.values().next().value;
+            if (oldest !== undefined)
+                this.seen.delete(oldest);
+        }
+        return true;
+    }
+    has(key) {
+        return this.seen.has(key);
+    }
+}
+exports.ReplayCache = ReplayCache;
+//# sourceMappingURL=verify-core.js.map

package/dist/src/verify-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-core.js","sourceRoot":"","sources":["../../src/verify-core.ts"],"names":[],"mappings":";;;AAeA,wCAcC;AA7BD,6CAAkF;AAWlF;;;GAGG;AACH,SAAgB,cAAc,CAAC,KAAa,EAAE,YAAqB,EAAE,KAAc,EAAE,IAAgB;IACnG,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;QACpF,OAAO,qBAAqB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5G,OAAO,sBAAsB,CAAC;IAChC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,MAAM,EAAE,GAAG,IAAA,oBAAQ,EAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAA,6BAAe,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC;QACtI,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,kDAAkD,CAAC;IACxE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,iCAAiC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;IAC9F,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAa,WAAW;IAEO;IADZ,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,YAA6B,MAAM,MAAM;QAAZ,QAAG,GAAH,GAAG,CAAS;IAAG,CAAC;IAE7C,4DAA4D;IAC5D,GAAG,CAAC,GAAW;QACb,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC/C,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;CACF;AAlBD,kCAkBC"}