@vorionsys/platform-core 0.1.0

package/dist/common/secret-generator.js

@@ -0,0 +1,286 @@
+/**
+ * Secret Generator for Vorion
+ *
+ * Provides secure secret generation and management for deployment.
+ * Generates cryptographically secure secrets for JWT, encryption, CSRF, etc.
+ *
+ * @packageDocumentation
+ */
+import { randomBytes, createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import { join } from 'path';
+/**
+ * Minimum entropy threshold in bits for production secrets
+ */
+const MIN_ENTROPY_BITS = 128;
+/**
+ * Current secret format version
+ */
+const SECRET_FORMAT_VERSION = 1;
+/**
+ * Calculate Shannon entropy of a string in bits.
+ *
+ * Used to validate secret quality and detect weak secrets.
+ * A good cryptographic secret should have high entropy (close to the
+ * theoretical maximum based on character set and length).
+ *
+ * @param str - The string to analyze
+ * @returns Entropy in bits
+ */
+export function calculateEntropy(str) {
+    if (!str || str.length === 0)
+        return 0;
+    // Count character frequencies
+    const freq = new Map();
+    for (const char of str) {
+        freq.set(char, (freq.get(char) ?? 0) + 1);
+    }
+    // Calculate Shannon entropy
+    let entropy = 0;
+    for (const count of freq.values()) {
+        const p = count / str.length;
+        entropy -= p * Math.log2(p);
+    }
+    // Return total entropy (entropy per character * length)
+    return entropy * str.length;
+}
+/**
+ * Generate a cryptographically secure random secret.
+ *
+ * Uses Node.js crypto.randomBytes which is backed by the OS CSPRNG.
+ *
+ * @param bytes - Number of random bytes to generate (default: 64)
+ * @returns Base64-encoded secret string
+ */
+export function generateSecret(bytes = 64) {
+    return randomBytes(bytes).toString('base64');
+}
+/**
+ * Generate a cryptographically secure secret with entropy validation.
+ *
+ * Throws an error if the generated secret doesn't meet minimum entropy
+ * requirements (which should never happen with a working CSPRNG).
+ *
+ * @param bytes - Number of random bytes to generate
+ * @param minEntropy - Minimum required entropy in bits (default: 128)
+ * @returns Base64-encoded secret string
+ * @throws Error if generated secret has insufficient entropy
+ */
+export function generateSecretWithValidation(bytes = 64, minEntropy = MIN_ENTROPY_BITS) {
+    const secret = generateSecret(bytes);
+    const entropy = calculateEntropy(secret);
+    if (entropy < minEntropy) {
+        // This should never happen with a working CSPRNG
+        throw new Error(`Generated secret has insufficient entropy (${Math.floor(entropy)} bits, need ${minEntropy}+). ` +
+            'This may indicate a problem with the system random number generator.');
+    }
+    return secret;
+}
+/**
+ * Generate all required secrets for Vorion deployment.
+ *
+ * Generates:
+ * - jwtSecret: 64 bytes for JWT signing (512 bits)
+ * - encryptionKey: 32 bytes for AES-256-GCM (256 bits)
+ * - encryptionSalt: 16 bytes for PBKDF2 (128 bits)
+ * - dedupeSecret: 32 bytes for HMAC (256 bits)
+ * - csrfSecret: 32 bytes for CSRF tokens (256 bits)
+ *
+ * @returns Generated secrets object
+ */
+export function generateSecrets() {
+    return {
+        jwtSecret: generateSecretWithValidation(64),
+        encryptionKey: generateSecretWithValidation(32),
+        // Use 24 bytes for salt to ensure Shannon entropy meets 128-bit threshold
+        // when base64-encoded (16 bytes can occasionally produce lower Shannon entropy
+        // due to character distribution even though raw entropy is 128 bits)
+        encryptionSalt: generateSecretWithValidation(24),
+        dedupeSecret: generateSecretWithValidation(32),
+        csrfSecret: generateSecretWithValidation(32),
+        generatedAt: new Date().toISOString(),
+        version: SECRET_FORMAT_VERSION,
+    };
+}
+/**
+ * Generate a deterministic key fingerprint for secret identification.
+ *
+ * Creates a short hash that can be used to identify which secrets are
+ * in use without exposing the actual secret values.
+ *
+ * @param secret - The secret to fingerprint
+ * @returns First 8 characters of SHA-256 hash
+ */
+export function getSecretFingerprint(secret) {
+    return createHash('sha256').update(secret).digest('hex').slice(0, 8);
+}
+/**
+ * Load existing secrets from file or generate new ones.
+ *
+ * If secrets file exists and is valid, loads and returns existing secrets.
+ * Otherwise, generates new secrets and saves them with restricted permissions.
+ *
+ * The secrets file is created with mode 0o600 (owner read/write only).
+ *
+ * @param dataDir - Directory to store/load secrets from
+ * @returns Loaded or generated secrets
+ */
+export async function loadOrGenerateSecrets(dataDir) {
+    const secretsPath = join(dataDir, '.vorion-secrets.json');
+    try {
+        const content = await fs.readFile(secretsPath, 'utf-8');
+        const secrets = JSON.parse(content);
+        // Validate loaded secrets have all required fields
+        const requiredFields = [
+            'jwtSecret',
+            'encryptionKey',
+            'encryptionSalt',
+            'dedupeSecret',
+            'csrfSecret',
+        ];
+        for (const field of requiredFields) {
+            if (!secrets[field] || typeof secrets[field] !== 'string') {
+                throw new Error(`Missing or invalid field: ${field}`);
+            }
+        }
+        // Validate entropy of loaded secrets
+        const minLengths = {
+            jwtSecret: 32,
+            encryptionKey: 32,
+            encryptionSalt: 16,
+            dedupeSecret: 32,
+            csrfSecret: 32,
+        };
+        for (const [field, minLength] of Object.entries(minLengths)) {
+            const secret = secrets[field];
+            if (secret.length < minLength) {
+                throw new Error(`Secret ${field} is too short (${secret.length} < ${minLength})`);
+            }
+        }
+        return secrets;
+    }
+    catch (error) {
+        // File doesn't exist or is invalid - generate new secrets
+        const secrets = generateSecrets();
+        // Ensure directory exists
+        await fs.mkdir(dataDir, { recursive: true });
+        // Write with restricted permissions (owner read/write only)
+        await fs.writeFile(secretsPath, JSON.stringify(secrets, null, 2), {
+            mode: 0o600,
+        });
+        return secrets;
+    }
+}
+/**
+ * Apply generated secrets to environment variables.
+ *
+ * Sets the appropriate VORION_* environment variables from the secrets.
+ * Does not override variables that are already set.
+ *
+ * @param secrets - The secrets to apply
+ * @param override - Whether to override existing env vars (default: false)
+ */
+export function applySecretsToEnv(secrets, override = false) {
+    const envMappings = [
+        ['jwtSecret', 'VORION_JWT_SECRET'],
+        ['encryptionKey', 'VORION_ENCRYPTION_KEY'],
+        ['encryptionSalt', 'VORION_ENCRYPTION_SALT'],
+        ['dedupeSecret', 'VORION_DEDUPE_SECRET'],
+        ['csrfSecret', 'VORION_CSRF_SECRET'],
+    ];
+    for (const [secretKey, envVar] of envMappings) {
+        const value = secrets[secretKey];
+        if (typeof value === 'string' && (override || !process.env[envVar])) {
+            process.env[envVar] = value;
+        }
+    }
+}
+/**
+ * Generate environment file content from secrets.
+ *
+ * Creates a .env file format string that can be written to disk
+ * or used with docker-compose.
+ *
+ * @param secrets - The secrets to format
+ * @returns Environment file content
+ */
+export function generateEnvFileContent(secrets) {
+    const lines = [
+        '# Vorion Auto-Generated Secrets',
+        `# Generated: ${secrets.generatedAt}`,
+        `# Version: ${secrets.version}`,
+        '',
+        '# JWT signing secret (do not share)',
+        `VORION_JWT_SECRET=${secrets.jwtSecret}`,
+        '',
+        '# Encryption key for data at rest',
+        `VORION_ENCRYPTION_KEY=${secrets.encryptionKey}`,
+        '',
+        '# PBKDF2 salt for key derivation',
+        `VORION_ENCRYPTION_SALT=${secrets.encryptionSalt}`,
+        '',
+        '# HMAC secret for deduplication',
+        `VORION_DEDUPE_SECRET=${secrets.dedupeSecret}`,
+        '',
+        '# HMAC secret for CSRF tokens',
+        `VORION_CSRF_SECRET=${secrets.csrfSecret}`,
+        '',
+    ];
+    return lines.join('\n');
+}
+/**
+ * Rotate secrets by generating new ones.
+ *
+ * Generates a completely new set of secrets. The caller is responsible
+ * for handling the transition (e.g., supporting both old and new secrets
+ * during a migration period).
+ *
+ * @returns New generated secrets
+ */
+export function rotateSecrets() {
+    return generateSecrets();
+}
+/**
+ * Validate that a secret meets minimum security requirements.
+ *
+ * Checks:
+ * - Minimum length
+ * - Minimum entropy
+ * - Not a known weak pattern
+ *
+ * @param secret - The secret to validate
+ * @param name - Name of the secret (for error messages)
+ * @param minLength - Minimum required length (default: 32)
+ * @returns Validation result
+ */
+export function validateSecret(secret, name, minLength = 32) {
+    if (!secret) {
+        return { valid: false, error: `${name} is required` };
+    }
+    if (secret.length < minLength) {
+        return {
+            valid: false,
+            error: `${name} must be at least ${minLength} characters (got ${secret.length})`,
+        };
+    }
+    const entropy = calculateEntropy(secret);
+    if (entropy < MIN_ENTROPY_BITS) {
+        return {
+            valid: false,
+            error: `${name} has insufficient entropy (${Math.floor(entropy)} bits, need ${MIN_ENTROPY_BITS}+)`,
+        };
+    }
+    // Check for obviously weak patterns
+    const weakPatterns = [
+        /^(.)\1+$/, // All same character
+        /^(012345|123456|abcdef|qwerty)/i, // Sequential patterns
+        /^(password|secret|key|token)/i, // Common weak prefixes
+    ];
+    for (const pattern of weakPatterns) {
+        if (pattern.test(secret)) {
+            return { valid: false, error: `${name} matches a weak pattern` };
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=secret-generator.js.map

package/dist/common/secret-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-generator.js","sourceRoot":"","sources":["../../src/common/secret-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAsB5B;;GAEG;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B;;GAEG;AACH,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEvC,8BAA8B;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,4BAA4B;IAC5B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC;QAC7B,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED,wDAAwD;IACxD,OAAO,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE;IAC/C,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAgB,EAAE,EAClB,aAAqB,gBAAgB;IAErC,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEzC,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;QACzB,iDAAiD;QACjD,MAAM,IAAI,KAAK,CACb,8CAA8C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,UAAU,MAAM;YAChG,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,SAAS,EAAE,4BAA4B,CAAC,EAAE,CAAC;QAC3C,aAAa,EAAE,4BAA4B,CAAC,EAAE,CAAC;QAC/C,0EAA0E;QAC1E,+EAA+E;QAC/E,qEAAqE;QACrE,cAAc,EAAE,4BAA4B,CAAC,EAAE,CAAC;QAChD,YAAY,EAAE,4BAA4B,CAAC,EAAE,CAAC;QAC9C,UAAU,EAAE,4BAA4B,CAAC,EAAE,CAAC;QAC5C,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,OAAO,EAAE,qBAAqB;KAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAe;IACzD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC;IAE1D,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAqB,CAAC;QAExD,mDAAmD;QACnD,MAAM,cAAc,GAA+B;YACjD,WAAW;YACX,eAAe;YACf,gBAAgB;YAChB,cAAc;YACd,YAAY;SACb,CAAC;QAEF,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1D,MAAM,IAAI,KAAK,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAED,qCAAqC;QACrC,MAAM,UAAU,GAA2B;YACzC,SAAS,EAAE,EAAE;YACb,aAAa,EAAE,EAAE;YACjB,cAAc,EAAE,EAAE;YAClB,YAAY,EAAE,EAAE;YAChB,UAAU,EAAE,EAAE;SACf,CAAC;QAEF,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,KAA+B,CAAW,CAAC;YAClE,IAAI,MAAM,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,kBAAkB,MAAM,CAAC,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC;YACpF,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0DAA0D;QAC1D,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC;QAElC,0BAA0B;QAC1B,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE7C,4DAA4D;QAC5D,MAAM,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;YAChE,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAyB,EAAE,WAAoB,KAAK;IACpF,MAAM,WAAW,GAA4C;QAC3D,CAAC,WAAW,EAAE,mBAAmB,CAAC;QAClC,CAAC,eAAe,EAAE,uBAAuB,CAAC;QAC1C,CAAC,gBAAgB,EAAE,wBAAwB,CAAC;QAC5C,CAAC,cAAc,EAAE,sBAAsB,CAAC;QACxC,CAAC,YAAY,EAAE,oBAAoB,CAAC;KACrC,CAAC;IAEF,KAAK,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;YACpE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;QAC9B,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAyB;IAC9D,MAAM,KAAK,GAAG;QACZ,iCAAiC;QACjC,gBAAgB,OAAO,CAAC,WAAW,EAAE;QACrC,cAAc,OAAO,CAAC,OAAO,EAAE;QAC/B,EAAE;QACF,qCAAqC;QACrC,qBAAqB,OAAO,CAAC,SAAS,EAAE;QACxC,EAAE;QACF,mCAAmC;QACnC,yBAAyB,OAAO,CAAC,aAAa,EAAE;QAChD,EAAE;QACF,kCAAkC;QAClC,0BAA0B,OAAO,CAAC,cAAc,EAAE;QAClD,EAAE;QACF,iCAAiC;QACjC,wBAAwB,OAAO,CAAC,YAAY,EAAE;QAC9C,EAAE;QACF,+BAA+B;QAC/B,sBAAsB,OAAO,CAAC,UAAU,EAAE;QAC1C,EAAE;KACH,CAAC;IAEF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,eAAe,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,IAAY,EACZ,YAAoB,EAAE;IAEtB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,cAAc,EAAE,CAAC;IACxD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC9B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,GAAG,IAAI,qBAAqB,SAAS,oBAAoB,MAAM,CAAC,MAAM,GAAG;SACjF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,OAAO,GAAG,gBAAgB,EAAE,CAAC;QAC/B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,GAAG,IAAI,8BAA8B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,gBAAgB,IAAI;SACnG,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,MAAM,YAAY,GAAG;QACnB,UAAU,EAAE,qBAAqB;QACjC,iCAAiC,EAAE,sBAAsB;QACzD,+BAA+B,EAAE,uBAAuB;KACzD,CAAC;IAEF,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,yBAAyB,EAAE,CAAC;QACnE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/common/secure-fetch.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Secure HTTP Client Wrapper
+ *
+ * Provides SSRF (Server-Side Request Forgery) protection for all external HTTP requests.
+ * This module should be used instead of direct fetch() calls when making requests to
+ * user-provided or configurable URLs.
+ *
+ * Security features:
+ * - URL scheme validation (HTTPS only in production)
+ * - Private IP range blocking (RFC 1918, RFC 5737, RFC 6598)
+ * - Link-local address blocking (169.254.x.x)
+ * - Localhost and internal DNS pattern blocking
+ * - URL allowlist for known external services
+ * - Request timeout limits
+ * - DNS resolution validation at request time
+ * - Comprehensive audit logging
+ */
+export interface SecureFetchConfig {
+    /**
+     * Allow HTTP in addition to HTTPS.
+     * Should only be true in development environments.
+     * Default: false (HTTPS only)
+     */
+    allowHttp?: boolean;
+    /**
+     * Request timeout in milliseconds.
+     * Default: 10000 (10 seconds)
+     */
+    timeoutMs?: number;
+    /**
+     * List of allowed domains for this request.
+     * If provided, only these domains are allowed.
+     * If empty/undefined, allowlist is not enforced.
+     */
+    allowedDomains?: string[];
+    /**
+     * Additional blocked domains (beyond the default internal patterns).
+     */
+    blockedDomains?: string[];
+    /**
+     * Skip DNS resolution check (use with caution).
+     * Only set this if you've already validated the URL.
+     * Default: false
+     */
+    skipDnsCheck?: boolean;
+    /**
+     * Expected resolved IP from prior validation (DNS pinning).
+     * If provided, the request will fail if DNS resolves to a different IP.
+     */
+    pinnedIp?: string;
+    /**
+     * Custom headers to include in the request.
+     */
+    headers?: Record<string, string>;
+}
+export interface UrlValidationResult {
+    valid: boolean;
+    reason?: string;
+    resolvedIp?: string;
+}
+export interface SecureFetchResponse {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Headers;
+    text: () => Promise<string>;
+    json: <T = unknown>() => Promise<T>;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+}
+/**
+ * Check if an IP address is in a private/internal range.
+ *
+ * @param ip - The IP address to check (IPv4 or IPv6)
+ * @returns true if the IP is private/internal, false otherwise
+ */
+export declare function isPrivateIP(ip: string): boolean;
+/**
+ * Check if a hostname matches internal/private patterns.
+ *
+ * @param hostname - The hostname to check
+ * @returns true if the hostname is internal, false otherwise
+ */
+export declare function isInternalHostname(hostname: string): boolean;
+/**
+ * Validate a URL for external requests.
+ *
+ * Performs comprehensive validation including:
+ * - URL scheme (HTTPS required in production)
+ * - Hostname blocking (localhost, internal patterns)
+ * - IP address validation (private ranges)
+ * - Port blocking (internal service ports)
+ * - Domain allowlist (if configured)
+ *
+ * @param url - The URL to validate
+ * @param options - Validation options
+ * @returns Validation result with reason if invalid
+ */
+export declare function validateExternalUrl(url: string, options?: {
+    allowHttp?: boolean;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+}): UrlValidationResult;
+/**
+ * Validate URL at runtime with DNS resolution.
+ *
+ * This performs actual DNS resolution to detect:
+ * - DNS rebinding attacks (hostname resolves to private IP)
+ * - DNS resolution failures
+ * - IP pinning violations (if pinnedIp is provided)
+ *
+ * @param url - The URL to validate
+ * @param options - Validation options including optional pinned IP
+ * @returns Validation result with resolved IP
+ */
+export declare function validateUrlWithDns(url: string, options?: {
+    allowHttp?: boolean;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    pinnedIp?: string;
+}): Promise<UrlValidationResult>;
+/**
+ * Make a secure HTTP request with SSRF protection.
+ *
+ * This function should be used instead of direct fetch() calls when making
+ * requests to user-provided or configurable URLs.
+ *
+ * Features:
+ * - URL scheme validation (HTTPS required in production)
+ * - Private IP blocking (RFC 1918, RFC 5737, RFC 6598)
+ * - Internal hostname blocking
+ * - DNS resolution validation
+ * - DNS pinning support
+ * - Request timeout
+ * - Comprehensive audit logging
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options and security configuration
+ * @returns Response object
+ * @throws Error if URL validation fails or request times out
+ */
+export declare function secureFetch(url: string, options?: RequestInit & SecureFetchConfig): Promise<Response>;
+/**
+ * Convenience function for secure JSON requests.
+ *
+ * Makes a secure fetch request and parses the response as JSON.
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options and security configuration
+ * @returns Parsed JSON response
+ */
+export declare function secureFetchJson<T = unknown>(url: string, options?: RequestInit & SecureFetchConfig): Promise<T>;
+export type SecureFetchErrorCode = 'VALIDATION_FAILED' | 'TIMEOUT' | 'REQUEST_FAILED' | 'HTTP_ERROR' | 'DNS_REBINDING';
+/**
+ * Error thrown by secure fetch operations.
+ */
+export declare class SecureFetchError extends Error {
+    readonly code: SecureFetchErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(message: string, code: SecureFetchErrorCode, details?: Record<string, unknown>);
+}
+/**
+ * Get default secure fetch configuration from global config.
+ */
+export declare function getSecureFetchDefaults(): Partial<SecureFetchConfig>;
+/**
+ * Create a pre-configured secure fetch function with default options.
+ *
+ * @param defaultOptions - Default options to apply to all requests
+ * @returns Configured secure fetch function
+ */
+export declare function createSecureFetcher(defaultOptions?: Partial<SecureFetchConfig>): (url: string, options?: RequestInit & SecureFetchConfig) => Promise<Response>;
+/**
+ * Default allowed domains for external services.
+ * These are well-known external services that are typically safe to contact.
+ */
+export declare const DEFAULT_ALLOWED_DOMAINS: readonly string[];
+/**
+ * Get allowed domains from configuration.
+ * Falls back to default allowed domains if not configured.
+ */
+export declare function getAllowedDomains(): string[];
+//# sourceMappingURL=secure-fetch.d.ts.map

package/dist/common/secure-fetch.d.ts.map

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