@digitaldefiance/secrets 2.0.3

package/dist/esm/browser-types.d.ts

@@ -0,0 +1,112 @@
+import type { RNGFunction, CSPRNGType } from './types';
+import { CryptoError } from './errors';
+/**
+ * Enhanced browser Web Crypto API interface with comprehensive typing
+ */
+export interface BrowserCryptoAPI {
+    /**
+     * Generates cryptographically strong random values
+     * @param array - Typed array to fill with random values
+     * @returns The same array filled with random values
+     * @throws {Error} If random value generation fails
+     */
+    getRandomValues<T extends ArrayBufferView>(array: T): T;
+    /**
+     * SubtleCrypto interface for advanced cryptographic operations
+     */
+    subtle?: SubtleCrypto;
+}
+/**
+ * Browser window.crypto interface
+ */
+export interface WindowCrypto {
+    crypto?: BrowserCryptoAPI;
+}
+/**
+ * Type guard for Uint32Array
+ */
+export declare function isUint32Array(value: unknown): value is Uint32Array;
+/**
+ * Type guard for any typed array
+ */
+export declare function isTypedArray(value: unknown): value is ArrayBufferView;
+/**
+ * Detects if the current environment is a browser
+ * @returns true if running in a browser, false otherwise
+ */
+export declare function isBrowserEnvironment(): boolean;
+/**
+ * Attempts to access the browser Web Crypto API
+ * @returns BrowserCryptoAPI if available, null otherwise
+ */
+export declare function getBrowserCrypto(): BrowserCryptoAPI | null;
+/**
+ * Checks if browser crypto.getRandomValues is available
+ * @returns true if crypto.getRandomValues is available
+ */
+export declare function hasBrowserCryptoGetRandomValues(): boolean;
+/**
+ * Error thrown when browser crypto operations fail
+ */
+export declare class BrowserCryptoError extends CryptoError {
+    readonly originalError?: Error | undefined;
+    constructor(operation: string, reason: string, originalError?: Error | undefined);
+}
+/**
+ * Error thrown when browser environment is required but not available
+ */
+export declare class BrowserEnvironmentError extends CryptoError {
+    constructor(feature: string);
+}
+/**
+ * Error thrown when Web Crypto API is not supported
+ */
+export declare class WebCryptoNotSupportedError extends BrowserCryptoError {
+    constructor();
+}
+/**
+ * Creates a browser-specific RNG function using crypto.getRandomValues
+ * @param crypto - Browser Web Crypto API
+ * @returns RNG function that generates random binary strings
+ * @throws {BrowserCryptoError} If random value generation fails
+ */
+export declare function createBrowserRNG(crypto: BrowserCryptoAPI): RNGFunction;
+/**
+ * Browser-specific crypto environment descriptor
+ */
+export interface BrowserCryptoEnvironment {
+    readonly type: 'browser';
+    readonly crypto: BrowserCryptoAPI;
+    readonly rngType: CSPRNGType;
+    readonly rng: RNGFunction;
+}
+/**
+ * Creates a browser crypto environment descriptor
+ * @returns BrowserCryptoEnvironment if browser crypto is available, null otherwise
+ */
+export declare function createBrowserCryptoEnvironment(): BrowserCryptoEnvironment | null;
+/**
+ * Validates that a value is a valid Uint32Array
+ * @param value - Value to validate
+ * @param paramName - Parameter name for error messages
+ * @throws {BrowserCryptoError} If value is not a valid Uint32Array
+ */
+export declare function validateUint32Array(value: unknown, paramName: string): asserts value is Uint32Array;
+/**
+ * Validates that a value is a valid typed array
+ * @param value - Value to validate
+ * @param paramName - Parameter name for error messages
+ * @throws {BrowserCryptoError} If value is not a valid typed array
+ */
+export declare function validateTypedArray(value: unknown, paramName: string): asserts value is ArrayBufferView;
+/**
+ * Validates that browser crypto is available
+ * @throws {WebCryptoNotSupportedError} If browser crypto is not available
+ */
+export declare function requireBrowserCrypto(): BrowserCryptoAPI;
+/**
+ * Checks if the browser supports the Web Crypto API
+ * @returns true if Web Crypto API is fully supported
+ */
+export declare function isWebCryptoSupported(): boolean;
+//# sourceMappingURL=browser-types.d.ts.map

package/dist/esm/browser-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-types.d.ts","sourceRoot":"","sources":["../../src/browser-types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAMvC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,eAAe,CAAC,CAAC,SAAS,eAAe,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAExD;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAIlE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAIrE;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAG9C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,GAAG,IAAI,CAsB1D;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,IAAI,OAAO,CAczD;AAMD;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;aACc,aAAa,CAAC,EAAE,KAAK;gBAAxE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAkB,aAAa,CAAC,EAAE,KAAK,YAAA;CAQrF;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,WAAW;gBAC1C,OAAO,EAAE,MAAM;CAO5B;AAED;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,kBAAkB;;CAQjE;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAqCtE;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,wBAAwB,GAAG,IAAI,CAahF;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAOnG;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,eAAe,CAOtG;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,CAQvD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAG9C"}

package/dist/esm/browser-types.js

@@ -0,0 +1,201 @@
+// Browser-specific type definitions and error handling
+// Provides enhanced typing for browser Web Crypto API and environment-specific behavior
+import { CryptoError } from './errors';
+/**
+ * Type guard for Uint32Array
+ */
+export function isUint32Array(value) {
+    var _a;
+    return value !== null &&
+        typeof value === 'object' &&
+        ((_a = value.constructor) === null || _a === void 0 ? void 0 : _a.name) === 'Uint32Array';
+}
+/**
+ * Type guard for any typed array
+ */
+export function isTypedArray(value) {
+    return value !== null &&
+        typeof value === 'object' &&
+        ArrayBuffer.isView(value);
+}
+// ============================================================================
+// Browser Environment Detection
+// ============================================================================
+/**
+ * Detects if the current environment is a browser
+ * @returns true if running in a browser, false otherwise
+ */
+export function isBrowserEnvironment() {
+    return typeof window !== 'undefined' &&
+        typeof window.document !== 'undefined';
+}
+/**
+ * Attempts to access the browser Web Crypto API
+ * @returns BrowserCryptoAPI if available, null otherwise
+ */
+export function getBrowserCrypto() {
+    // Check for window.crypto
+    if (typeof window !== 'undefined' && window.crypto) {
+        const crypto = window.crypto;
+        if (typeof crypto.getRandomValues === 'function' ||
+            typeof crypto.getRandomValues === 'object') {
+            return crypto;
+        }
+    }
+    // Check for global crypto (some environments)
+    if (typeof global !== 'undefined' && global.crypto) {
+        const crypto = global.crypto;
+        if (typeof crypto.getRandomValues === 'function' ||
+            typeof crypto.getRandomValues === 'object') {
+            return crypto;
+        }
+    }
+    return null;
+}
+/**
+ * Checks if browser crypto.getRandomValues is available
+ * @returns true if crypto.getRandomValues is available
+ */
+export function hasBrowserCryptoGetRandomValues() {
+    const crypto = getBrowserCrypto();
+    if (!crypto) {
+        return false;
+    }
+    // Check if Uint32Array is available
+    if (typeof Uint32Array !== 'function' && typeof Uint32Array !== 'object') {
+        return false;
+    }
+    return typeof crypto.getRandomValues === 'function' ||
+        typeof crypto.getRandomValues === 'object';
+}
+// ============================================================================
+// Browser-Specific Error Types
+// ============================================================================
+/**
+ * Error thrown when browser crypto operations fail
+ */
+export class BrowserCryptoError extends CryptoError {
+    constructor(operation, reason, originalError) {
+        super(operation, `Browser crypto error: ${reason}`);
+        this.originalError = originalError;
+        this.name = 'BrowserCryptoError';
+        if (originalError && Error.captureStackTrace) {
+            Error.captureStackTrace(this, BrowserCryptoError);
+        }
+    }
+}
+/**
+ * Error thrown when browser environment is required but not available
+ */
+export class BrowserEnvironmentError extends CryptoError {
+    constructor(feature) {
+        super('environment_check', `Feature '${feature}' requires browser environment but is not available`);
+        this.name = 'BrowserEnvironmentError';
+    }
+}
+/**
+ * Error thrown when Web Crypto API is not supported
+ */
+export class WebCryptoNotSupportedError extends BrowserCryptoError {
+    constructor() {
+        super('getRandomValues', 'Web Crypto API is not supported in this browser');
+        this.name = 'WebCryptoNotSupportedError';
+    }
+}
+// ============================================================================
+// Browser RNG Implementation
+// ============================================================================
+/**
+ * Creates a browser-specific RNG function using crypto.getRandomValues
+ * @param crypto - Browser Web Crypto API
+ * @returns RNG function that generates random binary strings
+ * @throws {BrowserCryptoError} If random value generation fails
+ */
+export function createBrowserRNG(crypto) {
+    return function browserCryptoGetRandomValues(bits) {
+        if (typeof bits !== 'number' || bits <= 0 || bits % 1 !== 0) {
+            throw new BrowserCryptoError('getRandomValues', `Invalid bits parameter: ${bits}. Must be a positive integer.`);
+        }
+        // Calculate number of 32-bit integers needed
+        const elems = Math.ceil(bits / 32);
+        try {
+            // Generate random values
+            const array = new Uint32Array(elems);
+            crypto.getRandomValues(array);
+            // Convert to binary string
+            let binary = '';
+            for (let i = 0; i < array.length; i++) {
+                const value = array[i];
+                const bin = value.toString(2);
+                // Pad to 32 bits
+                binary += '00000000000000000000000000000000'.substring(bin.length) + bin;
+            }
+            // Return exactly the requested number of bits
+            return binary.substring(0, bits);
+        }
+        catch (error) {
+            throw new BrowserCryptoError('getRandomValues', 'Failed to generate random values', error);
+        }
+    };
+}
+/**
+ * Creates a browser crypto environment descriptor
+ * @returns BrowserCryptoEnvironment if browser crypto is available, null otherwise
+ */
+export function createBrowserCryptoEnvironment() {
+    const crypto = getBrowserCrypto();
+    if (!crypto) {
+        return null;
+    }
+    return {
+        type: 'browser',
+        crypto,
+        rngType: 'browserCryptoGetRandomValues',
+        rng: createBrowserRNG(crypto)
+    };
+}
+// ============================================================================
+// Type Validation for Browser
+// ============================================================================
+/**
+ * Validates that a value is a valid Uint32Array
+ * @param value - Value to validate
+ * @param paramName - Parameter name for error messages
+ * @throws {BrowserCryptoError} If value is not a valid Uint32Array
+ */
+export function validateUint32Array(value, paramName) {
+    if (!isUint32Array(value)) {
+        throw new BrowserCryptoError('validation', `Parameter '${paramName}' must be a Uint32Array`);
+    }
+}
+/**
+ * Validates that a value is a valid typed array
+ * @param value - Value to validate
+ * @param paramName - Parameter name for error messages
+ * @throws {BrowserCryptoError} If value is not a valid typed array
+ */
+export function validateTypedArray(value, paramName) {
+    if (!isTypedArray(value)) {
+        throw new BrowserCryptoError('validation', `Parameter '${paramName}' must be a typed array`);
+    }
+}
+/**
+ * Validates that browser crypto is available
+ * @throws {WebCryptoNotSupportedError} If browser crypto is not available
+ */
+export function requireBrowserCrypto() {
+    const crypto = getBrowserCrypto();
+    if (!crypto) {
+        throw new WebCryptoNotSupportedError();
+    }
+    return crypto;
+}
+/**
+ * Checks if the browser supports the Web Crypto API
+ * @returns true if Web Crypto API is fully supported
+ */
+export function isWebCryptoSupported() {
+    return hasBrowserCryptoGetRandomValues() &&
+        (typeof Uint32Array === 'function' || typeof Uint32Array === 'object');
+}
+//# sourceMappingURL=browser-types.js.map

package/dist/esm/browser-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-types.js","sourceRoot":"","sources":["../../src/browser-types.ts"],"names":[],"mappings":"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"}

package/dist/esm/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Base error class for all secrets library errors
+ */
+export declare class SecretsError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Error thrown when invalid parameters are provided to a function
+ */
+export declare class InvalidParameterError extends SecretsError {
+    constructor(parameter: string, value: unknown, expected: string);
+}
+/**
+ * Error thrown when initialization fails
+ */
+export declare class InitializationError extends SecretsError {
+    constructor(reason: string);
+}
+/**
+ * Error thrown when share data is invalid or corrupted
+ */
+export declare class InvalidShareError extends SecretsError {
+    constructor(share: string, reason: string);
+}
+/**
+ * Error thrown when cryptographic operations fail
+ */
+export declare class CryptoError extends SecretsError {
+    constructor(operation: string, reason: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAGnB,IAAI,EAAE,MAAM;aACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAUpD;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM;CAQhE;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,MAAM,EAAE,MAAM;CAQ3B;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ1C;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,YAAY;gBAC/B,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ9C"}

package/dist/esm/errors.js

@@ -0,0 +1,54 @@
+// Type-safe error handling for @digitaldefiance/secrets
+// Provides structured error classes with context information
+/**
+ * Base error class for all secrets library errors
+ */
+export class SecretsError extends Error {
+    constructor(message, code, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'SecretsError';
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SecretsError);
+        }
+    }
+}
+/**
+ * Error thrown when invalid parameters are provided to a function
+ */
+export class InvalidParameterError extends SecretsError {
+    constructor(parameter, value, expected) {
+        super(`Invalid parameter '${parameter}': expected ${expected}, got ${typeof value}`, 'INVALID_PARAMETER', { parameter, value, expected });
+        this.name = 'InvalidParameterError';
+    }
+}
+/**
+ * Error thrown when initialization fails
+ */
+export class InitializationError extends SecretsError {
+    constructor(reason) {
+        super(`Initialization failed: ${reason}`, 'INITIALIZATION_FAILED', { reason });
+        this.name = 'InitializationError';
+    }
+}
+/**
+ * Error thrown when share data is invalid or corrupted
+ */
+export class InvalidShareError extends SecretsError {
+    constructor(share, reason) {
+        super(`Invalid share data: ${reason}`, 'INVALID_SHARE', { share, reason });
+        this.name = 'InvalidShareError';
+    }
+}
+/**
+ * Error thrown when cryptographic operations fail
+ */
+export class CryptoError extends SecretsError {
+    constructor(operation, reason) {
+        super(`Cryptographic operation '${operation}' failed: ${reason}`, 'CRYPTO_ERROR', { operation, reason });
+        this.name = 'CryptoError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,6DAA6D;AAE7D;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YACE,OAAe,EACC,IAAY,EACZ,OAAiC;QAEjD,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAA0B;QAGjD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAE3B,qFAAqF;QACrF,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD,YAAY,SAAiB,EAAE,KAAc,EAAE,QAAgB;QAC7D,KAAK,CACH,sBAAsB,SAAS,eAAe,QAAQ,SAAS,OAAO,KAAK,EAAE,EAC7E,mBAAmB,EACnB,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAC/B,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD,YAAY,MAAc;QACxB,KAAK,CACH,0BAA0B,MAAM,EAAE,EAClC,uBAAuB,EACvB,EAAE,MAAM,EAAE,CACX,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjD,YAAY,KAAa,EAAE,MAAc;QACvC,KAAK,CACH,uBAAuB,MAAM,EAAE,EAC/B,eAAe,EACf,EAAE,KAAK,EAAE,MAAM,EAAE,CAClB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,YAAY;IAC3C,YAAY,SAAiB,EAAE,MAAc;QAC3C,KAAK,CACH,4BAA4B,SAAS,aAAa,MAAM,EAAE,EAC1D,cAAc,EACd,EAAE,SAAS,EAAE,MAAM,EAAE,CACtB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/esm/node-types.d.ts

@@ -0,0 +1,87 @@
+import type { RNGFunction, CSPRNGType } from './types';
+import { CryptoError } from './errors';
+/**
+ * Enhanced Node.js crypto module interface with comprehensive typing
+ */
+export interface NodeCryptoModule {
+    /**
+     * Generates cryptographically strong pseudo-random data
+     * @param size - Number of bytes to generate
+     * @returns Buffer containing random bytes
+     * @throws {Error} If random data generation fails
+     */
+    randomBytes(size: number): Buffer;
+    /**
+     * Synchronous version of randomBytes
+     * @param size - Number of bytes to generate
+     * @returns Buffer containing random bytes
+     * @throws {Error} If random data generation fails
+     */
+    randomBytesSync?(size: number): Buffer;
+}
+/**
+ * Node.js Buffer type guard
+ */
+export declare function isNodeBuffer(value: unknown): value is Buffer;
+/**
+ * Detects if the current environment is Node.js
+ * @returns true if running in Node.js, false otherwise
+ */
+export declare function isNodeEnvironment(): boolean;
+/**
+ * Attempts to load the Node.js crypto module
+ * @returns NodeCryptoModule if available, null otherwise
+ */
+export declare function getNodeCrypto(): NodeCryptoModule | null;
+/**
+ * Checks if Node.js crypto.randomBytes is available
+ * @returns true if crypto.randomBytes is available
+ */
+export declare function hasNodeCryptoRandomBytes(): boolean;
+/**
+ * Error thrown when Node.js crypto operations fail
+ */
+export declare class NodeCryptoError extends CryptoError {
+    readonly originalError?: Error | undefined;
+    constructor(operation: string, reason: string, originalError?: Error | undefined);
+}
+/**
+ * Error thrown when Node.js environment is required but not available
+ */
+export declare class NodeEnvironmentError extends CryptoError {
+    constructor(feature: string);
+}
+/**
+ * Creates a Node.js-specific RNG function using crypto.randomBytes
+ * @param crypto - Node.js crypto module
+ * @returns RNG function that generates random binary strings
+ * @throws {NodeCryptoError} If random byte generation fails
+ */
+export declare function createNodeRNG(crypto: NodeCryptoModule): RNGFunction;
+/**
+ * Node.js-specific crypto environment descriptor
+ */
+export interface NodeCryptoEnvironment {
+    readonly type: 'node';
+    readonly crypto: NodeCryptoModule;
+    readonly rngType: CSPRNGType;
+    readonly rng: RNGFunction;
+}
+/**
+ * Creates a Node.js crypto environment descriptor
+ * @returns NodeCryptoEnvironment if Node.js crypto is available, null otherwise
+ */
+export declare function createNodeCryptoEnvironment(): NodeCryptoEnvironment | null;
+/**
+ * Validates that a value is a valid Node.js Buffer
+ * @param value - Value to validate
+ * @param paramName - Parameter name for error messages
+ * @throws {NodeCryptoError} If value is not a valid Buffer
+ */
+export declare function validateNodeBuffer(value: unknown, paramName: string): asserts value is Buffer;
+/**
+ * Validates that Node.js crypto is available
+ * @throws {NodeEnvironmentError} If Node.js crypto is not available
+ */
+export declare function requireNodeCrypto(): NodeCryptoModule;
+//# sourceMappingURL=node-types.d.ts.map

package/dist/esm/node-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-types.d.ts","sourceRoot":"","sources":["../../src/node-types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAMvC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAElC;;;;;OAKG;IACH,eAAe,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACxC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK5D;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAI3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,GAAG,IAAI,CAiBvD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAGlD;AAMD;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;aACiB,aAAa,CAAC,EAAE,KAAK;gBAAxE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAkB,aAAa,CAAC,EAAE,KAAK,YAAA;CAQrF;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,WAAW;gBACvC,OAAO,EAAE,MAAM;CAO5B;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAwCnE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,qBAAqB,GAAG,IAAI,CAa1E;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAO7F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,gBAAgB,CAQpD"}

package/dist/esm/node-types.js

@@ -0,0 +1,157 @@
+// Node.js-specific type definitions and error handling
+// Provides enhanced typing for Node.js crypto APIs and environment-specific behavior
+import { CryptoError } from './errors';
+/**
+ * Node.js Buffer type guard
+ */
+export function isNodeBuffer(value) {
+    return value !== null &&
+        typeof value === 'object' &&
+        'length' in value &&
+        typeof value.readUInt8 === 'function';
+}
+// ============================================================================
+// Node.js Environment Detection
+// ============================================================================
+/**
+ * Detects if the current environment is Node.js
+ * @returns true if running in Node.js, false otherwise
+ */
+export function isNodeEnvironment() {
+    return typeof process !== 'undefined' &&
+        process.versions != null &&
+        process.versions.node != null;
+}
+/**
+ * Attempts to load the Node.js crypto module
+ * @returns NodeCryptoModule if available, null otherwise
+ */
+export function getNodeCrypto() {
+    if (!isNodeEnvironment()) {
+        return null;
+    }
+    try {
+        // Dynamic require to avoid bundler issues
+        const crypto = require('crypto');
+        if (typeof crypto === 'object' && typeof crypto.randomBytes === 'function') {
+            return crypto;
+        }
+        return null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * Checks if Node.js crypto.randomBytes is available
+ * @returns true if crypto.randomBytes is available
+ */
+export function hasNodeCryptoRandomBytes() {
+    const crypto = getNodeCrypto();
+    return crypto !== null && typeof crypto.randomBytes === 'function';
+}
+// ============================================================================
+// Node.js-Specific Error Types
+// ============================================================================
+/**
+ * Error thrown when Node.js crypto operations fail
+ */
+export class NodeCryptoError extends CryptoError {
+    constructor(operation, reason, originalError) {
+        super(operation, `Node.js crypto error: ${reason}`);
+        this.originalError = originalError;
+        this.name = 'NodeCryptoError';
+        if (originalError && Error.captureStackTrace) {
+            Error.captureStackTrace(this, NodeCryptoError);
+        }
+    }
+}
+/**
+ * Error thrown when Node.js environment is required but not available
+ */
+export class NodeEnvironmentError extends CryptoError {
+    constructor(feature) {
+        super('environment_check', `Feature '${feature}' requires Node.js environment but is not available`);
+        this.name = 'NodeEnvironmentError';
+    }
+}
+// ============================================================================
+// Node.js RNG Implementation
+// ============================================================================
+/**
+ * Creates a Node.js-specific RNG function using crypto.randomBytes
+ * @param crypto - Node.js crypto module
+ * @returns RNG function that generates random binary strings
+ * @throws {NodeCryptoError} If random byte generation fails
+ */
+export function createNodeRNG(crypto) {
+    return function nodeCryptoRandomBytes(bits) {
+        if (typeof bits !== 'number' || bits <= 0 || bits % 1 !== 0) {
+            throw new NodeCryptoError('randomBytes', `Invalid bits parameter: ${bits}. Must be a positive integer.`);
+        }
+        const bytes = Math.ceil(bits / 8);
+        try {
+            const buffer = crypto.randomBytes(bytes);
+            // Convert buffer to hex string
+            let hex = '';
+            for (let i = 0; i < buffer.length; i++) {
+                const byte = buffer[i].toString(16);
+                hex += byte.length === 1 ? '0' + byte : byte;
+            }
+            // Convert hex to binary
+            let binary = '';
+            for (let i = 0; i < hex.length; i++) {
+                const num = parseInt(hex[i], 16);
+                const bin = num.toString(2);
+                binary += '0000'.substring(bin.length) + bin;
+            }
+            // Return exactly the requested number of bits
+            return binary.substring(0, bits);
+        }
+        catch (error) {
+            throw new NodeCryptoError('randomBytes', 'Failed to generate random bytes', error);
+        }
+    };
+}
+/**
+ * Creates a Node.js crypto environment descriptor
+ * @returns NodeCryptoEnvironment if Node.js crypto is available, null otherwise
+ */
+export function createNodeCryptoEnvironment() {
+    const crypto = getNodeCrypto();
+    if (!crypto) {
+        return null;
+    }
+    return {
+        type: 'node',
+        crypto,
+        rngType: 'nodeCryptoRandomBytes',
+        rng: createNodeRNG(crypto)
+    };
+}
+// ============================================================================
+// Type Validation for Node.js
+// ============================================================================
+/**
+ * Validates that a value is a valid Node.js Buffer
+ * @param value - Value to validate
+ * @param paramName - Parameter name for error messages
+ * @throws {NodeCryptoError} If value is not a valid Buffer
+ */
+export function validateNodeBuffer(value, paramName) {
+    if (!isNodeBuffer(value)) {
+        throw new NodeCryptoError('validation', `Parameter '${paramName}' must be a Node.js Buffer`);
+    }
+}
+/**
+ * Validates that Node.js crypto is available
+ * @throws {NodeEnvironmentError} If Node.js crypto is not available
+ */
+export function requireNodeCrypto() {
+    const crypto = getNodeCrypto();
+    if (!crypto) {
+        throw new NodeEnvironmentError('crypto.randomBytes');
+    }
+    return crypto;
+}
+//# sourceMappingURL=node-types.js.map