@friggframework/core 2.0.0--canary.395.0e9373c.0 → 2.0.0--canary.395.2718e67.0

package/database/health-check-repository.js

@@ -0,0 +1,117 @@
+const { mongoose } = require('./mongoose');
+
+/**
+ * Repository for Health Check database operations.
+ * Provides atomic database operations for health testing.
+ *
+ * Follows DDD/Hexagonal Architecture:
+ * - Infrastructure Layer (this repository)
+ * - Pure database operations only, no business logic
+ * - Used by Application Layer (Use Cases)
+ */
+class HealthCheckRepository {
+    /**
+     * Get database connection state
+     * @returns {Object} Object with readyState, stateName, and isConnected
+     */
+    getDatabaseConnectionState() {
+        const stateMap = {
+            0: 'disconnected',
+            1: 'connected',
+            2: 'connecting',
+            3: 'disconnecting',
+        };
+        const readyState = mongoose.connection.readyState;
+
+        return {
+            readyState,
+            stateName: stateMap[readyState],
+            isConnected: readyState === 1,
+        };
+    }
+
+    /**
+     * Ping the database to verify connectivity
+     * @param {number} maxTimeMS - Maximum time to wait for ping response
+     * @returns {Promise<number>} Response time in milliseconds
+     * @throws {Error} If database is not connected or ping fails
+     */
+    async pingDatabase(maxTimeMS = 2000) {
+        const pingStart = Date.now();
+        await mongoose.connection.db.admin().ping({ maxTimeMS });
+        return Date.now() - pingStart;
+    }
+
+    /**
+     * Create a test encryption model
+     * @returns {Model} Mongoose model with encryption plugin
+     */
+    createEncryptionTestModel() {
+        const { Encrypt } = require('../encrypt');
+
+        const testSchema = new mongoose.Schema(
+            {
+                testSecret: { type: String, lhEncrypt: true },
+                normalField: { type: String },
+                nestedSecret: {
+                    value: { type: String, lhEncrypt: true },
+                },
+            },
+            { timestamps: false }
+        );
+
+        testSchema.plugin(Encrypt);
+
+        return (
+            mongoose.models.TestEncryption ||
+            mongoose.model('TestEncryption', testSchema)
+        );
+    }
+
+    /**
+     * Save a test document to the database
+     * @param {Model} TestModel - Mongoose model
+     * @param {Object} data - Data to save
+     * @returns {Promise<Document>} Saved document
+     */
+    async saveTestDocument(TestModel, data) {
+        const testDoc = new TestModel(data);
+        await testDoc.save();
+        return testDoc;
+    }
+
+    /**
+     * Find a test document by ID
+     * @param {Model} TestModel - Mongoose model
+     * @param {string} id - Document ID
+     * @returns {Promise<Document>} Found document
+     */
+    async findTestDocumentById(TestModel, id) {
+        return await TestModel.findById(id);
+    }
+
+    /**
+     * Get raw document from collection (bypassing Mongoose)
+     * Used for verifying encryption at the database level
+     * @param {string} collectionName - Collection name
+     * @param {Object} filter - Query filter
+     * @returns {Promise<Object>} Raw document from database
+     */
+    async getRawDocumentFromCollection(collectionName, filter) {
+        return await mongoose.connection.db
+            .collection(collectionName)
+            .findOne(filter);
+    }
+
+    /**
+     * Delete a test document
+     * @param {Model} TestModel - Mongoose model
+     * @param {string} id - Document ID
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteTestDocument(TestModel, id) {
+        return await TestModel.deleteOne({ _id: id });
+    }
+}
+
+module.exports = { HealthCheckRepository };

package/database/token-repository.js

@@ -0,0 +1,105 @@
+const { Token } = require('./models/Token');
+
+/**
+ * Repository for Token operations.
+ * Handles persistence of authentication tokens.
+ */
+class TokenRepository {
+    /**
+     * Create a token with expiration
+     * @param {string} userId - The user ID
+     * @param {string} rawToken - The raw (unhashed) token string
+     * @param {number} minutes - Minutes until expiration
+     * @returns {Promise<Object>} The created token record
+     */
+    async createTokenWithExpire(userId, rawToken, minutes) {
+        return await Token.createTokenWithExpire(userId, rawToken, minutes);
+    }
+
+    /**
+     * Validate and retrieve token from JSON token object
+     * @param {Object} tokenObj - Object with id and token properties
+     * @returns {Promise<Object>} The validated token record
+     * @throws {Error} If token is invalid, expired, or doesn't exist
+     */
+    async validateAndGetToken(tokenObj) {
+        return await Token.validateAndGetTokenFromJSONToken(tokenObj);
+    }
+
+    /**
+     * Find a token by ID
+     * @param {string} tokenId - The token ID
+     * @returns {Promise<Object|null>} The token record or null
+     */
+    async findTokenById(tokenId) {
+        return await Token.findById(tokenId);
+    }
+
+    /**
+     * Find tokens by user ID
+     * @param {string} userId - The user ID
+     * @returns {Promise<Array>} Array of token records
+     */
+    async findTokensByUserId(userId) {
+        return await Token.find({ user: userId });
+    }
+
+    /**
+     * Delete a token by ID
+     * @param {string} tokenId - The token ID
+     * @returns {Promise<Object>} The deletion result
+     */
+    async deleteToken(tokenId) {
+        return await Token.deleteOne({ _id: tokenId });
+    }
+
+    /**
+     * Delete expired tokens
+     * @returns {Promise<Object>} The deletion result with count
+     */
+    async deleteExpiredTokens() {
+        return await Token.deleteMany({
+            expires: { $lt: new Date() },
+        });
+    }
+
+    /**
+     * Delete all tokens for a user
+     * @param {string} userId - The user ID
+     * @returns {Promise<Object>} The deletion result
+     */
+    async deleteTokensByUserId(userId) {
+        return await Token.deleteMany({ user: userId });
+    }
+
+    /**
+     * Create JSON token string from token object and raw token
+     * @param {Object} token - The token record
+     * @param {string} rawToken - The raw token string
+     * @returns {string} JSON string with id and token
+     */
+    createJSONToken(token, rawToken) {
+        return Token.createJSONToken(token, rawToken);
+    }
+
+    /**
+     * Create base64 encoded buffer token
+     * @param {Object} token - The token record
+     * @param {string} rawToken - The raw token string
+     * @returns {string} Base64 encoded token
+     */
+    createBase64BufferToken(token, rawToken) {
+        return Token.createBase64BufferToken(token, rawToken);
+    }
+
+    /**
+     * Parse JSON token from base64 buffer
+     * @param {string} buffer - Base64 encoded token string
+     * @returns {Object} Parsed token object with id and token
+     */
+    getJSONTokenFromBase64BufferToken(buffer) {
+        return Token.getJSONTokenFromBase64BufferToken(buffer);
+    }
+}
+
+module.exports = { TokenRepository };

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

@@ -0,0 +1,34 @@
+/**
+ * Use Case for checking database health.
+ * Contains business logic for determining database connectivity and health status.
+ */
+class CheckDatabaseHealthUseCase {
+    /**
+     * @param {Object} params
+     * @param {import('../health-check-repository').HealthCheckRepository} params.healthCheckRepository
+     */
+    constructor({ healthCheckRepository }) {
+        this.repository = healthCheckRepository;
+    }
+
+    /**
+     * Execute database health check
+     * @returns {Promise<Object>} Health check result with status, state, and response time
+     */
+    async execute() {
+        const { stateName, isConnected } = 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/test-encryption-use-case.js

@@ -0,0 +1,193 @@
+/**
+ * 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').HealthCheckRepository} params.healthCheckRepository
+     */
+    constructor({ healthCheckRepository }) {
+        this.repository = healthCheckRepository;
+    }
+
+    /**
+     * Execute encryption test
+     * Orchestrates the full encryption test workflow
+     * @returns {Promise<Object>} Test results with status and details
+     */
+    async execute() {
+        const TestModel = this.repository.createEncryptionTestModel();
+
+        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 testDoc = await this._withTimeout(
+            this.repository.saveTestDocument(TestModel, testData),
+            5000,
+            'Save operation timed out'
+        );
+
+        try {
+            const retrievedDoc = await this._withTimeout(
+                this.repository.findTestDocumentById(TestModel, testDoc._id),
+                5000,
+                'Find operation timed out'
+            );
+
+            const decryptionWorks = this._verifyDecryption(
+                retrievedDoc,
+                testData
+            );
+
+            const rawDoc = await this._withTimeout(
+                this.repository.getRawDocumentFromCollection(
+                    TestModel.collection.name,
+                    { _id: testDoc._id }
+                ),
+                5000,
+                'Database verification timed out'
+            );
+
+            const encryptionResults = this._verifyEncryptionInDatabase(
+                rawDoc,
+                testData
+            );
+
+            return this._evaluateEncryptionResults(
+                decryptionWorks,
+                encryptionResults
+            );
+        } finally {
+            await this._withTimeout(
+                this.repository.deleteTestDocument(TestModel, testDoc._id),
+                5000,
+                'Delete operation timed out'
+            );
+        }
+    }
+
+    /**
+     * 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 };

package/database/websocket-connection-repository.js

@@ -0,0 +1,44 @@
+const { WebsocketConnection } = require('./models/WebsocketConnection');
+
+/**
+ * Repository for WebSocket connection operations.
+ * Handles persistence of active WebSocket connections.
+ */
+class WebsocketConnectionRepository {
+    /**
+     * Create a new WebSocket connection record
+     * @param {string} connectionId - The WebSocket connection ID
+     * @returns {Promise<Object>} The created connection record
+     */
+    async createConnection(connectionId) {
+        return await WebsocketConnection.create({ connectionId });
+    }
+
+    /**
+     * Delete a WebSocket connection record
+     * @param {string} connectionId - The WebSocket connection ID to delete
+     * @returns {Promise<Object>} The deletion result
+     */
+    async deleteConnection(connectionId) {
+        return await WebsocketConnection.deleteOne({ connectionId });
+    }
+
+    /**
+     * Get all active WebSocket connections
+     * @returns {Promise<Array>} Array of active connection objects with send capability
+     */
+    async getActiveConnections() {
+        return await WebsocketConnection.getActiveConnections();
+    }
+
+    /**
+     * Find a connection by ID
+     * @param {string} connectionId - The WebSocket connection ID
+     * @returns {Promise<Object|null>} The connection record or null
+     */
+    async findConnection(connectionId) {
+        return await WebsocketConnection.findOne({ connectionId });
+    }
+}
+
+module.exports = { WebsocketConnectionRepository };

package/handlers/routers/HEALTHCHECK.md

@@ -237,4 +237,106 @@ await mongoose.connection.db.admin().ping({ maxTimeMS: 2000 });
 
 ## Environment Variables
 
-- `HEALTH_API_KEY`: Required API key for accessing detailed health endpoints
+- `HEALTH_API_KEY`: Required API key for accessing detailed health endpoints
+
+## TODO: DDD/Hexagonal Architecture Refactoring
+
+### Current Architecture Issues
+
+The health router (health.js, 677 lines) currently violates DDD/Hexagonal Architecture principles:
+
+**✅ What's Good:**
+- Database access properly abstracted through `HealthCheckRepository`
+- `CheckDatabaseHealthUseCase` and `TestEncryptionUseCase` correctly implement use case pattern
+- All tests passing, no breaking changes
+
+**❌ Architecture Violations:**
+1. **Handler contains significant business logic** - Functions like `getEncryptionConfiguration()`, `checkEncryptionHealth()`, `checkKmsDecryptCapability()`, `detectVpcConfiguration()`, `checkExternalAPIs()`, and `checkIntegrations()` contain business logic that should be in use cases
+2. **Direct infrastructure dependencies** - Handler directly uses `https`, `http`, Node.js `dns`, and factory modules instead of accessing through repositories
+3. **Mixed concerns** - Single file handles HTTP routing, business logic, infrastructure detection, and response formatting
+4. **Violates dependency rule** - Handler should only call use cases, never repositories or contain business logic
+
+### Proposed Refactoring Plan
+
+#### Priority 1: Extract Core Health Check Use Cases (Immediate)
+
+**New Use Cases:**
+1. `CheckEncryptionHealthUseCase` - Orchestrate encryption testing with configuration checks (from health.js:122-181)
+2. `CheckKmsConnectivityUseCase` - Test KMS decrypt capability (from health.js:339-490)
+3. `DetectNetworkConfigurationUseCase` - VPC and network detection (from health.js:244-336)
+
+**New Repositories:**
+1. `EncryptionConfigRepository` - Get encryption mode, bypass rules (from health.js:98-120)
+2. `KmsRepository` - KMS connectivity testing, decrypt capability checks
+3. `NetworkRepository` - DNS resolution, VPC detection, TCP connectivity tests
+
+#### Priority 2: Extract External Service Checks
+
+**New Use Cases:**
+4. `CheckExternalServicesUseCase` - Check external API availability (from health.js:183-209)
+
+**New Repositories:**
+4. `ExternalServiceRepository` - HTTP-based service health checking with timeout handling
+
+#### Priority 3: Extract Integration Checks
+
+**New Use Cases:**
+5. `CheckIntegrationAvailabilityUseCase` - Verify integrations and modules loaded (from health.js:211-231)
+
+**Extend Existing:**
+- Add `getAvailableIntegrations()` and `getAvailableModules()` methods to existing `IntegrationRepository`
+
+### Architectural Principles to Follow
+
+**The Handler Should Only:**
+- Define routes
+- Call use cases
+- Map use case results to HTTP responses
+- Handle HTTP-specific concerns (status codes, headers)
+
+**The Rule:**
+> "Handlers (adapters) should only call use cases, never repositories or business logic directly"
+
+**Dependency Direction:**
+```
+Handler (Adapter Layer)
+  ↓ calls
+Use Cases (Application Layer)
+  ↓ calls
+Repositories (Infrastructure Layer)
+  ↓ calls
+External Systems (Database, APIs, AWS Services)
+```
+
+### Expected Outcome
+
+- Reduce health.js from **677 lines to ~100-150 lines**
+- All business logic moved to use cases
+- All infrastructure access moved to repositories
+- Handler becomes thin HTTP adapter
+- Improved testability (use cases testable without HTTP context)
+- Better reusability (use cases usable in CLI tools, background jobs, etc.)
+
+### Implementation Status
+
+- [ ] P1: Extract `CheckEncryptionHealthUseCase`
+- [ ] P1: Create `EncryptionConfigRepository`
+- [ ] P1: Extract `CheckKmsConnectivityUseCase`
+- [ ] P1: Create `KmsRepository`
+- [ ] P1: Extract `DetectNetworkConfigurationUseCase`
+- [ ] P1: Create `NetworkRepository`
+- [ ] P2: Extract `CheckExternalServicesUseCase`
+- [ ] P2: Create `ExternalServiceRepository`
+- [ ] P3: Extract `CheckIntegrationAvailabilityUseCase`
+- [ ] P3: Extend existing `IntegrationRepository`
+
+### Future Considerations (Optional)
+
+**Domain Models (Value Objects):**
+- `HealthCheckResult` - Overall health check result with status, checks, timestamp
+- `DatabaseHealth` - Database-specific health information
+- `EncryptionHealth` - Encryption-specific health information
+- `ServiceHealth` - Generic external service health
+- `NetworkConfiguration` - VPC and network detection results
+
+These would replace plain objects and provide type safety and business logic encapsulation.