@emilia-protocol/gate 0.10.0 → 0.13.0

package/src/roster.ts

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — signer-roster sync from an enterprise IdP (EP-GATE-ROSTER-v1).
+ *
+ * The boring key story: WHO may approve is an HR fact, not a crypto fact. This
+ * module turns a SCIM-like IdP export into a versioned signer roster and
+ * reconciles a key registry (key-registry.js) against it, so a deprovisioned
+ * employee STOPS being an acceptable approver on the next sync. Fail closed:
+ *   - only `active === true` users' keys are ever pinned; anything else
+ *     (false, missing, truthy-but-not-boolean) never pins;
+ *   - a user absent from the import — offboarded, or silently dropped by a
+ *     broken IdP export — has every previously pinned key revoked;
+ *   - a kid claimed by two principals (or carrying two different key
+ *     materials) is CONTESTED: it pins nothing and is revoked if present;
+ *   - an import that would leave ZERO active signers requires an explicit
+ *     `allowEmpty` acknowledgment, so an empty/broken IdP response cannot
+ *     silently mass-revoke every approver.
+ *
+ * importRoster/diffRoster are pure (inputs in, artifact out; `importedAt` is
+ * the caller-supplied clock). applyRosterToRegistry mutates the given registry
+ * through its real API: key-registry CAN express revocation (`revoke(kid, at)`,
+ * hard and fail-closed), so reconciliation performs it directly and the
+ * returned `revoked` list is the exact set of revocations performed.
+ */
+
+export const ROSTER_VERSION = 'EP-GATE-ROSTER-v1';
+
+/**
+ * Import a SCIM-like IdP user export into a signer roster.
+ * @param {Array<{id:string, userName:string, active:boolean, emails?:any, keys?:Array<{kid:string, publicKey:string}>}>} idpUsers
+ * @param {object} [o]
+ * @param {string} [o.source]        IdP provenance, e.g. 'scim:okta:acme' (required)
+ * @param {string|number} [o.importedAt]  import time (ISO or ms); the caller's clock
+ * @param {boolean} [o.allowEmpty=false]  acknowledge an import with zero active signers
+ * @returns {{version:string, source:string, imported_at:string, signers:Array<{principal:string, kid:string, publicKey:string, active:boolean}>, integrity_warnings:object[]}}
+ */
+export function importRoster(idpUsers, {
+  source,
+  importedAt,
+  allowEmpty = false,
+}: {
+  source?: string;
+  importedAt?: string | number;
+  allowEmpty?: boolean;
+} = {}) {
+  if (!Array.isArray(idpUsers)) throw new Error('roster import: idpUsers must be an array');
+  if (!source || typeof source !== 'string') {
+    throw new Error('roster import: source (IdP provenance, e.g. "scim:okta:acme") is required');
+  }
+  const atMs = importedAt == null
+    ? Date.now()
+    : (typeof importedAt === 'number' ? importedAt : Date.parse(importedAt));
+  if (!Number.isFinite(atMs)) throw new Error('roster import: importedAt is not a valid time');
+
+  const warnings: Record<string, any>[] = [];
+  const candidates: { principal: string; kid: string; publicKey: string; active: boolean }[] = [];
+  const usersByPrincipal = new Map();
+
+  for (const u of idpUsers) {
+    // A user without a stable id AND a userName cannot be diffed or revoked
+    // reliably later — excluded, never an approver.
+    if (!u || typeof u !== 'object'
+      || typeof u.id !== 'string' || !u.id
+      || typeof u.userName !== 'string' || !u.userName) {
+      warnings.push({ code: 'malformed_user', id: u?.id ?? null, userName: u?.userName ?? null });
+      continue;
+    }
+    const principal = u.userName;
+    usersByPrincipal.set(principal, (usersByPrincipal.get(principal) || 0) + 1);
+    const active = u.active === true; // strictly boolean true; anything else never pins
+    for (const k of Array.isArray(u.keys) ? u.keys : []) {
+      if (!k || typeof k.kid !== 'string' || !k.kid
+        || typeof k.publicKey !== 'string' || !k.publicKey) {
+        warnings.push({ code: 'malformed_key', principal, kid: k?.kid ?? null });
+        continue;
+      }
+      candidates.push({ principal, kid: k.kid, publicKey: k.publicKey, active });
+    }
+  }
+
+  // Two IdP users claiming one principal: identity is ambiguous — neither pins.
+  const contestedPrincipals = new Set();
+  for (const [principal, count] of usersByPrincipal) {
+    if (count > 1) {
+      contestedPrincipals.add(principal);
+      warnings.push({ code: 'duplicate_principal', principal, users: count });
+    }
+  }
+  let entries = candidates.filter((c) => !contestedPrincipals.has(c.principal));
+
+  // Exact-duplicate rows collapse silently (same principal + kid + key).
+  const seen = new Set();
+  entries = entries.filter((c) => {
+    const id = `${c.principal}\n${c.kid}\n${c.publicKey}`;
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+
+  // One kid claimed by two principals, or one kid carrying two key materials,
+  // is an integrity failure: the contested kid pins NOTHING for anyone.
+  const byKid = new Map();
+  for (const c of entries) {
+    const g = byKid.get(c.kid) || { principals: new Set(), keys: new Set() };
+    g.principals.add(c.principal);
+    g.keys.add(c.publicKey);
+    byKid.set(c.kid, g);
+  }
+  const contestedKids = new Set();
+  for (const [kid, g] of byKid) {
+    if (g.principals.size > 1 || g.keys.size > 1) {
+      contestedKids.add(kid);
+      warnings.push({ code: 'duplicate_kid', kid, principals: [...g.principals].sort() });
+    }
+  }
+  entries = entries.filter((c) => !contestedKids.has(c.kid));
+
+  // Mass-deprovision guard: a roster with zero active signers would, on apply,
+  // revoke EVERY approver. That is indistinguishable from a broken IdP export,
+  // so it requires the operator's explicit acknowledgment.
+  if (!allowEmpty && !entries.some((e) => e.active)) {
+    throw new Error('roster import: zero active signers (mass-deprovision guard) — pass allowEmpty:true to acknowledge revoking every approver');
+  }
+
+  entries.sort((a, b) => (a.principal < b.principal ? -1 : a.principal > b.principal ? 1
+    : a.kid < b.kid ? -1 : a.kid > b.kid ? 1 : 0));
+
+  return {
+    version: ROSTER_VERSION,
+    source,
+    imported_at: new Date(atMs).toISOString(),
+    signers: entries.map(({ principal, kid, publicKey, active }) => ({ principal, kid, publicKey, active })),
+    integrity_warnings: warnings,
+  };
+}
+
+/** A roster must be well-formed before it can drive a diff or a registry mutation. */
+function assertRoster(r, name) {
+  if (!r || r.version !== ROSTER_VERSION || !Array.isArray(r.signers)) {
+    throw new Error(`roster: ${name} is not an ${ROSTER_VERSION} roster`);
+  }
+  for (const s of r.signers) {
+    if (!s || typeof s.principal !== 'string' || !s.principal
+      || typeof s.kid !== 'string' || !s.kid
+      || typeof s.publicKey !== 'string' || !s.publicKey
+      || typeof s.active !== 'boolean') {
+      throw new Error(`roster: ${name} contains a malformed signer entry`);
+    }
+  }
+}
+
+function groupByPrincipal(roster) {
+  const m = new Map();
+  for (const s of roster.signers) {
+    const g = m.get(s.principal) || { kids: new Set(), active: false };
+    g.kids.add(s.kid);
+    if (s.active === true) g.active = true;
+    m.set(s.principal, g);
+  }
+  return m;
+}
+
+/**
+ * Diff two rosters at the principal level.
+ * `removed`/`deactivated` carry the PREVIOUS roster's kids — the revocation
+ * candidates; `added` carries the next roster's kids.
+ * @returns {{added:Array<{principal:string,kids:string[]}>, removed:Array<{principal:string,kids:string[]}>, deactivated:Array<{principal:string,kids:string[]}>}}
+ */
+export function diffRoster(previous, next) {
+  assertRoster(previous, 'previous');
+  assertRoster(next, 'next');
+  const prev = groupByPrincipal(previous);
+  const nxt = groupByPrincipal(next);
+  const added: { principal: string; kids: string[] }[] = [];
+  const removed: { principal: string; kids: string[] }[] = [];
+  const deactivated: { principal: string; kids: string[] }[] = [];
+  for (const [principal, g] of nxt) {
+    if (!prev.has(principal)) added.push({ principal, kids: [...g.kids].sort() });
+  }
+  for (const [principal, g] of prev) {
+    if (!nxt.has(principal)) { removed.push({ principal, kids: [...g.kids].sort() }); continue; }
+    if (g.active && !nxt.get(principal).active) deactivated.push({ principal, kids: [...g.kids].sort() });
+  }
+  const byPrincipal = (a, b) => (a.principal < b.principal ? -1 : a.principal > b.principal ? 1 : 0);
+  added.sort(byPrincipal); removed.sort(byPrincipal); deactivated.sort(byPrincipal);
+  return { added, removed, deactivated };
+}
+
+/**
+ * Reconcile a key registry (createKeyRegistry) against a roster:
+ *   - PIN each ACTIVE, uncontested signer's key not already present;
+ *   - REVOKE every registry kid not owned by an active roster signer — absent
+ *     or inactive means deprovisioned. The registry passed here must therefore
+ *     be DEDICATED to roster-managed approver keys.
+ * key-registry's API DOES express revocation (revoke(kid, at) — hard,
+ * fail-closed), so revocations are performed directly; `revoked` is the exact
+ * set performed, returned for the caller's evidence trail.
+ * A kid the registry has EVER revoked is never re-pinned (a rehire gets a new
+ * key; revoked key material stays dead).
+ * @param {object} roster    an EP-GATE-ROSTER-v1 roster
+ * @param {object} registry  createKeyRegistry() instance (add/revoke/status)
+ * @param {object} [o]
+ * @param {string|number} [o.revokedAt=roster.imported_at]  revocation timestamp
+ * @returns {{pinned:Array<{principal:string,kid:string}>, already_pinned:string[], revoked:Array<{kid:string,revoked_at:string|number,reason:string}>, refused:Array<{principal:string,kid:string,reason:string}>}}
+ */
+export function applyRosterToRegistry(roster, registry, { revokedAt }: { revokedAt?: string | number } = {}) {
+  assertRoster(roster, 'roster');
+  // Fail closed on the registry too: never coerce a flat key array here —
+  // asKeyRegistry would build a DETACHED registry and every revocation this
+  // function performs would be silently lost.
+  if (!registry || typeof registry.add !== 'function'
+    || typeof registry.revoke !== 'function' || typeof registry.status !== 'function') {
+    throw new Error('roster apply: registry must expose add/revoke/status (createKeyRegistry)');
+  }
+  const at = revokedAt ?? roster.imported_at;
+
+  // Recompute kid contests here as well — a hand-built roster must not bypass
+  // the import-time duplicate-kid integrity check.
+  const byKid = new Map();
+  for (const s of roster.signers) {
+    const g = byKid.get(s.kid) || { principals: new Set(), keys: new Set() };
+    g.principals.add(s.principal);
+    g.keys.add(s.publicKey);
+    byKid.set(s.kid, g);
+  }
+  const contested = new Set();
+  for (const [kid, g] of byKid) {
+    if (g.principals.size > 1 || g.keys.size > 1) contested.add(kid);
+  }
+
+  const activeByKid = new Map();
+  for (const s of roster.signers) {
+    if (s.active === true && !contested.has(s.kid)) activeByKid.set(s.kid, s);
+  }
+
+  const status = registry.status();
+  const everRevoked = new Set(status.filter((e) => e.revoked).map((e) => e.kid));
+  const present = new Set(status.map((e) => e.kid));
+
+  const pinned: { principal: string; kid: string }[] = [];
+  const alreadyPinned: string[] = [];
+  const revoked: { kid: string; revoked_at: string | number; reason: string }[] = [];
+  const refused: { principal: string; kid: string; reason: string }[] = [];
+
+  for (const s of roster.signers) {
+    if (s.active === true && contested.has(s.kid)) {
+      refused.push({ principal: s.principal, kid: s.kid, reason: 'contested_kid' });
+    }
+  }
+
+  for (const [kid, s] of activeByKid) {
+    if (everRevoked.has(kid)) {
+      refused.push({ principal: s.principal, kid, reason: 'kid_previously_revoked' });
+      continue;
+    }
+    if (present.has(kid)) { alreadyPinned.push(kid); continue; }
+    registry.add({ kid, key: s.publicKey });
+    pinned.push({ principal: s.principal, kid });
+  }
+
+  // Absent-or-inactive (and contested) kids stop being acceptable NOW.
+  const done = new Set();
+  for (const e of status) {
+    if (e.revoked || done.has(e.kid) || activeByKid.has(e.kid)) continue;
+    registry.revoke(e.kid, at);
+    done.add(e.kid);
+    revoked.push({ kid: e.kid, revoked_at: at, reason: contested.has(e.kid) ? 'contested_kid' : 'absent_or_inactive' });
+  }
+
+  return { pinned, already_pinned: alreadyPinned, revoked, refused };
+}
+
+export default { ROSTER_VERSION, importRoster, diffRoster, applyRosterToRegistry };

package/src/runtime-monitor.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Runtime bridge for the Gate lifecycle.
+ *
+ * This is deliberately an explicit, reviewable monitor rather than a claim
+ * that TLA+ can be mechanically compiled into JavaScript. Its transition
+ * table mirrors the load-bearing lifecycle invariants in
+ * formal/ep_handshake.tla: an effect follows authorization, consumption is
+ * one-way, and execution evidence follows the effect attempt. A divergence
+ * enters fail-closed safe mode; recovery requires an operator-supplied
+ * authorizer and never re-authorizes an old receipt.
+ */
+
+export const RUNTIME_MONITOR_VERSION = 'EP-GATE-RUNTIME-MONITOR-v1';
+export const RUNTIME_MONITOR_MODES = Object.freeze({
+  NORMAL: 'normal',
+  DEGRADED: 'degraded',
+  LOCKDOWN: 'lockdown',
+});
+
+export const RUNTIME_INVARIANTS = Object.freeze({
+  CONSUME_ONCE: 'ConsumeOnceSafety',
+  WRITE_BYPASS: 'WriteBypassSafety',
+  SIGNOFF_BINDING: 'SignoffBindingMatch',
+});
+
+const TIER_RANK = Object.freeze({ software: 0, class_a: 1, quorum: 2 });
+const SAFE_MODE_TIER = 'class_a';
+const MAX_EVENTS = 256;
+const MAX_CYCLES = 1024;
+
+function isPromiseLike(value) {
+  return value !== null
+    && (typeof value === 'object' || typeof value === 'function')
+    && typeof value.then === 'function';
+}
+
+function publicContext(context: { cycle_id?: any; action?: any; receipt_id?: any; phase?: any } = {}) {
+  return {
+    cycle_id: context.cycle_id ?? null,
+    action: typeof context.action === 'string' ? context.action : null,
+    receipt_id: typeof context.receipt_id === 'string' ? context.receipt_id : null,
+    phase: context.phase ?? null,
+  };
+}
+
+function copyEvent(event) {
+  return Object.freeze({ ...event, context: Object.freeze({ ...event.context }) });
+}
+
+/**
+ * Create a process-local monitor. Operators should export divergence events to
+ * durable SIEM/evidence storage through onDivergence; the monitor itself keeps
+ * only a bounded diagnostic buffer.
+ *
+ * @param {{ now?: (() => number) | number, onDivergence?: ((event: object) => any) | null, authorizeRecovery?: ((input: object) => boolean) | null }} [options]
+ */
+export function createRuntimeMonitor({
+  now = Date.now,
+  onDivergence = null,
+  authorizeRecovery = null,
+}: {
+  now?: (() => number) | number;
+  onDivergence?: ((event: object) => any) | null;
+  authorizeRecovery?: ((input: object) => boolean) | null;
+} = {}) {
+  let mode: typeof RUNTIME_MONITOR_MODES[keyof typeof RUNTIME_MONITOR_MODES] = RUNTIME_MONITOR_MODES.NORMAL;
+  let sequence = 0;
+  const cycles = new Map();
+  const events: any[] = [];
+
+  function timestamp() {
+    const value = typeof now === 'function' ? now() : now;
+    return new Date(Number(value)).toISOString();
+  }
+
+  function clockValue() {
+    return typeof now === 'function' ? now() : now;
+  }
+
+  function emitDivergence(cycle, theorem, expected, actual, severity = 'critical') {
+    const event = copyEvent({
+      version: RUNTIME_MONITOR_VERSION,
+      type: 'SPEC_DIVERGENCE',
+      at: timestamp(),
+      theorem,
+      expected,
+      actual,
+      severity,
+      context: publicContext({ ...cycle, phase: cycle?.phase }),
+    });
+    events.push(event);
+    if (events.length > MAX_EVENTS) events.shift();
+    mode = severity === 'critical' ? RUNTIME_MONITOR_MODES.LOCKDOWN : RUNTIME_MONITOR_MODES.DEGRADED;
+    if (typeof onDivergence === 'function') {
+      try {
+        const result = onDivergence(event);
+        if (isPromiseLike(result)) result.catch(() => {});
+      } catch { /* monitoring must not weaken the fail-closed transition */ }
+    }
+    return { ok: false, reason: `runtime_divergence:${theorem}`, event };
+  }
+
+  function fail(cycle, theorem, expected, actual, severity = 'critical') {
+    return emitDivergence(cycle, theorem, expected, actual, severity);
+  }
+
+  function transition(cycleId, event, details: {
+    allow?: boolean;
+    status?: number;
+    guarded?: boolean;
+    receipt_id?: string;
+    reason?: string;
+  } = {}) {
+    const cycle = cycles.get(cycleId);
+    if (!cycle) {
+      return fail({ cycle_id: cycleId, ...details }, RUNTIME_INVARIANTS.WRITE_BYPASS,
+        'known runtime cycle', 'unknown runtime cycle');
+    }
+    if (event === 'decision') {
+      if (cycle.phase !== 'checking') {
+        return fail(cycle, RUNTIME_INVARIANTS.WRITE_BYPASS, 'checking → decision', `${cycle.phase} → decision`);
+      }
+      if (details.allow === true && details.status !== 200) {
+        return fail(cycle, RUNTIME_INVARIANTS.WRITE_BYPASS, 'allow requires HTTP 200', `allow with ${details.status}`);
+      }
+      if (details.allow === true && details.guarded === true && !details.receipt_id) {
+        return fail(cycle, RUNTIME_INVARIANTS.SIGNOFF_BINDING, 'guarded allow has receipt_id', 'guarded allow without receipt_id');
+      }
+      cycle.phase = details.allow === true ? 'authorized' : 'refused';
+      cycle.allow = details.allow === true;
+      cycle.reason = details.reason ?? null;
+      return { ok: true };
+    }
+    const expected = {
+      effect_attempted: ['authorized'],
+      effect_returned: ['effect_attempted'],
+      effect_failed: ['effect_attempted', 'effect_returned'],
+      capability_refused: ['authorized'],
+      consumed: ['effect_returned', 'effect_failed'],
+      execution_recorded: ['consumed'],
+    }[event];
+    if (!expected || !expected.includes(cycle.phase)) {
+      const theorem = event === 'consumed'
+        ? RUNTIME_INVARIANTS.CONSUME_ONCE
+        : RUNTIME_INVARIANTS.WRITE_BYPASS;
+      return fail(cycle, theorem, `${expected?.join(' or ') || 'known event'} → ${event}`, `${cycle.phase} → ${event}`);
+    }
+    if (event === 'consumed' && cycle.consumed === true) {
+      return fail(cycle, RUNTIME_INVARIANTS.CONSUME_ONCE, 'consumed at most once', 'second consumption transition');
+    }
+    cycle.phase = event;
+    if (event === 'consumed') cycle.consumed = true;
+    if (event === 'execution_recorded') cycle.complete = true;
+    return { ok: true };
+  }
+
+  return {
+    version: RUNTIME_MONITOR_VERSION,
+    beginCheck({ action = null, receipt_id = null } = {}) {
+      const cycle_id = `rt_${Number(clockValue()).toString(36)}_${(++sequence).toString(36)}`;
+      cycles.set(cycle_id, { cycle_id, action, receipt_id, phase: 'checking', consumed: false });
+      while (cycles.size > MAX_CYCLES) cycles.delete(cycles.keys().next().value);
+      return cycle_id;
+    },
+    preflight({ hasReceipt }: { hasReceipt?: boolean } = {}) {
+      if (mode === RUNTIME_MONITOR_MODES.NORMAL || hasReceipt === true) return { ok: true };
+      return { ok: false, reason: 'runtime_safe_mode_signoff_required', mode };
+    },
+    minimumAssuranceTier(declaredTier) {
+      if (mode === RUNTIME_MONITOR_MODES.NORMAL || declaredTier === undefined || declaredTier === null) return declaredTier;
+      return (TIER_RANK[declaredTier] ?? 0) < TIER_RANK[SAFE_MODE_TIER] ? SAFE_MODE_TIER : declaredTier;
+    },
+    recordDecision(cycleId, details) {
+      return transition(cycleId, 'decision', details);
+    },
+    beginExecution(cycleId, authorization) {
+      if (!authorization || authorization.allow !== true || isPromiseLike(authorization)) {
+        const cycle = cycles.get(cycleId) || { cycle_id: cycleId };
+        return fail(cycle, RUNTIME_INVARIANTS.WRITE_BYPASS, 'resolved allow authorization', 'missing or promise authorization');
+      }
+      return transition(cycleId, 'effect_attempted');
+    },
+    effectReturned(cycleId) { return transition(cycleId, 'effect_returned'); },
+    effectFailed(cycleId) { return transition(cycleId, 'effect_failed'); },
+    capabilityRefused(cycleId) { return transition(cycleId, 'capability_refused'); },
+    consumptionCommitted(cycleId) { return transition(cycleId, 'consumed'); },
+    executionRecorded(cycleId) { return transition(cycleId, 'execution_recorded'); },
+    executionSkipped(cycleId) {
+      const cycle = cycles.get(cycleId);
+      if (!cycle || cycle.phase !== 'consumed') {
+        return fail(cycle || { cycle_id: cycleId }, RUNTIME_INVARIANTS.WRITE_BYPASS,
+          'consumed → execution skipped', `${cycle?.phase || 'unknown'} → execution skipped`);
+      }
+      cycle.phase = 'complete';
+      cycle.complete = true;
+      return { ok: true };
+    },
+    getMode() { return mode; },
+    getEvents() { return events.map(copyEvent); },
+    getState(cycleId) {
+      const cycle = cycles.get(cycleId);
+      return cycle ? Object.freeze({ ...cycle }) : null;
+    },
+    recover(input = {}) {
+      if (mode === RUNTIME_MONITOR_MODES.NORMAL) return { ok: true, mode };
+      if (typeof authorizeRecovery !== 'function' || authorizeRecovery(input) !== true) {
+        return { ok: false, reason: 'runtime_recovery_authorization_required', mode };
+      }
+      mode = RUNTIME_MONITOR_MODES.NORMAL;
+      return { ok: true, mode };
+    },
+  };
+}
+
+export default { createRuntimeMonitor, RUNTIME_MONITOR_VERSION, RUNTIME_MONITOR_MODES, RUNTIME_INVARIANTS };