🏗️ Architecture: How to secure the Sandbox Orchestrator API from unauthorized...

Date: 2026-02-27
Time: 16:24:22 UTC
Session: gspace1-150.6
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to secure the Sandbox Orchestrator API from unauthorized access?

Task: Sandbox orchestrator API security

🎯 Decision Made

Chosen:

API key guard (X-API-Key header) with constant-time comparison via crypto.timingSafeEqual(). Health and metrics endpoints exempt (for load balancers and Prometheus). Per-session ephemeral SSH keys for VM communication. Nginx rate limiting at 5 creates/min.

Options Considered:

1. API key with constant-time comparison (chosen)
2. JWT tokens
3. mTLS (mutual TLS)
4. IP allowlisting only

💭 Reasoning

ROOT CAUSE: Original Session 141 plan had ZERO authentication on the orchestrator API. Anyone who discovered the URL could create arbitrary VMs on our hardware — a critical security gap. API key chosen over JWT because: (1) server-to-server communication (SelfHostedProvider→Orchestrator), no user sessions needed; (2) simpler implementation, one shared secret; (3) constant-time comparison prevents timing attacks. Exempt endpoints: /health (load balancers need unauthenticated access), /metrics (Prometheus scraping). Rate limiting at nginx level prevents burst VM creation even with valid key. SSH keys are per-session ephemeral (ed25519, generated at create, deleted at destroy) — no long-lived credentials stored. WHAT WOULD MAKE THIS WRONG: If we need per-user authorization (different users get different VM quotas) → upgrade to JWT with claims. EARLY WARNING: Monitor 401 responses in nginx access logs for brute-force attempts.

📁 Files Involved

• APIs/sandbox-orchestrator/src/app/auth/api-key.guard.ts
• APIs/backend-ai-api/src/app/infrastructure/services/sandbox/self-hosted.provider.ts
• deployment/sandbox-orchestrator/nginx.conf

🔗 Related

• Decision ID: dev_1772209462317_9u5hb2t
• Session: 150
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation