test: add DNS restriction enforcement tests (#1054)

* feat(api-proxy): add structured logging, metrics, and request tracing

- logging.js: structured JSON logging with request IDs (crypto.randomUUID),
  sanitizeForLog utility, zero external dependencies
- metrics.js: in-memory counters (requests_total, bytes), histograms
  (request_duration_ms with fixed buckets and percentile calculation),
  gauges (active_requests, uptime), memory-bounded
- server.js: replace all console.log/error with structured logger,
  instrument proxyRequest() with full metrics, add X-Request-ID header
  propagation, enhance /health with metrics_summary, add GET /metrics
  endpoint on port 10000

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

* feat(api-proxy): add sliding window rate limiter with CLI integration

Implement per-provider rate limiting for the API proxy sidecar:

- rate-limiter.js: Sliding window counter algorithm with 1-second
  granularity for RPM/bytes and 1-minute granularity for RPH.
  Per-provider independence, memory-bounded, fail-open on errors.

- server.js: Rate limit check before each proxyRequest() call.
  Returns 429 with Retry-After, X-RateLimit-* headers and JSON body.
  Rate limit status added to /health endpoint.

- CLI flags: --rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm,
  --no-rate-limit (all require --enable-api-proxy)

- TypeScript: RateLimitConfig interface in types.ts, env var passthrough
  in docker-manager.ts, validation in cli.ts

- Test runner: AwfOptions extended with rate limit fields

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

* ci: add API proxy unit tests to build workflow

Add Jest devDependency and test script to api-proxy package.json,
and add a CI step in build.yml to run container-level unit tests.

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

* test: add integration tests for api-proxy observability

Add two integration test files that verify the observability and rate
limiting features work end-to-end with actual Docker containers.

api-proxy-observability.test.ts:
- /metrics endpoint returns valid JSON with counters, histograms, gauges
- /health endpoint includes metrics_summary
- X-Request-ID header in proxy responses
- Metrics increment after API requests
- rate_limits appear in /health

api-proxy-rate-limit.test.ts:
- 429 response when RPM limit exceeded
- Retry-After header in 429 response
- X-RateLimit-* headers in 429 response
- --no-rate-limit flag disables limiting
- Custom RPM reflected in /health
- Rate limit metrics in /metrics after rejection

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

* test: extract buildRateLimitConfig and add coverage tests

Refactor rate limit validation into a standalone exported function
that can be tested independently. Adds 12 unit tests covering
defaults, --no-rate-limit, custom values, and validation errors.

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

* test: add --block-domains integration tests

Add blockDomains option to AwfRunner test fixture and integration tests
for the --block-domains deny-list feature:

- Block specific subdomain while allowing parent domain
- Block takes precedence over allow
- Wildcard blocking patterns (*.github.com)
- Multiple blocked domains
- Debug output verification

Closes #1041

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

* test: add DNS restriction enforcement tests

Add integration tests that verify DNS queries to non-whitelisted servers
are actually blocked by the --dns-servers flag, closing a gap where no
test used the dnsServers option in AwfRunner.

New tests verify:
- DNS queries to non-whitelisted servers are blocked
- DNS queries to whitelisted servers succeed
- The --dns-servers flag is passed through to iptables configuration
- Default DNS (8.8.8.8, 8.8.4.4) works without explicit --dns-servers
- Non-default DNS servers are blocked when using defaults
- Cloudflare DNS works when explicitly whitelisted

Closes #1043

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

* fix: address review feedback from Copilot

- Fix api-proxy Dockerfile to copy logging.js, metrics.js, rate-limiter.js
- Remove incomplete X-RateLimit headers test (covered by 429 test)
- Remove loose DNS test assertion that always matched "dns-test"
- Add CLI warning when rate limit flags used without --enable-api-proxy
- Fix rate-limiter.js comment to match actual algorithm (rolling window)
- Fix pre-existing cli.test.ts Commander.js parse failure

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

* test: add hasRateLimitOptions coverage to fix coverage regression

Extract rate limit option detection into testable hasRateLimitOptions()
function and add unit tests covering all branches.

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

* test: add validateApiProxyConfig copilot key coverage

Add tests for hasCopilotKey branch that was previously untested,
improving cli.ts line coverage.

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

* fix: restore rate limit options in awf-runner test helper

The merge with main incorrectly dropped the rate limit options
(rateLimitRpm, rateLimitRph, rateLimitBytesPm, noRateLimit) from
AwfOptions and both run/runWithSudo methods. These are needed by
api-proxy-rate-limit.test.ts on this branch.

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: Mossaka

src/cli.test.ts

@@ -351,7 +351,7 @@ describe('cli', () => {
         .option('--env-all', 'Pass all env vars', false);
 
       // Parse empty args to get defaults
-      program.parse(['node', 'awf'], { from: 'user' });
+      program.parse([], { from: 'user' });
       const opts = program.opts();
 
       expect(opts.logLevel).toBe('info');
@@ -1396,13 +1396,22 @@ describe('cli', () => {
       expect(result.debugMessages[0]).toContain('Anthropic');
     });
 
-    it('should detect both keys', () => {
-      const result = validateApiProxyConfig(true, true, true);
+    it('should detect Copilot key', () => {
+      const result = validateApiProxyConfig(true, false, false, true);
       expect(result.enabled).toBe(true);
       expect(result.warnings).toEqual([]);
-      expect(result.debugMessages).toHaveLength(2);
+      expect(result.debugMessages).toHaveLength(1);
+      expect(result.debugMessages[0]).toContain('Copilot');
+    });
+
+    it('should detect all three keys', () => {
+      const result = validateApiProxyConfig(true, true, true, true);
+      expect(result.enabled).toBe(true);
+      expect(result.warnings).toEqual([]);
+      expect(result.debugMessages).toHaveLength(3);
       expect(result.debugMessages[0]).toContain('OpenAI');
       expect(result.debugMessages[1]).toContain('Anthropic');
+      expect(result.debugMessages[2]).toContain('Copilot');
     });
 
     it('should not warn when disabled even with keys', () => {

src/cli.ts

@@ -371,6 +371,19 @@ export interface FlagValidationResult {
   error?: string;
 }
 
+/**
+ * Checks if any rate limit options are set in the CLI options.
+ * Used to warn when rate limit flags are provided without --enable-api-proxy.
+ */
+export function hasRateLimitOptions(options: {
+  rateLimitRpm?: string;
+  rateLimitRph?: string;
+  rateLimitBytesPm?: string;
+  rateLimit?: boolean;
+}): boolean {
+  return !!(options.rateLimitRpm || options.rateLimitRph || options.rateLimitBytesPm || options.rateLimit === false);
+}
+
 /**
  * Validates that --skip-pull is not used with --build-local
  * @param skipPull - Whether --skip-pull flag was provided

tests/integration/dns-servers.test.ts

@@ -10,7 +10,7 @@
 
 /// <reference path="../jest-custom-matchers.d.ts" />
 
-import { describe, test, expect, beforeAll, afterAll } from '@jest/globals';
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
 import { createRunner, AwfRunner } from '../fixtures/awf-runner';
 import { cleanup } from '../fixtures/cleanup';
 
@@ -113,3 +113,116 @@ describe('DNS Server Configuration', () => {
     expect(result.stdout.trim()).toMatch(/\d+\.\d+\.\d+\.\d+/);
   }, 120000);
 });
+
+describe('DNS Restriction Enforcement', () => {
+  let runner: AwfRunner;
+
+  beforeAll(async () => {
+    await cleanup(false);
+    runner = createRunner();
+  });
+
+  afterAll(async () => {
+    await cleanup(false);
+  });
+
+  // Clean up between each test to prevent container name conflicts
+  beforeEach(async () => {
+    await cleanup(false);
+  });
+
+  test('should block DNS queries to non-whitelisted servers', async () => {
+    // Only whitelist Google DNS (8.8.8.8) — Cloudflare (1.1.1.1) should be blocked
+    const result = await runner.runWithSudo(
+      'nslookup example.com 1.1.1.1',
+      {
+        allowDomains: ['example.com'],
+        dnsServers: ['8.8.8.8'],
+        logLevel: 'debug',
+        timeout: 60000,
+      }
+    );
+
+    // DNS query to non-whitelisted server should fail
+    expect(result).toFail();
+  }, 120000);
+
+  test('should allow DNS queries to whitelisted servers', async () => {
+    // Whitelist Google DNS (8.8.8.8) — queries to it should succeed
+    const result = await runner.runWithSudo(
+      'nslookup example.com 8.8.8.8',
+      {
+        allowDomains: ['example.com'],
+        dnsServers: ['8.8.8.8'],
+        logLevel: 'debug',
+        timeout: 60000,
+      }
+    );
+
+    expect(result).toSucceed();
+    expect(result.stdout).toContain('Address');
+  }, 120000);
+
+  test('should pass --dns-servers flag through to iptables configuration', async () => {
+    const result = await runner.runWithSudo(
+      'echo "dns-test"',
+      {
+        allowDomains: ['example.com'],
+        dnsServers: ['8.8.8.8'],
+        logLevel: 'debug',
+        timeout: 60000,
+      }
+    );
+
+    expect(result).toSucceed();
+    // Debug output should show the custom DNS server configuration
+    expect(result.stderr).toContain('8.8.8.8');
+  }, 120000);
+
+  test('should work with default DNS when --dns-servers is not specified', async () => {
+    // Without explicit dnsServers, default Google DNS (8.8.8.8, 8.8.4.4) should work
+    const result = await runner.runWithSudo(
+      'nslookup example.com',
+      {
+        allowDomains: ['example.com'],
+        logLevel: 'debug',
+        timeout: 60000,
+      }
+    );
+
+    expect(result).toSucceed();
+    expect(result.stdout).toContain('Address');
+  }, 120000);
+
+  test('should block DNS to non-default server when using defaults', async () => {
+    // With default DNS (8.8.8.8, 8.8.4.4), a query to a random DNS server
+    // like 208.67.222.222 (OpenDNS) should be blocked
+    const result = await runner.runWithSudo(
+      'nslookup example.com 208.67.222.222',
+      {
+        allowDomains: ['example.com'],
+        logLevel: 'debug',
+        timeout: 60000,
+      }
+    );
+
+    // DNS query to non-default server should fail
+    expect(result).toFail();
+  }, 120000);
+
+  test('should allow Cloudflare DNS when explicitly whitelisted', async () => {
+    // Whitelist Cloudflare DNS (1.1.1.1) — queries to it should succeed
+    const result = await runner.runWithSudo(
+      'nslookup example.com 1.1.1.1',
+      {
+        allowDomains: ['example.com'],
+        dnsServers: ['1.1.1.1'],
+        logLevel: 'debug',
+        timeout: 60000,
+      }
+    );
+
+    expect(result).toSucceed();
+    expect(result.stdout).toContain('Address');
+  }, 120000);
+});