harperdb 4.7.0-beta.3 → 4.7.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "harperdb",
-	"version": "4.7.0-beta.3",
+	"version": "4.7.0-beta.4",
 	"description": "HarperDB is a distributed database, caching service, streaming broker, and application development platform focused on performance and ease of use.",
 	"keywords": [
 		"database",
@@ -62,6 +62,7 @@
 		"@turf/length": "6.5.0",
 		"alasql": "4.6.6",
 		"argon2": "0.43.0",
+		"asn1js": "3.0.6",
 		"cbor-x": "1.6.0",
 		"chalk": "4.1.2",
 		"chokidar": "^4.0.3",
@@ -104,6 +105,7 @@
 		"passport-http": "0.3.0",
 		"passport-local": "1.0.0",
 		"pino": "8.16.0",
+		"pkijs": "3.2.5",
 		"prompt": "1.3.0",
 		"properties-reader": "2.3.0",
 		"recursive-iterator": "3.3.0",

package/resources/Table.d.ts

@@ -43,12 +43,12 @@ type ResidencyDefinition = number | string[] | void;
  */
 export declare function makeTable(options: any): {
     new (identifier: Id, source: any): {
-        #record: any;
-        #changes: any;
-        #version?: number;
-        #entry?: Entry;
-        #saveMode?: boolean;
-        #loadedFromSource?: boolean;
+        "__#private@#record": any;
+        "__#private@#changes": any;
+        "__#private@#version"?: number;
+        "__#private@#entry"?: Entry;
+        "__#private@#saveMode"?: boolean;
+        "__#private@#loadedFromSource"?: boolean;
         getProperty: (name: string) => any;
         /**
          * This is a request to explicitly ensure that the record is loaded from source, rather than only using the local record.
@@ -98,8 +98,8 @@ export declare function makeTable(options: any): {
             getExpiresAt(): number;
             addTo(property: string, value: number | bigint): void;
             subtractFrom(property: string, value: number | bigint): void;
-            #record: any;
-            #changes: any;
+            "__#private@#record": any;
+            "__#private@#changes": any;
             getRecord(): any;
             setRecord(record: any): void;
             getChanges(): any;
@@ -196,9 +196,9 @@ export declare function makeTable(options: any): {
         validate(record: any, patch?: boolean): void;
         getUpdatedTime(): number;
         wasLoadedFromSource(): boolean | void;
-        readonly #id: Id;
-        readonly #context: Context;
-        #isCollection: boolean;
+        readonly "__#private@#id": Id;
+        readonly "__#private@#context": Context;
+        "__#private@#isCollection": boolean;
         post(newRecord: any): Promise<any>;
         get isCollection(): boolean;
         connect(incomingMessages: import("./IterableEventQueue.js").IterableEventQueue, query?: {}): AsyncIterable<any>;
@@ -252,12 +252,12 @@ export declare function makeTable(options: any): {
      * @returns
      */
     getResource(id: Id, request: Context, resourceOptions?: any): Promise<{
-        #record: any;
-        #changes: any;
-        #version?: number;
-        #entry?: Entry;
-        #saveMode?: boolean;
-        #loadedFromSource?: boolean;
+        "__#private@#record": any;
+        "__#private@#changes": any;
+        "__#private@#version"?: number;
+        "__#private@#entry"?: Entry;
+        "__#private@#saveMode"?: boolean;
+        "__#private@#loadedFromSource"?: boolean;
         getProperty: (name: string) => any;
         /**
          * This is a request to explicitly ensure that the record is loaded from source, rather than only using the local record.
@@ -307,8 +307,8 @@ export declare function makeTable(options: any): {
             getExpiresAt(): number;
             addTo(property: string, value: number | bigint): void;
             subtractFrom(property: string, value: number | bigint): void;
-            #record: any;
-            #changes: any;
+            "__#private@#record": any;
+            "__#private@#changes": any;
             getRecord(): any;
             setRecord(record: any): void;
             getChanges(): any;
@@ -405,21 +405,21 @@ export declare function makeTable(options: any): {
         validate(record: any, patch?: boolean): void;
         getUpdatedTime(): number;
         wasLoadedFromSource(): boolean | void;
-        readonly #id: Id;
-        readonly #context: Context;
-        #isCollection: boolean;
+        readonly "__#private@#id": Id;
+        readonly "__#private@#context": Context;
+        "__#private@#isCollection": boolean;
         post(newRecord: any): Promise<any>;
         get isCollection(): boolean;
         connect(incomingMessages: import("./IterableEventQueue.js").IterableEventQueue, query?: {}): AsyncIterable<any>;
         getId(): Id;
         getContext(): Context | import("./ResourceInterface.ts").SourceContext;
     }> | {
-        #record: any;
-        #changes: any;
-        #version?: number;
-        #entry?: Entry;
-        #saveMode?: boolean;
-        #loadedFromSource?: boolean;
+        "__#private@#record": any;
+        "__#private@#changes": any;
+        "__#private@#version"?: number;
+        "__#private@#entry"?: Entry;
+        "__#private@#saveMode"?: boolean;
+        "__#private@#loadedFromSource"?: boolean;
         getProperty: (name: string) => any;
         /**
          * This is a request to explicitly ensure that the record is loaded from source, rather than only using the local record.
@@ -469,8 +469,8 @@ export declare function makeTable(options: any): {
             getExpiresAt(): number;
             addTo(property: string, value: number | bigint): void;
             subtractFrom(property: string, value: number | bigint): void;
-            #record: any;
-            #changes: any;
+            "__#private@#record": any;
+            "__#private@#changes": any;
             getRecord(): any;
             setRecord(record: any): void;
             getChanges(): any;
@@ -567,9 +567,9 @@ export declare function makeTable(options: any): {
         validate(record: any, patch?: boolean): void;
         getUpdatedTime(): number;
         wasLoadedFromSource(): boolean | void;
-        readonly #id: Id;
-        readonly #context: Context;
-        #isCollection: boolean;
+        readonly "__#private@#id": Id;
+        readonly "__#private@#context": Context;
+        "__#private@#isCollection": boolean;
         post(newRecord: any): Promise<any>;
         get isCollection(): boolean;
         connect(incomingMessages: import("./IterableEventQueue.js").IterableEventQueue, query?: {}): AsyncIterable<any>;
@@ -613,7 +613,7 @@ export declare function makeTable(options: any): {
     /**
      * Evicting a record will remove it from a caching table. This is not considered a canonical data change, and it is assumed that retrieving this record from the source will still yield the same record, this is only removing the local copy of the record.
      */
-    evict(id: any, existingRecord: any, existingVersion: any): Promise<void>;
+    evict(id: any, existingRecord: any, existingVersion: any): any;
     operation(operation: any, context: any): any;
     /**
      * This is responsible for ordering and select()ing the attributes/properties from returned entries

package/resources/blob.d.ts

@@ -11,6 +11,7 @@
  *   - Note that for compressed data, the size is the uncompressed size, and the compressed size in the file
  */
 import type { LMDBStore } from 'lmdb';
+import * as buffer from 'node:buffer';
 type StorageInfo = {
     storageIndex: number;
     fileId: string;
@@ -26,6 +27,7 @@ type StorageInfo = {
     end?: number;
     saving?: Promise<void>;
     asString?: string;
+    deleteOnFailure?: boolean;
 };
 export declare const Blob: {
     new (blobParts?: BlobPart[], options?: BlobPropertyBag): Blob;
@@ -38,7 +40,7 @@ export declare const Blob: {
         arrayBuffer(): Promise<ArrayBufferLike>;
         get size(): number;
         slice(): /*elided*/ any;
-        bytes(): Promise<Buffer>;
+        bytes(): Promise<buffer.Buffer>;
         get type(): string;
     };
 };
@@ -52,7 +54,7 @@ declare namespace InstanceOfBlobWithNoConstructor {
         arrayBuffer(): Promise<ArrayBufferLike>;
         get size(): number;
         slice(): /*elided*/ any;
-        bytes(): Promise<Buffer>;
+        bytes(): Promise<buffer.Buffer>;
         get type(): string;
     };
 }
@@ -81,6 +83,7 @@ declare class FileBackedBlob extends InstanceOfBlobWithNoConstructor {
     stream(): ReadableStream;
     slice(start: number, end: number, type?: string): Blob;
     save(): Promise<void>;
+    get written(): Promise<void>;
 }
 /**
  * Delete the file for the blob
@@ -95,7 +98,7 @@ export type BlobCreationOptions = {
     size?: number;
     saveBeforeCommit?: boolean;
 };
-export declare function saveBlob(blob: FileBackedBlob): StorageInfo;
+export declare function saveBlob(blob: FileBackedBlob, deleteOnFailure?: boolean): StorageInfo;
 export declare function getFileId(blob: Blob): string;
 export declare function isSaving(blob: Blob): string;
 export declare function getFilePathForBlob(blob: FileBackedBlob): string;

package/resources/openApi.d.ts

@@ -0,0 +1,27 @@
+import { Resources } from './Resources.ts';
+export declare function generateJsonApi(resources: Resources, serverHttpURL: string): {
+    openapi: string;
+    info: {
+        title: string;
+        version: any;
+    };
+    servers: {
+        description: string;
+        url: string;
+    }[];
+    paths: {};
+    components: {
+        schemas: {};
+        securitySchemes: {
+            basicAuth: {
+                type: string;
+                scheme: string;
+            };
+            bearerAuth: {
+                type: string;
+                scheme: string;
+                bearerFormat: string;
+            };
+        };
+    };
+};

package/security/certificateVerification/certificateVerificationSource.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Certificate verification source that handles both CRL and OCSP methods
+ */
+import { Resource } from '../../resources/Resource.ts';
+import type { Query } from '../../resources/ResourceInterface.ts';
+/**
+ * Certificate Verification Source that can handle both CRL and OCSP
+ */
+export declare class CertificateVerificationSource extends Resource {
+    get(query: Query): Promise<{
+        certificate_id: string;
+        status: any;
+        reason: any;
+        checked_at: number;
+        expiresAt: any;
+        method: string;
+    }>;
+}

package/security/certificateVerification/configValidation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Configuration validation for certificate verification
+ */
+import type { CertificateVerificationConfig, OCSPDefaults, CRLDefaults } from './types.ts';
+export declare const DEFAULT_FAILURE_MODE = "fail-closed";
+export declare const OCSP_DEFAULTS: OCSPDefaults;
+export declare const CRL_DEFAULTS: CRLDefaults;
+/**
+ * Validate and parse certificate verification configuration
+ * @param config - Certificate verification configuration to validate
+ * @returns Validated and parsed configuration object
+ * @throws {Error} If configuration is invalid
+ */
+export declare function validateAndParseCertificateVerificationConfig(config: unknown): CertificateVerificationConfig;

package/security/certificateVerification/crlVerification.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CRL (Certificate Revocation List) verification
+ */
+import type { CertificateVerificationResult, CRLCheckResult, CRLConfig } from './types.ts';
+/**
+ * Custom error for CRL signature verification failures
+ * This distinguishes security failures (invalid signatures) from operational failures (network, timeout)
+ */
+export declare class CRLSignatureVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify CRL status of a client certificate
+ * @param certPem - Client certificate as Buffer (DER format)
+ * @param issuerPem - Issuer (CA) certificate as Buffer (DER format)
+ * @param config - CRL configuration
+ * @param crlUrls - Optional pre-extracted CRL distribution point URLs (avoids re-parsing)
+ * @returns Promise resolving to verification result
+ */
+export declare function verifyCRL(certPem: Buffer, issuerPem: Buffer, config?: CRLConfig, crlUrls?: string[]): Promise<CertificateVerificationResult>;
+/**
+ * Perform the actual CRL check by looking up the certificate in the revoked certificates table
+ * @param certPem - Certificate in PEM format
+ * @param issuerPem - Issuer certificate in PEM format
+ * @param config - CRL configuration
+ * @param crlUrls - Optional pre-extracted CRL distribution point URLs (avoids re-parsing)
+ * @returns CRL check result
+ */
+export declare function performCRLCheck(certPem: string, issuerPem: string, config: CRLConfig, crlUrls?: string[]): Promise<CRLCheckResult>;

package/security/certificateVerification/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 type { PeerCertificate, CertificateVerificationResult } from './types.ts';
+/**
+ * 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 declare function verifyCertificate(peerCertificate: PeerCertificate, mtlsConfig?: boolean | Record<string, any> | null): Promise<CertificateVerificationResult>;

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;