tunnelfetch 1.0.0

package/types/trust/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * A trust anchor as supplied by a caller: PEM text or raw DER.
+ * @typedef {string | Uint8Array} AnchorInput
+ */
+/**
+ * Revocation policy, for the modes that validate chains. Checking is via stapled OCSP only, so
+ * the knob decides what a MISSING staple means: `'staple'` (the default) tolerates absence but
+ * fully verifies any staple that is present; `'require-staple'` makes absence OCSP_REQUIRED.
+ * A verified `revoked` or `unknown` verdict is fatal under both — no value ignores it.
+ * @typedef {'staple' | 'require-staple'} RevocationPolicy
+ */
+/**
+ * Verify against the bundled CCADB root store. The default.
+ * @typedef {{ mode?: 'system', revocation?: RevocationPolicy }} SystemTrust
+ */
+/**
+ * Verify against exactly these anchors and nothing else. The bundled store is not consulted.
+ * @typedef {{ mode: 'anchors', anchors: AnchorInput[],
+ *             revocation?: RevocationPolicy }} AnchorsTrust
+ */
+/**
+ * Full path validation, plus a requirement that some certificate in the accepted path (or its
+ * anchor) match one of `pins`. Pins are `sha256/` followed by the base64 SHA-256 of a
+ * SubjectPublicKeyInfo, the same spelling HPKP used.
+ * @typedef {{ mode: 'pinned', pins: string[], anchors?: AnchorInput[],
+ *             revocation?: RevocationPolicy }} PinnedTrust
+ */
+/**
+ * No path validation at all. `insecureAcceptAnyCertificate` is mandatory and must be `true`, so
+ * that this mode can never be reached by a typo in `mode`. Supplying `pins` turns it into
+ * pin-only trust: no chain is built, but a pin must still match. `revocation` is refused here:
+ * without a validated issuer there is no trusted key to verify a staple against, so the check
+ * cannot be performed honestly and pretending otherwise would be worse.
+ * @typedef {{ mode: 'none', insecureAcceptAnyCertificate: true, pins?: string[] }} NoTrust
+ */
+/**
+ * Caller-supplied policy. Returning normally accepts the chain; throwing rejects it. The third
+ * argument carries the peer's stapled OCSP response (DER, or null) so a custom policy can judge
+ * revocation itself — `verifyOcspStaple` is exported for exactly that.
+ * @typedef {{ mode: 'custom',
+ *             verify: (chain: ParsedCertificate[], hostname: string,
+ *                      details?: { ocspResponse: Uint8Array | null })
+ *               => void | Promise<void> }} CustomTrust
+ */
+/**
+ * The `verify=` knob, in httpx's spirit. Written as a discriminated union so that a TypeScript
+ * caller cannot ask for pinning without pins, or reach `mode: 'none'` without spelling out the
+ * flag that says they meant it — both of which are otherwise runtime errors discovered in
+ * production rather than compile errors discovered while typing.
+ * @typedef {SystemTrust | AnchorsTrust | PinnedTrust | NoTrust | CustomTrust} TrustConfig
+ */
+/**
+ * A parsed certificate, as returned by `parseCertificate`. Only the members other layers rely on
+ * are named here; the object carries the full parse.
+ * @typedef {object} ParsedCertificate
+ * @property {Uint8Array} der the original bytes, never re-encoded
+ * @property {Uint8Array} tbsBytes exact TBSCertificate slice the signature covers
+ * @property {{ spkiDer: Uint8Array, algorithmOid: string, keyBytes: Uint8Array }} spki
+ * @property {{ text: string }} subject
+ * @property {{ text: string }} issuer
+ * @property {number} notBefore epoch ms
+ * @property {number} notAfter epoch ms
+ * @property {{ dns: string[], ip: Uint8Array[], uri: string[], email: string[] }} subjectAltNames
+ */
+/**
+ * Verify a TLS-delivered certificate chain for `hostname`.
+ *
+ * @param {object} opts
+ * @param {Uint8Array[]} opts.chain DER certificates, leaf first, as the peer sent them
+ * @param {string} opts.hostname identity from the request URL (DNS name or IP literal)
+ * @param {TrustConfig} [opts.trust] the verification policy; defaults to the bundled roots
+ * @param {number} [opts.now] epoch ms, for tests and for callers with a better clock
+ * @param {Uint8Array | null} [opts.ocspResponse] the peer's stapled DER OCSPResponse, when the
+ *   handshake carried one; judged under `trust.revocation` (see the policy comment above)
+ * @returns {Promise<ParsedCertificate>} the parsed leaf. Every other outcome throws.
+ */
+export function verifyChain({ chain, hostname, trust, now, ocspResponse, }: {
+    chain: Uint8Array[];
+    hostname: string;
+    trust?: TrustConfig | undefined;
+    now?: number | undefined;
+    ocspResponse?: Uint8Array<ArrayBufferLike> | null | undefined;
+}): Promise<ParsedCertificate>;
+export { matchesIdentity } from "./name.js";
+/**
+ * A trust anchor as supplied by a caller: PEM text or raw DER.
+ */
+export type AnchorInput = string | Uint8Array;
+/**
+ * Revocation policy, for the modes that validate chains. Checking is via stapled OCSP only, so
+ * the knob decides what a MISSING staple means: `'staple'` (the default) tolerates absence but
+ * fully verifies any staple that is present; `'require-staple'` makes absence OCSP_REQUIRED.
+ * A verified `revoked` or `unknown` verdict is fatal under both — no value ignores it.
+ */
+export type RevocationPolicy = "staple" | "require-staple";
+/**
+ * Verify against the bundled CCADB root store. The default.
+ */
+export type SystemTrust = {
+    mode?: "system";
+    revocation?: RevocationPolicy;
+};
+/**
+ * Verify against exactly these anchors and nothing else. The bundled store is not consulted.
+ */
+export type AnchorsTrust = {
+    mode: "anchors";
+    anchors: AnchorInput[];
+    revocation?: RevocationPolicy;
+};
+/**
+ * Full path validation, plus a requirement that some certificate in the accepted path (or its
+ * anchor) match one of `pins`. Pins are `sha256/` followed by the base64 SHA-256 of a
+ * SubjectPublicKeyInfo, the same spelling HPKP used.
+ */
+export type PinnedTrust = {
+    mode: "pinned";
+    pins: string[];
+    anchors?: AnchorInput[];
+    revocation?: RevocationPolicy;
+};
+/**
+ * No path validation at all. `insecureAcceptAnyCertificate` is mandatory and must be `true`, so
+ * that this mode can never be reached by a typo in `mode`. Supplying `pins` turns it into
+ * pin-only trust: no chain is built, but a pin must still match. `revocation` is refused here:
+ * without a validated issuer there is no trusted key to verify a staple against, so the check
+ * cannot be performed honestly and pretending otherwise would be worse.
+ */
+export type NoTrust = {
+    mode: "none";
+    insecureAcceptAnyCertificate: true;
+    pins?: string[];
+};
+/**
+ * Caller-supplied policy. Returning normally accepts the chain; throwing rejects it. The third
+ * argument carries the peer's stapled OCSP response (DER, or null) so a custom policy can judge
+ * revocation itself — `verifyOcspStaple` is exported for exactly that.
+ */
+export type CustomTrust = {
+    mode: "custom";
+    verify: (chain: ParsedCertificate[], hostname: string, details?: {
+        ocspResponse: Uint8Array | null;
+    }) => void | Promise<void>;
+};
+/**
+ * The `verify=` knob, in httpx's spirit. Written as a discriminated union so that a TypeScript
+ * caller cannot ask for pinning without pins, or reach `mode: 'none'` without spelling out the
+ * flag that says they meant it — both of which are otherwise runtime errors discovered in
+ * production rather than compile errors discovered while typing.
+ */
+export type TrustConfig = SystemTrust | AnchorsTrust | PinnedTrust | NoTrust | CustomTrust;
+/**
+ * A parsed certificate, as returned by `parseCertificate`. Only the members other layers rely on
+ * are named here; the object carries the full parse.
+ */
+export type ParsedCertificate = {
+    /**
+     * the original bytes, never re-encoded
+     */
+    der: Uint8Array;
+    /**
+     * exact TBSCertificate slice the signature covers
+     */
+    tbsBytes: Uint8Array;
+    spki: {
+        spkiDer: Uint8Array;
+        algorithmOid: string;
+        keyBytes: Uint8Array;
+    };
+    subject: {
+        text: string;
+    };
+    issuer: {
+        text: string;
+    };
+    /**
+     * epoch ms
+     */
+    notBefore: number;
+    /**
+     * epoch ms
+     */
+    notAfter: number;
+    subjectAltNames: {
+        dns: string[];
+        ip: Uint8Array[];
+        uri: string[];
+        email: string[];
+    };
+};
+export { parseCertificate, decodePem } from "./x509.js";
+export { validatePath, anchorFromCertificate } from "./path.js";
+export { verifyOcspStaple, parseOcspResponse } from "./ocsp.js";
+export { systemAnchors, provenance as rootStoreProvenance } from "./roots.js";

package/types/trust/name.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Parse an IP literal (v4 dotted-quad or v6, optionally [bracketed]) to raw bytes, else null.
+ * @param {string} text
+ * @returns {Uint8Array | null}
+ */
+export function parseIp(text: string): Uint8Array | null;
+/**
+ * Verify that `cert` is a certificate for `hostname`. Returns nothing; every non-match throws
+ * CERT_NAME_MISMATCH with the entries that were considered, so one log line shows exactly how
+ * close the certificate was.
+ *
+ * @param {import('./x509.js').Certificate} cert
+ * @param {string} hostname DNS name (A-label form) or IP literal, per the request URL
+ * @returns {void}
+ */
+export function matchesIdentity(cert: import("./x509.js").Certificate, hostname: string): void;
+/**
+ * RFC 5280 s4.2.1.10 dNSName subtree: a constraint "example.com" covers the host itself and any
+ * subdomain, at a label boundary. The seen-in-the-wild ".example.com" form covers subdomains
+ * only. An empty constraint covers every DNS name (used by permittedSubtrees to say "any DNS").
+ * @param {string} name
+ * @param {string} base
+ * @returns {boolean}
+ */
+export function dnsWithinSubtree(name: string, base: string): boolean;
+/**
+ * iPAddress subtree: same family, and (address & mask) equal on every byte.
+ * @param {Uint8Array} ip
+ * @param {Uint8Array} addr
+ * @param {Uint8Array} mask
+ * @returns {boolean}
+ */
+export function ipWithinSubtree(ip: Uint8Array, addr: Uint8Array, mask: Uint8Array): boolean;

package/types/trust/ocsp.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Parse a DER OCSPResponse (RFC 6960 s4.2.1) into a fully-walked structure.
+ *
+ * A parser, not a judge, exactly like parseCertificate: it throws OCSP_PARSE on malformed or
+ * self-contradictory bytes and on constructs this package refuses to interpret (unknown
+ * responseType, unrecognized critical extensions); whether the parsed response is TRUE is
+ * verifyOcspStaple's problem.
+ *
+ * @param {Uint8Array} der
+ * @returns {OcspResponse}
+ */
+export function parseOcspResponse(der: Uint8Array): OcspResponse;
+/**
+ * Verify a stapled OCSP response against the certificate it must vouch for.
+ *
+ * Every check the module comment promises happens here, in this order: parse, match the CertID
+ * to `leaf`/`issuer`, establish the signer (the CA itself or an RFC 6960 s4.2.2.2 delegated
+ * responder), verify the signature over the original tbsResponseData bytes, and only then read
+ * the verdict and its freshness window. `revoked` and `unknown` always throw; `good` throws
+ * unless the window covers `now`.
+ *
+ * @param {object} args
+ * @param {Uint8Array} args.staple DER OCSPResponse, exactly as the peer stapled it
+ * @param {import('./x509.js').Certificate} args.leaf the validated leaf the staple must cover
+ * @param {OcspIssuer} args.issuer the leaf's issuer, from the validated path
+ * @param {number} args.now epoch ms, injected — never a wall clock read here
+ * @returns {Promise<OcspVerdict>} every failure throws a typed CertificateError (OCSP_* codes)
+ */
+export function verifyOcspStaple({ staple, leaf, issuer, now }: {
+    staple: Uint8Array;
+    leaf: import("./x509.js").Certificate;
+    issuer: OcspIssuer;
+    now: number;
+}): Promise<OcspVerdict>;
+/**
+ * CertID (RFC 6960 s4.1.1): which certificate a SingleResponse is talking about.
+ */
+export type OcspCertId = {
+    hashOid: string;
+    issuerNameHash: Uint8Array;
+    issuerKeyHash: Uint8Array;
+    /**
+     * INTEGER content bytes, minimal DER
+     */
+    serialBytes: Uint8Array;
+};
+/**
+ * One SingleResponse, parsed. Times are epoch ms.
+ */
+export type OcspSingleResponse = {
+    certId: OcspCertId;
+    status: {
+        kind: "good";
+    } | {
+        kind: "unknown";
+    } | {
+        kind: "revoked";
+        revocationTime: number;
+        reason: number | null;
+    };
+    thisUpdate: number;
+    nextUpdate: number | null;
+};
+/**
+ * A parsed BasicOCSPResponse. `tbsBytes` is the exact original ResponseData element — the bytes
+ * the signature covers, never re-encoded.
+ */
+export type OcspBasicResponse = {
+    tbsBytes: Uint8Array;
+    signatureAlgorithm: import("./x509.js").AlgorithmId;
+    signature: Uint8Array;
+    responderId: {
+        kind: "name";
+        nameBytes: Uint8Array;
+    } | {
+        kind: "key";
+        keyHash: Uint8Array;
+    };
+    /**
+     * epoch ms
+     */
+    producedAt: number;
+    singles: OcspSingleResponse[];
+    /**
+     * attached responder certificates, parsed
+     */
+    certs: import("./x509.js").Certificate[];
+};
+export type OcspResponse = {
+    responseStatus: number;
+    responseStatusName: string;
+    /**
+     * null exactly when responseStatus != successful
+     */
+    basic: OcspBasicResponse | null;
+};
+/**
+ * The issuer of the certificate under check, reduced to what OCSP verification needs. Built by
+ * the caller from the VALIDATED path — the certificate that actually signed the leaf, or the
+ * trust anchor when the leaf sits directly under one — never from the unverified wire chain.
+ */
+export type OcspIssuer = {
+    /**
+     * exact subject Name DER
+     */
+    subjectBytes: Uint8Array;
+    /**
+     * SubjectPublicKeyInfo DER
+     */
+    spkiDer: Uint8Array;
+    /**
+     * for error messages
+     */
+    subjectText: string;
+};
+/**
+ * What a verified `good` staple reports. Every other outcome throws; there is no boolean.
+ */
+export type OcspVerdict = {
+    status: "good";
+    /**
+     * epoch ms
+     */
+    producedAt: number;
+    /**
+     * epoch ms
+     */
+    thisUpdate: number;
+    /**
+     * epoch ms
+     */
+    nextUpdate: number | null;
+    /**
+     * whether a delegated responder certificate signed, rather than
+     * the CA key itself
+     */
+    delegated: boolean;
+};

package/types/trust/path.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The RFC 5280 s6.1.1 trust-anchor triple, normalised. Validity bounds are recorded but never
+ * enforced — see the module comment for why expiring a root is store policy, not path policy.
+ * @typedef {object} TrustAnchor
+ * @property {Uint8Array} subjectBytes exact subject DN DER
+ * @property {string} subjectText
+ * @property {Uint8Array} spkiDer
+ * @property {Uint8Array | null} subjectKeyIdentifier
+ * @property {import('./x509.js').NameConstraints | null} nameConstraints
+ * @property {number | null} notBefore
+ * @property {number | null} notAfter
+ */
+/**
+ * Anything normalizeAnchor accepts: DER, a parsed certificate, or an anchor-shaped record.
+ * The record form also admits `nameConstraintsBytes` (raw extnValue), which is how the bundled
+ * store defers parsing to the one anchor a handshake actually lands on.
+ * @typedef {object} AnchorRecord
+ * @property {Uint8Array} subjectBytes
+ * @property {Uint8Array} spkiDer
+ * @property {string} [subjectText]
+ * @property {Uint8Array | null} [subjectKeyIdentifier]
+ * @property {import('./x509.js').NameConstraints | null} [nameConstraints]
+ * @property {Uint8Array | null} [nameConstraintsBytes]
+ * @property {number | null} [notBefore]
+ * @property {number | null} [notAfter]
+ */
+/** @typedef {Uint8Array | import('./x509.js').Certificate | AnchorRecord} AnchorLike */
+/**
+ * An indexed anchor lookup: everything path building needs from a root store. The bundled
+ * store implements it with a subject-hash index so a handshake touches one anchor, not all.
+ * @typedef {{ forIssuer: (subjectDn: Uint8Array) => AnchorLike[] | Promise<AnchorLike[]> }}
+ *   AnchorSource
+ */
+/**
+ * Strip a parsed certificate down to the RFC 5280 s6.1.1 trust-anchor triple. Used for the
+ * `mode:'anchors'` knob and by the root-store generator, so both feed path validation through
+ * the identical shape.
+ * @param {import('./x509.js').Certificate} cert
+ * @returns {TrustAnchor}
+ */
+export function anchorFromCertificate(cert: import("./x509.js").Certificate): TrustAnchor;
+/**
+ * Verify `cert`'s signature over its original to-be-signed bytes with the signer's public key.
+ *
+ * The scheme comes from resolveSignatureScheme (which is where MD5/SHA-1 die, before any
+ * cryptography runs). For ECDSA the curve belongs to the issuer's key, not the OID, so the
+ * WebCrypto import parameters are chosen from the issuer's SPKI and only the hash from the OID —
+ * both looked up in SIG_SCHEME_PARAMS rather than re-declared here.
+ *
+ * Exported (as verifySignedObject) for the OCSP checker: a BasicOCSPResponse is signed exactly
+ * like a certificate — an AlgorithmIdentifier, a BIT STRING over the original DER of a TBS
+ * element — and two implementations of "check an X.509-style signature" is two chances for one
+ * of them to be subtly the weaker. `cert` is therefore the structural subset both callers can
+ * supply: `{ tbsBytes, signature, signatureAlgorithm, subject: { text } }`, which a parsed
+ * Certificate satisfies as-is and the OCSP checker fakes up from response fields.
+ *
+ * @param {{ tbsBytes: Uint8Array, signature: Uint8Array,
+ *           signatureAlgorithm: import('./x509.js').AlgorithmId,
+ *           subject: { text: string } }} cert what was signed, certificate-shaped
+ * @param {Uint8Array} issuerSpkiDer the signer's SubjectPublicKeyInfo, DER
+ * @param {string} issuerText the signer's name, for error messages
+ * @returns {Promise<void>} every failure throws a typed CertificateError
+ */
+export function verifySignedObject(cert: {
+    tbsBytes: Uint8Array;
+    signature: Uint8Array;
+    signatureAlgorithm: import("./x509.js").AlgorithmId;
+    subject: {
+        text: string;
+    };
+}, issuerSpkiDer: Uint8Array, issuerText: string): Promise<void>;
+/**
+ * Build and validate a certification path. Every failure throws a typed CertificateError;
+ * there is no boolean to forget to check.
+ *
+ * @param {object} opts
+ * @param {Array<Uint8Array | import('./x509.js').Certificate>} opts.chain DER (or
+ *   already-parsed) certificates, leaf first, in whatever order and with whatever extras the
+ *   server chose to send
+ * @param {AnchorLike[] | AnchorSource} opts.anchors trust anchors, or an indexed anchor source
+ * @param {string | null} [opts.hostname] identity to require of the leaf; omit to skip
+ *   (index.js never omits)
+ * @param {number} [opts.now] epoch ms
+ * @param {number} [opts.maxPathLength] hard cap on path certificates — this runs on a metered
+ *   runtime and a pathological chain must cost O(cap), not O(chain²)
+ * @returns {Promise<{ leaf: import('./x509.js').Certificate,
+ *   path: import('./x509.js').Certificate[], anchor: TrustAnchor }>} parsed leaf, the
+ *   validated path (leaf first), and the anchor that terminated it
+ */
+export function validatePath({ chain, anchors, hostname, now, maxPathLength }: {
+    chain: Array<Uint8Array | import("./x509.js").Certificate>;
+    anchors: AnchorLike[] | AnchorSource;
+    hostname?: string | null | undefined;
+    now?: number | undefined;
+    maxPathLength?: number | undefined;
+}): Promise<{
+    leaf: import("./x509.js").Certificate;
+    path: import("./x509.js").Certificate[];
+    anchor: TrustAnchor;
+}>;
+/**
+ * The RFC 5280 s6.1.1 trust-anchor triple, normalised. Validity bounds are recorded but never
+ * enforced — see the module comment for why expiring a root is store policy, not path policy.
+ */
+export type TrustAnchor = {
+    /**
+     * exact subject DN DER
+     */
+    subjectBytes: Uint8Array;
+    subjectText: string;
+    spkiDer: Uint8Array;
+    subjectKeyIdentifier: Uint8Array | null;
+    nameConstraints: import("./x509.js").NameConstraints | null;
+    notBefore: number | null;
+    notAfter: number | null;
+};
+/**
+ * Anything normalizeAnchor accepts: DER, a parsed certificate, or an anchor-shaped record.
+ * The record form also admits `nameConstraintsBytes` (raw extnValue), which is how the bundled
+ * store defers parsing to the one anchor a handshake actually lands on.
+ */
+export type AnchorRecord = {
+    subjectBytes: Uint8Array;
+    spkiDer: Uint8Array;
+    subjectText?: string | undefined;
+    subjectKeyIdentifier?: Uint8Array<ArrayBufferLike> | null | undefined;
+    nameConstraints?: import("./x509.js").NameConstraints | null | undefined;
+    nameConstraintsBytes?: Uint8Array<ArrayBufferLike> | null | undefined;
+    notBefore?: number | null | undefined;
+    notAfter?: number | null | undefined;
+};
+export type AnchorLike = Uint8Array | import("./x509.js").Certificate | AnchorRecord;
+/**
+ * An indexed anchor lookup: everything path building needs from a root store. The bundled
+ * store implements it with a subject-hash index so a handshake touches one anchor, not all.
+ */
+export type AnchorSource = {
+    forIssuer: (subjectDn: Uint8Array) => AnchorLike[] | Promise<AnchorLike[]>;
+};

package/types/trust/roots.d.ts

@@ -0,0 +1,36 @@
+/** Where these anchors came from. */
+export const provenance: Readonly<{
+    source: "ccadb:IncludedRootsPEMTxt?TrustBitsInclude=Websites";
+    retrievedAt: "2026-07-30";
+    upstreamSha256: "1813222850e0d3efb875b2978e61acbcb5fcdce93d5c4358443050e9659394bd";
+    anchorCount: 121;
+}>;
+export namespace systemAnchors {
+    /**
+     * @param {Uint8Array} dnBytes exact subject DN DER of the issuer being resolved
+     * @returns {Promise<StoredAnchor[]>}
+     */
+    function forIssuer(dnBytes: Uint8Array): Promise<StoredAnchor[]>;
+}
+export type PackedAnchor = {
+    name: string;
+    s: string;
+    spki: string;
+    ski: string | null;
+    nc: string | null;
+    nb: number;
+    na: number;
+};
+/**
+ * An unpacked anchor record, shaped for path validation's normalizeAnchor: name constraints
+ * stay raw (`nameConstraintsBytes`) so only the anchor a handshake lands on pays for parsing.
+ */
+export type StoredAnchor = {
+    subjectText: string;
+    subjectBytes: Uint8Array;
+    spkiDer: Uint8Array;
+    subjectKeyIdentifier: Uint8Array | null;
+    nameConstraintsBytes: Uint8Array | null;
+    notBefore: number;
+    notAfter: number;
+};