tr-fetch 0.9.0

package/ocsp.js

@@ -0,0 +1,265 @@
+'use strict';
+
+const asn1 = require('asn1js');
+const pki = require('pkijs');
+const { randomBytes, X509Certificate } = require('node:crypto');
+const { cryptoEngine, parseDer, parseCertificate, extensionsById, extensionValue } = require('./pkiutils');
+const { downloadOcsp, networkUrl } = require('./download');
+const { TrFetchOcspError, applyPolicy } = require('./errors');
+const { debugUrl } = require('./debug');
+
+const OCSP_ACCESS = '1.3.6.1.5.5.7.48.1';
+const NONCE = '1.3.6.1.5.5.7.48.1.2';
+const NO_CHECK = '1.3.6.1.5.5.7.48.1.5';
+const OCSP_SIGNING = '1.3.6.1.5.5.7.3.9';
+
+function ocspUris(certificate) {
+    const extension = extensionsById(certificate.extensions).get('1.3.6.1.5.5.7.1.1');
+    if (! extension) {
+        return [];
+    }
+    const access = extensionValue(extension, pki.InfoAccess);
+    return access.accessDescriptions.filter(x => x.accessMethod === OCSP_ACCESS)
+        .map(x => (x.accessLocation.type === 6) ? x.accessLocation.value : '');
+}
+
+async function createOcspRequest(certificate, issuer) {
+    // SHA-1 here identifies the issuer; response signatures require SHA-2.
+    const certID = await pki.CertID.create(certificate, { issuerCertificate: issuer, hashAlgorithm: 'SHA-1' }, cryptoEngine);
+    const nonce = randomBytes(32);
+    const request = new pki.OCSPRequest();
+    request.tbsRequest.requestList = [ new pki.Request({ reqCert: certID }) ];
+    request.tbsRequest.requestExtensions = [ new pki.Extension({
+        extnID: NONCE,
+        extnValue: new asn1.OctetString({ valueHex: nonce }).toBER()
+    }) ];
+    return { certID, nonce, bytes: Buffer.from(request.toSchema(true).toBER()) };
+}
+
+function checkExtensions(extensions, allowedCritical = []) {
+    const byId = extensionsById(extensions);
+    for (const extension of byId.values()) {
+        if (extension.critical && ! allowedCritical.includes(extension.extnID)) {
+            throw new Error(`Unsupported critical OCSP extension ${extension.extnID}`);
+        }
+    }
+    return byId;
+}
+
+async function authorizeSigner(signer, issuer, producedAt, now) {
+    const before = signer.notBefore.value.getTime();
+    const after = signer.notAfter.value.getTime();
+    if (! Number.isFinite(before) || ! Number.isFinite(after) ||
+        (before > now) || (after <= now) || (producedAt < before) || (producedAt > after)) {
+        throw new Error('OCSP signer certificate is expired or not yet valid');
+    }
+    if (Buffer.from(signer.toSchema().toBER()).equals(Buffer.from(issuer.toSchema().toBER()))) {
+        return after;
+    }
+    if (! [ 'SHA-256', 'SHA-384', 'SHA-512' ].includes(cryptoEngine.getHashAlgorithm(signer.signatureAlgorithm))) {
+        throw new Error('Unsupported or weak OCSP delegated signer certificate signature');
+    }
+    const key = new X509Certificate(Buffer.from(signer.toSchema().toBER())).publicKey;
+    if ([ 'rsa', 'rsa-pss' ].includes(key.asymmetricKeyType) && (key.asymmetricKeyDetails.modulusLength < 2048)) {
+        throw new Error('OCSP delegated signer RSA key must be at least 2048 bits');
+    }
+    if (! signer.issuer.isEqual(issuer.subject) || ! await signer.verify(issuer, cryptoEngine)) {
+        throw new Error('OCSP delegated signer was not issued directly by the checked certificate issuer');
+    }
+    const extensions = checkExtensions(signer.extensions, [ '2.5.29.15', '2.5.29.19', '2.5.29.37' ]);
+    const eku = extensions.get('2.5.29.37');
+    if (! eku || ! extensionValue(eku, pki.ExtKeyUsage).keyPurposes.includes(OCSP_SIGNING)) {
+        throw new Error('OCSP delegated signer lacks the OCSP signing extended key usage');
+    }
+    const usage = extensions.get('2.5.29.15');
+    if (usage) {
+        const bits = extensionValue(usage);
+        if (! (bits instanceof asn1.BitString) || ! (bits.valueBlock.valueHexView[0] & 0x80)) {
+            throw new Error('OCSP delegated signer key usage does not permit digital signatures');
+        }
+    }
+    const basic = extensions.get('2.5.29.19');
+    if (basic && extensionValue(basic, pki.BasicConstraints).cA) {
+        throw new Error('OCSP delegated signer must be an end-entity responder certificate');
+    }
+    // Without no-check, the responder certificate needs its own revocation
+    // checking. Do not silently trust it or recursively query the same responder.
+    const noCheck = extensions.get(NO_CHECK);
+    if (! noCheck || ! (extensionValue(noCheck) instanceof asn1.Null)) {
+        throw new Error('OCSP delegated signer without a valid id-pkix-ocsp-nocheck extension is unsupported');
+    }
+    return after;
+}
+
+async function validateOcspResponse(bytes, request, certificate, issuer, now = Date.now(), debug) {
+    if (bytes.length > 1024 * 1024) {
+        throw new Error('OCSP response exceeds the 1 MiB size limit');
+    }
+    const envelope = parseDer(bytes, pki.OCSPResponse);
+    const status = envelope.responseStatus.valueBlock.valueDec;
+    if (status !== 0) {
+        const names = { 1: 'malformedRequest', 2: 'internalError', 3: 'tryLater', 5: 'sigRequired', 6: 'unauthorized' };
+        throw new Error(`OCSP responder returned ${names[status] ?? 'unrecognized status'} (${status})`);
+    }
+    if (envelope.responseBytes?.responseType !== '1.3.6.1.5.5.7.48.1.1') {
+        throw new Error('OCSP response has no supported BasicOCSPResponse');
+    }
+    const basic = parseDer(envelope.responseBytes.response.valueBlock.valueHexView, pki.BasicOCSPResponse);
+    const data = basic.tbsResponseData;
+    debug?.('OCSP response parsed', { responses: data.responses.length });
+    if ((data.version ?? 0) !== 0) {
+        throw new Error('Unsupported OCSP response version');
+    }
+    const producedAt = data.producedAt.getTime();
+    if (! Number.isFinite(producedAt) || (producedAt > now)) {
+        throw new Error('OCSP producedAt is invalid or in the future');
+    }
+    const extensions = checkExtensions(data.responseExtensions, [ NONCE ]);
+    const nonceExtension = extensions.get(NONCE);
+    if (nonceExtension) {
+        const nonce = extensionValue(nonceExtension);
+        if (! (nonce instanceof asn1.OctetString) ||
+            ! Buffer.from(nonce.valueBlock.valueHexView).equals(request.nonce)) {
+            throw new Error('OCSP response nonce does not match the request');
+        }
+    }
+    const matches = data.responses.filter(x => x.certID.isEqual(request.certID));
+    if (matches.length !== 1) {
+        throw new Error('OCSP response must contain exactly one matching certificate ID (issuer and serial)');
+    }
+    const single = matches[0];
+    checkExtensions(single.singleExtensions);
+    const thisUpdate = single.thisUpdate.getTime();
+    // Some responders omit nextUpdate. Such responses have a maximum age of
+    // five minutes here, even if the transport just retrieved them successfully.
+    const nextUpdate = single.nextUpdate?.getTime() ?? thisUpdate + 300000;
+    if (! Number.isFinite(thisUpdate) || ! Number.isFinite(nextUpdate) ||
+        (thisUpdate > now) || (thisUpdate > producedAt) || (nextUpdate <= thisUpdate)) {
+        throw new Error('OCSP response has invalid or future validity times');
+    }
+    if (nextUpdate <= now) {
+        throw new Error('OCSP response has expired or is stale');
+    }
+    if (! certificate.issuer.isEqual(issuer.subject) || ! await certificate.verify(issuer, cryptoEngine)) {
+        throw new Error('OCSP issuer did not issue the checked certificate');
+    }
+    const hash = cryptoEngine.getHashAlgorithm(basic.signatureAlgorithm);
+    if (! [ 'SHA-256', 'SHA-384', 'SHA-512' ].includes(hash)) {
+        throw new Error(`Unsupported or weak OCSP signature algorithm: ${basic.signatureAlgorithm.algorithmId}`);
+    }
+    const signers = [ issuer, ...(basic.certs ?? []) ];
+    if (signers.length > 33) {
+        throw new Error('OCSP response includes too many signer certificates');
+    }
+    const candidates = await pki.BasicOCSPResponse.collectResponderCandidates(signers, data.responderID, cryptoEngine);
+    let authenticated = false;
+    let signerExpiry = Infinity;
+    let signerError;
+    for (const index of candidates) {
+        try {
+            signerExpiry = await authorizeSigner(signers[index], issuer, producedAt, now);
+            if (! await basic.verifyResponseSignature(signers[index], cryptoEngine)) {
+                throw new Error('OCSP response signature verification failed');
+            }
+            authenticated = true;
+            break;
+        } catch (error) {
+            signerError = error;
+        }
+    }
+    if (! authenticated) {
+        throw signerError ?? new Error('No authorized OCSP signer matches the responder ID');
+    }
+    const certStatus = single.certStatus;
+    const tag = certStatus.idBlock.tagNumber;
+    if ((certStatus.idBlock.tagClass !== 3) || ! [ 0, 1, 2 ].includes(tag) ||
+        ((tag !== 1) && (certStatus.idBlock.isConstructed || certStatus.valueBlock.valueHexView.length))) {
+        throw new Error('Malformed OCSP certificate status');
+    }
+    if (tag === 1) {
+        const time = certStatus.valueBlock.value?.[0];
+        if (! (time instanceof asn1.GeneralizedTime) || (time.toDate().getTime() > producedAt)) {
+            throw new Error('Malformed or future OCSP revocation time');
+        }
+    }
+    const expiresAt = Math.min(nextUpdate, signerExpiry);
+    if (Date.now() >= expiresAt) {
+        throw new Error('OCSP response or signer certificate expired during validation');
+    }
+    return { status: [ 'good', 'revoked', 'unknown' ][tag], nextUpdate: expiresAt };
+}
+
+async function checkOcspCertificate(peer, hostname, options, signal, leaf, debug) {
+    const policy = options.ocspPolicy;
+    const label = `${leaf ? 'server' : 'intermediate CA'} certificate ${peer.serialNumber} for ${JSON.stringify(hostname)}`;
+    function issue(key, message, uri, cause, ocspStatus) {
+        debug?.('OCSP condition detected', { policy: key, configuredAction: policy[key], reason: message,
+                                             source: (uri === undefined) ? undefined : debugUrl(uri), result: ocspStatus });
+        return new TrFetchOcspError(key, `${message} (${label})`, {
+            hostname, serialNumber: peer.serialNumber, fingerprint256: peer.fingerprint256, ocspUri: uri, ocspStatus
+        }, cause);
+    }
+    let certificate, uris, issuer, request;
+    try {
+        certificate = parseCertificate(peer.raw);
+        uris = (leaf && (options.ocspUri !== undefined)) ? [ options.ocspUri ] : ocspUris(certificate);
+        for (const uri of uris) {
+            debug?.((leaf && (options.ocspUri !== undefined)) ? 'OCSP URI override selected' : 'OCSP URI detected in certificate', {
+                source: debugUrl(uri)
+            });
+        }
+    } catch (cause) {
+        applyPolicy(policy, issue('rejectedCertificate', `Cannot read OCSP certificate information: ${cause.message}`, undefined, cause, 'invalid-response'), debug);
+        return;
+    }
+    if (! uris.length) {
+        applyPolicy(policy, issue('missingOcspUri', 'Missing OCSP responder URI'), debug);
+        return;
+    }
+    try {
+        if (! peer.issuerCertificate?.raw) {
+            throw new Error('The verified TLS chain does not expose the issuer certificate');
+        }
+        issuer = parseCertificate(peer.issuerCertificate.raw);
+        request = await createOcspRequest(certificate, issuer);
+    } catch (cause) {
+        applyPolicy(policy, issue('rejectedCertificate', `Cannot prepare OCSP verification: ${cause.message}`, undefined, cause, 'invalid-response'), debug);
+        return;
+    }
+    const failures = [];
+    for (const uri of uris.slice(0, 32)) {
+        signal?.throwIfAborted();
+        const responderDebug = debug ? (event, details) => debug(event, { source: debugUrl(uri), ...details }) : undefined;
+        let bytes;
+        try {
+            bytes = await downloadOcsp(networkUrl(uri, 'OCSP responder'), request.bytes, signal, responderDebug);
+        } catch (cause) {
+            signal?.throwIfAborted();
+            failures.push(issue('unreachableOcspUri', `Unreachable OCSP responder: ${cause.message}`, uri, cause));
+            continue;
+        }
+        let result;
+        try {
+            result = await validateOcspResponse(bytes, request, certificate, issuer, Date.now(), responderDebug);
+        } catch (cause) {
+            failures.push(issue('rejectedCertificate', `Invalid OCSP response: ${cause.message}`, uri, cause, 'invalid-response'));
+            continue;
+        }
+        responderDebug?.('OCSP check completed', { result: result.status, authenticated: true,
+                                                   policy: 'rejectedCertificate', configuredAction: policy.rejectedCertificate,
+                                                   action: (result.status === 'good') ? 'continue' : policy.rejectedCertificate, nextUpdate: result.nextUpdate });
+        if (result.status !== 'good') {
+            applyPolicy(policy, issue('rejectedCertificate',
+                                      `OCSP rejected certificate: responder reports ${result.status}`, uri, undefined, result.status), responderDebug);
+        }
+        return result.nextUpdate;
+    }
+    if (uris.length > 32) {
+        failures.push(issue('unreachableOcspUri', 'OCSP responder URI lookup limit (32) exceeded'));
+    }
+    for (const failure of failures) {
+        applyPolicy(policy, failure, debug);
+    }
+}
+
+module.exports = { ocspUris, createOcspRequest, validateOcspResponse, checkOcspCertificate };

package/options.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const DEFAULT_POLICY = {
+    disabled: false,
+    missingCrlDistributionPoint: 'ignore',
+    unreachableCrlDistributionPoint: 'reject',
+    invalidCrl: 'reject',
+    revokedCertificate: 'reject'
+};
+
+const DEFAULT_OCSP_POLICY = {
+    disabled: false,
+    missingOcspUri: 'ignore',
+    unreachableOcspUri: 'reject',
+    rejectedCertificate: 'reject'
+};
+
+const CUSTOM_OPTIONS = [
+    'trFetchCrlPolicy', 'trFetchCrlCacheSize', 'trFetchCrlCacheTTL',
+    'trFetchCrlDistributionPointOverride', 'trFetchCrlOverride', 'trFetchCrlCheckDepth',
+    'trFetchOcspPolicy', 'trFetchOcspUriOverride', 'trFetchOcspCheckDepth', 'trFetchDebug'
+];
+
+const FETCH_OPTIONS = [
+    'method', 'headers', 'body', 'referrer', 'referrerPolicy', 'mode',
+    'credentials', 'cache', 'redirect', 'integrity', 'keepalive', 'signal',
+    'window', 'duplex', 'priority', 'dispatcher'
+];
+
+// Web IDL dictionaries also read inherited and non-enumerable properties.
+// In particular, never discard an inherited dispatcher or rejection policy.
+function copyOptions(value, keys) {
+    const copy = { ...value };
+    for (const key of keys) {
+        if ((value != null) && ! Object.hasOwn(copy, key) && (key in value)) {
+            copy[key] = value[key];
+        }
+    }
+    return copy;
+}
+
+function parsePolicy(value, defaults, name) {
+    if ((value !== undefined) &&
+        ((value === null) || (typeof(value) !== 'object') || Array.isArray(value))) {
+        throw new TypeError(`${name} must be an object`);
+    }
+    const policy = { ...defaults };
+    for (const [key, setting] of Object.entries(copyOptions(value, Object.keys(defaults)))) {
+        if (! Object.hasOwn(defaults, key)) {
+            throw new TypeError(`Unknown ${name} property: ${key}`);
+        }
+        if (key === 'disabled') {
+            if ((setting != null) && (typeof(setting) !== 'boolean')) {
+                throw new TypeError(`${name}.disabled must be a boolean, null or undefined`);
+            }
+            policy.disabled = setting ?? false;
+        } else {
+            if (! [ 'ignore', 'warn', 'reject' ].includes(setting)) {
+                throw new TypeError(`${name}.${key} must be ignore, warn or reject`);
+            }
+            policy[key] = setting;
+        }
+    }
+    return policy;
+}
+
+function parseDepth(value, name) {
+    if ((value == null) || (value === 'leaf')) {
+        return 0;
+    }
+    if (value === 'full-chain') {
+        return Infinity;
+    }
+    if (! Number.isSafeInteger(value) || (value < 0)) {
+        throw new TypeError(`${name} must be a nonnegative safe integer, leaf or full-chain`);
+    }
+    return value;
+}
+
+function splitOptions(options) {
+    if ((options !== undefined) && (options !== null) &&
+        ((typeof(options) !== 'object') || Array.isArray(options))) {
+        throw new TypeError('fetch options must be an object');
+    }
+    const fetchOptions = copyOptions(options, [ ...FETCH_OPTIONS, ...CUSTOM_OPTIONS ]);
+    for (const key in options) {
+        if (key.startsWith('trFetch') && ! CUSTOM_OPTIONS.includes(key)) {
+            throw new TypeError(`Unknown trFetch option: ${key}`);
+        }
+    }
+    const debugEnabled = (fetchOptions.trFetchDebug === undefined) ? false : fetchOptions.trFetchDebug;
+    if (typeof(debugEnabled) !== 'boolean') {
+        throw new TypeError('trFetchDebug must be a boolean');
+    }
+    const policy = parsePolicy(fetchOptions.trFetchCrlPolicy, DEFAULT_POLICY, 'trFetchCrlPolicy');
+    const ocspPolicy = parsePolicy(fetchOptions.trFetchOcspPolicy, DEFAULT_OCSP_POLICY, 'trFetchOcspPolicy');
+    const cacheSize = fetchOptions.trFetchCrlCacheSize ?? 32;
+    const cacheTTL = fetchOptions.trFetchCrlCacheTTL ?? 1800;
+    const checkDepth = parseDepth(fetchOptions.trFetchCrlCheckDepth, 'trFetchCrlCheckDepth');
+    const ocspCheckDepth = parseDepth(fetchOptions.trFetchOcspCheckDepth, 'trFetchOcspCheckDepth');
+    let ocspUri = fetchOptions.trFetchOcspUriOverride;
+    if (ocspUri instanceof URL) {
+        ocspUri = ocspUri.href;
+    }
+    if ((ocspUri !== undefined) && (typeof(ocspUri) !== 'string')) {
+        throw new TypeError('trFetchOcspUriOverride must be a URL string or URL');
+    }
+    if (! Number.isSafeInteger(cacheSize)) {
+        throw new TypeError('trFetchCrlCacheSize must be a safe integer');
+    }
+    if (! Number.isSafeInteger(cacheTTL) || (cacheTTL < -1)) {
+        throw new TypeError('trFetchCrlCacheTTL must be -1 or a nonnegative safe integer (seconds)');
+    }
+    let distributionPoint = fetchOptions.trFetchCrlDistributionPointOverride;
+    let crl = fetchOptions.trFetchCrlOverride;
+    if ((distributionPoint !== undefined) && (crl !== undefined)) {
+        throw new TypeError('trFetchCrlDistributionPointOverride and trFetchCrlOverride are mutually exclusive');
+    }
+    if (distributionPoint instanceof URL) {
+        distributionPoint = distributionPoint.href;
+    }
+    if ((distributionPoint !== undefined) && (typeof(distributionPoint) !== 'string')) {
+        throw new TypeError('trFetchCrlDistributionPointOverride must be a URL string or URL');
+    }
+    if (crl !== undefined) {
+        if (typeof(crl) === 'string') {
+            crl = Buffer.from(crl);
+        } else if (crl instanceof Uint8Array) {
+            crl = Buffer.from(crl);
+        } else if (crl instanceof ArrayBuffer) {
+            crl = Buffer.from(new Uint8Array(crl));
+        } else {
+            throw new TypeError('trFetchCrlOverride must be PEM text or DER/PEM bytes');
+        }
+    }
+    for (const key of CUSTOM_OPTIONS) {
+        delete fetchOptions[key];
+    }
+    if (fetchOptions.dispatcher !== undefined) {
+        throw new TypeError('trFetch cannot safely combine CRL checking with a custom dispatcher');
+    }
+    return { fetchOptions, policy, cacheSize, cacheTTL, checkDepth, distributionPoint, crl,
+             ocspPolicy, ocspUri, ocspCheckDepth, debugEnabled };
+}
+
+module.exports = { splitOptions };

package/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "tr-fetch",
+    "version": "0.9.0",
+    "description": "Node.js fetch with CRL and OCSP certificate revocation checking, plus tr-curl, a curl-like test tool",
+    "main": "index.js",
+    "exports": {
+        ".": "./index.js",
+        "./package.json": "./package.json"
+    },
+    "bin": {
+        "tr-curl": "bin/tr-curl.js"
+    },
+    "files": [
+        "index.js",
+        "cache.js",
+        "check.js",
+        "crl.js",
+        "debug.js",
+        "download.js",
+        "errors.js",
+        "ocsp.js",
+        "options.js",
+        "pkiutils.js",
+        "transport.js",
+        "bin/",
+        "tr-curl/"
+    ],
+    "scripts": {
+        "test": "node --test test/*.test.js"
+    },
+    "engines": {
+        "node": ">=26.0.0"
+    },
+    "dependencies": {
+        "asn1js": "^3.0.10",
+        "optist": "^2.0.1",
+        "pkijs": "^3.4.1",
+        "undici": "^8.11.2"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rinne/node-tr-fetch.git"
+    },
+    "keywords": [
+        "fetch",
+        "https",
+        "tls",
+        "x509",
+        "certificate",
+        "revocation",
+        "crl",
+        "ocsp",
+        "curl",
+        "security"
+    ],
+    "author": {
+        "name": "Timo J. Rinne",
+        "email": "tri@iki.fi",
+        "url": "https://github.com/rinne/"
+    },
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/rinne/node-tr-fetch/issues"
+    },
+    "homepage": "https://github.com/rinne/node-tr-fetch#readme"
+}

package/pkiutils.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const asn1 = require('asn1js');
+const pki = require('pkijs');
+const { webcrypto } = require('node:crypto');
+
+const cryptoEngine = new pki.CryptoEngine({ name: 'tr-fetch', crypto: webcrypto });
+
+function parseDer(bytes, Type) {
+    const decoded = asn1.fromBER(bytes);
+    if ((decoded.offset !== bytes.length) || decoded.result.error) {
+        throw new Error('Malformed ASN.1 data or trailing bytes');
+    }
+    return new Type({ schema: decoded.result });
+}
+
+function extensionsById(extensions = []) {
+    const result = new Map();
+    for (const extension of extensions) {
+        if (result.has(extension.extnID)) {
+            throw new Error(`Duplicate extension ${extension.extnID}`);
+        }
+        result.set(extension.extnID, extension);
+    }
+    return result;
+}
+
+function extensionValue(extension, Type) {
+    const data = extension.extnValue.valueBlock.valueHexView;
+    const decoded = asn1.fromBER(data);
+    if ((decoded.offset !== data.length) || decoded.result.error) {
+        throw new Error(`Malformed extension ${extension.extnID}`);
+    }
+    if (Type) {
+        return new Type({ schema: decoded.result });
+    }
+    return decoded.result;
+}
+
+function parseCertificate(bytes) {
+    return parseDer(bytes, pki.Certificate);
+}
+
+module.exports = { cryptoEngine, parseDer, extensionsById, extensionValue, parseCertificate };