@poolzin/pool-bot 2026.3.22 → 2026.3.24

package/dist/gateway/run-tracker.js

@@ -0,0 +1,253 @@
+/**
+ * Run Tracking System
+ *
+ * Tracks active agent runs with AbortController support for cancellation.
+ * Provides run lifecycle management and resource cleanup.
+ */
+export class RunTracker {
+    runs = new Map();
+    completedRuns = new Map();
+    MAX_COMPLETED_RUNS;
+    constructor(options) {
+        this.MAX_COMPLETED_RUNS = options?.maxCompletedRuns ?? 1000;
+    }
+    /**
+     * Start tracking a new run
+     */
+    startRun(runId, params) {
+        if (this.runs.has(runId)) {
+            throw new Error(`Run ${runId} already exists`);
+        }
+        const abortController = new AbortController();
+        const buffer = new TransformStream();
+        const writer = buffer.writable.getWriter();
+        const reader = buffer.readable.getReader();
+        const state = {
+            abortController,
+            buffer,
+            writer,
+            reader,
+            startTime: Date.now(),
+            model: params.model,
+            sessionKey: params.sessionKey,
+            runId,
+            status: "running",
+            metadata: params.metadata,
+        };
+        this.runs.set(runId, state);
+        return state;
+    }
+    /**
+     * Get run state by ID
+     */
+    getRun(runId) {
+        return this.runs.get(runId);
+    }
+    /**
+     * Check if run exists and is active
+     */
+    hasRun(runId) {
+        return this.runs.has(runId);
+    }
+    /**
+     * Get all active runs
+     */
+    getActiveRuns() {
+        return Array.from(this.runs.values());
+    }
+    /**
+     * Get runs by session key
+     */
+    getRunsBySession(sessionKey) {
+        return Array.from(this.runs.values()).filter((run) => run.sessionKey === sessionKey);
+    }
+    /**
+     * Abort a specific run
+     */
+    async abortRun(runId, reason) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return false;
+        }
+        try {
+            run.status = "aborted";
+            run.abortController.abort(reason);
+            // Cancel writer and reader (ignore errors)
+            try {
+                await run.writer.abort();
+            }
+            catch {
+                // Ignore writer abort errors
+            }
+            try {
+                await run.reader.cancel();
+            }
+            catch {
+                // Ignore reader cancel errors
+            }
+            // Cleanup
+            this.runs.delete(runId);
+            this.markCompleted(run, reason ? new Error(reason) : undefined);
+            return true;
+        }
+        catch (error) {
+            console.error(`Error aborting run ${runId}:`, error);
+            // Still cleanup even if there was an error
+            this.runs.delete(runId);
+            return false;
+        }
+    }
+    /**
+     * Mark run as completed
+     */
+    async completeRun(runId, metadata) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return false;
+        }
+        try {
+            run.status = "completed";
+            // Close streams
+            await run.writer.close();
+            // Cleanup
+            this.runs.delete(runId);
+            this.markCompleted(run, undefined, metadata);
+            return true;
+        }
+        catch (error) {
+            console.error(`Error completing run ${runId}:`, error);
+            run.status = "failed";
+            run.error = error instanceof Error ? error : new Error(String(error));
+            this.runs.delete(runId);
+            this.markCompleted(run, run.error);
+            return false;
+        }
+    }
+    /**
+     * Mark run as failed
+     */
+    async failRun(runId, error) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return false;
+        }
+        try {
+            run.status = "failed";
+            run.error = error;
+            // Cleanup streams (ignore errors)
+            try {
+                await run.writer.abort(error);
+            }
+            catch {
+                // Ignore writer abort errors
+            }
+            try {
+                await run.reader.cancel(error);
+            }
+            catch {
+                // Ignore reader cancel errors
+            }
+            // Cleanup
+            this.runs.delete(runId);
+            this.markCompleted(run, error);
+            return true;
+        }
+        catch (cleanupError) {
+            console.error(`Error failing run ${runId}:`, cleanupError);
+            // Still cleanup even if there was an error
+            this.runs.delete(runId);
+            this.markCompleted(run, error);
+            return false;
+        }
+    }
+    /**
+     * Write data to run buffer
+     */
+    async writeToRun(runId, data) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            throw new Error(`Run ${runId} not found`);
+        }
+        if (run.status !== "running") {
+            throw new Error(`Run ${runId} is not running (status: ${run.status})`);
+        }
+        if (run.abortController.signal.aborted) {
+            throw new Error(`Run ${runId} was aborted`);
+        }
+        await run.writer.write(data);
+    }
+    /**
+     * Get run duration in milliseconds
+     */
+    getRunDuration(runId) {
+        const run = this.runs.get(runId);
+        if (run) {
+            return Date.now() - run.startTime;
+        }
+        const completed = this.completedRuns.get(runId);
+        if (completed && completed.endTime) {
+            return completed.endTime - completed.startTime;
+        }
+        return null;
+    }
+    /**
+     * Get statistics about runs
+     */
+    getStats() {
+        const completed = Array.from(this.completedRuns.values());
+        const durations = completed
+            .filter((r) => r.endTime && r.startTime)
+            .map((r) => r.endTime - r.startTime);
+        const avgDuration = durations.length > 0 ? durations.reduce((a, b) => a + b, 0) / durations.length : 0;
+        return {
+            activeRuns: this.runs.size,
+            completedRuns: completed.filter((r) => r.status === "completed").length,
+            abortedRuns: completed.filter((r) => r.status === "aborted").length,
+            failedRuns: completed.filter((r) => r.status === "failed").length,
+            averageDuration: avgDuration,
+        };
+    }
+    /**
+     * Clear all completed runs from memory
+     */
+    clearCompletedRuns() {
+        this.completedRuns.clear();
+    }
+    /**
+     * Destroy tracker and cleanup all runs
+     */
+    async destroy() {
+        // Abort all active runs
+        const abortPromises = Array.from(this.runs.keys()).map((runId) => this.abortRun(runId, "Tracker destroyed"));
+        await Promise.all(abortPromises);
+        this.runs.clear();
+        this.completedRuns.clear();
+    }
+    markCompleted(run, error, metadata) {
+        const completedMetadata = {
+            runId: run.runId,
+            sessionKey: run.sessionKey,
+            model: run.model,
+            startTime: run.startTime,
+            endTime: Date.now(),
+            status: run.status,
+            error: error?.message,
+            ...run.metadata,
+            ...metadata,
+        };
+        this.completedRuns.set(run.runId, completedMetadata);
+        // Evict oldest if at capacity
+        if (this.completedRuns.size > this.MAX_COMPLETED_RUNS) {
+            const oldest = Array.from(this.completedRuns.entries()).sort((a, b) => a[1].startTime - b[1].startTime)[0];
+            if (oldest) {
+                this.completedRuns.delete(oldest[0]);
+            }
+        }
+    }
+}
+/**
+ * Generate unique run ID
+ */
+export function generateRunId() {
+    return `run_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}

package/dist/gateway/server-methods/nodes.js

@@ -2,6 +2,7 @@ import { loadConfig } from "../../config/config.js";
 import { listDevicePairing } from "../../infra/device-pairing.js";
 import { approveNodePairing, listNodePairing, rejectNodePairing, renamePairedNode, requestNodePairing, verifyNodeToken, } from "../../infra/node-pairing.js";
 import { loadApnsRegistration, resolveApnsAuthConfigFromEnv, sendApnsAlert, sendApnsBackgroundWake, } from "../../infra/push-apns.js";
+import { CommandAnalyzer } from "../../infra/security/command-analyzer.js";
 import { isNodeCommandAllowed, resolveNodeCommandAllowlist } from "../node-command-policy.js";
 import { sanitizeNodeInvokeParamsForForwarding } from "../node-invoke-sanitize.js";
 import { ErrorCodes, errorShape, validateNodeDescribeParams, validateNodeEventParams, validateNodeInvokeParams, validateNodeListParams, validateNodePairApproveParams, validateNodePairListParams, validateNodePairRejectParams, validateNodePairRequestParams, validateNodePairVerifyParams, validateNodeRenameParams, } from "../protocol/index.js";
@@ -529,6 +530,19 @@ export const nodeHandlers = {
                 }));
                 return;
             }
+            // Command security analysis
+            const commandAnalyzer = new CommandAnalyzer();
+            const analysis = commandAnalyzer.analyze(command, []);
+            if (analysis.blockedReason) {
+                context.logGateway.warn(`node.invoke blocked command=${command} nodeId=${nodeId} reason=${analysis.blockedReason}`);
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, analysis.blockedReason, {
+                    details: { command, riskLevel: analysis.riskLevel },
+                }));
+                return;
+            }
+            if (analysis.requiresApproval && analysis.riskLevel !== "low") {
+                context.logGateway.info(`node.invoke requires approval command=${command} nodeId=${nodeId} riskLevel=${analysis.riskLevel}`);
+            }
             const forwardedParams = sanitizeNodeInvokeParamsForForwarding({
                 command,
                 rawParams: p.params,

package/dist/gateway/websocket-preauth-security.js

@@ -0,0 +1,188 @@
+/**
+ * WebSocket Pre-Authentication Security Hardening
+ *
+ * Security fixes for WebSocket pre-auth:
+ * - Shorten unauthenticated handshake retention
+ * - Reject oversized pre-auth frames
+ * - Fail-closed for malformed frames
+ */
+/**
+ * Default security configuration
+ *
+ * Security: Hardened values for production
+ * - 5 second handshake timeout (reduced from 10s)
+ * - 1KB max pre-auth frame size (prevents DoS)
+ * - 3 max pre-auth frames (limits attack surface)
+ */
+export const DEFAULT_PREAUTH_CONFIG = {
+    handshakeTimeoutMs: 5_000, // 5 seconds (reduced from 10s)
+    maxPreAuthFrameSize: 1024, // 1KB
+    maxPreAuthFrames: 3,
+};
+/**
+ * Create a new pre-auth connection state
+ */
+export function createPreAuthConnectionState(ws, config = DEFAULT_PREAUTH_CONFIG) {
+    return {
+        ws,
+        createdAt: Date.now(),
+        frameCount: 0,
+        totalBytesReceived: 0,
+        authenticated: false,
+        config,
+    };
+}
+/**
+ * Start handshake timeout timer
+ *
+ * Security: Shorter timeout reduces attack surface for unauthenticated connections
+ */
+export function startHandshakeTimeout(state, onTimeout) {
+    // Clear any existing timeout
+    if (state.handshakeTimeout) {
+        clearTimeout(state.handshakeTimeout);
+    }
+    // Set new timeout with hardened value
+    state.handshakeTimeout = setTimeout(() => {
+        if (!state.authenticated) {
+            onTimeout();
+        }
+    }, state.config.handshakeTimeoutMs);
+}
+/**
+ * Clear handshake timeout
+ */
+export function clearHandshakeTimeout(state) {
+    if (state.handshakeTimeout) {
+        clearTimeout(state.handshakeTimeout);
+        state.handshakeTimeout = undefined;
+    }
+}
+/**
+ * Validate pre-auth frame size
+ *
+ * Security: Reject oversized frames before authentication to prevent DoS
+ *
+ * Returns true if frame is acceptable, false if it should be rejected
+ */
+export function validatePreAuthFrameSize(state, frameSize) {
+    // Check single frame size
+    if (frameSize > state.config.maxPreAuthFrameSize) {
+        return {
+            valid: false,
+            reason: `Pre-auth frame too large: ${frameSize} bytes (max: ${state.config.maxPreAuthFrameSize})`,
+        };
+    }
+    // Check cumulative size
+    const newTotal = state.totalBytesReceived + frameSize;
+    const maxCumulativeSize = state.config.maxPreAuthFrameSize * state.config.maxPreAuthFrames;
+    if (newTotal > maxCumulativeSize) {
+        return {
+            valid: false,
+            reason: `Pre-auth cumulative size exceeded: ${newTotal} bytes (max: ${maxCumulativeSize})`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Track pre-auth frame reception
+ *
+ * Security: Enforce frame count and size limits
+ *
+ * Returns true if frame is acceptable, false if connection should be closed
+ */
+export function trackPreAuthFrame(state, frameSize) {
+    // Check frame count limit
+    if (state.frameCount >= state.config.maxPreAuthFrames) {
+        return {
+            accepted: false,
+            reason: `Max pre-auth frames exceeded: ${state.frameCount} (max: ${state.config.maxPreAuthFrames})`,
+        };
+    }
+    // Validate frame size
+    const sizeValidation = validatePreAuthFrameSize(state, frameSize);
+    if (!sizeValidation.valid) {
+        return { accepted: false, reason: sizeValidation.reason };
+    }
+    // Update counters
+    state.frameCount++;
+    state.totalBytesReceived += frameSize;
+    return { accepted: true };
+}
+/**
+ * Mark connection as authenticated
+ *
+ * Security: Clear pre-auth restrictions after successful authentication
+ */
+export function markAuthenticated(state) {
+    state.authenticated = true;
+    clearHandshakeTimeout(state);
+}
+/**
+ * Check if connection is still in pre-auth state
+ */
+export function isPreAuth(state) {
+    return !state.authenticated;
+}
+/**
+ * Get connection age in milliseconds
+ */
+export function getConnectionAge(state) {
+    return Date.now() - state.createdAt;
+}
+/**
+ * Analyze WebSocket connection security
+ */
+export function analyzeWebSocketSecurity(state) {
+    const age = getConnectionAge(state);
+    const timeoutRemaining = state.handshakeTimeout
+        ? Math.max(0, state.config.handshakeTimeoutMs - age)
+        : undefined;
+    // Determine security level
+    let securityLevel;
+    if (!state.authenticated && age > state.config.handshakeTimeoutMs) {
+        securityLevel = "critical"; // Overdue for auth
+    }
+    else if (!state.authenticated && age > state.config.handshakeTimeoutMs / 2) {
+        securityLevel = "low"; // Approaching timeout
+    }
+    else if (!state.authenticated) {
+        securityLevel = "medium"; // Normal pre-auth
+    }
+    else {
+        securityLevel = "high"; // Authenticated
+    }
+    return {
+        isPreAuth: isPreAuth(state),
+        connectionAge: age,
+        frameCount: state.frameCount,
+        totalBytesReceived: state.totalBytesReceived,
+        handshakeTimeoutRemaining: timeoutRemaining,
+        securityLevel,
+    };
+}
+/**
+ * Get security event message for logging
+ */
+export function getSecurityEventMessage(event, state) {
+    const analysis = analyzeWebSocketSecurity(state);
+    switch (event) {
+        case "handshake_timeout":
+            return `WebSocket handshake timeout after ${analysis.connectionAge}ms (pre-auth)`;
+        case "frame_size_exceeded":
+            return `WebSocket pre-auth frame size exceeded: ${analysis.totalBytesReceived} bytes`;
+        case "frame_count_exceeded":
+            return `WebSocket pre-auth frame count exceeded: ${analysis.frameCount} frames`;
+        case "authenticated":
+            return `WebSocket authenticated successfully after ${analysis.connectionAge}ms`;
+        default:
+            return `WebSocket security event: ${event}`;
+    }
+}
+/**
+ * Cleanup pre-auth connection state
+ */
+export function cleanupPreAuthConnectionState(state) {
+    clearHandshakeTimeout(state);
+    state.ws.removeAllListeners();
+}

package/dist/hooks/module-loader.js

@@ -0,0 +1,28 @@
+import { pathToFileURL } from "node:url";
+export function resolveFileModuleUrl(params) {
+    const url = pathToFileURL(params.modulePath).href;
+    if (!params.cacheBust) {
+        return url;
+    }
+    const ts = params.nowMs ?? Date.now();
+    return `${url}?t=${ts}`;
+}
+export async function importFileModule(params) {
+    const specifier = resolveFileModuleUrl(params);
+    return (await import(specifier));
+}
+export function resolveFunctionModuleExport(params) {
+    const explicitExport = params.exportName?.trim();
+    if (explicitExport) {
+        const candidate = params.mod[explicitExport];
+        return typeof candidate === "function" ? candidate : undefined;
+    }
+    const fallbacks = params.fallbackExportNames ?? ["default"];
+    for (const exportName of fallbacks) {
+        const candidate = params.mod[exportName];
+        if (typeof candidate === "function") {
+            return candidate;
+        }
+    }
+    return undefined;
+}

package/dist/infra/agent-command-binding.js

@@ -0,0 +1,144 @@
+/**
+ * Agent Command Binding System
+ *
+ * Allows binding specific commands to agents.
+ * Implemented from scratch for Pool Bot architecture.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+const BINDINGS_FILE = path.join(process.cwd(), ".poolbot", "agent-command-bindings.json");
+/**
+ * Load command bindings from file
+ */
+export async function loadCommandBindings() {
+    try {
+        const data = await fs.readFile(BINDINGS_FILE, "utf-8");
+        return JSON.parse(data);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { bindings: {} };
+        }
+        throw error;
+    }
+}
+/**
+ * Save command bindings to file
+ */
+export async function saveCommandBindings(store) {
+    await fs.mkdir(path.dirname(BINDINGS_FILE), { recursive: true });
+    await fs.writeFile(BINDINGS_FILE, JSON.stringify(store, null, 2));
+}
+/**
+ * Bind commands to an agent
+ */
+export async function bindCommandsToAgent(params) {
+    const { agentId, commands, allowlist = true } = params;
+    const now = Date.now();
+    const store = await loadCommandBindings();
+    const existing = store.bindings[agentId];
+    const binding = {
+        agentId,
+        commands: [...new Set(commands)], // Remove duplicates
+        allowlist,
+        createdAt: existing?.createdAt || now,
+        updatedAt: now,
+    };
+    store.bindings[agentId] = binding;
+    await saveCommandBindings(store);
+    return binding;
+}
+/**
+ * Unbind commands from an agent
+ */
+export async function unbindCommandsFromAgent(agentId) {
+    const store = await loadCommandBindings();
+    if (!store.bindings[agentId]) {
+        return false;
+    }
+    delete store.bindings[agentId];
+    await saveCommandBindings(store);
+    return true;
+}
+/**
+ * Get command bindings for an agent
+ */
+export async function getAgentBindings(agentId) {
+    const store = await loadCommandBindings();
+    return store.bindings[agentId];
+}
+/**
+ * Get all command bindings
+ */
+export async function getAllBindings() {
+    const store = await loadCommandBindings();
+    return Object.values(store.bindings);
+}
+/**
+ * Check if a command is allowed for an agent
+ */
+export async function isCommandAllowedForAgent(params) {
+    const { agentId, command } = params;
+    const binding = await getAgentBindings(agentId);
+    // No binding = all commands allowed
+    if (!binding) {
+        return { allowed: true, reason: "No binding - all commands allowed" };
+    }
+    const commandExists = binding.commands.includes(command);
+    if (binding.allowlist) {
+        // Allowlist mode: only these commands are allowed
+        if (commandExists) {
+            return { allowed: true, reason: "Command in allowlist" };
+        }
+        else {
+            return { allowed: false, reason: "Command not in allowlist" };
+        }
+    }
+    else {
+        // Denylist mode: all commands allowed except these
+        if (commandExists) {
+            return { allowed: false, reason: "Command in denylist" };
+        }
+        else {
+            return { allowed: true, reason: "Command not in denylist" };
+        }
+    }
+}
+/**
+ * Add commands to an agent's binding
+ */
+export async function addCommandsToAgent(params) {
+    const { agentId, commands } = params;
+    const binding = await getAgentBindings(agentId);
+    if (!binding) {
+        return bindCommandsToAgent({ agentId, commands });
+    }
+    const updatedCommands = [...new Set([...binding.commands, ...commands])];
+    return bindCommandsToAgent({ agentId, commands: updatedCommands, allowlist: binding.allowlist });
+}
+/**
+ * Remove commands from an agent's binding
+ */
+export async function removeCommandsFromAgent(params) {
+    const { agentId, commands } = params;
+    const binding = await getAgentBindings(agentId);
+    if (!binding) {
+        throw new Error(`No binding found for agent ${agentId}`);
+    }
+    const updatedCommands = binding.commands.filter((cmd) => !commands.includes(cmd));
+    return bindCommandsToAgent({ agentId, commands: updatedCommands, allowlist: binding.allowlist });
+}
+/**
+ * Toggle binding mode (allowlist/denylist)
+ */
+export async function toggleBindingMode(agentId) {
+    const binding = await getAgentBindings(agentId);
+    if (!binding) {
+        throw new Error(`No binding found for agent ${agentId}`);
+    }
+    return bindCommandsToAgent({
+        agentId,
+        commands: binding.commands,
+        allowlist: !binding.allowlist,
+    });
+}