@typedstandards/verify-core 0.5.0 → 0.6.0

package/dist/rekor-inclusion.d.ts

@@ -29,6 +29,17 @@ export interface RekorInclusionProof {
     /** The signed checkpoint (Go note) committing to `rootHash` at `treeSize`. */
     checkpoint: string;
 }
+/**
+ * Parse the carried Rekor inclusion proof — the JSON string in
+ * `verification.inclusionProof` (or the stored DB column) — into the structured proof
+ * `verifyRekorInclusion` folds. Only a REAL proof is usable: it must carry an audit
+ * path (`hashes`) AND a signed `checkpoint`. The empty `{}` some early packages carry,
+ * any value missing those fields, and malformed JSON all resolve to null — inclusion
+ * is then simply not verified, never thrown. This is the SINGLE guard the server
+ * route, the browser verify-flow, and the backfill script share (#119 P4), so "what
+ * counts as a real proof" is defined and tested in exactly one place.
+ */
+export declare function parseInclusionProof(raw: string | null | undefined): RekorInclusionProof | null;
 export type RekorInclusionFailReason = 'leaf_index_out_of_range' | 'proof_wrong_length' | 'root_mismatch' | 'checkpoint_unparseable' | 'checkpoint_root_mismatch' | 'checkpoint_unknown_anchor' | 'checkpoint_signature_invalid';
 export interface RekorInclusionResult {
     /** The entry body + audit path reproduce the proof's `rootHash` (RFC 6962). */

package/dist/rekor-inclusion.js

@@ -42,6 +42,33 @@ export const REKOR_LOG_ANCHORS = [
         curve: 'p256',
     },
 ];
+/**
+ * Parse the carried Rekor inclusion proof — the JSON string in
+ * `verification.inclusionProof` (or the stored DB column) — into the structured proof
+ * `verifyRekorInclusion` folds. Only a REAL proof is usable: it must carry an audit
+ * path (`hashes`) AND a signed `checkpoint`. The empty `{}` some early packages carry,
+ * any value missing those fields, and malformed JSON all resolve to null — inclusion
+ * is then simply not verified, never thrown. This is the SINGLE guard the server
+ * route, the browser verify-flow, and the backfill script share (#119 P4), so "what
+ * counts as a real proof" is defined and tested in exactly one place.
+ */
+export function parseInclusionProof(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            Array.isArray(parsed.hashes) &&
+            typeof parsed.checkpoint === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        // malformed proof string ⇒ null
+    }
+    return null;
+}
 // --- RFC 6962 Merkle hashing ----------------------------------------------
 /** Leaf hash: `SHA-256(0x00 ‖ leaf)` (RFC 6962 §2.1). */
 function leafHash(leaf) {

package/dist/rfc3161.js

@@ -22,7 +22,7 @@ import { p384 } from '@noble/curves/nist.js';
 import { sha512 } from '@noble/hashes/sha2.js';
 import { base64ToBytes, bytesToHex } from "./primitives.js";
 import { Asn1Error, readNode, children, content, rawTlv, oidToString, readTime, } from "./asn1.js";
-import { parseCertificate, verifyCertSignatureRsa, bytesEqual, OID_EKU_TIMESTAMPING, } from "./x509.js";
+import { parseCertificate, verifyCertChainToAnchor, bytesEqual, OID_EKU_TIMESTAMPING, } from "./x509.js";
 const OID_SIGNED_DATA = '1.2.840.113549.1.7.2';
 const OID_CT_TSTINFO = '1.2.840.113549.1.9.16.1.4';
 const OID_SHA256 = '2.16.840.1.101.3.4.2.1';
@@ -121,32 +121,38 @@ function parseTstInfo(tst) {
         genTime: readTime(tst, genTimeNode),
     };
 }
+// Map the X.509 chain verifier's precise reason onto this module's vocabulary. The
+// strict-RFC structural/policy rejections (#119 P4) collapse to `chain_incomplete`
+// (the chain could not be trusted) and only a real RSA link failure surfaces as
+// `chain_signature_invalid`; the chain layer keeps the fine-grained reason.
+function toRfc3161ChainReason(reason) {
+    switch (reason) {
+        case 'genTime_outside_validity':
+            return 'genTime_outside_validity';
+        case 'untrusted_root':
+            return 'untrusted_root';
+        case 'link_signature_invalid':
+            return 'chain_signature_invalid';
+        case 'unsupported_critical_extension':
+        case 'algorithm_mismatch':
+        case 'issuer_not_found':
+        case 'issuer_not_ca':
+        case 'path_len_exceeded':
+            return 'chain_incomplete';
+    }
+}
 /**
- * Validate the embedded chain from `leaf` up to a self-signed cert whose key is a
- * pinned root anchor, verifying each link's RSA signature, that issuers are CAs, and
- * that genTime falls within every cert's validity. Returns the matched anchor or a
- * reason. Bounded against cycles/length.
+ * Validate the embedded chain from `leaf` up to a pinned root anchor, delegating to
+ * the strict RFC 5280 verifier in `x509.ts` (each link's RSA signature; CA + keyUsage
+ * keyCertSign on issuers; pathLenConstraint; unknown-critical-extension and inner==
+ * outer-algorithm rejection; validity at genTime). Returns the matched anchor or a
+ * mapped reason.
  */
 async function validateChainToRoot(certs, leaf, anchors, genTime) {
-    let current = leaf;
-    for (let depth = 0; depth < 8; depth++) {
-        if (genTime < current.notBefore || genTime > current.notAfter) {
-            return { ok: false, reason: 'genTime_outside_validity' };
-        }
-        if (bytesEqual(current.issuerDer, current.subjectDer)) {
-            // self-signed: trusted iff its key is pinned.
-            const anchor = anchors.find((a) => bytesEqual(base64ToBytes(a.rootKeyDer), current.spkiDer));
-            return anchor ? { ok: true, tsa: anchor.name } : { ok: false, reason: 'untrusted_root' };
-        }
-        const issuer = certs.find((c) => bytesEqual(c.subjectDer, current.issuerDer));
-        if (!issuer || !issuer.isCA)
-            return { ok: false, reason: 'chain_incomplete' };
-        if (!(await verifyCertSignatureRsa(current, issuer.spkiDer))) {
-            return { ok: false, reason: 'chain_signature_invalid' };
-        }
-        current = issuer;
-    }
-    return { ok: false, reason: 'chain_incomplete' };
+    const result = await verifyCertChainToAnchor(certs, leaf, anchors, genTime);
+    if (result.ok)
+        return { ok: true, tsa: result.anchorName };
+    return { ok: false, reason: toRfc3161ChainReason(result.reason ?? 'issuer_not_found') };
 }
 function fail(base, reason) {
     return { ...base, reason };

package/dist/x509.d.ts

@@ -5,6 +5,12 @@ export interface X509Cert {
     tbsBytes: Uint8Array;
     /** Outer signatureAlgorithm OID. */
     sigAlgOid: string;
+    /** Outer signatureAlgorithm AlgorithmIdentifier (raw TLV). */
+    sigAlgDer: Uint8Array;
+    /** Inner TBSCertificate.signature AlgorithmIdentifier (raw TLV). */
+    innerSigAlgDer: Uint8Array;
+    /** Inner == outer signature AlgorithmIdentifier, byte-for-byte (check (d)). */
+    sigAlgConsistent: boolean;
     /** signatureValue (BIT STRING content, the leading unused-bits octet dropped). */
     signature: Uint8Array;
     /** SubjectPublicKeyInfo (raw TLV) — this cert's public key. */
@@ -20,6 +26,12 @@ export interface X509Cert {
     ekus: string[];
     /** basicConstraints cA:TRUE. */
     isCA: boolean;
+    /** keyUsage asserts keyCertSign (false if keyUsage is absent — check (b)). */
+    keyCertSign: boolean;
+    /** basicConstraints pathLenConstraint, or null when absent/unconstrained (check (c)). */
+    pathLen: number | null;
+    /** Carries a critical extension this verifier does not recognize (check (a)). */
+    hasUnknownCriticalExt: boolean;
 }
 /** Parse a Certificate (SEQUENCE { tbsCertificate, signatureAlgorithm, signature }). */
 export declare function parseCertificate(buf: Uint8Array, node: DerNode): X509Cert;
@@ -31,3 +43,27 @@ export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
  * algorithm or any verification error.
  */
 export declare function verifyCertSignatureRsa(cert: X509Cert, issuerSpkiDer: Uint8Array): Promise<boolean>;
+/** A pinned trust anchor: a root whose public key is trusted by value. */
+export interface ChainAnchor {
+    name: string;
+    /** Root public key, base64 SPKI DER. */
+    rootKeyDer: string;
+}
+export type ChainFailReason = 'unsupported_critical_extension' | 'algorithm_mismatch' | 'genTime_outside_validity' | 'issuer_not_found' | 'issuer_not_ca' | 'path_len_exceeded' | 'link_signature_invalid' | 'untrusted_root';
+export interface ChainResult {
+    /** The path links to a pinned anchor and every strict check passed. */
+    ok: boolean;
+    /** The matched anchor's name, when `ok`. */
+    anchorName?: string;
+    /** The first check that failed, otherwise. */
+    reason?: ChainFailReason;
+}
+/**
+ * Validate the embedded chain from `leaf` up to a self-signed cert whose key is a
+ * pinned anchor, applying the strict RFC 5280 checks (a)-(d) documented at the top of
+ * this module. `atTime` (epoch ms) is the instant every cert's validity is checked
+ * against (the RFC 3161 genTime, for a TSA chain). Each link's RSA signature is
+ * verified via WebCrypto. Async; never throws — a structural/policy failure is
+ * reported as a `reason`. Bounded against cycles and runaway length.
+ */
+export declare function verifyCertChainToAnchor(certs: X509Cert[], leaf: X509Cert, anchors: readonly ChainAnchor[], atTime: number): Promise<ChainResult>;

package/dist/x509.js

@@ -1,14 +1,52 @@
-// Minimal X.509 certificate parsing (civic-ai-tools-website#119 P2b) — browser-safe.
+// Minimal X.509 certificate parsing + chain validation (civic-ai-tools-website#119
+// P2b/P4) — browser-safe.
 //
 // Just enough of RFC 5280 to validate the RFC 3161 token's embedded cert chain: the
 // signed TBSCertificate bytes, the outer signature + algorithm, the public key, the
 // validity window, issuer/subject (for chain linking), the serial (to match the CMS
-// signer), and the two extensions we gate on (EKU, basicConstraints). Built on the
-// strict-DER `asn1.ts` reader, so malformed certs throw rather than mis-parse.
+// signer), and the extensions we gate on (EKU, basicConstraints, keyUsage). Built on
+// the strict-DER `asn1.ts` reader, so malformed certs throw rather than mis-parse.
+//
+// STRICT RFC 5280 COMPLIANCE (#119 P4). `verifyCertChainToAnchor` is the pinned-root
+// chain verifier; it fails CLOSED on four checks that a conforming verifier MUST
+// enforce. Under the pinned FreeTSA root these are non-exploitable (the root issues a
+// well-formed chain), so they are defence-in-depth / strict-RFC hardening, and each
+// has a fail-closed negative test (mint-forged certs) in `x509.test.ts`:
+//   (a) UNKNOWN CRITICAL EXTENSIONS are rejected (RFC 5280 §4.2: a system MUST reject
+//       a certificate with a critical extension it does not recognize). The recognized
+//       set is { basicConstraints, keyUsage, extKeyUsage }; any other critical
+//       extension sets `hasUnknownCriticalExt`.
+//   (b) An issuer is trusted to sign certificates only if it is a CA (basicConstraints
+//       cA:TRUE) AND its keyUsage asserts keyCertSign (RFC 5280 §4.2.1.3) — both, or
+//       the link is rejected as `issuer_not_ca`.
+//   (c) basicConstraints pathLenConstraint is enforced DOWN the chain (§4.2.1.9): an
+//       issuer with pathLen=n may have at most n intermediate CAs beneath it.
+//   (d) The inner TBSCertificate.signature AlgorithmIdentifier MUST byte-equal the
+//       outer signatureAlgorithm (§4.1.1.2) — an anti algorithm-substitution check;
+//       a mismatch sets `sigAlgConsistent=false` and the link is rejected.
 import { readNode, children, content, rawTlv, oidToString, readTime, Asn1Error, } from "./asn1.js";
+import { base64ToBytes } from "./primitives.js";
 export const OID_EKU_TIMESTAMPING = '1.3.6.1.5.5.7.3.8';
 const OID_EXT_EKU = '2.5.29.37';
 const OID_EXT_BASIC_CONSTRAINTS = '2.5.29.19';
+const OID_EXT_KEY_USAGE = '2.5.29.15';
+// Critical extensions a conforming verifier recognizes and processes (check (a)).
+// A critical extension OUTSIDE this set means the cert MUST be rejected.
+const RECOGNIZED_CRITICAL_EXTS = new Set([
+    OID_EXT_EKU,
+    OID_EXT_BASIC_CONSTRAINTS,
+    OID_EXT_KEY_USAGE,
+]);
+// keyUsage is a DER BIT STRING; keyCertSign is bit 5 (RFC 5280 §4.2.1.3), i.e. the
+// 0x04 bit of the first data octet (content is [unusedBits, byte0, …]).
+const KEY_CERT_SIGN_BIT = 0x04;
+/** Read a small non-negative DER INTEGER's content as a Number (used for pathLen). */
+function readUint(bytes) {
+    let n = 0;
+    for (const b of bytes)
+        n = n * 256 + b; // *256, not <<8, to avoid 32-bit overflow
+    return n;
+}
 /** Parse a Certificate (SEQUENCE { tbsCertificate, signatureAlgorithm, signature }). */
 export function parseCertificate(buf, node) {
     const [tbs, sigAlg, sigBits] = children(buf, node);
@@ -21,38 +59,66 @@ export function parseCertificate(buf, node) {
     if (tk[i]?.tag === 0xa0)
         i++; // optional version [0]
     const serial = content(buf, tk[i++]);
-    i++; // inner signature AlgorithmIdentifier (redundant; skip)
+    const innerSigAlg = tk[i++]; // inner signature AlgorithmIdentifier (check (d))
     const issuer = tk[i++];
     const validity = tk[i++];
     const subject = tk[i++];
     const spki = tk[i++];
-    if (!issuer || !validity || !subject || !spki)
+    if (!innerSigAlg || !issuer || !validity || !subject || !spki) {
         throw new Asn1Error('malformed TBSCertificate');
+    }
     const [nb, na] = children(buf, validity);
     if (!nb || !na)
         throw new Asn1Error('malformed Validity');
     const ekus = [];
     let isCA = false;
+    let keyCertSign = false;
+    let pathLen = null;
+    let hasUnknownCriticalExt = false;
     const extsWrap = tk.slice(i).find((c) => c.tag === 0xa3); // extensions [3] EXPLICIT
     if (extsWrap) {
         for (const ext of children(buf, children(buf, extsWrap)[0])) {
             const ec = children(buf, ext); // Extension { extnID OID, critical BOOL?, extnValue OCTET }
             const oid = oidToString(buf, ec[0]);
+            // critical BOOLEAN DEFAULT FALSE: present iff a BOOLEAN precedes extnValue.
+            const critical = ec.length === 3 && ec[1]?.tag === 0x01 && content(buf, ec[1])[0] === 0xff;
+            if (critical && !RECOGNIZED_CRITICAL_EXTS.has(oid))
+                hasUnknownCriticalExt = true; // (a)
             const value = content(buf, ec[ec.length - 1]); // extnValue OCTET STRING content (nested DER)
             if (oid === OID_EXT_EKU) {
                 for (const kp of children(value, readNode(value, 0)))
                     ekus.push(oidToString(value, kp));
             }
             else if (oid === OID_EXT_BASIC_CONSTRAINTS) {
+                // BasicConstraints ::= SEQUENCE { cA BOOLEAN DEFAULT FALSE,
+                //                                 pathLenConstraint INTEGER (0..MAX) OPTIONAL }
                 const bc = children(value, readNode(value, 0));
-                if (bc[0]?.tag === 0x01 && content(value, bc[0])[0] === 0xff)
-                    isCA = true;
+                let b = 0;
+                if (bc[b]?.tag === 0x01) {
+                    if (content(value, bc[b])[0] === 0xff)
+                        isCA = true;
+                    b++;
+                }
+                if (bc[b]?.tag === 0x02)
+                    pathLen = readUint(content(value, bc[b])); // (c)
+            }
+            else if (oid === OID_EXT_KEY_USAGE) {
+                const ku = readNode(value, 0); // BIT STRING
+                if (ku.tag === 0x03) {
+                    const bits = content(value, ku); // [unusedBits, byte0, …]
+                    keyCertSign = bits.length >= 2 && (bits[1] & KEY_CERT_SIGN_BIT) !== 0; // (b)
+                }
             }
         }
     }
+    const sigAlgDer = rawTlv(buf, sigAlg);
+    const innerSigAlgDer = rawTlv(buf, innerSigAlg);
     return {
         tbsBytes: rawTlv(buf, tbs),
         sigAlgOid: oidToString(buf, children(buf, sigAlg)[0]),
+        sigAlgDer,
+        innerSigAlgDer,
+        sigAlgConsistent: bytesEqual(innerSigAlgDer, sigAlgDer), // (d)
         signature: content(buf, sigBits).slice(1),
         spkiDer: rawTlv(buf, spki),
         serial,
@@ -62,6 +128,9 @@ export function parseCertificate(buf, node) {
         notAfter: readTime(buf, na),
         ekus,
         isCA,
+        keyCertSign,
+        pathLen,
+        hasUnknownCriticalExt,
     };
 }
 export function bytesEqual(a, b) {
@@ -99,3 +168,49 @@ export async function verifyCertSignatureRsa(cert, issuerSpkiDer) {
         return false;
     }
 }
+// A self-issued chain deeper than this is rejected (cycle / runaway guard). The real
+// TSA chain is depth 1 (leaf → root); 8 is generous headroom for intermediates.
+const MAX_CHAIN_DEPTH = 8;
+/**
+ * Validate the embedded chain from `leaf` up to a self-signed cert whose key is a
+ * pinned anchor, applying the strict RFC 5280 checks (a)-(d) documented at the top of
+ * this module. `atTime` (epoch ms) is the instant every cert's validity is checked
+ * against (the RFC 3161 genTime, for a TSA chain). Each link's RSA signature is
+ * verified via WebCrypto. Async; never throws — a structural/policy failure is
+ * reported as a `reason`. Bounded against cycles and runaway length.
+ */
+export async function verifyCertChainToAnchor(certs, leaf, anchors, atTime) {
+    let current = leaf;
+    // `depth` doubles as the count of intermediate CAs between the current issuer and
+    // the leaf: at depth 0 the issuer signs the end-entity directly (0 intermediates),
+    // at depth k there are k intermediates beneath it — exactly the pathLen budget (c).
+    for (let depth = 0; depth < MAX_CHAIN_DEPTH; depth++) {
+        if (current.hasUnknownCriticalExt) {
+            return { ok: false, reason: 'unsupported_critical_extension' }; // (a)
+        }
+        if (!current.sigAlgConsistent) {
+            return { ok: false, reason: 'algorithm_mismatch' }; // (d)
+        }
+        if (atTime < current.notBefore || atTime > current.notAfter) {
+            return { ok: false, reason: 'genTime_outside_validity' };
+        }
+        if (bytesEqual(current.issuerDer, current.subjectDer)) {
+            // Self-signed terminus: trusted iff its key is a pinned anchor.
+            const anchor = anchors.find((a) => bytesEqual(base64ToBytes(a.rootKeyDer), current.spkiDer));
+            return anchor ? { ok: true, anchorName: anchor.name } : { ok: false, reason: 'untrusted_root' };
+        }
+        const issuer = certs.find((c) => bytesEqual(c.subjectDer, current.issuerDer));
+        if (!issuer)
+            return { ok: false, reason: 'issuer_not_found' };
+        if (!issuer.isCA || !issuer.keyCertSign)
+            return { ok: false, reason: 'issuer_not_ca' }; // (b)
+        if (issuer.pathLen !== null && depth > issuer.pathLen) {
+            return { ok: false, reason: 'path_len_exceeded' }; // (c)
+        }
+        if (!(await verifyCertSignatureRsa(current, issuer.spkiDer))) {
+            return { ok: false, reason: 'link_signature_invalid' };
+        }
+        current = issuer;
+    }
+    return { ok: false, reason: 'issuer_not_found' };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typedstandards/verify-core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Portable, browser-safe verification core for Typed Standards evidence packages — the §9.2 check suite, single-sourced so it verifies identically on a server and in the browser.",
   "license": "MIT",
   "author": "Nathan Storey",