@emilia-protocol/gate 0.11.0 → 0.14.0

package/key-registry.js

@@ -1,135 +1,4 @@
 // 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}))$/;
-
-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 = []) {
-  const list = [];
-  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, at) {
-      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 };
+// Compatibility entry point for the TypeScript key-registry module.
+export * from './dist/key-registry.js';
+export { default } from './dist/key-registry.js';

package/mcp.js

@@ -1,110 +1,4 @@
 // 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';
-
-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 = {}, 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 };
+// Compatibility entry point for the TypeScript mcp module.
+export * from './dist/mcp.js';
+export { default } from './dist/mcp.js';

package/metering.js

@@ -1,227 +1,4 @@
 // 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 {{protected_actions:number, allows:number, denies:number,
- *   replays_blocked:number, by_action_type:object, by_tier:object,
- *   receipt_years:number, period:object, integrity_warnings:object[]}}
- */
-export function meterUsage(entries = [], { periodStart, periodEnd, retentionYearsDefault = DEFAULT_RETENTION_YEARS } = {}) {
-  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 = [];
-  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.
- */
-export function buildUsageStatement(usage, { org } = {}) {
-  // 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 };
+// Compatibility entry point for the TypeScript metering module.
+export * from './dist/metering.js';
+export { default } from './dist/metering.js';