Files

Jason Woltje 12abdfe81d feat(#93 ): implement agent spawn via federation

Implements FED-010: Agent Spawn via Federation feature that enables
spawning and managing Claude agents on remote federated Mosaic Stack
instances via COMMAND message type.

Features:
- Federation agent command types (spawn, status, kill)
- FederationAgentService for handling agent operations
- Integration with orchestrator's agent spawner/lifecycle services
- API endpoints for spawning, querying status, and killing agents
- Full command routing through federation COMMAND infrastructure
- Comprehensive test coverage (12/12 tests passing)

Architecture:
- Hub → Spoke: Spawn agents on remote instances
- Command flow: FederationController → FederationAgentService →
  CommandService → Remote Orchestrator
- Response handling: Remote orchestrator returns agent status/results
- Security: Connection validation, signature verification

Files created:
- apps/api/src/federation/types/federation-agent.types.ts
- apps/api/src/federation/federation-agent.service.ts
- apps/api/src/federation/federation-agent.service.spec.ts

Files modified:
- apps/api/src/federation/command.service.ts (agent command routing)
- apps/api/src/federation/federation.controller.ts (agent endpoints)
- apps/api/src/federation/federation.module.ts (service registration)
- apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint)
- apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration)

Testing:
- 12/12 tests passing for FederationAgentService
- All command service tests passing
- TypeScript compilation successful
- Linting passed

Refs #93

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-03 14:37:06 -06:00

4.3 KiB

Raw Blame History

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

Identify all coordinator integration endpoints without authentication
Write security tests first (TDD - RED phase)
Implement authentication mechanism (JWT/bearer token or API key)
Verify all tests pass (GREEN phase)
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

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
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:

Constant-time comparison - Uses crypto.timingSafeEqual to prevent timing attacks
Header case-insensitivity - Accepts X-API-Key, x-api-key, X-Api-Key variations
Empty string validation - Rejects empty API keys
Configuration validation - Fails fast if COORDINATOR_API_KEY is not configured
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

Security tests to verify authentication is required
Tests to verify valid credentials are accepted
Tests to verify invalid credentials are rejected
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%

4.3 KiB Raw Blame History