feat: gate Swagger/OpenAPI docs endpoint in production

src/api.test.ts

@@ -72,12 +72,12 @@
   on: jest.fn(),
   once: jest.fn(),
   emit: jest.fn()
 } as any;
 
 const mockIngestManager = {
   load: jest.fn().mockResolvedValue(undefined),
   startPolling: jest.fn()
 } as any;
 
 describe('api', () => {
   it('responds with hello, world!', async () => {
@@ -144,3 +144,60 @@
     expect(csp).not.toContain("default-src 'none'");
   });
 });
+
+describe('Swagger docs gating', () => {
+  const buildServer = () =>
+    api({
+      title: 'my awesome service',
+      smbServerBaseUrl: 'http://localhost',
+      endpointIdleTimeout: '60',
+      publicHost: 'http://localhost',
+      dbManager: mockDbManager,
+      productionManager: mockProductionManager,
+      ingestManager: mockIngestManager,
+      coreFunctions: new CoreFunctions(
+        mockProductionManager,
+        new ConnectionQueue()
+      )
+    });
+
+  const originalNodeEnv = process.env.NODE_ENV;
+  const originalEnableSwagger = process.env.ENABLE_SWAGGER;
+
+  afterEach(() => {
+    if (originalNodeEnv === undefined) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = originalNodeEnv;
+    }
+    if (originalEnableSwagger === undefined) {
+      delete process.env.ENABLE_SWAGGER;
+    } else {
+      process.env.ENABLE_SWAGGER = originalEnableSwagger;
+    }
+  });
+
+  it('registers /api/docs by default (non-production)', async () => {
+    delete process.env.NODE_ENV;
+    delete process.env.ENABLE_SWAGGER;
+    const server = await buildServer();
+    const response = await server.inject({ method: 'GET', url: '/api/docs/' });
+    expect(response.statusCode).toBe(200);
+  });
+
+  it('does not register /api/docs when NODE_ENV=production', async () => {
+    process.env.NODE_ENV = 'production';
+    delete process.env.ENABLE_SWAGGER;
+    const server = await buildServer();
+    const response = await server.inject({ method: 'GET', url: '/api/docs/' });
+    expect(response.statusCode).toBe(404);
+  });
+
+  it('registers /api/docs in production when ENABLE_SWAGGER=true', async () => {
+    process.env.NODE_ENV = 'production';
+    process.env.ENABLE_SWAGGER = 'true';
+    const server = await buildServer();
+    const response = await server.inject({ method: 'GET', url: '/api/docs/' });
+    expect(response.statusCode).toBe(200);
+  });
+});

src/api.ts

@@ -117,22 +117,31 @@ export default async (opts: ApiOptions) => {
     global: false // Only apply to specific routes
   });
 
-  // register the swagger plugins, it will automagically do magic
-  api.register(swagger, {
-    swagger: {
-      info: {
-        title: opts.title,
-        description: 'Intercom Manager API',
-        version: 'v1'
+  // Gate the Swagger/OpenAPI docs so the full API surface is not exposed
+  // unauthenticated in production. The docs are registered when NOT running in
+  // production, or when explicitly opted in via ENABLE_SWAGGER=true (an escape
+  // hatch to enable the docs in a production deployment when desired).
+  const enableSwagger =
+    process.env.NODE_ENV !== 'production' ||
+    process.env.ENABLE_SWAGGER === 'true';
+  if (enableSwagger) {
+    // register the swagger plugins, it will automagically do magic
+    api.register(swagger, {
+      swagger: {
+        info: {
+          title: opts.title,
+          description: 'Intercom Manager API',
+          version: 'v1'
+        }
       }
-    }
-  });
-  api.register(swaggerUI, {
-    routePrefix: '/api/docs',
-    // Emit a CSP tailored to Swagger UI's own assets so the docs page keeps
-    // working under the strict global helmet CSP registered above.
-    staticCSP: true
-  });
+    });
+    api.register(swaggerUI, {
+      routePrefix: '/api/docs',
+      // Emit a CSP tailored to Swagger UI's own assets so the docs page keeps
+      // working under the strict global helmet CSP registered above.
+      staticCSP: true
+    });
+  }
 
   api.register(healthcheck, { title: opts.title });
   // register other API routes here