@poolzin/pool-bot 2026.3.4 → 2026.3.7

package/dist/plugin-sdk/windows-spawn.js

@@ -0,0 +1,214 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+function isFilePath(candidate) {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveWindowsExecutablePath(command, env) {
+    if (command.includes("/") || command.includes("\\") || path.isAbsolute(command)) {
+        return command;
+    }
+    const pathValue = env.PATH ?? env.Path ?? process.env.PATH ?? process.env.Path ?? "";
+    const pathEntries = pathValue
+        .split(";")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const hasExtension = path.extname(command).length > 0;
+    const pathExtRaw = env.PATHEXT ??
+        env.Pathext ??
+        process.env.PATHEXT ??
+        process.env.Pathext ??
+        ".EXE;.CMD;.BAT;.COM";
+    const pathExt = hasExtension
+        ? [""]
+        : pathExtRaw
+            .split(";")
+            .map((ext) => ext.trim())
+            .filter(Boolean)
+            .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
+    for (const dir of pathEntries) {
+        for (const ext of pathExt) {
+            for (const candidateExt of [ext, ext.toLowerCase(), ext.toUpperCase()]) {
+                const candidate = path.join(dir, `${command}${candidateExt}`);
+                if (isFilePath(candidate)) {
+                    return candidate;
+                }
+            }
+        }
+    }
+    return command;
+}
+function resolveEntrypointFromCmdShim(wrapperPath) {
+    if (!isFilePath(wrapperPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(wrapperPath, "utf8");
+        const candidates = [];
+        for (const match of content.matchAll(/"([^"\r\n]*)"/g)) {
+            const token = match[1] ?? "";
+            const relMatch = token.match(/%~?dp0%?\s*[\\/]*(.*)$/i);
+            const relative = relMatch?.[1]?.trim();
+            if (!relative) {
+                continue;
+            }
+            const normalizedRelative = relative.replace(/[\\/]+/g, path.sep).replace(/^[\\/]+/, "");
+            const candidate = path.resolve(path.dirname(wrapperPath), normalizedRelative);
+            if (isFilePath(candidate)) {
+                candidates.push(candidate);
+            }
+        }
+        const nonNode = candidates.find((candidate) => {
+            const base = path.basename(candidate).toLowerCase();
+            return base !== "node.exe" && base !== "node";
+        });
+        return nonNode ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveBinEntry(packageName, binField) {
+    if (typeof binField === "string") {
+        const trimmed = binField.trim();
+        return trimmed || null;
+    }
+    if (!binField || typeof binField !== "object") {
+        return null;
+    }
+    if (packageName) {
+        const preferred = binField[packageName];
+        if (typeof preferred === "string" && preferred.trim()) {
+            return preferred.trim();
+        }
+    }
+    for (const value of Object.values(binField)) {
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+function resolveEntrypointFromPackageJson(wrapperPath, packageName) {
+    if (!packageName) {
+        return null;
+    }
+    const wrapperDir = path.dirname(wrapperPath);
+    const packageDirs = [
+        path.resolve(wrapperDir, "..", packageName),
+        path.resolve(wrapperDir, "node_modules", packageName),
+    ];
+    for (const packageDir of packageDirs) {
+        const packageJsonPath = path.join(packageDir, "package.json");
+        if (!isFilePath(packageJsonPath)) {
+            continue;
+        }
+        try {
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+            const entryRel = resolveBinEntry(packageName, packageJson.bin);
+            if (!entryRel) {
+                continue;
+            }
+            const entryPath = path.resolve(packageDir, entryRel);
+            if (isFilePath(entryPath)) {
+                return entryPath;
+            }
+        }
+        catch {
+            // Ignore malformed package metadata.
+        }
+    }
+    return null;
+}
+export function resolveWindowsSpawnProgramCandidate(params) {
+    const platform = params.platform ?? process.platform;
+    const env = params.env ?? process.env;
+    const execPath = params.execPath ?? process.execPath;
+    if (platform !== "win32") {
+        return {
+            command: params.command,
+            leadingArgv: [],
+            resolution: "direct",
+        };
+    }
+    const resolvedCommand = resolveWindowsExecutablePath(params.command, env);
+    const ext = path.extname(resolvedCommand).toLowerCase();
+    if (ext === ".js" || ext === ".cjs" || ext === ".mjs") {
+        return {
+            command: execPath,
+            leadingArgv: [resolvedCommand],
+            resolution: "node-entrypoint",
+            windowsHide: true,
+        };
+    }
+    if (ext === ".cmd" || ext === ".bat") {
+        const entrypoint = resolveEntrypointFromCmdShim(resolvedCommand) ??
+            resolveEntrypointFromPackageJson(resolvedCommand, params.packageName);
+        if (entrypoint) {
+            const entryExt = path.extname(entrypoint).toLowerCase();
+            if (entryExt === ".exe") {
+                return {
+                    command: entrypoint,
+                    leadingArgv: [],
+                    resolution: "exe-entrypoint",
+                    windowsHide: true,
+                };
+            }
+            return {
+                command: execPath,
+                leadingArgv: [entrypoint],
+                resolution: "node-entrypoint",
+                windowsHide: true,
+            };
+        }
+        return {
+            command: resolvedCommand,
+            leadingArgv: [],
+            resolution: "unresolved-wrapper",
+        };
+    }
+    return {
+        command: resolvedCommand,
+        leadingArgv: [],
+        resolution: "direct",
+    };
+}
+export function applyWindowsSpawnProgramPolicy(params) {
+    if (params.candidate.resolution !== "unresolved-wrapper") {
+        return {
+            command: params.candidate.command,
+            leadingArgv: params.candidate.leadingArgv,
+            resolution: params.candidate.resolution,
+            windowsHide: params.candidate.windowsHide,
+        };
+    }
+    if (params.allowShellFallback !== false) {
+        return {
+            command: params.candidate.command,
+            leadingArgv: [],
+            resolution: "shell-fallback",
+            shell: true,
+        };
+    }
+    throw new Error(`${path.basename(params.candidate.command)} wrapper resolved, but no executable/Node entrypoint could be resolved without shell execution.`);
+}
+export function resolveWindowsSpawnProgram(params) {
+    const candidate = resolveWindowsSpawnProgramCandidate(params);
+    return applyWindowsSpawnProgramPolicy({
+        candidate,
+        allowShellFallback: params.allowShellFallback,
+    });
+}
+export function materializeWindowsSpawnProgram(program, argv) {
+    return {
+        command: program.command,
+        argv: [...program.leadingArgv, ...argv],
+        resolution: program.resolution,
+        shell: program.shell,
+        windowsHide: program.windowsHide,
+    };
+}

package/dist/security/capability-guards.js

@@ -0,0 +1,89 @@
+import { getCapabilityManager } from "./capability-manager.js";
+/** Error thrown when a capability check fails. */
+export class CapabilityError extends Error {
+    agentId;
+    required;
+    constructor(message, agentId, required) {
+        super(message);
+        this.agentId = agentId;
+        this.required = required;
+        this.name = "CapabilityError";
+    }
+}
+/** Guard function that throws if capability is denied. */
+export function requireCapability(agentId, required) {
+    const manager = getCapabilityManager();
+    const check = manager.check(agentId, required);
+    if (!check.granted) {
+        throw new CapabilityError(check.reason, agentId, required);
+    }
+}
+/** Async guard that returns a promise rejection if denied. */
+export async function withCapability(agentId, required, fn) {
+    requireCapability(agentId, required);
+    return await fn();
+}
+/** Helper to check file read capability. */
+export function checkFileRead(agentId, path) {
+    return getCapabilityManager().check(agentId, {
+        type: "file:read",
+        pattern: path,
+    });
+}
+/** Helper to check file write capability. */
+export function checkFileWrite(agentId, path) {
+    return getCapabilityManager().check(agentId, {
+        type: "file:write",
+        pattern: path,
+    });
+}
+/** Helper to check tool invocation capability. */
+export function checkToolInvoke(agentId, toolId) {
+    return getCapabilityManager().check(agentId, {
+        type: "tool:invoke",
+        toolId,
+    });
+}
+/** Helper to check network connection capability. */
+export function checkNetConnect(agentId, host) {
+    return getCapabilityManager().check(agentId, {
+        type: "net:connect",
+        pattern: host,
+    });
+}
+/** Helper to check shell execution capability. */
+export function checkShellExec(agentId, command) {
+    return getCapabilityManager().check(agentId, {
+        type: "shell:exec",
+        pattern: command,
+    });
+}
+/** Helper to check LLM query capability. */
+export function checkLlmQuery(agentId, model) {
+    return getCapabilityManager().check(agentId, {
+        type: "llm:query",
+        pattern: model,
+    });
+}
+/** Helper to check agent spawn capability. */
+export function checkAgentSpawn(agentId) {
+    return getCapabilityManager().check(agentId, { type: "agent:spawn" });
+}
+/** Helper to check memory read capability. */
+export function checkMemoryRead(agentId, scope) {
+    return getCapabilityManager().check(agentId, {
+        type: "memory:read",
+        scope,
+    });
+}
+/** Helper to check memory write capability. */
+export function checkMemoryWrite(agentId, scope) {
+    return getCapabilityManager().check(agentId, {
+        type: "memory:write",
+        scope,
+    });
+}
+/** Helper to check gateway admin capability. */
+export function checkGatewayAdmin(agentId) {
+    return getCapabilityManager().check(agentId, { type: "gateway:admin" });
+}

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/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/shared/net/ip-test-fixtures.js

@@ -0,0 +1 @@
+export const blockedIpv6MulticastLiterals = ["ff02::1", "ff05::1:3", "[ff02::1]"];