@friggframework/core 2.0.0-next.12 → 2.0.0-next.120

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

@@ -0,0 +1,138 @@
+const {
+    HealthCheckRepositoryInterface,
+} = require('./health-check-repository-interface');
+const {
+    toObjectId,
+    fromObjectId,
+    findOne,
+    insertOne,
+    deleteOne,
+} = require('../documentdb-utils');
+const { DocumentDBEncryptionService } = require('../documentdb-encryption-service');
+
+class HealthCheckRepositoryDocumentDB extends HealthCheckRepositoryInterface {
+    /**
+     * @param {Object} params
+     * @param {Object} params.prismaClient - Prisma client instance
+     */
+    constructor({ prismaClient }) {
+        super();
+        this.prisma = prismaClient;
+        this.encryptionService = new DocumentDBEncryptionService();
+    }
+
+    /**
+     * @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,
+        };
+    }
+
+    /**
+     * @param {number} maxTimeMS
+     * @returns {Promise<number>} Response time in milliseconds
+     */
+    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) {
+        const now = new Date();
+        const document = {
+            ...credentialData,
+            createdAt: now,
+            updatedAt: now,
+        };
+
+        // Encrypt sensitive fields before insert
+        const encryptedDocument = await this.encryptionService.encryptFields(
+            'Credential',
+            document
+        );
+        const insertedId = await insertOne(this.prisma, 'Credential', encryptedDocument);
+        const created = await findOne(this.prisma, 'Credential', { _id: insertedId });
+
+        // Decrypt after read
+        const decrypted = await this.encryptionService.decryptFields(
+            'Credential',
+            created
+        );
+
+        return {
+            id: fromObjectId(decrypted._id),
+            ...decrypted,
+        };
+    }
+
+    async findCredentialById(id) {
+        const doc = await findOne(this.prisma, 'Credential', {
+            _id: toObjectId(id),
+        });
+
+        if (!doc) return null;
+
+        // Decrypt sensitive fields
+        const decrypted = await this.encryptionService.decryptFields('Credential', doc);
+
+        return {
+            id: fromObjectId(decrypted._id),
+            ...decrypted,
+        };
+    }
+
+    async getRawCredentialById(id) {
+        const objectId = toObjectId(id);
+        if (!objectId) return null;
+
+        const result = await this.prisma.$runCommandRaw({
+            find: 'Credential',
+            filter: { _id: objectId },
+        });
+
+        // Return raw document WITHOUT decryption
+        // This allows the test to verify that fields are actually encrypted in the database
+        return result?.cursor?.firstBatch?.[0] ?? null;
+    }
+
+    async deleteCredential(id) {
+        const objectId = toObjectId(id);
+        if (!objectId) return false;
+
+        const result = await deleteOne(this.prisma, 'Credential', { _id: objectId });
+        const deleted = result?.n ?? 0;
+        return deleted > 0;
+    }
+}
+
+module.exports = { HealthCheckRepositoryDocumentDB };
+

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

@@ -0,0 +1,48 @@
+const { HealthCheckRepositoryMongoDB } = require('./health-check-repository-mongodb');
+const { HealthCheckRepositoryPostgreSQL } = require('./health-check-repository-postgres');
+const { HealthCheckRepositoryDocumentDB } = require('./health-check-repository-documentdb');
+const config = require('../config');
+
+/**
+ * Factory function to create a health check repository for the configured database type.
+ * Requires explicit prismaClient injection to support IoC container patterns.
+ *
+ * @param {Object} options
+ * @param {Object} options.prismaClient - Prisma client instance (required for dependency injection)
+ * @returns {HealthCheckRepositoryInterface} Database-specific health check repository
+ * @throws {Error} If prismaClient is not provided
+ *
+ * @example
+ * const { prisma } = require('../prisma');
+ * const repository = createHealthCheckRepository({ prismaClient: prisma });
+ */
+function createHealthCheckRepository({ prismaClient } = {}) {
+    if (!prismaClient) {
+        throw new Error('prismaClient is required');
+    }
+
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new HealthCheckRepositoryMongoDB({ prismaClient });
+
+        case 'postgresql':
+            return new HealthCheckRepositoryPostgreSQL({ prismaClient });
+
+        case 'documentdb':
+            return new HealthCheckRepositoryDocumentDB({ prismaClient });
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createHealthCheckRepository,
+    HealthCheckRepositoryMongoDB,
+    HealthCheckRepositoryPostgreSQL,
+    HealthCheckRepositoryDocumentDB,
+};

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 /admin/db-migrate to initialize database';
+        }
+
+        // Add recommendation if migrations pending
+        if (!state.upToDate && state.pendingMigrations > 0) {
+            response.recommendation = `Run POST /admin/db-migrate to apply ${state.pendingMigrations} pending migration(s)`;
+        }
+
+        return response;
+    }
+}
+
+module.exports = {
+    CheckDatabaseStateUseCase,
+    ValidationError,
+};
+