@emilia-protocol/gate 0.9.1 → 0.9.3

package/index.js

@@ -73,6 +73,13 @@ export {
 } from './action-control-manifest.js';
 export { EXECUTION_BINDING_VERSION, canonicalize, hashCanonical, materialFieldsFor, verifyExecutionBinding } from './execution-binding.js';
 export { RELIANCE_PACKET_VERSION, ADMISSIBILITY_VERDICTS, buildReliancePacket } from './reliance-packet.js';
+export {
+  EXTERNAL_VERIFICATION_STATEMENT_VERSION,
+  EXTERNAL_VERIFICATION_DOMAIN,
+  externalVerificationDigest,
+  signExternalVerificationStatement,
+  verifyExternalVerificationStatement,
+} from './reports/external-verification.js';
 export {
   EG1_VERSION, EG1_CHECKS, EG1_DEFAULT_ACTION, EG1_DEFAULT_SELECTOR,
   createEg1Harness, makeGateInvoke, runEg1, mintDeviceSignoff, mintQuorumEvidence,
@@ -156,9 +163,26 @@ export function verifyAdmissibilityAgainstPinnedProfile(pinned, presented) {
  *      verifyWebAuthnSignoff earns `class_a`. Used where the approver keys travel
  *      with the receipt rather than being pinned by the relying party.
  *
+ *      TRUST-LAUNDERING GUARD: an approver key carried INSIDE the receipt proves
+ *      only that whoever minted the receipt also holds that key — it is NOT proof
+ *      the relying party trusts that human. Crediting an elevated tier off such a
+ *      key would collapse VERIFIED into ACCEPTED (any party can mint a fresh
+ *      keypair, self-sign a signoff, and embed both). So path (b) elevates the
+ *      tier ONLY when either: (i) the caller explicitly opts in with
+ *      `allowEmbeddedApproverKeys:true` (the documented self-contained mode,
+ *      DEFAULT OFF); or (ii) every embedded approver key that would earn the
+ *      credit is present in the relying party's PINNED approver key set
+ *      (opts.approverKeys). With no pin and no opt-in, path (b) may still VERIFY
+ *      the signoff/quorum, but it does NOT elevate above `software`. Fail-closed.
+ *
  * @param {object} doc  the EP-RECEIPT-v1 document
  * @param {object} [opts]
- * @param {object} [opts.approverKeys] pinned approver keys for path (a)
+ * @param {object} [opts.approverKeys] pinned approver keys for path (a) and the
+ *   path-(b) fallback: a receipt-embedded approver key elevates the tier only if
+ *   it is one of these pinned keys (unless allowEmbeddedApproverKeys is set)
+ * @param {boolean} [opts.allowEmbeddedApproverKeys=false] explicit opt-in to the
+ *   self-contained mode where an UNPINNED approver key carried inside the receipt
+ *   may still elevate the path-(b) tier. DEFAULT OFF (fail-closed).
  * @param {function} [opts.verifyAssurance] custom assurance verifier for path (a)
  * @param {string} [opts.rpId]  bind embedded device assertions to this WebAuthn RP id (path b)
  * @param {boolean} [opts.detail] return a {tier, quorum, signoff} object instead of the string
@@ -178,30 +202,43 @@ export function receiptAssuranceTier(doc, opts = {}) {
   // --- Path (b): self-contained embedded per-signer evidence (DoD audit fix). ---
   const p = doc?.payload || {};
   const verifyOpts = opts.rpId ? { rpId: opts.rpId } : {};
+  // The relying party's PINNED approver public keys (base64url SPKI-DER strings).
+  // An embedded approver key elevates the tier only if it is in this set, unless
+  // the caller explicitly opts into the self-contained mode.
+  const allowEmbedded = opts.allowEmbeddedApproverKeys === true;
+  const pinnedKeys = pinnedApproverKeySet(opts.approverKeys);
+  const keyIsTrusted = (k) => allowEmbedded || (typeof k === 'string' && pinnedKeys.has(k));
 
   // quorum: a real, self-contained EP-QUORUM-v1 evidence document. Accept it
   // under payload.quorum or payload.claim.quorum. It only counts if it is a full
   // quorum document (policy + members with WebAuthn signoffs) AND verifyQuorum
   // returns valid. A bare {signers,threshold} block has no members to verify and
-  // therefore CANNOT be credited quorum.
+  // therefore CANNOT be credited quorum. The cryptographic verification runs
+  // regardless (so `detail.quorum` reports validity), but the tier elevates only
+  // when every member's embedded approver key is pinned (or the caller opted in).
   const q = p.quorum || p.claim?.quorum;
   if (detail.tier !== 'quorum' && isQuorumEvidence(q)) {
     const qr = verifyQuorum(q, verifyOpts);
-    detail.quorum = { valid: qr.valid, checks: qr.checks };
-    if (qr.valid) detail.tier = 'quorum';
+    const membersTrusted = allowEmbedded
+      || (Array.isArray(q.members) && q.members.length > 0
+          && q.members.every((m) => keyIsTrusted(m?.approver_public_key)));
+    detail.quorum = { valid: qr.valid, checks: qr.checks, embedded_keys_trusted: membersTrusted };
+    if (qr.valid && membersTrusted) detail.tier = 'quorum';
   }
 
   // class_a: a verifiable WebAuthn device signoff. The signoff evidence is
   // {context, webauthn}; the approver key travels with it (signoff.approver_public_key)
-  // or alongside it (payload.approver_public_key).
+  // or alongside it (payload.approver_public_key). That key elevates the tier only
+  // when it is pinned by the relying party (or the caller opted into embedded keys).
   if ((TIER_RANK[detail.tier] ?? 0) < TIER_RANK.class_a) {
     const so = p.signoff || p.claim?.signoff;
     if (isSignoffEvidence(so)) {
       const key = so.approver_public_key || p.approver_public_key || p.claim?.approver_public_key;
       if (key) {
         const sr = verifyWebAuthnSignoff(so, key, verifyOpts);
-        detail.signoff = { valid: sr.valid, checks: sr.checks };
-        if (sr.valid && (TIER_RANK[detail.tier] ?? 0) < TIER_RANK.class_a) detail.tier = 'class_a';
+        const trusted = keyIsTrusted(key);
+        detail.signoff = { valid: sr.valid, checks: sr.checks, embedded_key_trusted: trusted };
+        if (sr.valid && trusted && (TIER_RANK[detail.tier] ?? 0) < TIER_RANK.class_a) detail.tier = 'class_a';
       }
     }
   }
@@ -209,6 +246,34 @@ export function receiptAssuranceTier(doc, opts = {}) {
   return opts.detail ? detail : detail.tier;
 }
 
+/**
+ * The set of PINNED approver public keys (base64url SPKI-DER strings) a relying
+ * party trusts, from the same `approverKeys` map path (a) uses. Accepts either a
+ * map of { keyId: { public_key } } (the EP-ASSURANCE-PROOF-v1 shape) or a plain
+ * array/set of key strings. Used to decide whether a receipt-embedded approver
+ * key may elevate the path-(b) tier. Never throws.
+ */
+function pinnedApproverKeySet(approverKeys) {
+  const out = new Set();
+  if (!approverKeys) return out;
+  if (approverKeys instanceof Set) {
+    for (const k of approverKeys) if (typeof k === 'string' && k) out.add(k);
+    return out;
+  }
+  if (Array.isArray(approverKeys)) {
+    for (const k of approverKeys) if (typeof k === 'string' && k) out.add(k);
+    return out;
+  }
+  if (typeof approverKeys === 'object') {
+    for (const entry of Object.values(approverKeys)) {
+      if (typeof entry === 'string' && entry) { out.add(entry); continue; }
+      const pk = entry && typeof entry === 'object' ? entry.public_key : null;
+      if (typeof pk === 'string' && pk) out.add(pk);
+    }
+  }
+  return out;
+}
+
 /** A quorum evidence doc must carry members with per-signer signoffs to be verifiable. */
 function isQuorumEvidence(q) {
   return !!q && typeof q === 'object' && q.policy && Array.isArray(q.members) && q.members.length > 0
@@ -231,8 +296,16 @@ function isSignoffEvidence(s) {
  * @param {object} [opts.keyRegistry] a key registry (createKeyRegistry) for rotation + revocation;
  *   if given it supersedes trustedKeys — a receipt is verified only against keys valid (and not
  *   revoked) at its issuance time.
+ * @param {object} [opts.approverKeys] PINNED approver keys ({ keyId: { public_key, key_class } }).
+ *   Used both for the pinned assurance-proof path and to authorize receipt-embedded
+ *   approver keys under the self-contained embedded-evidence path.
+ * @param {boolean} [opts.allowEmbeddedApproverKeys=false] opt into the self-contained
+ *   embedded-evidence mode: when true, a class_a/quorum tier may be credited from an
+ *   approver key carried INSIDE the receipt even if that key is not pinned. DEFAULT OFF
+ *   — with no pinned approverKeys and no opt-in, embedded evidence verifies but does not
+ *   elevate above 'software' (prevents VERIFIED collapsing into ACCEPTED / trust-laundering).
  */
-export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900, store, log, allowInlineKey = false, allowEphemeralStore = false, strictEvidence = true, now = Date.now, keyRegistry = null, approverKeys = {}, approver_keys = null, verifyAssurance = null, rpId = null, requiredAdmissibilityProfile = null } = {}) {
+export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900, store, log, allowInlineKey = false, allowEphemeralStore = false, strictEvidence = true, now = Date.now, keyRegistry = null, approverKeys = {}, approver_keys = null, verifyAssurance = null, rpId = null, requiredAdmissibilityProfile = null, allowEmbeddedApproverKeys = false } = {}) {
   // Production key custody: a registry (rotation + revocation) supersedes a flat
   // trustedKeys list. A flat list is coerced to an always-valid registry, so
   // existing callers are unchanged.
@@ -360,6 +433,10 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     });
     const tierResult = receiptAssuranceTier(receipt, {
       rpId, detail: true, approverKeys: approver_keys || approverKeys, verifyAssurance,
+      // Trust-laundering guard: a receipt-embedded approver key does NOT elevate
+      // the tier unless it is in the pinned approverKeys set, or the operator
+      // explicitly opted into the self-contained embedded-evidence mode. DEFAULT OFF.
+      allowEmbeddedApproverKeys,
     });
     // Take the strongest tier either path proves.
     const have = (TIER_RANK[assurance.have] ?? 0) >= (TIER_RANK[tierResult.tier] ?? 0)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@emilia-protocol/gate",
-  "version": "0.9.1",
-  "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.",
+  "version": "0.9.3",
+  "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.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "index.js",
@@ -34,7 +34,8 @@
     "./breakglass": "./breakglass.js",
     "./store-postgres": "./store-postgres.js",
     "./reports/auditor-workpaper": "./reports/auditor-workpaper.js",
-    "./reports/reperform": "./reports/reperform.js"
+    "./reports/reperform": "./reports/reperform.js",
+    "./reports/external-verification": "./reports/external-verification.js"
   },
   "files": [
     "index.js",
@@ -91,7 +92,8 @@
     "deploy/terraform/versions.tf",
     "deploy/terraform/README.md",
     "reports/auditor-workpaper.js",
-    "reports/reperform.js"
+    "reports/reperform.js",
+    "reports/external-verification.js"
   ],
   "scripts": {
     "test": "node --test",

package/reports/external-verification.js

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EP-EXTERNAL-VERIFICATION-STATEMENT-v1.
+ *
+ * A signed statement a NON-EMILIA verifier can issue after it re-performs an
+ * evidence log, replays an admissibility profile, or runs a conformance harness.
+ * This is the missing adoption rail between "our verifier works" and "an
+ * outside party says exactly what they checked."
+ *
+ * Scope is intentionally narrow:
+ *   - the statement signs a procedure, inputs, result, and limitations;
+ *   - it does NOT authorize an action;
+ *   - it does NOT certify business correctness;
+ *   - acceptance is by a relying party pinning the external verifier key.
+ */
+import crypto from 'node:crypto';
+// In-package canonicalize (byte-identical to lib/canonical-json.js): reports must
+// never import outside the package root or the published tarball cannot resolve it.
+import { canonicalize } from '../execution-binding.js';
+
+export const EXTERNAL_VERIFICATION_STATEMENT_VERSION = 'EP-EXTERNAL-VERIFICATION-STATEMENT-v1';
+export const EXTERNAL_VERIFICATION_DOMAIN = 'EP-EXTERNAL-VERIFICATION-STATEMENT-v1\0';
+
+const SHA256_RE = /^sha256:[0-9a-f]{64}$/i;
+
+function sha256hex(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function publicKeyToB64u(key) {
+  return crypto.createPublicKey(key).export({ type: 'spki', format: 'der' }).toString('base64url');
+}
+
+function keyIdFor(publicKeyB64u) {
+  return `ep:external-verifier-key:sha256:${sha256hex(Buffer.from(publicKeyB64u, 'base64url')).slice(0, 16)}`;
+}
+
+function signingBytes(unsignedStatement) {
+  return Buffer.from(EXTERNAL_VERIFICATION_DOMAIN + canonicalize(unsignedStatement), 'utf8');
+}
+
+function unsigned(statement) {
+  if (!statement || typeof statement !== 'object' || Array.isArray(statement)) {
+    throw new Error('statement must be an object');
+  }
+  const { signature: _signature, ...body } = statement;
+  return body;
+}
+
+/** Digest of the signed statement body, excluding the signature envelope. */
+export function externalVerificationDigest(statement) {
+  return `sha256:${sha256hex(signingBytes(unsigned(statement)))}`;
+}
+
+function normalizeChecks(checks) {
+  if (!Array.isArray(checks)) return [];
+  return checks.map((c) => ({
+    id: String(c?.id ?? ''),
+    ok: c?.ok === true,
+    ...(c?.detail !== undefined ? { detail: c.detail } : {}),
+  })).filter((c) => c.id);
+}
+
+/**
+ * Build and sign an external-verifier statement.
+ *
+ * @param {object} args
+ * @param {object} args.verifier {id, name?, organization?}
+ * @param {object} args.subject  what was checked, e.g. {kind:'evidence_log', head:'sha256:...'}
+ * @param {object} args.procedure {id, version?, tool?, command?}
+ * @param {object} args.result {status, checks?, artifact_digest?}
+ * @param {object} [args.inputs] stable digests/ids the procedure consumed
+ * @param {string[]} [args.limitations] honest non-claims
+ * @param {string|number} [args.generated_at] ISO or epoch millis
+ * @param {crypto.KeyObject} privateKey Ed25519 private key
+ */
+export function signExternalVerificationStatement(args, privateKey) {
+  if (!privateKey) throw new Error('privateKey is required');
+  const generatedAt = args?.generated_at !== undefined
+    ? new Date(args.generated_at).toISOString()
+    : new Date().toISOString();
+  const publicKey = publicKeyToB64u(privateKey);
+  const body = {
+    '@version': EXTERNAL_VERIFICATION_STATEMENT_VERSION,
+    generated_at: generatedAt,
+    verifier: {
+      id: args?.verifier?.id ?? keyIdFor(publicKey),
+      ...(args?.verifier?.name ? { name: args.verifier.name } : {}),
+      ...(args?.verifier?.organization ? { organization: args.verifier.organization } : {}),
+    },
+    subject: args?.subject ?? {},
+    procedure: args?.procedure ?? {},
+    inputs: args?.inputs ?? {},
+    result: {
+      status: String(args?.result?.status ?? 'unknown'),
+      checks: normalizeChecks(args?.result?.checks),
+      ...(args?.result?.artifact_digest ? { artifact_digest: args.result.artifact_digest } : {}),
+    },
+    limitations: Array.isArray(args?.limitations) && args.limitations.length
+      ? args.limitations.map(String)
+      : [
+        'This statement records the external verifier procedure and result; it does not authorize the action.',
+        'It does not certify business correctness, legal compliance, or human wisdom.',
+        'Acceptance depends on the relying party pinning the verifier key out of band.',
+        'The statement carries no expiry and no consumer binding; it is replayable verbatim, and generated_at is asserted by the signer, not verified.',
+      ],
+  };
+
+  const digest = externalVerificationDigest(body);
+  const sig = crypto.sign(null, signingBytes(body), privateKey).toString('base64url');
+  return Object.freeze({
+    ...body,
+    signature: {
+      algorithm: 'Ed25519',
+      key_id: keyIdFor(publicKey),
+      public_key: publicKey,
+      statement_digest: digest,
+      signature_b64u: sig,
+    },
+  });
+}
+
+/**
+ * Verify a signed external-verifier statement against pinned verifier keys.
+ *
+ * @param {object} statement
+ * @param {{pinnedVerifierKeys:Array<{verifier_id?:string,key_id?:string,public_key:string}>}} opts
+ * @returns {{verified:boolean, accepted:boolean, checks:object, reason?:string, statement_digest?:string}}
+ */
+export function verifyExternalVerificationStatement(statement, opts = {}) {
+  const fail = (reason, extra = {}) => ({
+    verified: false,
+    accepted: false,
+    checks: {
+      version: statement?.['@version'] === EXTERNAL_VERIFICATION_STATEMENT_VERSION,
+      signature: false,
+      pinned_verifier_key: false,
+      statement_digest: false,
+    },
+    reason,
+    ...extra,
+  });
+
+  if (statement?.['@version'] !== EXTERNAL_VERIFICATION_STATEMENT_VERSION) {
+    return fail('unsupported_version');
+  }
+  const sig = statement.signature;
+  if (!sig || sig.algorithm !== 'Ed25519' || typeof sig.public_key !== 'string' || typeof sig.signature_b64u !== 'string') {
+    return fail('signature_missing_or_malformed');
+  }
+  if (typeof sig.statement_digest !== 'string' || !SHA256_RE.test(sig.statement_digest)) {
+    return fail('statement_digest_missing_or_malformed');
+  }
+
+  let digest;
+  try {
+    digest = externalVerificationDigest(statement);
+  } catch {
+    return fail('statement_uncanonicalizable');
+  }
+  if (digest !== sig.statement_digest) {
+    return fail('statement_digest_mismatch', { statement_digest: digest });
+  }
+
+  const pinned = Array.isArray(opts.pinnedVerifierKeys) ? opts.pinnedVerifierKeys : [];
+  const verifierId = statement.verifier?.id ?? null;
+  // key_id is always DERIVED from the carried public key. The envelope's key_id is
+  // outside the signed bytes, so it is attacker-malleable; if present it must match
+  // the derived value or the statement is refused.
+  const keyId = keyIdFor(sig.public_key);
+  if (sig.key_id !== undefined && sig.key_id !== keyId) {
+    return fail('key_id_mismatch', { statement_digest: digest });
+  }
+  // A pin grants an identity, not just a key: every usable pin entry must name the
+  // verifier_id it vouches for. A pin that matches the key but omits verifier_id
+  // (or names a different one) never binds the statement's claimed identity.
+  const keyMatched = pinned.filter((k) => k?.public_key === sig.public_key
+    && (k.key_id === undefined || k.key_id === keyId));
+  const pin = keyMatched.find((k) => typeof k.verifier_id === 'string' && k.verifier_id === verifierId);
+  if (!pin) {
+    return {
+      verified: false,
+      accepted: false,
+      checks: { version: true, signature: false, pinned_verifier_key: false, statement_digest: true },
+      reason: keyMatched.length ? 'pin_missing_or_mismatched_verifier_id' : 'verifier_key_not_pinned',
+      statement_digest: digest,
+    };
+  }
+
+  let ok = false;
+  try {
+    const publicKey = crypto.createPublicKey({ key: Buffer.from(sig.public_key, 'base64url'), type: 'spki', format: 'der' });
+    ok = crypto.verify(null, signingBytes(unsigned(statement)), publicKey, Buffer.from(sig.signature_b64u, 'base64url'));
+  } catch {
+    ok = false;
+  }
+  if (!ok) {
+    return {
+      verified: false,
+      accepted: false,
+      checks: { version: true, signature: false, pinned_verifier_key: true, statement_digest: true },
+      reason: 'signature_invalid',
+      statement_digest: digest,
+    };
+  }
+
+  return {
+    verified: true,
+    accepted: true,
+    checks: { version: true, signature: true, pinned_verifier_key: true, statement_digest: true },
+    verifier_id: verifierId,
+    key_id: keyId,
+    statement_digest: digest,
+  };
+}
+
+export default {
+  EXTERNAL_VERIFICATION_STATEMENT_VERSION,
+  EXTERNAL_VERIFICATION_DOMAIN,
+  externalVerificationDigest,
+  signExternalVerificationStatement,
+  verifyExternalVerificationStatement,
+};