fix(SEC-ORCH-2): Add API key authentication to orchestrator API

Add OrchestratorApiKeyGuard to protect agent management endpoints (spawn,
kill, kill-all, status) from unauthorized access. Uses X-API-Key header
with constant-time comparison to prevent timing attacks.

- Create apps/orchestrator/src/common/guards/api-key.guard.ts
- Add comprehensive tests for all guard scenarios
- Apply guard to AgentsController (controller-level protection)
- Document ORCHESTRATOR_API_KEY in .env.example files
- Health endpoints remain unauthenticated for monitoring

Security: Prevents unauthorized users from draining API credits or
killing all agents via unprotected endpoints.

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

apps/orchestrator/src/common/guards/api-key.guard.ts

@@ -0,0 +1,82 @@
+import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { timingSafeEqual } from "crypto";
+
+/**
+ * OrchestratorApiKeyGuard - Authentication guard for orchestrator API endpoints
+ *
+ * Validates the X-API-Key header against the ORCHESTRATOR_API_KEY environment variable.
+ * Uses constant-time comparison to prevent timing attacks.
+ *
+ * Usage:
+ * @UseGuards(OrchestratorApiKeyGuard)
+ * @Controller('agents')
+ * export class AgentsController { ... }
+ */
+@Injectable()
+export class OrchestratorApiKeyGuard implements CanActivate {
+  constructor(private readonly configService: ConfigService) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<{ headers: Record<string, string> }>();
+    const providedKey = this.extractApiKeyFromHeader(request);
+
+    if (!providedKey) {
+      throw new UnauthorizedException("No API key provided");
+    }
+
+    const configuredKey = this.configService.get<string>("ORCHESTRATOR_API_KEY");
+
+    if (!configuredKey) {
+      throw new UnauthorizedException("API key authentication not configured");
+    }
+
+    if (!this.isValidApiKey(providedKey, configuredKey)) {
+      throw new UnauthorizedException("Invalid API key");
+    }
+
+    return true;
+  }
+
+  /**
+   * Extract API key from X-API-Key header (case-insensitive)
+   */
+  private extractApiKeyFromHeader(request: {
+    headers: Record<string, string>;
+  }): string | undefined {
+    const headers = request.headers;
+
+    // Check common variations (lowercase, uppercase, mixed case)
+    // HTTP headers are typically normalized to lowercase, but we check common variations for safety
+    const apiKey =
+      headers["x-api-key"] || headers["X-API-Key"] || headers["X-Api-Key"] || undefined;
+
+    // Return undefined if key is empty string
+    if (typeof apiKey === "string" && apiKey.trim() === "") {
+      return undefined;
+    }
+
+    return apiKey;
+  }
+
+  /**
+   * Validate API key using constant-time comparison to prevent timing attacks
+   */
+  private isValidApiKey(providedKey: string, configuredKey: string): boolean {
+    try {
+      // Convert strings to buffers for constant-time comparison
+      const providedBuffer = Buffer.from(providedKey, "utf8");
+      const configuredBuffer = Buffer.from(configuredKey, "utf8");
+
+      // Keys must be same length for timingSafeEqual
+      if (providedBuffer.length !== configuredBuffer.length) {
+        return false;
+      }
+
+      return timingSafeEqual(providedBuffer, configuredBuffer);
+    } catch {
+      // If comparison fails for any reason, reject
+      return false;
+    }
+  }
+}