aegis-bridge 2.2.2

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,62 @@
+/**
+ * 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);
+            }
+        }
+    }
+}
+//# sourceMappingURL=sse-limiter.js.map

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,95 @@
+/**
+ * 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.destroy();
+        }
+        catch { /* already closed */ }
+        this.onCleanup();
+    }
+    cleanup() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        this.isDestroyed = true;
+        this.onCleanup();
+    }
+}
+//# sourceMappingURL=sse-writer.js.map

package/dist/ssrf.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+ * - CGNAT: 100.64.0.0/10 (RFC 6598)
+ */
+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. */
+export type DnsLookupFn = (hostname: string) => Promise<DnsLookupResult>;
+/**
+ * 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.
+ *
+ * @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>;
+/**
+ * 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;

package/dist/ssrf.js

@@ -0,0 +1,169 @@
+/**
+ * ssrf.ts — Shared SSRF (Server-Side Request Forgery) prevention utilities.
+ *
+ * Validates URLs by checking scheme, hostname, and DNS resolution against
+ * private/internal IP ranges. Used by webhook channel and screenshot endpoint.
+ */
+import dns from 'node:dns/promises';
+import net from 'node:net';
+/**
+ * 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
+ * - CGNAT: 100.64.0.0/10 (RFC 6598)
+ */
+export function isPrivateIP(ip) {
+    // IPv4
+    if (net.isIPv4(ip)) {
+        const parts = ip.split('.').map(Number);
+        const [a, b] = parts;
+        // 0.0.0.0/8
+        if (a === 0)
+            return true;
+        // 10.0.0.0/8
+        if (a === 10)
+            return true;
+        // 127.0.0.0/8
+        if (a === 127)
+            return true;
+        // 169.254.0.0/16
+        if (a === 169 && b === 254)
+            return true;
+        // 172.16.0.0/12
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        // 192.168.0.0/16
+        if (a === 192 && b === 168)
+            return true;
+        // 100.64.0.0/10 (CGNAT)
+        if (a === 100 && b >= 64 && b <= 127)
+            return true;
+        return false;
+    }
+    // IPv6
+    const lower = ip.toLowerCase();
+    // ::1 (loopback)
+    if (lower === '::1')
+        return true;
+    // :: (unspecified)
+    if (lower === '::')
+        return true;
+    // fe80::/10 (link-local)
+    if (lower.startsWith('fe8') || lower.startsWith('fe9') || lower.startsWith('fea') || lower.startsWith('feb'))
+        return true;
+    // fc00::/7 (unique-local) — includes fc and fd prefixes
+    if (lower.startsWith('fc') || lower.startsWith('fd'))
+        return true;
+    return false;
+}
+/**
+ * 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 function validateWebhookUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch { /* malformed URL string */
+        return 'Invalid URL';
+    }
+    const hostname = parsed.hostname;
+    // Scheme check — must be HTTPS, or HTTP only for local dev
+    const isLocalDev = hostname === '127.0.0.1' || hostname === '::1' || hostname === 'localhost';
+    if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && isLocalDev)) {
+        if (parsed.protocol === 'http:') {
+            return 'Only HTTPS URLs are allowed for external hosts';
+        }
+        return 'Only HTTPS URLs are allowed';
+    }
+    // Reject *.local hostnames (but allow literal localhost for dev)
+    if (hostname.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) {
+        return 'Private/internal IP addresses are not allowed';
+    }
+    return null;
+}
+/** Default DNS lookup using node:dns/promises. */
+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.
+ *
+ * @param hostname - Hostname or literal IP to check
+ * @param lookupFn - Optional DNS lookup function (for testing)
+ */
+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 null;
+    }
+    try {
+        const result = await lookupFn(hostname);
+        if (isPrivateIP(result.address)) {
+            return `DNS resolution points to a private/internal IP: ${result.address}`;
+        }
+        return null;
+    }
+    catch { /* DNS lookup failed — treat as unsafe */
+        return `DNS resolution failed for ${hostname}`;
+    }
+}
+/**
+ * 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 function validateScreenshotUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch { /* malformed URL string */
+        return 'Invalid URL';
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return 'Only http and https URLs are allowed';
+    }
+    const hostname = parsed.hostname;
+    // Reject localhost / *.local hostnames
+    if (hostname === 'localhost' || hostname.endsWith('.local')) {
+        return 'Localhost URLs are not allowed';
+    }
+    // Reject private/internal IPs
+    if (net.isIP(hostname) && isPrivateIP(hostname)) {
+        return 'Private/internal IP addresses are not allowed';
+    }
+    return null;
+}
+//# sourceMappingURL=ssrf.js.map

package/dist/swarm-monitor.d.ts

@@ -0,0 +1,114 @@
+/**
+ * swarm-monitor.ts — Monitors Claude Code swarm sockets for teammate sessions.
+ *
+ * Issue #81: Agent Swarm Awareness.
+ *
+ * When CC spawns teammates/subagents, it creates them in tmux with:
+ *   - Socket: -L claude-swarm-{pid} (isolated from main session)
+ *   - Window naming: teammate-{name}
+ *   - Env vars: CLAUDE_PARENT_SESSION_ID, --agent-id, --agent-name
+ *
+ * This module discovers those swarm sockets, lists their windows,
+ * cross-references with parent sessions, and tracks teammate status.
+ */
+import type { SessionManager, SessionInfo } from './session.js';
+/** Information about a single teammate window in a swarm socket. */
+export interface TeammateInfo {
+    /** Window ID (e.g. "@0") */
+    windowId: string;
+    /** Window name (e.g. "teammate-explore-agent") */
+    windowName: string;
+    /** Working directory of the teammate */
+    cwd: string;
+    /** Current process running in the pane */
+    paneCommand: string;
+    /** Whether the teammate process is alive (claude/node running) */
+    alive: boolean;
+    /** Inferred status from pane command */
+    status: 'running' | 'idle' | 'dead';
+}
+/** A detected swarm (parent + its teammates). */
+export interface SwarmInfo {
+    /** Socket name (e.g. "claude-swarm-12345") */
+    socketName: string;
+    /** PID extracted from socket name */
+    pid: number;
+    /** The parent Aegis session, if found */
+    parentSession: SessionInfo | null;
+    /** Detected teammate windows */
+    teammates: TeammateInfo[];
+    /** Aggregated swarm status */
+    aggregatedStatus: 'all_idle' | 'some_working' | 'all_dead' | 'no_teammates';
+    /** When this swarm was last scanned */
+    lastScannedAt: number;
+}
+/** Result of scanning all swarm sockets. */
+export interface SwarmScanResult {
+    swarms: SwarmInfo[];
+    totalSockets: number;
+    totalTeammates: number;
+    scannedAt: number;
+}
+export interface SwarmMonitorConfig {
+    /** How often to scan for swarm sockets (default: 10s) */
+    scanIntervalMs: number;
+    /** Glob pattern for swarm socket directories */
+    socketGlobPattern: string;
+}
+export declare const DEFAULT_SWARM_CONFIG: SwarmMonitorConfig;
+/** Events emitted by SwarmMonitor when teammate state changes. */
+export type SwarmEvent = {
+    type: 'teammate_spawned';
+    swarm: SwarmInfo;
+    teammate: TeammateInfo;
+} | {
+    type: 'teammate_finished';
+    swarm: SwarmInfo;
+    teammate: TeammateInfo;
+};
+/** Callback for swarm events. */
+export type SwarmEventHandler = (event: SwarmEvent) => void;
+export declare class SwarmMonitor {
+    private sessions;
+    private config;
+    private running;
+    private lastResult;
+    private timer;
+    private eventHandlers;
+    constructor(sessions: SessionManager, config?: SwarmMonitorConfig);
+    /** Register an event handler for teammate lifecycle events. */
+    onEvent(handler: SwarmEventHandler): void;
+    private emitEvent;
+    /** Start the periodic scan loop. */
+    start(): void;
+    /** Stop the periodic scan loop. */
+    stop(): void;
+    /** Get the most recent scan result. */
+    getLastResult(): SwarmScanResult | null;
+    /** Run a single scan and return the result. */
+    scan(): Promise<SwarmScanResult>;
+    /** Compare current scan result against previous to detect teammate changes. */
+    private detectChanges;
+    /** Snapshot of teammates from previous scan for diffing. */
+    private previousTeammates;
+    /** Cached /tmp listing to avoid redundant I/O on every scan. */
+    private cachedSocketNames;
+    private cachedSocketAt;
+    private static readonly SOCKET_CACHE_TTL_MS;
+    /** Discover swarm socket directories in /tmp. */
+    private discoverSwarmSockets;
+    /** Inspect a single swarm socket and return swarm info. */
+    inspectSwarmSocket(socketName: string): Promise<SwarmInfo>;
+    /** Extract PID from socket name "claude-swarm-{pid}". */
+    private extractPid;
+    /** List all windows in a swarm socket. */
+    private listSwarmWindows;
+    /** Find the parent Aegis session for a swarm by matching the CC process PID. */
+    private findParentSession;
+    /** Compute aggregated status for a swarm. */
+    private computeAggregatedStatus;
+    /** Find a specific swarm by parent session ID. */
+    findSwarmByParentSessionId(sessionId: string): SwarmInfo | null;
+    /** Find all swarms associated with any active session. */
+    findActiveSwarms(): SwarmInfo[];
+}