fix(api-server): address code audit findings

- fix: make ApiKeyAuth constructor private; add static resetInstance() for tests
- fix: enforce MAX_REQUEST_SIZE via content-length header check (413 response)
- fix: add PAYLOAD_TOO_LARGE to ErrorCode enum and getErrorCodeForStatus map
- fix: add --watch flag to api:server:dev script for hot-reload
- fix: add ALLOWED_ORIGINS to docker-compose.yml environment section
- fix: expand api-validate.yml trigger paths to include api-server/** and package.json
- chore: remove implementation-plan-fetch-ready.md from repo root

Author: luandro

.github/workflows/api-validate.yml

@@ -3,11 +3,18 @@ name: API Validate
 on:
   workflow_dispatch:
   push:
+    branches:
+      - main
+      - "feat/**"
     paths:
       - ".github/workflows/api-validate.yml"
+      - "api-server/**"
+      - "package.json"
   pull_request:
     paths:
       - ".github/workflows/api-validate.yml"
+      - "api-server/**"
+      - "package.json"
 
 jobs:
   api-validate:

api-server/auth.test.ts

@@ -16,9 +16,9 @@ describe("ApiKeyAuth", () => {
   let auth: ApiKeyAuth;
 
   beforeEach(() => {
-    // Clear any existing instance and create fresh one for each test
-    ApiKeyAuth["instance"] = undefined;
-    auth = new ApiKeyAuth();
+    // Reset the singleton and obtain a fresh instance for each test
+    ApiKeyAuth.resetInstance();
+    auth = ApiKeyAuth.getInstance();
     // Ensure no keys are loaded from environment for consistent testing
     auth.clearKeys();
   });
@@ -243,7 +243,8 @@ describe("ApiKeyAuth", () => {
 
   describe("Hash collision resistance", () => {
     it("should produce different hashes for different keys", () => {
-      const auth = new ApiKeyAuth();
+      ApiKeyAuth.resetInstance();
+      const auth = ApiKeyAuth.getInstance();
       const keys = [
         "test-key-aaaa-1234567890",
         "test-key-bbbb-1234567890",
@@ -272,7 +273,8 @@ describe("ApiKeyAuth", () => {
     });
 
     it("should not authenticate with a key that has the same hash length but different content", () => {
-      const auth = new ApiKeyAuth();
+      ApiKeyAuth.resetInstance();
+      const auth = ApiKeyAuth.getInstance();
       auth.addKey("real", "real-api-key-1234567890ab", {
         name: "real",
         active: true,

api-server/auth.ts

@@ -51,10 +51,10 @@ export interface AuthResult {
  * Keys are loaded from environment variables in format: API_KEY_<name>
  */
 export class ApiKeyAuth {
-  private static instance: ApiKeyAuth;
+  private static instance: ApiKeyAuth | undefined;
   private apiKeys: Map<string, ApiKeyRecord> = new Map();
 
-  public constructor() {
+  private constructor() {
     this.loadKeysFromEnv();
   }
 
@@ -68,6 +68,14 @@ export class ApiKeyAuth {
     return ApiKeyAuth.instance;
   }
 
+  /**
+   * Reset the singleton instance and clear all keys.
+   * Intended for use in tests only.
+   */
+  static resetInstance(): void {
+    ApiKeyAuth.instance = undefined;
+  }
+
   /**
    * Load API keys from environment variables
    * Format: API_KEY_<name> = <key value>

api-server/github-actions-secret-handling.test.ts

@@ -62,8 +62,8 @@ describe("GitHub Actions Secret Handling", () => {
   describe("API key auth compatibility", () => {
     it("accepts GitHub Actions bearer token style keys", () => {
       // Reset singleton for isolated test behavior.
-      ApiKeyAuth["instance"] = undefined;
-      const auth = new ApiKeyAuth();
+      ApiKeyAuth.resetInstance();
+      const auth = ApiKeyAuth.getInstance();
 
       const token = "gha_" + "a".repeat(32);
       auth.addKey("GITHUB_ACTIONS", token, {

api-server/module-extraction.test.ts

@@ -129,8 +129,8 @@ describe("Module Extraction - extractKeyFromHeader (auth module)", () => {
   let auth: ApiKeyAuth;
 
   beforeEach(() => {
-    ApiKeyAuth["instance"] = undefined;
-    auth = new ApiKeyAuth();
+    ApiKeyAuth.resetInstance();
+    auth = ApiKeyAuth.getInstance();
   });
 
   const extractKeyFromHeader = (header: string): string | null => {

api-server/request-handler.ts

@@ -11,7 +11,7 @@ import {
   createErrorResponse,
   type ErrorResponse,
 } from "./response-schemas";
-import { isPublicEndpoint } from "./validation";
+import { isPublicEndpoint, MAX_REQUEST_SIZE } from "./validation";
 import { routeRequest } from "./router";
 
 /**
@@ -29,6 +29,29 @@ export async function handleRequest(req: Request): Promise<Response> {
     const url = new URL(req.url);
     const path = url.pathname;
 
+    // Reject oversized requests early using the Content-Length header.
+    // Only reject when the header is present; chunked requests (no header) pass through.
+    const contentLength = req.headers.get("content-length");
+    if (
+      contentLength !== null &&
+      parseInt(contentLength, 10) > MAX_REQUEST_SIZE
+    ) {
+      const error: ErrorResponse = createErrorResponse(
+        ErrorCode.PAYLOAD_TOO_LARGE,
+        "Request body exceeds 1MB limit",
+        413,
+        requestId
+      );
+      return new Response(JSON.stringify(error, null, 2), {
+        status: 413,
+        headers: {
+          "Content-Type": "application/json",
+          ...getCorsHeaders(requestOrigin),
+          "X-Request-ID": requestId,
+        },
+      });
+    }
+
     // Check if endpoint is public or CORS preflight (OPTIONS)
     // CORS preflight requests must skip auth since browsers don't send credentials
     const isPublic = isPublicEndpoint(path) || req.method === "OPTIONS";

api-server/response-schemas.ts

@@ -38,6 +38,9 @@ export enum ErrorCode {
   // Rate limiting (4xx)
   RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
 
+  // Payload errors (4xx)
+  PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
+
   // Server errors (5xx)
   INTERNAL_ERROR = "INTERNAL_ERROR",
   SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
@@ -273,6 +276,7 @@ export function getErrorCodeForStatus(status: number): ErrorCode {
     403: ErrorCode.FORBIDDEN,
     404: ErrorCode.NOT_FOUND,
     409: ErrorCode.CONFLICT,
+    413: ErrorCode.PAYLOAD_TOO_LARGE,
     429: ErrorCode.RATE_LIMIT_EXCEEDED,
     500: ErrorCode.INTERNAL_ERROR,
     503: ErrorCode.SERVICE_UNAVAILABLE,

docker-compose.yml

@@ -75,6 +75,11 @@ services:
       # Example: API_KEY_DEPLOYMENT=your-secret-key-min-16-chars
       API_KEY_GITHUB_ACTIONS: ${API_KEY_GITHUB_ACTIONS}
 
+      # CORS Origin Allowlist (optional, comma-separated)
+      # Leave unset to allow all origins; set to restrict cross-origin access
+      # Example: ALLOWED_ORIGINS=https://your-app.com,https://admin.your-app.com
+      ALLOWED_ORIGINS: ${ALLOWED_ORIGINS:-}
+
     # Volume mounts for persistent data
     volumes:
       # Mount job persistence directory