aegis-bridge 0.1.0

package/dist/shutdown-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * shutdown-utils.ts — reusable shutdown helpers for server signal handling.
+ */
+export declare function parseShutdownTimeoutMs(rawValue: string | undefined, fallbackMs?: number): number;
+export declare function isWindowsShutdownMessage(message: unknown): boolean;

package/dist/shutdown-utils.js

@@ -0,0 +1,24 @@
+/**
+ * shutdown-utils.ts — reusable shutdown helpers for server signal handling.
+ */
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 15_000;
+export function parseShutdownTimeoutMs(rawValue, fallbackMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed) || parsed < 1_000)
+        return fallbackMs;
+    return Math.floor(parsed);
+}
+export function isWindowsShutdownMessage(message) {
+    if (typeof message === 'string') {
+        const normalized = message.trim().toLowerCase();
+        return normalized === 'shutdown' || normalized === 'graceful-shutdown';
+    }
+    if (typeof message === 'object' && message !== null && 'type' in message) {
+        const typeValue = message.type;
+        if (typeof typeValue === 'string') {
+            const normalized = typeValue.trim().toLowerCase();
+            return normalized === 'shutdown' || normalized === 'graceful-shutdown';
+        }
+    }
+    return false;
+}

package/dist/signal-cleanup-helper.d.ts

@@ -0,0 +1,48 @@
+/**
+ * signal-cleanup-helper.ts — Signal handler cleanup logic for Issue #569.
+ *
+ * Provides killAllSessions() and createSignalHandler() for graceful shutdown.
+ * Separated from server.ts for testability.
+ */
+import type { SessionManager } from './session.js';
+import type { TmuxManager } from './tmux.js';
+/** Result of killAllSessions operation. */
+export interface KillAllResult {
+    /** Number of sessions successfully killed. */
+    killed: number;
+    /** Number of sessions that failed to kill. */
+    errors: number;
+}
+/** Result of killAllSessionsWithTimeout operation. */
+export interface KillAllWithTimeoutResult extends KillAllResult {
+    /** Whether any session kill timed out. */
+    timedOut: boolean;
+}
+/**
+ * Kill all active CC sessions and the tmux session.
+ * Best-effort: continues even if individual session kills fail.
+ *
+ * @param sessions - SessionManager instance
+ * @param tmux - TmuxManager instance
+ * @returns Number of sessions killed and errors encountered
+ */
+export declare function killAllSessions(sessions: SessionManager, tmux: TmuxManager): Promise<KillAllResult>;
+/**
+ * Kill all sessions with per-session timeout protection.
+ * If a session kill hangs beyond the timeout, it is skipped.
+ *
+ * @param sessions - SessionManager instance
+ * @param tmux - TmuxManager instance
+ * @param perSessionTimeoutMs - Maximum time to wait per session kill (default 5000ms)
+ * @returns Result including timeout status
+ */
+export declare function killAllSessionsWithTimeout(sessions: SessionManager, tmux: TmuxManager, perSessionTimeoutMs?: number): Promise<KillAllWithTimeoutResult>;
+/**
+ * Create a signal handler that kills all sessions on SIGTERM/SIGINT.
+ * Includes reentrance guard to prevent double cleanup on rapid signals.
+ *
+ * @param sessions - SessionManager instance
+ * @param tmux - TmuxManager instance
+ * @returns Signal handler function
+ */
+export declare function createSignalHandler(sessions: SessionManager, tmux: TmuxManager): (signal: string) => void;

package/dist/signal-cleanup-helper.js

@@ -0,0 +1,117 @@
+/**
+ * signal-cleanup-helper.ts — Signal handler cleanup logic for Issue #569.
+ *
+ * Provides killAllSessions() and createSignalHandler() for graceful shutdown.
+ * Separated from server.ts for testability.
+ */
+/**
+ * Kill all active CC sessions and the tmux session.
+ * Best-effort: continues even if individual session kills fail.
+ *
+ * @param sessions - SessionManager instance
+ * @param tmux - TmuxManager instance
+ * @returns Number of sessions killed and errors encountered
+ */
+export async function killAllSessions(sessions, tmux) {
+    const allSessions = sessions.listSessions();
+    let killed = 0;
+    let errors = 0;
+    // Kill each session individually (restores settings, cleans up temp files)
+    for (const session of allSessions) {
+        try {
+            await sessions.killSession(session.id);
+            killed++;
+        }
+        catch (e) {
+            errors++;
+            console.error(`Signal cleanup: failed to kill session ${session.windowName} (${session.id.slice(0, 8)}): ${e.message}`);
+        }
+    }
+    // Final fallback: kill the entire tmux session to ensure nothing is left
+    try {
+        await tmux.killSession();
+    }
+    catch (e) {
+        console.error(`Signal cleanup: failed to kill tmux session: ${e.message}`);
+    }
+    console.log(`Signal cleanup: killed ${killed} sessions (${errors} errors)`);
+    return { killed, errors };
+}
+/**
+ * Kill all sessions with per-session timeout protection.
+ * If a session kill hangs beyond the timeout, it is skipped.
+ *
+ * @param sessions - SessionManager instance
+ * @param tmux - TmuxManager instance
+ * @param perSessionTimeoutMs - Maximum time to wait per session kill (default 5000ms)
+ * @returns Result including timeout status
+ */
+export async function killAllSessionsWithTimeout(sessions, tmux, perSessionTimeoutMs = 5_000) {
+    const allSessions = sessions.listSessions();
+    let killed = 0;
+    let errors = 0;
+    let timedOut = false;
+    for (const session of allSessions) {
+        try {
+            await withTimeout(sessions.killSession(session.id), perSessionTimeoutMs, `Session kill timeout for ${session.windowName}`);
+            killed++;
+        }
+        catch (e) {
+            if (e instanceof TimeoutError) {
+                timedOut = true;
+                console.error(`Signal cleanup: TIMED OUT killing session ${session.windowName}`);
+            }
+            else {
+                console.error(`Signal cleanup: failed to kill session ${session.windowName}: ${e.message}`);
+            }
+            errors++;
+        }
+    }
+    // Final fallback: kill entire tmux session
+    try {
+        await tmux.killSession();
+    }
+    catch (e) {
+        console.error(`Signal cleanup: failed to kill tmux session: ${e.message}`);
+    }
+    console.log(`Signal cleanup: killed ${killed}/${allSessions.length} sessions (${errors} errors, ${timedOut ? 'some timed out' : 'no timeouts'})`);
+    return { killed, errors, timedOut };
+}
+/** Error thrown when an operation exceeds its timeout. */
+class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+/** Wrap a promise with a timeout. */
+function withTimeout(promise, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError(message)), ms);
+        promise.then((val) => { clearTimeout(timer); resolve(val); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
+/**
+ * Create a signal handler that kills all sessions on SIGTERM/SIGINT.
+ * Includes reentrance guard to prevent double cleanup on rapid signals.
+ *
+ * @param sessions - SessionManager instance
+ * @param tmux - TmuxManager instance
+ * @returns Signal handler function
+ */
+export function createSignalHandler(sessions, tmux) {
+    let shuttingDown = false;
+    return (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(`${signal} received — cleaning up ${sessions.listSessions().length} active sessions...`);
+        void killAllSessions(sessions, tmux)
+            .then((result) => {
+            console.log(`${signal} cleanup complete: ${result.killed} sessions killed`);
+        })
+            .catch((e) => {
+            console.error(`${signal} cleanup error:`, e);
+        });
+    };
+}

package/dist/sse-limiter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * sse-limiter.ts — Connection limiter for SSE endpoints (Issue #300).
+ *
+ * Tracks active SSE connections per-IP and globally.
+ * Enforces configurable limits to prevent unbounded resource consumption.
+ */
+export interface SSELimiterConfig {
+    /** Maximum total concurrent SSE connections across all IPs. Default: 100 */
+    maxConnections?: number;
+    /** Maximum concurrent SSE connections per client IP. Default: 10 */
+    maxPerIp?: number;
+}
+export interface AcquireResult {
+    allowed: true;
+    connectionId: string;
+}
+export interface AcquireDeniedResult {
+    allowed: false;
+    reason: 'per_ip_limit' | 'global_limit';
+    /** Current count for the limiting dimension */
+    current: number;
+    /** Configured limit */
+    limit: number;
+}
+export type AcquireResponse = AcquireResult | AcquireDeniedResult;
+export declare class SSEConnectionLimiter {
+    private readonly maxConnections;
+    private readonly maxPerIp;
+    private readonly connections;
+    private readonly ipCounts;
+    private nextId;
+    constructor(config?: SSELimiterConfig);
+    /** Current total active connections. */
+    get activeCount(): number;
+    /** Active connections for a specific IP. */
+    activeCountForIp(ip: string): number;
+    /**
+     * Attempt to acquire a connection slot.
+     * Check per-IP limit first (more specific), then global limit.
+     */
+    acquire(ip: string): AcquireResponse;
+    /**
+     * Release a connection slot.
+     * Safe to call with unknown or already-released IDs (no-op).
+     */
+    release(connectionId: string): void;
+}

package/dist/sse-limiter.js

@@ -0,0 +1,61 @@
+/**
+ * sse-limiter.ts — Connection limiter for SSE endpoints (Issue #300).
+ *
+ * Tracks active SSE connections per-IP and globally.
+ * Enforces configurable limits to prevent unbounded resource consumption.
+ */
+export class SSEConnectionLimiter {
+    maxConnections;
+    maxPerIp;
+    connections = new Map();
+    ipCounts = new Map();
+    nextId = 1;
+    constructor(config) {
+        this.maxConnections = config?.maxConnections ?? 100;
+        this.maxPerIp = config?.maxPerIp ?? 10;
+    }
+    /** Current total active connections. */
+    get activeCount() {
+        return this.connections.size;
+    }
+    /** Active connections for a specific IP. */
+    activeCountForIp(ip) {
+        return this.ipCounts.get(ip) ?? 0;
+    }
+    /**
+     * Attempt to acquire a connection slot.
+     * Check per-IP limit first (more specific), then global limit.
+     */
+    acquire(ip) {
+        const currentPerIp = this.activeCountForIp(ip);
+        if (currentPerIp >= this.maxPerIp) {
+            return { allowed: false, reason: 'per_ip_limit', current: currentPerIp, limit: this.maxPerIp };
+        }
+        if (this.connections.size >= this.maxConnections) {
+            return { allowed: false, reason: 'global_limit', current: this.connections.size, limit: this.maxConnections };
+        }
+        const connectionId = `sse-${this.nextId++}`;
+        this.connections.set(connectionId, { ip });
+        this.ipCounts.set(ip, currentPerIp + 1);
+        return { allowed: true, connectionId };
+    }
+    /**
+     * Release a connection slot.
+     * Safe to call with unknown or already-released IDs (no-op).
+     */
+    release(connectionId) {
+        const entry = this.connections.get(connectionId);
+        if (!entry)
+            return;
+        this.connections.delete(connectionId);
+        const count = this.ipCounts.get(entry.ip);
+        if (count !== undefined) {
+            if (count <= 1) {
+                this.ipCounts.delete(entry.ip);
+            }
+            else {
+                this.ipCounts.set(entry.ip, count - 1);
+            }
+        }
+    }
+}

package/dist/sse-writer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * sse-writer.ts — SSE write helper with back-pressure handling.
+ *
+ * Issue #302: Check reply.raw.write() return value and disconnect
+ * slow clients after consecutive failed writes.
+ */
+import type { ServerResponse, IncomingMessage } from 'node:http';
+export declare class SSEWriter {
+    private readonly res;
+    private readonly onCleanup;
+    private consecutiveFailures;
+    private isDestroyed;
+    private heartbeatTimer;
+    private lastWrite;
+    /** Drop slow clients after this many consecutive write() calls returning false. */
+    private static readonly MAX_CONSECUTIVE_FAILURES;
+    constructor(res: ServerResponse, req: IncomingMessage, onCleanup: () => void);
+    /**
+     * Write SSE data to the response.
+     * Returns true if the write succeeded (or is within failure threshold).
+     * Returns false if the connection was destroyed due to back-pressure.
+     */
+    write(data: string): boolean;
+    /**
+     * Start heartbeat + idle timeout loop.
+     * Returns a stop function to cancel the timer.
+     */
+    startHeartbeat(intervalMs: number, idleTimeoutMs: number, buildEvent: () => string): () => void;
+    private destroy;
+    private cleanup;
+}

package/dist/sse-writer.js

@@ -0,0 +1,94 @@
+/**
+ * sse-writer.ts — SSE write helper with back-pressure handling.
+ *
+ * Issue #302: Check reply.raw.write() return value and disconnect
+ * slow clients after consecutive failed writes.
+ */
+export class SSEWriter {
+    res;
+    onCleanup;
+    consecutiveFailures = 0;
+    isDestroyed = false;
+    heartbeatTimer = null;
+    lastWrite = Date.now();
+    /** Drop slow clients after this many consecutive write() calls returning false. */
+    static MAX_CONSECUTIVE_FAILURES = 3;
+    constructor(res, req, onCleanup) {
+        this.res = res;
+        this.onCleanup = onCleanup;
+        req.on('close', () => this.cleanup());
+    }
+    /**
+     * Write SSE data to the response.
+     * Returns true if the write succeeded (or is within failure threshold).
+     * Returns false if the connection was destroyed due to back-pressure.
+     */
+    write(data) {
+        if (this.isDestroyed)
+            return false;
+        try {
+            const canContinue = this.res.write(data);
+            if (!canContinue) {
+                this.consecutiveFailures++;
+                if (this.consecutiveFailures >= SSEWriter.MAX_CONSECUTIVE_FAILURES) {
+                    this.destroy();
+                    return false;
+                }
+            }
+            else {
+                this.consecutiveFailures = 0;
+                this.lastWrite = Date.now();
+            }
+            return true;
+        }
+        catch { /* write failed — destroy connection */
+            this.destroy();
+            return false;
+        }
+    }
+    /**
+     * Start heartbeat + idle timeout loop.
+     * Returns a stop function to cancel the timer.
+     */
+    startHeartbeat(intervalMs, idleTimeoutMs, buildEvent) {
+        this.heartbeatTimer = setInterval(() => {
+            if (this.isDestroyed) {
+                clearInterval(this.heartbeatTimer);
+                return;
+            }
+            if (Date.now() - this.lastWrite > idleTimeoutMs) {
+                this.destroy();
+                return;
+            }
+            this.write(buildEvent());
+        }, intervalMs);
+        return () => {
+            if (this.heartbeatTimer) {
+                clearInterval(this.heartbeatTimer);
+                this.heartbeatTimer = null;
+            }
+        };
+    }
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        this.isDestroyed = true;
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        try {
+            this.res.end();
+        }
+        catch { /* already closed */ }
+        this.onCleanup();
+    }
+    cleanup() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.isDestroyed = true;
+        this.onCleanup();
+    }
+}

package/dist/ssrf.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Check if an IP address (v4 or v6) is private/internal.
+ *
+ * Rejects:
+ * - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+ * - Loopback: 127.0.0.0/8, ::1
+ * - Link-local: 169.254.0.0/16, fe80::/10
+ * - 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)
+ * - Documentation: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737)
+ * - Benchmarking: 198.18.0.0/15 (RFC 2544)
+ */
+export declare function isPrivateIP(ip: string): boolean;
+/**
+ * Validate a URL for webhook configuration.
+ *
+ * Checks:
+ * 1. Valid URL format
+ * 2. HTTPS scheme required for external hosts
+ * 3. HTTP allowed only for localhost / 127.0.0.1
+ * 4. Rejects private/internal IP addresses (except 127.0.0.1 in dev mode)
+ * 5. Rejects *.local hostnames
+ *
+ * Returns null if valid, or an error string if invalid.
+ */
+export declare function validateWebhookUrl(rawUrl: string): string | null;
+/** DNS lookup result shape (matches node:dns/promises.LookupAddress). */
+export interface DnsLookupResult {
+    address: string;
+    family: number;
+}
+/** DNS lookup function type for dependency injection. Returns ALL addresses. */
+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 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<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;
+/**
+ * Build a connection URL where the hostname is replaced by the resolved IP address.
+ *
+ * This prevents DNS rebinding (TOCTOU) attacks in HTTP clients (like Node fetch)
+ * by ensuring the connection goes to the validated IP, not a re-resolved address.
+ * The original hostname is returned separately so callers can set the Host header.
+ *
+ * For IPv6 addresses, wraps the IP in brackets per RFC 2732.
+ *
+ * @param originalUrl - The original URL (e.g. "https://example.com/path")
+ * @param resolvedIp - The validated IP address to connect to
+ * @returns Object with the connection URL and the original hostname for Host header
+ */
+export declare function buildConnectionUrl(originalUrl: string, resolvedIp: string): {
+    connectionUrl: string;
+    hostHeader: string;
+};
+/**
+ * Validate a URL for the screenshot endpoint to prevent SSRF attacks.
+ *
+ * Checks:
+ * 1. Valid URL format
+ * 2. http: or https: scheme only
+ * 3. Rejects private/internal IP addresses (literal)
+ * 4. Rejects localhost / *.local hostnames
+ *
+ * For full DNS-resolution protection, call resolveAndCheckIp() separately.
+ *
+ * Returns null if valid, or an error string if invalid.
+ */
+export declare function validateScreenshotUrl(rawUrl: string): string | null;