@int-loop/core 0.1.0 → 0.2.0

package/dist/tsp.js

@@ -0,0 +1,228 @@
+// RFC 3161 timestamps: building a request, reading the reply and verifying the token.
+//
+// A token is a CMS SignedData whose content is a TSTInfo: the hash that was stamped, the
+// time, a serial number and the nonce we sent. Verifying it means checking the hash and
+// nonce, the CMS signature over the signed attributes, the binding of the signing
+// certificate (ESS signingCertificate), the certificate's timestamping purpose, and a
+// chain to a trusted root valid at the stamped time. Pure: the nonce is passed in.
+import { bytesEqual, concatBytes, toHex } from "./hash.js";
+import { children, contextTag, encodeBoolean, encodeNull, encodeOctetString, encodeOid, encodeSequence, encodeSmallInt, encodeUnsignedInteger, expectTag, readDer, readIntegerBytes, readOctetString, readOid, readSmallInt, readTime, seq, TAG, } from "./der.js";
+import { buildChain, extendedKeyUsage, HASH_BY_OID, keyUsageAllows, OID, parseCertificate, subjectKeyIdentifier, verifySignature } from "./x509.js";
+const CMS = {
+    signedData: "1.2.840.113549.1.7.2",
+    tstInfo: "1.2.840.113549.1.9.16.1.4",
+    contentType: "1.2.840.113549.1.9.3",
+    messageDigest: "1.2.840.113549.1.9.4",
+    signingCertificate: "1.2.840.113549.1.9.16.2.12",
+    signingCertificateV2: "1.2.840.113549.1.9.16.2.47",
+};
+const KEY_USAGE_DIGITAL_SIGNATURE = 0;
+/** Real TSAs send three or four; more is not a token worth reading. */
+const MAX_CERTIFICATES = 8;
+const KEY_USAGE_NON_REPUDIATION = 1;
+/** A TimeStampReq for a SHA-256 digest, asking for the signing certificate to be included. */
+export function buildTimestampRequest(digest, nonce) {
+    if (digest.length !== 32)
+        throw new Error("expected a 32-byte SHA-256 digest");
+    return encodeSequence(encodeSmallInt(1), encodeSequence(encodeSequence(encodeOid(OID.sha256), encodeNull()), encodeOctetString(digest)), encodeUnsignedInteger(nonce), encodeBoolean(true));
+}
+/** Reads a TimeStampResp. A refusal is a result, not an error; malformed bytes throw. */
+export function parseTimestampReply(bytes) {
+    const [statusInfo, token, ...extra] = seq(readDer(bytes), "TimeStampResp");
+    if (extra.length)
+        throw new Error("TimeStampResp has trailing elements");
+    const [status, ...rest] = seq(statusInfo, "PKIStatusInfo");
+    const code = readSmallInt(status, "PKIStatus");
+    if (code !== 0 && code !== 1) {
+        const text = rest[0]?.tag === TAG.SEQUENCE ? children(rest[0]).map((s) => new TextDecoder().decode(s.content)).join("; ") : "";
+        return { granted: false, reason: `the TSA refused the request (status ${code}${text ? `: ${text}` : ""})` };
+    }
+    if (!token)
+        throw new Error("the TSA granted the request but sent no token");
+    return { granted: true, token: token.raw };
+}
+/** Verifies a TimeStampToken. Never throws: anything malformed is a failure. */
+export async function verifyTimestampToken(token, expect) {
+    try {
+        return await verifyUnsafe(token, expect);
+    }
+    catch (err) {
+        return { ok: false, reason: `malformed timestamp token: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+async function verifyUnsafe(token, expect) {
+    const fail = (reason) => ({ ok: false, reason });
+    // ContentInfo { id-signedData, [0] EXPLICIT SignedData }
+    const [ctype, wrapped, ...ciExtra] = seq(readDer(token), "ContentInfo");
+    if (ciExtra.length || readOid(ctype) !== CMS.signedData)
+        return fail("not a CMS SignedData");
+    const [signedData, ...wrapExtra] = children(expectTag(wrapped, contextTag(0), "SignedData wrapper"));
+    if (wrapExtra.length)
+        return fail("SignedData wrapper has trailing elements");
+    const sd = seq(signedData, "SignedData");
+    const encap = seq(sd[2], "encapContentInfo");
+    if (encap.length !== 2)
+        return fail("encapContentInfo must carry exactly the TSTInfo");
+    if (readOid(encap[0]) !== CMS.tstInfo)
+        return fail("the signed content is not a TSTInfo");
+    const [eContentEl] = children(expectTag(encap[1], contextTag(0), "eContent wrapper"));
+    const eContent = readOctetString(eContentEl, "eContent");
+    const certificates = [];
+    let k = 3;
+    if (sd[k]?.tag === contextTag(0)) {
+        const certs = children(sd[k++]);
+        if (certs.length > MAX_CERTIFICATES)
+            return fail(`the token carries ${certs.length} certificates; at most ${MAX_CERTIFICATES} are read`);
+        certificates.push(...certs.map((c) => parseCertificate(c.raw)));
+    }
+    if (sd[k]?.tag === contextTag(1))
+        k++; // CRLs: not used
+    const signerInfos = seq(sd[k++], "signerInfos", TAG.SET);
+    if (k !== sd.length)
+        return fail("SignedData has trailing elements");
+    if (signerInfos.length !== 1)
+        return fail(`expected one signer, found ${signerInfos.length}`);
+    // TSTInfo
+    const tst = parseTstInfo(eContent);
+    if (tst.imprintAlg !== OID.sha256)
+        return fail("the stamped hash is not SHA-256");
+    if (!bytesEqual(tst.imprint, expect.digest))
+        return fail("the timestamp is for a different hash");
+    if (expect.nonce !== undefined && (tst.nonce === null || !bytesEqual(tst.nonce, readIntegerBytes(readDer(encodeUnsignedInteger(expect.nonce)))))) {
+        return fail("the nonce does not match the request");
+    }
+    // SignerInfo
+    const si = seq(signerInfos[0], "SignerInfo");
+    const sid = si[1];
+    const digestAlg = readOid(seq(si[2], "digestAlgorithm")[0]);
+    const hash = HASH_BY_OID[digestAlg];
+    if (!hash || hash === "SHA-1")
+        return fail(`unsupported digest algorithm ${digestAlg}`);
+    const signedAttrsEl = expectTag(si[3], contextTag(0), "signedAttrs");
+    const sigAlg = readOid(seq(si[4], "signatureAlgorithm")[0]);
+    const signature = readOctetString(si[5], "signature");
+    if (si.length > 7 || (si.length === 7 && si[6].tag !== contextTag(1)))
+        return fail("SignerInfo has unexpected elements");
+    const attrs = new Map();
+    for (const attr of children(signedAttrsEl)) {
+        const [type, values] = seq(attr, "attribute");
+        const oid = readOid(type);
+        const vs = seq(values, "attribute values", TAG.SET);
+        if (attrs.has(oid) || vs.length !== 1)
+            return fail(`signed attribute ${oid} must appear once with one value`);
+        attrs.set(oid, vs[0]);
+    }
+    if (readOid(attrs.get(CMS.contentType), "contentType attribute") !== CMS.tstInfo)
+        return fail("contentType attribute is not TSTInfo");
+    const contentDigest = new Uint8Array(await crypto.subtle.digest(hash, eContent));
+    if (!bytesEqual(readOctetString(attrs.get(CMS.messageDigest), "messageDigest attribute"), contentDigest))
+        return fail("messageDigest does not match the TSTInfo");
+    // The signer's certificate: identified by the SignerInfo and bound by ESS signingCertificate.
+    const signer = certificates.find((c) => matchesSid(c, sid));
+    if (!signer)
+        return fail("the token does not include the signing certificate");
+    const essProblem = await checkSigningCertificate(signer, attrs);
+    if (essProblem)
+        return fail(essProblem);
+    // The signature covers the DER of the signed attributes, re-tagged as a SET.
+    const signed = concatBytes(Uint8Array.of(TAG.SET), signedAttrsEl.raw.subarray(1));
+    let valid = false;
+    try {
+        valid = await verifySignature(signer.spki, sigAlg, signature, signed, hash);
+    }
+    catch (err) {
+        return fail(`signature cannot be checked: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!valid)
+        return fail("the TSA's signature does not verify");
+    // RFC 3161 2.3: the signing certificate is for timestamping only, and says so critically.
+    const eku = extendedKeyUsage(signer);
+    if (!eku || !eku.critical || eku.purposes.length !== 1 || eku.purposes[0] !== OID.kpTimeStamping) {
+        return fail(`${signer.name} is not a certificate for timestamping only (critical extended key usage id-kp-timeStamping)`);
+    }
+    if (!keyUsageAllows(signer, KEY_USAGE_DIGITAL_SIGNATURE) && !keyUsageAllows(signer, KEY_USAGE_NON_REPUDIATION)) {
+        return fail(`${signer.name} is not allowed to make signatures`);
+    }
+    const roots = expect.roots.map((r) => parseCertificate(r));
+    const chain = await buildChain(signer, certificates.filter((c) => c !== signer), roots, tst.genTime);
+    if (!chain.ok)
+        return fail(`the TSA's certificate does not chain to a trusted root: ${chain.reason}`);
+    const rootHash = toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", chain.anchor.raw)));
+    return { ok: true, gen_time: new Date(tst.genTime).toISOString(), serial: toHex(tst.serial), policy: tst.policy, chain: chain.path, root_sha256: rootHash };
+}
+function parseTstInfo(bytes) {
+    const t = seq(readDer(bytes), "TSTInfo");
+    if (readSmallInt(t[0], "TSTInfo version") !== 1)
+        throw new Error("unsupported TSTInfo version");
+    const policy = readOid(t[1], "policy");
+    const [alg, hashed, ...imprintExtra] = seq(t[2], "messageImprint");
+    if (imprintExtra.length)
+        throw new Error("messageImprint has trailing elements");
+    const algParts = seq(alg, "hashAlgorithm");
+    if (algParts.length > 2 || (algParts[1] && algParts[1].tag !== TAG.NULL))
+        throw new Error("unexpected hashAlgorithm parameters");
+    const imprintAlg = readOid(algParts[0]);
+    const imprint = readOctetString(hashed, "hashedMessage");
+    const serial = readIntegerBytes(t[3], "serialNumber");
+    const genTime = readTime(expectTag(t[4], TAG.GENERALIZED_TIME, "genTime"), "genTime");
+    let nonce = null;
+    for (const el of t.slice(5)) {
+        if (el.tag === TAG.INTEGER) {
+            if (nonce !== null)
+                throw new Error("TSTInfo has two nonces");
+            nonce = readIntegerBytes(el, "nonce");
+        }
+        // A critical extension we do not understand might change what the token means.
+        if (el.tag === contextTag(1)) {
+            for (const ext of children(el)) {
+                const parts = seq(ext, "TSTInfo extension");
+                if (parts.length === 3 && parts[1].tag === TAG.BOOLEAN && parts[1].content[0] === 0xff)
+                    throw new Error("TSTInfo has a critical extension");
+            }
+        }
+        // accuracy, ordering and the tsa name do not affect what is checked here
+    }
+    return { policy, imprintAlg, imprint, serial, genTime, nonce };
+}
+/** SignerIdentifier: IssuerAndSerialNumber, or [0] SubjectKeyIdentifier. */
+function matchesSid(cert, sid) {
+    if (sid.tag === TAG.SEQUENCE) {
+        const [issuer, serial] = children(sid);
+        return bytesEqual(issuer.raw, cert.issuer) && bytesEqual(readIntegerBytes(serial), cert.serial);
+    }
+    if (sid.tag === contextTag(0, false)) {
+        const ski = subjectKeyIdentifier(cert);
+        return ski !== null && bytesEqual(ski, sid.content);
+    }
+    return false;
+}
+/** RFC 2634 / RFC 5035: the signed attributes name the signing certificate by hash. At least one form is required. */
+async function checkSigningCertificate(signer, attrs) {
+    const v2 = attrs.get(CMS.signingCertificateV2);
+    const v1 = attrs.get(CMS.signingCertificate);
+    if (!v1 && !v2)
+        return "the token does not bind its signing certificate (no ESS signingCertificate attribute)";
+    if (v2) {
+        const [certs] = seq(v2, "SigningCertificateV2");
+        const first = seq(certs, "ESSCertIDv2 list")[0];
+        const parts = seq(first, "ESSCertIDv2");
+        let alg = OID.sha256;
+        let i = 0;
+        if (parts[0]?.tag === TAG.SEQUENCE)
+            alg = readOid(seq(parts[i++], "hashAlgorithm")[0]);
+        const hashName = HASH_BY_OID[alg];
+        if (!hashName)
+            return `unsupported signingCertificateV2 hash ${alg}`;
+        const actual = new Uint8Array(await crypto.subtle.digest(hashName, signer.raw));
+        if (!bytesEqual(readOctetString(parts[i], "certHash"), actual))
+            return "signingCertificateV2 names a different certificate";
+    }
+    if (v1) {
+        const [certs] = seq(v1, "SigningCertificate");
+        const first = seq(certs, "ESSCertID list")[0];
+        const actual = new Uint8Array(await crypto.subtle.digest("SHA-1", signer.raw));
+        if (!bytesEqual(readOctetString(seq(first, "ESSCertID")[0], "certHash"), actual))
+            return "signingCertificate names a different certificate";
+    }
+    return null;
+}

package/dist/x509.d.ts

@@ -0,0 +1,93 @@
+export declare const OID: {
+    readonly rsaEncryption: "1.2.840.113549.1.1.1";
+    readonly sha256WithRSA: "1.2.840.113549.1.1.11";
+    readonly sha384WithRSA: "1.2.840.113549.1.1.12";
+    readonly sha512WithRSA: "1.2.840.113549.1.1.13";
+    readonly ecPublicKey: "1.2.840.10045.2.1";
+    readonly ecdsaWithSHA256: "1.2.840.10045.4.3.2";
+    readonly ecdsaWithSHA384: "1.2.840.10045.4.3.3";
+    readonly ecdsaWithSHA512: "1.2.840.10045.4.3.4";
+    readonly p256: "1.2.840.10045.3.1.7";
+    readonly p384: "1.3.132.0.34";
+    readonly p521: "1.3.132.0.35";
+    readonly sha1: "1.3.14.3.2.26";
+    readonly sha256: "2.16.840.1.101.3.4.2.1";
+    readonly sha384: "2.16.840.1.101.3.4.2.2";
+    readonly sha512: "2.16.840.1.101.3.4.2.3";
+    readonly commonName: "2.5.4.3";
+    readonly organisation: "2.5.4.10";
+    readonly subjectKeyIdentifier: "2.5.29.14";
+    readonly keyUsage: "2.5.29.15";
+    readonly subjectAltName: "2.5.29.17";
+    readonly basicConstraints: "2.5.29.19";
+    readonly crlDistributionPoints: "2.5.29.31";
+    readonly certificatePolicies: "2.5.29.32";
+    readonly authorityKeyIdentifier: "2.5.29.35";
+    readonly extKeyUsage: "2.5.29.37";
+    readonly authorityInfoAccess: "1.3.6.1.5.5.7.1.1";
+    readonly kpTimeStamping: "1.3.6.1.5.5.7.3.8";
+    readonly anyExtendedKeyUsage: "2.5.29.37.0";
+};
+export type HashName = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
+export declare const HASH_BY_OID: Record<string, HashName>;
+export type Certificate = {
+    raw: Uint8Array<ArrayBuffer>;
+    tbs: Uint8Array<ArrayBuffer>;
+    signatureAlg: string;
+    signature: Uint8Array<ArrayBuffer>;
+    serial: Uint8Array<ArrayBuffer>;
+    issuer: Uint8Array<ArrayBuffer>;
+    subject: Uint8Array<ArrayBuffer>;
+    /** A readable form of the subject, for reports: CN, else O. */
+    name: string;
+    notBefore: number;
+    notAfter: number;
+    spki: Uint8Array<ArrayBuffer>;
+    extensions: Map<string, {
+        critical: boolean;
+        value: Uint8Array<ArrayBuffer>;
+    }>;
+};
+export declare function parseCertificate(bytes: Uint8Array): Certificate;
+/** basicConstraints: whether this is a CA, and how many intermediate CAs may follow it (null: no limit). */
+export declare function basicConstraints(cert: Certificate): {
+    ca: boolean;
+    pathLen: number | null;
+};
+export declare function isCa(cert: Certificate): boolean;
+/** Whether the key usage extension allows `bit`. An absent extension permits every use. */
+export declare function keyUsageAllows(cert: Certificate, bit: number): boolean;
+export declare function extendedKeyUsage(cert: Certificate): {
+    critical: boolean;
+    purposes: string[];
+} | null;
+export declare function subjectKeyIdentifier(cert: Certificate): Uint8Array<ArrayBuffer> | 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 declare function verifySignature(spki: Uint8Array<ArrayBuffer>, alg: string, signature: Uint8Array, data: Uint8Array<ArrayBuffer>, hash?: HashName): Promise<boolean>;
+/** X.509 and CMS carry ECDSA signatures as DER SEQUENCE { r, s }; WebCrypto wants r || s. */
+export declare function ecdsaDerToRaw(der: Uint8Array, size: number): Uint8Array<ArrayBuffer>;
+export type ChainResult = {
+    ok: true;
+    path: string[];
+    anchor: Certificate;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 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 declare function buildChain(leaf: Certificate, intermediates: readonly Certificate[], anchors: readonly Certificate[], at: number): Promise<ChainResult>;
+/** SHA-256 fingerprint, base64url, for reports and pinning. */
+export declare function certificateFingerprint(cert: Certificate): Promise<string>;

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.2.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",