@poolzin/pool-bot 2026.3.17 → 2026.3.18

package/dist/media/fetch.js

@@ -1,21 +1,26 @@
+/**
+ * Secure Media Fetch with SSRF Protection
+ */
 import path from "node:path";
-import { fetchWithSsrFGuard } from "../infra/net/fetch-guard.js";
+import { fetchWithGuard } from "../infra/net/fetch-guard.js";
 import { detectMime, extensionForMime } from "./mime.js";
+import { readResponseWithLimit } from "./read-response-with-limit.js";
 export class MediaFetchError extends Error {
     code;
-    constructor(code, message) {
+    httpStatus;
+    constructor(code, message, httpStatus) {
         super(message);
         this.code = code;
         this.name = "MediaFetchError";
+        this.httpStatus = httpStatus;
     }
 }
 function stripQuotes(value) {
     return value.replace(/^["']|["']$/g, "");
 }
 function parseContentDispositionFileName(header) {
-    if (!header) {
+    if (!header)
         return undefined;
-    }
     const starMatch = /filename\*\s*=\s*([^;]+)/i.exec(header);
     if (starMatch?.[1]) {
         const cleaned = stripQuotes(starMatch[1].trim());
@@ -36,139 +41,105 @@ function parseContentDispositionFileName(header) {
 async function readErrorBodySnippet(res, maxChars = 200) {
     try {
         const text = await res.text();
-        if (!text) {
+        if (!text)
             return undefined;
-        }
         const collapsed = text.replace(/\s+/g, " ").trim();
-        if (!collapsed) {
+        if (!collapsed)
             return undefined;
-        }
-        if (collapsed.length <= maxChars) {
-            return collapsed;
-        }
-        return `${collapsed.slice(0, maxChars)}…`;
+        return collapsed.length <= maxChars ? collapsed : `${collapsed.slice(0, maxChars)}…`;
     }
     catch {
         return undefined;
     }
 }
 export async function fetchRemoteMedia(options) {
-    const { url, fetchImpl, filePathHint, maxBytes, maxRedirects, ssrfPolicy, lookupFn } = options;
-    let res;
-    let finalUrl = url;
-    let release = null;
+    const { url, maxBytes = 100 * 1024 * 1024, readIdleTimeoutMs = 30000, maxRedirects = 5, timeoutMs = 60000, allowPrivateIPs = false, filePathHint, fetchImpl: _fetchImpl, ssrfPolicy, } = options;
+    let parsedUrl;
     try {
-        const result = await fetchWithSsrFGuard({
-            url,
-            fetchImpl,
-            maxRedirects,
-            policy: ssrfPolicy,
-            lookupFn,
-        });
-        res = result.response;
-        finalUrl = result.finalUrl;
-        release = result.release;
+        parsedUrl = new URL(url);
     }
-    catch (err) {
-        throw new MediaFetchError("fetch_failed", `Failed to fetch media from ${url}: ${String(err)}`);
+    catch (error) {
+        throw new MediaFetchError("fetch_failed", `Invalid URL: ${error instanceof Error ? error.message : String(error)}`);
     }
+    let response;
     try {
-        if (!res.ok) {
-            const statusText = res.statusText ? ` ${res.statusText}` : "";
-            const redirected = finalUrl !== url ? ` (redirected to ${finalUrl})` : "";
-            let detail = `HTTP ${res.status}${statusText}`;
-            if (!res.body) {
-                detail = `HTTP ${res.status}${statusText}; empty response body`;
-            }
-            else {
-                const snippet = await readErrorBodySnippet(res);
-                if (snippet) {
-                    detail += `; body: ${snippet}`;
-                }
+        const guardOptions = {
+            allowPrivateIPs,
+            maxRedirects,
+            timeoutMs,
+            ...ssrfPolicy,
+        };
+        response = await fetchWithGuard(url, undefined, guardOptions);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name.includes("FetchGuard")) {
+            const guardError = error;
+            if (guardError.code === "ssrf_blocked") {
+                throw new MediaFetchError("ssrf_blocked", "SSRF protection blocked this request");
             }
-            throw new MediaFetchError("http_error", `Failed to fetch media from ${url}${redirected}: ${detail}`);
-        }
-        const contentLength = res.headers.get("content-length");
-        if (maxBytes && contentLength) {
-            const length = Number(contentLength);
-            if (Number.isFinite(length) && length > maxBytes) {
-                throw new MediaFetchError("max_bytes", `Failed to fetch media from ${url}: content length ${length} exceeds maxBytes ${maxBytes}`);
+            if (guardError.code === "timeout") {
+                throw new MediaFetchError("timeout", "Request timeout");
             }
         }
-        const buffer = maxBytes
-            ? await readResponseWithLimit(res, maxBytes)
-            : Buffer.from(await res.arrayBuffer());
-        let fileNameFromUrl;
-        try {
-            const parsed = new URL(finalUrl);
-            const base = path.basename(parsed.pathname);
-            fileNameFromUrl = base || undefined;
-        }
-        catch {
-            // ignore parse errors; leave undefined
-        }
-        const headerFileName = parseContentDispositionFileName(res.headers.get("content-disposition"));
-        let fileName = headerFileName || fileNameFromUrl || (filePathHint ? path.basename(filePathHint) : undefined);
-        const filePathForMime = headerFileName && path.extname(headerFileName) ? headerFileName : (filePathHint ?? finalUrl);
-        const contentType = await detectMime({
-            buffer,
-            headerMime: res.headers.get("content-type"),
-            filePath: filePathForMime,
-        });
-        if (fileName && !path.extname(fileName) && contentType) {
-            const ext = extensionForMime(contentType);
-            if (ext) {
-                fileName = `${fileName}${ext}`;
-            }
-        }
-        return {
-            buffer,
-            contentType: contentType ?? undefined,
-            fileName,
-        };
+        throw new MediaFetchError("fetch_failed", error instanceof Error ? error.message : String(error));
     }
-    finally {
-        if (release) {
-            await release();
-        }
+    if (!response.ok) {
+        const errorBody = await readErrorBodySnippet(response);
+        throw new MediaFetchError("http_error", `HTTP ${response.status}${errorBody ? `: ${errorBody}` : ""}`, response.status);
     }
-}
-async function readResponseWithLimit(res, maxBytes) {
-    const body = res.body;
-    if (!body || typeof body.getReader !== "function") {
-        const fallback = Buffer.from(await res.arrayBuffer());
-        if (fallback.length > maxBytes) {
-            throw new MediaFetchError("max_bytes", `Failed to fetch media from ${res.url || "response"}: payload exceeds maxBytes ${maxBytes}`);
+    const contentType = response.headers.get("content-type") || undefined;
+    const contentDisposition = response.headers.get("content-disposition");
+    let fileName = parseContentDispositionFileName(contentDisposition);
+    if (!fileName && filePathHint) {
+        fileName = path.basename(filePathHint);
+    }
+    if (!fileName) {
+        const urlPath = parsedUrl.pathname;
+        if (urlPath && urlPath !== "/") {
+            fileName = path.basename(urlPath);
         }
-        return fallback;
     }
-    const reader = body.getReader();
-    const chunks = [];
-    let total = 0;
+    let buffer;
     try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-                break;
+        buffer = await readResponseWithLimit(response, {
+            maxBytes,
+            readIdleTimeoutMs,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "ReadResponseError") {
+            const readError = error;
+            if (readError.code === "max_bytes") {
+                throw new MediaFetchError("max_bytes", `Download exceeds size limit (${maxBytes} bytes)`);
             }
-            if (value?.length) {
-                total += value.length;
-                if (total > maxBytes) {
-                    try {
-                        await reader.cancel();
-                    }
-                    catch { }
-                    throw new MediaFetchError("max_bytes", `Failed to fetch media from ${res.url || "response"}: payload exceeds maxBytes ${maxBytes}`);
-                }
-                chunks.push(value);
+            if (readError.code === "timeout") {
+                throw new MediaFetchError("timeout", "Download timeout - connection stalled");
             }
         }
+        throw new MediaFetchError("fetch_failed", error instanceof Error ? error.message : String(error));
     }
-    finally {
-        try {
-            reader.releaseLock();
+    let finalContentType = contentType;
+    if (!finalContentType) {
+        finalContentType = await detectMime({ buffer });
+    }
+    if (fileName && finalContentType) {
+        const ext = extensionForMime(finalContentType);
+        if (ext && !fileName.toLowerCase().endsWith(ext.toLowerCase())) {
+            fileName = fileName + ext;
         }
-        catch { }
     }
-    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+    return {
+        buffer,
+        contentType: finalContentType,
+        fileName,
+        size: buffer.length,
+    };
+}
+export async function quickFetchMedia(url) {
+    return fetchRemoteMedia({
+        url,
+        maxBytes: 50 * 1024 * 1024,
+        readIdleTimeoutMs: 15000,
+        timeoutMs: 30000,
+    });
 }

package/dist/media/inbound-path-policy.js

@@ -1,114 +1,107 @@
+/**
+ * Inbound Path Policy
+ *
+ * Validates and sanitizes file paths to prevent path traversal attacks
+ */
 import path from "node:path";
-const WILDCARD_SEGMENT = "*";
-const WINDOWS_DRIVE_ABS_RE = /^[A-Za-z]:\//;
-const WINDOWS_DRIVE_ROOT_RE = /^[A-Za-z]:$/;
-export const DEFAULT_IMESSAGE_ATTACHMENT_ROOTS = ["/Users/*/Library/Messages/Attachments"];
-function normalizePosixAbsolutePath(value) {
-    const trimmed = value.trim();
-    if (!trimmed || trimmed.includes("\0")) {
-        return undefined;
+export class InboundPathError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "InboundPathError";
     }
-    const normalized = path.posix.normalize(trimmed.replaceAll("\\", "/"));
-    const isAbsolute = normalized.startsWith("/") || WINDOWS_DRIVE_ABS_RE.test(normalized);
-    if (!isAbsolute || normalized === "/") {
-        return undefined;
-    }
-    const withoutTrailingSlash = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
-    if (WINDOWS_DRIVE_ROOT_RE.test(withoutTrailingSlash)) {
-        return undefined;
-    }
-    return withoutTrailingSlash;
-}
-function splitPathSegments(value) {
-    return value.split("/").filter(Boolean);
 }
-function matchesRootPattern(params) {
-    const candidateSegments = splitPathSegments(params.candidatePath);
-    const rootSegments = splitPathSegments(params.rootPattern);
-    if (candidateSegments.length < rootSegments.length) {
-        return false;
+/**
+ * Validate and resolve an inbound file path
+ */
+export function validateInboundPath(inputPath, options) {
+    const { baseDir, allowOutside = false, allowedExtensions, maxLength = 1024, } = options;
+    // Check path length
+    if (inputPath.length > maxLength) {
+        throw new InboundPathError("too_long", `Path exceeds maximum length (${maxLength} chars)`);
     }
-    for (let idx = 0; idx < rootSegments.length; idx += 1) {
-        const expected = rootSegments[idx];
-        const actual = candidateSegments[idx];
-        if (expected === WILDCARD_SEGMENT) {
-            continue;
-        }
-        if (expected !== actual) {
-            return false;
-        }
-    }
-    return true;
-}
-export function isValidInboundPathRootPattern(value) {
-    const normalized = normalizePosixAbsolutePath(value);
-    if (!normalized) {
-        return false;
-    }
-    const segments = splitPathSegments(normalized);
-    if (segments.length === 0) {
-        return false;
+    // Check for invalid characters
+    const invalidChars = /["<>:"|?*]/g;
+    if (invalidChars.test(inputPath)) {
+        throw new InboundPathError("invalid_chars", "Path contains invalid characters");
     }
-    return segments.every((segment) => segment === WILDCARD_SEGMENT || !segment.includes("*"));
-}
-export function normalizeInboundPathRoots(roots) {
-    const normalized = [];
-    const seen = new Set();
-    for (const root of roots ?? []) {
-        if (typeof root !== "string") {
-            continue;
-        }
-        if (!isValidInboundPathRootPattern(root)) {
-            continue;
-        }
-        const candidate = normalizePosixAbsolutePath(root);
-        if (!candidate || seen.has(candidate)) {
-            continue;
+    // Normalize and resolve path
+    const normalizedPath = path.normalize(inputPath);
+    const resolvedPath = path.resolve(baseDir, normalizedPath);
+    // Check for path traversal
+    if (!allowOutside) {
+        const normalizedBaseDir = path.resolve(baseDir);
+        // Ensure resolved path starts with base directory
+        if (!resolvedPath.startsWith(normalizedBaseDir + path.sep) &&
+            resolvedPath !== normalizedBaseDir) {
+            throw new InboundPathError("path_traversal", "Path traversal detected - path must be within base directory");
         }
-        seen.add(candidate);
-        normalized.push(candidate);
     }
-    return normalized;
-}
-export function mergeInboundPathRoots(...rootsLists) {
-    const merged = [];
-    const seen = new Set();
-    for (const roots of rootsLists) {
-        const normalized = normalizeInboundPathRoots(roots);
-        for (const root of normalized) {
-            if (seen.has(root)) {
-                continue;
-            }
-            seen.add(root);
-            merged.push(root);
+    // Check file extension
+    if (allowedExtensions && allowedExtensions.length > 0) {
+        const ext = path.extname(resolvedPath).toLowerCase();
+        if (!allowedExtensions.includes(ext)) {
+            throw new InboundPathError("invalid_extension", `Extension ${ext} not allowed. Allowed: ${allowedExtensions.join(", ")}`);
         }
     }
-    return merged;
+    return resolvedPath;
 }
-export function isInboundPathAllowed(params) {
-    const candidatePath = normalizePosixAbsolutePath(params.filePath);
-    if (!candidatePath) {
-        return false;
+/**
+ * Sanitize a filename for safe storage
+ */
+export function sanitizeFilename(filename) {
+    // Remove path components
+    let safe = path.basename(filename);
+    // Remove or replace unsafe characters
+    safe = safe.replace(/["<>:"|?*]/g, "_");
+    // Trim leading/trailing spaces and dots
+    safe = safe.replace(/^[\s.]+|[\s.]+$/g, "");
+    // Limit length
+    if (safe.length > 255) {
+        const ext = path.extname(safe);
+        const name = path.basename(safe, ext);
+        safe = name.slice(0, 255 - ext.length) + ext;
     }
-    const roots = normalizeInboundPathRoots(params.roots);
-    const effectiveRoots = roots.length > 0 ? roots : normalizeInboundPathRoots(params.fallbackRoots ?? undefined);
-    if (effectiveRoots.length === 0) {
-        return false;
+    // Ensure not empty
+    if (!safe) {
+        safe = "unnamed";
     }
-    return effectiveRoots.some((rootPattern) => matchesRootPattern({ candidatePath, rootPattern }));
+    return safe;
 }
-function resolveIMessageAccountConfig(params) {
-    const accountId = params.accountId?.trim();
-    if (!accountId) {
-        return undefined;
+/**
+ * Check if a path is safe (within allowed directory)
+ */
+export function isPathSafe(targetPath, baseDir) {
+    try {
+        validateInboundPath(targetPath, { baseDir });
+        return true;
+    }
+    catch {
+        return false;
     }
-    return params.cfg.channels?.imessage?.accounts?.[accountId];
 }
-export function resolveIMessageAttachmentRoots(params) {
-    const accountConfig = resolveIMessageAccountConfig(params);
-    return mergeInboundPathRoots(accountConfig?.attachmentRoots, params.cfg.channels?.imessage?.attachmentRoots, DEFAULT_IMESSAGE_ATTACHMENT_ROOTS);
+/**
+ * Check if a path matches allowed patterns
+ */
+export function isValidInboundPathRootPattern(pattern) {
+    // Basic validation - should not contain traversal sequences
+    return !pattern.includes("..") && !pattern.includes("\\");
 }
-export function resolveIMessageRemoteAttachmentRoots(params) {
-    const accountConfig = resolveIMessageAccountConfig(params);
-    return mergeInboundPathRoots(accountConfig?.remoteAttachmentRoots, params.cfg.channels?.imessage?.remoteAttachmentRoots, accountConfig?.attachmentRoots, params.cfg.channels?.imessage?.attachmentRoots, DEFAULT_IMESSAGE_ATTACHMENT_ROOTS);
+/**
+ * Check if an inbound path is allowed
+ * Supports both (targetPath, baseDir) and ({ filePath, roots }) signatures
+ */
+export function isInboundPathAllowed(targetPathOrOptions, baseDir) {
+    // Handle object signature: { filePath, roots }
+    if (typeof targetPathOrOptions === "object") {
+        const { filePath, roots } = targetPathOrOptions;
+        // Check if path is within any of the allowed roots
+        return roots.some((root) => isPathSafe(filePath, root));
+    }
+    // Handle string signature: (targetPath, baseDir)
+    if (baseDir) {
+        return isPathSafe(targetPathOrOptions, baseDir);
+    }
+    return false;
 }

package/dist/media/read-response-with-limit.js

@@ -1,41 +1,64 @@
-export async function readResponseWithLimit(res, maxBytes, opts) {
-    const onOverflow = opts?.onOverflow ??
-        ((params) => new Error(`Content too large: ${params.size} bytes (limit: ${params.maxBytes} bytes)`));
-    const body = res.body;
-    if (!body || typeof body.getReader !== "function") {
-        const fallback = Buffer.from(await res.arrayBuffer());
-        if (fallback.length > maxBytes) {
-            throw onOverflow({ size: fallback.length, maxBytes, res });
-        }
-        return fallback;
+/**
+ * Read HTTP response body with limits and idle timeout
+ *
+ * Prevents hanging on slow/stalled downloads
+ */
+export class ReadResponseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ReadResponseError";
+    }
+}
+export async function readResponseWithLimit(response, options = {}) {
+    const { maxBytes = 100 * 1024 * 1024, // 100MB default
+    readIdleTimeoutMs = 30000, // 30s default
+     } = options;
+    if (!response.body) {
+        throw new ReadResponseError("read_failed", "Response body is null");
     }
-    const reader = body.getReader();
     const chunks = [];
-    let total = 0;
+    let totalBytes = 0;
+    let lastReadTime = Date.now();
+    const reader = response.body.getReader();
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            // Check idle timeout
+            const idleTime = Date.now() - lastReadTime;
+            if (idleTime > readIdleTimeoutMs) {
+                throw new ReadResponseError("timeout", `Read idle timeout exceeded (${readIdleTimeoutMs}ms)`);
+            }
+            const { done, value } = await Promise.race([
+                reader.read(),
+                new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new ReadResponseError("timeout", "Read timeout"));
+                    }, readIdleTimeoutMs);
+                }),
+            ]);
+            lastReadTime = Date.now();
             if (done) {
                 break;
             }
-            if (value?.length) {
-                total += value.length;
-                if (total > maxBytes) {
-                    try {
-                        await reader.cancel();
-                    }
-                    catch { }
-                    throw onOverflow({ size: total, maxBytes, res });
+            if (value) {
+                totalBytes += value.length;
+                if (totalBytes > maxBytes) {
+                    throw new ReadResponseError("max_bytes", `Response size exceeds limit (${maxBytes} bytes)`);
                 }
                 chunks.push(value);
             }
         }
     }
     finally {
-        try {
-            reader.releaseLock();
-        }
-        catch { }
+        reader.releaseLock();
+    }
+    // Concatenate chunks
+    const result = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
     }
-    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+    return Buffer.from(result);
 }

package/dist/media-understanding/attachments.js

@@ -205,7 +205,7 @@ export class MediaAttachmentCache {
             throw new MediaUnderstandingSkipError("empty", `Attachment ${params.attachmentIndex + 1} has no path or URL.`);
         }
         try {
-            const fetchImpl = (input, init) => fetchWithTimeout(resolveRequestUrl(input), init ?? {}, params.timeoutMs, fetch);
+            const fetchImpl = ((input, init) => fetchWithTimeout(resolveRequestUrl(input), init ?? {}, params.timeoutMs, fetch));
             const fetched = await fetchRemoteMedia({ url, fetchImpl, maxBytes: params.maxBytes });
             entry.buffer = fetched.buffer;
             entry.bufferMime =

package/dist/plugin-sdk/audio.js

@@ -0,0 +1,7 @@
+/**
+ * Pool Bot Plugin SDK - Audio
+ *
+ * Re-exports audio-related plugin utilities
+ */
+export { transcribeAudio, isVoiceCompatibleAudio, } from "../media/audio.js";
+export { extractAudioTags, } from "../media/audio-tags.js";

package/dist/plugin-sdk/bluebubbles.js

@@ -0,0 +1,7 @@
+/**
+ * Pool Bot Plugin SDK - BlueBubbles
+ *
+ * Re-exports BlueBubbles-specific plugin utilities
+ */
+export { createBlueBubblesChannel, } from "../bluebubbles/channel.js";
+export { BLUEBUBBLES_ACTIONS, BLUEBUBBLES_ACTION_NAMES, BLUEBUBBLES_GROUP_ACTIONS, } from "../bluebubbles/actions.js";

package/dist/plugin-sdk/browser.js

@@ -0,0 +1,7 @@
+/**
+ * Pool Bot Plugin SDK - Browser
+ *
+ * Re-exports browser-related plugin utilities
+ */
+export { createBrowserTool, } from "../browser/browser-tool.js";
+export { resolveBrowserConfig, resolveProfile, } from "../browser/config.js";

package/dist/plugin-sdk/canvas.js

@@ -0,0 +1,7 @@
+/**
+ * Pool Bot Plugin SDK - Canvas
+ *
+ * Re-exports canvas-related plugin utilities
+ */
+export { createCanvasTool, } from "../canvas-host/canvas-tool.js";
+export { sendCanvasMessage, } from "../canvas-host/canvas-send.js";

package/dist/plugin-sdk/cron.js

@@ -0,0 +1,7 @@
+/**
+ * Pool Bot Plugin SDK - Cron
+ *
+ * Re-exports cron-related plugin utilities
+ */
+export { createCronTool, } from "../cron/cron-tool.js";
+export { scheduleCronJob, cancelCronJob, listCronJobs, } from "../cron/cron-manager.js";

package/dist/plugin-sdk/discord-actions.js

@@ -0,0 +1,6 @@
+/**
+ * Pool Bot Plugin SDK - Discord Actions
+ *
+ * Re-exports Discord action utilities
+ */
+export { discordSendMessage, discordEditMessage, discordDeleteMessage, discordCreateThread, discordPinMessage, discordUnpinMessage, discordAddReaction, discordRemoveReaction, } from "../discord/actions.js";

package/dist/plugin-sdk/discord.js

@@ -0,0 +1,7 @@
+/**
+ * Pool Bot Plugin SDK - Discord
+ *
+ * Re-exports Discord-specific plugin utilities
+ */
+export { createDiscordChannel, } from "../discord/channel.js";
+export { autoBindSpawnedDiscordSubagent, listThreadBindingsBySessionKey, unbindThreadBindingsBySessionKey, } from "../discord/monitor/thread-bindings.js";

package/dist/plugin-sdk/image.js

@@ -0,0 +1,7 @@
+/**
+ * Pool Bot Plugin SDK - Image
+ *
+ * Re-exports image-related plugin utilities
+ */
+export { resizeToJpeg, getImageMetadata, } from "../media/image-ops.js";
+export { createImageTool, createImageGenerateTool, } from "../media/image-tool.js";

package/dist/plugin-sdk/imessage.js

@@ -0,0 +1,6 @@
+/**
+ * Pool Bot Plugin SDK - iMessage
+ *
+ * Re-exports iMessage-specific plugin utilities
+ */
+export { createIMessageChannel, } from "../imessage/channel.js";