@vorionsys/platform-core 0.1.0

package/dist/common/safe-json.js

@@ -0,0 +1,442 @@
+/**
+ * Safe JSON Parser
+ *
+ * Provides secure JSON parsing with prototype pollution protection,
+ * schema validation, depth limits, and size limits.
+ *
+ * Security features:
+ * - Removes __proto__, constructor, and prototype properties
+ * - Validates against Zod schemas
+ * - Limits object nesting depth to prevent stack overflow
+ * - Limits JSON size to prevent memory exhaustion
+ * - Uses Object.create(null) for prototype-free objects where appropriate
+ *
+ * @packageDocumentation
+ */
+import { createLogger } from "./logger.js";
+const logger = createLogger({ component: "safe-json" });
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Properties that are dangerous and should be stripped from parsed objects
+ * to prevent prototype pollution attacks.
+ */
+const DANGEROUS_PROPERTIES = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Default maximum depth for nested objects
+ */
+const DEFAULT_MAX_DEPTH = 20;
+/**
+ * Default maximum size in bytes for JSON strings
+ */
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024; // 10MB
+/**
+ * Error codes for safe JSON operations
+ */
+export var SafeJsonErrorCode;
+(function (SafeJsonErrorCode) {
+    /** JSON syntax is invalid */
+    SafeJsonErrorCode["INVALID_JSON"] = "INVALID_JSON";
+    /** JSON exceeds maximum size limit */
+    SafeJsonErrorCode["SIZE_EXCEEDED"] = "SIZE_EXCEEDED";
+    /** JSON nesting exceeds maximum depth */
+    SafeJsonErrorCode["DEPTH_EXCEEDED"] = "DEPTH_EXCEEDED";
+    /** JSON failed schema validation */
+    SafeJsonErrorCode["SCHEMA_VALIDATION_FAILED"] = "SCHEMA_VALIDATION_FAILED";
+    /** Prototype pollution attempt detected */
+    SafeJsonErrorCode["PROTOTYPE_POLLUTION"] = "PROTOTYPE_POLLUTION";
+})(SafeJsonErrorCode || (SafeJsonErrorCode = {}));
+/**
+ * Error class for safe JSON operations
+ */
+export class SafeJsonError extends Error {
+    /** Error code identifying the type of error */
+    code;
+    /** Original error that caused this error (if any) */
+    cause;
+    /** Validation errors from Zod (if applicable) */
+    validationErrors;
+    constructor(message, code, cause, validationErrors) {
+        super(message);
+        this.name = "SafeJsonError";
+        this.code = code;
+        this.cause = cause;
+        this.validationErrors = validationErrors;
+    }
+}
+// =============================================================================
+// Core Functions
+// =============================================================================
+/**
+ * Recursively remove dangerous prototype properties from an object.
+ *
+ * This function walks through an object and its nested properties,
+ * removing any properties that could be used for prototype pollution attacks.
+ *
+ * @param obj - The object to sanitize
+ * @returns A new sanitized object with dangerous properties removed
+ *
+ * @example
+ * ```typescript
+ * const malicious = { __proto__: { isAdmin: true }, name: 'test' };
+ * const safe = sanitizeObject(malicious);
+ * // safe = { name: 'test' }
+ * ```
+ */
+export function sanitizeObject(obj) {
+    if (obj === null || typeof obj !== "object") {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => {
+            if (typeof item === "object" && item !== null) {
+                return sanitizeObject(item);
+            }
+            return item;
+        });
+    }
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        // Skip dangerous properties
+        if (DANGEROUS_PROPERTIES.has(key)) {
+            logger.warn({ property: key }, "Stripped dangerous property from parsed JSON");
+            continue;
+        }
+        const value = obj[key];
+        if (typeof value === "object" && value !== null) {
+            result[key] = sanitizeObject(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Create a null-prototype object from an existing object.
+ *
+ * This creates a new object with Object.create(null) and copies
+ * all properties from the source object. The resulting object
+ * has no prototype chain, providing protection against prototype
+ * pollution attacks.
+ *
+ * @param obj - The source object
+ * @returns A new object with null prototype
+ */
+function toNullPrototype(obj) {
+    if (obj === null || typeof obj !== "object") {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => {
+            if (typeof item === "object" && item !== null) {
+                return toNullPrototype(item);
+            }
+            return item;
+        });
+    }
+    const result = Object.create(null);
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        if (typeof value === "object" && value !== null) {
+            result[key] = toNullPrototype(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Check if an object exceeds the maximum nesting depth.
+ *
+ * @param obj - The object to check
+ * @param maxDepth - Maximum allowed depth
+ * @param currentDepth - Current depth in the traversal
+ * @returns true if depth is valid, false if exceeded
+ */
+function checkDepth(obj, maxDepth, currentDepth = 0) {
+    if (currentDepth > maxDepth) {
+        return false;
+    }
+    if (typeof obj !== "object" || obj === null) {
+        return true;
+    }
+    if (Array.isArray(obj)) {
+        return obj.every((item) => checkDepth(item, maxDepth, currentDepth + 1));
+    }
+    return Object.values(obj).every((value) => checkDepth(value, maxDepth, currentDepth + 1));
+}
+/**
+ * Check if an object contains dangerous prototype properties.
+ *
+ * @param obj - The object to check
+ * @returns true if dangerous properties are found
+ */
+function hasDangerousProperties(obj) {
+    if (typeof obj !== "object" || obj === null) {
+        return false;
+    }
+    if (Array.isArray(obj)) {
+        return obj.some((item) => hasDangerousProperties(item));
+    }
+    for (const key of Object.keys(obj)) {
+        if (DANGEROUS_PROPERTIES.has(key)) {
+            return true;
+        }
+        const value = obj[key];
+        if (hasDangerousProperties(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Safely parse a JSON string with security protections.
+ *
+ * This function provides multiple layers of protection against common
+ * JSON-based attacks:
+ * - Size limits to prevent memory exhaustion
+ * - Depth limits to prevent stack overflow
+ * - Prototype pollution protection
+ * - Optional schema validation
+ *
+ * @param json - The JSON string to parse
+ * @param options - Parsing options
+ * @returns The parsed and validated object
+ * @throws {SafeJsonError} If parsing fails or validation fails
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const data = safeJsonParse<{ name: string }>('{"name": "test"}');
+ *
+ * // With schema validation
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const validated = safeJsonParse('{"name": "test", "age": 25}', { schema });
+ *
+ * // With all options
+ * const secure = safeJsonParse(untrustedJson, {
+ *   schema: mySchema,
+ *   maxDepth: 10,
+ *   maxSize: 1024 * 1024, // 1MB
+ *   stripPrototype: true,
+ *   useNullPrototype: true,
+ * });
+ * ```
+ */
+export function safeJsonParse(json, options = {}) {
+    const { schema, maxDepth = DEFAULT_MAX_DEPTH, maxSize = DEFAULT_MAX_SIZE, stripPrototype = true, useNullPrototype = false, } = options;
+    // Check size limit
+    const size = new TextEncoder().encode(json).length;
+    if (size > maxSize) {
+        throw new SafeJsonError(`JSON size ${size} bytes exceeds maximum of ${maxSize} bytes`, SafeJsonErrorCode.SIZE_EXCEEDED);
+    }
+    // Parse JSON
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        throw new SafeJsonError(`Invalid JSON: ${error instanceof Error ? error.message : "Unknown error"}`, SafeJsonErrorCode.INVALID_JSON, error instanceof Error ? error : undefined);
+    }
+    // Check depth limit
+    if (typeof parsed === "object" && parsed !== null) {
+        if (!checkDepth(parsed, maxDepth)) {
+            throw new SafeJsonError(`JSON nesting depth exceeds maximum of ${maxDepth}`, SafeJsonErrorCode.DEPTH_EXCEEDED);
+        }
+    }
+    // Check for and optionally strip dangerous properties
+    if (typeof parsed === "object" && parsed !== null) {
+        if (hasDangerousProperties(parsed)) {
+            if (stripPrototype) {
+                logger.warn({ jsonPreview: json.substring(0, 100) }, "Dangerous properties detected and stripped from JSON");
+                parsed = sanitizeObject(parsed);
+            }
+            else {
+                throw new SafeJsonError("JSON contains dangerous prototype properties", SafeJsonErrorCode.PROTOTYPE_POLLUTION);
+            }
+        }
+        // Convert to null prototype if requested
+        if (useNullPrototype) {
+            parsed = toNullPrototype(parsed);
+        }
+    }
+    // Validate against schema if provided
+    if (schema) {
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            throw new SafeJsonError(`Schema validation failed: ${result.error.message}`, SafeJsonErrorCode.SCHEMA_VALIDATION_FAILED, result.error, result.error.errors);
+        }
+        return result.data;
+    }
+    return parsed;
+}
+/**
+ * Safely parse a JSON string, returning a result object instead of throwing.
+ *
+ * This is the "safe" variant that never throws, making it suitable for
+ * use cases where you want to handle errors gracefully.
+ *
+ * @param json - The JSON string to parse
+ * @param options - Parsing options
+ * @returns A result object with success/failure status
+ *
+ * @example
+ * ```typescript
+ * const result = safeJsonParseSafe(userInput, { schema: mySchema });
+ * if (result.success) {
+ *   console.log('Parsed:', result.data);
+ * } else {
+ *   console.error('Failed:', result.error?.message);
+ * }
+ * ```
+ */
+export function safeJsonParseSafe(json, options = {}) {
+    try {
+        const data = safeJsonParse(json, options);
+        return { success: true, data };
+    }
+    catch (error) {
+        if (error instanceof SafeJsonError) {
+            return { success: false, error };
+        }
+        return {
+            success: false,
+            error: new SafeJsonError(`Unexpected error: ${error instanceof Error ? error.message : "Unknown"}`, SafeJsonErrorCode.INVALID_JSON, error instanceof Error ? error : undefined),
+        };
+    }
+}
+/**
+ * Create a Map from JSON instead of a plain object.
+ *
+ * Maps are inherently safe from prototype pollution because they
+ * don't have a prototype chain for data access.
+ *
+ * @param json - The JSON string to parse (must be an object)
+ * @param options - Parsing options (schema is not applicable for Maps)
+ * @returns A Map with string keys
+ *
+ * @example
+ * ```typescript
+ * const map = safeJsonParseAsMap('{"key1": "value1", "key2": "value2"}');
+ * console.log(map.get('key1')); // "value1"
+ * ```
+ */
+export function safeJsonParseAsMap(json, options = {}) {
+    const parsed = safeJsonParse(json, {
+        ...options,
+        stripPrototype: true,
+    });
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new SafeJsonError("JSON must be an object to parse as Map", SafeJsonErrorCode.INVALID_JSON);
+    }
+    const map = new Map();
+    for (const [key, value] of Object.entries(parsed)) {
+        // Skip dangerous keys even though sanitizeObject should have removed them
+        if (!DANGEROUS_PROPERTIES.has(key)) {
+            map.set(key, value);
+        }
+    }
+    return map;
+}
+/**
+ * Stringify an object to JSON safely.
+ *
+ * This function sanitizes the object before stringifying to ensure
+ * dangerous properties are not serialized.
+ *
+ * @param value - The value to stringify
+ * @param space - Indentation for pretty printing
+ * @returns The JSON string
+ *
+ * @example
+ * ```typescript
+ * const json = safeJsonStringify({ name: 'test', __proto__: { evil: true } });
+ * // json = '{"name":"test"}'
+ * ```
+ */
+export function safeJsonStringify(value, space) {
+    if (typeof value === "object" && value !== null) {
+        value = sanitizeObject(value);
+    }
+    return JSON.stringify(value, null, space);
+}
+// =============================================================================
+// Pre-configured Parsers
+// =============================================================================
+/**
+ * Create a type-safe parser for a specific schema.
+ *
+ * This creates a reusable parser function that always validates
+ * against the provided schema.
+ *
+ * @param schema - The Zod schema to validate against
+ * @param defaultOptions - Default options for all parse calls
+ * @returns A parser function
+ *
+ * @example
+ * ```typescript
+ * const userSchema = z.object({
+ *   id: z.string().uuid(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * const parseUser = createSafeParser(userSchema);
+ *
+ * // Later...
+ * const user = parseUser(jsonString);
+ * // user is typed as { id: string; name: string; email: string }
+ * ```
+ */
+export function createSafeParser(schema, defaultOptions = {}) {
+    return (json, options = {}) => {
+        return safeJsonParse(json, {
+            ...defaultOptions,
+            ...options,
+            schema,
+        });
+    };
+}
+/**
+ * Create a type-safe parser that returns a SafeParseResult.
+ *
+ * @param schema - The Zod schema to validate against
+ * @param defaultOptions - Default options for all parse calls
+ * @returns A parser function that returns SafeParseResult
+ */
+export function createSafeParserSafe(schema, defaultOptions = {}) {
+    return (json, options = {}) => {
+        return safeJsonParseSafe(json, {
+            ...defaultOptions,
+            ...options,
+            schema,
+        });
+    };
+}
+// =============================================================================
+// Reviver-based Parsing
+// =============================================================================
+/**
+ * A JSON.parse reviver function that strips dangerous properties.
+ *
+ * This can be used directly with JSON.parse when you need low-level control.
+ *
+ * @param key - The property key
+ * @param value - The property value
+ * @returns The value (or undefined to skip)
+ *
+ * @example
+ * ```typescript
+ * const parsed = JSON.parse(json, safeReviver);
+ * ```
+ */
+export function safeReviver(key, value) {
+    if (DANGEROUS_PROPERTIES.has(key)) {
+        return undefined;
+    }
+    return value;
+}
+//# sourceMappingURL=safe-json.js.map

package/dist/common/safe-json.js.map

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

package/dist/common/secret-generator.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Secret Generator for Vorion
+ *
+ * Provides secure secret generation and management for deployment.
+ * Generates cryptographically secure secrets for JWT, encryption, CSRF, etc.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Generated secrets structure
+ */
+export interface GeneratedSecrets {
+    /** JWT signing secret (64 bytes, base64 encoded) */
+    jwtSecret: string;
+    /** AES-256-GCM encryption key (32 bytes, base64 encoded) */
+    encryptionKey: string;
+    /** PBKDF2 salt for key derivation (16 bytes, base64 encoded) */
+    encryptionSalt: string;
+    /** HMAC secret for deduplication hashing (32 bytes, base64 encoded) */
+    dedupeSecret: string;
+    /** HMAC secret for CSRF token signing (32 bytes, base64 encoded) */
+    csrfSecret: string;
+    /** Timestamp when secrets were generated */
+    generatedAt: string;
+    /** Version of the secret generation format */
+    version: number;
+}
+/**
+ * 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 declare function calculateEntropy(str: string): number;
+/**
+ * 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 declare function generateSecret(bytes?: number): string;
+/**
+ * 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 declare function generateSecretWithValidation(bytes?: number, minEntropy?: number): string;
+/**
+ * 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 declare function generateSecrets(): GeneratedSecrets;
+/**
+ * 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 declare function getSecretFingerprint(secret: string): string;
+/**
+ * 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 declare function loadOrGenerateSecrets(dataDir: string): Promise<GeneratedSecrets>;
+/**
+ * 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 declare function applySecretsToEnv(secrets: GeneratedSecrets, override?: boolean): void;
+/**
+ * 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 declare function generateEnvFileContent(secrets: GeneratedSecrets): string;
+/**
+ * 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 declare function rotateSecrets(): GeneratedSecrets;
+/**
+ * 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 declare function validateSecret(secret: string, name: string, minLength?: number): {
+    valid: boolean;
+    error?: string;
+};
+//# sourceMappingURL=secret-generator.d.ts.map

package/dist/common/secret-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-generator.d.ts","sourceRoot":"","sources":["../../src/common/secret-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAYD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBpD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAE,MAAW,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,GAAE,MAAW,EAClB,UAAU,GAAE,MAAyB,GACpC,MAAM,CAaR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAalD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqDtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,GAAE,OAAe,GAAG,IAAI,CAe5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAwBxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,CAEhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAW,GACrB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAkCpC"}