Service Communication
Internal HTTP (Synchronous)
All service-to-service HTTP calls are authenticated via HMAC-SHA256 request signing.
Signature Mechanism
The calling service signs each outbound request:
canonical_string = METHOD + "\n" + PATH + "\n" + TIMESTAMP
signature = HMAC-SHA256(INTERNAL_SERVICE_SECRET, canonical_string)
Headers added to outbound request:
X-Internal-Service-Auth: HMAC signatureX-Service-Name: Calling service identifierX-Tenant-Id: Authenticated tenant ID
The receiving service validates the signature and rejects requests with:
- Invalid or missing signature (403)
- Timestamp outside 60-second replay window (403)
- Missing service name header (403)
Enforcement Modes
| Mode | Behavior | Default Environment |
|---|---|---|
enforce |
Rejects unsigned requests with 403 | Production |
audit |
Logs but does not block unsigned requests | Development |
disabled |
No verification | Unsafe; not recommended |
Controlled via INTERNAL_AUTH_MODE environment variable.
Implemented in packages/security/src/internal-auth/middleware.ts at commit 4b572c2.
Proxy Routes
The API Gateway maintains proxy mappings to internal services:
| Gateway Path | Target Service | Upstream Path |
|---|---|---|
/api/insights/* |
insights-service:3005 | /api/v1/* |
/api/data/* |
unified-data-service:4001 | /api/* |
/api/templates/* |
workflow-engine:8080 | /api/v1/templates/* |
/api/workflows/* |
workflow-engine:8080 | /api/v1/workflows/* |
/api/runs/* |
workflow-engine:8080 | /api/v1/runs/* |
/api/agents/* |
agent-orchestrator:8080 | /api/v1/agents/* |
/api/agent/* |
agent-orchestrator:8080 | /api/v1/agent/* |
/api/ml/* |
ml-service:8080 | /api/v1/* |
/api/v1/bhi/* |
insights-service:3005 | /api/v1/bhi/* |
/api/v1/nba/* |
insights-service:3005 | /api/v1/nba/* |
/api/v1/saas/* |
insights-service:3005 | /api/v1/saas/* |
/api/v1/risk/* |
insights-service:3005 | /api/v1/risk/* |
Implemented in services/api-gateway/src/routes/proxy.ts at commit 4b572c2.
Service Client
Internal service calls from the API Gateway use a shared fetchService() function that:
- Resolves target service URL from environment variables
- Signs request with HMAC
- Propagates tenant ID, correlation ID, and request ID headers
- Applies circuit breaker and timeout
- Parses JSON response or returns error
Implemented in services/api-gateway/src/service-clients.ts at commit 4b572c2.