@int-loop/core 0.1.0 → 0.3.0

package/dist/tsa-roots.js

@@ -0,0 +1,150 @@
+// Timestamp authority roots that int-loop and int-loop-verify trust by default. An auditor
+// can replace this list with their own (int-loop-verify --tsa-roots roots.pem).
+//
+// Provenance, checked 2026-11-09 (SHA-256 fingerprints):
+//   FreeTSA Root CA          a6379e7cecc05faa3cbf076013d745e327bbbaa38c0b9af22469d4701d18aabc
+//                            from https://freetsa.org/files/cacert.pem, identical to the root FreeTSA sends
+//   DigiCert Trusted Root G4 552f7bdcf1a7af9e6ce672017f4f12abf77240c78e761ac203d1d9d20ac89988
+//                            from the macOS system root store
+//   Sectigo Public Time Stamping Root R46
+//                            4941b001b8a97e961b7817c9d9e960ec4b056bfc915a8c1aabf6ef6b3ac046a5
+//                            from the macOS system root store
+//
+// tests/core/tsp.test.ts checks each fingerprint, so a change here cannot go unnoticed.
+import { fromPem } from "./der.js";
+export const KNOWN_TSA_ROOTS = [
+    {
+        id: "freetsa",
+        name: "FreeTSA Root CA",
+        sha256: "a6379e7cecc05faa3cbf076013d745e327bbbaa38c0b9af22469d4701d18aabc",
+        pem: `
+      -----BEGIN CERTIFICATE-----
+      MIIH/zCCBeegAwIBAgIJAMHphhYNqOmAMA0GCSqGSIb3DQEBDQUAMIGVMREwDwYD
+      VQQKEwhGcmVlIFRTQTEQMA4GA1UECxMHUm9vdCBDQTEYMBYGA1UEAxMPd3d3LmZy
+      ZWV0c2Eub3JnMSIwIAYJKoZIhvcNAQkBFhNidXNpbGV6YXNAZ21haWwuY29tMRIw
+      EAYDVQQHEwlXdWVyemJ1cmcxDzANBgNVBAgTBkJheWVybjELMAkGA1UEBhMCREUw
+      HhcNMTYwMzEzMDE1MjEzWhcNNDEwMzA3MDE1MjEzWjCBlTERMA8GA1UEChMIRnJl
+      ZSBUU0ExEDAOBgNVBAsTB1Jvb3QgQ0ExGDAWBgNVBAMTD3d3dy5mcmVldHNhLm9y
+      ZzEiMCAGCSqGSIb3DQEJARYTYnVzaWxlemFzQGdtYWlsLmNvbTESMBAGA1UEBxMJ
+      V3VlcnpidXJnMQ8wDQYDVQQIEwZCYXllcm4xCzAJBgNVBAYTAkRFMIICIjANBgkq
+      hkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAtgKODjAy8REQ2WTNqUudAnjhlCrpE6ql
+      mQfNppeTmVvZrH4zutn+NwTaHAGpjSGv4/WRpZ1wZ3BRZ5mPUBZyLgq0YrIfQ5Fx
+      0s/MRZPzc1r3lKWrMR9sAQx4mN4z11xFEO529L0dFJjPF9MD8Gpd2feWzGyptlel
+      b+PqT+++fOa2oY0+NaMM7l/xcNHPOaMz0/2olk0i22hbKeVhvokPCqhFhzsuhKsm
+      q4Of/o+t6dI7sx5h0nPMm4gGSRhfq+z6BTRgCrqQG2FOLoVFgt6iIm/BnNffUr7V
+      DYd3zZmIwFOj/H3DKHoGik/xK3E82YA2ZulVOFRW/zj4ApjPa5OFbpIkd0pmzxzd
+      EcL479hSA9dFiyVmSxPtY5ze1P+BE9bMU1PScpRzw8MHFXxyKqW13Qv7LWw4sbk3
+      SciB7GACbQiVGzgkvXG6y85HOuvWNvC5GLSiyP9GlPB0V68tbxz4JVTRdw/Xn/XT
+      FNzRBM3cq8lBOAVt/PAX5+uFcv1S9wFE8YjaBfWCP1jdBil+c4e+0tdywT2oJmYB
+      BF/kEt1wmGwMmHunNEuQNzh1FtJY54hbUfiWi38mASE7xMtMhfj/C4SvapiDN837
+      gYaPfs8x3KZxbX7C3YAsFnJinlwAUss1fdKar8Q/YVs7H/nU4c4Ixxxz4f67fcVq
+      M2ITKentbCMCAwEAAaOCAk4wggJKMAwGA1UdEwQFMAMBAf8wDgYDVR0PAQH/BAQD
+      AgHGMB0GA1UdDgQWBBT6VQ2MNGZRQ0z357OnbJWveuaklzCBygYDVR0jBIHCMIG/
+      gBT6VQ2MNGZRQ0z357OnbJWveuakl6GBm6SBmDCBlTERMA8GA1UEChMIRnJlZSBU
+      U0ExEDAOBgNVBAsTB1Jvb3QgQ0ExGDAWBgNVBAMTD3d3dy5mcmVldHNhLm9yZzEi
+      MCAGCSqGSIb3DQEJARYTYnVzaWxlemFzQGdtYWlsLmNvbTESMBAGA1UEBxMJV3Vl
+      cnpidXJnMQ8wDQYDVQQIEwZCYXllcm4xCzAJBgNVBAYTAkRFggkAwemGFg2o6YAw
+      MwYDVR0fBCwwKjAooCagJIYiaHR0cDovL3d3dy5mcmVldHNhLm9yZy9yb290X2Nh
+      LmNybDCBzwYDVR0gBIHHMIHEMIHBBgorBgEEAYHyJAEBMIGyMDMGCCsGAQUFBwIB
+      FidodHRwOi8vd3d3LmZyZWV0c2Eub3JnL2ZyZWV0c2FfY3BzLmh0bWwwMgYIKwYB
+      BQUHAgEWJmh0dHA6Ly93d3cuZnJlZXRzYS5vcmcvZnJlZXRzYV9jcHMucGRmMEcG
+      CCsGAQUFBwICMDsaOUZyZWVUU0EgdHJ1c3RlZCB0aW1lc3RhbXBpbmcgU29mdHdh
+      cmUgYXMgYSBTZXJ2aWNlIChTYWFTKTA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUH
+      MAGGG2h0dHA6Ly93d3cuZnJlZXRzYS5vcmc6MjU2MDANBgkqhkiG9w0BAQ0FAAOC
+      AgEAaK9+v5OFYu9M6ztYC+L69sw1omdyli89lZAfpWMMh9CRmJhM6KBqM/ipwoLt
+      nxyxGsbCPhcQjuTvzm+ylN6VwTMmIlVyVSLKYZcdSjt/eCUN+41K7sD7GVmxZBAF
+      ILnBDmTGJmLkrU0KuuIpj8lI/E6Z6NnmuP2+RAQSHsfBQi6sssnXMo4HOW5gtPO7
+      gDrUpVXID++1P4XndkoKn7Svw5n0zS9fv1hxBcYIHPPQUze2u30bAQt0n0iIyRLz
+      aWuhtpAtd7ffwEbASgzB7E+NGF4tpV37e8KiA2xiGSRqT5ndu28fgpOY87gD3ArZ
+      DctZvvTCfHdAS5kEO3gnGGeZEVLDmfEsv8TGJa3AljVa5E40IQDsUXpQLi8G+UC4
+      1DWZu8EVT4rnYaCw1VX7ShOR1PNCCvjb8S8tfdudd9zhU3gEB0rxdeTy1tVbNLXW
+      99y90xcwr1ZIDUwM/xQ/noO8FRhm0LoPC73Ef+J4ZBdrvWwauF3zJe33d4ibxEcb
+      8/pz5WzFkeixYM2nsHhqHsBKw7JPouKNXRnl5IAE1eFmqDyC7G/VT7OF669xM6hb
+      Ut5G21JE4cNK6NNucS+fzg1JPX0+3VhsYZjj7D5uljRvQXrJ8iHgr/M6j2oLHvTA
+      I2MLdq2qjZFDOCXsxBxJpbmLGBx9ow6ZerlUxzws2AWv2pk=
+      -----END CERTIFICATE-----
+    `,
+    },
+    {
+        id: "digicert-g4",
+        name: "DigiCert Trusted Root G4",
+        sha256: "552f7bdcf1a7af9e6ce672017f4f12abf77240c78e761ac203d1d9d20ac89988",
+        pem: `
+      -----BEGIN CERTIFICATE-----
+      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
+      -----END CERTIFICATE-----
+    `,
+    },
+    {
+        id: "sectigo-r46",
+        name: "Sectigo Public Time Stamping Root R46",
+        sha256: "4941b001b8a97e961b7817c9d9e960ec4b056bfc915a8c1aabf6ef6b3ac046a5",
+        pem: `
+      -----BEGIN CERTIFICATE-----
+      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
+      XftzTXTX48FRiJ6PA9o=
+      -----END CERTIFICATE-----
+    `,
+    },
+];
+/** The default roots, as DER. */
+export function knownTsaRootsDer() {
+    return KNOWN_TSA_ROOTS.flatMap((r) => fromPem(r.pem));
+}

package/dist/tsp.d.ts

@@ -0,0 +1,37 @@
+/** A TimeStampReq for a SHA-256 digest, asking for the signing certificate to be included. */
+export declare function buildTimestampRequest(digest: Uint8Array, nonce: Uint8Array): Uint8Array<ArrayBuffer>;
+export type TimestampReply = {
+    granted: true;
+    token: Uint8Array<ArrayBuffer>;
+} | {
+    granted: false;
+    reason: string;
+};
+/** Reads a TimeStampResp. A refusal is a result, not an error; malformed bytes throw. */
+export declare function parseTimestampReply(bytes: Uint8Array): TimestampReply;
+export type TimestampExpectation = {
+    /** The SHA-256 digest that should have been stamped. */
+    digest: Uint8Array;
+    /** The nonce sent with the request, when checking a fresh reply. */
+    nonce?: Uint8Array;
+    /** Trusted TSA roots, as DER certificates. */
+    roots: readonly Uint8Array[];
+};
+export type TimestampInfo = {
+    /** The stamped time, as the TSA states it. */
+    gen_time: string;
+    serial: string;
+    policy: string;
+    /** Signing certificate first, trusted root last. */
+    chain: string[];
+    /** SHA-256 (hex) of the trusted root the chain ends at: which authority vouches for the time. */
+    root_sha256: string;
+};
+export type TimestampResult = ({
+    ok: true;
+} & TimestampInfo) | {
+    ok: false;
+    reason: string;
+};
+/** Verifies a TimeStampToken. Never throws: anything malformed is a failure. */
+export declare function verifyTimestampToken(token: Uint8Array, expect: TimestampExpectation): Promise<TimestampResult>;

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>;