@friggframework/core 2.0.0-next.8 → 2.0.0-next.80

package/database/repositories/health-check-repository-interface.js

@@ -0,0 +1,82 @@
+/**
+ * Health Check Repository Interface
+ * Abstract base class defining the contract for health check persistence adapters
+ *
+ * This follows the Port in Hexagonal Architecture:
+ * - Domain layer depends on this abstraction
+ * - Concrete adapters implement this interface
+ * - Use cases receive repositories via dependency injection
+ *
+ * Note: Currently, HealthCheckRepository has identical structure across MongoDB and PostgreSQL,
+ * so HealthCheckRepository serves both. This interface exists for consistency and
+ * future-proofing if database-specific implementations become needed.
+ *
+ * @abstract
+ */
+class HealthCheckRepositoryInterface {
+    /**
+     * @returns {Promise<{readyState: number, stateName: string, isConnected: boolean}>}
+     * @abstract
+     */
+    async getDatabaseConnectionState() {
+        throw new Error('Method getDatabaseConnectionState must be implemented by subclass');
+    }
+
+    /**
+     * Ping database to verify connectivity
+     *
+     * @param {number} maxTimeMS - Maximum time in milliseconds
+     * @returns {Promise<number>} Response time in milliseconds
+     * @abstract
+     */
+    async pingDatabase(maxTimeMS) {
+        throw new Error('Method pingDatabase must be implemented by subclass');
+    }
+
+    /**
+     * Persist an encrypted credential for health verification.
+     * Implementations should rely on Prisma so encryption middleware runs.
+     *
+     * @param {Object} credentialData
+     * @returns {Promise<Object>} Persisted credential
+     * @abstract
+     */
+    async createCredential(credentialData) {
+        throw new Error('Method createCredential must be implemented by subclass');
+    }
+
+    /**
+     * Retrieve credential by ID using Prisma (decrypted).
+     *
+     * @param {string} id
+     * @returns {Promise<Object|null>}
+     * @abstract
+     */
+    async findCredentialById(id) {
+        throw new Error('Method findCredentialById must be implemented by subclass');
+    }
+
+    /**
+     * Fetch raw credential document from the database (without decryption).
+     *
+     * @param {string} id
+     * @returns {Promise<Object|null>}
+     * @abstract
+     */
+    async getRawCredentialById(id) {
+        throw new Error('Method getRawCredentialById must be implemented by subclass');
+    }
+
+    /**
+     * Delete credential by ID.
+     *
+     * @param {string} id
+     * @returns {Promise<void>}
+     * @abstract
+     */
+    async deleteCredential(id) {
+        throw new Error('Method deleteCredential must be implemented by subclass');
+    }
+}
+
+module.exports = { HealthCheckRepositoryInterface };

package/database/repositories/health-check-repository-mongodb.js

@@ -0,0 +1,89 @@
+const {
+    HealthCheckRepositoryInterface,
+} = require('./health-check-repository-interface');
+
+class HealthCheckRepositoryMongoDB extends HealthCheckRepositoryInterface {
+    /**
+     * @param {Object} params
+     * @param {Object} params.prismaClient - Prisma client instance
+     */
+    constructor({ prismaClient }) {
+        super();
+        this.prisma = prismaClient;
+    }
+
+    /**
+     * @returns {Promise<{readyState: number, stateName: string, isConnected: boolean}>}
+     */
+    async getDatabaseConnectionState() {
+        let isConnected = false;
+        let stateName = 'unknown';
+
+        try {
+            await this.prisma.$runCommandRaw({ ping: 1 });
+            isConnected = true;
+            stateName = 'connected';
+        } catch (error) {
+            stateName = 'disconnected';
+        }
+
+        return {
+            readyState: isConnected ? 1 : 0,
+            stateName,
+            isConnected,
+        };
+    }
+
+    async pingDatabase(maxTimeMS = 2000) {
+        const pingStart = Date.now();
+        let timeoutId;
+
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error('Database ping timeout')), maxTimeMS);
+        });
+
+        try {
+            await Promise.race([
+                this.prisma.$runCommandRaw({ ping: 1 }),
+                timeoutPromise
+            ]);
+            return Date.now() - pingStart;
+        } finally {
+            clearTimeout(timeoutId);
+        }
+    }
+
+    async createCredential(credentialData) {
+        return await this.prisma.credential.create({
+            data: credentialData,
+        });
+    }
+
+    async findCredentialById(id) {
+        return await this.prisma.credential.findUnique({
+            where: { id },
+        });
+    }
+
+    /**
+     * Get raw credential from database bypassing Prisma encryption extension.
+     * Uses findRaw() to query MongoDB directly.
+     * @param {string} id
+     * @returns {Promise<Object|null>}
+     */
+    async getRawCredentialById(id) {
+        if (!id) return null;
+        const results = await this.prisma.credential.findRaw({
+            filter: { _id: { $oid: id } },
+        });
+        return results[0] || null;
+    }
+
+    async deleteCredential(id) {
+        await this.prisma.credential.delete({
+            where: { id },
+        });
+    }
+}
+
+module.exports = { HealthCheckRepositoryMongoDB };

package/database/repositories/health-check-repository-postgres.js

@@ -0,0 +1,82 @@
+const {
+    HealthCheckRepositoryInterface,
+} = require('./health-check-repository-interface');
+
+class HealthCheckRepositoryPostgreSQL extends HealthCheckRepositoryInterface {
+    /**
+     * @param {Object} params
+     * @param {Object} params.prismaClient - Prisma client instance
+     */
+    constructor({ prismaClient }) {
+        super();
+        this.prisma = prismaClient;
+    }
+
+    /**
+     * @returns {Promise<{readyState: number, stateName: string, isConnected: boolean}>}
+     */
+    async getDatabaseConnectionState() {
+        let isConnected = false;
+        let stateName = 'unknown';
+        
+        try {
+            await this.prisma.$queryRaw`SELECT 1`;
+            isConnected = true;
+            stateName = 'connected';
+        } catch (error) {
+            stateName = 'disconnected';
+        }
+
+        return {
+            readyState: isConnected ? 1 : 0,
+            stateName,
+            isConnected,
+        };
+    }
+
+    /**
+     * @param {number} maxTimeMS
+     * @returns {Promise<number>} Response time in milliseconds
+     */
+    async pingDatabase(maxTimeMS = 2000) {
+        const pingStart = Date.now();
+        await this.prisma.$queryRaw`SELECT 1`;
+        return Date.now() - pingStart;
+    }
+
+    async createCredential(credentialData) {
+        return await this.prisma.credential.create({
+            data: credentialData,
+        });
+    }
+
+    async findCredentialById(id) {
+        return await this.prisma.credential.findUnique({
+            where: { id },
+        });
+    }
+
+    /**
+     * @param {string} id
+     * @returns {Promise<Object|null>}
+     */
+    async getRawCredentialById(id) {
+        const results = await this.prisma.$queryRaw`
+            SELECT * FROM "Credential" WHERE id = ${id}
+        `;
+
+        if (!results || results.length === 0) {
+            return null;
+        }
+
+        return results[0];
+    }
+
+    async deleteCredential(id) {
+        await this.prisma.credential.delete({
+            where: { id },
+        });
+    }
+}
+
+module.exports = { HealthCheckRepositoryPostgreSQL };

package/database/repositories/migration-status-repository-s3.js

@@ -0,0 +1,137 @@
+/**
+ * Migration Status Repository - S3 Storage
+ * 
+ * Infrastructure Layer - Hexagonal Architecture
+ * 
+ * Stores migration status in S3 to avoid chicken-and-egg dependency on User/Process tables.
+ * Initial database migrations can't use Process table (requires User FK which doesn't exist yet).
+ */
+
+const { S3Client, PutObjectCommand, GetObjectCommand } = require('@aws-sdk/client-s3');
+const { randomUUID } = require('crypto');
+
+class MigrationStatusRepositoryS3 {
+    /**
+     * @param {string} bucketName - S3 bucket name for migration status storage
+     * @param {S3Client} s3Client - Optional S3 client (for testing)
+     */
+    constructor(bucketName, s3Client = null) {
+        this.bucketName = bucketName;
+        this.s3Client = s3Client || new S3Client({ region: process.env.AWS_REGION || 'us-east-1' });
+    }
+
+    /**
+     * Build S3 key for migration status
+     * @param {string} migrationId - Migration identifier
+     * @param {string} stage - Deployment stage
+     * @returns {string} S3 key
+     */
+    _buildS3Key(migrationId, stage) {
+        return `migrations/${stage}/${migrationId}.json`;
+    }
+
+    /**
+     * Create new migration status record
+     * @param {Object} data - Migration data
+     * @param {string} [data.migrationId] - Migration ID (generates UUID if not provided)
+     * @param {string} data.stage - Deployment stage
+     * @param {string} [data.triggeredBy] - User or system that triggered migration
+     * @param {string} [data.triggeredAt] - ISO timestamp
+     * @returns {Promise<Object>} Created migration status
+     */
+    async create(data) {
+        const migrationId = data.migrationId || randomUUID();
+        const timestamp = data.triggeredAt || new Date().toISOString();
+
+        const status = {
+            migrationId,
+            stage: data.stage,
+            state: 'INITIALIZING',
+            progress: 0,
+            triggeredBy: data.triggeredBy || 'system',
+            triggeredAt: timestamp,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+
+        const key = this._buildS3Key(migrationId, data.stage);
+
+        await this.s3Client.send(
+            new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(status, null, 2),
+                ContentType: 'application/json',
+            })
+        );
+
+        return status;
+    }
+
+    /**
+     * Update existing migration status
+     * @param {Object} data - Update data
+     * @param {string} data.migrationId - Migration ID
+     * @param {string} data.stage - Deployment stage
+     * @param {string} [data.state] - New state
+     * @param {number} [data.progress] - Progress percentage (0-100)
+     * @param {string} [data.error] - Error message if failed
+     * @param {string} [data.completedAt] - Completion timestamp
+     * @returns {Promise<Object>} Updated migration status
+     */
+    async update(data) {
+        const key = this._buildS3Key(data.migrationId, data.stage);
+
+        // Get existing status
+        const existing = await this.get(data.migrationId, data.stage);
+
+        // Merge updates
+        const updated = {
+            ...existing,
+            ...data,
+            updatedAt: new Date().toISOString(),
+        };
+
+        await this.s3Client.send(
+            new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(updated, null, 2),
+                ContentType: 'application/json',
+            })
+        );
+
+        return updated;
+    }
+
+    /**
+     * Get migration status by ID
+     * @param {string} migrationId - Migration ID
+     * @param {string} stage - Deployment stage
+     * @returns {Promise<Object>} Migration status
+     * @throws {Error} If migration not found
+     */
+    async get(migrationId, stage) {
+        const key = this._buildS3Key(migrationId, stage);
+
+        try {
+            const response = await this.s3Client.send(
+                new GetObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: key,
+                })
+            );
+
+            const body = await response.Body.transformToString();
+            return JSON.parse(body);
+        } catch (error) {
+            if (error.name === 'NoSuchKey') {
+                throw new Error(`Migration not found: ${migrationId}`);
+            }
+            throw error;
+        }
+    }
+}
+
+module.exports = { MigrationStatusRepositoryS3 };
+

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

@@ -0,0 +1,29 @@
+class CheckDatabaseHealthUseCase {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/health-check-repository-interface').HealthCheckRepositoryInterface} params.healthCheckRepository
+     */
+    constructor({ healthCheckRepository }) {
+        this.repository = healthCheckRepository;
+    }
+
+    /**
+     * @returns {Promise<{status: string, state: string, responseTime?: number}>}
+     */
+    async execute() {
+        const { stateName, isConnected } = await this.repository.getDatabaseConnectionState();
+
+        const result = {
+            status: isConnected ? 'healthy' : 'unhealthy',
+            state: stateName,
+        };
+
+        if (isConnected) {
+            result.responseTime = await this.repository.pingDatabase(2000);
+        }
+
+        return result;
+    }
+}
+
+module.exports = { CheckDatabaseHealthUseCase };

package/database/use-cases/check-database-state-use-case.js

@@ -0,0 +1,81 @@
+/**
+ * Check Database State Use Case
+ * 
+ * Domain logic for checking database state (pending migrations, errors, etc).
+ * Does NOT trigger migrations, just reports current state.
+ * 
+ * Architecture: Hexagonal/Clean
+ * - Use Case (Domain Layer)
+ * - Depends on prismaRunner (Infrastructure abstraction)
+ * - Called by Router or other Use Cases (Adapter Layer)
+ */
+
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+class CheckDatabaseStateUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.prismaRunner - Prisma runner utility
+     */
+    constructor({ prismaRunner }) {
+        if (!prismaRunner) {
+            throw new Error('prismaRunner dependency is required');
+        }
+        this.prismaRunner = prismaRunner;
+    }
+
+    /**
+     * Execute check migration status
+     * 
+     * @param {string} dbType - Database type (postgresql, mongodb, or documentdb)
+     * @param {string} stage - Deployment stage (default: 'production')
+     * @returns {Promise<Object>} Migration status
+     */
+    async execute(dbType, stage = 'production') {
+        // Validate inputs
+        if (!dbType) {
+            throw new ValidationError('dbType is required');
+        }
+
+        if (!['postgresql', 'mongodb', 'documentdb'].includes(dbType)) {
+            throw new ValidationError('dbType must be postgresql, mongodb, or documentdb');
+        }
+
+        console.log(`Checking migration status for ${dbType} in ${stage}`);
+
+        // Check database state using Prisma
+        const state = await this.prismaRunner.checkDatabaseState(dbType);
+
+        // Build response
+        const response = {
+            upToDate: state.upToDate,
+            pendingMigrations: state.pendingMigrations || 0,
+            dbType,
+            stage,
+        };
+
+        // Add error if present
+        if (state.error) {
+            response.error = state.error;
+            response.recommendation = 'Run POST /db-migrate to initialize database';
+        }
+
+        // Add recommendation if migrations pending
+        if (!state.upToDate && state.pendingMigrations > 0) {
+            response.recommendation = `Run POST /db-migrate to apply ${state.pendingMigrations} pending migration(s)`;
+        }
+
+        return response;
+    }
+}
+
+module.exports = {
+    CheckDatabaseStateUseCase,
+    ValidationError,
+};
+

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 };
+
+