agentic-qe 1.1.0 → 1.3.0

package/dist/utils/SecureRandom.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Secure Random Utility
+ *
+ * Provides cryptographically secure random number generation.
+ * Replaces insecure SecureRandom.randomFloat() with crypto.randomBytes() and crypto.randomInt().
+ *
+ * Security: Uses Node.js crypto module for CSPRNG (Cryptographically Secure
+ * Pseudo-Random Number Generator)
+ *
+ * @module utils/SecureRandom
+ */
+/**
+ * Secure random number generator
+ *
+ * Security Fixes (Alerts #1-13): Replaces SecureRandom.randomFloat() with crypto module
+ * Previous vulnerability: SecureRandom.randomFloat() is predictable and unsuitable for security
+ * New approach: Uses crypto.randomBytes() and crypto.randomInt() for CSPRNG
+ *
+ * @example
+ * ```typescript
+ * // Generate secure random ID
+ * const id = SecureRandom.generateId(); // "a3f2b91c4d5e6f78..."
+ *
+ * // Generate random integer
+ * const roll = SecureRandom.randomInt(1, 7); // 1-6 (dice roll)
+ *
+ * // Generate random float
+ * const probability = SecureRandom.randomFloat(); // 0.0-1.0
+ *
+ * // Generate UUID
+ * const uuid = SecureRandom.uuid(); // "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+export declare class SecureRandom {
+    /**
+     * Generate cryptographically secure random ID (hex string)
+     *
+     * @param length Byte length (default: 16 bytes = 32 hex characters)
+     * @returns Hex-encoded random string
+     *
+     * @example
+     * ```typescript
+     * const id = SecureRandom.generateId(); // "a3f2b91c4d5e6f7890abcdef12345678"
+     * const shortId = SecureRandom.generateId(8); // "a3f2b91c4d5e6f78"
+     * ```
+     */
+    static generateId(length?: number): string;
+    /**
+     * Generate cryptographically secure random integer
+     *
+     * @param min Minimum value (inclusive)
+     * @param max Maximum value (exclusive)
+     * @returns Random integer in range [min, max)
+     *
+     * @example
+     * ```typescript
+     * const diceRoll = SecureRandom.randomInt(1, 7); // 1-6
+     * const randomPercent = SecureRandom.randomInt(0, 101); // 0-100
+     * ```
+     */
+    static randomInt(min: number, max: number): number;
+    /**
+     * Generate cryptographically secure random float between 0 and 1
+     *
+     * @param precision Decimal precision (default: 6)
+     * @returns Random float in range [0.0, 1.0)
+     *
+     * @example
+     * ```typescript
+     * const probability = SecureRandom.randomFloat(); // 0.543210
+     * const highPrecision = SecureRandom.randomFloat(10); // 0.5432109876
+     * ```
+     */
+    static randomFloat(precision?: number): number;
+    /**
+     * Generate RFC4122 v4 UUID
+     *
+     * @returns UUID string
+     *
+     * @example
+     * ```typescript
+     * const id = SecureRandom.uuid(); // "550e8400-e29b-41d4-a716-446655440000"
+     * ```
+     */
+    static uuid(): string;
+    /**
+     * Generate random string with custom alphabet
+     *
+     * @param length String length
+     * @param alphabet Character set (default: alphanumeric)
+     * @returns Random string
+     *
+     * @example
+     * ```typescript
+     * // Alphanumeric
+     * const code = SecureRandom.randomString(8); // "a3F2b91C"
+     *
+     * // Custom alphabet
+     * const hexCode = SecureRandom.randomString(8, '0123456789ABCDEF'); // "A3F2B91C"
+     * const pin = SecureRandom.randomString(4, '0123456789'); // "5432"
+     * ```
+     */
+    static randomString(length: number, alphabet?: string): string;
+    /**
+     * Generate random boolean with optional bias
+     *
+     * @param trueProbability Probability of true (0.0-1.0, default: 0.5)
+     * @returns Random boolean
+     *
+     * @example
+     * ```typescript
+     * const coinFlip = SecureRandom.randomBoolean(); // 50/50
+     * const biasedCoin = SecureRandom.randomBoolean(0.7); // 70% true, 30% false
+     * ```
+     */
+    static randomBoolean(trueProbability?: number): boolean;
+    /**
+     * Shuffle array using Fisher-Yates algorithm with secure randomness
+     *
+     * @param array Array to shuffle (in-place)
+     * @returns Shuffled array
+     *
+     * @example
+     * ```typescript
+     * const deck = [1, 2, 3, 4, 5];
+     * SecureRandom.shuffle(deck); // [3, 1, 5, 2, 4]
+     * ```
+     */
+    static shuffle<T>(array: T[]): T[];
+    /**
+     * Select random element from array
+     *
+     * @param array Array to select from
+     * @returns Random element
+     *
+     * @example
+     * ```typescript
+     * const colors = ['red', 'green', 'blue'];
+     * const color = SecureRandom.choice(colors); // "green"
+     * ```
+     */
+    static choice<T>(array: T[]): T;
+    /**
+     * Select multiple random elements from array (without replacement)
+     *
+     * @param array Array to select from
+     * @param count Number of elements to select
+     * @returns Array of random elements
+     *
+     * @example
+     * ```typescript
+     * const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+     * const lottery = SecureRandom.sample(numbers, 3); // [7, 2, 9]
+     * ```
+     */
+    static sample<T>(array: T[], count: number): T[];
+    /**
+     * Generate random bytes as Buffer
+     *
+     * @param size Number of bytes
+     * @returns Buffer containing random bytes
+     *
+     * @example
+     * ```typescript
+     * const key = SecureRandom.bytes(32); // 256-bit key
+     * const iv = SecureRandom.bytes(16); // 128-bit IV
+     * ```
+     */
+    static bytes(size: number): Buffer;
+}
+//# sourceMappingURL=SecureRandom.d.ts.map

package/dist/utils/SecureRandom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureRandom.d.ts","sourceRoot":"","sources":["../../src/utils/SecureRandom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,GAAE,MAAW,GAAG,MAAM;IAI9C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAOlD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,WAAW,CAAC,SAAS,GAAE,MAAU,GAAG,MAAM;IAMjD;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,IAAI,MAAM;IAIrB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,YAAY,CACjB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAyE,GAClF,MAAM;IAWT;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,aAAa,CAAC,eAAe,GAAE,MAAY,GAAG,OAAO;IAO5D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE;IAQlC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC;IAO/B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE;IAoBhD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAGnC"}

package/dist/utils/SecureRandom.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * Secure Random Utility
+ *
+ * Provides cryptographically secure random number generation.
+ * Replaces insecure SecureRandom.randomFloat() with crypto.randomBytes() and crypto.randomInt().
+ *
+ * Security: Uses Node.js crypto module for CSPRNG (Cryptographically Secure
+ * Pseudo-Random Number Generator)
+ *
+ * @module utils/SecureRandom
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecureRandom = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Secure random number generator
+ *
+ * Security Fixes (Alerts #1-13): Replaces SecureRandom.randomFloat() with crypto module
+ * Previous vulnerability: SecureRandom.randomFloat() is predictable and unsuitable for security
+ * New approach: Uses crypto.randomBytes() and crypto.randomInt() for CSPRNG
+ *
+ * @example
+ * ```typescript
+ * // Generate secure random ID
+ * const id = SecureRandom.generateId(); // "a3f2b91c4d5e6f78..."
+ *
+ * // Generate random integer
+ * const roll = SecureRandom.randomInt(1, 7); // 1-6 (dice roll)
+ *
+ * // Generate random float
+ * const probability = SecureRandom.randomFloat(); // 0.0-1.0
+ *
+ * // Generate UUID
+ * const uuid = SecureRandom.uuid(); // "550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+class SecureRandom {
+    /**
+     * Generate cryptographically secure random ID (hex string)
+     *
+     * @param length Byte length (default: 16 bytes = 32 hex characters)
+     * @returns Hex-encoded random string
+     *
+     * @example
+     * ```typescript
+     * const id = SecureRandom.generateId(); // "a3f2b91c4d5e6f7890abcdef12345678"
+     * const shortId = SecureRandom.generateId(8); // "a3f2b91c4d5e6f78"
+     * ```
+     */
+    static generateId(length = 16) {
+        return (0, crypto_1.randomBytes)(length).toString('hex');
+    }
+    /**
+     * Generate cryptographically secure random integer
+     *
+     * @param min Minimum value (inclusive)
+     * @param max Maximum value (exclusive)
+     * @returns Random integer in range [min, max)
+     *
+     * @example
+     * ```typescript
+     * const diceRoll = SecureRandom.randomInt(1, 7); // 1-6
+     * const randomPercent = SecureRandom.randomInt(0, 101); // 0-100
+     * ```
+     */
+    static randomInt(min, max) {
+        if (min >= max) {
+            throw new Error(`Invalid range: min (${min}) must be less than max (${max})`);
+        }
+        return (0, crypto_1.randomInt)(min, max);
+    }
+    /**
+     * Generate cryptographically secure random float between 0 and 1
+     *
+     * @param precision Decimal precision (default: 6)
+     * @returns Random float in range [0.0, 1.0)
+     *
+     * @example
+     * ```typescript
+     * const probability = SecureRandom.randomFloat(); // 0.543210
+     * const highPrecision = SecureRandom.randomFloat(10); // 0.5432109876
+     * ```
+     */
+    static randomFloat(precision = 6) {
+        const max = Math.pow(10, precision);
+        const randomValue = (0, crypto_1.randomInt)(0, max);
+        return randomValue / max;
+    }
+    /**
+     * Generate RFC4122 v4 UUID
+     *
+     * @returns UUID string
+     *
+     * @example
+     * ```typescript
+     * const id = SecureRandom.uuid(); // "550e8400-e29b-41d4-a716-446655440000"
+     * ```
+     */
+    static uuid() {
+        return (0, crypto_1.randomUUID)();
+    }
+    /**
+     * Generate random string with custom alphabet
+     *
+     * @param length String length
+     * @param alphabet Character set (default: alphanumeric)
+     * @returns Random string
+     *
+     * @example
+     * ```typescript
+     * // Alphanumeric
+     * const code = SecureRandom.randomString(8); // "a3F2b91C"
+     *
+     * // Custom alphabet
+     * const hexCode = SecureRandom.randomString(8, '0123456789ABCDEF'); // "A3F2B91C"
+     * const pin = SecureRandom.randomString(4, '0123456789'); // "5432"
+     * ```
+     */
+    static randomString(length, alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789') {
+        const bytes = (0, crypto_1.randomBytes)(length);
+        let result = '';
+        for (let i = 0; i < length; i++) {
+            result += alphabet[bytes[i] % alphabet.length];
+        }
+        return result;
+    }
+    /**
+     * Generate random boolean with optional bias
+     *
+     * @param trueProbability Probability of true (0.0-1.0, default: 0.5)
+     * @returns Random boolean
+     *
+     * @example
+     * ```typescript
+     * const coinFlip = SecureRandom.randomBoolean(); // 50/50
+     * const biasedCoin = SecureRandom.randomBoolean(0.7); // 70% true, 30% false
+     * ```
+     */
+    static randomBoolean(trueProbability = 0.5) {
+        if (trueProbability < 0 || trueProbability > 1) {
+            throw new Error('Probability must be between 0 and 1');
+        }
+        return this.randomFloat() < trueProbability;
+    }
+    /**
+     * Shuffle array using Fisher-Yates algorithm with secure randomness
+     *
+     * @param array Array to shuffle (in-place)
+     * @returns Shuffled array
+     *
+     * @example
+     * ```typescript
+     * const deck = [1, 2, 3, 4, 5];
+     * SecureRandom.shuffle(deck); // [3, 1, 5, 2, 4]
+     * ```
+     */
+    static shuffle(array) {
+        for (let i = array.length - 1; i > 0; i--) {
+            const j = this.randomInt(0, i + 1);
+            [array[i], array[j]] = [array[j], array[i]];
+        }
+        return array;
+    }
+    /**
+     * Select random element from array
+     *
+     * @param array Array to select from
+     * @returns Random element
+     *
+     * @example
+     * ```typescript
+     * const colors = ['red', 'green', 'blue'];
+     * const color = SecureRandom.choice(colors); // "green"
+     * ```
+     */
+    static choice(array) {
+        if (array.length === 0) {
+            throw new Error('Cannot choose from empty array');
+        }
+        return array[this.randomInt(0, array.length)];
+    }
+    /**
+     * Select multiple random elements from array (without replacement)
+     *
+     * @param array Array to select from
+     * @param count Number of elements to select
+     * @returns Array of random elements
+     *
+     * @example
+     * ```typescript
+     * const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+     * const lottery = SecureRandom.sample(numbers, 3); // [7, 2, 9]
+     * ```
+     */
+    static sample(array, count) {
+        if (count > array.length) {
+            throw new Error('Sample size cannot exceed array length');
+        }
+        if (count < 0) {
+            throw new Error('Sample size must be non-negative');
+        }
+        const copy = [...array];
+        const result = [];
+        for (let i = 0; i < count; i++) {
+            const index = this.randomInt(0, copy.length);
+            result.push(copy[index]);
+            copy.splice(index, 1);
+        }
+        return result;
+    }
+    /**
+     * Generate random bytes as Buffer
+     *
+     * @param size Number of bytes
+     * @returns Buffer containing random bytes
+     *
+     * @example
+     * ```typescript
+     * const key = SecureRandom.bytes(32); // 256-bit key
+     * const iv = SecureRandom.bytes(16); // 128-bit IV
+     * ```
+     */
+    static bytes(size) {
+        return (0, crypto_1.randomBytes)(size);
+    }
+}
+exports.SecureRandom = SecureRandom;
+//# sourceMappingURL=SecureRandom.js.map

package/dist/utils/SecureRandom.js.map

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

package/dist/utils/SecureUrlValidator.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Secure URL Validator - Native TypeScript Implementation
+ *
+ * A secure, zero-dependency URL validation utility using the WHATWG URL API
+ * to replace validator.js isURL() and avoid CVE-2025-56200.
+ *
+ * @module SecureUrlValidator
+ * @see CVE-2025-56200 - validator.js URL validation bypass vulnerability
+ */
+export interface UrlValidationOptions {
+    /**
+     * Allowed URL protocols (e.g., ['http:', 'https:'])
+     * Default: ['http:', 'https:']
+     */
+    allowedProtocols?: string[];
+    /**
+     * Whether to allow URLs with authentication (username:password@host)
+     * Default: false (for security)
+     */
+    allowAuthentication?: boolean;
+    /**
+     * Whether to require a valid TLD (top-level domain)
+     * Default: true
+     */
+    requireTld?: boolean;
+    /**
+     * Whether to allow localhost URLs
+     * Default: false (for production safety)
+     */
+    allowLocalhost?: boolean;
+    /**
+     * Whether to allow IP addresses (IPv4/IPv6)
+     * Default: true
+     */
+    allowIpAddress?: boolean;
+    /**
+     * Maximum URL length
+     * Default: 2048 (browser limit)
+     */
+    maxLength?: number;
+    /**
+     * Custom domain allowlist (if provided, only these domains are allowed)
+     */
+    allowedDomains?: string[];
+    /**
+     * Custom domain blocklist (if provided, these domains are rejected)
+     */
+    blockedDomains?: string[];
+}
+export interface UrlValidationResult {
+    /**
+     * Whether the URL is valid
+     */
+    valid: boolean;
+    /**
+     * Error message if invalid
+     */
+    error?: string;
+    /**
+     * Parsed URL object if valid
+     */
+    url?: URL;
+    /**
+     * Security warnings (non-fatal)
+     */
+    warnings?: string[];
+}
+/**
+ * Validates a URL string using the WHATWG URL API
+ *
+ * This is the secure replacement for validator.js isURL() function.
+ * It uses the native URL constructor which properly handles all edge cases
+ * and prevents the CVE-2025-56200 vulnerability.
+ *
+ * @param urlString - The URL string to validate
+ * @param options - Validation options
+ * @returns Validation result with details
+ *
+ * @example
+ * ```typescript
+ * // Basic validation
+ * const result = validateUrl('https://example.com');
+ * if (result.valid) {
+ *   console.log('Valid URL:', result.url?.href);
+ * }
+ *
+ * // Strict validation for user input
+ * const strictResult = validateUrl(userInput, {
+ *   allowedProtocols: ['https:'],
+ *   requireTld: true,
+ *   allowLocalhost: false,
+ *   allowAuthentication: false,
+ * });
+ *
+ * // Custom domain allowlist
+ * const allowlistResult = validateUrl(url, {
+ *   allowedDomains: ['example.com', 'trusted-site.org'],
+ * });
+ * ```
+ */
+export declare function validateUrl(urlString: string, options?: UrlValidationOptions): UrlValidationResult;
+/**
+ * Simple boolean validation (for drop-in replacement of validator.isURL)
+ *
+ * @param urlString - The URL string to validate
+ * @param options - Validation options
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isValidUrl('https://example.com')) {
+ *   // URL is valid
+ * }
+ * ```
+ */
+export declare function isValidUrl(urlString: string, options?: UrlValidationOptions): boolean;
+/**
+ * Sanitize URL by parsing and reconstructing it
+ * This ensures the URL is properly formatted and safe
+ *
+ * @param urlString - The URL string to sanitize
+ * @param options - Validation options
+ * @returns Sanitized URL string or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const clean = sanitizeUrl('HTTP://EXAMPLE.COM/path');
+ * // Returns: 'http://example.com/path'
+ * ```
+ */
+export declare function sanitizeUrl(urlString: string, options?: UrlValidationOptions): string | null;
+/**
+ * Extract and validate hostname from URL
+ *
+ * @param urlString - The URL string
+ * @returns Hostname or null if invalid
+ */
+export declare function extractHostname(urlString: string): string | null;
+/**
+ * Check if URL is HTTPS
+ *
+ * @param urlString - The URL string
+ * @returns true if HTTPS, false otherwise
+ */
+export declare function isHttps(urlString: string): boolean;
+/**
+ * Preset validation configurations for common use cases
+ */
+export declare const UrlValidationPresets: {
+    /**
+     * Strict validation for production user input
+     */
+    STRICT: UrlValidationOptions;
+    /**
+     * Standard web URLs (HTTP/HTTPS)
+     */
+    WEB: UrlValidationOptions;
+    /**
+     * Development mode (allows localhost)
+     */
+    DEVELOPMENT: UrlValidationOptions;
+    /**
+     * API endpoints (allows authentication)
+     */
+    API: UrlValidationOptions;
+};
+//# sourceMappingURL=SecureUrlValidator.d.ts.map

package/dist/utils/SecureUrlValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureUrlValidator.d.ts","sourceRoot":"","sources":["../../src/utils/SecureUrlValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE5B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IAEV;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CAwIrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAET;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,oBAAyB,GACjC,MAAM,GAAG,IAAI,CAGf;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;OAEG;YAOE,oBAAoB;IAEzB;;OAEG;SAOE,oBAAoB;IAEzB;;OAEG;iBAOE,oBAAoB;IAEzB;;OAEG;SAOE,oBAAoB;CAC1B,CAAC"}