@harperfast/harper 5.0.0-alpha.10 → 5.0.0-beta.1

package/security/certificateVerification/index.ts

@@ -0,0 +1,121 @@
+/**
+ * Certificate verification for mTLS authentication
+ *
+ * This module provides certificate revocation checking for client certificates
+ * in mutual TLS (mTLS) connections. Supports both OCSP (Online Certificate
+ * Status Protocol) and CRL (Certificate Revocation List) verification methods
+ * with automatic method selection.
+ *
+ * Features:
+ * - OCSP verification with caching
+ * - CRL verification with caching
+ * - CRL-first with OCSP fallback for optimal performance
+ * - Background CRL refresh with exponential backoff
+ * - Graceful degradation during network outages
+ * - Ed25519/Ed448 certificate support
+ *
+ * Default behavior:
+ * - Certificate verification: disabled (must be explicitly enabled)
+ * - Verification approach: CRL-first (with OCSP fallback)
+ * - CRL timeout: 10 seconds, cache TTL: 24 hours
+ * - OCSP timeout: 5 seconds, cache TTL: 1 hour
+ * - Failure mode: fail-closed (rejects connections if verification fails)
+ */
+
+import { loggerWithTag } from '../../utility/logging/logger.ts';
+import { extractCertificateChain, extractRevocationUrls, bufferToPem } from './verificationUtils.ts';
+import { getCachedCertificateVerificationConfig } from './verificationConfig.ts';
+import { verifyOCSP } from './ocspVerification.ts';
+import { verifyCRL } from './crlVerification.ts';
+import type { PeerCertificate, CertificateVerificationResult } from './types.ts';
+
+const logger = loggerWithTag('cert-verification');
+
+/**
+ * Verify certificate revocation status using OCSP and/or CRL
+ * @param peerCertificate - Peer certificate object from TLS connection
+ * @param mtlsConfig - The mTLS configuration from the request
+ * @returns Promise resolving to verification result
+ */
+export async function verifyCertificate(
+	peerCertificate: PeerCertificate,
+	mtlsConfig?: boolean | Record<string, any> | null
+): Promise<CertificateVerificationResult> {
+	logger.debug?.(`verifyCertificate called for: ${peerCertificate.subject?.CN || 'unknown'}`);
+
+	// Get the verification configuration from mtlsConfig (cached for performance)
+	const config = getCachedCertificateVerificationConfig(mtlsConfig);
+
+	// If config is false, verification is disabled
+	if (config === false) {
+		logger.debug?.('Certificate verification disabled');
+		return { valid: true, status: 'disabled', method: 'disabled' };
+	}
+
+	// Extract certificate chain
+	const certChain = extractCertificateChain(peerCertificate);
+	logger.trace?.(`Certificate chain length: ${certChain.length}`);
+
+	// Check if we have sufficient chain for verification (need certificate and issuer)
+	if (certChain.length < 2 || !certChain[0].issuer) {
+		logger.debug?.('Certificate chain insufficient for revocation checking - need certificate and issuer');
+		return { valid: true, status: 'no-issuer-cert', method: 'disabled' };
+	}
+
+	// Extract certificate revocation URLs in single parse operation
+	const certPem = bufferToPem(certChain[0].cert, 'CERTIFICATE');
+	const { crlUrls, ocspUrls } = extractRevocationUrls(certPem);
+
+	logger.debug?.(`Certificate extensions: CRL distribution points=${crlUrls.length}, OCSP URLs=${ocspUrls.length}`);
+
+	// Try CRL first (can provide definitive results)
+	if (crlUrls.length > 0) {
+		if (config.crl.enabled) {
+			try {
+				logger.debug?.('Attempting CRL verification');
+				const result = await verifyCRL(certChain[0].cert, certChain[0].issuer, config.crl, crlUrls);
+
+				// Return on definitive result (good or revoked)
+				if (result.status === 'good' || result.status === 'revoked') {
+					logger.debug?.(`CRL verification result: ${result.status}`);
+					return result;
+				}
+
+				logger.debug?.(`CRL verification inconclusive: ${result.status}, trying OCSP fallback`);
+			} catch (error) {
+				logger.warn?.(`CRL verification failed: ${error}`);
+			}
+		} else {
+			logger.debug?.('Skipping CRL - disabled in configuration');
+		}
+	} else {
+		logger.debug?.('Skipping CRL - no distribution points in certificate');
+	}
+
+	// Fall back to OCSP if available (real-time status)
+	if (ocspUrls.length > 0) {
+		if (config.ocsp.enabled) {
+			try {
+				logger.debug?.('Attempting OCSP verification');
+				const result = await verifyOCSP(certChain[0].cert, certChain[0].issuer, config.ocsp, ocspUrls);
+
+				// Return result (definitive or not)
+				logger.debug?.(`OCSP verification result: ${result.status}`);
+				return result;
+			} catch (error) {
+				logger.warn?.(`OCSP verification failed: ${error}`);
+			}
+		} else {
+			logger.debug?.('Skipping OCSP - disabled in configuration');
+		}
+	} else {
+		logger.debug?.('Skipping OCSP - no responder URLs in certificate');
+	}
+
+	// All methods tried or skipped - determine failure handling
+	if (config.failureMode === 'fail-closed') {
+		return { valid: false, status: 'no-verification-available', method: 'disabled' };
+	}
+
+	return { valid: true, status: 'verification-unavailable-allowed', method: 'disabled' };
+}

package/security/certificateVerification/ocspVerification.ts

@@ -0,0 +1,148 @@
+/**
+ * OCSP (Online Certificate Status Protocol) verification
+ */
+
+// Apply PKI.js Ed25519 patch before importing easy-ocsp
+import './pkijs-ed25519-patch.ts';
+import { getCertStatus } from 'easy-ocsp';
+import { loggerWithTag } from '../../utility/logging/logger.ts';
+import {
+	bufferToPem,
+	createCacheKey,
+	getCertificateCacheTable as getSharedCertificateCacheTable,
+} from './verificationUtils.ts';
+import type {
+	CertificateVerificationResult,
+	CertificateVerificationContext,
+	CertificateCacheEntry,
+	OCSPCheckResult,
+	OCSPConfig,
+} from './types.ts';
+
+const logger = loggerWithTag('ocsp-verification');
+
+// Import the shared source
+import { CertificateVerificationSource } from './certificateVerificationSource.ts';
+
+// Lazy-load the certificate verification cache table
+let certCacheTable: ReturnType<typeof getSharedCertificateCacheTable>;
+function getCertificateCacheTable() {
+	if (!certCacheTable) {
+		certCacheTable = getSharedCertificateCacheTable();
+		// Configure the caching source using the shared CertificateVerificationSource class
+		(certCacheTable as any).sourcedFrom(CertificateVerificationSource);
+	}
+	return certCacheTable;
+}
+
+/**
+ * Verify OCSP status of a client certificate
+ * @param certPem - Client certificate as Buffer (DER format)
+ * @param issuerPem - Issuer (CA) certificate as Buffer (DER format)
+ * @param config - OCSP configuration
+ * @param ocspUrls - Optional pre-extracted OCSP responder URLs (avoids re-parsing)
+ * @returns Promise resolving to verification result
+ */
+export async function verifyOCSP(
+	certPem: Buffer,
+	issuerPem: Buffer,
+	config?: OCSPConfig,
+	ocspUrls?: string[]
+): Promise<CertificateVerificationResult> {
+	// Check if OCSP verification is disabled
+	if (config?.enabled === false) {
+		return { valid: true, status: 'disabled', method: 'disabled' };
+	}
+
+	try {
+		// Convert DER buffers to PEM strings for certificate parsing libraries
+		// PKI.js and easy-ocsp expect PEM format for extension extraction and OCSP requests
+		const certPemStr = bufferToPem(certPem, 'CERTIFICATE');
+		const issuerPemStr = bufferToPem(issuerPem, 'CERTIFICATE');
+
+		// Create a cache key that includes all verification parameters
+		const cacheKey = createCacheKey(certPemStr, issuerPemStr, 'ocsp');
+
+		// Get the cache table - Harper will automatically handle
+		// concurrent requests and cache stampede prevention
+		// Pass certificate data as context - Harper will make it available as requestContext in the source
+		const cacheEntry = await (getCertificateCacheTable() as any).get(cacheKey, {
+			certPem: certPemStr,
+			issuerPem: issuerPemStr,
+			ocspUrls,
+			config: { ocsp: config ?? {} },
+		} as CertificateVerificationContext);
+
+		if (!cacheEntry) {
+			// This should not happen if the source is configured correctly
+			// but handle it gracefully
+			if (config.failureMode === 'fail-closed') {
+				return { valid: false, status: 'error', error: 'Cache fetch failed', method: 'ocsp' };
+			}
+
+			logger.warn?.('OCSP cache fetch failed, allowing connection (fail-open mode)');
+			return { valid: true, status: 'error-allowed', method: 'ocsp' };
+		}
+
+		const cached = cacheEntry as unknown as CertificateCacheEntry;
+		const wasLoadedFromSource = (cacheEntry as any).wasLoadedFromSource?.();
+		logger.trace?.(`OCSP ${wasLoadedFromSource ? 'source fetch' : 'cache hit'} for certificate`);
+
+		return {
+			valid: cached.status === 'good',
+			status: cached.status,
+			cached: !wasLoadedFromSource,
+			method: cached.method || 'ocsp',
+		};
+	} catch (error) {
+		logger.error?.(`OCSP verification error: ${error}`);
+
+		// Check failure mode
+		if (config.failureMode === 'fail-closed') {
+			return { valid: false, status: 'error', error: (error as Error).message, method: 'ocsp' };
+		}
+
+		// Fail open - allow connection on OCSP errors
+		logger.warn?.('OCSP check failed, allowing connection (fail-open mode)');
+		return { valid: true, status: 'error-allowed', method: 'ocsp' };
+	}
+}
+
+/**
+ * Perform the actual OCSP check using easy-ocsp
+ * @param certPem - Certificate in PEM format
+ * @param issuerPem - Issuer certificate in PEM format
+ * @param config - OCSP configuration
+ * @param ocspUrls - Optional pre-extracted OCSP responder URLs (avoids re-parsing)
+ * @returns OCSP check result
+ */
+export async function performOCSPCheck(
+	certPem: string,
+	issuerPem: string,
+	config: any,
+	ocspUrls?: string[]
+): Promise<OCSPCheckResult> {
+	try {
+		const response = await getCertStatus(certPem, {
+			ca: issuerPem,
+			timeout: config.timeout,
+			...(ocspUrls?.length && { ocspUrl: ocspUrls[0] }),
+		});
+
+		// Map response status to internal format
+		switch (response.status) {
+			case 'good':
+				return { status: 'good' };
+			case 'revoked':
+				return { status: 'revoked', reason: response.revocationReason?.toString() || 'unspecified' };
+			default:
+				return { status: 'unknown', reason: 'unknown-status' };
+		}
+	} catch (error) {
+		const err = error as Error;
+
+		// Return appropriate error based on type
+		const reason = err.name === 'AbortError' ? 'timeout' : 'ocsp-error';
+		return { status: 'unknown', reason };
+	}
+}

package/security/certificateVerification/pkijs-ed25519-patch.ts

@@ -0,0 +1,188 @@
+/**
+ * PKI.js Ed25519/Ed448 Support Patch
+ *
+ * This module patches PKI.js to add complete Ed25519/Ed448 support for certificate
+ * and OCSP response verification. While PKI.js has some Ed25519/Ed448 support,
+ * it currently lacks:
+ * - getHashAlgorithm() support for Ed25519/Ed448 OIDs
+ * - getAlgorithmByOID() recognition of Ed25519/Ed448
+ * - Certificate verification using Ed25519/Ed448 signatures
+ * - OCSP response signature verification with Ed25519/Ed448
+ *
+ * This patch must be loaded before any module that uses PKI.js (including easy-ocsp).
+ */
+
+import * as pkijs from 'pkijs';
+import { webcrypto, X509Certificate } from 'node:crypto';
+
+// Ed25519/Ed448 OIDs (these are standardized object identifiers, not IP addresses)
+const ED25519_OID = '1.3.101.112' as const;
+const ED448_OID = '1.3.101.113' as const;
+type EdDSAOID = typeof ED25519_OID | typeof ED448_OID;
+
+// Algorithm names as constants
+const ED25519_NAME = 'Ed25519' as const;
+const ED448_NAME = 'Ed448' as const;
+type EdDSAAlgorithmName = typeof ED25519_NAME | typeof ED448_NAME;
+
+// Apply patches only once
+let patchesApplied = false;
+
+function isEd25519OrEd448(oid: string): oid is EdDSAOID {
+	return oid === ED25519_OID || oid === ED448_OID;
+}
+
+function isEdDSAAlgorithmName(name: string): name is EdDSAAlgorithmName {
+	return name === ED25519_NAME || name === ED448_NAME;
+}
+
+function getEdDSAAlgorithmName(oid: string): EdDSAAlgorithmName {
+	return oid === ED25519_OID ? ED25519_NAME : ED448_NAME;
+}
+
+export function applyEd25519Patch(): void {
+	if (patchesApplied) return;
+	patchesApplied = true;
+
+	const CryptoEngine = pkijs.CryptoEngine.prototype;
+	const Certificate = pkijs.Certificate.prototype;
+
+	// Store original methods
+	const originals = {
+		getHashAlgorithm: CryptoEngine.getHashAlgorithm,
+		getAlgorithmByOID: CryptoEngine.getAlgorithmByOID,
+		getAlgorithmParameters: CryptoEngine.getAlgorithmParameters,
+		verifyWithPublicKey: CryptoEngine.verifyWithPublicKey,
+		certificateVerify: Certificate.verify,
+		getPublicKey: Certificate.getPublicKey,
+	};
+
+	// Patch getHashAlgorithm - Ed25519/Ed448 don't use separate hashes
+	CryptoEngine.getHashAlgorithm = function (
+		...params: Parameters<typeof originals.getHashAlgorithm>
+	): ReturnType<typeof originals.getHashAlgorithm> {
+		const [signatureAlgorithm] = params;
+		if (isEd25519OrEd448(signatureAlgorithm.algorithmId)) {
+			// EdDSA signatures have built-in hash functions per RFC 8032:
+			// - Ed25519 uses SHA-512 internally (Section 5.1.6)
+			// - Ed448 uses SHAKE256 internally (Section 5.2.6)
+			// The hash is not a parameter - it's part of the algorithm definition.
+			// Returning a placeholder since PKI.js expects a string, but our patched
+			// verification methods bypass any code that would use this value.
+			return 'UNUSED-EDDSA-BUILTIN-HASH';
+		}
+		return originals.getHashAlgorithm.call(this, signatureAlgorithm);
+	};
+
+	// Patch getAlgorithmByOID to recognize Ed25519/Ed448
+	CryptoEngine.getAlgorithmByOID = function (
+		...params: Parameters<typeof originals.getAlgorithmByOID>
+	): ReturnType<typeof originals.getAlgorithmByOID> {
+		const [oid] = params;
+		if (isEd25519OrEd448(oid)) {
+			return { name: getEdDSAAlgorithmName(oid) };
+		}
+		return originals.getAlgorithmByOID.call(this, ...params);
+	};
+
+	// Patch getAlgorithmParameters
+	CryptoEngine.getAlgorithmParameters = function (
+		...params: Parameters<typeof originals.getAlgorithmParameters>
+	): ReturnType<typeof originals.getAlgorithmParameters> {
+		const [algorithmName, operation] = params;
+		if (isEdDSAAlgorithmName(algorithmName)) {
+			return {
+				algorithm: { name: algorithmName },
+				usages: operation === 'sign' ? ['sign'] : ['verify'],
+			};
+		}
+		return originals.getAlgorithmParameters.call(this, ...params);
+	};
+
+	// Patch getPublicKey for Ed25519/Ed448
+	Certificate.getPublicKey = async function (
+		...params: Parameters<typeof originals.getPublicKey>
+	): ReturnType<typeof originals.getPublicKey> {
+		const [, cryptoEngine = pkijs.getCrypto(true)] = params;
+		const algId = this.subjectPublicKeyInfo.algorithm.algorithmId;
+		if (isEd25519OrEd448(algId)) {
+			const algorithmName = getEdDSAAlgorithmName(algId);
+			return cryptoEngine.importKey('spki', this.subjectPublicKeyInfo.toSchema().toBER(false), algorithmName, true, [
+				'verify',
+			]);
+		}
+		return originals.getPublicKey.call(this, ...params);
+	};
+
+	// Patch Certificate.verify for Ed25519/Ed448
+	Certificate.verify = async function (
+		...params: Parameters<typeof originals.certificateVerify>
+	): ReturnType<typeof originals.certificateVerify> {
+		const [issuerCertificate] = params;
+		if (isEd25519OrEd448(this.signatureAlgorithm.algorithmId)) {
+			try {
+				// Use Node.js X509Certificate for Ed25519/Ed448 verification
+				const certDer = this.toSchema().toBER(false);
+				const issuerDer = issuerCertificate.toSchema().toBER(false);
+
+				const nodeCert = new X509Certificate(Buffer.from(certDer));
+				const nodeIssuer = new X509Certificate(Buffer.from(issuerDer));
+
+				return nodeCert.verify(nodeIssuer.publicKey);
+			} catch {
+				// Any failure in verification should return false
+				return false;
+			}
+		}
+		return originals.certificateVerify.call(this, ...params);
+	};
+
+	// Patch verifyWithPublicKey for OCSP response verification
+	if (originals.verifyWithPublicKey) {
+		CryptoEngine.verifyWithPublicKey = async function (
+			...params: Parameters<typeof originals.verifyWithPublicKey>
+		): ReturnType<typeof originals.verifyWithPublicKey> {
+			const [data, signature, publicKeyInfo] = params;
+			const algId = publicKeyInfo.algorithm.algorithmId;
+			if (isEd25519OrEd448(algId)) {
+				const algorithmName = getEdDSAAlgorithmName(algId);
+
+				try {
+					// Get crypto.subtle from available sources
+					const cryptoSubtle =
+						(this as any).crypto?.subtle || (this as any).subtle || pkijs.getCrypto(true)?.subtle || webcrypto?.subtle;
+
+					if (!cryptoSubtle) {
+						throw new Error('No crypto.subtle available');
+					}
+
+					// Import the public key
+					const publicKey = await cryptoSubtle.importKey(
+						'spki',
+						publicKeyInfo.toSchema().toBER(false),
+						algorithmName,
+						false,
+						['verify']
+					);
+
+					// Handle BIT STRING signature value
+					let signatureValue = signature.valueBlock.valueHexView;
+					// Check if this is a BIT STRING with unused bits
+					if ('unusedBits' in signature.valueBlock && signature.valueBlock.unusedBits > 0) {
+						signatureValue = signatureValue.slice(0, signatureValue.length - 1);
+					}
+
+					// Verify the signature
+					return await cryptoSubtle.verify(algorithmName, publicKey, signatureValue, data);
+				} catch {
+					// Any failure in verification should return false
+					return false;
+				}
+			}
+			return originals.verifyWithPublicKey.call(this, ...params);
+		};
+	}
+}
+
+// Apply patch on module load
+applyEd25519Patch();

package/security/certificateVerification/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared TypeScript interfaces and types for certificate verification
+ */
+
+import type { Context } from '../../resources/ResourceInterface.ts';
+
+export type CertificateStatus = 'good' | 'revoked' | 'unknown';
+
+export type VerificationMethod = 'ocsp' | 'crl';
+export type VerificationResultMethod = VerificationMethod | 'disabled';
+
+export type FailureMode = 'fail-open' | 'fail-closed';
+
+export interface PeerCertificate {
+	subject?: {
+		CN?: string;
+		[key: string]: any;
+	};
+	raw?: Buffer;
+	issuerCertificate?: PeerCertificate;
+}
+
+export interface CertificateVerificationResult {
+	valid: boolean;
+	status: string;
+	cached?: boolean;
+	error?: string;
+	method?: VerificationResultMethod;
+}
+
+export interface CertificateCacheEntry {
+	certificate_id: string;
+	status: CertificateStatus;
+	reason?: string;
+	checked_at: number;
+	expiresAt: number;
+	method: VerificationMethod;
+}
+
+export interface CRLCacheEntry {
+	distribution_point: string;
+	issuer_dn: string;
+	crl_blob: Buffer;
+	this_update: number;
+	next_update: number;
+	signature_valid: boolean;
+	expiresAt: number;
+}
+
+export interface RevokedCertificateEntry {
+	composite_id: string; // {issuer_hash}:{serial_number}
+	serial_number: string;
+	issuer_key_id: string;
+	revocation_date: number;
+	revocation_reason?: string;
+	crl_source: string; // Links to CRLCacheEntry.crl_id
+	crl_next_update: number;
+	expiresAt: number;
+}
+
+export interface CertificateChainEntry {
+	cert: Buffer;
+	issuer?: Buffer;
+}
+
+export interface OCSPCheckResult {
+	status: CertificateStatus;
+	reason?: string;
+}
+
+export interface CRLCheckResult {
+	status: CertificateStatus;
+	reason?: string;
+	source?: string; // CRL distribution point URL
+}
+
+// Configuration interfaces
+export interface OCSPConfig {
+	enabled?: boolean;
+	timeout?: number;
+	cacheTtl?: number;
+	errorCacheTtl?: number;
+	failureMode?: FailureMode;
+}
+
+export interface CRLConfig {
+	enabled?: boolean;
+	timeout?: number;
+	cacheTtl?: number;
+	failureMode?: FailureMode;
+	gracePeriod?: number;
+}
+
+export interface CertificateVerificationConfig {
+	failureMode?: FailureMode;
+	ocsp?: OCSPConfig;
+	crl?: CRLConfig;
+}
+
+// Context types for certificate verification cache requests
+export interface CertificateVerificationContext extends Context {
+	certPem: string;
+	issuerPem: string;
+	ocspUrls?: string[];
+	distributionPoint?: string;
+	config?: CertificateVerificationConfig;
+}
+
+export interface CRLVerificationContext extends Context {
+	distributionPoint: string;
+	issuerPem: string;
+	config?: CRLConfig;
+}
+
+// Default configuration values
+export interface VerificationDefaults {
+	timeout: number;
+	cacheTtl: number;
+	failureMode: FailureMode;
+}
+
+export interface OCSPDefaults extends VerificationDefaults {
+	errorCacheTtl: number;
+}
+
+export interface CRLDefaults extends VerificationDefaults {
+	gracePeriod: number;
+}