@friggframework/core 2.0.0-next.1 → 2.0.0-next.100

package/handlers/middleware/admin-auth.js

@@ -0,0 +1,73 @@
+const crypto = require('node:crypto');
+
+/**
+ * Admin Auth Middleware
+ *
+ * Shared authentication middleware for all admin endpoints:
+ * - /admin/db-migrate/*
+ * - /admin/scripts/*
+ *
+ * Uses simple ENV-based API key validation.
+ * Expects: x-frigg-admin-api-key header
+ */
+
+/**
+ * Constant-time comparison of two secrets. Hashing both to a fixed-length
+ * digest first means timingSafeEqual never throws on length mismatch and the
+ * comparison leaks neither the key nor its length.
+ * @private
+ */
+function secretsMatch(provided, expected) {
+    const providedHash = crypto
+        .createHash('sha256')
+        .update(String(provided))
+        .digest();
+    const expectedHash = crypto
+        .createHash('sha256')
+        .update(String(expected))
+        .digest();
+    return crypto.timingSafeEqual(providedHash, expectedHash);
+}
+
+/**
+ * Validate admin API key from request header
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {import('express').NextFunction} next
+ */
+function validateAdminApiKey(req, res, next) {
+    const expectedKey = process.env.ADMIN_API_KEY;
+
+    // Check if admin API key is configured
+    if (!expectedKey) {
+        console.error('ADMIN_API_KEY environment variable not configured');
+        return res.status(401).json({
+            error: 'Unauthorized',
+            message: 'Admin API key not configured',
+        });
+    }
+
+    const apiKey = req.headers['x-frigg-admin-api-key'];
+
+    // Check if header is present
+    if (!apiKey) {
+        console.error('Missing x-frigg-admin-api-key header');
+        return res.status(401).json({
+            error: 'Unauthorized',
+            message: 'x-frigg-admin-api-key header required',
+        });
+    }
+
+    // Validate key using a constant-time comparison
+    if (!secretsMatch(apiKey, expectedKey)) {
+        console.error('Invalid admin API key provided');
+        return res.status(401).json({
+            error: 'Unauthorized',
+            message: 'Invalid admin API key',
+        });
+    }
+
+    next();
+}
+
+module.exports = { validateAdminApiKey };

package/handlers/routers/HEALTHCHECK.md

@@ -0,0 +1,342 @@
+# 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
+
+## 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.

package/handlers/routers/auth.js

@@ -0,0 +1,15 @@
+const { createIntegrationRouter } = require('@friggframework/core');
+const { createAppHandler } = require('./../app-handler-helpers');
+
+const router = createIntegrationRouter();
+
+router.route('/api/integrations/redirect/:appId').get((req, res) => {
+    res.redirect(
+        `${process.env.FRONTEND_URI}/redirect/${req.params.appId
+        }?${new URLSearchParams(req.query)}`
+    );
+});
+
+const handler = createAppHandler('HTTP Event: Auth', router);
+
+module.exports = { handler };

package/handlers/routers/db-migration.handler.js

@@ -0,0 +1,29 @@
+/**
+ * Database Migration Router Lambda Handler
+ *
+ * Minimal Lambda wrapper that avoids loading core/index.js
+ * (which would try to load user/** modules excluded from migration packages)
+ * 
+ * This handler is intentionally simpler than health.handler.js to avoid dependencies.
+ */
+
+const serverlessHttp = require('serverless-http');
+const express = require('express');
+const cors = require('cors');
+const { router: dbMigrationRouter } = require('./db-migration');
+
+// Create minimal Express app
+const app = express();
+app.use(cors());
+app.use(express.json());
+app.use(dbMigrationRouter);
+
+// Error handler
+app.use((err, req, res, next) => {
+    console.error('Error:', err);
+    res.status(500).json({ message: 'Internal Server Error' });
+});
+
+// Export as .handler property (Lambda config: db-migration.handler)
+module.exports.handler = serverlessHttp(app);
+