fix(security): disable OpenAPI docs in production by default (API-001)

GET /openapi.json and /docs exposed the entire API surface to anonymous
callers. They are a development aid, so they are now disabled when
NODE_ENV=production unless the operator opts in with ENABLE_API_DOCS=true.
Non-production behaviour is unchanged. A hard on/off switch is used rather than
session-auth gating to avoid the IDOR/login-loop-prone auth path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ersinkoc

packages/gateway/src/routes/openapi.test.ts

@@ -5,7 +5,7 @@
  * fake API endpoints and verifies the served spec covers them.
  */
 
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { Hono } from 'hono';
 import { registerOpenApiRoutes } from './openapi.js';
 
@@ -60,4 +60,32 @@ describe('OpenAPI routes', () => {
     expect(html).toContain('swagger-ui');
     expect(html).toContain('/openapi.json');
   });
+
+  describe('API-001 production gate', () => {
+    const prevEnv = process.env.NODE_ENV;
+    const prevFlag = process.env.ENABLE_API_DOCS;
+    afterEach(() => {
+      process.env.NODE_ENV = prevEnv;
+      if (prevFlag === undefined) delete process.env.ENABLE_API_DOCS;
+      else process.env.ENABLE_API_DOCS = prevFlag;
+    });
+
+    it('does not register docs in production by default', async () => {
+      process.env.NODE_ENV = 'production';
+      delete process.env.ENABLE_API_DOCS;
+      const prod = new Hono();
+      registerOpenApiRoutes(prod);
+      expect((await prod.request('/openapi.json')).status).toBe(404);
+      expect((await prod.request('/docs')).status).toBe(404);
+    });
+
+    it('registers docs in production when ENABLE_API_DOCS=true', async () => {
+      process.env.NODE_ENV = 'production';
+      process.env.ENABLE_API_DOCS = 'true';
+      const prod = new Hono();
+      registerOpenApiRoutes(prod);
+      expect((await prod.request('/openapi.json')).status).toBe(200);
+      expect((await prod.request('/docs')).status).toBe(200);
+    });
+  });
 });

packages/gateway/src/routes/openapi.ts

@@ -15,6 +15,16 @@ import { SWAGGER_UI_HTML } from '../openapi/swagger-html.js';
 import { VERSION } from '@ownpilot/core';
 
 export function registerOpenApiRoutes(app: Hono): void {
+  // API-001: the OpenAPI spec and Swagger UI disclose the entire API surface to
+  // anonymous callers. They are a development aid, so they are disabled in
+  // production unless an operator explicitly opts in via ENABLE_API_DOCS=true.
+  // Outside production they remain on for convenience. This deliberately avoids
+  // wiring docs into the session-auth model (which has had IDOR/login-loop
+  // regressions) — a hard on/off switch is the lower-risk control.
+  const docsEnabled =
+    process.env.NODE_ENV !== 'production' || process.env.ENABLE_API_DOCS === 'true';
+  if (!docsEnabled) return;
+
   let cached: OpenApiSpec | null = null;
 
   app.get('/openapi.json', (c) => {