@emilia-protocol/verify 1.0.1 → 1.2.0

package/LICENSE

@@ -175,7 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2024–2026 EMILIA Protocol Contributors
+   Copyright 2024–2026 EMILIA Protocol, Inc. and contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -28,6 +28,27 @@ console.log(result);
 // { valid: true, checks: { version: true, signature: true, anchor: null } }
 ```
 
+## In the browser, edge, or Deno
+
+The default entry uses Node's `crypto`. For any runtime with the W3C Web Crypto
+API — every modern browser, Deno, Cloudflare Workers, Vercel Edge — import the
+`/web` build instead. Same inputs, same `{ valid, checks }` output (proven
+byte-for-byte in `web.test.js`); the functions are `async` because Web Crypto is.
+
+```js
+import { verifyReceipt, verifyWebAuthnSignoff } from '@emilia-protocol/verify/web';
+
+const r = await verifyReceipt(receipt, publicKey);          // Ed25519
+const s = await verifyWebAuthnSignoff(signoff, approverKey, // ECDSA P-256
+  { rpId: 'emiliaprotocol.ai' });
+```
+
+This is what powers [emiliaprotocol.ai/verify](https://www.emiliaprotocol.ai/verify):
+a relying party verifies a receipt entirely in their own tab — nothing uploaded,
+no server trusted. Receipts use Ed25519; Class-A device signoffs use ECDSA P-256
+over a WebAuthn assertion (the `/web` build converts the DER signature to the raw
+form Web Crypto expects). Call `isSupported()` to feature-detect.
+
 ## API
 
 ### `verifyReceipt(doc, publicKeyBase64url)`

package/index.d.ts

@@ -59,3 +59,36 @@ export function verifyReceiptBundle(
   bundle: Record<string, unknown>,
   publicKeyBase64url: string
 ): BundleVerificationResult;
+
+export interface WebAuthnSignoffChecks {
+  challenge_binding: boolean;
+  client_data_type: boolean;
+  user_present: boolean;
+  user_verified: boolean;
+  rp_id_hash: boolean | null;
+  signature: boolean;
+}
+
+export interface WebAuthnSignoffResult {
+  valid: boolean;
+  checks: WebAuthnSignoffChecks;
+  error?: string;
+}
+
+/**
+ * Verify a Class A (approver-held key, WebAuthn) signoff fully offline.
+ * Proves the device signed SHA-256(JCS(context)) with user verification,
+ * against the approver's enrolled P-256 key. Pure math — no network.
+ */
+export function verifyWebAuthnSignoff(
+  signoff: {
+    context: Record<string, unknown>;
+    webauthn: {
+      authenticator_data: string;
+      client_data_json: string;
+      signature: string;
+    };
+  },
+  approverPublicKeySpkiB64u: string,
+  opts?: { rpId?: string }
+): WebAuthnSignoffResult;

package/index.js

@@ -145,6 +145,122 @@ export function verifyMerkleAnchor(leafHash, proof, expectedRoot) {
   return current === expectedRoot;
 }
 
+// =============================================================================
+// CLASS A SIGNOFF VERIFICATION (WebAuthn, offline)
+// =============================================================================
+
+// authenticatorData layout (WebAuthn L2 §6.1): rpIdHash(32) | flags(1) |
+// signCount(4) | ... Flags bit 0 = UP (user present), bit 2 = UV (user
+// verified — biometric/PIN).
+const FLAG_UP = 0x01;
+const FLAG_UV = 0x04;
+
+/**
+ * Verify a Class A (approver-held key) signoff fully offline.
+ *
+ * What this proves with pure math, no network, no EP server:
+ *   - the WebAuthn challenge the device signed equals
+ *     SHA-256(JCS(context)) for the EXACT context in the signoff — which
+ *     binds the action hash, nonce, approver, and validity window;
+ *   - the signature verifies against the approver's enrolled P-256 key;
+ *   - the authenticator asserted user presence AND user verification
+ *     (a human with the biometric/PIN was there);
+ *   - (if rpId supplied) the assertion was scoped to the expected relying
+ *     party.
+ *
+ * What it does NOT prove (EP draft §6.3): that the key wasn't revoked
+ * after commit time, or what the human SAW when they signed (§11.3).
+ *
+ * @param {object} signoff - {
+ *   context: object,            // the canonical Authorization Context
+ *   webauthn: {
+ *     authenticator_data: string,  // b64u
+ *     client_data_json: string,    // b64u
+ *     signature: string,           // b64u (DER ECDSA)
+ *   }
+ * }
+ * @param {string} approverPublicKeySpkiB64u - enrolled P-256 key, SPKI DER b64u
+ * @param {{ rpId?: string }} [opts]
+ * @returns {{ valid: boolean, checks: object, error?: string }}
+ */
+export function verifyWebAuthnSignoff(signoff, approverPublicKeySpkiB64u, opts = {}) {
+  const checks = {
+    challenge_binding: false,
+    client_data_type: false,
+    user_present: false,
+    user_verified: false,
+    rp_id_hash: null,
+    signature: false,
+  };
+
+  try {
+    if (!signoff?.context || !signoff?.webauthn) {
+      return { valid: false, checks, error: 'Missing context or webauthn evidence' };
+    }
+    const { authenticator_data, client_data_json, signature } = signoff.webauthn;
+    if (!authenticator_data || !client_data_json || !signature) {
+      return { valid: false, checks, error: 'Missing webauthn fields' };
+    }
+
+    // 1. Challenge binding: clientDataJSON.challenge must equal
+    //    b64u(SHA-256(canonical(context))). The context is re-canonicalized
+    //    here — tamper any field (amount, approver, nonce) and this fails.
+    const clientDataBytes = Buffer.from(client_data_json, 'base64url');
+    const clientData = JSON.parse(clientDataBytes.toString('utf8'));
+    const expectedChallenge = crypto
+      .createHash('sha256')
+      .update(canonicalize(signoff.context), 'utf8')
+      .digest()
+      .toString('base64url');
+    checks.challenge_binding = clientData.challenge === expectedChallenge;
+
+    // 2. Ceremony type must be an assertion, not a registration.
+    checks.client_data_type = clientData.type === 'webauthn.get';
+
+    // 3. Authenticator flags: user present + user verified.
+    const authData = Buffer.from(authenticator_data, 'base64url');
+    if (authData.length < 37) {
+      return { valid: false, checks, error: 'authenticator_data too short' };
+    }
+    const flags = authData[32];
+    checks.user_present = (flags & FLAG_UP) === FLAG_UP;
+    checks.user_verified = (flags & FLAG_UV) === FLAG_UV;
+
+    // 4. Optional rpId scope check.
+    if (opts.rpId) {
+      const expectedRpIdHash = crypto.createHash('sha256').update(opts.rpId, 'utf8').digest();
+      checks.rp_id_hash = expectedRpIdHash.equals(authData.subarray(0, 32));
+    }
+
+    // 5. Signature: ECDSA P-256/SHA-256 over authData || SHA-256(clientDataJSON).
+    const signedData = Buffer.concat([
+      authData,
+      crypto.createHash('sha256').update(clientDataBytes).digest(),
+    ]);
+    const keyObject = crypto.createPublicKey({
+      key: Buffer.from(approverPublicKeySpkiB64u, 'base64url'),
+      format: 'der',
+      type: 'spki',
+    });
+    checks.signature = crypto.verify(
+      'sha256',
+      signedData,
+      keyObject,
+      Buffer.from(signature, 'base64url'),
+    );
+  } catch (e) {
+    return { valid: false, checks, error: `WebAuthn verification failed: ${e.message}` };
+  }
+
+  const valid = checks.challenge_binding
+    && checks.client_data_type
+    && checks.user_present
+    && checks.user_verified
+    && checks.signature
+    && (checks.rp_id_hash === null || checks.rp_id_hash === true);
+  return { valid, checks };
+}
+
 // =============================================================================
 // COMMITMENT PROOF VERIFICATION
 // =============================================================================

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@emilia-protocol/verify",
-  "version": "1.0.1",
-  "description": "Zero-dependency standalone verification for EP trust receipts, Merkle anchors, and commitment proofs. Uses only Node.js built-in crypto. No EP infrastructure required.",
+  "version": "1.2.0",
+  "description": "Zero-dependency offline verification for EP trust receipts, Merkle anchors, commitment proofs, and Class-A WebAuthn device signoffs. Node build uses built-in crypto; the /web build runs in any browser, edge, or Deno via Web Crypto. No EP infrastructure required.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "index.js",
@@ -10,10 +10,14 @@
     ".": {
       "import": "./index.js",
       "types": "./index.d.ts"
+    },
+    "./web": {
+      "import": "./web.js"
     }
   },
   "files": [
     "index.js",
+    "web.js",
     "index.d.ts",
     "README.md",
     "LICENSE"
@@ -41,8 +45,8 @@
   "bugs": {
     "url": "https://github.com/emiliaprotocol/emilia-protocol/issues"
   },
-  "author": "Emilia Protocol Contributors",
+  "author": "EMILIA Protocol, Inc.",
   "scripts": {
-    "test": "node --test test.js"
+    "test": "node --test test.js web.test.js"
   }
 }

package/web.js

@@ -0,0 +1,324 @@
+/**
+ * @emilia-protocol/verify/web — Zero-Dependency Trust Verification (Web Crypto)
+ *
+ * The browser/edge/Deno counterpart to index.js. Identical verification
+ * semantics, but built on the W3C Web Crypto API (globalThis.crypto.subtle)
+ * instead of Node's `crypto` module — so a receipt can be verified entirely
+ * inside the relying party's own browser tab, with nothing uploaded and no
+ * server trusted. Same input, same `{ valid, checks }` output as index.js
+ * (proven byte-for-byte in web.test.js).
+ *
+ * Pure ESM, zero dependencies. Functions are async because Web Crypto is.
+ *
+ * @license Apache-2.0
+ */
+
+const SUPPORTED_VERSIONS = ['EP-RECEIPT-v1'];
+const SUPPORTED_PROOF_VERSIONS = ['EP-PROOF-v1'];
+
+const subtle = globalThis.crypto?.subtle;
+
+// =============================================================================
+// PRIMITIVES (pure — no Node Buffer, no Node crypto)
+// =============================================================================
+
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+
+function utf8(str) {
+  return ENC.encode(str);
+}
+
+// base64url (and tolerant of standard base64) → Uint8Array.
+function b64uToBytes(b64u) {
+  const b64 = b64u.replace(/-/g, '+').replace(/_/g, '/');
+  const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+  const bin = atob(b64 + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function bytesToB64u(bytes) {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function bytesToHex(bytes) {
+  let hex = '';
+  for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, '0');
+  return hex;
+}
+
+// Same recursive canonical JSON as index.js / lib/guard-policies.js — depth-first
+// key sort at every level. Signer and verifier MUST compute byte-identical bytes.
+function canonicalize(value) {
+  if (value === null || value === undefined) return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(',')}]`;
+  }
+  if (typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => JSON.stringify(k) + ':' + canonicalize(value[k]))
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+async function sha256Bytes(bytes) {
+  return new Uint8Array(await subtle.digest('SHA-256', bytes));
+}
+
+async function sha256Hex(str) {
+  return bytesToHex(await sha256Bytes(utf8(str)));
+}
+
+async function hashPairHex(a, b) {
+  const sorted = [a, b].sort();
+  return sha256Hex(sorted[0] + sorted[1]);
+}
+
+function concatBytes(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+// WebAuthn ECDSA signatures are ASN.1 DER: SEQUENCE { INTEGER r, INTEGER s }.
+// Web Crypto's ECDSA verify wants raw r‖s (two fixed-width 32-byte integers).
+// Node's crypto.verify accepts DER directly, which is why index.js needs no
+// conversion — the browser does. Returns a 64-byte Uint8Array, or null if the
+// DER is malformed.
+function derEcdsaToRawP256(der) {
+  let i = 0;
+  if (der[i++] !== 0x30) return null; // SEQUENCE
+  // sequence length (short or long form) — we don't need the value, just skip it.
+  if (der[i] & 0x80) i += 1 + (der[i] & 0x7f);
+  else i += 1;
+
+  const readInt = () => {
+    if (der[i++] !== 0x02) return null; // INTEGER
+    let len = der[i++];
+    let val = der.subarray(i, i + len);
+    i += len;
+    // strip any leading 0x00 sign-padding
+    while (val.length > 1 && val[0] === 0x00) val = val.subarray(1);
+    if (val.length > 32) return null; // not a P-256 component
+    const padded = new Uint8Array(32);
+    padded.set(val, 32 - val.length); // left-pad to 32 bytes
+    return padded;
+  };
+
+  const r = readInt();
+  if (!r) return null;
+  const s = readInt();
+  if (!s) return null;
+  return concatBytes(r, s);
+}
+
+// =============================================================================
+// RECEIPT VERIFICATION (Ed25519)
+// =============================================================================
+
+/**
+ * Verify an EP receipt document in the browser. Mirrors index.js verifyReceipt.
+ * @param {object} doc
+ * @param {string} publicKeyBase64url - Ed25519 public key (SPKI DER, base64url)
+ * @returns {Promise<{valid:boolean, checks:{version:boolean,signature:boolean,anchor:boolean|null}, error?:string}>}
+ */
+export async function verifyReceipt(doc, publicKeyBase64url) {
+  const checks = { version: false, signature: false, anchor: null };
+
+  if (!doc?.['@version'] || !SUPPORTED_VERSIONS.includes(doc['@version'])) {
+    return { valid: false, checks, error: `Unsupported version: ${doc?.['@version']}` };
+  }
+  checks.version = true;
+
+  if (!doc.payload || !doc.signature?.value || !doc.signature?.algorithm) {
+    return { valid: false, checks, error: 'Missing payload or signature' };
+  }
+
+  try {
+    const payloadBytes = utf8(canonicalize(doc.payload));
+    const key = await subtle.importKey(
+      'spki', b64uToBytes(publicKeyBase64url), { name: 'Ed25519' }, false, ['verify'],
+    );
+    checks.signature = await subtle.verify(
+      { name: 'Ed25519' }, key, b64uToBytes(doc.signature.value), payloadBytes,
+    );
+  } catch (e) {
+    return { valid: false, checks, error: `Signature verification failed: ${e.message}` };
+  }
+
+  if (doc.anchor?.merkle_proof && doc.anchor?.leaf_hash && doc.anchor?.merkle_root) {
+    checks.anchor = await verifyMerkleAnchor(doc.anchor.leaf_hash, doc.anchor.merkle_proof, doc.anchor.merkle_root);
+  }
+
+  const valid = checks.version && checks.signature && (checks.anchor === null || checks.anchor === true);
+  return { valid, checks };
+}
+
+// =============================================================================
+// MERKLE ANCHOR VERIFICATION
+// =============================================================================
+
+/** @returns {Promise<boolean>} */
+export async function verifyMerkleAnchor(leafHash, proof, expectedRoot) {
+  if (typeof leafHash !== 'string' || !leafHash) return false;
+  if (typeof expectedRoot !== 'string' || !expectedRoot) return false;
+  if (!Array.isArray(proof)) return false;
+  if (proof.length > 20) return false;
+
+  let current = leafHash;
+  for (const step of proof) {
+    if (!step || typeof step.hash !== 'string') return false;
+    if (step.position !== 'left' && step.position !== 'right') return false;
+    current = step.position === 'left'
+      ? await hashPairHex(step.hash, current)
+      : await hashPairHex(current, step.hash);
+  }
+  return current === expectedRoot;
+}
+
+// =============================================================================
+// CLASS A SIGNOFF VERIFICATION (WebAuthn, offline, ECDSA P-256)
+// =============================================================================
+
+const FLAG_UP = 0x01;
+const FLAG_UV = 0x04;
+
+/**
+ * Verify a Class A (approver-held key) signoff fully offline, in the browser.
+ * Mirrors index.js verifyWebAuthnSignoff.
+ * @returns {Promise<{valid:boolean, checks:object, error?:string}>}
+ */
+export async function verifyWebAuthnSignoff(signoff, approverPublicKeySpkiB64u, opts = {}) {
+  const checks = {
+    challenge_binding: false,
+    client_data_type: false,
+    user_present: false,
+    user_verified: false,
+    rp_id_hash: null,
+    signature: false,
+  };
+
+  try {
+    if (!signoff?.context || !signoff?.webauthn) {
+      return { valid: false, checks, error: 'Missing context or webauthn evidence' };
+    }
+    const { authenticator_data, client_data_json, signature } = signoff.webauthn;
+    if (!authenticator_data || !client_data_json || !signature) {
+      return { valid: false, checks, error: 'Missing webauthn fields' };
+    }
+
+    // 1. Challenge binding: clientData.challenge === b64u(SHA-256(canonical(context))).
+    const clientDataBytes = b64uToBytes(client_data_json);
+    const clientData = JSON.parse(DEC.decode(clientDataBytes));
+    const expectedChallenge = bytesToB64u(await sha256Bytes(utf8(canonicalize(signoff.context))));
+    checks.challenge_binding = clientData.challenge === expectedChallenge;
+
+    // 2. Ceremony type must be an assertion.
+    checks.client_data_type = clientData.type === 'webauthn.get';
+
+    // 3. Authenticator flags: user present + user verified.
+    const authData = b64uToBytes(authenticator_data);
+    if (authData.length < 37) {
+      return { valid: false, checks, error: 'authenticator_data too short' };
+    }
+    const flags = authData[32];
+    checks.user_present = (flags & FLAG_UP) === FLAG_UP;
+    checks.user_verified = (flags & FLAG_UV) === FLAG_UV;
+
+    // 4. Optional rpId scope check.
+    if (opts.rpId) {
+      const expectedRpIdHash = await sha256Bytes(utf8(opts.rpId));
+      checks.rp_id_hash = bytesEqual(expectedRpIdHash, authData.subarray(0, 32));
+    }
+
+    // 5. Signature: ECDSA P-256/SHA-256 over authData ‖ SHA-256(clientDataJSON).
+    const signedData = concatBytes(authData, await sha256Bytes(clientDataBytes));
+    const rawSig = derEcdsaToRawP256(b64uToBytes(signature));
+    if (!rawSig) {
+      return { valid: false, checks, error: 'Malformed ECDSA signature' };
+    }
+    const key = await subtle.importKey(
+      'spki', b64uToBytes(approverPublicKeySpkiB64u),
+      { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify'],
+    );
+    checks.signature = await subtle.verify(
+      { name: 'ECDSA', hash: 'SHA-256' }, key, rawSig, signedData,
+    );
+  } catch (e) {
+    return { valid: false, checks, error: `WebAuthn verification failed: ${e.message}` };
+  }
+
+  const valid = checks.challenge_binding
+    && checks.client_data_type
+    && checks.user_present
+    && checks.user_verified
+    && checks.signature
+    && (checks.rp_id_hash === null || checks.rp_id_hash === true);
+  return { valid, checks };
+}
+
+// =============================================================================
+// COMMITMENT PROOF VERIFICATION (Ed25519)
+// =============================================================================
+
+/** @returns {Promise<{valid:boolean, claim:object|null, error?:string}>} */
+export async function verifyCommitmentProof(proof, publicKeyBase64url) {
+  if (!proof?.['@version'] || !SUPPORTED_PROOF_VERSIONS.includes(proof['@version'])) {
+    return { valid: false, claim: null, error: `Unsupported version: ${proof?.['@version']}` };
+  }
+  if (proof.expires_at && new Date(proof.expires_at) < new Date()) {
+    return { valid: false, claim: proof.claim, error: 'Proof has expired' };
+  }
+  if (publicKeyBase64url && proof.signature) {
+    try {
+      const key = await subtle.importKey(
+        'spki', b64uToBytes(publicKeyBase64url), { name: 'Ed25519' }, false, ['verify'],
+      );
+      const ok = await subtle.verify(
+        { name: 'Ed25519' }, key, b64uToBytes(proof.signature.value), utf8(canonicalize(proof.commitment)),
+      );
+      if (!ok) return { valid: false, claim: proof.claim, error: 'Invalid signature' };
+    } catch (e) {
+      return { valid: false, claim: proof.claim, error: `Signature check failed: ${e.message}` };
+    }
+  }
+  return { valid: true, claim: proof.claim };
+}
+
+// =============================================================================
+// BUNDLE VERIFICATION
+// =============================================================================
+
+/** @returns {Promise<{valid:boolean, total:number, verified:number, failed:string[]}>} */
+export async function verifyReceiptBundle(bundle, publicKeyBase64url) {
+  if (bundle?.['@version'] !== 'EP-BUNDLE-v1') {
+    return { valid: false, total: 0, verified: 0, failed: ['Invalid bundle version'] };
+  }
+  const failed = [];
+  let verified = 0;
+  for (let i = 0; i < bundle.documents.length; i++) {
+    const result = await verifyReceipt(bundle.documents[i], publicKeyBase64url);
+    if (result.valid) verified++;
+    else failed.push(`doc[${i}]: ${result.error || 'verification failed'}`);
+  }
+  return { valid: failed.length === 0, total: bundle.documents.length, verified, failed };
+}
+
+/** True if Web Crypto with the algorithms EP needs is available in this runtime. */
+export function isSupported() {
+  return Boolean(subtle && typeof atob === 'function' && typeof btoa === 'function');
+}