@emilia-protocol/gate 0.1.0 → 0.6.0

package/key-registry.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — issuer key registry (production key custody for the VERIFIER).
+ *
+ * A flat `trustedKeys: string[]` cannot express the two things a production
+ * deployment needs:
+ *   1. ROTATION — an issuer key is valid only for a window; a new key overlaps
+ *      the old one, then the old one retires, without rejecting receipts that
+ *      were legitimately issued while it was current.
+ *   2. REVOCATION — a COMPROMISED issuer key must be rejected immediately, for
+ *      every receipt, regardless of the issuance time the (now-untrusted) key
+ *      claims. Fail closed: once revoked, the key signs nothing the gate accepts.
+ *
+ * The registry resolves, for a given receipt issuance time, the set of public
+ * keys the gate should verify against — excluding revoked keys entirely and
+ * windowed keys whose [not_before, not_after] does not contain that time. The
+ * gate passes that resolved set to the receipt verifier, so an excluded key's
+ * signature simply does not verify and the action is refused.
+ *
+ * A key with no window and no revocation behaves exactly like a flat trustedKeys
+ * entry (back-compatible).
+ */
+
+function toMs(t) {
+  if (t == null) return null;
+  const ms = typeof t === 'number' ? t : Date.parse(t);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * @param {Array<object>} entries each: {
+ *   kid?: string, key: string (base64url SPKI-DER public key),
+ *   not_before?: string|number, not_after?: string|number, revoked_at?: string|number
+ * }
+ */
+export function createKeyRegistry(entries = []) {
+  const list = [];
+  function normalize(e) {
+    if (!e || !e.key || typeof e.key !== 'string') throw new Error('key registry entry requires a base64url SPKI key');
+    return {
+      kid: e.kid || e.key.slice(0, 16),
+      key: e.key,
+      not_before: toMs(e.not_before),
+      not_after: toMs(e.not_after),
+      revoked_at: toMs(e.revoked_at),
+    };
+  }
+  for (const e of entries) list.push(normalize(e));
+
+  /** Is this entry usable to verify a receipt issued at `atMs`? */
+  function entryActiveAt(entry, atMs) {
+    if (entry.revoked_at != null) return false; // HARD revocation: never trust a revoked key
+    if (entry.not_before != null && atMs != null && atMs < entry.not_before) return false;
+    if (entry.not_after != null && atMs != null && atMs > entry.not_after) return false;
+    // A windowed key with an unknown issuance time cannot be safely placed in
+    // its window — fail closed and exclude it. An unwindowed key still applies.
+    if ((entry.not_before != null || entry.not_after != null) && atMs == null) return false;
+    return true;
+  }
+
+  return {
+    /** The base64url public keys to verify a receipt issued at `at` (ISO or ms). */
+    keysValidAt(at) {
+      const atMs = toMs(at);
+      return list.filter((e) => entryActiveAt(e, atMs)).map((e) => e.key);
+    },
+    /** Mark a kid revoked as of `at` (default: now-as-supplied). Fail-closed thereafter. */
+    revoke(kid, at) {
+      let n = 0;
+      for (const e of list) {
+        if (e.kid === kid && e.revoked_at == null) { e.revoked_at = toMs(at) ?? 0; n += 1; }
+      }
+      if (n === 0) throw new Error(`key registry: no active key with kid "${kid}" to revoke`);
+      return n;
+    },
+    /** Add/rotate in a new key. */
+    add(entry) { list.push(normalize(entry)); return this; },
+    /** Operational snapshot (no private material; keys are public). */
+    status(at) {
+      const atMs = toMs(at);
+      return list.map((e) => ({
+        kid: e.kid,
+        revoked: e.revoked_at != null,
+        active: entryActiveAt(e, atMs),
+        not_before: e.not_before,
+        not_after: e.not_after,
+        revoked_at: e.revoked_at,
+      }));
+    },
+    get size() { return list.length; },
+  };
+}
+
+/** Coerce a flat trustedKeys[] OR a registry into a registry (back-compat). */
+export function asKeyRegistry(trustedKeysOrRegistry) {
+  if (trustedKeysOrRegistry && typeof trustedKeysOrRegistry.keysValidAt === 'function') {
+    return trustedKeysOrRegistry;
+  }
+  const keys = Array.isArray(trustedKeysOrRegistry) ? trustedKeysOrRegistry : [];
+  return createKeyRegistry(keys.map((key) => ({ key })));
+}
+
+export default { createKeyRegistry, asKeyRegistry };

package/mcp.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — MCP drop-in. The lowest-friction place to put the firewall:
+ * agents already live at the MCP tool-call boundary, and a single wrapper turns
+ * a dangerous MCP tool into a receipt-required one.
+ *
+ *   import { createTrustedActionFirewall } from '@emilia-protocol/gate';
+ *   import { gateMcpTool } from '@emilia-protocol/gate/mcp';
+ *   const gate = createTrustedActionFirewall({ trustedKeys: [ISSUER] });
+ *
+ *   server.tool('release_payment',
+ *     gateMcpTool(gate, { tool: 'release_payment' }, async (args) => actuallyPay(args)));
+ *
+ * A guarded call with no valid, sufficiently-assured, non-replayed receipt
+ * returns a structured MCP error (isError) carrying the Receipt-Required
+ * challenge, so the agent knows to go get a human/quorum to authorize THIS exact
+ * action. On success the tool runs and an execution proof + reliance packet are
+ * attached under `_emilia`.
+ *
+ * Receipt resolution order (override with opts.receipt): args._emilia_receipt,
+ * args.emilia_receipt, then a base64 string in args._emilia_receipt_b64.
+ */
+
+function resolveReceipt(args, opts) {
+  if (typeof opts.receipt === 'function') return opts.receipt(args);
+  if (opts.receipt) return opts.receipt;
+  if (args && typeof args === 'object') {
+    if (args._emilia_receipt) return args._emilia_receipt;
+    if (args.emilia_receipt) return args.emilia_receipt;
+    if (typeof args._emilia_receipt_b64 === 'string') {
+      try { return JSON.parse(Buffer.from(args._emilia_receipt_b64, 'base64').toString('utf8')); } catch { return null; }
+    }
+  }
+  return null;
+}
+
+/**
+ * Wrap a single MCP tool handler so it runs only behind a passing gate check.
+ * @param {object} gate     an EMILIA Gate (createGate/createTrustedActionFirewall)
+ * @param {object} o
+ * @param {string} o.tool   the MCP tool name (matched against the manifest)
+ * @param {string} [o.protocol='mcp']
+ * @param {string} [o.action] explicit action_type (else resolved by the manifest from {protocol,tool})
+ * @param {object|function} [o.observedAction] the system-of-record facts to bind (default: the tool args)
+ * @param {object|function} [o.receipt] override receipt resolution
+ * @param {function} handler the real tool implementation (args, extra) => result
+ * @returns {function} a gated MCP tool handler
+ */
+export function gateMcpTool(gate, o = {}, handler) {
+  if (!gate || typeof gate.run !== 'function') throw new Error('gateMcpTool requires an EMILIA Gate (with .run)');
+  if (typeof handler !== 'function') throw new Error('gateMcpTool requires a tool handler function');
+  const { tool, protocol = 'mcp', action } = o;
+  if (!tool) throw new Error('gateMcpTool requires { tool }');
+
+  return async function gatedTool(args = {}, extra) {
+    const selector = { protocol, tool, ...(action ? { action_type: action } : {}) };
+    const receipt = resolveReceipt(args, o);
+    const observedAction = typeof o.observedAction === 'function'
+      ? o.observedAction(args, extra)
+      : (o.observedAction ?? args);
+
+    const out = await gate.run({ selector, receipt, observedAction }, () => handler(args, extra));
+    if (!out.ok) {
+      return {
+        isError: true,
+        content: [{
+          type: 'text',
+          text: `EMILIA Gate refused "${tool}": ${out.authorization.reason}. `
+            + 'This is a high-risk action; present a valid, sufficiently-assured, unused human/quorum receipt.',
+        }],
+        _emilia: {
+          gate: 'refused',
+          status: out.status,
+          reason: out.authorization.reason,
+          challenge: out.body,
+        },
+      };
+    }
+    const result = out.result;
+    // Attach the proof without clobbering a structured tool result.
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+      return { ...result, _emilia: { gate: 'allowed', execution: out.execution, reliance: out.packet } };
+    }
+    return { result, _emilia: { gate: 'allowed', execution: out.execution, reliance: out.packet } };
+  };
+}
+
+/**
+ * Convenience: wrap a map of { toolName: handler } in one call. Tools not named
+ * in the manifest still pass through the gate (which lets non-guarded tools run).
+ */
+export function gateMcpTools(gate, handlers = {}, opts = {}) {
+  const wrapped = {};
+  for (const [tool, handler] of Object.entries(handlers)) {
+    wrapped[tool] = gateMcpTool(gate, { ...opts, tool }, handler);
+  }
+  return wrapped;
+}
+
+export default { gateMcpTool, gateMcpTools };

package/package.json

@@ -1,17 +1,32 @@
 {
   "name": "@emilia-protocol/gate",
-  "version": "0.1.0",
-  "description": "EMILIA Gate — the Trusted Action Firewall. Deny-by-default enforcement for consequential machine actions: an action runs only with a valid, in-scope, sufficiently-assured, non-replayed EMILIA authorization receipt (proof a named human authorized this exact action). Composes require-receipt + verify; adds assurance-tier enforcement, one-time consumption (replay defense), and a tamper-evident evidence log. Framework-agnostic, fails closed. Reference implementation, experimental.",
+  "version": "0.6.0",
+  "description": "EMILIA Gate — the Trusted Action Firewall. Deny-by-default enforcement for consequential machine actions: an action runs only with a valid, in-scope, sufficiently-assured, non-replayed EMILIA authorization receipt (proof a named human authorized this exact action). Composes require-receipt + verify; adds assurance-tier enforcement, one-time consumption (replay defense), a tamper-evident evidence log, default high-risk action packs, execution-field binding, reliance packets, an MCP drop-in, a GitHub system-of-record adapter, and EG-1 conformance. Framework-agnostic, fails closed. Reference implementation, experimental.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "index.js",
-  "files": ["index.js", "store.js", "evidence.js", "README.md"],
+  "exports": {
+    ".": "./index.js",
+    "./mcp": "./mcp.js",
+    "./adapters/github": "./adapters/github.js",
+    "./adapters/stripe": "./adapters/stripe.js",
+    "./adapters/supabase": "./adapters/supabase.js",
+    "./adapters/aws": "./adapters/aws.js",
+    "./adapters/k8s": "./adapters/k8s.js",
+    "./adapters/terraform": "./adapters/terraform.js",
+    "./adapters/gcp": "./adapters/gcp.js",
+    "./key-registry": "./key-registry.js",
+    "./retention": "./retention.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["index.js", "store.js", "evidence.js", "action-packs.js", "execution-binding.js", "reliance-packet.js", "key-registry.js", "retention.js", "eg1-conformance.js", "eg1.mjs", "mcp.js", "adapters/_kit.js", "adapters/github.js", "adapters/github-demo.mjs", "adapters/stripe.js", "adapters/supabase.js", "adapters/aws.js", "adapters/k8s.js", "adapters/terraform.js", "adapters/gcp.js", "demo.mjs", "custody-demo.mjs", "README.md"],
   "scripts": {
     "test": "node --test",
-    "demo": "node demo.mjs"
+    "demo": "node demo.mjs",
+    "eg1": "node eg1.mjs"
   },
   "dependencies": {
-    "@emilia-protocol/require-receipt": "^0.1.0"
+    "@emilia-protocol/require-receipt": "^0.4.1"
   },
   "keywords": ["emilia", "authorization", "receipt", "firewall", "trusted-action-firewall", "agent", "mcp", "gate", "policy-enforcement-point", "ai-safety"]
 }

package/reliance-packet.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// Auditor / insurer-facing reliance packet for an EMILIA Gate decision.
+
+export const RELIANCE_PACKET_VERSION = 'EP-GATE-RELIANCE-PACKET-v1';
+
+function evidenceStatus(evidence) {
+  if (!evidence) return { ok: null, length: null, head: null };
+  if (typeof evidence.verify === 'function') return evidence.verify();
+  return evidence;
+}
+
+function check(id, ok, detail = null) {
+  return { id, ok, ...(detail ? { detail } : {}) };
+}
+
+export function buildReliancePacket({
+  decision,
+  execution = null,
+  evidence = null,
+  manifest = null,
+  binding = null,
+  verifier = '@emilia-protocol/gate',
+} = {}) {
+  const evidenceCheck = evidenceStatus(evidence);
+  const decisionHash = decision?.evidence?.hash || decision?.hash || null;
+  const executionBound = !execution || (execution.kind === 'execution' && execution.authorizes_decision === decisionHash);
+  const bindingCheck = binding || decision?.evidence?.execution_binding || decision?.execution_binding || null;
+  const allowed = decision?.allow === true;
+  const evidenceOk = evidenceCheck.ok !== false;
+  const bindingOk = bindingCheck ? bindingCheck.ok === true : true;
+  const verdict = allowed && executionBound && evidenceOk && bindingOk ? 'rely' : 'do_not_rely';
+
+  return {
+    '@version': RELIANCE_PACKET_VERSION,
+    product: 'EMILIA Gate',
+    verifier,
+    verdict,
+    summary: {
+      action: decision?.action || null,
+      receipt_id: decision?.evidence?.receipt_id || decision?.receipt_id || null,
+      subject: decision?.evidence?.subject || null,
+      required_tier: decision?.evidence?.required_tier || decision?.required_tier || null,
+      observed_tier: decision?.evidence?.have_tier || decision?.have_tier || null,
+      decision_hash: decisionHash,
+      execution_hash: execution?.hash || null,
+      evidence_head: evidenceCheck.head || null,
+    },
+    checks: [
+      check('receipt_present_and_valid', allowed && !String(decision?.reason || '').startsWith('receipt_rejected'), decision?.reason || null),
+      check('assurance_sufficient', allowed || decision?.reason !== 'assurance_too_low', decision?.reason === 'assurance_too_low' ? 'receipt tier below action requirement' : null),
+      check('receipt_one_time_consumed', allowed || decision?.reason === 'replay_refused' ? decision?.reason !== 'replay_refused' : null),
+      check('execution_fields_bound', bindingCheck ? bindingCheck.ok === true : null, bindingCheck ? { missing_observed_fields: bindingCheck.missing_observed_fields || [], mismatched_fields: bindingCheck.mismatched_fields || [] } : 'no material execution-field binding required by this action'),
+      check('execution_attests_decision', execution ? executionBound : null, execution ? null : 'no execution record supplied'),
+      check('evidence_log_intact', evidenceCheck.ok === undefined ? null : evidenceCheck.ok, evidenceCheck.reason || null),
+    ],
+    manifest_version: manifest?.['@version'] || null,
+    limitations: [
+      'The packet proves the gate verified a receipt and enforced its configured policy; it does not prove the human made a wise decision.',
+      'Identity, authority enrollment, and key custody remain external trust roots that must be operated correctly.',
+      'For execution-field binding, observedAction must come from the system of record, not from attacker-controlled request input.',
+    ],
+  };
+}
+
+export default { RELIANCE_PACKET_VERSION, buildReliancePacket };

package/retention.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — evidence retention policy (production audit custody).
+ *
+ * The evidence log is the compliance/insurance artifact. Production custody adds
+ * a retention POLICY over it: classify each decision/execution record as HOT
+ * (recent, fast access), COLD (older, archival), or EXPIRED (past the retention
+ * horizon, eligible for deletion) — and honor a LEGAL HOLD that pins records so
+ * they are never expired. `EP_AUDIT_HOT_DAYS` / `EP_AUDIT_COLD_DAYS` set the
+ * horizons; legal hold is a set of evidence hashes.
+ *
+ * Pure functions over the evidence entries (each has `.at` ISO and `.hash`); the
+ * gate never deletes anything itself — it tells the operator what is eligible.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function ageDays(atISO, nowMs) {
+  const t = Date.parse(atISO);
+  if (!Number.isFinite(t)) return null;
+  return (nowMs - t) / DAY_MS;
+}
+
+/**
+ * Classify evidence entries into retention buckets.
+ * @param {Array<{at:string, hash?:string}>} entries  evidence.all()
+ * @param {object} o
+ * @param {number} [o.hotDays=365]
+ * @param {number} [o.coldDays=2190]   (6y)
+ * @param {number} [o.now=Date.now()]
+ * @param {Set<string>|string[]} [o.legalHold]  hashes pinned indefinitely
+ * @returns {{hot:object[], cold:object[], expired:object[], legal_hold:object[], unknown:object[], summary:object}}
+ */
+export function classifyRetention(entries = [], {
+  hotDays = 365, coldDays = 2190, now = Date.now(), legalHold,
+} = {}) {
+  const held = legalHold instanceof Set ? legalHold : new Set(legalHold || []);
+  const buckets = { hot: [], cold: [], expired: [], legal_hold: [], unknown: [] };
+  for (const e of entries) {
+    const tagged = { hash: e.hash ?? null, at: e.at ?? null, kind: e.kind ?? null };
+    if (e.hash && held.has(e.hash)) { buckets.legal_hold.push(tagged); continue; }
+    const age = ageDays(e.at, now);
+    if (age == null) { buckets.unknown.push(tagged); continue; }
+    if (age <= hotDays) buckets.hot.push(tagged);
+    else if (age <= coldDays) buckets.cold.push(tagged);
+    else buckets.expired.push(tagged);
+  }
+  return {
+    ...buckets,
+    summary: {
+      total: entries.length,
+      hot: buckets.hot.length,
+      cold: buckets.cold.length,
+      expired: buckets.expired.length,
+      legal_hold: buckets.legal_hold.length,
+      unknown: buckets.unknown.length,
+      hot_days: hotDays,
+      cold_days: coldDays,
+    },
+  };
+}
+
+/**
+ * Build an export manifest (the artifact handed to an auditor / SIEM). Includes
+ * the evidence head so the export is verifiably tied to a chain state.
+ */
+export function buildRetentionExport(entries = [], opts = {}) {
+  const cls = classifyRetention(entries, opts);
+  const last = entries[entries.length - 1] || null;
+  return {
+    '@version': 'EP-GATE-RETENTION-EXPORT-v1',
+    generated_at: new Date(opts.now || Date.now()).toISOString(),
+    hot_days: cls.summary.hot_days,
+    cold_days: cls.summary.cold_days,
+    evidence_head: last?.hash ?? null,
+    counts: {
+      total: cls.summary.total, hot: cls.summary.hot, cold: cls.summary.cold,
+      expired: cls.summary.expired, legal_hold: cls.summary.legal_hold, unknown: cls.summary.unknown,
+    },
+    entries: entries.map((e) => ({ hash: e.hash ?? null, at: e.at ?? null, kind: e.kind ?? null })),
+  };
+}
+
+export const RETENTION_EXPORT_VERSION = 'EP-GATE-RETENTION-EXPORT-v1';
+export default { classifyRetention, buildRetentionExport, RETENTION_EXPORT_VERSION };

package/store.js

@@ -10,17 +10,38 @@
 export class MemoryConsumptionStore {
   constructor() {
     this.seen = new Set();
+    this.reserved = new Set();
   }
 
   /** Returns true the FIRST time a key is seen, false on every replay. */
   async consume(key) {
-    if (this.seen.has(key)) return false;
+    if (this.seen.has(key) || this.reserved.has(key)) return false;
     this.seen.add(key);
     return true;
   }
 
+  /** Reserve an id while an action is in flight; blocks concurrent replay. */
+  async reserve(key) {
+    if (this.seen.has(key) || this.reserved.has(key)) return false;
+    this.reserved.add(key);
+    return true;
+  }
+
+  /** Commit a reserved id after the action succeeds. */
+  async commit(key) {
+    this.reserved.delete(key);
+    this.seen.add(key);
+    return true;
+  }
+
+  /** Release a reserved id after the action fails; approval stays retryable. */
+  async release(key) {
+    this.reserved.delete(key);
+    return true;
+  }
+
   async has(key) {
-    return this.seen.has(key);
+    return this.seen.has(key) || this.reserved.has(key);
   }
 
   get size() {
@@ -28,4 +49,55 @@ export class MemoryConsumptionStore {
   }
 }
 
-export default { MemoryConsumptionStore };
+/**
+ * Production custody for replay defense: a durable consumption store backed by
+ * any shared key-value backend (Redis, Postgres, DynamoDB, ...), so a receipt
+ * consumed on one pod/lambda cannot be replayed on another.
+ *
+ * The backend MUST provide an ATOMIC insert-if-absent — this is the single
+ * correctness primitive that makes replay defense sound under concurrency:
+ *
+ *   backend = {
+ *     async addIfAbsent(key, value): boolean  // true iff it inserted (Redis SET NX,
+ *                                             // Postgres INSERT .. ON CONFLICT DO NOTHING)
+ *     async set(key, value): void             // overwrite
+ *     async delete(key): void
+ *     async has(key): boolean
+ *   }
+ *
+ * State per receipt id is a single key: 'reserved' while in flight, 'committed'
+ * once the action succeeded. reserve() is the atomic gate; a second reserve()
+ * (concurrent replay) loses the race and is refused. Optional `ttlSeconds` is
+ * passed through to the backend so consumed ids can expire after the receipt's
+ * own max age (the gate already rejects stale receipts on freshness).
+ */
+export function createDurableConsumptionStore(backend, { ttlSeconds } = {}) {
+  for (const m of ['addIfAbsent', 'set', 'delete', 'has']) {
+    if (typeof backend?.[m] !== 'function') {
+      throw new Error(`createDurableConsumptionStore: backend must implement async ${m}(). `
+        + 'addIfAbsent MUST be atomic (e.g. Redis SET NX) or replay defense is not fleet-safe.');
+    }
+  }
+  const opt = ttlSeconds ? { ttlSeconds } : undefined;
+  return {
+    async reserve(key) { return (await backend.addIfAbsent(key, 'reserved', opt)) === true; },
+    async commit(key) { await backend.set(key, 'committed', opt); return true; },
+    async release(key) { await backend.delete(key); return true; },
+    async consume(key) { return (await backend.addIfAbsent(key, 'committed', opt)) === true; },
+    async has(key) { return (await backend.has(key)) === true; },
+  };
+}
+
+/** In-memory reference backend (for tests/single-process). addIfAbsent is atomic in a single thread. */
+export function createMemoryBackend() {
+  const map = new Map();
+  return {
+    async addIfAbsent(key, value) { if (map.has(key)) return false; map.set(key, value); return true; },
+    async set(key, value) { map.set(key, value); },
+    async delete(key) { map.delete(key); },
+    async has(key) { return map.has(key); },
+    get size() { return map.size; },
+  };
+}
+
+export default { MemoryConsumptionStore, createDurableConsumptionStore, createMemoryBackend };