@getaegis/cli 0.8.0 → 0.9.0

package/dist/gate/gate.js

@@ -0,0 +1,1243 @@
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { createLogger, generateRequestId } from '../logger/index.js';
+import { buildPolicyMap, evaluatePolicy, loadPoliciesFromDirectory } from '../policy/index.js';
+import { VERSION } from '../version.js';
+import { BodyInspector } from './body-inspector.js';
+import { parseRateLimit, RateLimiter } from './rate-limiter.js';
+// ─── Scope → HTTP Method Mapping ─────────────────────────────────────────────
+// Credential scopes restrict which HTTP methods are permitted.
+//   "read"  → GET, HEAD, OPTIONS  (safe/idempotent methods)
+//   "write" → POST, PUT, PATCH, DELETE  (state-changing methods)
+//   "*"     → all methods (default)
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/**
+ * Check whether an HTTP method is permitted by a credential's scopes.
+ * Returns true if the method is allowed, false if blocked.
+ */
+export function methodMatchesScope(method, scopes) {
+    if (scopes.includes('*'))
+        return true;
+    const upper = method.toUpperCase();
+    if (scopes.includes('read') && READ_METHODS.has(upper))
+        return true;
+    if (scopes.includes('write') && WRITE_METHODS.has(upper))
+        return true;
+    return false;
+}
+/**
+ * Aegis Gate — HTTP proxy that sits between an AI agent and external APIs.
+ *
+ * The agent makes requests to: http://localhost:{port}/{service}/actual/api/path
+ * Gate resolves the service → looks up credential → injects auth → forwards to real API.
+ *
+ * The agent NEVER sees the credential.
+ */
+export class Gate {
+    server = null;
+    vault;
+    ledger;
+    port;
+    logger;
+    tlsOptions;
+    testUpstream;
+    rateLimiter;
+    bodyInspector;
+    shuttingDown = false;
+    activeRequests = 0;
+    shutdownTimeoutMs;
+    agentRegistry;
+    requireAgentAuth;
+    policyMap;
+    policyMode;
+    policyDir;
+    policyWatcher;
+    metrics;
+    webhooks;
+    onAuditEntry;
+    maxBodySize;
+    requestTimeout;
+    maxConnectionsPerAgent;
+    /** Tracks in-flight request count per agent (keyed by agent ID). */
+    agentConnections = new Map();
+    /** Tracks upstream service failures for circuit breaker (keyed by service name). */
+    circuitBreaker = new Map();
+    /** Dedicated HTTP agent for outbound proxy requests (connection pooling with keep-alive). */
+    httpAgent;
+    /** Dedicated HTTPS agent for outbound proxy requests (connection pooling with keep-alive + TLS session reuse). */
+    httpsAgent;
+    constructor(options) {
+        this.vault = options.vault;
+        this.ledger = options.ledger;
+        this.port = options.port;
+        this.logger = createLogger({
+            module: 'gate',
+            level: options.logLevel ?? 'info',
+        });
+        this.tlsOptions = options.tls;
+        this.testUpstream = options._testUpstream;
+        this.rateLimiter = new RateLimiter();
+        this.bodyInspector = new BodyInspector();
+        this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? 10_000;
+        this.agentRegistry = options.agentRegistry;
+        this.requireAgentAuth = options.requireAgentAuth ?? true;
+        this.policyMode = options.policyMode ?? 'enforce';
+        this.policyDir = options.policyDir;
+        this.metrics = options.metrics;
+        this.webhooks = options.webhooks;
+        this.onAuditEntry = options.onAuditEntry;
+        this.maxBodySize = options.maxBodySize ?? 1_048_576; // 1 MB
+        this.requestTimeout = options.requestTimeout ?? 30_000; // 30 seconds
+        this.maxConnectionsPerAgent = options.maxConnectionsPerAgent ?? 50;
+        // Dedicated connection pool agents for outbound proxy requests.
+        // keepAlive: true  — reuse TCP connections across requests (avoids TCP+TLS handshake per request)
+        // maxSockets: 256  — cap concurrent sockets per upstream host (prevents socket exhaustion)
+        // maxFreeSockets: 64 — keep up to 64 idle sockets per host in the pool
+        // scheduling: 'lifo' — reuse most-recent socket first (reduces stale connection risk)
+        // timeout: 60s — idle socket timeout (close sockets unused for 60s)
+        const poolOptions = {
+            keepAlive: true,
+            maxSockets: 256,
+            maxFreeSockets: 64,
+            scheduling: 'lifo',
+            timeout: 60_000,
+        };
+        this.httpAgent = new http.Agent(poolOptions);
+        this.httpsAgent = new https.Agent(poolOptions);
+        // Load policies from disk or test injection
+        if (options._testPolicies) {
+            this.policyMap = options._testPolicies;
+        }
+        else if (options.policyDir) {
+            this.policyMap = this.loadPolicies(options.policyDir);
+        }
+        else {
+            this.policyMap = new Map();
+        }
+    }
+    /**
+     * Start the Gate proxy server.
+     */
+    /**
+     * Whether the Gate is running with TLS.
+     */
+    get isTls() {
+        return this.tlsOptions !== undefined;
+    }
+    /**
+     * Whether policies are loaded and active.
+     */
+    get hasPolicies() {
+        return this.policyMap.size > 0;
+    }
+    /**
+     * The current policy enforcement mode.
+     */
+    get currentPolicyMode() {
+        return this.policyMode;
+    }
+    /**
+     * Load policies from a directory.
+     */
+    loadPolicies(dir) {
+        try {
+            const results = loadPoliciesFromDirectory(dir);
+            const map = buildPolicyMap(results);
+            const valid = results.filter((r) => r.valid).length;
+            const invalid = results.filter((r) => !r.valid).length;
+            this.logger.info({ dir, valid, invalid }, `Loaded ${valid} policy file(s)`);
+            return map;
+        }
+        catch (err) {
+            this.logger.warn({ dir, err }, 'Failed to load policies');
+            return new Map();
+        }
+    }
+    /**
+     * Reload policies from the configured directory.
+     * Called on file system changes for hot-reload.
+     */
+    reloadPolicies() {
+        if (!this.policyDir)
+            return;
+        this.policyMap = this.loadPolicies(this.policyDir);
+        this.logger.info({ count: this.policyMap.size }, 'Policies reloaded');
+    }
+    /**
+     * Start watching the policy directory for changes (hot-reload).
+     * Debounces changes to avoid rapid reloads.
+     */
+    startPolicyWatcher() {
+        if (!this.policyDir)
+            return;
+        let debounceTimer = null;
+        try {
+            this.policyWatcher = fs.watch(this.policyDir, { persistent: false }, () => {
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(() => {
+                    this.logger.info('Policy files changed — reloading');
+                    this.reloadPolicies();
+                }, 500);
+            });
+        }
+        catch (err) {
+            this.logger.warn({ err }, 'Could not watch policy directory');
+        }
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            const handler = (req, res) => {
+                this.handleRequest(req, res);
+            };
+            if (this.tlsOptions) {
+                // Validate TLS files before attempting to create the server
+                for (const [label, filePath] of [
+                    ['certificate', this.tlsOptions.certPath],
+                    ['private key', this.tlsOptions.keyPath],
+                ]) {
+                    if (!fs.existsSync(filePath)) {
+                        throw new Error(`TLS ${label} file not found: ${filePath}`);
+                    }
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    const expectedMarker = label === 'certificate' ? '-----BEGIN CERTIFICATE-----' : '-----BEGIN';
+                    if (!content.includes(expectedMarker)) {
+                        throw new Error(`TLS ${label} file is not valid PEM format: ${filePath}\n` +
+                            `  Expected a PEM file starting with "${expectedMarker}".\n` +
+                            `  Generate a self-signed cert with:\n` +
+                            `  openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'`);
+                    }
+                }
+                const cert = fs.readFileSync(this.tlsOptions.certPath);
+                const key = fs.readFileSync(this.tlsOptions.keyPath);
+                this.server = https.createServer({ cert, key }, handler);
+            }
+            else {
+                this.server = http.createServer(handler);
+                this.logger.warn('Gate is running without TLS — credentials are transmitted in cleartext on localhost');
+            }
+            // Handle server errors (e.g. EADDRINUSE) before they become unhandled events
+            this.server.once('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    reject(new Error(`Port ${this.port} is already in use.\n` +
+                        `  Another process (or another Aegis instance) is using this port.\n` +
+                        `  Either stop that process or use a different port:\n` +
+                        `    aegis gate --port <port>`));
+                }
+                else {
+                    reject(err);
+                }
+            });
+            this.server.listen(this.port, () => {
+                // Update port in case 0 was passed (OS-assigned)
+                const addr = this.server?.address();
+                if (addr && typeof addr === 'object') {
+                    this.port = addr.port;
+                }
+                // Set server-level idle timeout to defend against slowloris attacks.
+                // Only covers idle socket time — outbound proxy has its own `timeout` option.
+                // Provide a custom callback so the default auto-destroy doesn't kill sockets
+                // that are legitimately waiting for upstream responses.
+                this.server?.setTimeout(this.requestTimeout, (socket) => {
+                    socket.destroy();
+                });
+                const protocol = this.tlsOptions ? 'https' : 'http';
+                this.logger.info({ protocol, port: this.port }, `Aegis Gate listening on ${protocol}://localhost:${this.port}`);
+                this.logger.info({ port: this.port }, 'Agent requests → localhost:{port}/{service}/path → credential injected → forwarded');
+                if (this.policyMap.size > 0) {
+                    this.logger.info({ count: this.policyMap.size, mode: this.policyMode }, 'Policy engine active');
+                    this.startPolicyWatcher();
+                }
+                resolve();
+            });
+        });
+    }
+    /**
+     * The port the server is listening on (may differ from constructor if 0 was passed).
+     */
+    get listeningPort() {
+        return this.port;
+    }
+    /**
+     * Stop the Gate proxy server gracefully.
+     *
+     * 1. Sets `shuttingDown = true` — new requests receive 503 Service Unavailable.
+     * 2. Waits for in-flight requests to complete (up to `shutdownTimeoutMs`).
+     * 3. Closes the server socket and returns.
+     *
+     * During the drain phase the server still accepts connections so clients get
+     * a clean 503 rather than a connection-refused error.
+     */
+    stop() {
+        this.shuttingDown = true;
+        // Stop watching policy files
+        if (this.policyWatcher) {
+            this.policyWatcher.close();
+            this.policyWatcher = undefined;
+        }
+        return new Promise((resolve) => {
+            if (!this.server) {
+                this.httpAgent.destroy();
+                this.httpsAgent.destroy();
+                resolve({ drained: true, activeAtClose: 0 });
+                return;
+            }
+            const finish = (drained) => {
+                const activeAtClose = this.activeRequests;
+                // Destroy connection pool agents — close all keep-alive sockets
+                this.httpAgent.destroy();
+                this.httpsAgent.destroy();
+                if (!drained) {
+                    // Force-destroy remaining connections so server.close() can complete
+                    this.server?.closeAllConnections();
+                }
+                this.server?.close(() => {
+                    // shuttingDown stays true — a stopped Gate is permanently shut down.
+                    // Outbound proxy requests may still error asynchronously; keeping
+                    // shuttingDown=true ensures error handlers skip Ledger writes.
+                    this.server = null;
+                    resolve({ drained, activeAtClose });
+                });
+            };
+            // If no active requests, shut down immediately
+            if (this.activeRequests === 0) {
+                this.logger.info('No in-flight requests — shutting down immediately');
+                finish(true);
+                return;
+            }
+            this.logger.info({ activeRequests: this.activeRequests }, 'Draining in-flight requests');
+            // Poll for active requests to reach 0
+            const drainInterval = setInterval(() => {
+                if (this.activeRequests === 0) {
+                    clearInterval(drainInterval);
+                    clearTimeout(forceTimeout);
+                    this.logger.info('All in-flight requests drained — shutdown complete');
+                    finish(true);
+                }
+            }, 50);
+            // Force-close after timeout
+            const forceTimeout = setTimeout(() => {
+                clearInterval(drainInterval);
+                this.logger.warn({ timeoutMs: this.shutdownTimeoutMs, activeRequests: this.activeRequests }, 'Shutdown timeout — forcing close');
+                finish(false);
+            }, this.shutdownTimeoutMs);
+        });
+    }
+    /**
+     * Whether the Gate is currently shutting down (draining in-flight requests).
+     */
+    get isShuttingDown() {
+        return this.shuttingDown;
+    }
+    /**
+     * The number of currently in-flight requests.
+     */
+    get inFlightRequests() {
+        return this.activeRequests;
+    }
+    async handleRequest(req, res) {
+        // Reject new requests during shutdown
+        if (this.shuttingDown) {
+            res.writeHead(503, { 'Content-Type': 'application/json' });
+            res.end(`${JSON.stringify({ error: 'Aegis Gate is shutting down' })}\n`);
+            return;
+        }
+        this.activeRequests++;
+        const decrementActive = () => {
+            this.activeRequests = Math.max(0, this.activeRequests - 1);
+        };
+        // Ensure we decrement when the response finishes (or the connection drops)
+        res.on('close', decrementActive);
+        // Create a per-request child logger with a correlation ID
+        const requestId = generateRequestId();
+        const reqLog = this.logger.child({ requestId });
+        try {
+            // Parse path segments from the RAW URL (not via new URL()) to prevent
+            // percent-encoded path traversal. new URL() normalises %2e%2e → .. and
+            // resolves /../, which would let an agent escape service routing and
+            // reach internal /_aegis/* endpoints via /service/%2e%2e/_aegis/health.
+            const rawUrl = req.url ?? '/';
+            const qIdx = rawUrl.indexOf('?');
+            const rawPath = qIdx >= 0 ? rawUrl.slice(0, qIdx) : rawUrl;
+            const rawQuery = qIdx >= 0 ? rawUrl.slice(qIdx) : '';
+            const pathParts = rawPath.split('/').filter(Boolean);
+            // Explicit path traversal guard: reject any segment that decodes to
+            // ".." or "." — belt-and-suspenders defense on top of raw parsing.
+            // The service lookup would naturally reject these, but blocking here
+            // produces a clear 400 and audit trail entry for traversal attempts.
+            const hasTraversal = pathParts.some((seg) => {
+                if (seg === '..' || seg === '.')
+                    return true;
+                try {
+                    const decoded = decodeURIComponent(seg);
+                    return decoded === '..' || decoded === '.';
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (hasTraversal) {
+                reqLog.warn({ path: rawPath }, 'Blocked: path traversal attempt');
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify({ error: 'Path traversal detected' })}\n`);
+                return;
+            }
+            // Health check
+            if (pathParts[0] === '_aegis' && pathParts[1] === 'health') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify({ status: 'ok', version: VERSION })}\n`);
+                return;
+            }
+            // Stats endpoint
+            if (pathParts[0] === '_aegis' && pathParts[1] === 'stats') {
+                const stats = this.ledger.stats();
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify(stats)}\n`);
+                return;
+            }
+            // Prometheus metrics endpoint
+            if (pathParts[0] === '_aegis' && pathParts[1] === 'metrics') {
+                if (this.metrics) {
+                    const metricsOutput = await this.metrics.getMetricsOutput();
+                    res.writeHead(200, { 'Content-Type': this.metrics.getContentType() });
+                    res.end(metricsOutput);
+                }
+                else {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(`${JSON.stringify({ error: 'Metrics not enabled' })}\n`);
+                }
+                return;
+            }
+            // ─── Agent Authentication ──────────────────────────────────────
+            // If agent auth is required, validate the X-Aegis-Agent token.
+            // The authenticated agent identity flows through to scoping,
+            // rate limiting, and audit trail entries.
+            let authenticatedAgent;
+            if (this.requireAgentAuth && this.agentRegistry) {
+                const agentToken = req.headers['x-aegis-agent'];
+                if (!agentToken) {
+                    this.auditBlocked({
+                        service: pathParts[0] ?? 'unknown',
+                        targetDomain: 'unknown',
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                        reason: 'Missing X-Aegis-Agent header — agent authentication required',
+                    });
+                    reqLog.warn({ service: pathParts[0] ?? 'unknown' }, 'Blocked: missing X-Aegis-Agent header');
+                    this.metrics?.recordBlocked(pathParts[0] ?? 'unknown', 'agent_auth_missing');
+                    this.webhooks?.emit('agent_auth_failure', {
+                        service: pathParts[0] ?? 'unknown',
+                        reason: 'Missing X-Aegis-Agent header',
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                    });
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(`${JSON.stringify({
+                        error: 'Agent authentication required',
+                        hint: "Include X-Aegis-Agent header with your agent token. Run 'aegis agent add --name my-agent' to create one.",
+                    })}\n`);
+                    return;
+                }
+                const agent = this.agentRegistry.validateToken(agentToken);
+                if (!agent) {
+                    this.auditBlocked({
+                        service: pathParts[0] ?? 'unknown',
+                        targetDomain: 'unknown',
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                        reason: 'Invalid agent token in X-Aegis-Agent header',
+                    });
+                    reqLog.warn({ service: pathParts[0] ?? 'unknown' }, 'Blocked: invalid agent token');
+                    this.metrics?.recordBlocked(pathParts[0] ?? 'unknown', 'agent_auth_invalid');
+                    this.webhooks?.emit('agent_auth_failure', {
+                        service: pathParts[0] ?? 'unknown',
+                        reason: 'Invalid agent token',
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                    });
+                    res.writeHead(401, { 'Content-Type': 'application/json' });
+                    res.end(`${JSON.stringify({
+                        error: 'Invalid agent token',
+                        hint: 'Check your X-Aegis-Agent token or register a new agent with: aegis agent add',
+                    })}\n`);
+                    return;
+                }
+                authenticatedAgent = agent;
+                reqLog.debug({ agent: agent.name, tokenPrefix: agent.tokenPrefix }, 'Authenticated agent');
+            }
+            else if (this.agentRegistry) {
+                // Agent auth not required, but optionally identify the agent if a token is provided
+                const agentToken = req.headers['x-aegis-agent'];
+                if (agentToken) {
+                    const agent = this.agentRegistry.validateToken(agentToken);
+                    if (agent) {
+                        authenticatedAgent = agent;
+                        reqLog.debug({ agent: agent.name, tokenPrefix: agent.tokenPrefix }, 'Identified agent');
+                    }
+                }
+            }
+            // ─── Per-Agent Connection Limits ─────────────────────────────────
+            // Prevent a single agent from exhausting all available connections
+            // by tracking in-flight requests per agent.
+            if (authenticatedAgent) {
+                const agentId = authenticatedAgent.id;
+                const currentConnections = this.agentConnections.get(agentId) ?? 0;
+                if (currentConnections >= this.maxConnectionsPerAgent) {
+                    reqLog.warn({
+                        agent: authenticatedAgent.name,
+                        current: currentConnections,
+                        max: this.maxConnectionsPerAgent,
+                    }, 'Blocked: per-agent connection limit exceeded');
+                    this.metrics?.recordBlocked(pathParts[0] ?? 'unknown', 'agent_connection_limit', authenticatedAgent.name);
+                    res.writeHead(429, { 'Content-Type': 'application/json' });
+                    res.end(`${JSON.stringify({
+                        error: 'Too many concurrent requests for this agent',
+                        agent: authenticatedAgent.name,
+                        limit: this.maxConnectionsPerAgent,
+                        hint: 'Wait for in-flight requests to complete or increase gate.max_connections_per_agent',
+                    })}\n`);
+                    return;
+                }
+                this.agentConnections.set(agentId, currentConnections + 1);
+                // Decrement on response close
+                res.on('close', () => {
+                    const count = this.agentConnections.get(agentId) ?? 1;
+                    if (count <= 1) {
+                        this.agentConnections.delete(agentId);
+                    }
+                    else {
+                        this.agentConnections.set(agentId, count - 1);
+                    }
+                });
+            }
+            // Route format: /{service}/rest/of/the/path
+            const serviceName = pathParts[0];
+            if (!serviceName) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify({
+                    error: 'Missing service name',
+                    usage: 'GET http://localhost:{port}/{service}/api/path',
+                })}\n`);
+                return;
+            }
+            // Look up credential for this service
+            const credential = this.vault.getByService(serviceName);
+            if (!credential) {
+                this.auditBlocked({
+                    service: serviceName,
+                    targetDomain: 'unknown',
+                    method: req.method ?? 'GET',
+                    path: req.url ?? '/',
+                    reason: `No credential found for service: ${serviceName}`,
+                    agentName: authenticatedAgent?.name,
+                    agentTokenPrefix: authenticatedAgent?.tokenPrefix,
+                });
+                reqLog.warn({ service: serviceName }, 'Blocked: no credential found');
+                this.metrics?.recordBlocked(serviceName, 'no_credential', authenticatedAgent?.name);
+                this.webhooks?.emit('blocked_request', {
+                    service: serviceName,
+                    reason: 'no_credential',
+                    method: req.method ?? 'GET',
+                    path: req.url ?? '/',
+                    agent: authenticatedAgent?.name,
+                });
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify({
+                    error: `No credential registered for service: ${serviceName}`,
+                    hint: `Run: aegis vault add --name ${serviceName} --service ${serviceName} --secret YOUR_KEY --domains api.example.com`,
+                })}\n`);
+                return;
+            }
+            // TTL enforcement: reject expired credentials
+            if (this.vault.isExpired(credential)) {
+                this.auditBlocked({
+                    service: serviceName,
+                    targetDomain: credential.domains[0] ?? 'unknown',
+                    method: req.method ?? 'GET',
+                    path: req.url ?? '/',
+                    reason: `Credential "${credential.name}" expired at ${credential.expiresAt}`,
+                    agentName: authenticatedAgent?.name,
+                    agentTokenPrefix: authenticatedAgent?.tokenPrefix,
+                });
+                reqLog.warn({ credential: credential.name, expiredAt: credential.expiresAt }, 'Blocked: credential expired');
+                this.metrics?.recordBlocked(serviceName, 'credential_expired', authenticatedAgent?.name);
+                this.webhooks?.emit('credential_expiry', {
+                    service: serviceName,
+                    credential: credential.name,
+                    expiredAt: credential.expiresAt,
+                    agent: authenticatedAgent?.name,
+                });
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify({
+                    error: 'Credential has expired',
+                    credential: credential.name,
+                    expiredAt: credential.expiresAt,
+                    hint: `Rotate with: aegis vault rotate --name ${credential.name} --secret NEW_SECRET`,
+                })}\n`);
+                return;
+            }
+            // ─── Credential Scope Enforcement ────────────────────────────────
+            // If the credential has scopes (read/write/*), verify the HTTP
+            // method is permitted. read → GET/HEAD/OPTIONS, write → POST/PUT/PATCH/DELETE.
+            const reqMethod = req.method ?? 'GET';
+            if (!methodMatchesScope(reqMethod, credential.scopes)) {
+                const scopeList = credential.scopes.join(', ');
+                this.auditBlocked({
+                    service: serviceName,
+                    targetDomain: credential.domains[0] ?? 'unknown',
+                    method: reqMethod,
+                    path: req.url ?? '/',
+                    reason: `Method "${reqMethod}" not permitted by credential scopes [${scopeList}]`,
+                    agentName: authenticatedAgent?.name,
+                    agentTokenPrefix: authenticatedAgent?.tokenPrefix,
+                });
+                reqLog.warn({ credential: credential.name, method: reqMethod, scopes: credential.scopes }, 'Blocked: credential scope violation');
+                this.metrics?.recordBlocked(serviceName, 'credential_scope', authenticatedAgent?.name);
+                this.webhooks?.emit('blocked_request', {
+                    service: serviceName,
+                    reason: 'credential_scope',
+                    credential: credential.name,
+                    method: reqMethod,
+                    scopes: credential.scopes,
+                    agent: authenticatedAgent?.name,
+                    path: req.url ?? '/',
+                });
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify({
+                    error: 'Method not permitted by credential scopes',
+                    method: reqMethod,
+                    scopes: credential.scopes,
+                    hint: `Update scopes with: aegis vault update --name ${credential.name} --scopes ${scopeList},${reqMethod === 'GET' ? 'read' : 'write'}`,
+                })}\n`);
+                return;
+            }
+            // ─── Agent Credential Scoping ──────────────────────────────────
+            // If agent auth is required, verify this agent has been granted
+            // access to the requested credential.
+            if (authenticatedAgent && this.requireAgentAuth && this.agentRegistry) {
+                if (!this.agentRegistry.hasAccess(authenticatedAgent.id, credential.id)) {
+                    this.auditBlocked({
+                        service: serviceName,
+                        targetDomain: credential.domains[0] ?? 'unknown',
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                        reason: `Agent "${authenticatedAgent.name}" not granted access to credential "${credential.name}"`,
+                        agentName: authenticatedAgent.name,
+                        agentTokenPrefix: authenticatedAgent.tokenPrefix,
+                    });
+                    reqLog.warn({ agent: authenticatedAgent.name, credential: credential.name }, 'Blocked: agent not scoped to credential');
+                    this.metrics?.recordBlocked(serviceName, 'agent_scope', authenticatedAgent.name);
+                    this.webhooks?.emit('blocked_request', {
+                        service: serviceName,
+                        reason: 'agent_scope',
+                        agent: authenticatedAgent.name,
+                        credential: credential.name,
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                    });
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(`${JSON.stringify({
+                        error: 'Agent not granted access to this credential',
+                        agent: authenticatedAgent.name,
+                        credential: credential.name,
+                        hint: `Grant access with: aegis agent grant --agent ${authenticatedAgent.name} --credential ${credential.name}`,
+                    })}\n`);
+                    return;
+                }
+            }
+            // ─── Policy Evaluation ─────────────────────────────────────────
+            // If the authenticated agent has a policy, evaluate the request
+            // against it. Policy checks: service access, method restrictions,
+            // path restrictions, time-of-day windows.
+            if (authenticatedAgent && this.policyMap.size > 0) {
+                const agentPolicy = this.policyMap.get(authenticatedAgent.name);
+                if (agentPolicy) {
+                    const remainingPathForPolicy = `/${pathParts.slice(1).join('/')}`;
+                    const evaluation = evaluatePolicy(agentPolicy, {
+                        service: serviceName,
+                        method: req.method ?? 'GET',
+                        path: remainingPathForPolicy,
+                    });
+                    if (!evaluation.allowed) {
+                        const reason = `Policy violation: ${evaluation.reason}`;
+                        if (this.policyMode === 'enforce') {
+                            this.auditBlocked({
+                                service: serviceName,
+                                targetDomain: credential.domains[0] ?? 'unknown',
+                                method: req.method ?? 'GET',
+                                path: req.url ?? '/',
+                                reason,
+                                agentName: authenticatedAgent.name,
+                                agentTokenPrefix: authenticatedAgent.tokenPrefix,
+                            });
+                            reqLog.warn({
+                                agent: authenticatedAgent.name,
+                                violation: evaluation.violation,
+                                reason: evaluation.reason,
+                            }, 'Blocked: policy violation');
+                            this.metrics?.recordBlocked(serviceName, 'policy_violation', authenticatedAgent.name);
+                            this.webhooks?.emit('blocked_request', {
+                                service: serviceName,
+                                reason: 'policy_violation',
+                                agent: authenticatedAgent.name,
+                                violation: evaluation.violation,
+                                detail: evaluation.reason,
+                                method: req.method ?? 'GET',
+                                path: req.url ?? '/',
+                            });
+                            res.writeHead(403, { 'Content-Type': 'application/json' });
+                            res.end(`${JSON.stringify({
+                                error: 'Policy violation',
+                                agent: authenticatedAgent.name,
+                                violation: evaluation.violation,
+                                reason: evaluation.reason,
+                                hint: "Update the agent's policy file to permit this request",
+                            })}\n`);
+                            return;
+                        }
+                        // Dry-run mode: log the would-be violation but allow the request through
+                        this.auditBlocked({
+                            service: serviceName,
+                            targetDomain: credential.domains[0] ?? 'unknown',
+                            method: req.method ?? 'GET',
+                            path: req.url ?? '/',
+                            reason: `POLICY_DRY_RUN: ${evaluation.reason}`,
+                            agentName: authenticatedAgent.name,
+                            agentTokenPrefix: authenticatedAgent.tokenPrefix,
+                        });
+                        reqLog.info({ agent: authenticatedAgent.name, reason: evaluation.reason }, 'Dry-run: would block');
+                    }
+                    // ─── Policy Rate Limiting ────────────────────────────────
+                    // If the matched rule has a rateLimit, enforce it using the
+                    // shared rate limiter. Keyed per agent+service for isolation.
+                    if (evaluation.allowed && evaluation.matchedRule?.rateLimit) {
+                        const policyRateLimitStr = evaluation.matchedRule.rateLimit;
+                        let policyParsedLimit;
+                        try {
+                            policyParsedLimit = parseRateLimit(policyRateLimitStr);
+                        }
+                        catch {
+                            reqLog.error({ agent: authenticatedAgent.name, rateLimit: policyRateLimitStr }, 'Invalid policy rate limit config');
+                            policyParsedLimit = { maxRequests: Number.MAX_SAFE_INTEGER, windowMs: 60_000 };
+                        }
+                        const policyRateKey = `policy:${authenticatedAgent.name}:${serviceName}`;
+                        const policyRateResult = this.rateLimiter.check(policyRateKey, policyParsedLimit);
+                        if (!policyRateResult.allowed) {
+                            const reason = `Policy rate limit exceeded: ${policyRateLimitStr} (retry after ${policyRateResult.retryAfterSeconds}s)`;
+                            if (this.policyMode === 'enforce') {
+                                this.auditBlocked({
+                                    service: serviceName,
+                                    targetDomain: credential.domains[0] ?? 'unknown',
+                                    method: req.method ?? 'GET',
+                                    path: req.url ?? '/',
+                                    reason,
+                                    agentName: authenticatedAgent.name,
+                                    agentTokenPrefix: authenticatedAgent.tokenPrefix,
+                                });
+                                reqLog.warn({
+                                    agent: authenticatedAgent.name,
+                                    limit: policyRateLimitStr,
+                                    retryAfter: policyRateResult.retryAfterSeconds,
+                                }, 'Blocked: policy rate limit exceeded');
+                                this.metrics?.recordBlocked(serviceName, 'policy_rate_limit', authenticatedAgent.name);
+                                this.webhooks?.emit('rate_limit_exceeded', {
+                                    service: serviceName,
+                                    type: 'policy',
+                                    agent: authenticatedAgent.name,
+                                    limit: policyRateLimitStr,
+                                    retryAfter: policyRateResult.retryAfterSeconds,
+                                });
+                                res.writeHead(429, {
+                                    'Content-Type': 'application/json',
+                                    'Retry-After': String(policyRateResult.retryAfterSeconds),
+                                });
+                                res.end(`${JSON.stringify({
+                                    error: 'Policy rate limit exceeded',
+                                    agent: authenticatedAgent.name,
+                                    limit: policyRateLimitStr,
+                                    retryAfter: policyRateResult.retryAfterSeconds,
+                                })}\n`);
+                                return;
+                            }
+                            // Dry-run mode: log but allow through
+                            this.auditBlocked({
+                                service: serviceName,
+                                targetDomain: credential.domains[0] ?? 'unknown',
+                                method: req.method ?? 'GET',
+                                path: req.url ?? '/',
+                                reason: `POLICY_DRY_RUN: ${reason}`,
+                                agentName: authenticatedAgent.name,
+                                agentTokenPrefix: authenticatedAgent.tokenPrefix,
+                            });
+                            reqLog.info({ agent: authenticatedAgent.name, limit: policyRateLimitStr }, 'Dry-run: would block (policy rate limit)');
+                        }
+                    }
+                }
+            }
+            // ─── Per-Agent Rate Limiting ───────────────────────────────────
+            // If the authenticated agent has a rate limit, check it before
+            // the credential rate limit. More restrictive limit wins.
+            if (authenticatedAgent?.rateLimit) {
+                let agentParsedLimit;
+                try {
+                    agentParsedLimit = parseRateLimit(authenticatedAgent.rateLimit);
+                }
+                catch {
+                    reqLog.error({ agent: authenticatedAgent.name, rateLimit: authenticatedAgent.rateLimit }, 'Invalid agent rate limit config');
+                    agentParsedLimit = { maxRequests: Number.MAX_SAFE_INTEGER, windowMs: 60_000 };
+                }
+                const agentResult = this.rateLimiter.check(`agent:${authenticatedAgent.id}`, agentParsedLimit);
+                if (!agentResult.allowed) {
+                    this.auditBlocked({
+                        service: serviceName,
+                        targetDomain: credential.domains[0] ?? 'unknown',
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                        reason: `Agent rate limit exceeded: ${authenticatedAgent.rateLimit} (retry after ${agentResult.retryAfterSeconds}s)`,
+                        agentName: authenticatedAgent.name,
+                        agentTokenPrefix: authenticatedAgent.tokenPrefix,
+                    });
+                    reqLog.warn({
+                        agent: authenticatedAgent.name,
+                        limit: authenticatedAgent.rateLimit,
+                        retryAfter: agentResult.retryAfterSeconds,
+                    }, 'Blocked: agent rate limit exceeded');
+                    this.metrics?.recordBlocked(serviceName, 'agent_rate_limit', authenticatedAgent.name);
+                    this.webhooks?.emit('rate_limit_exceeded', {
+                        service: serviceName,
+                        type: 'agent',
+                        agent: authenticatedAgent.name,
+                        limit: authenticatedAgent.rateLimit,
+                        retryAfter: agentResult.retryAfterSeconds,
+                    });
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(agentResult.retryAfterSeconds),
+                    });
+                    res.end(`${JSON.stringify({
+                        error: 'Agent rate limit exceeded',
+                        agent: authenticatedAgent.name,
+                        limit: authenticatedAgent.rateLimit,
+                        retryAfter: agentResult.retryAfterSeconds,
+                    })}\n`);
+                    return;
+                }
+            }
+            // Rate limit enforcement: check per-credential rate limit
+            if (credential.rateLimit) {
+                let parsedLimit;
+                try {
+                    parsedLimit = parseRateLimit(credential.rateLimit);
+                }
+                catch {
+                    reqLog.error({ credential: credential.name, rateLimit: credential.rateLimit }, 'Invalid credential rate limit config');
+                    parsedLimit = { maxRequests: Number.MAX_SAFE_INTEGER, windowMs: 60_000 };
+                }
+                const result = this.rateLimiter.check(credential.id, parsedLimit);
+                if (!result.allowed) {
+                    this.auditBlocked({
+                        service: serviceName,
+                        targetDomain: credential.domains[0] ?? 'unknown',
+                        method: req.method ?? 'GET',
+                        path: req.url ?? '/',
+                        reason: `Rate limit exceeded: ${credential.rateLimit} (retry after ${result.retryAfterSeconds}s)`,
+                        agentName: authenticatedAgent?.name,
+                        agentTokenPrefix: authenticatedAgent?.tokenPrefix,
+                    });
+                    reqLog.warn({
+                        credential: credential.name,
+                        limit: credential.rateLimit,
+                        retryAfter: result.retryAfterSeconds,
+                    }, 'Blocked: credential rate limit exceeded');
+                    this.metrics?.recordBlocked(serviceName, 'credential_rate_limit', authenticatedAgent?.name);
+                    this.webhooks?.emit('rate_limit_exceeded', {
+                        service: serviceName,
+                        type: 'credential',
+                        credential: credential.name,
+                        limit: credential.rateLimit,
+                        retryAfter: result.retryAfterSeconds,
+                        agent: authenticatedAgent?.name,
+                    });
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(result.retryAfterSeconds),
+                    });
+                    res.end(`${JSON.stringify({
+                        error: 'Rate limit exceeded',
+                        credential: credential.name,
+                        limit: credential.rateLimit,
+                        retryAfter: result.retryAfterSeconds,
+                    })}\n`);
+                    return;
+                }
+            }
+            // Determine target domain:
+            //   1. Agent can request a specific domain via X-Target-Host header
+            //   2. Otherwise, fall back to the credential's primary (first) domain
+            const agentRequestedHost = req.headers['x-target-host'] ?? undefined;
+            const targetDomain = agentRequestedHost ?? credential.domains[0];
+            const remainingPath = `/${pathParts.slice(1).join('/')}`;
+            const query = rawQuery;
+            // Domain guard: verify target domain is in the credential's allowlist
+            // This is the core security boundary — blocks agents from exfiltrating
+            // credentials to domains not explicitly approved.
+            if (!this.vault.domainMatches(targetDomain, credential.domains)) {
+                this.auditBlocked({
+                    service: serviceName,
+                    targetDomain,
+                    method: req.method ?? 'GET',
+                    path: remainingPath,
+                    reason: `Domain "${targetDomain}" not in allowlist [${credential.domains.join(', ')}]`,
+                    agentName: authenticatedAgent?.name,
+                    agentTokenPrefix: authenticatedAgent?.tokenPrefix,
+                });
+                reqLog.warn({ targetDomain, allowed: credential.domains }, 'Blocked: domain guard rejected');
+                this.metrics?.recordBlocked(serviceName, 'domain_guard', authenticatedAgent?.name);
+                this.webhooks?.emit('blocked_request', {
+                    service: serviceName,
+                    reason: 'domain_guard',
+                    targetDomain,
+                    allowedDomains: credential.domains,
+                    agent: authenticatedAgent?.name,
+                    method: req.method ?? 'GET',
+                    path: remainingPath,
+                });
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(`${JSON.stringify({
+                    error: 'Domain not in credential allowlist',
+                    requested: targetDomain,
+                    allowed: credential.domains,
+                })}\n`);
+                return;
+            }
+            // Build outbound headers — strip any auth the agent tried to add
+            const outboundHeaders = {};
+            for (const [key, value] of Object.entries(req.headers)) {
+                const lower = key.toLowerCase();
+                // Strip auth headers the agent might have tried to include
+                if (lower === 'authorization' || lower === 'x-api-key')
+                    continue;
+                // Don't forward host, target-host override, or agent token
+                if (lower === 'host' || lower === 'x-target-host' || lower === 'x-aegis-agent')
+                    continue;
+                outboundHeaders[key] = value;
+            }
+            // Inject the real credential (query auth may modify the path)
+            const injectedPath = this.injectCredential(outboundHeaders, credential, `${remainingPath}${query}`);
+            outboundHeaders.host = targetDomain;
+            reqLog.debug({ service: serviceName, method: req.method, targetDomain, path: remainingPath }, 'Proxying request');
+            // Start request duration timer for Prometheus histogram
+            const stopTimer = this.metrics?.startRequestTimer(serviceName);
+            // Buffer the request body for inspection before forwarding.
+            // Enforce max body size to prevent memory exhaustion.
+            const bodyChunks = [];
+            let bodySize = 0;
+            let bodySizeExceeded = false;
+            req.on('data', (chunk) => {
+                bodySize += chunk.length;
+                if (bodySize > this.maxBodySize) {
+                    bodySizeExceeded = true;
+                    // Stop buffering — we'll reject in the 'end' handler.
+                    // Don't destroy the stream (that kills the socket before we can respond).
+                }
+                else {
+                    bodyChunks.push(chunk);
+                }
+            });
+            req.on('end', () => {
+                // Reject oversized bodies
+                if (bodySizeExceeded) {
+                    reqLog.warn({ service: serviceName, bodySize, maxBodySize: this.maxBodySize }, 'Blocked: request body too large');
+                    this.auditBlocked({
+                        service: serviceName,
+                        targetDomain,
+                        method: req.method ?? 'GET',
+                        path: remainingPath,
+                        reason: 'Body too large',
+                    });
+                    this.metrics?.recordBlocked(serviceName, 'body_too_large', authenticatedAgent?.name);
+                    res.writeHead(413, { 'Content-Type': 'application/json' });
+                    res.end(`${JSON.stringify({
+                        error: 'Request body too large',
+                        received: bodySize,
+                        limit: this.maxBodySize,
+                        hint: 'Reduce body size or increase gate.max_body_size in aegis.config.yaml',
+                    })}\n`);
+                    return;
+                }
+                // Clear the server-level idle timeout — the body is fully received,
+                // so slowloris is no longer a risk. The outbound proxy timeout handles upstream delays.
+                req.socket?.setTimeout(0);
+                const bodyBuffer = Buffer.concat(bodyChunks);
+                const bodyString = bodyBuffer.toString('utf-8');
+                // Body inspection: scan for credential-like patterns in the request body
+                if (credential.bodyInspection !== 'off' && bodyString.length > 0) {
+                    const inspection = this.bodyInspector.inspect(bodyString);
+                    if (inspection.suspicious) {
+                        const matchSummary = inspection.matches.join('; ');
+                        if (credential.bodyInspection === 'block') {
+                            this.auditBlocked({
+                                service: serviceName,
+                                targetDomain,
+                                method: req.method ?? 'GET',
+                                path: remainingPath,
+                                reason: `Body inspection: potential credential exfiltration — ${matchSummary}`,
+                                agentName: authenticatedAgent?.name,
+                                agentTokenPrefix: authenticatedAgent?.tokenPrefix,
+                            });
+                            reqLog.warn({ credential: credential.name, matches: inspection.matches }, 'Blocked: body inspection detected exfiltration');
+                            this.metrics?.recordBlocked(serviceName, 'body_inspection', authenticatedAgent?.name);
+                            this.webhooks?.emit('body_inspection', {
+                                service: serviceName,
+                                credential: credential.name,
+                                matches: inspection.matches,
+                                agent: authenticatedAgent?.name,
+                                method: req.method ?? 'GET',
+                                path: remainingPath,
+                            });
+                            res.writeHead(403, { 'Content-Type': 'application/json' });
+                            res.end(`${JSON.stringify({
+                                error: 'Request body contains credential-like patterns',
+                                mode: 'block',
+                                matches: inspection.matches,
+                                hint: "If this is intentional, set body inspection to 'warn' or 'off' for this credential",
+                            })}\n`);
+                            return;
+                        }
+                        // warn mode — log but allow through
+                        reqLog.warn({ credential: credential.name, matches: inspection.matches }, 'Body inspection: credential-like patterns detected (warn mode)');
+                    }
+                }
+                // ─── Circuit Breaker Check ────────────────────────────────────
+                // If the upstream service has been failing repeatedly, short-circuit
+                // with 503 instead of adding more load to a struggling service.
+                const circuitState = this.circuitBreaker.get(serviceName);
+                if (circuitState && circuitState.openUntil > Date.now()) {
+                    reqLog.warn({ service: serviceName, failures: circuitState.failures }, 'Blocked: circuit breaker open');
+                    if (!res.headersSent) {
+                        const retryAfterSeconds = Math.ceil((circuitState.openUntil - Date.now()) / 1000);
+                        res.writeHead(503, {
+                            'Content-Type': 'application/json',
+                            'Retry-After': String(retryAfterSeconds),
+                        });
+                        res.end(`${JSON.stringify({
+                            error: 'Service temporarily unavailable (circuit breaker open)',
+                            service: serviceName,
+                            retryAfter: retryAfterSeconds,
+                            hint: 'The upstream service has been failing repeatedly. Requests will resume automatically.',
+                        })}\n`);
+                    }
+                    return;
+                }
+                // Forward the request with timeout and retry for transient failures
+                const upstream = this.testUpstream;
+                const transport = upstream?.protocol === 'http' ? http : https;
+                const agent = upstream?.protocol === 'http' ? this.httpAgent : this.httpsAgent;
+                const maxRetries = 2; // original + 2 retries = 3 total attempts
+                const attemptProxy = (attempt) => {
+                    const proxyReq = transport.request({
+                        hostname: upstream?.hostname ?? targetDomain,
+                        port: upstream?.port ?? 443,
+                        path: injectedPath ?? `${remainingPath}${query}`,
+                        method: req.method,
+                        headers: outboundHeaders,
+                        timeout: this.requestTimeout,
+                        agent,
+                    }, (proxyRes) => {
+                        const statusCode = proxyRes.statusCode ?? 500;
+                        // Retry on transient upstream failures (502, 503, 504) if retries remain
+                        // Only retry idempotent methods (GET, HEAD, OPTIONS) — never retry state-changing methods
+                        const isRetryable = (statusCode === 502 || statusCode === 503 || statusCode === 504) &&
+                            attempt < maxRetries &&
+                            READ_METHODS.has(req.method?.toUpperCase() ?? 'GET');
+                        if (isRetryable) {
+                            reqLog.info({ service: serviceName, status: statusCode, attempt: attempt + 1 }, 'Retrying transient upstream failure');
+                            // Consume the response body before retrying
+                            proxyRes.resume();
+                            // Exponential backoff: 500ms, 1000ms
+                            const backoff = 500 * (attempt + 1);
+                            setTimeout(() => attemptProxy(attempt + 1), backoff);
+                            return;
+                        }
+                        // Record circuit breaker state on upstream failures
+                        if (statusCode >= 500) {
+                            this.recordCircuitFailure(serviceName);
+                        }
+                        else {
+                            // Success — reset circuit breaker for this service
+                            this.circuitBreaker.delete(serviceName);
+                        }
+                        // Strip any credential info from response headers
+                        const safeHeaders = { ...proxyRes.headers };
+                        delete safeHeaders['set-cookie']; // Prevent session hijack via agent
+                        this.auditAllowed({
+                            credentialId: credential.id,
+                            credentialName: credential.name,
+                            service: serviceName,
+                            targetDomain,
+                            method: req.method ?? 'GET',
+                            path: remainingPath,
+                            responseCode: statusCode,
+                            agentName: authenticatedAgent?.name,
+                            agentTokenPrefix: authenticatedAgent?.tokenPrefix,
+                        });
+                        reqLog.info({
+                            service: serviceName,
+                            method: req.method,
+                            path: remainingPath,
+                            status: statusCode,
+                        }, 'Request proxied');
+                        stopTimer?.();
+                        this.metrics?.recordRequest(serviceName, req.method ?? 'GET', statusCode, authenticatedAgent?.name);
+                        res.writeHead(statusCode, safeHeaders);
+                        proxyRes.pipe(res);
+                    });
+                    // Outbound request timeout — fires if upstream takes too long
+                    proxyReq.on('timeout', () => {
+                        proxyReq.destroy(new Error('upstream request timed out'));
+                    });
+                    proxyReq.on('error', (err) => {
+                        // Retry on ECONNRESET / socket hang up when using a reused (keep-alive) socket.
+                        // The server may have closed the idle connection before our request arrived.
+                        const isStaleSocket = (err.message.includes('ECONNRESET') || err.message.includes('socket hang up')) &&
+                            proxyReq.reusedSocket;
+                        if (isStaleSocket && attempt < maxRetries) {
+                            reqLog.info({ service: serviceName, attempt: attempt + 1 }, 'Retrying after stale socket error on reused connection');
+                            attemptProxy(attempt + 1);
+                            return;
+                        }
+                        reqLog.error({ service: serviceName, err: err.message }, 'Proxy error');
+                        // Record the failure for circuit breaker
+                        this.recordCircuitFailure(serviceName);
+                        if (!this.shuttingDown) {
+                            try {
+                                this.auditBlocked({
+                                    service: serviceName,
+                                    targetDomain,
+                                    method: req.method ?? 'GET',
+                                    path: remainingPath,
+                                    reason: `Proxy error: ${err.message}`,
+                                });
+                            }
+                            catch {
+                                // Ledger may be unavailable during shutdown cleanup
+                            }
+                        }
+                        if (!res.headersSent) {
+                            const isTimeout = err.message.includes('timed out');
+                            const statusCode = isTimeout ? 504 : 502;
+                            const errorMessage = isTimeout
+                                ? 'Upstream request timed out'
+                                : 'Failed to reach upstream service';
+                            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+                            res.end(`${JSON.stringify({
+                                error: errorMessage,
+                                service: serviceName,
+                            })}\n`);
+                        }
+                    });
+                    // Write the buffered body and end
+                    if (bodyBuffer.length > 0) {
+                        proxyReq.write(bodyBuffer);
+                    }
+                    proxyReq.end();
+                };
+                attemptProxy(0);
+            });
+        }
+        catch (err) {
+            reqLog.error({ err }, 'Unhandled error');
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(`${JSON.stringify({ error: 'Internal Aegis Gate error' })}\n`);
+        }
+    }
+    /**
+     * Record an upstream failure for circuit breaker logic.
+     * After 5 consecutive failures, the circuit opens for 30 seconds.
+     */
+    recordCircuitFailure(service) {
+        const state = this.circuitBreaker.get(service) ?? { failures: 0, openUntil: 0 };
+        state.failures++;
+        // Open the circuit after 5 consecutive failures (30s cooldown)
+        const FAILURE_THRESHOLD = 5;
+        const COOLDOWN_MS = 30_000;
+        if (state.failures >= FAILURE_THRESHOLD) {
+            state.openUntil = Date.now() + COOLDOWN_MS;
+            this.logger.warn({ service, failures: state.failures, cooldownMs: COOLDOWN_MS }, 'Circuit breaker opened — service failures exceeded threshold');
+        }
+        this.circuitBreaker.set(service, state);
+    }
+    /**
+     * Inject the credential into outbound request headers based on auth type.
+     * For `query` auth, the secret is appended as a URL query parameter instead.
+     */
+    injectCredential(headers, credential, path) {
+        switch (credential.authType) {
+            case 'bearer':
+                headers.authorization = `Bearer ${credential.secret}`;
+                break;
+            case 'header':
+                headers[credential.headerName ?? 'x-api-key'] = credential.secret;
+                break;
+            case 'basic':
+                headers.authorization = `Basic ${Buffer.from(credential.secret).toString('base64')}`;
+                break;
+            case 'query': {
+                if (path !== undefined) {
+                    const paramName = encodeURIComponent(credential.headerName ?? 'key');
+                    const paramValue = encodeURIComponent(credential.secret);
+                    const separator = path.includes('?') ? '&' : '?';
+                    return `${path}${separator}${paramName}=${paramValue}`;
+                }
+                break;
+            }
+        }
+        return path;
+    }
+    // ─── Audit Wrappers (Ledger + Dashboard Broadcast) ─────────────
+    /**
+     * Log an allowed request and broadcast to dashboard live feed.
+     */
+    auditAllowed(params) {
+        this.ledger.logAllowed(params);
+        this.onAuditEntry?.({
+            timestamp: new Date().toISOString(),
+            credentialId: params.credentialId,
+            credentialName: params.credentialName,
+            service: params.service,
+            targetDomain: params.targetDomain,
+            method: params.method,
+            path: params.path,
+            status: 'allowed',
+            blockedReason: null,
+            responseCode: params.responseCode ?? null,
+            agentName: params.agentName ?? null,
+            agentTokenPrefix: params.agentTokenPrefix ?? null,
+            channel: 'gate',
+        });
+    }
+    /**
+     * Log a blocked request and broadcast to dashboard live feed.
+     */
+    auditBlocked(params) {
+        this.ledger.logBlocked(params);
+        this.onAuditEntry?.({
+            timestamp: new Date().toISOString(),
+            credentialId: null,
+            credentialName: null,
+            service: params.service,
+            targetDomain: params.targetDomain,
+            method: params.method,
+            path: params.path,
+            status: 'blocked',
+            blockedReason: params.reason,
+            responseCode: null,
+            agentName: params.agentName ?? null,
+            agentTokenPrefix: params.agentTokenPrefix ?? null,
+            channel: 'gate',
+        });
+    }
+}
+//# sourceMappingURL=gate.js.map