@emilia-protocol/gate 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @emilia-protocol/gate — EMILIA Gate
+
+**The Trusted Action Firewall.** Deny-by-default enforcement for consequential machine actions.
+
+> If an agent cannot produce a valid receipt, it cannot change money, code, permissions, data,
+> infrastructure, energy, or physical state.
+
+A guarded action runs **only** if it arrives with a receipt that is **valid** (Ed25519 over
+canonical JSON, signed by a pinned issuer), **in-scope** (bound to the exact action), **sufficiently
+assured** (meets the action's required tier), **fresh**, and **unused** (not a replay). Otherwise it
+is refused with a machine-readable `Receipt-Required` challenge (HTTP 428). Every decision — allow or
+deny — is appended to a tamper-evident evidence log.
+
+This is **not** authentication ("who are you") or permissions ("are you allowed here"). It is a
+**policy-enforcement point** that requires portable proof a named human authorized *this exact
+action* before the world is mutated.
+
+## Run it
+
+```bash
+node --test        # 10 tests
+node demo.mjs       # end-to-end: passthrough -> 428 -> too-low -> allow -> replay -> tamper
+```
+
+## Use it
+
+```js
+import { createGate } from '@emilia-protocol/gate';
+
+const gate = createGate({
+  manifest,             // EP-ACTION-RISK-MANIFEST-v0.1: which actions are guarded + their tier
+  trustedKeys: [ISSUER_PUBKEY_B64U],   // pin the issuers you trust
+  maxAgeSec: 900,
+});
+
+// 1) Framework-agnostic check
+const out = await gate.check({ selector: { protocol: 'mcp', tool: 'release_payment' }, receipt });
+if (!out.allow) throw out.challenge;   // 428 Receipt-Required
+
+// 2) Express / Connect middleware
+app.post('/payments', gate.middleware({ action: 'payment.release' }), handler);
+
+// 3) Wrap any function
+const release = gate.guard(reallyRelease, { selector: () => ({ tool: 'release_payment', protocol: 'mcp' }), receipt: (args, r) => r });
+```
+
+## What it adds over a bare verifier
+
+`@emilia-protocol/require-receipt` already does manifest matching, offline verification, and the 428
+challenge. The Gate composes that and adds the three things a firewall needs:
+
+- **Assurance tiers** — `software` < `class_a` (device signoff) < `quorum` (m-of-n). A `critical`
+  action can demand `class_a` or `quorum`; a lower-assurance receipt is refused (`assurance_too_low`).
+- **One-time consumption** — a receipt authorizes one action, once. Replays are refused
+  (`replay_refused`). Default store is in-memory; swap in Redis/DB for a fleet.
+- **Evidence log** — every decision is hash-chained (`evidence.verify()` detects any alteration).
+  This is the compliance / insurance artifact.
+
+## Boundary
+
+EMILIA Gate does not stop every bad actor. It makes **legitimate infrastructure refuse unreceipted
+consequential actions by default**, so the parties with leverage (clouds, payment rails, regulators,
+insurers) can *require* a receipt — and "no receipt" becomes like "no TLS cert" or "unsigned binary":
+not always illegal, just untrusted. Necessary, not sufficient.
+
+## Standards
+
+The mechanism is specified in `draft-schrock-ep-enforcement-point` (the Receipt-Required rail) over
+`draft-schrock-ep-authorization-receipts`. Earn the **RR-1** conformance level via
+`receiptRequiredConformance()` in `@emilia-protocol/require-receipt`. Reference implementation;
+experimental. Apache-2.0. Fails closed.

package/evidence.js

@@ -0,0 +1,84 @@
+/**
+ * @emilia-protocol/gate — evidence log (tamper-evident audit of decisions).
+ * @license Apache-2.0
+ *
+ * Every gate decision — allow or deny — appends a hash-chained record. Each
+ * record commits to the previous one, so removing or altering any decision
+ * breaks the chain and `verify()` catches it. This is the compliance and
+ * insurance artifact: a provable account of exactly which consequential actions
+ * were authorized, refused, and why. Default sink is in-memory; pass `sink` to
+ * stream records to durable/append-only storage.
+ *
+ * Hashing is over CANONICAL JSON (sorted keys) so the same logical record hashes
+ * identically across systems and languages — a plain JSON.stringify is
+ * insertion-order dependent and would make cross-system verification fragile.
+ *
+ * `strict` mode makes the log fail CLOSED: if a durable `sink` write fails, the
+ * record is NOT appended and `record()` throws. The gate uses this so it never
+ * authorizes an action it cannot durably account for. In non-strict (observe)
+ * mode a sink failure is best-effort and swallowed.
+ */
+import crypto from 'node:crypto';
+
+function sha256hex(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+/** Canonical JSON (recursive sorted keys) — matches @emilia-protocol/verify. */
+function canonical(v) {
+  if (v === null || v === undefined) return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  if (typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canonical(v[k])).join(',')}}`;
+  }
+  return JSON.stringify(v);
+}
+
+export function createEvidenceLog({ sink, strict = false } = {}) {
+  const records = [];
+  let prev = 'genesis';
+
+  return {
+    async record(entry) {
+      const body = { seq: records.length, prev_hash: prev, ...entry };
+      const hash = sha256hex(canonical(body));
+      const rec = { ...body, hash };
+      if (sink) {
+        try {
+          await sink(rec);
+        } catch (e) {
+          // Fail closed in strict mode: do NOT advance the chain, surface the
+          // failure so the caller (the gate) can refuse the action. The seq is
+          // left unconsumed so a retry produces a consistent chain.
+          if (strict) {
+            const err = new Error('evidence_sink_failed');
+            err.cause = e;
+            throw err;
+          }
+          /* non-strict (observe): best-effort, swallow — never break the gate */
+        }
+      }
+      records.push(rec);
+      prev = hash;
+      return rec;
+    },
+
+    all() {
+      return records.slice();
+    },
+
+    /** Recompute the chain; detects any altered or removed record. */
+    verify() {
+      let p = 'genesis';
+      for (const r of records) {
+        const { hash, ...body } = r;
+        if (body.prev_hash !== p) return { ok: false, at: r.seq, reason: 'prev_hash_mismatch' };
+        if (sha256hex(canonical(body)) !== hash) return { ok: false, at: r.seq, reason: 'hash_mismatch' };
+        p = hash;
+      }
+      return { ok: true, length: records.length, head: p === 'genesis' ? null : p };
+    },
+  };
+}
+
+export default { createEvidenceLog };

package/index.js

@@ -0,0 +1,243 @@
+/**
+ * @emilia-protocol/gate — EMILIA Gate: the Trusted Action Firewall.
+ * @license Apache-2.0
+ *
+ * Deny-by-default enforcement for consequential machine actions. A guarded
+ * action runs ONLY if it arrives with a receipt that is:
+ *   1. valid          — Ed25519 over canonical JSON, signed by a pinned issuer;
+ *   2. in-scope       — bound to the exact action the manifest guards;
+ *   3. sufficiently   — meets the action's required assurance tier
+ *      assured           (software / class_a device signoff / quorum);
+ *   4. fresh          — within max age; and
+ *   5. unused         — not a replay (one-time consumption).
+ * Otherwise it is refused with a machine-readable Receipt-Required challenge
+ * (HTTP 428). Every decision is appended to a tamper-evident evidence log.
+ *
+ * It is NOT authentication ("who are you") and NOT permissions ("are you
+ * allowed here"). It is a policy-enforcement point that requires portable proof
+ * a named human authorized THIS exact action before the world is mutated.
+ *
+ * Composes @emilia-protocol/require-receipt (manifest + verify + challenge) and
+ * adds the three things a firewall needs over a bare verifier: assurance-tier
+ * enforcement, replay defense, and the evidence log. Fails closed.
+ */
+import {
+  verifyEmiliaReceipt,
+  receiptChallenge,
+  receiptRequiredHeader,
+  validateActionRiskManifest,
+  findActionRequirement,
+  RECEIPT_REQUIRED_STATUS,
+  RECEIPT_REQUIRED_HEADER,
+} from '../require-receipt/index.js';
+import { MemoryConsumptionStore } from './store.js';
+import { createEvidenceLog } from './evidence.js';
+
+export { MemoryConsumptionStore, createEvidenceLog };
+export const ASSURANCE_TIERS = ['software', 'class_a', 'quorum'];
+const TIER_RANK = { software: 0, class_a: 1, quorum: 2 };
+
+/**
+ * The assurance tier a receipt demonstrably meets. Conservative / fail-closed:
+ * if a higher tier's structure is not present, the receipt only earns the lower
+ * tier, and a guard that needs more will refuse it.
+ *   quorum   — a quorum block with >= 2 distinct signers and threshold >= 2.
+ *   class_a  — a device signoff (or claim.outcome === 'allow_with_signoff').
+ *   software — any otherwise-valid receipt (a software-held key).
+ */
+export function receiptAssuranceTier(doc) {
+  const p = doc?.payload || {};
+  const q = p.quorum || p.claim?.quorum;
+  const signers = q && (q.signers || q.approvers);
+  const threshold = q && (q.m ?? q.threshold ?? (Array.isArray(signers) ? signers.length : 0));
+  if (q && Array.isArray(signers) && signers.length >= 2 && threshold >= 2) return 'quorum';
+  if (p.signoff || p.claim?.outcome === 'allow_with_signoff') return 'class_a';
+  return 'software';
+}
+
+/**
+ * Create a gate.
+ * @param {object} opts
+ * @param {object} [opts.manifest]      EP-ACTION-RISK-MANIFEST-v0.1 (which actions are guarded, their tier)
+ * @param {string[]} [opts.trustedKeys] base64url SPKI-DER issuer keys you trust
+ * @param {number} [opts.maxAgeSec=900] reject receipts older than this
+ * @param {object} [opts.store]         consumption store (default in-memory)
+ * @param {object} [opts.log]           evidence log (default in-memory, hash-chained)
+ * @param {boolean} [opts.allowInlineKey=false] accept the receipt's own key (integrity, NOT trust)
+ */
+export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900, store, log, allowInlineKey = false, allowEphemeralStore = false, strictEvidence = true, now = Date.now } = {}) {
+  if (manifest) {
+    const m = validateActionRiskManifest(manifest);
+    if (!m.ok) throw new Error('EMILIA Gate: invalid action-risk manifest: ' + m.errors.join('; '));
+  }
+  if (allowInlineKey) {
+    // eslint-disable-next-line no-console
+    console.warn('EMILIA Gate: allowInlineKey=true accepts a receipt\'s OWN key. This proves INTEGRITY (the receipt was not tampered with) but NOT issuer TRUST (anyone can mint a receipt with their own key). Use for demos only; pin trustedKeys in production.');
+  }
+  // Replay defense is only sound if the consumption store is shared across every
+  // instance that can serve the action. The in-memory default is per-process, so
+  // a receipt consumed on one pod/lambda could be replayed on another. Fail
+  // CLOSED in production unless the operator explicitly accepts a single instance.
+  let consumption = store;
+  if (!consumption) {
+    const isProd = typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'production';
+    if (isProd && !allowEphemeralStore) {
+      throw new Error('EMILIA Gate: no consumption store provided. The default in-memory store is per-process and is NOT safe for multi-instance or serverless deployments — a receipt consumed on one instance can be replayed on another, defeating one-time consumption. Provide a shared store ({ async consume(key) {...} }, e.g. Redis/DB-backed), or pass allowEphemeralStore:true to acknowledge a single-instance deployment.');
+    }
+    consumption = new MemoryConsumptionStore();
+  }
+  const evidence = log || createEvidenceLog({ strict: strictEvidence });
+
+  async function check({ selector = {}, receipt = null } = {}) {
+    const requirement = manifest ? findActionRequirement(manifest, selector) : null;
+    const action = requirement?.action_type || selector.action_type || selector.action || null;
+    const requiredTier = requirement?.assurance_class || selector.assurance_class || 'software';
+
+    async function decide(allow, status, reason, extra = {}) {
+      const entry = {
+        kind: 'decision',
+        at: new Date(typeof now === 'function' ? now() : now).toISOString(),
+        action,
+        allow,
+        status,
+        reason,
+        selector: { ...selector },
+        required_tier: requiredTier,
+        receipt_id: receipt?.payload?.receipt_id ?? null,
+        subject: receipt?.payload?.subject ?? null,
+        ...extra,
+      };
+      let record;
+      try {
+        record = await evidence.record(entry);
+      } catch (e) {
+        // The decision could not be durably recorded. Fail CLOSED: never
+        // authorize an action we cannot account for. Downgrade any allow to a
+        // refusal and best-effort note the downgrade (non-fatal if that fails too).
+        allow = false;
+        status = RECEIPT_REQUIRED_STATUS;
+        reason = 'evidence_log_failed';
+        try {
+          record = await evidence.record({ ...entry, allow: false, status, reason, evidence_error: String(e?.message ?? e) });
+        } catch {
+          record = null;
+        }
+      }
+      const out = { allow, status, reason, action, requirement, evidence: record };
+      if (!allow) {
+        out.challenge = receiptChallenge(action, reason, {
+          status: RECEIPT_REQUIRED_STATUS,
+          assuranceClass: requiredTier,
+          maxAgeSec,
+          manifest: selector.manifestUrl,
+        });
+        out.header = receiptRequiredHeader({ action, assuranceClass: requiredTier, maxAgeSec });
+      }
+      return out;
+    }
+
+    // Manifest present and this selector is not guarded (or explicitly not required): pass through.
+    if (manifest && (!requirement || requirement.receipt_required === false)) {
+      return decide(true, 200, 'not_guarded');
+    }
+    // Guarded, but no receipt was presented.
+    if (!receipt) {
+      return decide(false, RECEIPT_REQUIRED_STATUS, 'receipt_required');
+    }
+    // Signature / freshness / action-binding / outcome.
+    const v = verifyEmiliaReceipt(receipt, { trustedKeys, allowInlineKey, action, maxAgeSec });
+    if (!v.ok) {
+      return decide(false, RECEIPT_REQUIRED_STATUS, `receipt_rejected:${v.reason}`, { rejected: v });
+    }
+    // Assurance tier.
+    const have = receiptAssuranceTier(receipt);
+    if ((TIER_RANK[have] ?? 0) < (TIER_RANK[requiredTier] ?? 0)) {
+      return decide(false, RECEIPT_REQUIRED_STATUS, 'assurance_too_low', { have_tier: have, need_tier: requiredTier });
+    }
+    // One-time consumption (replay defense). Require a stable, issuer-generated
+    // receipt_id — never fall back to a content hash, whose canonicalization can
+    // differ across language implementations and silently break replay detection
+    // when services of different languages share a store.
+    const receiptId = receipt?.payload?.receipt_id;
+    if (!receiptId) {
+      return decide(false, RECEIPT_REQUIRED_STATUS, 'receipt_rejected:missing_receipt_id');
+    }
+    const fresh = await consumption.consume(receiptId);
+    if (!fresh) {
+      return decide(false, RECEIPT_REQUIRED_STATUS, 'replay_refused', { consumption_key: receiptId });
+    }
+    return decide(true, 200, 'allow', { signer: v.signer, outcome: v.outcome, have_tier: have });
+  }
+
+  /** Express/Connect middleware: refuse the route unless a sufficient receipt is present. */
+  function middleware(opts = {}) {
+    return async function emiliaGate(req, res, next) {
+      let selector = typeof opts.selector === 'function' ? opts.selector(req) : { ...(opts.selector || {}) };
+      if (opts.action && !selector.action_type) {
+        selector.action_type = typeof opts.action === 'function' ? opts.action(req) : opts.action;
+      }
+      let doc = null;
+      const hdr = req.headers?.['x-emilia-receipt'];
+      if (hdr) { try { doc = JSON.parse(Buffer.from(hdr, 'base64').toString('utf8')); } catch { /* fallthrough */ } }
+      if (!doc && req.body?.emilia_receipt) doc = req.body.emilia_receipt;
+      const out = await check({ selector, receipt: doc });
+      if (!out.allow) {
+        res.setHeader(RECEIPT_REQUIRED_HEADER, out.header);
+        return res.status(out.status).json(out.challenge);
+      }
+      req.emiliaGate = out;
+      return next();
+    };
+  }
+
+  /**
+   * Emit a post-execution receipt bound to a prior authorization decision — the
+   * "execution emits proof" half of the loop (maps to the EP Commit seal). It
+   * commits to the exact authorization decision (`authorizes_decision` = that
+   * decision's evidence hash), so authorization and execution are one chain.
+   */
+  async function recordExecution({ authorization, outcome = 'executed', detail } = {}) {
+    const auth = authorization?.evidence || authorization || {};
+    return evidence.record({
+      kind: 'execution',
+      at: new Date(typeof now === 'function' ? now() : now).toISOString(),
+      authorizes_decision: auth.hash ?? null,
+      action: authorization?.action ?? auth.action ?? null,
+      receipt_id: auth.receipt_id ?? null,
+      outcome, // 'executed' | 'failed'
+      ...(detail !== undefined ? { detail } : {}),
+    });
+  }
+
+  /**
+   * Wrap any function so it runs only behind a passing gate check, and (unless
+   * disabled) emits an execution receipt after it runs — the full firewall loop:
+   * request -> check -> execute -> execution receipt. Framework-agnostic.
+   */
+  function guard(fn, opts = {}) {
+    return async function guarded(...args) {
+      const selector = typeof opts.selector === 'function' ? opts.selector(...args) : (opts.selector || {});
+      const receipt = typeof opts.receipt === 'function' ? opts.receipt(...args) : (opts.receipt ?? null);
+      const out = await check({ selector, receipt });
+      if (!out.allow) {
+        const e = new Error(`EMILIA Gate refused (${out.reason})`);
+        e.code = 'EMILIA_RECEIPT_REQUIRED';
+        e.gate = out;
+        throw e;
+      }
+      if (opts.recordExecution === false) return fn(...args);
+      try {
+        const result = await fn(...args);
+        await recordExecution({ authorization: out, outcome: 'executed' });
+        return result;
+      } catch (e) {
+        await recordExecution({ authorization: out, outcome: 'failed', detail: String(e?.message ?? e) });
+        throw e;
+      }
+    };
+  }
+
+  return { check, recordExecution, middleware, guard, evidence, store: consumption };
+}
+
+export default { createGate, receiptAssuranceTier, MemoryConsumptionStore, createEvidenceLog, ASSURANCE_TIERS };

package/package.json

@@ -0,0 +1,17 @@
+{
+  "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.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "index.js",
+  "files": ["index.js", "store.js", "evidence.js", "README.md"],
+  "scripts": {
+    "test": "node --test",
+    "demo": "node demo.mjs"
+  },
+  "dependencies": {
+    "@emilia-protocol/require-receipt": "^0.1.0"
+  },
+  "keywords": ["emilia", "authorization", "receipt", "firewall", "trusted-action-firewall", "agent", "mcp", "gate", "policy-enforcement-point", "ai-safety"]
+}

package/store.js

@@ -0,0 +1,31 @@
+/**
+ * @emilia-protocol/gate — consumption store (replay defense).
+ * @license Apache-2.0
+ *
+ * A receipt authorizes ONE action, once. The gate consumes a receipt's
+ * identifier the first time it is used; any later presentation of the same
+ * receipt is a replay and is refused. The default store is in-memory; swap in a
+ * Redis/DB-backed store with the same `consume(key)` contract for a fleet.
+ */
+export class MemoryConsumptionStore {
+  constructor() {
+    this.seen = 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;
+    this.seen.add(key);
+    return true;
+  }
+
+  async has(key) {
+    return this.seen.has(key);
+  }
+
+  get size() {
+    return this.seen.size;
+  }
+}
+
+export default { MemoryConsumptionStore };