aegis-bridge 2.5.1 → 2.5.3

package/dist/channels/manager.d.ts

@@ -6,6 +6,14 @@
  * one broken channel never kills the bridge.
  */
 import type { Channel, SessionEventPayload, InboundHandler } from './types.js';
+/**
+ * Thrown for retriable failures (5xx server errors, network timeouts).
+ * Only these increment the circuit breaker failure count.
+ * 4xx client errors are thrown as plain Error and do NOT trip the breaker.
+ */
+export declare class RetriableError extends Error {
+    constructor(message: string);
+}
 export declare class ChannelManager {
     private channels;
     private inboundHandler;

package/dist/channels/manager.js

@@ -5,6 +5,17 @@
  * to every registered channel, swallowing per-channel errors so
  * one broken channel never kills the bridge.
  */
+/**
+ * Thrown for retriable failures (5xx server errors, network timeouts).
+ * Only these increment the circuit breaker failure count.
+ * 4xx client errors are thrown as plain Error and do NOT trip the breaker.
+ */
+export class RetriableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RetriableError';
+    }
+}
 export class ChannelManager {
     channels = [];
     inboundHandler = null;
@@ -86,6 +97,10 @@ export class ChannelManager {
             }
             catch (e) {
                 console.error(`Channel ${ch.name} error on ${payload.event}:`, e);
+                // Only count retriable errors (5xx, network) toward circuit breaker.
+                // 4xx client errors are non-retriable — the server is healthy.
+                if (!(e instanceof RetriableError))
+                    return;
                 const h = this.health.get(ch.name) ?? { failCount: 0, disabledUntil: 0 };
                 h.failCount++;
                 if (h.failCount >= ChannelManager.FAILURE_THRESHOLD) {

package/dist/channels/webhook.js

@@ -7,6 +7,7 @@
 import { webhookEndpointSchema, getErrorMessage } from '../validation.js';
 import { validateWebhookUrl } from '../ssrf.js';
 import { redactSecretsFromText } from '../utils/redact-headers.js';
+import { RetriableError } from './manager.js';
 export class WebhookChannel {
     name = 'webhook';
     endpoints;
@@ -141,8 +142,13 @@ export class WebhookChannel {
                 console.error(`Webhook ${ep.url} failed after ${maxRetries} attempts for ${event}: ${lastError}`);
                 this.addToDeadLetterQueue(ep.url, event, lastError, maxRetries);
             }
-            // Final failure (HTTP or network) — throw so fire() can aggregate
-            throw new Error(lastError);
+            // Final failure — throw so fire() can aggregate.
+            // Use RetriableError for 5xx/network (circuit breaker counts these),
+            // plain Error for 4xx (circuit breaker ignores these).
+            if (lastError.startsWith('HTTP ') && parseInt(lastError.slice(5)) < 500) {
+                throw new Error(lastError);
+            }
+            throw new RetriableError(lastError);
         }
     }
     /** Issue #89 L14: Add a failed delivery to the dead letter queue. */

package/dist/events.d.ts

@@ -76,6 +76,8 @@ export declare class SessionEventBus {
     private globalEmitter;
     /** #689: Pending setImmediate timers for cleanup on destroy. */
     private pendingTimers;
+    /** #834: Pending setTimeout timers for cleanup on destroy/cleanupSession. */
+    private pendingTimeouts;
     /** Subscribe to events from ALL sessions (new and existing). Returns unsubscribe function. */
     subscribeGlobal(handler: (event: GlobalSSEEvent) => void): () => void;
     /** Emit a session created event to global subscribers. */

package/dist/events.js

@@ -178,12 +178,15 @@ export class SessionEventBus {
         // Clean up after a short delay (let clients receive the event)
         // Capture reference — only delete if it's still the same emitter
         // #357: Also delete the per-session event buffer to prevent unbounded map growth
-        setTimeout(() => {
+        // #834: Track the timer so cleanupSession/destroy can cancel it
+        const timeout = setTimeout(() => {
+            this.pendingTimeouts.delete(timeout);
             if (this.emitters.get(sessionId) === emitter) {
                 this.emitters.delete(sessionId);
             }
             this.eventBuffers.delete(sessionId);
         }, 1000);
+        this.pendingTimeouts.add(timeout);
     }
     /** Emit a stall event. */
     emitStall(sessionId, stallType, detail) {
@@ -227,6 +230,8 @@ export class SessionEventBus {
     globalEmitter = null;
     /** #689: Pending setImmediate timers for cleanup on destroy. */
     pendingTimers = new Set();
+    /** #834: Pending setTimeout timers for cleanup on destroy/cleanupSession. */
+    pendingTimeouts = new Set();
     /** Subscribe to events from ALL sessions (new and existing). Returns unsubscribe function. */
     subscribeGlobal(handler) {
         if (!this.globalEmitter) {
@@ -267,6 +272,11 @@ export class SessionEventBus {
     }
     /** #398: Clean up per-session state (call when session is killed). */
     cleanupSession(sessionId) {
+        // #834: Clear pending setTimeout for this session's emitEnded cleanup
+        for (const timeout of this.pendingTimeouts) {
+            clearTimeout(timeout);
+            this.pendingTimeouts.delete(timeout);
+        }
         this.eventBuffers.delete(sessionId);
         const emitter = this.emitters.get(sessionId);
         if (emitter) {
@@ -281,6 +291,11 @@ export class SessionEventBus {
             clearImmediate(imm);
         }
         this.pendingTimers.clear();
+        // #834: Clear pending setTimeout timers
+        for (const timeout of this.pendingTimeouts) {
+            clearTimeout(timeout);
+        }
+        this.pendingTimeouts.clear();
         for (const emitter of this.emitters.values()) {
             emitter.removeAllListeners();
         }

package/dist/hook-settings.js

@@ -105,14 +105,14 @@ export async function writeHookSettingsFile(baseUrl, sessionId, workDir) {
             }
         }
     }
-    // Deep-merge: project settings as base, hook settings override
-    const combined = {
-        ...merged,
-        hooks: {
-            ...(merged.hooks ?? {}),
-            ...hookSettings.hooks,
-        },
-    };
+    // Deep-merge: project settings as base, hooks merged by event key so both
+    // project-level and Aegis hooks coexist (Issue #635).
+    const existingHooks = merged.hooks ?? {};
+    const mergedHooks = { ...existingHooks };
+    for (const [event, entries] of Object.entries(hookSettings.hooks)) {
+        mergedHooks[event] = [...(existingHooks[event] ?? []), ...entries];
+    }
+    const combined = { ...merged, hooks: mergedHooks };
     // Issue #648: Use unpredictable directory name and restrictive permissions
     // to prevent symlink attacks and information disclosure in /tmp.
     const suffix = randomBytes(4).toString('hex');

package/dist/hooks.js

@@ -14,7 +14,7 @@
  * Issue #169: Phase 1 — HTTP hooks infrastructure.
  * Issue #169: Phase 3 — Hook-driven status detection.
  */
-import { isValidUUID, hookBodySchema } from './validation.js';
+import { isValidUUID, hookBodySchema, parseIntSafe } from './validation.js';
 /** CC hook events that require a decision response. */
 const DECISION_EVENTS = new Set(['PreToolUse', 'PermissionRequest']);
 /** Permission modes that should be auto-approved via hook response. */
@@ -22,7 +22,7 @@ const AUTO_APPROVE_MODES = new Set(['bypassPermissions', 'dontAsk', 'acceptEdits
 /** Default timeout for waiting on client permission decision (ms). */
 const PERMISSION_TIMEOUT_MS = 10_000;
 /** Default timeout for waiting on external answer to AskUserQuestion (ms). */
-const ANSWER_TIMEOUT_MS = parseInt(process.env.ANSWER_TIMEOUT_MS || '30000', 10);
+const ANSWER_TIMEOUT_MS = parseIntSafe(process.env.ANSWER_TIMEOUT_MS, 30_000);
 /** Valid permission_mode values accepted by Claude Code. */
 const VALID_PERMISSION_MODES = new Set(['default', 'plan', 'bypassPermissions']);
 /** Valid CC hook event names (allow any for extensibility, but these are known). */
@@ -186,9 +186,20 @@ export function registerHookRoutes(app, deps) {
         // Emit SSE status event only when the hook implies a state change
         if (newStatus && prevStatus !== newStatus) {
             switch (eventName) {
-                case 'Stop':
-                    deps.eventBus.emitStatus(sessionId, 'idle', 'Claude finished (hook: Stop)');
+                case 'Stop': {
+                    // Issue #812: Check if CC is waiting for user input (text-only last assistant message)
+                    const waiting = await deps.sessions.detectWaitingForInput(sessionId);
+                    if (waiting) {
+                        const session = deps.sessions.getSession(sessionId);
+                        if (session)
+                            session.status = 'waiting_for_input';
+                        deps.eventBus.emitStatus(sessionId, 'waiting_for_input', 'Claude finished, waiting for input (hook: Stop)');
+                    }
+                    else {
+                        deps.eventBus.emitStatus(sessionId, 'idle', 'Claude finished (hook: Stop)');
+                    }
                     break;
+                }
                 case 'PreToolUse':
                 case 'PostToolUse':
                     deps.eventBus.emitStatus(sessionId, 'working', 'Claude is working (hook: tool use)');

package/dist/screenshot.d.ts

@@ -9,6 +9,8 @@ export interface ScreenshotOptions {
     fullPage?: boolean;
     width?: number;
     height?: number;
+    /** Chromium --host-resolver-rules value to pin DNS (prevents TOCTOU rebinding). */
+    hostResolverRule?: string;
 }
 export interface ScreenshotResult {
     screenshot: string;

package/dist/screenshot.js

@@ -23,7 +23,11 @@ export async function captureScreenshot(opts) {
     if (!playwrightAvailable || !chromium) {
         throw new Error('Playwright is not installed. Install it with: npx playwright install chromium && npm install -D playwright');
     }
-    const browser = await chromium.launch({ headless: true });
+    const launchOptions = { headless: true };
+    if (opts.hostResolverRule) {
+        launchOptions.args = [`--host-resolver-rules=${opts.hostResolverRule}`];
+    }
+    const browser = await chromium.launch(launchOptions);
     try {
         const context = await browser.newContext({
             viewport: {

package/dist/server.d.ts

@@ -7,4 +7,9 @@
  * Notification channels (Telegram, webhooks, etc.) are pluggable —
  * the server doesn't know which channels are active.
  */
-export {};
+/**
+ * Read the parent PID from /proc/<pid>/status.
+ * Uses the PPid line instead of parsing /proc/<pid>/stat,
+ * which breaks when the comm field (process name) contains spaces.
+ */
+export declare function readPpid(pid: number): number;

package/dist/server.js

@@ -23,7 +23,7 @@ import { JsonlWatcher } from './jsonl-watcher.js';
 import { ChannelManager, TelegramChannel, WebhookChannel, } from './channels/index.js';
 import { loadConfig } from './config.js';
 import { captureScreenshot, isPlaywrightAvailable } from './screenshot.js';
-import { validateScreenshotUrl, resolveAndCheckIp } from './ssrf.js';
+import { validateScreenshotUrl, resolveAndCheckIp, buildHostResolverRule } from './ssrf.js';
 import { validateWorkDir } from './validation.js';
 import { SessionEventBus } from './events.js';
 import { SSEWriter } from './sse-writer.js';
@@ -461,7 +461,7 @@ async function createSessionHandler(req, reply) {
     if (typeof safeWorkDir === 'object')
         return reply.status(400).send({ error: safeWorkDir.error, code: safeWorkDir.code });
     // Issue #607: Check for an existing idle session with the same workDir
-    const existing = sessions.findIdleSessionByWorkDir(safeWorkDir);
+    const existing = await sessions.findIdleSessionByWorkDir(safeWorkDir);
     if (existing) {
         // Send prompt to the existing session if provided
         let promptDelivery;
@@ -746,10 +746,13 @@ async function screenshotHandler(req, reply) {
     const urlError = validateScreenshotUrl(url);
     if (urlError)
         return reply.status(400).send({ error: urlError });
-    // Post-DNS-resolution check: resolve hostname and reject private IPs
-    const ipError = await resolveAndCheckIp(new URL(url).hostname);
-    if (ipError)
-        return reply.status(400).send({ error: ipError });
+    // DNS-resolution check: resolve hostname and reject private IPs.
+    // Returns the resolved IP so we can pin it via --host-resolver-rules to prevent
+    // DNS rebinding (TOCTOU) between validation and page.goto().
+    const hostname = new URL(url).hostname;
+    const dnsResult = await resolveAndCheckIp(hostname);
+    if (dnsResult.error)
+        return reply.status(400).send({ error: dnsResult.error });
     // Validate session exists
     const session = sessions.getSession(req.params.id);
     if (!session)
@@ -761,7 +764,11 @@ async function screenshotHandler(req, reply) {
         });
     }
     try {
-        const result = await captureScreenshot({ url, fullPage, width, height });
+        // Pin the validated IP via host-resolver-rules to prevent DNS rebinding
+        const hostResolverRule = dnsResult.resolvedIp
+            ? buildHostResolverRule(hostname, dnsResult.resolvedIp)
+            : undefined;
+        const result = await captureScreenshot({ url, fullPage, width, height, hostResolverRule });
         return reply.status(200).send(result);
     }
     catch (e) {
@@ -1123,6 +1130,18 @@ function pidExists(pid) {
         return false;
     }
 }
+/**
+ * Read the parent PID from /proc/<pid>/status.
+ * Uses the PPid line instead of parsing /proc/<pid>/stat,
+ * which breaks when the comm field (process name) contains spaces.
+ */
+export function readPpid(pid) {
+    const status = readFileSync(`/proc/${pid}/status`, 'utf-8');
+    const match = status.match(/^PPid:\s+(\d+)/m);
+    if (!match)
+        throw new Error(`no PPid line in /proc/${pid}/status`);
+    return parseInt(match[1], 10);
+}
 /**
  * Check if a PID is an ancestor of the current process.
  */
@@ -1133,7 +1152,7 @@ function isAncestorPid(pid) {
             if (current === pid)
                 return true;
             try {
-                current = parseInt(readFileSync(`/proc/${current}/stat`, 'utf-8').split(' ')[1], 10);
+                current = readPpid(current);
             }
             catch { /* /proc unavailable or process gone — stop walking */
                 break;

package/dist/session.d.ts

@@ -56,6 +56,8 @@ export declare class SessionManager {
     private stateFile;
     private sessionMapFile;
     private pollTimers;
+    /** #835: Discovery timeout timers — cleared in cleanupSession to prevent orphan callbacks. */
+    private discoveryTimeouts;
     private saveQueue;
     private saveDebounceTimer;
     private static readonly SAVE_DEBOUNCE_MS;
@@ -132,6 +134,9 @@ export declare class SessionManager {
      *  Returns the previous status for change detection.
      *  Issue #87: Also records hook latency timestamps. */
     updateStatusFromHook(id: string, hookEvent: string, hookTimestamp?: number): UIState | null;
+    /** Issue #812: Detect if CC is waiting for user input by analyzing the JSONL transcript.
+     *  Returns true if the last assistant message has text content only (no tool_use). */
+    detectWaitingForInput(id: string): Promise<boolean>;
     /** Issue #88: Add an active subagent to a session. */
     addSubagent(id: string, name: string): void;
     /** Issue #88: Remove an active subagent from a session. */
@@ -156,8 +161,9 @@ export declare class SessionManager {
     listSessions(): SessionInfo[];
     /** Issue #607: Find an idle session for the given workDir.
      *  Returns the most recently active idle session, or null if none found.
-     *  Used to resume existing sessions instead of creating duplicates. */
-    findIdleSessionByWorkDir(workDir: string): SessionInfo | null;
+     *  Used to resume existing sessions instead of creating duplicates.
+     *  Issue #636: Verifies tmux window is still alive before returning. */
+    findIdleSessionByWorkDir(workDir: string): Promise<SessionInfo | null>;
     /** Get health info for a session.
      *  Issue #2: Returns comprehensive health status for orchestrators.
      */

package/dist/session.js

@@ -50,6 +50,8 @@ export class SessionManager {
     stateFile;
     sessionMapFile;
     pollTimers = new Map();
+    /** #835: Discovery timeout timers — cleared in cleanupSession to prevent orphan callbacks. */
+    discoveryTimeouts = new Map();
     saveQueue = Promise.resolve(); // #218: serialize concurrent saves
     saveDebounceTimer = null;
     static SAVE_DEBOUNCE_MS = 5_000; // #357: debounce offset-only saves
@@ -578,6 +580,34 @@ export class SessionManager {
         }
         return prevStatus;
     }
+    /** Issue #812: Detect if CC is waiting for user input by analyzing the JSONL transcript.
+     *  Returns true if the last assistant message has text content only (no tool_use). */
+    async detectWaitingForInput(id) {
+        const session = this.state.sessions[id];
+        if (!session?.jsonlPath)
+            return false;
+        try {
+            const { raw } = await readNewEntries(session.jsonlPath, 0);
+            // Walk backwards to find the last assistant JSONL entry
+            for (let i = raw.length - 1; i >= 0; i--) {
+                const entry = raw[i];
+                if (entry.type !== 'assistant' || !entry.message)
+                    continue;
+                const content = entry.message.content;
+                if (typeof content === 'string')
+                    return true; // text-only message
+                if (!Array.isArray(content))
+                    return false;
+                // Check if any content block is a tool_use
+                const hasToolUse = content.some((block) => block.type === 'tool_use');
+                return !hasToolUse;
+            }
+        }
+        catch {
+            // If we can't read the transcript, don't override status
+        }
+        return false;
+    }
     /** Issue #88: Add an active subagent to a session. */
     addSubagent(id, name) {
         const session = this.state.sessions[id];
@@ -662,14 +692,21 @@ export class SessionManager {
     }
     /** Issue #607: Find an idle session for the given workDir.
      *  Returns the most recently active idle session, or null if none found.
-     *  Used to resume existing sessions instead of creating duplicates. */
-    findIdleSessionByWorkDir(workDir) {
+     *  Used to resume existing sessions instead of creating duplicates.
+     *  Issue #636: Verifies tmux window is still alive before returning. */
+    async findIdleSessionByWorkDir(workDir) {
         const candidates = Object.values(this.state.sessions).filter((s) => s.workDir === workDir && s.status === 'idle');
         if (candidates.length === 0)
             return null;
         // Return the most recently active session
         candidates.sort((a, b) => b.lastActivity - a.lastActivity);
-        return candidates[0];
+        // Issue #636: verify tmux window exists before returning
+        for (const candidate of candidates) {
+            if (await this.tmux.windowExists(candidate.windowId)) {
+                return candidate;
+            }
+        }
+        return null;
     }
     /** Get health info for a session.
      *  Issue #2: Returns comprehensive health status for orchestrators.
@@ -1115,6 +1152,14 @@ export class SessionManager {
                 this.pollTimers.delete(key);
             }
         }
+        // #835: Clear discovery timeout timers to prevent orphan callbacks
+        for (const key of [id, `fs-${id}`]) {
+            const timeout = this.discoveryTimeouts.get(key);
+            if (timeout) {
+                clearTimeout(timeout);
+                this.discoveryTimeouts.delete(key);
+            }
+        }
         this.cleanupPendingPermission(id);
         this.cleanupPendingQuestion(id);
         this.parsedEntriesCache.delete(id);
@@ -1254,7 +1299,9 @@ export class SessionManager {
         }, 2000);
         this.pollTimers.set(id, interval);
         // P3 fix: Stop after 5 minutes if not found, log timeout
-        setTimeout(() => {
+        // #835: Track the timeout so cleanupSession can cancel it
+        const discoveryTimeout = setTimeout(() => {
+            this.discoveryTimeouts.delete(id);
             const timer = this.pollTimers.get(id);
             const session = this.state.sessions[id];
             if (timer) {
@@ -1266,6 +1313,7 @@ export class SessionManager {
                 }
             }
         }, 5 * 60 * 1000);
+        this.discoveryTimeouts.set(id, discoveryTimeout);
     }
     /** Issue #16: Filesystem-based discovery for --bare mode (no hooks).
      *  Scans the Claude projects directory for new .jsonl files created after the session.
@@ -1313,13 +1361,16 @@ export class SessionManager {
         }, 3000);
         this.pollTimers.set(`fs-${id}`, interval);
         // Timeout after 5 minutes
-        setTimeout(() => {
+        // #835: Track the timeout so cleanupSession can cancel it
+        const fsDiscoveryTimeout = setTimeout(() => {
+            this.discoveryTimeouts.delete(`fs-${id}`);
             const timer = this.pollTimers.get(`fs-${id}`);
             if (timer) {
                 clearInterval(timer);
                 this.pollTimers.delete(`fs-${id}`);
             }
         }, 5 * 60 * 1000);
+        this.discoveryTimeouts.set(`fs-${id}`, fsDiscoveryTimeout);
     }
     /** Sync CC session IDs from the hook-written session_map.json. */
     async syncSessionMap() {

package/dist/ssrf.d.ts

@@ -8,6 +8,8 @@
  * - Current network: 0.0.0.0/8
  * - Unspecified: ::
  * - IPv6 unique-local: fc00::/7
+ * - IPv4-mapped IPv6: ::ffff:x.x.x.x (RFC 4291)
+ * - IPv4-compatible IPv6: ::x.x.x.x (deprecated)
  * - CGNAT: 100.64.0.0/10 (RFC 6598)
  * - Broadcast: 255.255.255.255
  * - Multicast: 224.0.0.0/4 (RFC 5771)
@@ -35,16 +37,38 @@ export interface DnsLookupResult {
 }
 /** DNS lookup function type for dependency injection. */
 export type DnsLookupFn = (hostname: string) => Promise<DnsLookupResult>;
+/**
+ * Result of DNS resolution with SSRF check.
+ * On success, includes the resolved IP address for TOCTOU-safe pinning.
+ */
+export interface DnsCheckResult {
+    error: string | null;
+    resolvedIp: string | null;
+}
 /**
  * Resolve a hostname via DNS and check if the resulting IP is private/internal.
  *
  * For literal IP addresses, checks directly without DNS resolution.
- * Returns null if safe, or an error string if the IP is private.
+ * Returns a DnsCheckResult with error string if unsafe, or the resolved IP on success.
+ *
+ * The resolved IP should be used with Chromium --host-resolver-rules to pin the
+ * address and prevent DNS rebinding (TOCTOU) attacks between validation and page.goto().
  *
  * @param hostname - Hostname or literal IP to check
  * @param lookupFn - Optional DNS lookup function (for testing)
  */
-export declare function resolveAndCheckIp(hostname: string, lookupFn?: DnsLookupFn): Promise<string | null>;
+export declare function resolveAndCheckIp(hostname: string, lookupFn?: DnsLookupFn): Promise<DnsCheckResult>;
+/**
+ * Build Chromium --host-resolver-rules argument to pin a hostname to a specific IP.
+ *
+ * This prevents DNS rebinding (TOCTOU) attacks between SSRF validation and page.goto()
+ * by ensuring Chromium resolves the hostname to the same IP that was validated.
+ *
+ * @param hostname - The original hostname from the URL
+ * @param resolvedIp - The IP address that was validated as safe
+ * @returns The --host-resolver-rules argument string
+ */
+export declare function buildHostResolverRule(hostname: string, resolvedIp: string): string;
 /**
  * Validate a URL for the screenshot endpoint to prevent SSRF attacks.
  *

package/dist/ssrf.js

@@ -16,6 +16,8 @@ import net from 'node:net';
  * - Current network: 0.0.0.0/8
  * - Unspecified: ::
  * - IPv6 unique-local: fc00::/7
+ * - IPv4-mapped IPv6: ::ffff:x.x.x.x (RFC 4291)
+ * - IPv4-compatible IPv6: ::x.x.x.x (deprecated)
  * - CGNAT: 100.64.0.0/10 (RFC 6598)
  * - Broadcast: 255.255.255.255
  * - Multicast: 224.0.0.0/4 (RFC 5771)
@@ -70,6 +72,29 @@ export function isPrivateIP(ip) {
     }
     // IPv6
     const lower = ip.toLowerCase();
+    // IPv4-mapped IPv6 (::ffff:x.x.x.x, RFC 4291 §2.5.5)
+    // Handles dotted-quad form (::ffff:127.0.0.1) and hex form (::ffff:7f00:1).
+    // Also handles IPv4-compatible IPv6 (::x.x.x.x, deprecated).
+    if (lower.startsWith('::ffff:')) {
+        const suffix = lower.slice(7);
+        // Dotted quad form: ::ffff:127.0.0.1
+        if (net.isIPv4(suffix)) {
+            return isPrivateIP(suffix);
+        }
+        // Hex form: ::ffff:7f00:1 → parse last 32 bits as IPv4
+        const hexGroups = suffix.split(':').map(h => parseInt(h, 16));
+        if (hexGroups.length === 2 && hexGroups.every(n => !isNaN(n))) {
+            const embedded = `${(hexGroups[0] >> 8) & 0xff}.${hexGroups[0] & 0xff}.${(hexGroups[1] >> 8) & 0xff}.${hexGroups[1] & 0xff}`;
+            if (net.isIPv4(embedded)) {
+                return isPrivateIP(embedded);
+            }
+        }
+    }
+    // IPv4-compatible IPv6 (::x.x.x.x, deprecated RFC 4291 §2.5.5)
+    const afterPrefix = lower.startsWith('::') && lower !== '::' && lower !== '::1' ? lower.slice(2) : null;
+    if (afterPrefix !== null && net.isIPv4(afterPrefix)) {
+        return isPrivateIP(afterPrefix);
+    }
     // ::1 (loopback)
     if (lower === '::1')
         return true;
@@ -105,8 +130,10 @@ export function validateWebhookUrl(rawUrl) {
         return 'Invalid URL';
     }
     const hostname = parsed.hostname;
+    // Strip brackets from IPv6 URLs: [::1] → ::1
+    const bareHost = hostname.replace(/^\[|\]$/g, '');
     // Scheme check — must be HTTPS, or HTTP only for local dev
-    const isLocalDev = hostname === '127.0.0.1' || hostname === '::1' || hostname === 'localhost';
+    const isLocalDev = bareHost === '127.0.0.1' || bareHost === '::1' || bareHost === 'localhost';
     if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && isLocalDev)) {
         if (parsed.protocol === 'http:') {
             return 'Only HTTPS URLs are allowed for external hosts';
@@ -114,11 +141,11 @@ export function validateWebhookUrl(rawUrl) {
         return 'Only HTTPS URLs are allowed';
     }
     // Reject *.local hostnames (but allow literal localhost for dev)
-    if (hostname.endsWith('.local')) {
+    if (bareHost.endsWith('.local')) {
         return 'Localhost URLs are not allowed';
     }
     // Reject private/internal IPs (except 127.0.0.1/::1 which are allowed for dev over HTTP)
-    if (net.isIP(hostname) && isPrivateIP(hostname) && !isLocalDev) {
+    if (net.isIP(bareHost) && isPrivateIP(bareHost) && !isLocalDev) {
         return 'Private/internal IP addresses are not allowed';
     }
     return null;
@@ -129,7 +156,10 @@ const defaultLookup = (hostname) => dns.lookup(hostname);
  * Resolve a hostname via DNS and check if the resulting IP is private/internal.
  *
  * For literal IP addresses, checks directly without DNS resolution.
- * Returns null if safe, or an error string if the IP is private.
+ * Returns a DnsCheckResult with error string if unsafe, or the resolved IP on success.
+ *
+ * The resolved IP should be used with Chromium --host-resolver-rules to pin the
+ * address and prevent DNS rebinding (TOCTOU) attacks between validation and page.goto().
  *
  * @param hostname - Hostname or literal IP to check
  * @param lookupFn - Optional DNS lookup function (for testing)
@@ -138,21 +168,34 @@ export async function resolveAndCheckIp(hostname, lookupFn = defaultLookup) {
     // Literal IP — check directly
     if (net.isIP(hostname)) {
         if (isPrivateIP(hostname)) {
-            return `DNS resolution points to a private/internal IP: ${hostname}`;
+            return { error: `DNS resolution points to a private/internal IP: ${hostname}`, resolvedIp: null };
         }
-        return null;
+        return { error: null, resolvedIp: hostname };
     }
     try {
         const result = await lookupFn(hostname);
         if (isPrivateIP(result.address)) {
-            return `DNS resolution points to a private/internal IP: ${result.address}`;
+            return { error: `DNS resolution points to a private/internal IP: ${result.address}`, resolvedIp: null };
         }
-        return null;
+        return { error: null, resolvedIp: result.address };
     }
     catch { /* DNS lookup failed — treat as unsafe */
-        return `DNS resolution failed for ${hostname}`;
+        return { error: `DNS resolution failed for ${hostname}`, resolvedIp: null };
     }
 }
+/**
+ * Build Chromium --host-resolver-rules argument to pin a hostname to a specific IP.
+ *
+ * This prevents DNS rebinding (TOCTOU) attacks between SSRF validation and page.goto()
+ * by ensuring Chromium resolves the hostname to the same IP that was validated.
+ *
+ * @param hostname - The original hostname from the URL
+ * @param resolvedIp - The IP address that was validated as safe
+ * @returns The --host-resolver-rules argument string
+ */
+export function buildHostResolverRule(hostname, resolvedIp) {
+    return `MAP ${hostname} ${resolvedIp}`;
+}
 /**
  * Validate a URL for the screenshot endpoint to prevent SSRF attacks.
  *
@@ -178,12 +221,14 @@ export function validateScreenshotUrl(rawUrl) {
         return 'Only http and https URLs are allowed';
     }
     const hostname = parsed.hostname;
+    // Strip brackets from IPv6 URLs: [::1] → ::1
+    const bareHost = hostname.replace(/^\[|\]$/g, '');
     // Reject localhost / *.local hostnames
-    if (hostname === 'localhost' || hostname.endsWith('.local')) {
+    if (bareHost === 'localhost' || bareHost.endsWith('.local')) {
         return 'Localhost URLs are not allowed';
     }
     // Reject private/internal IPs
-    if (net.isIP(hostname) && isPrivateIP(hostname)) {
+    if (net.isIP(bareHost) && isPrivateIP(bareHost)) {
         return 'Private/internal IP addresses are not allowed';
     }
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-bridge",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "type": "module",
   "description": "Orchestrate Claude Code sessions via API. Create, brief, monitor, refine, ship.",
   "main": "dist/server.js",