@emilia-protocol/gate 0.11.0 → 0.14.0

package/src/key-registry.ts

@@ -0,0 +1,150 @@
+// 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).
+ */
+
+const RFC3339_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|([+-])(\d{2}):(\d{2}))$/;
+
+type RawKeyEntry = {
+  kid?: string;
+  key: string;
+  not_before?: string;
+  not_after?: string;
+  revoked_at?: string;
+};
+type NormalizedKeyEntry = {
+  kid: string;
+  key: string;
+  not_before: number | null;
+  not_after: number | null;
+  revoked_at: number | null;
+};
+
+function strictInstantMs(value) {
+  if (typeof value !== 'string') return NaN;
+  const match = value.match(RFC3339_INSTANT);
+  if (!match) return NaN;
+  const [, y, mo, d, h, mi, s, , oh, om] = match;
+  const calendar = new Date(0);
+  calendar.setUTCFullYear(Number(y), Number(mo) - 1, Number(d));
+  calendar.setUTCHours(Number(h), Number(mi), Number(s), 0);
+  if (calendar.toISOString().slice(0, 19) !== `${y}-${mo}-${d}T${h}:${mi}:${s}`) return NaN;
+  if (oh !== undefined && (Number(oh) > 23 || Number(om) > 59)) return NaN;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : NaN;
+}
+
+function optionalInstant(entry, field) {
+  if (!Object.hasOwn(entry, field)) return null;
+  const ms = strictInstantMs(entry[field]);
+  if (!Number.isFinite(ms)) {
+    throw new Error(`key registry: ${field} must be a valid RFC3339 instant when supplied`);
+  }
+  return ms;
+}
+
+/**
+ * @param {Array<object>} entries each: {
+ *   kid?: string, key: string (base64url SPKI-DER public key),
+ *   not_before?: string, not_after?: string, revoked_at?: string (strict RFC3339)
+ * }
+ */
+export function createKeyRegistry(entries: RawKeyEntry[] = []) {
+  const list: NormalizedKeyEntry[] = [];
+  function normalize(e) {
+    if (!e || !e.key || typeof e.key !== 'string') throw new Error('key registry entry requires a base64url SPKI key');
+    const normalized = {
+      kid: e.kid || e.key.slice(0, 16),
+      key: e.key,
+      not_before: optionalInstant(e, 'not_before'),
+      not_after: optionalInstant(e, 'not_after'),
+      revoked_at: optionalInstant(e, 'revoked_at'),
+    };
+    if (normalized.not_before != null && normalized.not_after != null
+        && normalized.not_after < normalized.not_before) {
+      throw new Error('key registry: not_after must not precede not_before');
+    }
+    return normalized;
+  }
+  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 (!Number.isFinite(atMs)) return false;
+    if (entry.not_before != null && atMs < entry.not_before) return false;
+    if (entry.not_after != null && atMs > entry.not_after) return false;
+    return true;
+  }
+
+  return {
+    /** The base64url public keys to verify a receipt issued at strict RFC3339 `at`. */
+    keysValidAt(at) {
+      const atMs = strictInstantMs(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: string, at?: string) {
+      let revokedAt = 0;
+      if (arguments.length > 1) {
+        revokedAt = strictInstantMs(at);
+        if (!Number.isFinite(revokedAt)) {
+          throw new Error('key registry: revoked_at must be a valid RFC3339 instant when supplied');
+        }
+      }
+      let n = 0;
+      for (const e of list) {
+        if (e.kid === kid && e.revoked_at == null) { e.revoked_at = revokedAt; 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 supplied = arguments.length > 0;
+      const atMs = supplied ? strictInstantMs(at) : NaN;
+      return list.map((e) => ({
+        kid: e.kid,
+        revoked: e.revoked_at != null,
+        active: supplied
+          ? entryActiveAt(e, atMs)
+          : e.revoked_at == null && e.not_before == null && e.not_after == null,
+        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/src/mcp.ts

@@ -0,0 +1,120 @@
+// 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], store: sharedConsumptionStore });
+ *
+ *   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.
+ */
+
+import { parseReceiptCarrier } from '@emilia-protocol/require-receipt';
+
+type Obj = Record<string, any>;
+
+type GateMcpToolOptions = {
+  tool?: string;
+  protocol?: string;
+  action?: string;
+  observedAction?: Obj | ((args: Obj, extra: any) => any);
+  receipt?: Obj | ((args: Obj) => any);
+};
+
+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') {
+      return parseReceiptCarrier(args._emilia_receipt_b64);
+    }
+  }
+  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: GateMcpToolOptions = {}, 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 }');
+
+  const refused = (reason, body = null) => ({
+    isError: true,
+    content: [{
+      type: 'text',
+      text: `EMILIA Gate refused "${tool}": ${reason}. `
+        + 'This is a high-risk action; present a valid, sufficiently-assured, unused human/quorum receipt.',
+    }],
+    _emilia: {
+      gate: 'refused',
+      status: 428,
+      reason,
+      challenge: body,
+    },
+  });
+
+  return async function gatedTool(args = {}, extra) {
+    const selector = { protocol, tool, ...(action ? { action_type: action } : {}) };
+    let receipt;
+    let observedAction;
+    try {
+      receipt = resolveReceipt(args, o);
+      observedAction = typeof o.observedAction === 'function'
+        ? o.observedAction(args, extra)
+        : (o.observedAction ?? args);
+    } catch {
+      return refused('receipt_boundary_failed');
+    }
+
+    const out = await gate.run({ selector, receipt, observedAction }, () => handler(args, extra));
+    if (!out.ok) {
+      return refused(out.authorization.reason, 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/src/metering.ts

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — usage metering (the value metric, EP-GATE-USAGE-v1).
+ *
+ * Pricing scales with what the gate actually protects: PROTECTED IRREVERSIBLE
+ * ACTIONS (guarded decisions — allows AND denies both consume enforcement) plus
+ * RECEIPT-YEARS under retention (one receipt kept one year = one receipt-year;
+ * horizons follow retention.js, default 6y = 2190 days). NEVER seats.
+ *
+ * Pure functions over evidence-log entries (`evidence.all()`); no clock, no
+ * network. The billing period is an explicit [periodStart, periodEnd) window —
+ * INCLUSIVE start, EXCLUSIVE end — so adjacent periods never double-count an
+ * entry sitting exactly on a boundary.
+ *
+ * Fail-closed posture for billing: an unbounded or reversed period is refused
+ * (thrown); malformed entries are surfaced in `integrity_warnings` rather than
+ * silently dropped; an entry whose allow flag is not literally `true` is
+ * counted as a deny; a statement over foreign or malformed usage is refused.
+ * `buildUsageStatement` output is deterministic (sorted keys + content hash)
+ * and UNSIGNED — the deployer signs it; the content hash binds that signature
+ * to exactly these numbers for billing reconciliation.
+ */
+import crypto from 'node:crypto';
+
+export const USAGE_VERSION = 'EP-GATE-USAGE-v1';
+
+const DAYS_PER_YEAR = 365;
+// Mirrors retention.js's cold-horizon default (coldDays = 2190 = 6y): a receipt
+// is presumed retained for the full audit horizon unless the entry states its own.
+const DEFAULT_RETENTION_YEARS = 2190 / DAYS_PER_YEAR;
+
+function sha256hex(s) {
+  return crypto.createHash('sha256').update(s).digest('hex');
+}
+
+/** Canonical JSON (recursive sorted keys) — matches evidence.js / @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);
+}
+
+function toMs(t) {
+  if (t == null) return null;
+  const ms = typeof t === 'number' ? t : Date.parse(t);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/** Key-sorted copy so output is byte-stable regardless of entry order. */
+function sortedCounts(map) {
+  const out = {};
+  for (const k of Object.keys(map).sort()) out[k] = map[k];
+  return out;
+}
+
+/** Entry-level day resolution (1/365y ≈ 0.00274) without float noise. */
+function round6(x) {
+  return Math.round(x * 1e6) / 1e6;
+}
+
+/**
+ * The retention this entry STATES for itself, in years.
+ * @returns {number|null|NaN} years, `null` when unstated (default applies),
+ *   `NaN` when stated but invalid (default applies + integrity warning — a
+ *   malformed stated value must never silently shrink the metered total).
+ */
+function statedRetentionYears(e) {
+  if (e.retention_years != null) {
+    const y = Number(e.retention_years);
+    return Number.isFinite(y) && y >= 0 ? y : NaN;
+  }
+  if (e.retention_days != null) {
+    const d = Number(e.retention_days);
+    return Number.isFinite(d) && d >= 0 ? d / DAYS_PER_YEAR : NaN;
+  }
+  return null;
+}
+
+/**
+ * Meter a billing period over evidence entries.
+ *
+ * Billable = `kind: 'decision'` entries on GUARDED actions (`not_guarded`
+ * pass-throughs are free; execution records are provenance, not enforcement).
+ * Window is [periodStart, periodEnd): inclusive start, exclusive end.
+ *
+ * @param {Array<object>} entries  evidence.all()
+ * @param {object} [o]
+ * @param {string|number} [o.periodStart]  ISO or ms — required
+ * @param {string|number} [o.periodEnd]    ISO or ms — required, >= periodStart
+ * @param {number} [o.retentionYearsDefault=6]  applied when an entry states no retention
+ * @returns {{'@version':string, protected_actions:number, allows:number, denies:number,
+ *   replays_blocked:number, by_action_type:object, by_tier:object,
+ *   receipt_years:number, retention_years_default:number, period:object, integrity_warnings:object[]}}
+ */
+export function meterUsage(entries: any[] = [], {
+  periodStart,
+  periodEnd,
+  retentionYearsDefault = DEFAULT_RETENTION_YEARS,
+}: {
+  periodStart?: string | number;
+  periodEnd?: string | number;
+  retentionYearsDefault?: number;
+} = {}) {
+  const startMs = toMs(periodStart);
+  const endMs = toMs(periodEnd);
+  // An unbounded or reversed period is not meterable — refuse rather than emit
+  // a statement whose window cannot be reconciled.
+  if (startMs == null || endMs == null) {
+    throw new Error('meterUsage: periodStart and periodEnd are required (ISO string or ms)');
+  }
+  if (endMs < startMs) throw new Error('meterUsage: periodEnd must be >= periodStart');
+  if (!Number.isFinite(retentionYearsDefault) || retentionYearsDefault < 0) {
+    throw new Error('meterUsage: retentionYearsDefault must be a finite number >= 0');
+  }
+
+  const warnings: { index: number; reason: string }[] = [];
+  const byAction = Object.create(null);
+  const byTier = Object.create(null);
+  let protectedActions = 0;
+  let allows = 0;
+  let denies = 0;
+  let replaysBlocked = 0;
+  let receiptYears = 0;
+
+  entries.forEach((e, index) => {
+    if (!e || typeof e !== 'object' || Array.isArray(e)) {
+      warnings.push({ index, reason: 'not_an_object' });
+      return;
+    }
+    const t = toMs(e.at);
+    if (t == null) {
+      // Unplaceable in ANY period — surfaced, never silently dropped.
+      warnings.push({ index, reason: 'unparseable_at' });
+      return;
+    }
+    if (t < startMs || t >= endMs) return; // outside [start, end)
+    if (typeof e.kind !== 'string' || e.kind.length === 0) {
+      warnings.push({ index, reason: 'missing_kind' });
+      return;
+    }
+    if (e.kind !== 'decision') return; // execution/other records are not billable
+    if (e.reason === 'not_guarded') return; // pass-throughs are free by design
+
+    protectedActions += 1;
+    // Fail closed: only a literal `true` counts as an allow.
+    if (e.allow === true) allows += 1; else denies += 1;
+    if (e.reason === 'replay_refused') replaysBlocked += 1;
+
+    const action = typeof e.action === 'string' && e.action ? e.action : 'unknown';
+    byAction[action] = (byAction[action] || 0) + 1;
+    const tier = typeof e.required_tier === 'string' && e.required_tier ? e.required_tier : 'unknown';
+    byTier[tier] = (byTier[tier] || 0) + 1;
+
+    const stated = statedRetentionYears(e);
+    if (Number.isNaN(stated)) {
+      warnings.push({ index, reason: 'invalid_stated_retention' });
+      receiptYears += retentionYearsDefault;
+    } else {
+      receiptYears += stated ?? retentionYearsDefault;
+    }
+  });
+
+  return {
+    '@version': USAGE_VERSION,
+    period: {
+      start: new Date(startMs).toISOString(),
+      end: new Date(endMs).toISOString(),
+      bounds: 'inclusive_start_exclusive_end',
+    },
+    protected_actions: protectedActions,
+    allows,
+    denies,
+    replays_blocked: replaysBlocked,
+    by_action_type: sortedCounts(byAction),
+    by_tier: sortedCounts(byTier),
+    receipt_years: round6(receiptYears),
+    retention_years_default: retentionYearsDefault,
+    integrity_warnings: warnings,
+  };
+}
+
+/**
+ * Build the signed-ready usage statement handed to billing reconciliation.
+ * UNSIGNED — the deployer signs it; `content_hash` (sha256 over the canonical
+ * JSON of everything else) binds that signature to exactly these numbers.
+ * Deterministic: same usage + org → byte-identical statement, regardless of
+ * the entry order the usage was metered from.
+ * @param {object} usage  a USAGE_VERSION object from meterUsage
+ * @param {{ org?: string }} [o]
+ */
+export function buildUsageStatement(usage, { org }: { org?: string } = {}) {
+  // Never emit a statement over an artifact of a different or unknown format,
+  // and never one that fails to name who it bills.
+  if (!usage || usage['@version'] !== USAGE_VERSION) {
+    throw new Error(`buildUsageStatement: usage must be a ${USAGE_VERSION} object from meterUsage`);
+  }
+  if (!org || typeof org !== 'string') {
+    throw new Error('buildUsageStatement: org is required — a statement must name the billed party');
+  }
+  if (!usage.period || !usage.period.start || !usage.period.end) {
+    throw new Error('buildUsageStatement: usage.period is missing');
+  }
+  for (const k of ['protected_actions', 'allows', 'denies', 'replays_blocked', 'receipt_years']) {
+    if (!Number.isFinite(usage[k]) || usage[k] < 0) {
+      throw new Error(`buildUsageStatement: usage.${k} must be a finite number >= 0`);
+    }
+  }
+  const warningCount = Array.isArray(usage.integrity_warnings) ? usage.integrity_warnings.length : 0;
+  const body = {
+    '@version': USAGE_VERSION,
+    kind: 'usage_statement',
+    org,
+    period: {
+      start: usage.period.start,
+      end: usage.period.end,
+      bounds: 'inclusive_start_exclusive_end',
+    },
+    protected_actions: usage.protected_actions,
+    allows: usage.allows,
+    denies: usage.denies,
+    replays_blocked: usage.replays_blocked,
+    by_action_type: sortedCounts(usage.by_action_type || {}),
+    by_tier: sortedCounts(usage.by_tier || {}),
+    receipt_years: usage.receipt_years,
+    retention_years_default: usage.retention_years_default ?? DEFAULT_RETENTION_YEARS,
+    // Data-quality signal for the reconciler: a statement metered over a log
+    // with integrity warnings is flagged incomplete, never silently clean.
+    integrity_warning_count: warningCount,
+    complete: warningCount === 0,
+  };
+  return { ...body, content_hash: sha256hex(canonical(body)) };
+}
+
+export default { meterUsage, buildUsageStatement, USAGE_VERSION };