stack/docs/scratchpads/184-add-coordinator-auth.md

Issue #184: [BLOCKER] Add authentication to coordinator integration endpoints

Objective

Add authentication to coordinator integration endpoints to prevent unauthorized access. This is a critical security vulnerability that must be fixed before deployment.

Approach

1. Identify all coordinator integration endpoints without authentication
2. Write security tests first (TDD - RED phase)
3. Implement authentication mechanism (JWT/bearer token or API key)
4. Verify all tests pass (GREEN phase)
5. Refactor if needed while maintaining test coverage

Progress

• Create scratchpad
• Investigate coordinator endpoints
• Investigate stitcher endpoints
• Write security tests for unauthenticated endpoints (TDD - RED)
• Implement authentication (TDD - GREEN)
• Verify 85% minimum coverage (95.65% achieved)
• All tests pass (25 new tests passing)
• Commit changes
• Update issue status

Findings

Unauthenticated Endpoints

1. CoordinatorIntegrationController (/coordinator/*)

   • POST /coordinator/jobs - Create job from coordinator
   • PATCH /coordinator/jobs/:id/status - Update job status
   • PATCH /coordinator/jobs/:id/progress - Update job progress
   • POST /coordinator/jobs/:id/complete - Mark job complete
   • POST /coordinator/jobs/:id/fail - Mark job failed
   • GET /coordinator/jobs/:id - Get job details
   • GET /coordinator/health - Health check

2. StitcherController (/stitcher/*)

   • POST /stitcher/webhook - Webhook from @mosaic bot
   • POST /stitcher/dispatch - Manual job dispatch

Authentication Mechanism

Decision: API Key Authentication

Reasons:

• Service-to-service communication (coordinator Python app → NestJS API)
• No user context needed
• Simpler than JWT for this use case
• Consistent with MOSAIC_API_TOKEN pattern already in use

Implementation:

• Create ApiKeyGuard that checks X-API-Key header
• Add COORDINATOR_API_KEY to .env.example
• Coordinator will send this key in X-API-Key header
• Guard validates key matches COORDINATOR_API_KEY env var

Security Review Notes

Authentication Mechanism: API Key Guard

Implementation: /apps/api/src/common/guards/api-key.guard.ts

Security Features:

1. Constant-time comparison - Uses crypto.timingSafeEqual to prevent timing attacks
2. Header case-insensitivity - Accepts X-API-Key, x-api-key, X-Api-Key variations
3. Empty string validation - Rejects empty API keys
4. Configuration validation - Fails fast if COORDINATOR_API_KEY is not configured
5. Clear error messages - Differentiates between missing, invalid, and unconfigured keys

Protected Endpoints:

• All CoordinatorIntegrationController endpoints (/coordinator/*)
• All StitcherController endpoints (/stitcher/*)

Environment Variable:

• COORDINATOR_API_KEY - Must be at least 32 characters (recommended: openssl rand -base64 32)

Testing:

• 8 tests for ApiKeyGuard (95.65% coverage)
• 10 tests for coordinator security
• 7 tests for stitcher security
• Total: 25 new security tests

Attack Prevention:

• Timing attacks: Prevented via constant-time comparison
• Unauthorized access: All endpoints require valid API key
• Empty/null keys: Explicitly rejected
• Configuration errors: Server fails to start if misconfigured

Testing

Test Plan

1. Security tests to verify authentication is required
2. Tests to verify valid credentials are accepted
3. Tests to verify invalid credentials are rejected
4. Integration tests for end-to-end flows

Test Results

ApiKeyGuard Tests: 8/8 passing (95.65% coverage)

• ✅ Valid API key accepted
• ✅ Missing API key rejected
• ✅ Invalid API key rejected
• ✅ Unconfigured API key rejected
• ✅ Case-insensitive header handling
• ✅ Empty string rejection
• ✅ Timing attack prevention

Coordinator Security Tests: 10/10 passing

• ✅ All endpoints require authentication
• ✅ Valid API key allows access
• ✅ Invalid API key blocks access

Stitcher Security Tests: 7/7 passing

• ✅ All endpoints require authentication
• ✅ Valid API key allows access
• ✅ Invalid/empty API keys blocked
• ✅ Webhook submission protection

Existing Tests: No regressions introduced (1420 tests still passing)

Notes

• Priority: CRITICAL SECURITY
• Impact: Prevents unauthorized access to coordinator integration
• Coverage requirement: Minimum 85%