@mcp-guardian/server 0.4.0 → 0.5.0

package/README.md

@@ -22,6 +22,7 @@ MCP Guardian scans your [Model Context Protocol](https://modelcontextprotocol.io
   - [One-Off Scan](#one-off-scan)
 - [CLI Reference](#cli-reference)
   - [`mcp-guardian proxy`](#mcp-guardian-proxy)
+  - [Policy Engine (v0.4+)](#policy-engine-v04)
   - [`mcp-guardian scan`](#mcp-guardian-scan)
   - [`mcp-guardian audit`](#mcp-guardian-audit)
   - [`mcp-guardian health`](#mcp-guardian-health)
@@ -30,6 +31,7 @@ MCP Guardian scans your [Model Context Protocol](https://modelcontextprotocol.io
   - [Available Tools](#available-tools)
   - [Available Resources & Prompts](#available-resources--prompts)
 - [CI/CD Integration](#cicd-integration)
+- [Production Deployment (K8s + Helm)](#production-deployment-k8s--helm)
 - [Docker](#docker)
 - [Architecture](#architecture)
   - [Data Flow (Proxy → DB → Audit)](#data-flow-proxy--db--audit)
@@ -38,6 +40,7 @@ MCP Guardian scans your [Model Context Protocol](https://modelcontextprotocol.io
 - [Pricing Models](#pricing-models)
 - [Environment Variables](#environment-variables)
 - [Development](#development)
+- [SECURITY.md](#securitymd)
 - [FAQ](#faq)
 - [Roadmap](#roadmap)
 - [License](#license)
@@ -50,10 +53,12 @@ As MCP adoption grows, so does the attack surface. MCP servers run arbitrary com
 
 MCP Guardian provides:
 
+- **Active policy enforcement (v0.4+)** — YAML-configurable policy engine that blocks, flags, or passes every `tools/call` in real time based on tool allowlists/denylists, regex patterns, rate limits, and token budgets
 - **Security auditing** — CVE scanning (OSV.dev + NVD), hardcoded secret detection, typo-squatting detection, command injection detection, and TLS validation
 - **Real cost tracking** — Proxy interceptor that captures actual `tools/call` traffic and counts tokens via `tiktoken` (o200k_base encoding) — no estimates, no mocks
 - **Health monitoring** — Live JSON-RPC 2.0 handshake probes with latency, success rate, tool count, and context pressure analysis
 - **Agent-native** — Runs as an MCP server so your AI assistant can self-audit its own infrastructure
+- **Enterprise SIEM logging (v0.4+)** — Structured JSON logs via pino with request-ID tracing, policy decision audit trails, and block events at WARN level
 
 ---
 
@@ -69,6 +74,7 @@ MCP Guardian provides:
 | **Typo-Squat Detection** | Levenshtein distance matching against 24 known official MCP packages |
 | **Secret Scanning** | 6 regex patterns for hardcoded API keys, tokens, private keys, passwords, GitHub tokens, OpenAI keys |
 | **Command Validation** | Flags dangerous patterns (path traversal, shell chaining, `rm -rf`, `curl`/`wget` in commands, and more) |
+| **🔴 Active Policy Engine (v0.4+)** | YAML-configurable rules: tool allowlist/denylist, regex pattern blocking, rate limiting, token budgets. Operates in `audit` (passive), `warn` (flag only), or `block` (active enforcement) modes |
 | **Scoring** | Weighted 0–100 security score with actionable recommendations |
 
 ### 💰 Cost Audit (`audit_costs`)
@@ -99,7 +105,7 @@ MCP Guardian provides:
 - **Graceful Shutdown** — SIGINT/SIGTERM handlers flush DB and close connections
 - **Batched DB Writes** — 1s debounced flush reduces I/O by 10x
 - **Alert Thresholds** — 6 CLI flags with exit codes 1/2 for CI/CD integration
-- **GitHub Actions CI** — Node 18/20/22 matrix, 63 tests across 10 suites
+- **GitHub Actions CI** — Node 18/20/22 matrix, 74 tests across 11 suites
 
 ---
 
@@ -192,15 +198,64 @@ mcp-guardian report --format markdown --output audit-report.md
 
 ### `mcp-guardian proxy`
 
-Start the MCP proxy interceptor to capture real token usage data. The proxy spawns all stdio MCP servers from config, then bridges stdin/stdout.
+Start the MCP proxy interceptor with optional active policy enforcement.
 
 ```bash
+# Audit-only (passive)
 mcp-guardian proxy --config ./cline_mcp_settings.json
+
+# Active blocking with default policy
+mcp-guardian proxy --config ./cline_mcp_settings.json --policy ./default-policy.yaml
+
+# Active blocking with custom policy + mode override
+mcp-guardian proxy --config ./cline_mcp_settings.json --policy ./my-policy.yaml --blocking-mode block
 ```
 
 | Option | Description |
 |---|---|
 | `-c, --config <path>` | Path to MCP config file |
+| `--policy <path>` | Path to policy YAML file (enables active blocking) |
+| `--blocking-mode <mode>` | Override policy mode: `audit` (passive), `warn` (flag), `block` (enforce) |
+
+### Policy Engine (v0.4+)
+
+The policy engine evaluates every intercepted `tools/call` before it reaches the MCP server. Define rules in YAML:
+
+```yaml
+# my-policy.yaml
+version: "1.0"
+policy:
+  mode: block
+  rules:
+    - name: "deny-shell-tools"
+      action: block
+      tools: { deny: ["execute_command", "bash", "sh", "eval", "exec"] }
+    - name: "block-injection"
+      action: block
+      patterns:
+        - "rm\\s+-rf"
+        - "curl\\s|wget\\s"
+        - ";\\s*\\w"
+        - "&&|\\|\\|"
+    - name: "rate-limit"
+      action: flag
+      maxCallsPerMinute: 60
+    - name: "token-budget"
+      action: flag
+      maxTokens: 50000
+```
+
+**Blocked calls** return a JSON-RPC 2.0 error to the client:
+```json
+{"jsonrpc":"2.0","id":"abc-123","error":{"code":-32001,"message":"Blocked by MCP Guardian policy: Tool 'execute_command' is explicitly denied"}}
+```
+
+**Policy modes:**
+| Mode | Behavior |
+|---|---|
+| `audit` | Pass all calls; log decisions only (passive) |
+| `warn` | Downgrade `block` actions to `flag`; log warnings |
+| `block` | Full active enforcement — blocked calls never reach the MCP server |
 
 ### `mcp-guardian scan`
 
@@ -349,6 +404,41 @@ Run MCP Guardian in CI to catch issues before deployment:
 
 ---
 
+## Production Deployment (K8s + Helm)
+
+See the full guide at **[deploy/PRODUCTION.md](deploy/PRODUCTION.md)**.
+
+### Quick Helm Install
+
+```bash
+# Install from local chart
+helm install mcp-guardian ./deploy/helm/mcp-guardian \
+  --set config.policy.mode=block \
+  --set config.mcpConfigPath=/etc/mcp-guardian/cline_mcp_settings.json
+
+# Or from the repo (future)
+helm repo add mcp-guardian https://rudraneel93.github.io/mcp-guardian
+helm install mcp-guardian mcp-guardian/mcp-guardian
+```
+
+### Key Features
+- **Helm chart** with ConfigMap-backed policies, PVC persistence, and safe defaults
+- **Fail-closed** by default (block traffic if proxy crashes) — configurable to fail-open
+- **Sidecar injection pattern** documented for stdio MCP servers
+- **Scaling guide** with CPU/memory recommendations per traffic level
+- **Pod Disruption Budget** for HA, anti-affinity for multi-AZ
+- **SIEM integration** via pino structured JSON logs (Splunk, Datadog, Elasticsearch)
+
+### Performance Overhead
+
+| Scenario | p50 | p99 | Overhead |
+|----------|-----|-----|----------|
+| Direct MCP (no proxy) | 5ms | 7ms | — |
+| Proxy (no policy) | 27ms | 77ms | +25.78ms |
+| Proxy (blocking policy) | 27ms | 74ms | +25.93ms |
+
+Policy engine adds **~0.15ms** — negligible. The ~26ms is Node.js child process stdio overhead.
+
 ## Docker
 
 A Docker image is available for running the proxy in containerized environments.
@@ -414,7 +504,7 @@ mcp-guardian/
 │       ├── scoring.ts              # Shared scoring utility
 │       └── logger.ts              # Colored console logger with log levels
 │
-tests/                              # 63 tests across 10 suites (Vitest)
+tests/                              # 74 tests across 11 suites (Vitest)
 ├── config-parser.test.ts
 ├── secret-scanner.test.ts
 ├── auth-prober.test.ts
@@ -541,7 +631,7 @@ npm install
 npm run dev          # Watch mode with tsx
 npm run build        # Compile TypeScript
 npm run lint         # Type check (tsc --noEmit)
-npm test             # 63 tests across 10 suites (Vitest)
+npm test             # 74 tests across 11 suites (Vitest)
 npm run test:watch   # Watch mode
 
 # Contributing
@@ -617,13 +707,20 @@ Token counting uses `tiktoken` with the `o200k_base` encoding (used by GPT-4o an
 - [x] Token-bucket rate limiter (OSV + NVD)
 - [x] TLS certificate validation
 - [x] Command injection validation (10 suspicious patterns)
-- [x] 63 unit tests (10 test suites)
+- [x] Active policy engine — YAML-based pass/block/flag with allowlists, regex, rate limiting, token budgets
+- [x] Structured JSON logging (pino) for SIEM ingestion
+- [x] STRIDE threat model (SECURITY.md)
+- [x] 74 tests (11 suites)
 - [x] GitHub Actions CI (Node 18/20/22 matrix)
+- [x] Performance benchmarks (p50: 5ms baseline, +25.78ms proxy overhead, +0.15ms policy)
+- [x] Helm chart + production deployment guide (K8s, fail-open/closed, sidecar pattern, scaling)
 - [x] Published to npm as [`@mcp-guardian/server`](https://www.npmjs.com/package/@mcp-guardian/server)
+- [ ] OPA integration for Rego policies
+- [ ] OAuth 2.1 / OIDC proxy authentication
 - [ ] Web dashboard for historical trends
-- [ ] Slack/Discord alerting integration
-- [ ] Custom CVE feed support
-- [ ] Multi-user proxy mode
+- [ ] Slack/Discord alerting
+- [ ] Prometheus metrics endpoint
+- [ ] Multi-user proxy
 
 ---
 

package/dist/auth/auth-types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * OAuth 2.1 / OIDC authentication types for MCP Guardian proxy.
+ */
+export interface AuthConfig {
+    /** OIDC issuer URL (e.g., https://accounts.google.com) */
+    issuer: string;
+    /** Expected audience claim in JWT */
+    audience: string;
+    /** Whether authentication is required (fail-closed) or optional (fail-open) */
+    required: boolean;
+    /** JWKS URI override (default: auto-discovered from issuer) */
+    jwksUri?: string;
+    /** Clock tolerance in seconds for JWT validation */
+    clockTolerance?: number;
+}
+export interface AgentIdentity {
+    /** Subject claim (sub) — unique agent identifier */
+    sub: string;
+    /** Client ID from the token */
+    clientId?: string;
+    /** Scopes granted to this agent */
+    scopes?: string[];
+    /** Issuer of the token */
+    issuer: string;
+    /** Token expiry timestamp */
+    expiresAt?: number;
+}
+export interface AuthValidationResult {
+    valid: boolean;
+    identity?: AgentIdentity;
+    error?: string;
+}
+export interface OIDCDiscovery {
+    issuer: string;
+    jwks_uri: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    scopes_supported?: string[];
+}
+//# sourceMappingURL=auth-types.d.ts.map

package/dist/auth/auth-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-types.d.ts","sourceRoot":"","sources":["../../src/auth/auth-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,UAAU;IACzB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B"}

package/dist/auth/auth-types.js

@@ -0,0 +1,5 @@
+/**
+ * OAuth 2.1 / OIDC authentication types for MCP Guardian proxy.
+ */
+export {};
+//# sourceMappingURL=auth-types.js.map

package/dist/auth/auth-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-types.js","sourceRoot":"","sources":["../../src/auth/auth-types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/auth/dashboard-auth.d.ts

@@ -0,0 +1,97 @@
+export interface AuthResult {
+    authenticated: boolean;
+    reason?: string;
+    identity?: string;
+}
+export interface DashboardAuthConfig {
+    /** Enable authentication on dashboard API */
+    enabled: boolean;
+    /** Pre-shared API key (simplest auth) */
+    apiKey?: string;
+    /** JWT HMAC secret for session tokens */
+    jwtSecret?: string;
+    /** Session token expiry in seconds */
+    sessionTtlSeconds: number;
+    /** Allowed origins for CORS/CSRF validation */
+    allowedOrigins: string[];
+    /** Maximum login attempts per minute per IP */
+    maxLoginAttemptsPerMinute: number;
+}
+/**
+ * DashboardAuth provides authentication for the dashboard HTTP server.
+ *
+ * Two modes:
+ * 1. API Key: Set DASHBOARD_API_KEY, pass as ?api_key=<key> or Authorization: Bearer <key>
+ * 2. JWT Sessions: Set DASHBOARD_JWT_SECRET, POST /api/login with credentials
+ */
+export declare class DashboardAuth {
+    private config;
+    private loginRateMap;
+    private activeTokens;
+    private cleanupInterval;
+    constructor(config?: Partial<DashboardAuthConfig>);
+    /**
+     * Authenticate a dashboard HTTP request.
+     * Checks multiple sources:
+     * 1. ?api_key=<key> query parameter
+     * 2. Authorization: Bearer <token> header
+     * 3. X-API-Key: <key> header
+     */
+    authenticate(req: {
+        url?: string;
+        headers?: Record<string, string | string[] | undefined>;
+        method?: string;
+    }): AuthResult;
+    /**
+     * Handle a login attempt. Creates a session token if credentials are valid.
+     * Credentials are validated against DASHBOARD_USERNAME / DASHBOARD_PASSWORD env vars.
+     */
+    login(req: {
+        url?: string;
+        headers?: Record<string, string | string[] | undefined>;
+        body?: {
+            username?: string;
+            password?: string;
+            api_key?: string;
+        };
+        ip?: string;
+    }): {
+        success: boolean;
+        token?: string;
+        error?: string;
+    };
+    /**
+     * Revoke a session token (logout).
+     */
+    logout(token: string): void;
+    /**
+     * Generate login page HTML (serves at /login when JWT auth is enabled).
+     */
+    getLoginPageHtml(error?: string): string;
+    /**
+     * Check if auth is enabled and required.
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if JWT session-based auth is configured (vs API key only).
+     */
+    hasJwtSessionAuth(): boolean;
+    /**
+     * Create a signed HMAC session token.
+     */
+    private createSessionToken;
+    /**
+     * Timing-safe string comparison to prevent timing attacks on API keys.
+     */
+    private timingSafeCompare;
+    /**
+     * Validate CSRF protection via Origin/Referer headers.
+     */
+    private validateCsrf;
+    private isAllowedOrigin;
+    private checkLoginRate;
+    private normalizeHeaders;
+    private cleanupRateMap;
+    dispose(): void;
+}
+//# sourceMappingURL=dashboard-auth.d.ts.map

package/dist/auth/dashboard-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-auth.d.ts","sourceRoot":"","sources":["../../src/auth/dashboard-auth.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,+CAA+C;IAC/C,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAUD;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,YAAY,CAA0C;IAC9D,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,eAAe,CAA+C;gBAE1D,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IA4BjD;;;;;;OAMG;IACH,YAAY,CAAC,GAAG,EAAE;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;QACxD,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,UAAU;IAyDd;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE;QACT,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;QACxD,IAAI,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAClE,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAuDxD;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI3B;;OAEG;IACH,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAyCxC;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAmB1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,cAAc;IAOtB,OAAO,IAAI,IAAI;CAKhB"}

package/dist/auth/dashboard-auth.js

@@ -0,0 +1,319 @@
+/**
+ * Dashboard Authentication Middleware
+ *
+ * Provides JWT-based authentication for the dashboard HTTP API.
+ * Supports:
+ * - API key authentication (simple, internal deployments)
+ * - JWT session tokens (for multi-user deployments)
+ * - CSRF protection via Origin/Referer validation
+ * - Rate limiting on auth endpoints
+ * - Login endpoint with configurable credential source
+ *
+ * Enable with: DASHBOARD_AUTH_ENABLED=true
+ * Configure API key: DASHBOARD_API_KEY=<key>
+ * Configure JWT secret: DASHBOARD_JWT_SECRET=<secret>
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
+import { Logger } from '../utils/logger.js';
+import { StructuredLogger } from '../utils/structured-logger.js';
+/**
+ * DashboardAuth provides authentication for the dashboard HTTP server.
+ *
+ * Two modes:
+ * 1. API Key: Set DASHBOARD_API_KEY, pass as ?api_key=<key> or Authorization: Bearer <key>
+ * 2. JWT Sessions: Set DASHBOARD_JWT_SECRET, POST /api/login with credentials
+ */
+export class DashboardAuth {
+    config;
+    loginRateMap = new Map();
+    activeTokens = new Set();
+    cleanupInterval = null;
+    constructor(config) {
+        const enabled = process.env['DASHBOARD_AUTH_ENABLED'] === 'true';
+        this.config = {
+            enabled: config?.enabled ?? enabled,
+            apiKey: config?.apiKey ?? process.env['DASHBOARD_API_KEY'] ?? undefined,
+            jwtSecret: config?.jwtSecret ?? process.env['DASHBOARD_JWT_SECRET'] ?? undefined,
+            sessionTtlSeconds: config?.sessionTtlSeconds ?? 3600,
+            allowedOrigins: config?.allowedOrigins ?? (process.env['DASHBOARD_ALLOWED_ORIGINS']
+                ? process.env['DASHBOARD_ALLOWED_ORIGINS'].split(',').map(s => s.trim())
+                : ['http://localhost:4000', 'http://localhost:3000', 'http://127.0.0.1:4000']),
+            maxLoginAttemptsPerMinute: config?.maxLoginAttemptsPerMinute ?? 5,
+        };
+        if (this.config.enabled && this.config.apiKey) {
+            Logger.info('[dashboard-auth] API key authentication enabled');
+        }
+        else if (this.config.enabled && this.config.jwtSecret) {
+            Logger.info('[dashboard-auth] JWT session authentication enabled');
+        }
+        else if (this.config.enabled) {
+            Logger.warn('[dashboard-auth] Auth enabled but no API key or JWT secret configured');
+        }
+        // Periodic cleanup of rate limit entries
+        if (this.config.enabled) {
+            this.cleanupInterval = setInterval(() => this.cleanupRateMap(), 60000);
+        }
+    }
+    /**
+     * Authenticate a dashboard HTTP request.
+     * Checks multiple sources:
+     * 1. ?api_key=<key> query parameter
+     * 2. Authorization: Bearer <token> header
+     * 3. X-API-Key: <key> header
+     */
+    authenticate(req) {
+        if (!this.config.enabled) {
+            return { authenticated: true, identity: 'anonymous' };
+        }
+        const url = req.url || '/';
+        const headers = this.normalizeHeaders(req.headers || {});
+        // ── CSRF check for mutating requests ──
+        if (req.method && ['POST', 'PUT', 'DELETE', 'PATCH'].includes(req.method)) {
+            const csrfResult = this.validateCsrf(headers);
+            if (!csrfResult.authenticated)
+                return csrfResult;
+        }
+        // ── Check query param API key ──
+        try {
+            const urlObj = new URL(url, 'http://localhost');
+            const queryKey = urlObj.searchParams.get('api_key');
+            if (queryKey && this.config.apiKey) {
+                if (this.timingSafeCompare(queryKey, this.config.apiKey)) {
+                    return { authenticated: true, identity: 'api_key' };
+                }
+            }
+        }
+        catch {
+            // Malformed URL — continue to other auth methods
+        }
+        // ── Check Authorization header ──
+        const authHeader = headers['authorization'];
+        if (authHeader) {
+            const bearerMatch = authHeader.match(/^Bearer\s+(.+)$/i);
+            if (bearerMatch) {
+                const token = bearerMatch[1];
+                // Check if it's the API key
+                if (this.config.apiKey && this.timingSafeCompare(token, this.config.apiKey)) {
+                    return { authenticated: true, identity: 'api_key' };
+                }
+                // Check if it's a valid session token
+                if (this.activeTokens.has(token)) {
+                    return { authenticated: true, identity: 'session' };
+                }
+            }
+        }
+        // ── Check X-API-Key header ──
+        const apiKeyHeader = headers['x-api-key'];
+        if (apiKeyHeader && this.config.apiKey) {
+            if (this.timingSafeCompare(apiKeyHeader, this.config.apiKey)) {
+                return { authenticated: true, identity: 'api_key' };
+            }
+        }
+        return { authenticated: false, reason: 'No valid authentication provided' };
+    }
+    /**
+     * Handle a login attempt. Creates a session token if credentials are valid.
+     * Credentials are validated against DASHBOARD_USERNAME / DASHBOARD_PASSWORD env vars.
+     */
+    login(req) {
+        if (!this.config.enabled || !this.config.jwtSecret) {
+            return { success: false, error: 'JWT auth not configured. Set DASHBOARD_JWT_SECRET.' };
+        }
+        // ── Rate limit login attempts ──
+        const ip = req.ip || 'unknown';
+        if (!this.checkLoginRate(ip)) {
+            StructuredLogger.info({
+                event: 'dashboard_login_rate_limited',
+                ip,
+            });
+            return { success: false, error: 'Too many login attempts. Try again later.' };
+        }
+        const body = req.body || {};
+        // Check API key shortcut
+        if (body.api_key && this.config.apiKey && this.timingSafeCompare(body.api_key, this.config.apiKey)) {
+            const token = this.createSessionToken();
+            Logger.info(`[dashboard-auth] Login via API key from ${ip}`);
+            return { success: true, token };
+        }
+        // Check username/password
+        const expectedUsername = process.env['DASHBOARD_USERNAME'];
+        const expectedPassword = process.env['DASHBOARD_PASSWORD'];
+        if (!expectedUsername || !expectedPassword) {
+            return { success: false, error: 'Login credentials not configured on server. Set DASHBOARD_USERNAME and DASHBOARD_PASSWORD.' };
+        }
+        if (body.username === expectedUsername &&
+            body.password &&
+            this.timingSafeCompare(body.password, expectedPassword)) {
+            const token = this.createSessionToken();
+            StructuredLogger.info({
+                event: 'dashboard_login',
+                ip,
+                identity: body.username,
+            });
+            return { success: true, token };
+        }
+        StructuredLogger.info({
+            event: 'dashboard_login_failed',
+            ip,
+            identity: body.username || 'unknown',
+        });
+        return { success: false, error: 'Invalid credentials' };
+    }
+    /**
+     * Revoke a session token (logout).
+     */
+    logout(token) {
+        this.activeTokens.delete(token);
+    }
+    /**
+     * Generate login page HTML (serves at /login when JWT auth is enabled).
+     */
+    getLoginPageHtml(error) {
+        const errorHtml = error ? `<div style="color:#f85149;margin-bottom:16px;padding:8px;background:#3d1f1f;border-radius:6px;">${error}</div>` : '';
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>MCP Guardian — Login</title>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif; background: #0d1117; color: #c9d1d9; display: flex; justify-content: center; align-items: center; min-height: 100vh; }
+.container { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 32px; width: 100%; max-width: 400px; }
+h1 { font-size: 20px; color: #58a6ff; margin-bottom: 8px; }
+h2 { font-size: 14px; color: #8b949e; margin-bottom: 24px; }
+label { display: block; font-size: 13px; color: #8b949e; margin-bottom: 4px; margin-top: 12px; }
+input { width: 100%; padding: 8px 12px; background: #0d1117; border: 1px solid #30363d; border-radius: 6px; color: #c9d1d9; font-size: 14px; }
+input:focus { outline: none; border-color: #58a6ff; }
+button { width: 100%; padding: 10px; background: #238636; color: #fff; border: none; border-radius: 6px; font-size: 14px; cursor: pointer; margin-top: 20px; }
+button:hover { background: #2ea043; }
+.footer { font-size: 12px; color: #8b949e; margin-top: 16px; text-align: center; }
+</style>
+</head>
+<body>
+<div class="container">
+<h1>🛡️ MCP Guardian</h1>
+<h2>Dashboard Authentication</h2>
+${errorHtml}
+<form method="POST" action="/api/login">
+<label for="username">Username</label>
+<input type="text" id="username" name="username" required autofocus>
+<label for="password">Password</label>
+<input type="password" id="password" name="password" required>
+<button type="submit">Sign In</button>
+</form>
+<div class="footer">Internal deployment — authorized access only</div>
+</div>
+</body>
+</html>`;
+    }
+    /**
+     * Check if auth is enabled and required.
+     */
+    isEnabled() {
+        return this.config.enabled && !!(this.config.apiKey || this.config.jwtSecret);
+    }
+    /**
+     * Check if JWT session-based auth is configured (vs API key only).
+     */
+    hasJwtSessionAuth() {
+        return this.config.enabled && !!this.config.jwtSecret;
+    }
+    /**
+     * Create a signed HMAC session token.
+     */
+    createSessionToken() {
+        const payload = Buffer.from(JSON.stringify({
+            iat: Math.floor(Date.now() / 1000),
+            jti: randomBytes(16).toString('hex'),
+        })).toString('base64url');
+        const signature = createHmac('sha256', this.config.jwtSecret || randomBytes(32).toString('hex'))
+            .update(payload)
+            .digest('base64url');
+        const token = `${payload}.${signature}`;
+        this.activeTokens.add(token);
+        // Auto-expire after TTL
+        setTimeout(() => this.activeTokens.delete(token), this.config.sessionTtlSeconds * 1000);
+        return token;
+    }
+    /**
+     * Timing-safe string comparison to prevent timing attacks on API keys.
+     */
+    timingSafeCompare(a, b) {
+        if (a.length !== b.length)
+            return false;
+        const bufA = Buffer.from(a, 'utf-8');
+        const bufB = Buffer.from(b, 'utf-8');
+        return timingSafeEqual(bufA, bufB);
+    }
+    /**
+     * Validate CSRF protection via Origin/Referer headers.
+     */
+    validateCsrf(headers) {
+        const origin = headers['origin'];
+        const referer = headers['referer'];
+        // If both are missing and we're strict, could block
+        // For now, only validate when present
+        if (origin) {
+            if (!this.isAllowedOrigin(origin)) {
+                return { authenticated: false, reason: `Origin '${origin}' not allowed` };
+            }
+        }
+        if (referer) {
+            try {
+                const refererOrigin = new URL(referer).origin;
+                if (!this.isAllowedOrigin(refererOrigin)) {
+                    return { authenticated: false, reason: `Referer origin '${refererOrigin}' not allowed` };
+                }
+            }
+            catch {
+                // Malformed referer — allow through
+            }
+        }
+        return { authenticated: true };
+    }
+    isAllowedOrigin(origin) {
+        return this.config.allowedOrigins.some(allowed => {
+            if (allowed === '*')
+                return true;
+            if (allowed === origin)
+                return true;
+            return false;
+        });
+    }
+    checkLoginRate(ip) {
+        const now = Date.now();
+        let entry = this.loginRateMap.get(ip);
+        if (!entry || now > entry.resetAt) {
+            entry = { count: 1, resetAt: now + 60000 };
+            this.loginRateMap.set(ip, entry);
+            return true;
+        }
+        entry.count++;
+        return entry.count <= this.config.maxLoginAttemptsPerMinute;
+    }
+    normalizeHeaders(headers) {
+        const result = {};
+        for (const [key, value] of Object.entries(headers)) {
+            if (Array.isArray(value))
+                result[key.toLowerCase()] = value[0] || '';
+            else if (value !== undefined)
+                result[key.toLowerCase()] = value;
+        }
+        return result;
+    }
+    cleanupRateMap() {
+        const now = Date.now();
+        for (const [ip, entry] of this.loginRateMap) {
+            if (now > entry.resetAt)
+                this.loginRateMap.delete(ip);
+        }
+    }
+    dispose() {
+        if (this.cleanupInterval)
+            clearInterval(this.cleanupInterval);
+        this.activeTokens.clear();
+        this.loginRateMap.clear();
+    }
+}
+//# sourceMappingURL=dashboard-auth.js.map