@poolzin/pool-bot 2026.3.6 → 2026.3.9

package/dist/security/capability-manager.js

@@ -0,0 +1,76 @@
+import { capabilityMatches, CapabilityResult } from "./capability.js";
+/**
+ * Manages capability grants for all agents.
+ * Uses a Map for O(1) lookups. Thread-safe for single-threaded Node.js.
+ */
+export class CapabilityManager {
+    grants = new Map();
+    /** Grant capabilities to an agent. Replaces any existing grants. */
+    grant(agentId, capabilities) {
+        this.grants.set(agentId, capabilities);
+    }
+    /** Add capabilities to an agent's existing grants. */
+    add(agentId, capabilities) {
+        const existing = this.grants.get(agentId) ?? [];
+        this.grants.set(agentId, [...existing, ...capabilities]);
+    }
+    /** Check whether an agent has a specific capability. */
+    check(agentId, required) {
+        const grants = this.grants.get(agentId);
+        if (!grants) {
+            return CapabilityResult.denied(`No capabilities registered for agent ${agentId}`);
+        }
+        for (const granted of grants) {
+            if (capabilityMatches(granted, required)) {
+                return CapabilityResult.granted();
+            }
+        }
+        return CapabilityResult.denied(`Agent ${agentId} does not have capability: ${JSON.stringify(required)}`);
+    }
+    /** Check multiple capabilities at once. Returns first denial or grants all. */
+    checkAll(agentId, required) {
+        for (const req of required) {
+            const result = this.check(agentId, req);
+            if (!result.granted)
+                return result;
+        }
+        return CapabilityResult.granted();
+    }
+    /** List all capabilities for an agent. */
+    list(agentId) {
+        return this.grants.get(agentId) ?? [];
+    }
+    /** Remove all capabilities for an agent. */
+    revokeAll(agentId) {
+        this.grants.delete(agentId);
+    }
+    /** Check if an agent has any capabilities registered. */
+    has(agentId) {
+        return this.grants.has(agentId);
+    }
+    /** Get all registered agent IDs. */
+    agents() {
+        return Array.from(this.grants.keys());
+    }
+    /** Clear all grants. */
+    clear() {
+        this.grants.clear();
+    }
+}
+/** Global singleton instance. */
+let globalManager;
+/** Get or create the global capability manager. */
+export function getCapabilityManager() {
+    if (!globalManager) {
+        globalManager = new CapabilityManager();
+    }
+    return globalManager;
+}
+/** Reset the global manager (useful for testing). */
+export function resetCapabilityManager() {
+    globalManager = undefined;
+}
+/** Set a custom global manager (useful for testing). */
+export function setCapabilityManager(manager) {
+    globalManager = manager;
+}

package/dist/security/capability.js

@@ -0,0 +1,147 @@
+/**
+ * Capability-based security system for Pool Bot.
+ *
+ * Inspired by OpenFang's capability system, adapted for TypeScript.
+ * Agents can only perform actions they've been explicitly granted permission for.
+ * Capabilities are immutable after agent creation and enforced at runtime.
+ */
+/** All available capability types for CLI and validation. */
+export const CAPABILITY_TYPES = [
+    // File system
+    "file:read",
+    "file:write",
+    // Network
+    "net:connect",
+    "net:listen",
+    // Tools
+    "tool:invoke",
+    "tool:all",
+    // LLM
+    "llm:query",
+    "llm:maxTokens",
+    // Agent interaction
+    "agent:spawn",
+    "agent:message",
+    "agent:kill",
+    // Memory
+    "memory:read",
+    "memory:write",
+    // Shell
+    "shell:exec",
+    "env:read",
+    // Gateway
+    "gateway:admin",
+    "gateway:channels:read",
+    "gateway:channels:write",
+    // Economic
+    "econ:spend",
+    "econ:earn",
+    "econ:transfer",
+];
+/** Helper to create capability check results. */
+export const CapabilityResult = {
+    granted() {
+        return { granted: true };
+    },
+    denied(reason) {
+        return { granted: false, reason };
+    },
+};
+/** Simple glob pattern matching supporting '*' as wildcard. */
+export function globMatches(pattern, value) {
+    if (pattern === "*")
+        return true;
+    if (pattern === value)
+        return true;
+    // Prefix wildcard: "*.example.com"
+    if (pattern.startsWith("*")) {
+        const suffix = pattern.slice(1);
+        return value.endsWith(suffix);
+    }
+    // Suffix wildcard: "api.*"
+    if (pattern.endsWith("*")) {
+        const prefix = pattern.slice(0, -1);
+        return value.startsWith(prefix);
+    }
+    // Middle wildcard: "api.*.com"
+    const starPos = pattern.indexOf("*");
+    if (starPos !== -1) {
+        const prefix = pattern.slice(0, starPos);
+        const suffix = pattern.slice(starPos + 1);
+        return (value.startsWith(prefix) &&
+            value.endsWith(suffix) &&
+            value.length >= prefix.length + suffix.length);
+    }
+    return false;
+}
+/**
+ * Check whether a required capability matches any granted capability.
+ */
+export function capabilityMatches(granted, required) {
+    // Tool:all grants any specific tool
+    if (granted.type === "tool:all" && required.type === "tool:invoke") {
+        return true;
+    }
+    // Same variant type matching
+    if (granted.type !== required.type)
+        return false;
+    switch (granted.type) {
+        case "file:read":
+        case "file:write":
+            return globMatches(granted.pattern, required.pattern);
+        case "net:connect":
+            return globMatches(granted.pattern, required.pattern);
+        case "net:listen":
+            return granted.port === required.port;
+        case "tool:invoke":
+            return granted.toolId === required.toolId || granted.toolId === "*";
+        case "llm:query":
+            return globMatches(granted.pattern, required.pattern);
+        case "llm:maxTokens":
+            return granted.limit >= required.limit;
+        case "agent:spawn":
+            return true;
+        case "agent:message":
+        case "agent:kill":
+            return globMatches(granted.pattern, required.pattern);
+        case "memory:read":
+        case "memory:write":
+            return globMatches(granted.scope, required.scope);
+        case "shell:exec":
+            return globMatches(granted.pattern, required.pattern);
+        case "env:read":
+            return globMatches(granted.pattern, required.pattern);
+        case "gateway:admin":
+        case "gateway:channels:read":
+            return true;
+        case "gateway:channels:write":
+            return globMatches(granted.pattern, required.pattern);
+        case "econ:spend":
+            return granted.limit >= required.limit;
+        case "econ:earn":
+            return true;
+        case "econ:transfer":
+            return globMatches(granted.pattern, required.pattern);
+        case "tool:all":
+            // tool:all only matches tool:all (already handled above for tool:invoke)
+            return false;
+        default:
+            return false;
+    }
+}
+/**
+ * Validate that child capabilities are a subset of parent capabilities.
+ * Prevents privilege escalation.
+ */
+export function validateCapabilityInheritance(parentCaps, childCaps) {
+    for (const childCap of childCaps) {
+        const isCovered = parentCaps.some((parentCap) => capabilityMatches(parentCap, childCap));
+        if (!isCovered) {
+            return {
+                valid: false,
+                reason: `Privilege escalation denied: child requests ${JSON.stringify(childCap)} but parent does not have a matching grant`,
+            };
+        }
+    }
+    return { valid: true };
+}

package/dist/security/dangerous-tools.js

@@ -14,6 +14,20 @@ export const DEFAULT_GATEWAY_HTTP_TOOL_DENY = [
     "gateway",
     // Interactive setup — requires terminal QR scan, hangs on HTTP
     "whatsapp_login",
+    // Cron automation — scheduling can be used for persistence
+    "cron",
+    // Exec tools — remote code execution risk
+    "exec",
+    "shell",
+    "spawn",
+    // File system mutations
+    "fs_write",
+    "fs_delete",
+    "fs_move",
+    "apply_patch",
+    // Device pairing
+    "device_pair",
+    "pair_device",
 ];
 /**
  * ACP tools that should always require explicit user approval.
@@ -30,5 +44,71 @@ export const DANGEROUS_ACP_TOOL_NAMES = [
     "fs_delete",
     "fs_move",
     "apply_patch",
+    "cron",
+    "exec_approved",
+    "elevated_exec",
 ];
 export const DANGEROUS_ACP_TOOLS = new Set(DANGEROUS_ACP_TOOL_NAMES);
+/**
+ * Tool categories by risk level
+ */
+export const TOOL_CATEGORIES = {
+    /** Execution tools - can run arbitrary code */
+    EXECUTION: ["exec", "spawn", "shell", "exec_approved", "elevated_exec"],
+    /** File system mutators - can modify files */
+    FILE_MUTATORS: ["fs_write", "fs_delete", "fs_move", "apply_patch", "fs_mkdir", "fs_rename"],
+    /** Session orchestrators - can spawn/control sessions */
+    SESSION_ORCHESTRATORS: ["sessions_spawn", "sessions_send", "sessions_kill", "sessions_reset"],
+    /** Gateway control - can reconfigure gateway */
+    GATEWAY_CONTROL: ["gateway", "config_set", "config_reload"],
+    /** Automation - can schedule/automate */
+    AUTOMATION: ["cron", "hook_register", "automation_create"],
+    /** External integrations - can interact with external services */
+    EXTERNAL: ["whatsapp_login", "device_pair", "pair_device", "oauth_flow"],
+};
+/**
+ * Check if a tool is in a specific category
+ */
+export function isToolInCategory(toolName, category) {
+    return TOOL_CATEGORIES[category].includes(toolName);
+}
+/**
+ * Check if a tool is considered dangerous
+ */
+export function isDangerousTool(toolName) {
+    return DANGEROUS_ACP_TOOLS.has(toolName.toLowerCase().trim());
+}
+/**
+ * Check if a tool is denied over HTTP gateway
+ */
+export function isGatewayHttpDenied(toolName) {
+    return DEFAULT_GATEWAY_HTTP_TOOL_DENY.includes(toolName.toLowerCase().trim());
+}
+/**
+ * Get risk level for a tool
+ */
+export function getToolRiskLevel(toolName) {
+    if (["exec", "spawn", "shell", "sessions_spawn"].includes(toolName)) {
+        return "critical";
+    }
+    if (["fs_write", "fs_delete", "apply_patch", "gateway"].includes(toolName)) {
+        return "high";
+    }
+    if (["fs_move", "cron", "sessions_send"].includes(toolName)) {
+        return "medium";
+    }
+    return "low";
+}
+/**
+ * Get tools that require explicit approval
+ */
+export function getToolsRequiringApproval(riskLevel = "high") {
+    const allDangerous = Array.from(DANGEROUS_ACP_TOOLS);
+    if (riskLevel === "critical") {
+        return allDangerous.filter((t) => getToolRiskLevel(t) === "critical");
+    }
+    if (riskLevel === "high") {
+        return allDangerous.filter((t) => ["critical", "high"].includes(getToolRiskLevel(t)));
+    }
+    return allDangerous;
+}

package/dist/security/index.js

@@ -0,0 +1,7 @@
+/**
+ * Security module index exports.
+ */
+export * from "./capability.js";
+export * from "./capability-manager.js";
+export * from "./capability-guards.js";
+export * from "./middleware.js";

package/dist/security/middleware.js

@@ -0,0 +1,105 @@
+import { getCapabilityManager } from "./capability-manager.js";
+import { CapabilityError } from "./capability-guards.js";
+import { logVerbose } from "../globals.js";
+/**
+ * Creates a middleware that checks tool invocation capabilities.
+ */
+export function createCapabilityMiddleware() {
+    return async (ctx, toolId, _args, next) => {
+        const manager = getCapabilityManager();
+        // Check for tool:all first (grants any tool)
+        const allCheck = manager.check(ctx.agentId, { type: "tool:all" });
+        if (allCheck.granted) {
+            logVerbose(`[capability] ${ctx.agentId} granted tool:all for ${toolId}`);
+            return await next();
+        }
+        // Check for specific tool invocation
+        const toolCheck = manager.check(ctx.agentId, {
+            type: "tool:invoke",
+            toolId,
+        });
+        if (!toolCheck.granted) {
+            logVerbose(`[capability] ${ctx.agentId} denied access to tool ${toolId}: ${toolCheck.reason}`);
+            throw new CapabilityError(`Tool '${toolId}' access denied: ${toolCheck.reason}`, ctx.agentId, { type: "tool:invoke", toolId });
+        }
+        logVerbose(`[capability] ${ctx.agentId} granted access to ${toolId}`);
+        return await next();
+    };
+}
+/**
+ * Creates a middleware that checks file access capabilities.
+ */
+export function createFileAccessMiddleware() {
+    return async (ctx, toolId, args, next) => {
+        // Tools that read files
+        if (toolId === "file_read" || toolId === "read_file") {
+            const path = args.path || args.file_path || args.filePath;
+            if (typeof path === "string") {
+                const manager = getCapabilityManager();
+                const check = manager.check(ctx.agentId, {
+                    type: "file:read",
+                    pattern: path,
+                });
+                if (!check.granted) {
+                    throw new CapabilityError(`File read denied for '${path}': ${check.reason}`, ctx.agentId, { type: "file:read", pattern: path });
+                }
+            }
+        }
+        // Tools that write files
+        if (toolId === "file_write" || toolId === "write_file") {
+            const path = args.path || args.file_path || args.filePath;
+            if (typeof path === "string") {
+                const manager = getCapabilityManager();
+                const check = manager.check(ctx.agentId, {
+                    type: "file:write",
+                    pattern: path,
+                });
+                if (!check.granted) {
+                    throw new CapabilityError(`File write denied for '${path}': ${check.reason}`, ctx.agentId, { type: "file:write", pattern: path });
+                }
+            }
+        }
+        return await next();
+    };
+}
+/**
+ * Creates a middleware that checks shell execution capabilities.
+ */
+export function createShellExecutionMiddleware() {
+    return async (ctx, toolId, args, next) => {
+        if (toolId === "shell" || toolId === "bash" || toolId === "exec") {
+            const command = args.command || args.cmd || args.shell;
+            if (typeof command === "string") {
+                const manager = getCapabilityManager();
+                const check = manager.check(ctx.agentId, {
+                    type: "shell:exec",
+                    pattern: command,
+                });
+                if (!check.granted) {
+                    throw new CapabilityError(`Shell execution denied for '${command}': ${check.reason}`, ctx.agentId, { type: "shell:exec", pattern: command });
+                }
+            }
+        }
+        return await next();
+    };
+}
+/**
+ * Composes multiple middlewares into a single middleware.
+ */
+export function composeMiddlewares(...middlewares) {
+    return async (ctx, toolId, args, finalNext) => {
+        let index = 0;
+        const dispatch = async () => {
+            if (index >= middlewares.length) {
+                return await finalNext();
+            }
+            const middleware = middlewares[index++];
+            return await middleware(ctx, toolId, args, dispatch);
+        };
+        return await dispatch();
+    };
+}
+/** Default security middleware stack. */
+export function createDefaultSecurityMiddleware() {
+    return composeMiddlewares(createCapabilityMiddleware(), createFileAccessMiddleware(), createShellExecutionMiddleware());
+}

package/dist/security/types.js

@@ -0,0 +1,12 @@
+/**
+ * Security Module for PoolBot
+ *
+ * Provides enterprise-grade security controls:
+ * - Audit logging for security events
+ * - Dangerous tool detection
+ * - Safe regex validation
+ * - External content validation
+ *
+ * Based on OpenClaw patterns but adapted for PoolBot architecture.
+ */
+export {};