@emilia-protocol/gate 0.9.5 → 0.11.0

package/breakglass.js

@@ -25,12 +25,11 @@
  *   - LOGGED     — `buildBreakGlassEvidence` shapes a kind:'breakglass' entry
  *                  for the tamper-evident evidence log.
  *
- * THE MODULE'S CONTRACT: NO EVIDENCE ENTRY, NO OVERRIDE. Callers MUST append
- * the break-glass evidence entry via a strict evidence log
- * (createEvidenceLog({ strict: true })) and see record() succeed BEFORE
- * executing the overridden action. If the entry cannot be durably recorded,
- * the override MUST NOT run — the whole point of break-glass-as-evidence is
- * that an unaccounted emergency action is indistinguishable from an attack.
+ * THE MODULE'S EXECUTION CONTRACT: use `runBreakGlass`. It is the one high-level
+ * path that enforces pinned-policy verification, permanent fleet-safe
+ * consumption, strict evidence acknowledgement, and only then effect invocation.
+ * The lower-level verify/consume/evidence helpers are composable primitives; no
+ * one of them alone authorizes or executes an override.
  *
  * Verification FAILS CLOSED with machine-readable reasons: threshold unmet,
  * non-distinct signer kids, expired, not-yet-valid, out-of-scope action_type,
@@ -42,6 +41,10 @@
  * from the wall clock implicitly, so verification is deterministic.
  */
 import crypto from 'node:crypto';
+import { strictJsonGate } from './strict-json.js';
+import { canonicalize as canonical } from './execution-binding.js';
+import { verifyEvidenceRecord } from './evidence.js';
+import { isSecureConsumptionStore } from './store.js';
 
 export const BREAKGLASS_VERSION = 'EP-GATE-BREAKGLASS-v1';
 export const BREAKGLASS_EVIDENCE_KIND = 'breakglass';
@@ -50,16 +53,6 @@ function sha256hex(s) {
   return crypto.createHash('sha256').update(s).digest('hex');
 }
 
-/** Canonical JSON (recursive sorted keys) — matches @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);
@@ -83,7 +76,8 @@ function isActionTypeList(a) {
  * Mint a break-glass authorization: every signer signs the canonical JSON of
  * the SAME grant payload. Throws on invalid fields — a malformed grant must
  * never be issued, only refused. Signer kids must already be distinct at mint
- * time: one principal can never pre-fill two threshold slots.
+ * time: one key can never pre-fill two threshold slots. Relying-party principal
+ * uniqueness is enforced at verification through the pinned policy roster.
  *
  * grant_id is CONTENT-DERIVED (sha-256 of the canonical grant fields), so the
  * id is deterministic and re-minting the identical grant yields the identical
@@ -109,11 +103,25 @@ export function mintBreakGlassAuthorization(signers, {
   if (new Set(kids).size !== kids.length) {
     throw new Error('breakglass: signer kids must be distinct — one principal cannot fill two threshold slots');
   }
+  let signerFingerprints;
+  try {
+    signerFingerprints = signers.map((s) => {
+      const publicKey = crypto.createPublicKey(s.privateKey);
+      if (publicKey.asymmetricKeyType !== 'ed25519') throw new Error('not Ed25519');
+      const spki = publicKey.export({ type: 'spki', format: 'der' });
+      return sha256hex(spki);
+    });
+  } catch {
+    throw new Error('breakglass: every signer privateKey must be an Ed25519 key');
+  }
+  if (new Set(signerFingerprints).size !== signerFingerprints.length) {
+    throw new Error('breakglass: signer SPKI keys must be distinct — one key cannot fill two threshold slots');
+  }
   if (!scope || !isActionTypeList(scope.action_types)) {
     throw new Error('breakglass: scope.action_types must be a non-empty array of action-type strings');
   }
-  if (!Number.isInteger(threshold) || threshold < 1) {
-    throw new Error('breakglass: threshold must be an integer >= 1');
+  if (!Number.isInteger(threshold) || threshold < 2) {
+    throw new Error('breakglass: threshold must be an integer >= 2');
   }
   if (threshold > signers.length) {
     throw new Error(`breakglass: threshold ${threshold} exceeds signer count ${signers.length} — the grant could never verify`);
@@ -157,37 +165,103 @@ function issuerKeyFor(issuerKeys, kid) {
   return typeof k === 'string' ? k : null;
 }
 
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function pinnedKey(key) {
+  if (typeof key !== 'string' || !/^[A-Za-z0-9_-]+$/.test(key)) {
+    throw new Error('invalid pinned key encoding');
+  }
+  const bytes = Buffer.from(key, 'base64url');
+  if (bytes.length === 0 || bytes.toString('base64url') !== key) {
+    throw new Error('non-canonical pinned key encoding');
+  }
+  const publicKey = crypto.createPublicKey({ key: bytes, format: 'der', type: 'spki' });
+  if (publicKey.asymmetricKeyType !== 'ed25519') throw new Error('pinned key is not Ed25519');
+  const canonicalSpki = publicKey.export({ type: 'spki', format: 'der' });
+  return {
+    publicKey,
+    fingerprint: `sha256:${sha256hex(canonicalSpki)}`,
+  };
+}
+
+/** Normalize the relying-party trust policy; presenter material is never used. */
+function normalizePinnedPolicy(policy, issuerKeys) {
+  if (!isPlainObject(policy)) return { ok: false, reason: 'missing_policy' };
+  if (!Number.isSafeInteger(policy.minimum_threshold) || policy.minimum_threshold < 2
+      || !Array.isArray(policy.roster)) {
+    return { ok: false, reason: 'invalid_policy' };
+  }
+
+  try {
+    const roster = new Map();
+    for (const entry of policy.roster) {
+      if (!isPlainObject(entry) || !isNonEmptyString(entry.kid)
+          || !isNonEmptyString(entry.principal_id) || roster.has(entry.kid)) {
+        return { ok: false, reason: 'invalid_policy' };
+      }
+      const key = isNonEmptyString(entry.key) ? entry.key : issuerKeyFor(issuerKeys, entry.kid);
+      const keyInfo = pinnedKey(key);
+      roster.set(entry.kid, {
+        kid: entry.kid,
+        principal_id: entry.principal_id,
+        ...keyInfo,
+      });
+    }
+    const members = [...roster.values()];
+    if (new Set(members.map((entry) => entry.principal_id)).size < policy.minimum_threshold
+        || new Set(members.map((entry) => entry.fingerprint)).size < policy.minimum_threshold) {
+      return { ok: false, reason: 'invalid_policy' };
+    }
+    return {
+      ok: true,
+      minimum_threshold: policy.minimum_threshold,
+      roster,
+    };
+  } catch {
+    return { ok: false, reason: 'invalid_policy' };
+  }
+}
+
 /**
- * Verify a break-glass grant against pinned issuer keys. NEVER throws for a
+ * Verify a break-glass grant against a relying-party-pinned policy. NEVER throws for a
  * bad artifact — every failure resolves to { valid:false, reason } so the
  * refusal itself is loggable. FAILS CLOSED on every path:
  *   no_grant | grant_unparseable | grant_malformed | unsupported_version |
  *   unsupported_algorithm | invalid_threshold | invalid_scope |
- *   missing_reason | missing_incident_ref | duplicate_signer |
- *   threshold_unmet | unknown_kid | bad_signature |
+ *   missing_reason | missing_incident_ref | missing_policy | invalid_policy |
+ *   duplicate_signer | duplicate_signer_principal | duplicate_signer_key |
+ *   policy_threshold_unmet | threshold_unmet | signer_not_in_roster | bad_signature |
  *   invalid_validity_window | not_yet_valid | expired |
  *   action_type_required | out_of_scope
  *
- * A grant can never nominate its own keys: every signature's kid must resolve
- * to a PINNED key, and EVERY listed signature must verify — one tampered or
- * unknown signature refuses the whole grant. The validity window is checked
+ * A grant can never nominate its own threshold, roster, identities, or keys.
+ * EVERY listed signature must verify against its pinned roster entry — one
+ * tampered or unrostered signature refuses the whole grant. The validity window is checked
  * only AFTER the signatures, so the timestamps themselves are authenticated.
  *
  * @param {object|string|null} grantJson the artifact (object or JSON string)
  * @param {object} o
- * @param {object|Array<{kid:string,key:string}>} o.issuerKeys pinned kid -> base64url SPKI-DER public key
+ * @param {{minimum_threshold:number,roster:Array<{kid:string,principal_id:string,key?:string}>}} o.policy relying-party policy
+ * @param {object|Array<{kid:string,key:string}>} [o.issuerKeys] optional pinned keys when roster entries omit key
  * @param {number|string|function} [o.now=Date.now] injected clock (ms, ISO, or () => ms)
  * @param {string} o.actionType the action the caller wants to override — REQUIRED (scope cannot be checked without it)
  * @returns {{ valid: boolean, reason: string, grant_id?: string, incident_ref?: string, scope?: object, window?: object, threshold?: number, signer_kids?: string[] }}
  */
-export function verifyBreakGlass(grantJson, { issuerKeys, now = Date.now, actionType } = {}) {
+function verifyBreakGlassInternal(grantJson, { policy, issuerKeys, now = Date.now, actionType } = {}) {
   if (grantJson == null || grantJson === '') return refuse('no_grant');
 
   let doc = grantJson;
   if (typeof doc === 'string') {
-    try { doc = JSON.parse(doc); } catch { return refuse('grant_unparseable'); }
+    try {
+      if (Buffer.byteLength(doc, 'utf8') > 1024 * 1024 || !strictJsonGate(doc).ok) return refuse('grant_unparseable');
+      doc = JSON.parse(doc);
+    } catch { return refuse('grant_unparseable'); }
   }
-  if (!doc || typeof doc !== 'object') return refuse('grant_malformed');
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return refuse('grant_malformed');
   if (doc['@version'] !== BREAKGLASS_VERSION) return refuse('unsupported_version');
 
   const p = doc.payload;
@@ -202,6 +276,9 @@ export function verifyBreakGlass(grantJson, { issuerKeys, now = Date.now, action
   if (!isNonEmptyString(p.reason)) return refuse('missing_reason');
   if (!isNonEmptyString(p.incident_ref)) return refuse('missing_incident_ref');
 
+  const pinned = normalizePinnedPolicy(policy, issuerKeys);
+  if (!pinned.ok) return refuse(pinned.reason);
+
   for (const s of sigs) {
     if (!s || typeof s !== 'object' || !isNonEmptyString(s.kid) || typeof s.value !== 'string') {
       return refuse('grant_malformed');
@@ -209,33 +286,57 @@ export function verifyBreakGlass(grantJson, { issuerKeys, now = Date.now, action
     if (s.algorithm !== 'Ed25519') return refuse('unsupported_algorithm', { kid: s.kid });
   }
 
-  // Distinct principals: one kid may fill exactly one threshold slot.
+  // Distinct roster slots, pinned human principals, and canonical SPKI keys are
+  // independent predicates. Aliases cannot satisfy separation of duties.
   const kids = sigs.map((s) => s.kid);
   if (new Set(kids).size !== kids.length) {
     const dup = kids.find((k, i) => kids.indexOf(k) !== i);
     return refuse('duplicate_signer', { kid: dup });
   }
+  const signerEntries = [];
+  for (const kid of kids) {
+    const entry = pinned.roster.get(kid);
+    if (!entry) return refuse('signer_not_in_roster', { kid });
+    signerEntries.push(entry);
+  }
+  const principalIds = signerEntries.map((entry) => entry.principal_id);
+  if (new Set(principalIds).size !== principalIds.length) {
+    const principalId = principalIds.find((id, i) => principalIds.indexOf(id) !== i);
+    return refuse('duplicate_signer_principal', { principal_id: principalId });
+  }
+  const fingerprints = signerEntries.map((entry) => entry.fingerprint);
+  if (new Set(fingerprints).size !== fingerprints.length) {
+    const fingerprint = fingerprints.find((value, i) => fingerprints.indexOf(value) !== i);
+    return refuse('duplicate_signer_key', { spki_fingerprint: fingerprint });
+  }
   if (sigs.length < p.threshold) {
     return refuse('threshold_unmet', { threshold: p.threshold, signatures: sigs.length });
   }
+  if (sigs.length < pinned.minimum_threshold) {
+    return refuse('policy_threshold_unmet', {
+      required_threshold: pinned.minimum_threshold,
+      presented_threshold: p.threshold,
+      signatures: sigs.length,
+    });
+  }
 
-  // Every listed signature must verify against a PINNED key. One unknown kid
-  // or one bad signature refuses the whole grant — never count past a failure.
-  const msg = Buffer.from(canonical(p), 'utf8');
-  for (const s of sigs) {
-    const keyB64 = issuerKeyFor(issuerKeys, s.kid);
-    if (!keyB64) return refuse('unknown_kid', { kid: s.kid });
-    let ok = false;
+  // Every listed signature must verify against its pinned roster key. Never
+  // count past one failure.
+  let msg;
+  try { msg = Buffer.from(canonical(p), 'utf8'); } catch { return refuse('grant_malformed'); }
+  for (let i = 0; i < sigs.length; i++) {
+    const s = sigs[i];
+    let ok;
     try {
-      const pub = crypto.createPublicKey({ key: Buffer.from(keyB64, 'base64url'), format: 'der', type: 'spki' });
-      ok = crypto.verify(null, msg, pub, Buffer.from(s.value, 'base64url'));
-    } catch { ok = false; }
-    if (!ok) return refuse('bad_signature', { kid: s.kid });
+      ok = crypto.verify(null, msg, signerEntries[i].publicKey, Buffer.from(s.value, 'base64url'));
+    } catch { return refuse('bad_signature', { kid: s.kid }); }
+    if (ok !== true) return refuse('bad_signature', { kid: s.kid });
   }
 
   // Validity window — checked only AFTER the signatures, so the timestamps
   // themselves are authenticated. Both bounds are required; unparseable fails closed.
-  const nowMs = typeof now === 'function' ? now() : toMs(now);
+  let nowMs;
+  try { nowMs = typeof now === 'function' ? toMs(now()) : toMs(now); } catch { nowMs = null; }
   const nbf = toMs(p.window?.not_before);
   const exp = toMs(p.window?.expires_at);
   if (nbf == null || exp == null || nowMs == null) return refuse('invalid_validity_window');
@@ -256,10 +357,18 @@ export function verifyBreakGlass(grantJson, { issuerKeys, now = Date.now, action
     scope: { action_types: p.scope.action_types.slice() },
     window: { not_before: p.window.not_before, expires_at: p.window.expires_at },
     threshold: p.threshold,
+    required_threshold: Math.max(p.threshold, pinned.minimum_threshold),
+    policy_minimum_threshold: pinned.minimum_threshold,
     signer_kids: kids.slice(),
+    signer_principal_ids: principalIds.slice(),
+    signer_spki_fingerprints: fingerprints.slice(),
   };
 }
 
+export function verifyBreakGlass(grantJson, options = {}) {
+  try { return verifyBreakGlassInternal(grantJson, options); } catch { return refuse('grant_malformed'); }
+}
+
 /**
  * SINGLE-USE consumption via the consumption-store contract (store.js):
  * `consume(key)` returns true the FIRST time, false on every replay, and marks
@@ -269,7 +378,8 @@ export function verifyBreakGlass(grantJson, { issuerKeys, now = Date.now, action
  *
  * Accepts the grant document ({ payload: { grant_id } }) or a verified result
  * ({ grant_id }). NEVER throws — a missing store, missing grant_id, or a store
- * error all refuse with a machine-readable reason.
+ * error all refuse with a machine-readable reason. This is a low-level primitive;
+ * only runBreakGlass also enforces store capabilities, evidence, and execution order.
  *
  * @param {object} grant break-glass grant document or verifyBreakGlass result
  * @param {{ consume(key: string): Promise<boolean> }} store consumption store (store.js contract)
@@ -300,11 +410,11 @@ export async function consumeBreakGlass(grant, store) {
  * taken under it. Append it via the hash-chained evidence log — with
  * { strict: true } so a sink failure refuses the override.
  *
- * THE CONTRACT: NO EVIDENCE ENTRY, NO OVERRIDE. `evidence.record(entry)` must
- * SUCCEED before the overridden action executes; if it throws, refuse. This
- * function never throws, even for a malformed grant or missing decision — the
- * refusal of a bad grant must itself be loggable. A missing/indeterminate
- * decision is recorded as allow:false (fail closed).
+ * This builder does not execute or authorize anything. runBreakGlass is the
+ * enforcing path that requires a strict, independently validated record
+ * acknowledgement before invoking an effect. This function never throws, even
+ * for a malformed grant or missing decision; an uncanonicalizable artifact has
+ * a null grant_hash and cannot pass runBreakGlass verification.
  *
  * @param {object} grant the break-glass grant document as presented (even if invalid)
  * @param {object} decision e.g. { allow, reason, action_type } from verify/consume
@@ -312,12 +422,19 @@ export async function consumeBreakGlass(grant, store) {
  * @param {number|string|function} [o.now=Date.now] injected clock for the entry timestamp
  * @returns {object} entry ready for createEvidenceLog().record()
  */
-export function buildBreakGlassEvidence(grant, decision, { now = Date.now } = {}) {
-  const nowMs = typeof now === 'function' ? now() : toMs(now);
+function buildBreakGlassEvidenceInternal(grant, decision, { now = Date.now } = {}) {
+  let nowMs;
+  try { nowMs = typeof now === 'function' ? toMs(now()) : toMs(now); } catch { nowMs = null; }
   const p = (grant && typeof grant === 'object' && grant.payload && typeof grant.payload === 'object')
     ? grant.payload : null;
   const sigs = (grant && Array.isArray(grant.signatures)) ? grant.signatures : [];
   const d = (decision && typeof decision === 'object') ? decision : {};
+  let grantHash = null;
+  try { grantHash = sha256hex(canonical(grant ?? null)); } catch { /* uncanonicalizable artifacts stay unbound */ }
+  const principalIds = Array.isArray(d.signer_principal_ids)
+    && d.signer_principal_ids.every(isNonEmptyString) ? d.signer_principal_ids.slice() : null;
+  const fingerprints = Array.isArray(d.signer_spki_fingerprints)
+    && d.signer_spki_fingerprints.every(isNonEmptyString) ? d.signer_spki_fingerprints.slice() : null;
   return {
     kind: BREAKGLASS_EVIDENCE_KIND,
     '@version': BREAKGLASS_VERSION,
@@ -327,10 +444,15 @@ export function buildBreakGlassEvidence(grant, decision, { now = Date.now } = {}
     grant_reason: p?.reason ?? null,
     scope: p?.scope?.action_types?.slice?.() ?? null,
     threshold: p?.threshold ?? null,
+    policy_minimum_threshold: Number.isSafeInteger(d.policy_minimum_threshold)
+      ? d.policy_minimum_threshold : null,
+    required_threshold: Number.isSafeInteger(d.required_threshold) ? d.required_threshold : null,
     signer_kids: sigs.map((s) => s?.kid ?? null),
+    signer_principal_ids: principalIds,
+    signer_spki_fingerprints: fingerprints,
     // Commits the log entry to the exact artifact presented — a later dispute
     // can prove which grant (tampered or not) the decision was taken under.
-    grant_hash: sha256hex(canonical(grant ?? null)),
+    grant_hash: grantHash,
     decision: {
       allow: d.allow === true, // fail closed: anything else records a refusal
       reason: isNonEmptyString(d.reason) ? d.reason : 'unspecified',
@@ -339,11 +461,123 @@ export function buildBreakGlassEvidence(grant, decision, { now = Date.now } = {}
   };
 }
 
+export function buildBreakGlassEvidence(grant, decision, options = {}) {
+  try { return buildBreakGlassEvidenceInternal(grant, decision, options); } catch {
+    return {
+      kind: BREAKGLASS_EVIDENCE_KIND,
+      '@version': BREAKGLASS_VERSION,
+      at: new Date(0).toISOString(),
+      grant_id: null,
+      incident_ref: null,
+      grant_reason: null,
+      scope: null,
+      threshold: null,
+      policy_minimum_threshold: null,
+      required_threshold: null,
+      signer_kids: [],
+      signer_principal_ids: null,
+      signer_spki_fingerprints: null,
+      grant_hash: null,
+      decision: { allow: false, reason: 'unspecified', action_type: null },
+    };
+  }
+}
+
+/**
+ * The sole high-level break-glass execution path. It snapshots the presented
+ * artifact, verifies it against relying-party policy, atomically consumes the
+ * grant in a capability-marked permanent store, validates a strict evidence
+ * acknowledgement, and only then invokes `effect`.
+ */
+export async function runBreakGlass({
+  grant,
+  policy,
+  issuerKeys,
+  actionType,
+  store,
+  evidence,
+  now = Date.now,
+} = {}, effect) {
+  if (typeof effect !== 'function') throw new Error('runBreakGlass: effect function is required');
+
+  let snapshot;
+  try {
+    const parsed = typeof grant === 'string' ? JSON.parse(grant) : grant;
+    snapshot = JSON.parse(canonical(parsed));
+  } catch {
+    const verification = verifyBreakGlass(grant, { policy, issuerKeys, actionType, now });
+    return { ok: false, reason: verification.reason, verification, consumption: null, evidence: null };
+  }
+
+  const verification = verifyBreakGlass(snapshot, { policy, issuerKeys, actionType, now });
+  if (!verification.valid) {
+    return { ok: false, reason: verification.reason, verification, consumption: null, evidence: null };
+  }
+  if (!isSecureConsumptionStore(store)) {
+    return {
+      ok: false,
+      reason: 'secure_consumption_store_required',
+      verification,
+      consumption: null,
+      evidence: null,
+    };
+  }
+  if (evidence?.strict !== true || typeof evidence?.record !== 'function') {
+    return {
+      ok: false,
+      reason: 'strict_evidence_required',
+      verification,
+      consumption: null,
+      evidence: null,
+    };
+  }
+
+  const consume = store.consume.bind(store);
+  const record = evidence.record.bind(evidence);
+  const consumption = await consumeBreakGlass(verification, { consume });
+  if (!consumption.consumed) {
+    return { ok: false, reason: consumption.reason, verification, consumption, evidence: null };
+  }
+
+  const entry = buildBreakGlassEvidence(snapshot, {
+    ...verification,
+    allow: true,
+    action_type: actionType,
+  }, { now });
+  let evidenceRecord;
+  try {
+    evidenceRecord = await record(entry);
+    if (!verifyEvidenceRecord(evidenceRecord, {
+      atomicRequired: evidence.atomicAppend === true,
+      expectedEntry: entry,
+    })) throw new Error('malformed evidence acknowledgement');
+  } catch {
+    return {
+      ok: false,
+      reason: 'evidence_record_failed',
+      verification,
+      consumption,
+      evidence: null,
+    };
+  }
+
+  const result = await effect({ verification, consumption, evidence: evidenceRecord });
+  return {
+    ok: true,
+    reason: 'breakglass_executed',
+    result,
+    verification,
+    consumption,
+    evidence: evidenceRecord,
+  };
+}
+
 export default {
   mintBreakGlassAuthorization,
   verifyBreakGlass,
   consumeBreakGlass,
   buildBreakGlassEvidence,
+  runBreakGlass,
   BREAKGLASS_VERSION,
   BREAKGLASS_EVIDENCE_KIND,
 };