@poolzin/pool-bot 2026.3.7 → 2026.3.10

package/dist/infra/retry.js

@@ -85,5 +85,101 @@ export async function retryAsync(fn, attemptsOrOptions = 3, initialDelayMs = 300
             await sleep(delay);
         }
     }
+    options.onExhausted?.(lastErr, maxAttempts);
     throw lastErr ?? new Error("Retry failed");
 }
+/**
+ * Execute a function with retry logic and return detailed result
+ */
+export async function retryWithResult(fn, options = {}) {
+    const resolved = resolveRetryConfig(DEFAULT_RETRY_CONFIG, options);
+    const maxAttempts = resolved.attempts;
+    const minDelayMs = resolved.minDelayMs;
+    const maxDelayMs = Number.isFinite(resolved.maxDelayMs)
+        ? resolved.maxDelayMs
+        : Number.POSITIVE_INFINITY;
+    const jitter = resolved.jitter;
+    const shouldRetry = options.shouldRetry ?? (() => true);
+    let lastErr;
+    let totalDelayMs = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            return { result, attempts: attempt, totalDelayMs };
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= maxAttempts || !shouldRetry(err, attempt)) {
+                break;
+            }
+            const retryAfterMs = options.retryAfterMs?.(err);
+            const hasRetryAfter = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs);
+            const baseDelay = hasRetryAfter
+                ? Math.max(retryAfterMs, minDelayMs)
+                : minDelayMs * 2 ** (attempt - 1);
+            let delay = Math.min(baseDelay, maxDelayMs);
+            delay = applyJitter(delay, jitter);
+            delay = Math.min(Math.max(delay, minDelayMs), maxDelayMs);
+            totalDelayMs += delay;
+            options.onRetry?.({
+                attempt,
+                maxAttempts,
+                delayMs: delay,
+                err,
+                label: options.label,
+            });
+            await sleep(delay);
+        }
+    }
+    options.onExhausted?.(lastErr, maxAttempts);
+    throw lastErr ?? new Error("Retry failed");
+}
+/**
+ * Check if error is retryable (network errors, rate limits, etc.)
+ */
+export function isRetryableError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        // Network errors
+        if (message.includes("econnreset"))
+            return true;
+        if (message.includes("etimedout"))
+            return true;
+        if (message.includes("econnrefused"))
+            return true;
+        if (message.includes("enotfound"))
+            return true;
+        if (message.includes("network"))
+            return true;
+        if (message.includes("timeout"))
+            return true;
+        // HTTP status codes that are retryable
+        const statusMatch = error.message.match(/status\s+(\d+)/i);
+        if (statusMatch) {
+            const status = parseInt(statusMatch[1], 10);
+            // 429 = Too Many Requests, 502/503/504 = Gateway errors
+            if (status === 429 || status === 502 || status === 503 || status === 504) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Default retry configuration for API calls
+ */
+export const API_RETRY_CONFIG = {
+    attempts: 3,
+    minDelayMs: 1000,
+    maxDelayMs: 10000,
+    jitter: 0.1,
+};
+/**
+ * Default retry configuration for network calls
+ */
+export const NETWORK_RETRY_CONFIG = {
+    attempts: 5,
+    minDelayMs: 500,
+    maxDelayMs: 30000,
+    jitter: 0.1,
+};

package/dist/secrets/index.js

@@ -0,0 +1,28 @@
+/**
+ * Secrets Management System
+ *
+ * Secure secret resolution with support for:
+ * - Environment variables (env:default:KEY)
+ * - JSON files (file:/path/to/secrets.json:key)
+ * - Direct values (backward compatible)
+ *
+ * @example
+ * ```typescript
+ * import { SecretsRuntime, resolveValue } from './secrets/index.js';
+ *
+ * // Create runtime
+ * const runtime = new SecretsRuntime({
+ *   allowDirectValues: true,
+ *   warnOnDirectValues: true
+ * });
+ *
+ * // Resolve API key
+ * runtime.resolve('openaiApiKey', 'env:default:OPENAI_API_KEY');
+ *
+ * // Get resolved value
+ * const apiKey = runtime.get('openaiApiKey');
+ * ```
+ */
+export * from "./types.js";
+export * from "./resolver.js";
+export * from "./runtime.js";

package/dist/secrets/resolver.js

@@ -0,0 +1,185 @@
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+/**
+ * Parse a secret reference string
+ * Formats:
+ * - env:default:KEY - Environment variable
+ * - env:production:KEY - Environment variable from specific source
+ * - file:/path/to/secrets.json:KEY - JSON file
+ * - file:/path/to/secrets.json - Entire JSON file as secret
+ * - raw value - Direct value (backward compatibility)
+ */
+export function parseSecretRef(value) {
+    // Check if it's a reference
+    const envMatch = value.match(/^env:([^:]+):(.+)$/);
+    if (envMatch) {
+        return {
+            isRef: true,
+            ref: {
+                provider: "env",
+                source: envMatch[1],
+                key: envMatch[2],
+            },
+        };
+    }
+    const fileMatch = value.match(/^file:([^:]+):(.+)$/);
+    if (fileMatch) {
+        return {
+            isRef: true,
+            ref: {
+                provider: "file",
+                source: fileMatch[1],
+                key: fileMatch[2],
+            },
+        };
+    }
+    const fileOnlyMatch = value.match(/^file:(.+)$/);
+    if (fileOnlyMatch) {
+        return {
+            isRef: true,
+            ref: {
+                provider: "file",
+                source: fileOnlyMatch[1],
+                key: "", // Entire file
+            },
+        };
+    }
+    // Not a reference - treat as direct value
+    return {
+        isRef: false,
+        rawValue: value,
+    };
+}
+/**
+ * Resolve a secret reference to its value
+ */
+export function resolveSecret(ref, options = {}) {
+    const warnings = [];
+    switch (ref.provider) {
+        case "env":
+            return resolveEnvSecret(ref, options, warnings);
+        case "file":
+            return resolveFileSecret(ref, options, warnings);
+        case "exec":
+            return resolveExecSecret(ref, options, warnings);
+        default:
+            return {
+                value: undefined,
+                resolved: false,
+                warnings: [`Unknown provider: ${String(ref.provider)}`],
+            };
+    }
+}
+function resolveEnvSecret(ref, options, warnings) {
+    const value = process.env[ref.key];
+    if (value === undefined) {
+        if (!options.allowMissing) {
+            warnings.push(`Environment variable ${ref.key} is not set`);
+        }
+        return {
+            value: undefined,
+            resolved: false,
+            source: `env:${ref.source}:${ref.key}`,
+            warnings,
+        };
+    }
+    return {
+        value,
+        resolved: true,
+        source: `env:${ref.source}:${ref.key}`,
+        warnings,
+    };
+}
+function resolveFileSecret(ref, options, warnings) {
+    try {
+        const filePath = resolvePath(ref.source);
+        // Path traversal protection
+        if (options.basePath && !filePath.startsWith(resolvePath(options.basePath))) {
+            warnings.push(`Secret file path outside allowed directory: ${ref.source}`);
+            return {
+                value: undefined,
+                resolved: false,
+                source: `file:${ref.source}`,
+                warnings,
+            };
+        }
+        const content = readFileSync(filePath, "utf-8");
+        // If key is empty, return entire file content
+        if (!ref.key) {
+            return {
+                value: content.trim(),
+                resolved: true,
+                source: `file:${ref.source}`,
+                warnings,
+            };
+        }
+        // Try to parse as JSON
+        try {
+            const json = JSON.parse(content);
+            if (typeof json === "object" && json !== null) {
+                if (ref.key in json) {
+                    const value = String(json[ref.key]);
+                    return {
+                        value,
+                        resolved: true,
+                        source: `file:${ref.source}:${ref.key}`,
+                        warnings,
+                    };
+                }
+                warnings.push(`Key "${ref.key}" not found in JSON file ${ref.source}`);
+            }
+        }
+        catch {
+            // Not valid JSON, treat as plain text
+            warnings.push(`File ${ref.source} is not valid JSON`);
+        }
+        if (!options.allowMissing) {
+            warnings.push(`Could not resolve secret from file: ${ref.source}:${ref.key}`);
+        }
+        return {
+            value: undefined,
+            resolved: false,
+            source: `file:${ref.source}:${ref.key}`,
+            warnings,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`Failed to read file ${ref.source}: ${message}`);
+        return {
+            value: undefined,
+            resolved: false,
+            source: `file:${ref.source}:${ref.key}`,
+            warnings,
+        };
+    }
+}
+function resolveExecSecret(ref, _options, warnings) {
+    // Exec provider not yet implemented
+    warnings.push("Exec provider is not yet implemented");
+    return {
+        value: undefined,
+        resolved: false,
+        source: `exec:${ref.source}:${ref.key}`,
+        warnings,
+    };
+}
+/**
+ * Resolve a value that may be a secret reference or direct value
+ */
+export function resolveValue(value, options = {}) {
+    const parsed = parseSecretRef(value);
+    if (parsed.isRef && parsed.ref) {
+        return resolveSecret(parsed.ref, options);
+    }
+    // Direct value
+    const warnings = [];
+    if (options.warnOnDirectValues && parsed.rawValue !== undefined) {
+        warnings.push("Using direct secret value. Consider using env:default:KEY or file:/path:key format for better security");
+    }
+    return {
+        value: parsed.rawValue,
+        resolved: parsed.rawValue !== undefined,
+        warnings,
+    };
+}

package/dist/secrets/runtime.js

@@ -0,0 +1,142 @@
+import { resolveValue } from "./resolver.js";
+/**
+ * Runtime snapshot for resolved secrets
+ *
+ * This class manages a snapshot of resolved secrets that is created
+ * at startup and remains immutable during runtime for security.
+ */
+export class SecretsRuntime {
+    snapshot;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            allowDirectValues: true,
+            warnOnDirectValues: true,
+            failOnUnresolved: false,
+            ...config,
+        };
+        this.snapshot = {
+            secrets: new Map(),
+            unresolved: [],
+            warnings: [],
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Resolve a single secret and add to snapshot
+     */
+    resolve(key, value) {
+        const result = resolveValue(value, {
+            allowDirectValues: this.config.allowDirectValues,
+            warnOnDirectValues: this.config.warnOnDirectValues,
+            allowMissing: !this.config.failOnUnresolved,
+        });
+        if (result.resolved && result.value !== undefined) {
+            this.snapshot.secrets.set(key, {
+                value: result.value,
+                source: result.source || "direct",
+                warnings: result.warnings,
+            });
+        }
+        else {
+            this.snapshot.unresolved.push(key);
+        }
+        if (result.warnings.length > 0) {
+            this.snapshot.warnings.push(...result.warnings);
+        }
+        return result;
+    }
+    /**
+     * Resolve multiple secrets from an object
+     */
+    resolveObject(obj) {
+        const resolved = {};
+        for (const [key, value] of Object.entries(obj)) {
+            const result = this.resolve(key, value);
+            if (result.value !== undefined) {
+                resolved[key] = result.value;
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Get a resolved secret value
+     */
+    get(key) {
+        return this.snapshot.secrets.get(key)?.value;
+    }
+    /**
+     * Check if a secret is resolved
+     */
+    has(key) {
+        return this.snapshot.secrets.has(key);
+    }
+    /**
+     * Get full snapshot info for a secret
+     */
+    getInfo(key) {
+        return this.snapshot.secrets.get(key);
+    }
+    /**
+     * Get all unresolved keys
+     */
+    getUnresolved() {
+        return [...this.snapshot.unresolved];
+    }
+    /**
+     * Get all warnings
+     */
+    getWarnings() {
+        return [...this.snapshot.warnings];
+    }
+    /**
+     * Get snapshot timestamp
+     */
+    getTimestamp() {
+        return this.snapshot.timestamp;
+    }
+    /**
+     * Create an immutable snapshot copy
+     */
+    createSnapshot() {
+        return {
+            secrets: new Map(this.snapshot.secrets),
+            unresolved: [...this.snapshot.unresolved],
+            warnings: [...this.snapshot.warnings],
+            timestamp: new Date(this.snapshot.timestamp),
+        };
+    }
+    /**
+     * Check if there are any unresolved required secrets
+     */
+    hasUnresolved() {
+        return this.snapshot.unresolved.length > 0;
+    }
+    /**
+     * Get summary of the runtime state
+     */
+    getSummary() {
+        return {
+            resolved: this.snapshot.secrets.size,
+            unresolved: this.snapshot.unresolved.length,
+            warnings: this.snapshot.warnings.length,
+            timestamp: this.snapshot.timestamp,
+        };
+    }
+}
+/**
+ * Global runtime instance (lazy initialized)
+ */
+let globalRuntime = null;
+export function getGlobalRuntime() {
+    if (!globalRuntime) {
+        globalRuntime = new SecretsRuntime();
+    }
+    return globalRuntime;
+}
+export function setGlobalRuntime(runtime) {
+    globalRuntime = runtime;
+}
+export function resetGlobalRuntime() {
+    globalRuntime = null;
+}

package/dist/secrets/types.js

@@ -0,0 +1,11 @@
+/**
+ * Secrets Management System for PoolBot
+ *
+ * Provides secure secret resolution with support for:
+ * - Environment variables (env:default:KEY)
+ * - JSON files (file:/path/to/secrets.json)
+ * - Direct values (for backward compatibility)
+ *
+ * Based on OpenClaw patterns but adapted for PoolBot architecture.
+ */
+export {};

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/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 {};