harperdb 4.7.0-beta.2 → 4.7.0-beta.4

package/security/certificateVerification/ocspVerification.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OCSP (Online Certificate Status Protocol) verification
+ */
+import './pkijs-ed25519-patch.ts';
+import type { CertificateVerificationResult, OCSPCheckResult, OCSPConfig } from './types.ts';
+/**
+ * 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 declare function verifyOCSP(certPem: Buffer, issuerPem: Buffer, config?: OCSPConfig, ocspUrls?: string[]): Promise<CertificateVerificationResult>;
+/**
+ * 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 declare function performOCSPCheck(certPem: string, issuerPem: string, config: any, ocspUrls?: string[]): Promise<OCSPCheckResult>;

package/security/certificateVerification/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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;
+    serial_number: string;
+    issuer_key_id: string;
+    revocation_date: number;
+    revocation_reason?: string;
+    crl_source: string;
+    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;
+}
+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;
+}
+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;
+}
+export interface VerificationDefaults {
+    timeout: number;
+    cacheTtl: number;
+    failureMode: FailureMode;
+}
+export interface OCSPDefaults extends VerificationDefaults {
+    errorCacheTtl: number;
+}
+export interface CRLDefaults extends VerificationDefaults {
+    gracePeriod: number;
+}

package/security/certificateVerification/verificationConfig.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration parsing and default values for certificate verification
+ */
+import type { CertificateVerificationConfig } from './types.ts';
+export declare const CRL_DEFAULT_VALIDITY_PERIOD: number;
+export declare const ERROR_CACHE_TTL = 300000;
+export declare const CRL_USER_AGENT: string;
+/**
+ * Cached version of getCertificateVerificationConfig to avoid redundant parsing
+ * This is the recommended function to use in hot paths like certificate verification.
+ *
+ * MEMORY SAFETY:
+ * - Uses WeakMap for object configs to prevent memory leaks
+ * - Config objects can be garbage collected when no longer referenced elsewhere
+ * - Primitive values (boolean, null, undefined) use simple reference equality
+ * - No strong references held to config objects, preventing memory accumulation
+ *
+ * ERROR HANDLING:
+ * - Invalid config causes validation errors to be thrown on first access
+ * - Validation errors are logged once and then cached
+ * - Subsequent accesses with the same invalid config return false (disabled) to prevent
+ *   repeated error logging and allow the application to continue running
+ * - This provides fail-safe behavior: invalid security config defaults to disabled
+ *   rather than crashing on every request
+ *
+ * @param mtlsConfig - The mTLS configuration from env.get()
+ * @returns Configuration object or false if verification is disabled or invalid
+ */
+export declare function getCachedCertificateVerificationConfig(mtlsConfig?: boolean | Record<string, any> | null): false | CertificateVerificationConfig;

package/security/certificateVerification/verificationUtils.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared utilities for certificate verification
+ */
+import type { PeerCertificate, CertificateChainEntry } from './types.ts';
+/**
+ * Convert a buffer to PEM format
+ * @param buffer - Certificate data as buffer
+ * @param type - Certificate type (e.g., 'CERTIFICATE')
+ * @returns PEM formatted string
+ */
+export declare function bufferToPem(buffer: Buffer, type: string): string;
+/**
+ * Extract certificate chain from peer certificate object
+ * @param peerCertificate - Peer certificate object from TLS connection
+ * @returns Certificate chain with issuer relationships
+ */
+export declare function extractCertificateChain(peerCertificate: PeerCertificate): CertificateChainEntry[];
+/**
+ * Extract CRL Distribution Points from a certificate using PKI.js
+ * @param certPem - Certificate in PEM format
+ * @returns Array of CRL distribution point URLs
+ */
+export declare function extractCRLDistributionPoints(certPem: string): string[];
+/**
+ * Extract both CRL and OCSP URLs from a certificate in a single parse operation
+ * @param certPem - Certificate in PEM format
+ * @returns Object containing arrays of CRL and OCSP URLs
+ */
+export declare function extractRevocationUrls(certPem: string): {
+    crlUrls: string[];
+    ocspUrls: string[];
+};
+/**
+ * Extract OCSP responder URLs from a certificate
+ * @param certPem - Certificate in PEM format
+ * @returns Array of OCSP responder URLs
+ */
+export declare function extractOCSPUrls(certPem: string): string[];
+/**
+ * Convert PEM string to buffer for PKI.js parsing
+ * @param pem - PEM formatted certificate
+ * @returns Buffer containing certificate data
+ */
+export declare function pemToBuffer(pem: string): ArrayBuffer;
+/**
+ * Create a cache key for certificate verification
+ * @param certPem - Certificate in PEM format
+ * @param issuerPem - Issuer certificate in PEM format
+ * @param method - Verification method (ocsp, crl)
+ * @param additionalData - Additional data to include in hash
+ * @returns Cache key string
+ */
+export declare function createCacheKey(certPem: string, issuerPem: string, method: 'ocsp' | 'crl', additionalData?: Record<string, any>): string;
+/**
+ * Create a cache key for CRL storage
+ * @param distributionPoint - CRL distribution point URL
+ * @returns Cache key string
+ */
+export declare function createCRLCacheKey(distributionPoint: string): string;
+/**
+ * Create a composite ID for revoked certificate lookup
+ * @param issuerKeyId - Issuer key identifier or DN hash
+ * @param serialNumber - Certificate serial number
+ * @returns Composite ID string
+ */
+export declare function createRevokedCertificateId(issuerKeyId: string, serialNumber: string): string;
+/**
+ * Extract serial number from a certificate
+ * @param certPem - Certificate in PEM format
+ * @returns Certificate serial number as string
+ */
+export declare function extractSerialNumber(certPem: string): string;
+/**
+ * Extract issuer key identifier from a certificate
+ * @param certPem - Certificate in PEM format
+ * @returns Issuer key identifier as hex string, or hash of issuer DN if not available
+ */
+export declare function extractIssuerKeyId(certPem: string): string;
+export declare function getCertificateCacheTable(): unknown;