@emilia-protocol/gate 0.9.0 → 0.9.2

package/metrics.js

@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — Prometheus metrics exposition (EP-GATE-METRICS-v1).
+ *
+ * Zero-dependency operational metrics over gate decisions, rendered in the
+ * Prometheus text exposition format 0.0.4 (HELP/TYPE lines, escaped label
+ * values, stable sorted output). Feed it the gate's decision entries — either
+ * the evidence-log entry ({ allow, action, reason, have_tier/required_tier,
+ * at }) or the `check()` output — via `onDecision`; scrape via `render()` or
+ * mount `handler()` on any framework.
+ *
+ * CONSTRAINT (enforced): metrics must NEVER throw into the enforcement path.
+ * `onDecision` sits on the gate's decision hot path; observability is never
+ * allowed to break enforcement. Any entry it cannot interpret — wrong type,
+ * underivable outcome, even a poisoned object whose property getters throw —
+ * increments ep_gate_metrics_malformed_total and returns. No exception
+ * escapes `onDecision`, ever.
+ *
+ * CARDINALITY GUARD: the action_type label is capped to a bounded set via the
+ * `maxSeries` option (default 64 distinct values). Once the cap is reached,
+ * new action types bucket to action_type="_other" so a hostile or buggy
+ * caller cannot blow up the time-series database. All label values are also
+ * length-capped. outcome and reason_class are bounded by construction.
+ *
+ * Deterministic and pure: time is injected (`now`), used only when an entry
+ * carries no usable timestamp. Same entries in, same exposition text out.
+ */
+
+export const METRICS_VERSION = 'EP-GATE-METRICS-v1';
+
+/** Prometheus text exposition format 0.0.4 content type. */
+export const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+
+/** Bounded denial reason classes — every gate refusal maps into exactly one. */
+export const REASON_CLASSES = [
+  'replay',            // replay_refused — one-time consumption caught a reuse
+  'receipt_missing',   // receipt_required — guarded action arrived with no receipt
+  'receipt_invalid',   // receipt_rejected:* — signature/freshness/scope/id failures
+  'assurance',         // assurance_too_low | unknown_required_tier
+  'execution_binding', // execution_binding_failed — claim != observed mutation
+  'infrastructure',    // evidence_log_failed | consumption_store_lacks_reserve
+  'other',             // anything this version does not model
+];
+
+/** Longest label value we will expose; longer values are truncated (bounded exposition size). */
+const MAX_LABEL_VALUE_LEN = 128;
+
+/** Overflow bucket for the action_type cardinality guard. */
+const OTHER_BUCKET = '_other';
+
+/**
+ * Classify a gate denial reason string into one of REASON_CLASSES. Bounded by
+ * construction: unknown reasons land in 'other', never in a fresh label value.
+ * @param {string} reason e.g. 'replay_refused', 'receipt_rejected:bad_signature'
+ * @returns {string} one of REASON_CLASSES
+ */
+export function classifyDenialReason(reason) {
+  if (typeof reason !== 'string') return 'other';
+  if (reason === 'replay_refused' || reason.includes('replay')) return 'replay';
+  if (reason === 'receipt_required') return 'receipt_missing';
+  if (reason.startsWith('receipt_rejected')) return 'receipt_invalid';
+  if (reason === 'assurance_too_low' || reason === 'unknown_required_tier') return 'assurance';
+  if (reason === 'execution_binding_failed') return 'execution_binding';
+  if (reason === 'evidence_log_failed' || reason === 'consumption_store_lacks_reserve') return 'infrastructure';
+  return 'other';
+}
+
+/** Escape a label value per the exposition format: backslash, quote, newline. */
+function escapeLabelValue(v) {
+  return String(v)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n');
+}
+
+/** Escape HELP text per the exposition format: backslash and newline only. */
+function escapeHelp(v) {
+  return String(v).replace(/\\/g, '\\\\').replace(/\n/g, '\\n');
+}
+
+/** Normalize a raw value into a safe, length-capped label value. */
+function normLabel(raw, fallback) {
+  if (typeof raw !== 'string' || raw.length === 0) return fallback;
+  return raw.length > MAX_LABEL_VALUE_LEN ? raw.slice(0, MAX_LABEL_VALUE_LEN) : raw;
+}
+
+/** Render a sorted, escaped label set: {a="x",b="y"} — stable key order. */
+function renderLabels(obj) {
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${k}="${escapeLabelValue(obj[k])}"`).join(',')}}`;
+}
+
+const METRICS = [
+  { name: 'ep_gate_decisions_total', type: 'counter', help: 'Gate decisions by outcome, action type, and credited assurance tier.' },
+  { name: 'ep_gate_denials_total', type: 'counter', help: 'Denied gate decisions by bounded denial reason class.' },
+  { name: 'ep_gate_evidence_entries_total', type: 'counter', help: 'Evidence-log entries recorded for gate decisions.' },
+  { name: 'ep_gate_last_decision_timestamp_seconds', type: 'gauge', help: 'Unix timestamp (seconds) of the most recent gate decision.' },
+  { name: 'ep_gate_metrics_malformed_total', type: 'counter', help: 'Decision entries the metrics layer could not interpret (dropped, never thrown).' },
+  { name: 'ep_gate_replays_blocked_total', type: 'counter', help: 'Receipt replays refused by one-time consumption.' },
+];
+
+/**
+ * Create a metrics registry for one gate.
+ * @param {object} [o]
+ * @param {number} [o.maxSeries=64] cap on distinct action_type label values; overflow buckets to "_other"
+ * @param {number|function} [o.now=Date.now] injected clock (ms or () => ms) — used only when an entry has no usable timestamp
+ * @returns {{ onDecision: (entry: object) => void, render: () => string, handler: () => { status: number, headers: object, body: string } }}
+ */
+export function createMetrics({ maxSeries = 64, now = Date.now } = {}) {
+  // Config is clamped, not thrown: a bad option must not brick metrics either.
+  const cap = (Number.isInteger(maxSeries) && maxSeries > 0) ? maxSeries : 64;
+
+  const decisions = new Map(); // rendered label set -> count
+  const denials = new Map();   // rendered label set -> count
+  let replaysBlocked = 0;
+  let evidenceEntries = 0;
+  let malformed = 0;
+  let lastDecisionSeconds = null; // gauge; no sample until the first decision
+
+  const actionTypes = new Set(); // cardinality guard for action_type
+
+  function boundedActionType(raw) {
+    const v = normLabel(raw, 'unknown');
+    if (actionTypes.has(v)) return v;
+    if (actionTypes.size < cap) { actionTypes.add(v); return v; }
+    return OTHER_BUCKET;
+  }
+
+  function inc(map, key) {
+    map.set(key, (map.get(key) || 0) + 1);
+  }
+
+  /**
+   * Observe one gate decision. NEVER throws — see the module constraint. A
+   * malformed entry (non-object, underivable outcome, throwing getters, ...)
+   * increments ep_gate_metrics_malformed_total and returns.
+   */
+  function onDecision(entry) {
+    try {
+      if (!entry || typeof entry !== 'object') { malformed += 1; return; }
+
+      // Outcome: the authoritative field is the boolean `allow` (evidence
+      // entry and check() output both carry it). A string outcome is accepted
+      // only if it is exactly 'allow'/'deny'. Anything else is malformed.
+      let outcome;
+      if (entry.allow === true) outcome = 'allow';
+      else if (entry.allow === false) outcome = 'deny';
+      else if (entry.outcome === 'allow' || entry.outcome === 'deny') outcome = entry.outcome;
+      else { malformed += 1; return; }
+
+      const actionType = boundedActionType(entry.action_type ?? entry.action);
+      const tier = normLabel(entry.tier ?? entry.have_tier ?? entry.required_tier, 'unknown');
+
+      inc(decisions, renderLabels({ outcome, action_type: actionType, tier }));
+
+      if (outcome === 'deny') {
+        const reasonClass = classifyDenialReason(entry.reason);
+        inc(denials, renderLabels({ reason_class: reasonClass }));
+        if (reasonClass === 'replay') replaysBlocked += 1;
+      }
+
+      // Each decision appends one evidence record — unless the entry says the
+      // write failed outright (check() output carries evidence: null then).
+      if (entry.evidence !== null) evidenceEntries += 1;
+
+      // Gauge: prefer the entry's own timestamp (`at` ISO/ms), else the
+      // injected clock. An unusable clock skips the gauge — never throws.
+      const at = entry.at ?? entry.created_at ?? null;
+      let ms = null;
+      if (typeof at === 'number' && Number.isFinite(at)) ms = at;
+      else if (typeof at === 'string') { const p = Date.parse(at); if (Number.isFinite(p)) ms = p; }
+      if (ms == null) {
+        try {
+          const n = typeof now === 'function' ? now() : now;
+          if (typeof n === 'number' && Number.isFinite(n)) ms = n;
+        } catch { /* unusable injected clock: skip the gauge update */ }
+      }
+      if (ms != null) lastDecisionSeconds = ms / 1000;
+    } catch {
+      // The never-throw guarantee: a poisoned entry (throwing getter, hostile
+      // proxy) lands here. Count it, drop it, return. Enforcement continues.
+      malformed += 1;
+    }
+  }
+
+  /** Render Prometheus text format 0.0.4. Deterministic: metrics in fixed order, series sorted. */
+  function render() {
+    const lines = [];
+    for (const m of METRICS) {
+      lines.push(`# HELP ${m.name} ${escapeHelp(m.help)}`);
+      lines.push(`# TYPE ${m.name} ${m.type}`);
+      switch (m.name) {
+        case 'ep_gate_decisions_total':
+          for (const k of [...decisions.keys()].sort()) lines.push(`${m.name}${k} ${decisions.get(k)}`);
+          break;
+        case 'ep_gate_denials_total':
+          for (const k of [...denials.keys()].sort()) lines.push(`${m.name}${k} ${denials.get(k)}`);
+          break;
+        case 'ep_gate_evidence_entries_total':
+          lines.push(`${m.name} ${evidenceEntries}`);
+          break;
+        case 'ep_gate_last_decision_timestamp_seconds':
+          // No sample until the first decision — a fabricated 0 would read as 1970.
+          if (lastDecisionSeconds != null) lines.push(`${m.name} ${lastDecisionSeconds}`);
+          break;
+        case 'ep_gate_metrics_malformed_total':
+          lines.push(`${m.name} ${malformed}`);
+          break;
+        case 'ep_gate_replays_blocked_total':
+          lines.push(`${m.name} ${replaysBlocked}`);
+          break;
+        /* c8 ignore next 2 -- METRICS is a module constant; no other names exist */
+        default:
+          break;
+      }
+    }
+    return lines.join('\n') + '\n';
+  }
+
+  /** Framework-agnostic scrape response: mount on any router/handler. */
+  function handler() {
+    return {
+      status: 200,
+      headers: { 'content-type': METRICS_CONTENT_TYPE },
+      body: render(),
+    };
+  }
+
+  return { onDecision, render, handler };
+}
+
+export default { createMetrics, classifyDenialReason, METRICS_VERSION, METRICS_CONTENT_TYPE, REASON_CLASSES };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@emilia-protocol/gate",
-  "version": "0.9.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.",
+  "version": "0.9.2",
+  "description": "EMILIA Gate \u2014 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",
@@ -23,7 +23,19 @@
     "./adapters/salesforce": "./adapters/salesforce.js",
     "./key-registry": "./key-registry.js",
     "./retention": "./retention.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./enterprise": "./enterprise.js",
+    "./metering": "./metering.js",
+    "./siem": "./siem.js",
+    "./roster": "./roster.js",
+    "./reports/art14": "./reports/art14.js",
+    "./reports/underwriter": "./reports/underwriter.js",
+    "./metrics": "./metrics.js",
+    "./breakglass": "./breakglass.js",
+    "./store-postgres": "./store-postgres.js",
+    "./reports/auditor-workpaper": "./reports/auditor-workpaper.js",
+    "./reports/reperform": "./reports/reperform.js",
+    "./reports/external-verification": "./reports/external-verification.js"
   },
   "files": [
     "index.js",
@@ -56,7 +68,32 @@
     "adapters/salesforce.js",
     "demo.mjs",
     "custody-demo.mjs",
-    "README.md"
+    "README.md",
+    "enterprise.js",
+    "metering.js",
+    "siem.js",
+    "roster.js",
+    "reports/art14.js",
+    "reports/underwriter.js",
+    "metrics.js",
+    "breakglass.js",
+    "store-postgres.js",
+    "deploy/helm/emilia-gate/Chart.yaml",
+    "deploy/helm/emilia-gate/values.yaml",
+    "deploy/helm/emilia-gate/templates/deployment.yaml",
+    "deploy/helm/emilia-gate/templates/service.yaml",
+    "deploy/helm/emilia-gate/templates/configmap.yaml",
+    "deploy/helm/emilia-gate/templates/servicemonitor.yaml",
+    "deploy/helm/emilia-gate/templates/NOTES.txt",
+    "deploy/helm/README.md",
+    "deploy/terraform/main.tf",
+    "deploy/terraform/variables.tf",
+    "deploy/terraform/outputs.tf",
+    "deploy/terraform/versions.tf",
+    "deploy/terraform/README.md",
+    "reports/auditor-workpaper.js",
+    "reports/reperform.js",
+    "reports/external-verification.js"
   ],
   "scripts": {
     "test": "node --test",

package/reliance-packet.js

@@ -3,6 +3,54 @@
 
 export const RELIANCE_PACKET_VERSION = 'EP-GATE-RELIANCE-PACKET-v1';
 
+// The CLOSED admissibility verdict set (mirror of lib/evidence/admissibility.js
+// ADMISSIBILITY_VERDICTS). The gate does NOT import that app module — it stays a
+// dependency-light published package — so the closed set is restated here as a
+// value contract. 'admissible' is the ONLY verdict that reads as success; every
+// other member, and anything not in this set, fails closed. Precedence lives in
+// the evaluator; the gate never re-derives a verdict, it only checks the one the
+// relying party's offline evaluator already computed.
+export const ADMISSIBILITY_VERDICTS = Object.freeze([
+  'admissible', 'missing_evidence', 'stale', 'conflicted', 'unverifiable',
+]);
+
+/**
+ * Normalize an admissibility block onto the packet. FAIL CLOSED: a missing block,
+ * a missing/unrecognized verdict, or a non-'admissible' verdict all produce
+ * admissible:false. The block is only carried when the caller supplies one; when
+ * absent, `admissibility` is null and no admissibility gating applies (backwards
+ * compatible with pre-profile packets).
+ *
+ * @param {object|null} adm  the relying-party evaluator's result, carrying
+ *   { admissibility_profile:{id,version}, profile_hash, verdict, replay_digest, challenge_id?, challenge_digest? }
+ */
+function normalizeAdmissibility(adm) {
+  if (!adm || typeof adm !== 'object') return null;
+  const verdict = typeof adm.verdict === 'string' ? adm.verdict : null;
+  const recognized = verdict !== null && ADMISSIBILITY_VERDICTS.includes(verdict);
+  // Only a recognized 'admissible' verdict reads as success. Missing, malformed,
+  // or any other closed-set member (missing_evidence/stale/conflicted/unverifiable)
+  // is non-admissible.
+  const admissible = recognized && verdict === 'admissible';
+  const profile = adm.admissibility_profile && typeof adm.admissibility_profile === 'object'
+    ? { id: adm.admissibility_profile.id ?? null, version: adm.admissibility_profile.version ?? null }
+    : null;
+  return {
+    admissibility_profile: profile,
+    profile_hash: typeof adm.profile_hash === 'string' ? adm.profile_hash : null,
+    verdict: verdict, // preserved verbatim (including null / unrecognized) for the auditor
+    verdict_recognized: recognized,
+    admissible,
+    replay_digest: typeof adm.replay_digest === 'string' ? adm.replay_digest : null,
+    // The evidence-challenge loop (lib/negotiate/evidence-challenge.js) keys each
+    // round by challenge_id; challenge_digest is carried through when the caller
+    // hashes the challenge. Either identifies which challenge round this verdict
+    // answers. Both null-safe.
+    challenge_id: adm.challenge_id ?? null,
+    challenge_digest: typeof adm.challenge_digest === 'string' ? adm.challenge_digest : null,
+  };
+}
+
 function evidenceStatus(evidence) {
   if (!evidence) return { ok: null, length: null, head: null };
   if (typeof evidence.verify === 'function') return evidence.verify();
@@ -19,6 +67,7 @@ export function buildReliancePacket({
   evidence = null,
   manifest = null,
   binding = null,
+  admissibility = null,
   verifier = '@emilia-protocol/gate',
 } = {}) {
   const evidenceCheck = evidenceStatus(evidence);
@@ -28,7 +77,15 @@ export function buildReliancePacket({
   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';
+
+  // Admissibility block (relying-party evaluator output, computed OFFLINE against
+  // its PINNED profile — never re-derived here). When present it is an additional
+  // gate on 'rely': a non-'admissible' verdict (or a missing/unrecognized one)
+  // fails closed. When absent, admissibility does not affect the verdict.
+  const adm = normalizeAdmissibility(admissibility);
+  const admissibilityOk = adm === null ? true : adm.admissible === true;
+
+  const verdict = allowed && executionBound && evidenceOk && bindingOk && admissibilityOk ? 'rely' : 'do_not_rely';
 
   return {
     '@version': RELIANCE_PACKET_VERSION,
@@ -44,7 +101,17 @@ export function buildReliancePacket({
       decision_hash: decisionHash,
       execution_hash: execution?.hash || null,
       evidence_head: evidenceCheck.head || null,
+      // Surface the admissibility verdict + pinned profile in the summary so an
+      // auditor sees WHICH bar was cleared without digging into checks. Null when
+      // no admissibility block was supplied.
+      admissibility_verdict: adm ? adm.verdict : null,
+      admissibility_profile: adm ? adm.admissibility_profile : null,
+      admissibility_profile_hash: adm ? adm.profile_hash : null,
     },
+    // Full admissibility block (or null). The auditor / gate can re-check
+    // {profile_hash, verdict, replay_digest} against the profile the relying party
+    // pinned. Carried verbatim, fail-closed by construction (see normalizeAdmissibility).
+    admissibility: adm,
     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),
@@ -52,14 +119,25 @@ export function buildReliancePacket({
       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),
+      // Admissibility verdict against the relying party's PINNED profile. null when
+      // no profile/verdict was supplied (this reliance did not gate on admissibility);
+      // true only for a recognized 'admissible' verdict; false otherwise (fail closed).
+      check(
+        'admissibility_verdict_admissible',
+        adm === null ? null : adm.admissible === true,
+        adm === null
+          ? 'no admissibility profile / verdict supplied for this reliance'
+          : { verdict: adm.verdict, verdict_recognized: adm.verdict_recognized, profile: adm.admissibility_profile, profile_hash: adm.profile_hash, replay_digest: adm.replay_digest },
+      ),
     ],
     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.',
+      'An admissible verdict means the evidence bundle cleared the bar THIS relying party pinned; it does not establish the action is correct, safe, or currently valid beyond the freshness bounds evaluated. The verdict is computed OFFLINE by the relying party against its own pinned profile — EMILIA neither hosts the authoritative registry nor adjudicates.',
     ],
   };
 }
 
-export default { RELIANCE_PACKET_VERSION, buildReliancePacket };
+export default { RELIANCE_PACKET_VERSION, ADMISSIBILITY_VERDICTS, buildReliancePacket };