@friggframework/core 2.0.0-next.6 → 2.0.0-next.61

package/database/encryption/encryption-schema-registry.js

@@ -0,0 +1,268 @@
+/**
+ * Encryption Schema Registry
+ *
+ * Centralized registry defining which fields require encryption for each Prisma model.
+ * Database-agnostic, works identically for MongoDB and PostgreSQL.
+ * Extensible by integration developers via appDefinition.
+ *
+ * Field path format: 'fieldName' or 'parent.child.field' for nested JSON.
+ */
+
+const { logger } = require('./logger');
+
+/**
+ * Core encryption schema (immutable - cannot be overridden by custom schemas)
+ */
+const CORE_ENCRYPTION_SCHEMA = {
+    Credential: {
+        fields: [
+            'data.access_token',
+            'data.refresh_token',
+            'data.id_token',
+            'data.api_key',
+            'data.apiKey',
+            'data.API_KEY_VALUE',
+            'data.password',
+            'data.client_secret',
+        ],
+    },
+
+    IntegrationMapping: {
+        fields: ['mapping'],
+    },
+
+    User: {
+        fields: ['hashword'],
+    },
+
+    Token: {
+        fields: ['token'],
+    },
+};
+
+let customSchema = {};
+
+/**
+ * Validates a custom encryption schema
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+function validateCustomSchema(schema) {
+    const errors = [];
+
+    if (!schema || typeof schema !== 'object') {
+        errors.push('Custom schema must be an object');
+        return { valid: false, errors };
+    }
+
+    for (const [modelName, config] of Object.entries(schema)) {
+        if (typeof modelName !== 'string' || !modelName) {
+            errors.push(`Invalid model name: ${modelName}`);
+            continue;
+        }
+
+        if (!config || typeof config !== 'object') {
+            errors.push(`Model "${modelName}" must have a config object`);
+            continue;
+        }
+
+        if (!Array.isArray(config.fields)) {
+            errors.push(`Model "${modelName}" must have a "fields" array`);
+            continue;
+        }
+
+        for (const fieldPath of config.fields) {
+            if (typeof fieldPath !== 'string' || !fieldPath) {
+                errors.push(`Model "${modelName}" has invalid field path: ${fieldPath}`);
+            }
+
+            // Check if trying to override core fields
+            const coreFields = CORE_ENCRYPTION_SCHEMA[modelName]?.fields || [];
+            if (coreFields.includes(fieldPath)) {
+                errors.push(
+                    `Cannot override core encrypted field "${fieldPath}" in model "${modelName}"`
+                );
+            }
+        }
+    }
+
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+
+/**
+ * Registers a custom encryption schema from integration developer.
+ * Merges with core schema, prevents overriding core fields.
+ * @throws {Error} If schema validation fails
+ */
+function registerCustomSchema(schema) {
+    if (!schema || Object.keys(schema).length === 0) {
+        return; // Nothing to register
+    }
+
+    const validation = validateCustomSchema(schema);
+    if (!validation.valid) {
+        throw new Error(
+            `Invalid custom encryption schema:\n- ${validation.errors.join('\n- ')}`
+        );
+    }
+
+    customSchema = { ...schema };
+    logger.info(
+        `Registered custom encryption schema for models: ${Object.keys(customSchema).join(', ')}`
+    );
+}
+
+/**
+ * Extracts credential field paths from module definitions
+ * @param {Array} moduleDefinitions - Array of module definition objects
+ * @returns {Array<string>} Array of field paths with data. prefix
+ */
+function extractCredentialFieldsFromModules(moduleDefinitions) {
+    const fields = [];
+
+    for (const moduleDef of moduleDefinitions) {
+        if (!moduleDef?.encryption?.credentialFields) {
+            continue;
+        }
+
+        const credentialFields = moduleDef.encryption.credentialFields;
+        if (!Array.isArray(credentialFields) || credentialFields.length === 0) {
+            continue;
+        }
+
+        for (const field of credentialFields) {
+            const prefixedField = field.startsWith('data.') ? field : `data.${field}`;
+            fields.push(prefixedField);
+        }
+    }
+
+    return [...new Set(fields)];
+}
+
+/**
+ * Loads and registers encryption schemas from API module definitions.
+ * Each module can declare credentialFields to encrypt in its encryption config.
+ *
+ * @param {Array} integrations - Array of integration classes with modules
+ */
+function loadModuleEncryptionSchemas(integrations) {
+    if (!integrations) {
+        throw new Error('integrations parameter is required');
+    }
+
+    if (!Array.isArray(integrations)) {
+        throw new Error('integrations must be an array');
+    }
+
+    if (integrations.length === 0) {
+        return;
+    }
+
+    const { getModulesDefinitionFromIntegrationClasses } = require('../integrations/utils/map-integration-dto');
+
+    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrations);
+    const credentialFields = extractCredentialFieldsFromModules(moduleDefinitions);
+
+    if (credentialFields.length === 0) {
+        return;
+    }
+
+    const moduleSchema = {
+        Credential: {
+            fields: credentialFields
+        }
+    };
+
+    logger.info(
+        `Registering module-level encryption for ${credentialFields.length} credential fields`
+    );
+
+    registerCustomSchema(moduleSchema);
+}
+
+/**
+ * Loads and registers custom encryption schema from appDefinition.
+ * Gracefully handles cases where appDefinition is not available.
+ *
+ * This ensures that custom encryption schemas defined in the backend's index.js
+ * are registered before any repositories attempt to encrypt data.
+ *
+ * Used by both Prisma (MongoDB/PostgreSQL) and DocumentDB encryption services.
+ */
+function loadCustomEncryptionSchema() {
+    try {
+        // Lazy require to avoid circular dependency issues
+        const path = require('node:path');
+        const { findNearestBackendPackageJson } = require('../../utils');
+
+        const backendPackagePath = findNearestBackendPackageJson();
+        if (!backendPackagePath) {
+            return; // No backend found, skip custom schema
+        }
+
+        const backendDir = path.dirname(backendPackagePath);
+        const backendIndexPath = path.join(backendDir, 'index.js');
+
+        const backendModule = require(backendIndexPath);
+        const appDefinition = backendModule?.Definition;
+
+        if (!appDefinition) {
+            return; // No app definition found
+        }
+
+        // Load app-level custom schema
+        const customSchema = appDefinition.encryption?.schema;
+        if (customSchema && Object.keys(customSchema).length > 0) {
+            registerCustomSchema(customSchema);
+        }
+
+        // Load module-level encryption schemas from integrations
+        const integrations = appDefinition.integrations;
+        if (integrations && Array.isArray(integrations)) {
+            loadModuleEncryptionSchemas(integrations);
+        }
+    } catch (error) {
+        // Silently ignore errors - custom schema is optional
+        // This handles cases like:
+        // - Backend package.json not found (tests, standalone usage)
+        // - No appDefinition defined
+        // - No custom encryption schema specified
+        logger.debug('Could not load custom encryption schema:', error.message);
+    }
+}
+
+function getEncryptedFields(modelName) {
+    const coreFields = CORE_ENCRYPTION_SCHEMA[modelName]?.fields || [];
+    const customFields = customSchema[modelName]?.fields || [];
+    const allFields = [...coreFields, ...customFields];
+    return [...new Set(allFields)];
+}
+
+function hasEncryptedFields(modelName) {
+    return getEncryptedFields(modelName).length > 0;
+}
+
+function getEncryptedModels() {
+    const coreModels = Object.keys(CORE_ENCRYPTION_SCHEMA);
+    const customModels = Object.keys(customSchema);
+    return [...new Set([...coreModels, ...customModels])];
+}
+
+function resetCustomSchema() {
+    customSchema = {};
+}
+
+module.exports = {
+    CORE_ENCRYPTION_SCHEMA,
+    getEncryptedFields,
+    hasEncryptedFields,
+    getEncryptedModels,
+    registerCustomSchema,
+    loadCustomEncryptionSchema,
+    loadModuleEncryptionSchemas,
+    extractCredentialFieldsFromModules,
+    validateCustomSchema,
+    resetCustomSchema,
+};

package/database/encryption/field-encryption-service.js

@@ -0,0 +1,226 @@
+/**
+ * Field Encryption Service
+ *
+ * Infrastructure layer service that orchestrates field-level encryption/decryption.
+ * Handles nested JSON paths (e.g., 'data.access_token') and bulk operations.
+ */
+class FieldEncryptionService {
+    constructor({ cryptor, schema }) {
+        if (!cryptor) {
+            throw new Error('Cryptor instance required');
+        }
+        if (!schema || typeof schema.getEncryptedFields !== 'function') {
+            throw new Error('Schema with getEncryptedFields method required');
+        }
+
+        this.cryptor = cryptor;
+        this.schema = schema;
+    }
+
+    async encryptFields(modelName, document) {
+        if (!document || typeof document !== 'object') {
+            return document;
+        }
+
+        const fields = this.schema.getEncryptedFields(modelName);
+        if (fields.length === 0) {
+            return document;
+        }
+
+        const encrypted = this._deepClone(document);
+
+        // Parallelize encryption of multiple fields
+        const encryptionPromises = fields.map(async (fieldPath) => {
+            const value = this._getNestedValue(encrypted, fieldPath);
+
+            if (this._shouldEncrypt(value)) {
+                const serializedValue = this._serializeForEncryption(value);
+                const encryptedValue = await this.cryptor.encrypt(serializedValue);
+                return { fieldPath, encryptedValue };
+            }
+            return null;
+        });
+
+        const results = await Promise.all(encryptionPromises);
+
+        // Apply encrypted values
+        for (const result of results) {
+            if (result) {
+                this._setNestedValue(encrypted, result.fieldPath, result.encryptedValue);
+            }
+        }
+
+        return encrypted;
+    }
+
+    async decryptFields(modelName, document) {
+        if (!document || typeof document !== 'object') {
+            return document;
+        }
+
+        const fields = this.schema.getEncryptedFields(modelName);
+        if (fields.length === 0) {
+            return document;
+        }
+
+        const decrypted = this._deepClone(document);
+
+        // Parallelize decryption of multiple fields
+        const decryptionPromises = fields.map(async (fieldPath) => {
+            const value = this._getNestedValue(decrypted, fieldPath);
+
+            if (this._isEncrypted(value)) {
+                const decryptedValue = await this.cryptor.decrypt(value);
+                const deserializedValue = this._deserializeAfterDecryption(decryptedValue);
+                return { fieldPath, decryptedValue: deserializedValue };
+            }
+            return null;
+        });
+
+        const results = await Promise.all(decryptionPromises);
+
+        // Apply decrypted values
+        for (const result of results) {
+            if (result) {
+                this._setNestedValue(decrypted, result.fieldPath, result.decryptedValue);
+            }
+        }
+
+        return decrypted;
+    }
+
+    async encryptFieldsInBulk(modelName, documents) {
+        if (!Array.isArray(documents)) {
+            return documents;
+        }
+
+        return Promise.all(
+            documents.map((doc) => this.encryptFields(modelName, doc))
+        );
+    }
+
+    async decryptFieldsInBulk(modelName, documents) {
+        if (!Array.isArray(documents)) {
+            return documents;
+        }
+
+        return Promise.all(
+            documents.map((doc) => this.decryptFields(modelName, doc))
+        );
+    }
+
+    _shouldEncrypt(value) {
+        return (
+            value !== null &&
+            value !== undefined &&
+            value !== '' &&
+            !this._isEncrypted(value)
+        );
+    }
+
+    _isEncrypted(value) {
+        if (typeof value !== 'string') {
+            return false;
+        }
+
+        const parts = value.split(':');
+        return parts.length >= 4;
+    }
+
+    _getNestedValue(obj, path) {
+        if (!obj || !path) {
+            return undefined;
+        }
+
+        return path.split('.').reduce((current, key) => {
+            return current?.[key];
+        }, obj);
+    }
+
+    _setNestedValue(obj, path, value) {
+        if (!obj || !path) {
+            return;
+        }
+
+        const keys = path.split('.');
+        const lastKey = keys.pop();
+
+        const target = keys.reduce((current, key) => {
+            if (!current[key] || typeof current[key] !== 'object') {
+                current[key] = {};
+            }
+            return current[key];
+        }, obj);
+
+        target[lastKey] = value;
+    }
+
+    _deepClone(obj) {
+        // Use structuredClone (Node.js 17+) for better performance
+        // Falls back to custom implementation for older Node versions
+        if (typeof structuredClone !== 'undefined') {
+            try {
+                return structuredClone(obj);
+            } catch {
+                // Fall through to custom implementation
+            }
+        }
+
+        // Custom fallback for older environments
+        if (obj === null || typeof obj !== 'object') {
+            return obj;
+        }
+
+        if (obj instanceof Date) {
+            return new Date(obj.getTime());
+        }
+
+        if (Array.isArray(obj)) {
+            return obj.map((item) => this._deepClone(item));
+        }
+
+        const cloned = {};
+        for (const key in obj) {
+            if (obj.hasOwnProperty(key)) {
+                cloned[key] = this._deepClone(obj[key]);
+            }
+        }
+
+        return cloned;
+    }
+
+    /**
+     * Serialize a value for encryption
+     * Objects/arrays are JSON stringified, primitives are converted to strings
+     * @private
+     */
+    _serializeForEncryption(value) {
+        if (typeof value === 'object' && value !== null) {
+            // JSON.stringify for objects and arrays
+            return JSON.stringify(value);
+        }
+        // For primitives (string, number, boolean), convert to string
+        return String(value);
+    }
+
+    /**
+     * Deserialize a value after decryption
+     * Attempts to parse as JSON, returns string if parsing fails
+     * @private
+     */
+    _deserializeAfterDecryption(value) {
+        if (typeof value !== 'string') {
+            return value;
+        }
+
+        // Try to parse as JSON
+        try {
+            return JSON.parse(value);
+        } catch {
+            // Not valid JSON, return as-is (likely was a plain string field)
+            return value;
+        }
+    }
+}
+
+module.exports = { FieldEncryptionService };

package/database/encryption/logger.js

@@ -0,0 +1,79 @@
+/**
+ * Encryption Logger
+ *
+ * Centralized logging for encryption operations.
+ * Prevents sensitive data leakage in production logs.
+ */
+
+const LOG_LEVELS = {
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3,
+};
+
+class EncryptionLogger {
+    constructor() {
+        this.minLevel = this._getMinLevel();
+    }
+
+    _getMinLevel() {
+        const level = process.env.FRIGG_LOG_LEVEL || 'INFO';
+        return LOG_LEVELS[level.toUpperCase()] ?? LOG_LEVELS.INFO;
+    }
+
+    _shouldLog(level) {
+        return LOG_LEVELS[level] >= this.minLevel;
+    }
+
+    _sanitize(message) {
+        // Remove potential key material or encrypted data from logs
+        if (typeof message === 'string') {
+            // Truncate long base64 strings that might be keys or encrypted data
+            return message.replace(/([A-Za-z0-9+/=]{50,})/g, (match) =>
+                `${match.substring(0, 10)}...[${match.length} chars]`
+            );
+        }
+        return message;
+    }
+
+    debug(message, ...args) {
+        if (this._shouldLog('DEBUG')) {
+            console.log(`[Frigg Debug]`, this._sanitize(message), ...args);
+        }
+    }
+
+    info(message, ...args) {
+        if (this._shouldLog('INFO')) {
+            console.log(`[Frigg]`, this._sanitize(message), ...args);
+        }
+    }
+
+    warn(message, ...args) {
+        if (this._shouldLog('WARN')) {
+            console.warn(`[Frigg]`, this._sanitize(message), ...args);
+        }
+    }
+
+    error(message, error) {
+        if (this._shouldLog('ERROR')) {
+            const sanitizedMessage = this._sanitize(message);
+
+            // In production, don't log stack traces with sensitive paths
+            const isProduction = process.env.STAGE === 'production';
+
+            if (error && !isProduction) {
+                console.error(`[Frigg]`, sanitizedMessage, error);
+            } else if (error) {
+                console.error(`[Frigg]`, sanitizedMessage, error.message);
+            } else {
+                console.error(`[Frigg]`, sanitizedMessage);
+            }
+        }
+    }
+}
+
+// Singleton instance
+const logger = new EncryptionLogger();
+
+module.exports = { logger };