@int-loop/core 0.1.0 → 0.3.0

package/dist/x509.js

@@ -0,0 +1,329 @@
+// X.509 certificates, as far as checking a timestamp authority's signature needs:
+// parsing, signature verification with WebCrypto, and building a chain from the
+// TSA's signing certificate to a trusted root at the moment of the timestamp.
+//
+// Trust anchors are matched by name and public key, not by exact bytes, because TSAs
+// send cross-signed copies of their roots alongside the chain.
+//
+// Not checked here: revocation (CRLs, OCSP). An evidence pack records the chain as the
+// TSA presented it; see DECISIONS.md, 2026-11-09.
+import { bytesEqual, concatBytes, toBase64Url } from "./hash.js";
+import { children, expectTag, readBitStringBytes, readBoolean, readDer, readIntegerBytes, readOctetString, readOid, readSmallInt, readTime, seq, TAG, contextTag } from "./der.js";
+export const OID = {
+    rsaEncryption: "1.2.840.113549.1.1.1",
+    sha256WithRSA: "1.2.840.113549.1.1.11",
+    sha384WithRSA: "1.2.840.113549.1.1.12",
+    sha512WithRSA: "1.2.840.113549.1.1.13",
+    ecPublicKey: "1.2.840.10045.2.1",
+    ecdsaWithSHA256: "1.2.840.10045.4.3.2",
+    ecdsaWithSHA384: "1.2.840.10045.4.3.3",
+    ecdsaWithSHA512: "1.2.840.10045.4.3.4",
+    p256: "1.2.840.10045.3.1.7",
+    p384: "1.3.132.0.34",
+    p521: "1.3.132.0.35",
+    sha1: "1.3.14.3.2.26",
+    sha256: "2.16.840.1.101.3.4.2.1",
+    sha384: "2.16.840.1.101.3.4.2.2",
+    sha512: "2.16.840.1.101.3.4.2.3",
+    commonName: "2.5.4.3",
+    organisation: "2.5.4.10",
+    subjectKeyIdentifier: "2.5.29.14",
+    keyUsage: "2.5.29.15",
+    subjectAltName: "2.5.29.17",
+    basicConstraints: "2.5.29.19",
+    crlDistributionPoints: "2.5.29.31",
+    certificatePolicies: "2.5.29.32",
+    authorityKeyIdentifier: "2.5.29.35",
+    extKeyUsage: "2.5.29.37",
+    authorityInfoAccess: "1.3.6.1.5.5.7.1.1",
+    kpTimeStamping: "1.3.6.1.5.5.7.3.8",
+    anyExtendedKeyUsage: "2.5.29.37.0",
+};
+export const HASH_BY_OID = {
+    [OID.sha1]: "SHA-1",
+    [OID.sha256]: "SHA-256",
+    [OID.sha384]: "SHA-384",
+    [OID.sha512]: "SHA-512",
+};
+/** Signature algorithms accepted, with the hash each implies. */
+const SIGNATURE_ALGS = {
+    [OID.sha256WithRSA]: { kind: "rsa", hash: "SHA-256" },
+    [OID.sha384WithRSA]: { kind: "rsa", hash: "SHA-384" },
+    [OID.sha512WithRSA]: { kind: "rsa", hash: "SHA-512" },
+    [OID.ecdsaWithSHA256]: { kind: "ecdsa", hash: "SHA-256" },
+    [OID.ecdsaWithSHA384]: { kind: "ecdsa", hash: "SHA-384" },
+    [OID.ecdsaWithSHA512]: { kind: "ecdsa", hash: "SHA-512" },
+};
+const CURVES = {
+    [OID.p256]: { name: "P-256", size: 32 },
+    [OID.p384]: { name: "P-384", size: 48 },
+    [OID.p521]: { name: "P-521", size: 66 },
+};
+/** Extensions this code understands, or that do not bear on trusting a timestamp. Any other critical extension fails the certificate. */
+const HANDLED_EXTENSIONS = new Set([
+    OID.subjectKeyIdentifier,
+    OID.keyUsage,
+    OID.subjectAltName,
+    OID.basicConstraints,
+    OID.crlDistributionPoints,
+    OID.certificatePolicies,
+    OID.authorityKeyIdentifier,
+    OID.extKeyUsage,
+    OID.authorityInfoAccess,
+]);
+const KEY_USAGE_KEY_CERT_SIGN = 5;
+export function parseCertificate(bytes) {
+    const top = readDer(bytes);
+    const [tbsEl, algEl, sigEl, ...extra] = seq(top, "certificate");
+    if (extra.length)
+        throw new Error("certificate has trailing elements");
+    const tbs = seq(tbsEl, "tbsCertificate");
+    let i = 0;
+    if (tbs[0]?.tag === contextTag(0)) {
+        const [v] = children(tbs[0]);
+        if (readIntegerBytes(v, "version")[0] !== 2)
+            throw new Error("only X.509 v3 certificates are supported");
+        i++;
+    }
+    else {
+        throw new Error("only X.509 v3 certificates are supported");
+    }
+    const serial = readIntegerBytes(tbs[i++], "serial number");
+    const innerAlg = readOid(seq(tbs[i++], "signature algorithm")[0]);
+    const issuer = expectTag(tbs[i++], TAG.SEQUENCE, "issuer").raw;
+    const [nb, na] = seq(tbs[i++], "validity");
+    const subjectEl = expectTag(tbs[i++], TAG.SEQUENCE, "subject");
+    const spki = expectTag(tbs[i++], TAG.SEQUENCE, "subjectPublicKeyInfo").raw;
+    const extensions = new Map();
+    for (; i < tbs.length; i++) {
+        const el = tbs[i];
+        if (el.tag === contextTag(1, false) || el.tag === contextTag(2, false))
+            continue; // unique identifiers
+        if (el.tag !== contextTag(3))
+            throw new Error("unexpected element in tbsCertificate");
+        for (const ext of seq(children(el)[0], "extensions")) {
+            const parts = seq(ext, "extension");
+            const oid = readOid(parts[0]);
+            if (parts.length !== 2 && parts.length !== 3)
+                throw new Error("malformed extension");
+            const critical = parts.length === 3 ? readBoolean(parts[1], "critical") : false;
+            if (extensions.has(oid))
+                throw new Error(`duplicate extension ${oid}`);
+            extensions.set(oid, { critical, value: readOctetString(parts[parts.length - 1], "extension value") });
+        }
+    }
+    const signatureAlg = readOid(seq(algEl, "signatureAlgorithm")[0]);
+    if (signatureAlg !== innerAlg)
+        throw new Error("the two signature algorithm fields disagree");
+    return {
+        raw: top.raw,
+        tbs: tbsEl.raw,
+        signatureAlg,
+        signature: readBitStringBytes(sigEl, "signature"),
+        serial,
+        issuer,
+        subject: subjectEl.raw,
+        name: readableName(subjectEl),
+        notBefore: readTime(nb, "notBefore"),
+        notAfter: readTime(na, "notAfter"),
+        spki,
+        extensions,
+    };
+}
+function readableName(name) {
+    const attrs = new Map();
+    for (const rdn of seq(name, "name")) {
+        for (const atv of seq(rdn, "relative distinguished name", TAG.SET)) {
+            const [type, value] = seq(atv, "attribute");
+            attrs.set(readOid(type), new TextDecoder().decode(value.content));
+        }
+    }
+    return attrs.get(OID.commonName) ?? attrs.get(OID.organisation) ?? "(unnamed)";
+}
+/** basicConstraints: whether this is a CA, and how many intermediate CAs may follow it (null: no limit). */
+export function basicConstraints(cert) {
+    const bc = cert.extensions.get(OID.basicConstraints);
+    if (!bc)
+        return { ca: false, pathLen: null };
+    const parts = seq(readDer(bc.value), "basicConstraints");
+    let i = 0;
+    const ca = parts[0]?.tag === TAG.BOOLEAN ? readBoolean(parts[i++], "cA") : false;
+    const pathLen = parts[i] ? readSmallInt(parts[i++], "pathLenConstraint") : null;
+    if (i !== parts.length)
+        throw new Error("malformed basicConstraints");
+    return { ca, pathLen };
+}
+export function isCa(cert) {
+    return basicConstraints(cert).ca;
+}
+/** Whether the key usage extension allows `bit`. An absent extension permits every use. */
+export function keyUsageAllows(cert, bit) {
+    const ku = cert.extensions.get(OID.keyUsage);
+    if (!ku)
+        return true;
+    const c = expectTag(readDer(ku.value), TAG.BIT_STRING, "keyUsage").content;
+    const byte = c[1 + Math.floor(bit / 8)] ?? 0;
+    return (byte & (0x80 >> bit % 8)) !== 0;
+}
+export function extendedKeyUsage(cert) {
+    const eku = cert.extensions.get(OID.extKeyUsage);
+    if (!eku)
+        return null;
+    return { critical: eku.critical, purposes: seq(readDer(eku.value), "extKeyUsage").map((p) => readOid(p)) };
+}
+export function subjectKeyIdentifier(cert) {
+    const ski = cert.extensions.get(OID.subjectKeyIdentifier);
+    return ski ? readOctetString(readDer(ski.value), "subjectKeyIdentifier") : null;
+}
+/**
+ * Verifies `signature` over `data` with the key in `spki`. `alg` is a signature algorithm OID,
+ * or rsaEncryption / ecPublicKey with the hash given separately (as CMS signer infos do).
+ */
+export async function verifySignature(spki, alg, signature, data, hash) {
+    const known = SIGNATURE_ALGS[alg];
+    const kind = known?.kind ?? (alg === OID.rsaEncryption ? "rsa" : alg === OID.ecPublicKey ? "ecdsa" : null);
+    const useHash = known?.hash ?? hash;
+    if (!kind || !useHash)
+        throw new Error(`unsupported signature algorithm ${alg}`);
+    if (useHash === "SHA-1")
+        throw new Error("SHA-1 signatures are not accepted");
+    const [algId] = seq(readDer(spki), "subjectPublicKeyInfo");
+    const [keyAlg, params] = seq(algId, "public key algorithm");
+    const keyOid = readOid(keyAlg);
+    if (kind === "rsa") {
+        if (keyOid !== OID.rsaEncryption)
+            throw new Error("signature algorithm does not match the key type");
+        const key = await crypto.subtle.importKey("spki", spki, { name: "RSASSA-PKCS1-v1_5", hash: useHash }, false, ["verify"]);
+        if (key.algorithm.modulusLength < 2048)
+            throw new Error("RSA keys under 2048 bits are not accepted");
+        return crypto.subtle.verify({ name: "RSASSA-PKCS1-v1_5" }, key, new Uint8Array(signature), data);
+    }
+    if (keyOid !== OID.ecPublicKey)
+        throw new Error("signature algorithm does not match the key type");
+    const curve = CURVES[readOid(params, "curve")];
+    if (!curve)
+        throw new Error("unsupported elliptic curve");
+    const key = await crypto.subtle.importKey("spki", spki, { name: "ECDSA", namedCurve: curve.name }, false, ["verify"]);
+    return crypto.subtle.verify({ name: "ECDSA", hash: useHash }, key, ecdsaDerToRaw(signature, curve.size), data);
+}
+/** X.509 and CMS carry ECDSA signatures as DER SEQUENCE { r, s }; WebCrypto wants r || s. */
+export function ecdsaDerToRaw(der, size) {
+    const [r, s, ...extra] = seq(readDer(der), "ECDSA signature");
+    if (extra.length)
+        throw new Error("ECDSA signature has trailing elements");
+    const fixed = (el) => {
+        let int = readIntegerBytes(el, "ECDSA signature value");
+        // r and s are positive; a negative encoding would let one signature be written two ways.
+        if ((int[0] & 0x80) !== 0)
+            throw new Error("negative ECDSA signature value");
+        while (int.length > size && int[0] === 0)
+            int = int.subarray(1);
+        if (int.length > size)
+            throw new Error("ECDSA signature value too long");
+        const out = new Uint8Array(size);
+        out.set(int, size - int.length);
+        return out;
+    };
+    return concatBytes(fixed(r), fixed(s));
+}
+const MAX_CHAIN = 6;
+/** Every signature checked while building one chain. Hostile input could otherwise make the search exponential. */
+const MAX_SIGNATURE_CHECKS = 24;
+/**
+ * Builds a chain from `leaf` to one of `anchors`, through `intermediates`, with every
+ * certificate, the anchor included, valid at `at` (the timestamp's own time). The anchor is
+ * reached when a certificate's issuer has an anchor's name and the anchor's key verifies
+ * it, or when a certificate has an anchor's name and key itself (a cross-signed copy).
+ *
+ * Every issuer, the anchor included, must be a CA allowed to sign certificates, within its
+ * path length constraint, and either without an extended key usage or with one that allows
+ * timestamping. The search is bounded: at most MAX_CHAIN deep, each (name, key) once per
+ * path, and MAX_SIGNATURE_CHECKS signatures in all.
+ */
+export async function buildChain(leaf, intermediates, anchors, at) {
+    let checks = 0;
+    const signedBy = async (cert, issuer) => {
+        if (++checks > MAX_SIGNATURE_CHECKS)
+            throw new ChainBudgetError();
+        try {
+            return await verifySignature(issuer.spki, cert.signatureAlg, cert.signature, cert.tbs);
+        }
+        catch {
+            return false;
+        }
+    };
+    const sameKey = (a, b) => bytesEqual(a.subject, b.subject) && bytesEqual(a.spki, b.spki);
+    // depth: the leaf is 0, its issuer 1, and so on. An issuer at depth d has d - 1 intermediate CAs below it.
+    const visit = async (cert, depth, path, onPath) => {
+        const problem = certificateProblem(cert, at, depth);
+        if (problem)
+            return { ok: false, reason: `${cert.name}: ${problem}` };
+        const copyOf = anchors.find((a) => sameKey(a, cert));
+        if (copyOf) {
+            const anchorProblem = certificateProblem(copyOf, at, depth);
+            return anchorProblem ? { ok: false, reason: `${copyOf.name}: ${anchorProblem}` } : { ok: true, path, anchor: copyOf };
+        }
+        for (const anchor of anchors) {
+            if (!bytesEqual(anchor.subject, cert.issuer) || !(await signedBy(cert, anchor)))
+                continue;
+            const anchorProblem = certificateProblem(anchor, at, depth + 1);
+            if (anchorProblem)
+                return { ok: false, reason: `${anchor.name}: ${anchorProblem}` };
+            return { ok: true, path: [...path, anchor.name], anchor };
+        }
+        if (depth + 1 >= MAX_CHAIN)
+            return { ok: false, reason: "certificate chain too long" };
+        let last = { ok: false, reason: `${cert.name}: issuer is not a trusted timestamp root and no issuing certificate was supplied` };
+        for (const parent of intermediates) {
+            if (onPath.some((c) => sameKey(c, parent)) || !bytesEqual(parent.subject, cert.issuer))
+                continue;
+            if (!(await signedBy(cert, parent))) {
+                last = { ok: false, reason: `${cert.name}: signature does not verify against ${parent.name}` };
+                continue;
+            }
+            const result = await visit(parent, depth + 1, [...path, parent.name], [...onPath, parent]);
+            if (result.ok)
+                return result;
+            last = result;
+        }
+        return last;
+    };
+    try {
+        return await visit(leaf, 0, [leaf.name], [leaf]);
+    }
+    catch (err) {
+        if (err instanceof ChainBudgetError)
+            return { ok: false, reason: "too many candidate certificates to check" };
+        throw err;
+    }
+}
+class ChainBudgetError extends Error {
+}
+/**
+ * Why `cert` cannot be at `depth` in a chain at time `at`, or null. Depth 0 is the leaf, whose
+ * purpose the caller checks; anything above it issues certificates.
+ */
+function certificateProblem(cert, at, depth) {
+    if (at < cert.notBefore || at > cert.notAfter)
+        return `not valid at ${new Date(at).toISOString()}`;
+    for (const [oid, ext] of cert.extensions)
+        if (ext.critical && !HANDLED_EXTENSIONS.has(oid))
+            return `unsupported critical extension ${oid}`;
+    if (depth === 0)
+        return null;
+    const bc = basicConstraints(cert);
+    if (!bc.ca)
+        return "is not a certificate authority";
+    if (!keyUsageAllows(cert, KEY_USAGE_KEY_CERT_SIGN))
+        return "is not allowed to sign certificates";
+    if (bc.pathLen !== null && depth - 1 > bc.pathLen)
+        return `its path length constraint (${bc.pathLen}) does not allow this chain`;
+    const eku = extendedKeyUsage(cert);
+    if (eku && !eku.purposes.includes(OID.kpTimeStamping) && !eku.purposes.includes(OID.anyExtendedKeyUsage))
+        return "is not authorised for timestamping (extended key usage)";
+    return null;
+}
+/** SHA-256 fingerprint, base64url, for reports and pinning. */
+export async function certificateFingerprint(cert) {
+    return toBase64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", cert.raw)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@int-loop/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Schemas, canonicalisation, hashing, passkey binding and ledger and receipt verification shared by the int-loop service and int-loop-verify.",
   "license": "Apache-2.0",
   "homepage": "https://int-loop.com",