@emilia-protocol/gate 0.8.0 → 0.9.1

package/reports/underwriter.js

@@ -0,0 +1,340 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — underwriter control attestation (AI-liability loss-run analogue).
+ *
+ * The artifact an AI-liability underwriter prices premium credit against — the
+ * MFA-for-cyber analogue: evidence that a deny-by-default authorization control
+ * was IN FORCE and OPERATING over the policy period, computed from the gate's
+ * tamper-evident evidence log. Pure function: same entries + same options in,
+ * identical JSON out (pin `now` for a byte-stable artifact).
+ *
+ * HONESTY BOUNDARY (carried inside the artifact): this attests CONTROL
+ * OPERATION only. It does not attest the business correctness of any authorized
+ * action, and it is not an insurance document until adopted by the carrier.
+ * Near-miss / remediation narrative belongs to the broker — the builder emits
+ * those fields as null and NEVER fabricates prose.
+ *
+ * Fail closed: a missing insured or an invalid period is an error, not a guess.
+ * Entries that cannot be verified as log records (unparseable time, missing
+ * hash, unknown kind, decision without an allow verdict) are EXCLUDED from every
+ * attested count and surfaced as integrity_warnings — the attestation never
+ * counts what it cannot account for. A zero-activity period is a valid (boring)
+ * attestation, not an error.
+ */
+
+export const UNDERWRITER_ATTESTATION_VERSION = 'EP-GATE-UNDERWRITER-ATTESTATION-v1';
+
+// The gate's assurance vocabulary. `software` is the single-approver baseline;
+// the distribution always carries all three so an underwriter can see zeros.
+const KNOWN_TIERS = ['class_a', 'quorum', 'software'];
+
+function toMs(t) {
+  if (t == null) return null;
+  const ms = typeof t === 'number' ? t : Date.parse(t);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/** Deterministic object from a Map: keys sorted, never insertion-ordered. */
+function sortedObject(map) {
+  const out = {};
+  for (const k of [...map.keys()].sort()) out[k] = map.get(k);
+  return out;
+}
+
+function countBy(items, keyFn) {
+  const m = new Map();
+  for (const it of items) {
+    const k = keyFn(it);
+    m.set(k, (m.get(k) || 0) + 1);
+  }
+  return m;
+}
+
+/** Tier histogram seeded with the known tiers so zeros are explicit. */
+function tierDistribution(values) {
+  const m = new Map(KNOWN_TIERS.map((t) => [t, 0]));
+  for (const v of values) {
+    const k = typeof v === 'string' && v.length ? v : 'unspecified';
+    m.set(k, (m.get(k) || 0) + 1);
+  }
+  return sortedObject(m);
+}
+
+/** Action family = the namespace segment ('payment.release' -> 'payment'). */
+function actionFamily(action) {
+  if (typeof action !== 'string' || action.length === 0) return 'unknown';
+  const dot = action.indexOf('.');
+  return dot > 0 ? action.slice(0, dot) : action;
+}
+
+/**
+ * Build the underwriter attestation over a slice of the evidence log.
+ * @param {Array<object>} entries  evidence.all() (or a durable export of it)
+ * @param {object} o
+ * @param {string} o.insured           named insured (required)
+ * @param {string} [o.policyRef]       carrier policy/submission reference (null until bound)
+ * @param {string|number} o.periodStart  inclusive period start (ISO or epoch ms)
+ * @param {string|number} o.periodEnd    inclusive period end (ISO or epoch ms)
+ * @param {number|function} [o.now]    clock for generated_at (pin for determinism)
+ * @returns {object} EP-GATE-UNDERWRITER-ATTESTATION-v1 document
+ */
+export function buildUnderwriterAttestation(entries = [], {
+  insured, policyRef = null, periodStart, periodEnd, now = Date.now,
+} = {}) {
+  if (!insured || typeof insured !== 'string') {
+    throw new Error('underwriter attestation: insured (named insured) is required');
+  }
+  const startMs = toMs(periodStart);
+  const endMs = toMs(periodEnd);
+  if (startMs == null || endMs == null) {
+    throw new Error('underwriter attestation: periodStart and periodEnd must be valid ISO strings or epoch ms');
+  }
+  if (startMs > endMs) {
+    throw new Error('underwriter attestation: periodStart must not be after periodEnd');
+  }
+  if (!Array.isArray(entries)) {
+    throw new Error('underwriter attestation: entries must be an array (evidence.all())');
+  }
+
+  // Scope + integrity pass. Out-of-window records are simply out of scope;
+  // records we cannot verify as log entries are warned AND excluded — never
+  // attested over. Exclusion is the conservative direction for premium credit.
+  const warnings = [];
+  const inScope = [];
+  entries.forEach((e, index) => {
+    const ref = { index, seq: e && typeof e === 'object' && Number.isInteger(e.seq) ? e.seq : null };
+    if (!e || typeof e !== 'object') { warnings.push({ ...ref, reason: 'not_an_object' }); return; }
+    const t = toMs(e.at);
+    if (t == null) { warnings.push({ ...ref, reason: 'unparseable_at' }); return; }
+    if (t < startMs || t > endMs) return;
+    if (typeof e.hash !== 'string' || e.hash.length === 0) { warnings.push({ ...ref, reason: 'missing_hash' }); return; }
+    if (e.kind !== 'decision' && e.kind !== 'execution') { warnings.push({ ...ref, reason: 'unknown_kind' }); return; }
+    if (e.kind === 'decision' && typeof e.allow !== 'boolean') { warnings.push({ ...ref, reason: 'decision_missing_allow' }); return; }
+    inScope.push({ entry: e, t });
+  });
+
+  const decisions = inScope.filter((x) => x.entry.kind === 'decision');
+  const executions = inScope.filter((x) => x.entry.kind === 'execution').map((x) => x.entry);
+
+  // 'not_guarded' pass-throughs ran WITHOUT the control — they are the
+  // uncontrolled surface, reported separately from protected-action volume.
+  const uncontrolled = decisions.filter((x) => x.entry.reason === 'not_guarded').map((x) => x.entry);
+  const guarded = decisions.filter((x) => x.entry.reason !== 'not_guarded');
+  const guardedAllows = guarded.filter((x) => x.entry.allow === true).map((x) => x.entry);
+  const denies = guarded.filter((x) => x.entry.allow === false).map((x) => x.entry);
+
+  const families = new Map();
+  for (const { entry: d } of guarded) {
+    const fam = actionFamily(d.action);
+    const f = families.get(fam) || { decisions: 0, allowed: 0, denied: 0 };
+    f.decisions += 1;
+    if (d.allow) f.allowed += 1; else f.denied += 1;
+    families.set(fam, f);
+  }
+
+  const reasons = sortedObject(countBy(denies, (d) => String(d.reason ?? 'unspecified')));
+  const replayBlocked = denies.filter((d) => d.reason === 'replay_refused').length;
+
+  // Hard actions = quorum required by the manifest, per the recorded decision.
+  const hard = guarded.filter((x) => x.entry.required_tier === 'quorum');
+  const hardAllowed = hard.filter((x) => x.entry.allow === true).length;
+
+  // Replay defense bypassed = the gate authorized with consumptionMode 'none'
+  // (one-time consumption explicitly skipped). An underwriter must see this.
+  const replayBypassed = guardedAllows.filter((a) => a.consumption_mode === 'none').length;
+
+  let firstAt = null; let lastAt = null;
+  for (const { entry: d, t } of decisions) {
+    if (firstAt === null || t < firstAt.t) firstAt = { t, at: d.at };
+    if (lastAt === null || t > lastAt.t) lastAt = { t, at: d.at };
+  }
+
+  const nowMs = typeof now === 'function' ? now() : now;
+
+  return {
+    '@version': UNDERWRITER_ATTESTATION_VERSION,
+    product: 'EMILIA Gate',
+    generated_at: new Date(nowMs).toISOString(),
+    insured,
+    policy_ref: policyRef ?? null,
+    period: { start: new Date(startMs).toISOString(), end: new Date(endMs).toISOString() },
+    honesty: {
+      attests: 'Operation of a deny-by-default authorization control (EMILIA Gate) over the stated period, computed from the gate\'s tamper-evident evidence log.',
+      does_not_attest: [
+        'The business correctness or wisdom of any authorized action.',
+        'Identity proofing, authority enrollment, or issuer/approver key custody, which remain external trust roots.',
+        'Any period, system, or enforcement point outside the supplied evidence log.',
+      ],
+      status: 'Not an insurance document. This attestation carries no coverage effect until adopted by the carrier.',
+    },
+    control_in_force: {
+      control: 'EMILIA Gate — Trusted Action Firewall',
+      mode: 'deny_by_default',
+      statement: 'Guarded actions execute only with a valid, in-scope, sufficiently-assured, fresh, one-time authorization receipt; absent or insufficient proof is refused, and every decision is appended to a hash-chained evidence log.',
+      guarded_decisions: guarded.length,
+      first_decision_at: firstAt?.at ?? null,
+      last_decision_at: lastAt?.at ?? null,
+    },
+    volume: {
+      guarded_decisions: guarded.length,
+      allowed: guardedAllows.length,
+      denied: denies.length,
+      by_action_family: sortedObject(families),
+    },
+    denials: {
+      total: denies.length,
+      // 0/0 is 'no guarded activity', not a 0% denial rate — represent as null.
+      rate: guarded.length === 0 ? null : denies.length / guarded.length,
+      reasons,
+    },
+    replay: { attempts_blocked: replayBlocked },
+    assurance: {
+      required_tier_distribution: tierDistribution(guarded.map((x) => x.entry.required_tier)),
+      credited_tier_distribution_on_allow: tierDistribution(guardedAllows.map((a) => a.have_tier)),
+    },
+    quorum_usage: {
+      hard_action_decisions: hard.length,
+      allowed: hardAllowed,
+      denied: hard.length - hardAllowed,
+    },
+    exceptions: {
+      uncontrolled_passthroughs: uncontrolled.length,
+      uncontrolled_actions: [...new Set(uncontrolled.map((d) => (typeof d.action === 'string' && d.action) || 'unknown'))].sort(),
+      replay_defense_bypassed: replayBypassed,
+    },
+    executions: {
+      recorded: executions.length,
+      executed: executions.filter((x) => x.outcome === 'executed').length,
+      failed: executions.filter((x) => x.outcome === 'failed').length,
+    },
+    // Broker fields. NEVER machine-generated — the builder only ever emits null.
+    narrative: { near_misses: null, remediation: null, completed_by: 'broker' },
+    evidence: {
+      log_entries_supplied: entries.length,
+      in_scope: inScope.length,
+      first_hash: inScope[0]?.entry.hash ?? null,
+      last_hash: inScope[inScope.length - 1]?.entry.hash ?? null,
+      integrity_warnings: warnings,
+    },
+  };
+}
+
+/* ------------------------------- markdown ------------------------------- */
+
+/** Table cells must not break the table; the source strings are log-derived. */
+function cell(v) {
+  return String(v ?? '—').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
+function pct(rate) {
+  return rate == null ? 'n/a' : `${(rate * 100).toFixed(2)}%`;
+}
+
+function countTable(header, obj) {
+  const keys = Object.keys(obj);
+  if (keys.length === 0) return ['_None in period._'];
+  return [
+    `| ${header} | Count |`,
+    '|---|---:|',
+    ...keys.map((k) => `| ${cell(k)} | ${obj[k]} |`),
+  ];
+}
+
+const BROKER_PLACEHOLDER = '_(left to the broker — not machine-generated)_';
+
+/**
+ * Render the attestation for a submission packet. Refuses any document that is
+ * not an EP-GATE-UNDERWRITER-ATTESTATION-v1 — never renders what it cannot
+ * vouch the shape of. Narrative fields render exactly as present in the pack
+ * (the broker fills them into the JSON); null renders as a placeholder.
+ */
+export function renderMarkdown(pack) {
+  if (!pack || typeof pack !== 'object' || pack['@version'] !== UNDERWRITER_ATTESTATION_VERSION) {
+    throw new Error(`renderMarkdown requires an ${UNDERWRITER_ATTESTATION_VERSION} document`);
+  }
+  const fams = pack.volume.by_action_family;
+  const famKeys = Object.keys(fams);
+  const req = pack.assurance.required_tier_distribution;
+  const cred = pack.assurance.credited_tier_distribution_on_allow;
+  const tierKeys = [...new Set([...Object.keys(req), ...Object.keys(cred)])].sort();
+  const warnings = pack.evidence.integrity_warnings;
+
+  const lines = [
+    '# Underwriter Control Attestation — EMILIA Gate',
+    '',
+    `\`${UNDERWRITER_ATTESTATION_VERSION}\` · generated ${pack.generated_at}`,
+    '',
+    `**Insured:** ${cell(pack.insured)} · **Policy:** ${cell(pack.policy_ref)} · **Period:** ${pack.period.start} → ${pack.period.end}`,
+    '',
+    `> **Attests:** ${pack.honesty.attests}`,
+    `> **Does not attest:** ${pack.honesty.does_not_attest.join(' ')}`,
+    `> **Status:** ${pack.honesty.status}`,
+    '',
+    '## Control in force',
+    '',
+    `- Control: ${pack.control_in_force.control} (${pack.control_in_force.mode})`,
+    `- ${pack.control_in_force.statement}`,
+    `- Guarded decisions in period: ${pack.control_in_force.guarded_decisions}`
+      + (pack.control_in_force.first_decision_at
+        ? ` (first ${pack.control_in_force.first_decision_at}, last ${pack.control_in_force.last_decision_at})`
+        : ''),
+    '',
+    '## Protected-action volume',
+    '',
+    ...(famKeys.length === 0
+      ? ['_No guarded decisions in the period._']
+      : [
+        '| Action family | Decisions | Allowed | Denied |',
+        '|---|---:|---:|---:|',
+        ...famKeys.map((k) => `| ${cell(k)} | ${fams[k].decisions} | ${fams[k].allowed} | ${fams[k].denied} |`),
+      ]),
+    '',
+    '## Denials',
+    '',
+    `- Denials: ${pack.denials.total} of ${pack.volume.guarded_decisions} guarded decisions (${pct(pack.denials.rate)})`,
+    '',
+    ...countTable('Denial reason', pack.denials.reasons),
+    '',
+    '## Replay defense',
+    '',
+    `- Replay attempts blocked: ${pack.replay.attempts_blocked}`,
+    '',
+    '## Assurance tiers',
+    '',
+    '| Tier | Required (guarded) | Credited (allowed) |',
+    '|---|---:|---:|',
+    ...tierKeys.map((t) => `| ${cell(t)} | ${req[t] ?? 0} | ${cred[t] ?? 0} |`),
+    '',
+    '## Quorum usage on hard actions',
+    '',
+    `- Decisions requiring quorum: ${pack.quorum_usage.hard_action_decisions} (allowed ${pack.quorum_usage.allowed}, denied ${pack.quorum_usage.denied})`,
+    '',
+    '## Exceptions / uncontrolled actions',
+    '',
+    `- Uncontrolled pass-throughs (not guarded by manifest): ${pack.exceptions.uncontrolled_passthroughs}`,
+    `- Uncontrolled actions: ${pack.exceptions.uncontrolled_actions.length ? pack.exceptions.uncontrolled_actions.map(cell).join(', ') : '—'}`,
+    `- Replay defense bypassed (consumption mode "none"): ${pack.exceptions.replay_defense_bypassed}`,
+    '',
+    '## Executions',
+    '',
+    `- Recorded: ${pack.executions.recorded} (executed ${pack.executions.executed}, failed ${pack.executions.failed})`,
+    '',
+    '## Near-miss narrative (broker)',
+    '',
+    `- Near misses: ${pack.narrative.near_misses == null ? BROKER_PLACEHOLDER : cell(pack.narrative.near_misses)}`,
+    `- Remediation: ${pack.narrative.remediation == null ? BROKER_PLACEHOLDER : cell(pack.narrative.remediation)}`,
+    '',
+    '## Evidence basis',
+    '',
+    `- Log entries supplied: ${pack.evidence.log_entries_supplied} · in scope: ${pack.evidence.in_scope}`,
+    `- First hash: ${cell(pack.evidence.first_hash)} · Last hash: ${cell(pack.evidence.last_hash)}`,
+    `- Integrity warnings: ${warnings.length}`,
+    ...(warnings.length
+      ? warnings.map((w) => `  - index ${w.index}${w.seq != null ? ` (seq ${w.seq})` : ''}: ${cell(w.reason)}`)
+      : []),
+    '',
+  ];
+  return lines.join('\n');
+}
+
+export default { UNDERWRITER_ATTESTATION_VERSION, buildUnderwriterAttestation, renderMarkdown };

package/roster.js

@@ -0,0 +1,265 @@
+// 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 } = {}) {
+  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 = [];
+  const candidates = [];
+  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 = [];
+  const removed = [];
+  const deactivated = [];
+  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 } = {}) {
+  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 = [];
+  const alreadyPinned = [];
+  const revoked = [];
+  const refused = [];
+
+  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 };