@friggframework/core 2.0.0-next.25 → 2.0.0-next.27

package/encrypt/encrypt.js

@@ -16,28 +16,18 @@ const findOneEvents = [
 
 const shouldBypassEncryption = (STAGE) => {
     const defaultBypassStages = ['dev', 'test', 'local'];
-    const bypassStageEnv = process.env.BYPASS_ENCRYPTION_STAGE;
-    // If the env is set to anything or an empty string, use the env. Otherwise, use the default array
-    const useEnv = !String(bypassStageEnv) || !!bypassStageEnv;
-    const bypassStages = useEnv
-        ? bypassStageEnv.split(',').map((stage) => stage.trim())
-        : defaultBypassStages;
-    return bypassStages.includes(STAGE);
+    return defaultBypassStages.includes(STAGE);
 };
 
-// The Mongoose plug-in function
-function Encrypt(schema, options) {
+function Encrypt(schema) {
     const { STAGE, KMS_KEY_ARN, AES_KEY_ID } = process.env;
 
     if (shouldBypassEncryption(STAGE)) {
         return;
     }
 
-    if (KMS_KEY_ARN && AES_KEY_ID) {
-        throw new Error(
-            'Local and AWS encryption keys are both set in the environment.'
-        );
-    }
+    const hasAES = AES_KEY_ID && AES_KEY_ID.trim() !== '';
+    const hasKMS = KMS_KEY_ARN && KMS_KEY_ARN.trim() !== '' && !hasAES;
 
     const fields = Object.values(schema.paths)
         .map(({ path, options }) => (options.lhEncrypt === true ? path : ''))
@@ -48,25 +38,17 @@ function Encrypt(schema, options) {
     }
 
     const cryptor = new Cryptor({
-        // Use AWS if the CMK is present
-        shouldUseAws: !!KMS_KEY_ARN,
-        // Find all the fields in the schema with lhEncrypt === true
+        shouldUseAws: hasKMS,
         fields: fields,
     });
 
-    // ---------------------------------------------
-    // ### Encrypt fields before save/update/insert.
-    // ---------------------------------------------
-
     schema.pre('save', async function encryptionPreSave() {
-        // `this` will be a doc
         await cryptor.encryptFieldsInDocuments([this]);
     });
 
     schema.pre(
         'insertMany',
         async function encryptionPreInsertMany(_, docs, options) {
-            // `this` will be the model
             if (options?.rawResult) {
                 throw new Error(
                     'Raw result not supported for insertMany with Encrypt plugin'
@@ -78,17 +60,14 @@ function Encrypt(schema, options) {
     );
 
     schema.pre(updateOneEvents, async function encryptionPreUpdateOne() {
-        // `this` will be a query
         await cryptor.encryptFieldsInQuery(this);
     });
 
     schema.pre('updateMany', async function encryptionPreUpdateMany() {
-        // `this` will be a query
         cryptor.expectNotToUpdateManyEncrypted(this.getUpdate());
     });
 
     schema.pre('update', async function encryptionPreUpdate() {
-        // `this` will be a query
         const { multiple } = this.getOptions();
 
         if (multiple) {
@@ -99,16 +78,11 @@ function Encrypt(schema, options) {
         await cryptor.encryptFieldsInQuery(this);
     });
 
-    // --------------------------------------------
-    // ### Decrypt documents after they are loaded.
-    // --------------------------------------------
     schema.post('save', async function encryptionPreSave() {
-        // `this` will be a doc
         await cryptor.decryptFieldsInDocuments([this]);
     });
 
     schema.post(findOneEvents, async function encryptionPostFindOne(doc) {
-        // `this` will be a query
         const { rawResult } = this.getOptions();
 
         if (rawResult) {
@@ -119,12 +93,10 @@ function Encrypt(schema, options) {
     });
 
     schema.post('find', async function encryptionPostFind(docs) {
-        // `this` will be a query
         await cryptor.decryptFieldsInDocuments(docs);
     });
 
     schema.post('insertMany', async function encryptionPostInsertMany(docs) {
-        // `this` will be the model
         await cryptor.decryptFieldsInDocuments(docs);
     });
 }

package/handlers/routers/HEALTHCHECK.md

@@ -0,0 +1,240 @@
+# Frigg Healthcheck Endpoint Documentation
+
+## Overview
+
+The Frigg service includes comprehensive healthcheck endpoints to monitor service health, connectivity, and readiness. These endpoints follow industry best practices and are designed for use with monitoring systems, load balancers, and container orchestration platforms.
+
+## Endpoints
+
+### 1. Basic Health Check
+**GET** `/health`
+
+Simple health check endpoint that returns basic service information. No authentication required. This endpoint is rate-limited at the API Gateway level.
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "timestamp": "2024-01-10T12:00:00.000Z",
+  "service": "frigg-core-api"
+}
+```
+
+**Status Codes:**
+- `200 OK` - Service is running
+
+### 2. Detailed Health Check
+**GET** `/health/detailed`
+
+Comprehensive health check that tests all service components and dependencies.
+
+**Authentication Required:**
+- Header: `x-api-key: YOUR_API_KEY`
+- The API key must match the `HEALTH_API_KEY` environment variable
+
+**Response:**
+```json
+{
+  "service": "frigg-core-api",
+  "status": "healthy",  // "healthy" or "unhealthy"
+  "timestamp": "2024-01-10T12:00:00.000Z",
+  "checks": {
+    "database": {
+      "status": "healthy",
+      "state": "connected",
+      "responseTime": 5  // milliseconds
+    },
+    "externalApis": {
+      "github": {
+        "status": "healthy",
+        "statusCode": 200,
+        "responseTime": 150,
+        "reachable": true
+      },
+      "npm": {
+        "status": "healthy",
+        "statusCode": 200,
+        "responseTime": 200,
+        "reachable": true
+      }
+    },
+    "integrations": {
+      "status": "healthy",
+      "modules": {
+        "count": 10,
+        "available": ["module1", "module2", "..."]
+      },
+      "integrations": {
+        "count": 5,
+        "available": ["integration1", "integration2", "..."]
+      }
+    }
+  },
+  "responseTime": 250  // total endpoint response time in milliseconds
+}
+```
+
+**Status Codes:**
+- `200 OK` - Service is healthy (all components operational)
+- `503 Service Unavailable` - Service is unhealthy (any component failure)
+- `401 Unauthorized` - Missing or invalid x-api-key header
+
+### 3. Liveness Probe
+**GET** `/health/live`
+
+Kubernetes-style liveness probe. Returns whether the service process is alive.
+
+**Authentication Required:**
+- Header: `x-api-key: YOUR_API_KEY`
+
+**Response:**
+```json
+{
+  "status": "alive",
+  "timestamp": "2024-01-10T12:00:00.000Z"
+}
+```
+
+**Status Codes:**
+- `200 OK` - Service process is alive
+
+### 4. Readiness Probe
+**GET** `/health/ready`
+
+Kubernetes-style readiness probe. Returns whether the service is ready to receive traffic.
+
+**Authentication Required:**
+- Header: `x-api-key: YOUR_API_KEY`
+
+**Response:**
+```json
+{
+  "ready": true,
+  "timestamp": "2024-01-10T12:00:00.000Z",
+  "checks": {
+    "database": true,
+    "modules": true
+  }
+}
+```
+
+**Status Codes:**
+- `200 OK` - Service is ready
+- `503 Service Unavailable` - Service is not ready
+
+## Health Status Definitions
+
+- **healthy**: All components are functioning normally
+- **unhealthy**: Any component is failing, service may not function properly
+
+## Component Checks
+
+### Database Connectivity
+- Checks database connection state
+- Performs ping test with 2-second timeout if connected
+- Reports connection state and response time
+- Database type is not exposed for security reasons
+
+### External API Connectivity
+- Tests connectivity to external services (GitHub, npm registry)
+- Configurable timeout (default: 5 seconds)
+- Reports reachability and response times
+- Uses Promise.all for parallel checking
+
+### Integration Status
+- Verifies available modules and integrations are loaded
+- Reports counts and lists of available components
+
+## Usage Examples
+
+### Monitoring Systems
+Configure your monitoring system to poll `/health/detailed` every 30-60 seconds:
+```bash
+curl -H "x-api-key: YOUR_API_KEY" https://your-frigg-instance.com/health/detailed
+```
+
+### Load Balancer Health Checks
+Configure load balancers to use the simple `/health` endpoint:
+```bash
+curl https://your-frigg-instance.com/health
+```
+
+### Kubernetes Configuration
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health/live
+    port: 8080
+    httpHeaders:
+    - name: x-api-key
+      value: YOUR_API_KEY
+  periodSeconds: 10
+  timeoutSeconds: 5
+
+readinessProbe:
+  httpGet:
+    path: /health/ready
+    port: 8080
+    httpHeaders:
+    - name: x-api-key
+      value: YOUR_API_KEY
+  initialDelaySeconds: 30
+  periodSeconds: 10
+```
+
+## Customization
+
+### Adding External API Checks
+To add more external API checks, modify the `externalAPIs` array in the health router:
+```javascript
+const externalAPIs = [
+    { name: 'github', url: 'https://api.github.com/status' },
+    { name: 'npm', url: 'https://registry.npmjs.org' },
+    { name: 'your-api', url: 'https://your-api.com/health' }
+];
+```
+
+### Adjusting Timeouts
+The default timeout for external API checks is 5 seconds. Database ping timeout is set to 2 seconds:
+```javascript
+const checkExternalAPI = (url, timeout = 5000) => {
+    // ...
+};
+
+await mongoose.connection.db.admin().ping({ maxTimeMS: 2000 });
+```
+
+## Best Practices
+
+1. **Authentication**: Basic `/health` endpoint requires no authentication, but detailed endpoints require `x-api-key` header
+2. **Rate Limiting**: Configure rate limiting at the API Gateway level to prevent abuse
+3. **Fast Response**: Health checks should respond quickly (< 1 second)
+4. **Strict Status Codes**: Return 503 for any non-healthy state to ensure proper alerting
+5. **Detailed Logging**: Failed health checks are logged for debugging
+6. **Security**: No sensitive information (DB types, versions) exposed in responses
+7. **Lambda Considerations**: Uptime and memory metrics not included as they're not relevant in serverless
+
+## Troubleshooting
+
+### Database Connection Issues
+- Check `MONGO_URI` environment variable
+- Verify network connectivity to MongoDB
+- Check MongoDB server status
+
+### External API Failures
+- May indicate network issues or external service downtime
+- Service reports "unhealthy" status if any external API is unreachable
+
+## Security Considerations
+
+- Basic health endpoint requires no authentication for monitoring compatibility
+- Detailed endpoints require `x-api-key` header authentication
+- Health endpoints do not expose sensitive information
+- Database connection strings and credentials are never included in responses
+- External API checks use read-only endpoints
+- Rate limiting should be configured at the API Gateway level
+- Consider IP whitelisting for health endpoints in production
+
+## Environment Variables
+
+- `HEALTH_API_KEY`: Required API key for accessing detailed health endpoints

package/handlers/routers/health.js

@@ -0,0 +1,451 @@
+const { Router } = require('express');
+const mongoose = require('mongoose');
+const https = require('https');
+const http = require('http');
+const { moduleFactory, integrationFactory } = require('./../backend-utils');
+const { createAppHandler } = require('./../app-handler-helpers');
+
+const router = Router();
+
+const validateApiKey = (req, res, next) => {
+    const apiKey = req.headers['x-api-key'];
+    
+    if (req.path === '/health') {
+        return next();
+    }
+    
+    if (!apiKey || apiKey !== process.env.HEALTH_API_KEY) {
+        return res.status(401).json({
+            status: 'error',
+            message: 'Unauthorized'
+        });
+    }
+    
+    next();
+};
+
+router.use(validateApiKey);
+
+const checkExternalAPI = (url, timeout = 5000) => {
+    return new Promise((resolve) => {
+        const protocol = url.startsWith('https:') ? https : http;
+        const startTime = Date.now();
+        
+        try {
+            const request = protocol.get(url, { timeout }, (res) => {
+                const responseTime = Date.now() - startTime;
+                resolve({
+                    status: 'healthy',
+                    statusCode: res.statusCode,
+                    responseTime,
+                    reachable: res.statusCode < 500
+                });
+            });
+
+            request.on('error', (error) => {
+                resolve({
+                    status: 'unhealthy',
+                    error: error.message,
+                    responseTime: Date.now() - startTime,
+                    reachable: false
+                });
+            });
+
+            request.on('timeout', () => {
+                request.destroy();
+                resolve({
+                    status: 'timeout',
+                    error: 'Request timeout',
+                    responseTime: timeout,
+                    reachable: false
+                });
+            });
+        } catch (error) {
+            resolve({
+                status: 'error',
+                error: error.message,
+                responseTime: Date.now() - startTime,
+                reachable: false
+            });
+        }
+    });
+};
+
+const getDatabaseState = () => {
+    const stateMap = {
+        0: 'disconnected',
+        1: 'connected',
+        2: 'connecting',
+        3: 'disconnecting'
+    };
+    const readyState = mongoose.connection.readyState;
+    
+    return {
+        readyState,
+        stateName: stateMap[readyState],
+        isConnected: readyState === 1
+    };
+};
+
+const checkDatabaseHealth = async () => {
+    const { stateName, isConnected } = getDatabaseState();
+    const result = {
+        status: isConnected ? 'healthy' : 'unhealthy',
+        state: stateName
+    };
+
+    if (isConnected) {
+        const pingStart = Date.now();
+        await mongoose.connection.db.admin().ping({ maxTimeMS: 2000 });
+        result.responseTime = Date.now() - pingStart;
+    }
+
+    return result;
+};
+
+const 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() !== '' && !hasAES;
+    const mode = hasAES ? 'aes' : hasKMS ? 'kms' : 'none';
+    
+    return {
+        stage: STAGE || null,
+        isBypassed,
+        hasAES,
+        hasKMS,
+        mode,
+    };
+};
+
+const createTestEncryptionModel = () => {
+    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);
+};
+
+const createTestDocument = async (TestModel) => {
+    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 = new TestModel(testData);
+    await testDoc.save();
+    
+    return { testDoc, testData };
+};
+
+const verifyDecryption = (retrievedDoc, originalData) => {
+    return retrievedDoc && 
+        retrievedDoc.testSecret === originalData.testSecret &&
+        retrievedDoc.normalField === originalData.normalField &&
+        retrievedDoc.nestedSecret?.value === originalData.nestedSecret.value;
+};
+
+const verifyEncryptionInDatabase = async (testDoc, originalData, TestModel) => {
+    const collectionName = TestModel.collection.name;
+    const rawDoc = await mongoose.connection.db
+        .collection(collectionName)
+        .findOne({ _id: testDoc._id });
+
+    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
+    };
+};
+
+const evaluateEncryptionTestResults = (decryptionWorks, encryptionResults) => {
+    const { secretIsEncrypted, nestedIsEncrypted, normalNotEncrypted } = encryptionResults;
+    
+    if (decryptionWorks && secretIsEncrypted && nestedIsEncrypted && normalNotEncrypted) {
+        return {
+            status: 'enabled',
+            testResult: 'Encryption and decryption verified successfully'
+        };
+    }
+    
+    if (decryptionWorks && (!secretIsEncrypted || !nestedIsEncrypted)) {
+        return {
+            status: 'unhealthy',
+            testResult: 'Fields are not being encrypted in database'
+        };
+    }
+    
+    if (decryptionWorks && !normalNotEncrypted) {
+        return {
+            status: 'unhealthy',
+            testResult: 'Normal fields are being incorrectly encrypted'
+        };
+    }
+    
+    return {
+        status: 'unhealthy',
+        testResult: 'Decryption failed or data mismatch'
+    };
+};
+
+const testEncryption = async () => {
+    const TestModel = createTestEncryptionModel();
+    const { testDoc, testData } = await createTestDocument(TestModel);
+    
+    try {
+        const retrievedDoc = await TestModel.findById(testDoc._id);
+        const decryptionWorks = verifyDecryption(retrievedDoc, testData);
+        const encryptionResults = await verifyEncryptionInDatabase(testDoc, testData, TestModel);
+        
+        const evaluation = evaluateEncryptionTestResults(decryptionWorks, encryptionResults);
+        
+        return {
+            ...evaluation,
+            encryptionWorks: decryptionWorks
+        };
+    } finally {
+        await TestModel.deleteOne({ _id: testDoc._id });
+    }
+};
+
+const checkEncryptionHealth = async () => {
+    const config = 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 testEncryption();
+        
+        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
+            }
+        };
+    }
+};
+
+const checkExternalAPIs = async () => {
+    const apis = [
+        { name: 'github', url: 'https://api.github.com/status' },
+        { name: 'npm', url: 'https://registry.npmjs.org' }
+    ];
+
+    const results = await Promise.all(
+        apis.map(api => 
+            checkExternalAPI(api.url).then(result => ({ name: api.name, ...result }))
+        )
+    );
+    
+    const apiStatuses = {};
+    let allReachable = true;
+    
+    results.forEach(({ name, ...checkResult }) => {
+        apiStatuses[name] = checkResult;
+        if (!checkResult.reachable) {
+            allReachable = false;
+        }
+    });
+    
+    return { apiStatuses, allReachable };
+};
+
+const checkIntegrations = () => {
+    const moduleTypes = Array.isArray(moduleFactory.moduleTypes)
+        ? moduleFactory.moduleTypes
+        : [];
+    
+    const integrationTypes = Array.isArray(integrationFactory.integrationTypes)
+        ? integrationFactory.integrationTypes
+        : [];
+
+    return {
+        status: 'healthy',
+        modules: {
+            count: moduleTypes.length,
+            available: moduleTypes,
+        },
+        integrations: {
+            count: integrationTypes.length,
+            available: integrationTypes,
+        },
+    };
+};
+
+const buildHealthCheckResponse = (startTime) => {
+    return {
+        service: 'frigg-core-api',
+        status: 'healthy',
+        timestamp: new Date().toISOString(),
+        checks: {},
+        calculateResponseTime: () => Date.now() - startTime
+    };
+};
+
+router.get('/health', async (_req, res) => {
+    const status = {
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        service: 'frigg-core-api'
+    };
+
+    res.status(200).json(status);
+});
+
+router.get('/health/detailed', async (_req, res) => {
+    const startTime = Date.now();
+    const response = buildHealthCheckResponse(startTime);
+
+    try {
+        response.checks.database = await checkDatabaseHealth();
+        const dbState = getDatabaseState();
+        if (!dbState.isConnected) {
+            response.status = 'unhealthy';
+        }
+    } catch (error) {
+        response.checks.database = {
+            status: 'unhealthy',
+            error: error.message
+        };
+        response.status = 'unhealthy';
+    }
+
+    try {
+        response.checks.encryption = await checkEncryptionHealth();
+        if (response.checks.encryption.status === 'unhealthy') {
+            response.status = 'unhealthy';
+        }
+    } catch (error) {
+        response.checks.encryption = {
+            status: 'unhealthy',
+            error: error.message
+        };
+        response.status = 'unhealthy';
+    }
+
+    const { apiStatuses, allReachable } = await checkExternalAPIs();
+    response.checks.externalApis = apiStatuses;
+    if (!allReachable) {
+        response.status = 'unhealthy';
+    }
+
+    try {
+        response.checks.integrations = checkIntegrations();
+    } catch (error) {
+        response.checks.integrations = {
+            status: 'unhealthy',
+            error: error.message
+        };
+        response.status = 'unhealthy';
+    }
+
+    response.responseTime = response.calculateResponseTime();
+    delete response.calculateResponseTime;
+
+    const statusCode = response.status === 'healthy' ? 200 : 503;
+    res.status(statusCode).json(response);
+});
+
+router.get('/health/live', (_req, res) => {
+    res.status(200).json({
+        status: 'alive',
+        timestamp: new Date().toISOString()
+    });
+});
+
+router.get('/health/ready', async (_req, res) => {
+    const dbState = getDatabaseState();
+    const isDbReady = dbState.isConnected;
+    
+    let areModulesReady = false;
+    try {
+        const moduleTypes = Array.isArray(moduleFactory.moduleTypes)
+            ? moduleFactory.moduleTypes
+            : [];
+        areModulesReady = moduleTypes.length > 0;
+    } catch (error) {
+        areModulesReady = false;
+    }
+
+    const isReady = isDbReady && areModulesReady;
+
+    res.status(isReady ? 200 : 503).json({
+        ready: isReady,
+        timestamp: new Date().toISOString(),
+        checks: {
+            database: isDbReady,
+            modules: areModulesReady
+        }
+    });
+});
+
+const handler = createAppHandler('HTTP Event: Health', router);
+
+module.exports = { handler, router };

package/handlers/routers/health.test.js

@@ -0,0 +1,203 @@
+process.env.HEALTH_API_KEY = 'test-api-key';
+
+jest.mock('mongoose', () => ({
+    set: jest.fn(),
+    connection: {
+        readyState: 1,
+        db: {
+            admin: () => ({
+                ping: jest.fn().mockResolvedValue(true)
+            })
+        }
+    }
+}));
+
+jest.mock('./../backend-utils', () => ({
+    moduleFactory: {
+        moduleTypes: ['test-module', 'another-module']
+    },
+    integrationFactory: {
+        integrationTypes: ['test-integration', 'another-integration']
+    }
+}));
+
+jest.mock('./../app-handler-helpers', () => ({
+    createAppHandler: jest.fn((name, router) => ({ name, router }))
+}));
+
+const { router } = require('./health');
+const mongoose = require('mongoose');
+
+const mockRequest = (path, headers = {}) => ({
+    path,
+    headers
+});
+
+const mockResponse = () => {
+    const res = {};
+    res.status = jest.fn().mockReturnValue(res);
+    res.json = jest.fn().mockReturnValue(res);
+    return res;
+};
+
+describe('Health Check Endpoints', () => {
+    beforeEach(() => {
+        mongoose.connection.readyState = 1;
+    });
+
+    describe('Middleware - validateApiKey', () => {
+        it('should allow access to /health without authentication', async () => {
+            expect(true).toBe(true);
+        });
+    });
+
+    describe('GET /health', () => {
+        it('should return basic health status', async () => {
+            const req = mockRequest('/health');
+            const res = mockResponse();
+
+            const routeHandler = router.stack.find(layer => 
+                layer.route && layer.route.path === '/health'
+            ).route.stack[0].handle;
+
+            await routeHandler(req, res);
+
+            expect(res.status).toHaveBeenCalledWith(200);
+            expect(res.json).toHaveBeenCalledWith({
+                status: 'ok',
+                timestamp: expect.any(String),
+                service: 'frigg-core-api'
+            });
+        });
+    });
+
+    describe('GET /health/detailed', () => {
+        it('should return detailed health status when healthy', async () => {
+            const req = mockRequest('/health/detailed', { 'x-api-key': 'test-api-key' });
+            const res = mockResponse();
+
+            const originalPromiseAll = Promise.all;
+            Promise.all = jest.fn().mockResolvedValue([
+                { name: 'github', status: 'healthy', reachable: true, statusCode: 200, responseTime: 100 },
+                { name: 'npm', status: 'healthy', reachable: true, statusCode: 200, responseTime: 150 }
+            ]);
+
+            const routeHandler = router.stack.find(layer => 
+                layer.route && layer.route.path === '/health/detailed'
+            ).route.stack[0].handle;
+
+            await routeHandler(req, res);
+            
+            Promise.all = originalPromiseAll;
+
+            expect(res.status).toHaveBeenCalledWith(200);
+            expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+                status: 'healthy',
+                service: 'frigg-core-api',
+                timestamp: expect.any(String),
+                checks: expect.objectContaining({
+                    database: expect.objectContaining({
+                        status: 'healthy',
+                        state: 'connected'
+                    }),
+                    integrations: expect.objectContaining({
+                        status: 'healthy'
+                    })
+                }),
+                responseTime: expect.any(Number)
+            }));
+
+            const response = res.json.mock.calls[0][0];
+            expect(response).not.toHaveProperty('version');
+            expect(response).not.toHaveProperty('uptime');
+            expect(response.checks).not.toHaveProperty('memory');
+            expect(response.checks.database).not.toHaveProperty('type');
+        });
+
+        it('should return 503 when database is disconnected', async () => {
+            mongoose.connection.readyState = 0;
+
+            const req = mockRequest('/health/detailed', { 'x-api-key': 'test-api-key' });
+            const res = mockResponse();
+
+            const originalPromiseAll = Promise.all;
+            Promise.all = jest.fn().mockResolvedValue([
+                { name: 'github', status: 'healthy', reachable: true, statusCode: 200, responseTime: 100 },
+                { name: 'npm', status: 'healthy', reachable: true, statusCode: 200, responseTime: 150 }
+            ]);
+
+            const routeHandler = router.stack.find(layer => 
+                layer.route && layer.route.path === '/health/detailed'
+            ).route.stack[0].handle;
+
+            await routeHandler(req, res);
+            
+            Promise.all = originalPromiseAll;
+
+            expect(res.status).toHaveBeenCalledWith(503);
+            expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+                status: 'unhealthy'
+            }));
+        });
+    });
+
+    describe('GET /health/live', () => {
+        it('should return alive status', async () => {
+            const req = mockRequest('/health/live', { 'x-api-key': 'test-api-key' });
+            const res = mockResponse();
+
+            const routeHandler = router.stack.find(layer => 
+                layer.route && layer.route.path === '/health/live'
+            ).route.stack[0].handle;
+
+            routeHandler(req, res);
+
+            expect(res.status).toHaveBeenCalledWith(200);
+            expect(res.json).toHaveBeenCalledWith({
+                status: 'alive',
+                timestamp: expect.any(String)
+            });
+        });
+    });
+
+    describe('GET /health/ready', () => {
+        it('should return ready when all checks pass', async () => {
+            const req = mockRequest('/health/ready', { 'x-api-key': 'test-api-key' });
+            const res = mockResponse();
+
+            const routeHandler = router.stack.find(layer => 
+                layer.route && layer.route.path === '/health/ready'
+            ).route.stack[0].handle;
+
+            await routeHandler(req, res);
+
+            expect(res.status).toHaveBeenCalledWith(200);
+            expect(res.json).toHaveBeenCalledWith({
+                ready: true,
+                timestamp: expect.any(String),
+                checks: {
+                    database: true,
+                    modules: true
+                }
+            });
+        });
+
+        it('should return 503 when database is not connected', async () => {
+            mongoose.connection.readyState = 0;
+
+            const req = mockRequest('/health/ready', { 'x-api-key': 'test-api-key' });
+            const res = mockResponse();
+
+            const routeHandler = router.stack.find(layer => 
+                layer.route && layer.route.path === '/health/ready'
+            ).route.stack[0].handle;
+
+            await routeHandler(req, res);
+
+            expect(res.status).toHaveBeenCalledWith(503);
+            expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+                ready: false
+            }));
+        });
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/core",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0-next.25",
+  "version": "2.0.0-next.27",
   "dependencies": {
     "@hapi/boom": "^10.0.1",
     "aws-sdk": "^2.1200.0",
@@ -22,9 +22,9 @@
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0-next.25",
-    "@friggframework/prettier-config": "2.0.0-next.25",
-    "@friggframework/test": "2.0.0-next.25",
+    "@friggframework/eslint-config": "2.0.0-next.27",
+    "@friggframework/prettier-config": "2.0.0-next.27",
+    "@friggframework/test": "2.0.0-next.27",
     "@types/lodash": "4.17.15",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "chai": "^4.3.6",
@@ -53,5 +53,5 @@
   },
   "homepage": "https://github.com/friggframework/frigg#readme",
   "description": "",
-  "gitHead": "d758d225a2cfbe4038ecc2b777cd6826949312fb"
+  "gitHead": "82dec739e8d482b55f995eecf088ef05f7931188"
 }