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

package/database/use-cases/check-encryption-health-use-case.js

@@ -0,0 +1,83 @@
+class CheckEncryptionHealthUseCase {
+    constructor({ testEncryptionUseCase }) {
+        this.testEncryptionUseCase = testEncryptionUseCase;
+    }
+
+    async execute() {
+        const config = this._getEncryptionConfiguration();
+
+        if (config.isBypassed || config.mode === 'none') {
+            const testResult = config.isBypassed
+                ? 'Encryption bypassed for this stage'
+                : 'No encryption keys configured';
+
+            return {
+                status: 'disabled',
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                testResult,
+                encryptionWorks: false,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
+            };
+        }
+
+        try {
+            const testResults = await this.testEncryptionUseCase.execute();
+
+            return {
+                ...testResults,
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
+            };
+        } catch (error) {
+            return {
+                status: 'unhealthy',
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                testResult: `Encryption test failed: ${error.message}`,
+                encryptionWorks: false,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
+            };
+        }
+    }
+
+    _getEncryptionConfiguration() {
+        const { STAGE, BYPASS_ENCRYPTION_STAGE, KMS_KEY_ARN, AES_KEY_ID } =
+            process.env;
+
+        const defaultBypassStages = ['dev', 'test', 'local'];
+        const useEnv = BYPASS_ENCRYPTION_STAGE !== undefined;
+        const bypassStages = useEnv
+            ? BYPASS_ENCRYPTION_STAGE.split(',').map((s) => s.trim())
+            : defaultBypassStages;
+
+        const isBypassed = bypassStages.includes(STAGE);
+        const hasAES = AES_KEY_ID && AES_KEY_ID.trim() !== '';
+        const hasKMS = KMS_KEY_ARN && KMS_KEY_ARN.trim() !== '';
+        // Prefer KMS over AES when both are configured (KMS is more secure)
+        const mode = hasKMS ? 'kms' : hasAES ? 'aes' : 'none';
+
+        return {
+            stage: STAGE || null,
+            isBypassed,
+            hasAES,
+            hasKMS,
+            mode,
+        };
+    }
+}
+
+module.exports = { CheckEncryptionHealthUseCase };

package/database/use-cases/get-database-state-via-worker-use-case.js

@@ -0,0 +1,61 @@
+/**
+ * Get Database State Via Worker Use Case
+ * 
+ * Domain logic for getting database state by invoking the worker Lambda.
+ * This use case delegates to the worker Lambda which has Prisma CLI installed,
+ * keeping the router Lambda lightweight.
+ * 
+ * Architecture: Hexagonal/Clean
+ * - Use Case (Domain Layer)
+ * - Depends on LambdaInvoker (Infrastructure abstraction)
+ * - Called by Router (Adapter Layer)
+ */
+
+/**
+ * Domain Use Case: Get database state by invoking worker Lambda
+ * 
+ * This use case delegates database state checking to the worker Lambda,
+ * which has Prisma CLI installed. Keeps the router Lambda lightweight.
+ */
+class GetDatabaseStateViaWorkerUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {LambdaInvoker} dependencies.lambdaInvoker - Lambda invocation adapter
+     * @param {string} dependencies.workerFunctionName - Worker Lambda function name
+     */
+    constructor({ lambdaInvoker, workerFunctionName }) {
+        if (!lambdaInvoker) {
+            throw new Error('lambdaInvoker dependency is required');
+        }
+        if (!workerFunctionName) {
+            throw new Error('workerFunctionName is required');
+        }
+        this.lambdaInvoker = lambdaInvoker;
+        this.workerFunctionName = workerFunctionName;
+    }
+
+    /**
+     * Execute database state check via worker Lambda
+     * 
+     * @param {string} stage - Deployment stage (prod, dev, etc)
+     * @returns {Promise<Object>} Database state result
+     */
+    async execute(stage = 'production') {
+        const dbType = process.env.DB_TYPE || 'postgresql';
+
+        console.log(`Invoking worker Lambda to check database state: ${this.workerFunctionName}`);
+
+        // Invoke worker Lambda with checkStatus action
+        const result = await this.lambdaInvoker.invoke(this.workerFunctionName, {
+            action: 'checkStatus',
+            dbType,
+            stage,
+        });
+
+        return result;
+    }
+}
+
+module.exports = { GetDatabaseStateViaWorkerUseCase };
+
+

package/database/use-cases/get-migration-status-use-case.js

@@ -0,0 +1,93 @@
+/**
+ * Get Migration Status Use Case
+ *
+ * Retrieves the status of a database migration by process ID.
+ * Formats the Process record for migration-specific response.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Routers (adapters) call use cases
+ * - Use cases contain business logic and formatting
+ * - Use cases call repositories for data access
+ */
+
+class GetMigrationStatusUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.migrationStatusRepository - Repository for migration status (S3)
+     */
+    constructor({ migrationStatusRepository }) {
+        if (!migrationStatusRepository) {
+            throw new Error('migrationStatusRepository dependency is required');
+        }
+        this.migrationStatusRepository = migrationStatusRepository;
+    }
+
+    /**
+     * Execute get migration status
+     *
+     * @param {string} migrationId - Migration ID to retrieve
+     * @param {string} [stage] - Deployment stage (defaults to env.STAGE)
+     * @returns {Promise<Object>} Migration status from S3
+     * @throws {NotFoundError} If migration not found
+     * @throws {ValidationError} If migrationId is invalid
+     */
+    async execute(migrationId, stage = null) {
+        // Validation
+        this._validateParams(migrationId);
+
+        const effectiveStage = stage || process.env.STAGE || 'production';
+
+        // Get migration status from S3
+        try {
+            const migrationStatus = await this.migrationStatusRepository.get(migrationId, effectiveStage);
+            return migrationStatus;
+        } catch (error) {
+            if (error.message.includes('not found')) {
+                throw new NotFoundError(`Migration not found: ${migrationId}`);
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Validate parameters
+     * @private
+     */
+    _validateParams(migrationId) {
+        if (!migrationId) {
+            throw new ValidationError('migrationId is required');
+        }
+
+        if (typeof migrationId !== 'string') {
+            throw new ValidationError('migrationId must be a string');
+        }
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Custom error for not found resources
+ */
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+        this.statusCode = 404;
+    }
+}
+
+module.exports = {
+    GetMigrationStatusUseCase,
+    ValidationError,
+    NotFoundError,
+};
+

package/database/use-cases/run-database-migration-use-case.js

@@ -0,0 +1,139 @@
+/**
+ * Run Database Migration Use Case
+ *
+ * Business logic for running Prisma database migrations.
+ * Orchestrates Prisma client generation and migration execution.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Handlers (adapters) call use cases
+ * - Use cases contain business logic and orchestration
+ * - Use cases call repositories/utilities for data access
+ */
+
+class RunDatabaseMigrationUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.prismaRunner - Prisma runner utilities
+     */
+    constructor({ prismaRunner }) {
+        if (!prismaRunner) {
+            throw new Error('prismaRunner dependency is required');
+        }
+        this.prismaRunner = prismaRunner;
+    }
+
+    /**
+     * Execute database migration
+     *
+     * @param {Object} params
+     * @param {string} params.dbType - Database type ('postgresql', 'mongodb', or 'documentdb')
+     * @param {string} params.stage - Deployment stage (determines migration command)
+     * @param {boolean} [params.verbose=false] - Enable verbose output
+     * @returns {Promise<Object>} Migration result { success, dbType, stage, command, message }
+     * @throws {MigrationError} If migration fails
+     * @throws {ValidationError} If parameters are invalid
+     */
+    async execute({ dbType, stage, verbose = false }) {
+        // Validation
+        this._validateParams({ dbType, stage });
+
+        // Step 1: Generate Prisma client
+        const generateResult = await this.prismaRunner.runPrismaGenerate(dbType, verbose);
+
+        if (!generateResult.success) {
+            throw new MigrationError(
+                `Failed to generate Prisma client: ${generateResult.error || 'Unknown error'}`,
+                { dbType, stage, step: 'generate', output: generateResult.output }
+            );
+        }
+
+        // Step 2: Run migrations based on database type
+        let migrationResult;
+        let migrationCommand;
+
+        if (dbType === 'postgresql') {
+            migrationCommand = this.prismaRunner.getMigrationCommand(stage);
+            migrationResult = await this.prismaRunner.runPrismaMigrate(migrationCommand, verbose);
+
+            if (!migrationResult.success) {
+                throw new MigrationError(
+                    `PostgreSQL migration failed: ${migrationResult.error || 'Unknown error'}`,
+                    { dbType, stage, command: migrationCommand, step: 'migrate', output: migrationResult.output }
+                );
+            }
+        } else if (dbType === 'mongodb' || dbType === 'documentdb') {
+            migrationCommand = 'db push';
+            // Use non-interactive mode for automated/Lambda environments
+            migrationResult = await this.prismaRunner.runPrismaDbPush(verbose, true);
+
+            if (!migrationResult.success) {
+                throw new MigrationError(
+                    `Mongo-compatible push failed: ${migrationResult.error || 'Unknown error'}`,
+                    { dbType, stage, command: migrationCommand, step: 'push', output: migrationResult.output }
+                );
+            }
+        } else {
+            throw new ValidationError(
+                `Unsupported database type: ${dbType}. Must be 'postgresql', 'mongodb', or 'documentdb'.`
+            );
+        }
+
+        // Return success result
+        return {
+            success: true,
+            dbType,
+            stage,
+            command: migrationCommand,
+            message: 'Database migration completed successfully',
+        };
+    }
+
+    /**
+     * Validate execution parameters
+     * @private
+     */
+    _validateParams({ dbType, stage }) {
+        if (!dbType) {
+            throw new ValidationError('dbType is required');
+        }
+
+        if (typeof dbType !== 'string') {
+            throw new ValidationError('dbType must be a string');
+        }
+
+        if (!stage) {
+            throw new ValidationError('stage is required');
+        }
+
+        if (typeof stage !== 'string') {
+            throw new ValidationError('stage must be a string');
+        }
+    }
+}
+
+/**
+ * Custom error for migration failures
+ */
+class MigrationError extends Error {
+    constructor(message, context = {}) {
+        super(message);
+        this.name = 'MigrationError';
+        this.context = context;
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+module.exports = {
+    RunDatabaseMigrationUseCase,
+    MigrationError,
+    ValidationError,
+};

package/database/use-cases/test-encryption-use-case.js

@@ -0,0 +1,253 @@
+/**
+ * Use Case for testing encryption functionality.
+ * Contains business logic for verifying that encryption and decryption work correctly.
+ *
+ * Follows DDD/Hexagonal Architecture:
+ * - Application Layer (this use case)
+ * - Depends on Infrastructure Layer (HealthCheckRepository)
+ */
+class TestEncryptionUseCase {
+    /**
+     * @param {Object} params
+     * @param {import('../health-check-repository-interface').HealthCheckRepositoryInterface} params.healthCheckRepository
+     */
+    constructor({ healthCheckRepository }) {
+        this.repository = healthCheckRepository;
+    }
+
+    /**
+     * Execute encryption test
+     * Orchestrates the full encryption test workflow using Prisma
+     * @returns {Promise<Object>} Test results with status and details
+     */
+    async execute() {
+        const testData = {
+            testSecret: 'This is a secret value that should be encrypted',
+            normalField: 'This is a normal field that should not be encrypted',
+            nestedSecret: {
+                value: 'This is a nested secret that should be encrypted',
+            },
+        };
+
+        const credentialData = this._mapTestDataToCredential(testData);
+
+        const credential = await this._withTimeout(
+            this.repository.createCredential(credentialData),
+            5000,
+            'Save operation timed out'
+        );
+
+        try {
+            const retrievedCredential = await this._withTimeout(
+                this.repository.findCredentialById(credential.id),
+                5000,
+                'Find operation timed out'
+            );
+
+            const retrievedTestData =
+                this._mapCredentialToTestData(retrievedCredential);
+            const decryptionWorks = this._verifyDecryption(
+                retrievedTestData,
+                testData
+            );
+
+            const rawCredential = await this._withTimeout(
+                this.repository.getRawCredentialById(credential.id),
+                5000,
+                'Database verification timed out'
+            );
+
+            const rawTestData = this._mapRawCredentialToTestData(rawCredential);
+            const encryptionResults = this._verifyEncryptionInDatabase(
+                rawTestData,
+                testData
+            );
+
+            return this._evaluateEncryptionResults(
+                decryptionWorks,
+                encryptionResults
+            );
+        } finally {
+            await this._withTimeout(
+                this.repository.deleteCredential(credential.id),
+                5000,
+                'Delete operation timed out'
+            );
+        }
+    }
+
+    /**
+     * Map test data format to Credential model format
+     * @param {Object} testData - Test data with testSecret, normalField, nestedSecret
+     * @returns {Object} Credential data structure
+     * @private
+     */
+    _mapTestDataToCredential(testData) {
+        // Note: Using camelCase for Prisma compatibility (both MongoDB and PostgreSQL)
+        // Changed from snake_case (user_id, entity_id) to camelCase (userId, externalId)
+        return {
+            externalId: 'test-encryption-entity',
+            data: {
+                access_token: testData.testSecret,      // Encrypted field
+                refresh_token: testData.nestedSecret?.value, // Encrypted field
+                domain: testData.normalField,           // Not encrypted
+            },
+        };
+    }
+
+    /**
+     * Map Credential model format to test data format
+     * @param {Object} credential - Credential from database
+     * @returns {Object} Test data format
+     * @private
+     */
+    _mapCredentialToTestData(credential) {
+        if (!credential) {
+            return null;
+        }
+
+        return {
+            id: credential.id,
+            testSecret: credential.data.access_token,
+            normalField: credential.data.domain,
+            nestedSecret: {
+                value: credential.data.refresh_token,
+            },
+        };
+    }
+
+    /**
+     * Map raw Credential data to test data format
+     * @param {Object} rawCredential - Raw credential from database
+     * @returns {Object} Test data format with raw encrypted values
+     * @private
+     */
+    _mapRawCredentialToTestData(rawCredential) {
+        if (!rawCredential) {
+            return null;
+        }
+
+        return {
+            testSecret: rawCredential.data?.access_token,
+            normalField: rawCredential.data?.domain,
+            nestedSecret: {
+                value: rawCredential.data?.refresh_token,
+            },
+        };
+    }
+
+    /**
+     * Verify that a document was decrypted correctly
+     * @param {Object} retrievedDoc - Document retrieved from database
+     * @param {Object} originalData - Original unencrypted data
+     * @returns {boolean} True if decryption worked correctly
+     * @private
+     */
+    _verifyDecryption(retrievedDoc, originalData) {
+        return (
+            retrievedDoc &&
+            retrievedDoc.testSecret === originalData.testSecret &&
+            retrievedDoc.normalField === originalData.normalField &&
+            retrievedDoc.nestedSecret?.value === originalData.nestedSecret.value
+        );
+    }
+
+    /**
+     * Verify that data was encrypted in the database
+     * Business rule: Encrypted fields should contain ':' and differ from original
+     * @param {Object} rawDoc - Raw document from database
+     * @param {Object} originalData - Original unencrypted data
+     * @returns {Object} Encryption verification results
+     * @private
+     */
+    _verifyEncryptionInDatabase(rawDoc, originalData) {
+        const secretIsEncrypted =
+            rawDoc &&
+            typeof rawDoc.testSecret === 'string' &&
+            rawDoc.testSecret.includes(':') &&
+            rawDoc.testSecret !== originalData.testSecret;
+
+        const nestedIsEncrypted =
+            rawDoc?.nestedSecret?.value &&
+            typeof rawDoc.nestedSecret.value === 'string' &&
+            rawDoc.nestedSecret.value.includes(':') &&
+            rawDoc.nestedSecret.value !== originalData.nestedSecret.value;
+
+        const normalNotEncrypted =
+            rawDoc && rawDoc.normalField === originalData.normalField;
+
+        return {
+            secretIsEncrypted,
+            nestedIsEncrypted,
+            normalNotEncrypted,
+        };
+    }
+
+    /**
+     * Evaluate encryption test results
+     * Business logic for determining if encryption is healthy
+     * @param {boolean} decryptionWorks - Whether decryption succeeded
+     * @param {Object} encryptionResults - Encryption verification results
+     * @returns {Object} Test status and result message
+     * @private
+     */
+    _evaluateEncryptionResults(decryptionWorks, encryptionResults) {
+        const { secretIsEncrypted, nestedIsEncrypted, normalNotEncrypted } =
+            encryptionResults;
+
+        if (
+            decryptionWorks &&
+            secretIsEncrypted &&
+            nestedIsEncrypted &&
+            normalNotEncrypted
+        ) {
+            return {
+                status: 'enabled',
+                testResult:
+                    'Encryption and decryption verified successfully',
+                encryptionWorks: true,
+            };
+        }
+
+        if (decryptionWorks && (!secretIsEncrypted || !nestedIsEncrypted)) {
+            return {
+                status: 'unhealthy',
+                testResult: 'Fields are not being encrypted in database',
+                encryptionWorks: false,
+            };
+        }
+
+        if (decryptionWorks && !normalNotEncrypted) {
+            return {
+                status: 'unhealthy',
+                testResult: 'Normal fields are being incorrectly encrypted',
+                encryptionWorks: false,
+            };
+        }
+
+        return {
+            status: 'unhealthy',
+            testResult: 'Decryption failed or data mismatch',
+            encryptionWorks: false,
+        };
+    }
+
+    /**
+     * Execute promise with timeout
+     * @param {Promise} promise - Promise to execute
+     * @param {number} ms - Timeout in milliseconds
+     * @param {string} errorMessage - Error message for timeout
+     * @returns {Promise} Promise that rejects on timeout
+     * @private
+     */
+    _withTimeout(promise, ms, errorMessage) {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) =>
+                setTimeout(() => reject(new Error(errorMessage)), ms)
+            ),
+        ]);
+    }
+}
+
+module.exports = { TestEncryptionUseCase };