poltertab 1.8.1-beta.1 → 1.9.0-beta.2

package/README.md

@@ -57,10 +57,10 @@ Prefer not to install globally? `npx poltertab setup` does the same thing.
 
 The installer prints this link when it finishes:
 
-1. Download the latest [release zip](https://github.com/abhinav162/poltertab/releases/latest) and unzip it
+1. Download the latest [release zip](https://github.com/abhinav162/poltertab/releases/latest) and unzip it into its own folder (e.g. `unzip poltertab-extension-vX.zip -d poltertab-extension`, or double-click on macOS — which creates a folder automatically)
 2. Open Chrome → `chrome://extensions/`
 3. Enable **Developer mode** (top right toggle)
-4. Click **Load unpacked** and select the unzipped `chrome-extension/` directory
+4. Click **Load unpacked** and select that folder (the one containing `manifest.json`)
 
 Then restart your AI tool so it picks up the new tools.
 
@@ -84,7 +84,7 @@ Running from a clone instead of npm? Point the client at the file directly:
 
 ## Supported MCP Tools
 
-The server exposes 27 tools to the LLM (all prefixed with `browser_`). Every
+The server exposes 28 tools to the LLM (all prefixed with `browser_`). Every
 page-facing tool also takes optional `tabId` and `session` to target a specific
 tab — omit both and PolterTab uses the agent's current tab: the last one it
 navigated, opened or switched to. The first `browser_navigate` (and the first
@@ -215,6 +215,22 @@ tab instead of quietly acting on another one.
 | `browser_tab_switch` | `tabId` or `session`, `focus` | Make another tab current. A tab that does not exist in Chrome returns `tab_not_found`. |
 | `browser_tab_close` | `tabId` or `session`, `force` | Close a tab (default: current). Tabs not opened by PolterTab (including ones adopted via `browser_session_create({tabId})`) return `needs_user_permission` — ask the user, then retry with `force: true`. A tab that does not exist in Chrome returns `tab_not_found`. |
 
+### File upload
+
+| Action | Parameters | Description |
+| -------- | ----------- | ------------- |
+| `browser_upload_file` | `selector` (required), `paths` (required), `method` (`"picker"` or `"drop"`), `tabId`, `session` | Upload local files to a page. `method: "picker"` (default) clicks `selector` and intercepts the OS file chooser via CDP — works for any `<input type="file">` or button that opens one. `method: "drop"` dispatches a DataTransfer drag-and-drop event — use for drop zones. Paths must be within directories listed in `upload_allowed_paths` in `~/.poltertab/config.json`. A brief debugging banner appears during picker uploads (CDP requirement). |
+
+**Configuration** — add `upload_allowed_paths` to `~/.poltertab/config.json` before using `browser_upload_file`:
+
+```json
+{
+  "upload_allowed_paths": ["/Users/you/Documents", "/Users/you/Downloads"]
+}
+```
+
+Always-blocked regardless of the allowlist: `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.config`, `/etc`, `/private/etc`, `/System`, `/private/System`, `/Library`, `/private/Library`, `/proc`, home dotfiles. Note: `/tmp` (and its macOS realpath `/private/tmp`) is **not** blocked and can be added to `upload_allowed_paths` normally.
+
 ### Site memory
 
 | Action | Parameters | Description |
@@ -232,8 +248,7 @@ Selectors are resolved in order:
 3. **XPath** — `//div[@class="foo"]`
 4. **Text match** — exact text content of an element
 
-A miss on all four is retried with shadow-root piercing, so a selector that only
-exists inside a web component still resolves.
+A miss on all four is retried with shadow-root piercing (open roots, one level deep) and top-level same-origin iframe search. Nested iframes (iframe inside iframe) and cross-origin iframes are not supported; the tool returns a clear error in those cases.
 
 ## Troubleshooting & Options
 
@@ -337,6 +352,12 @@ PolterTab servers share that port by design (see above). Both sides must move:
    "args": ["/absolute/path/to/poltertab/mcp-server/index.js", "--port", "7824"]
    ```
 
+**Picker uploads fail while DevTools is open:**
+Chrome allows only one debugger at a time per tab. When DevTools is open on the target tab, `browser_upload_file` (method `"picker"`) fails with "Another debugger is already attached". Close DevTools on that tab before running a picker upload.
+
+**Adding `debugger` permission requires re-approving the extension:**
+Loading or reloading the extension folder after the `debugger` permission was added prompts Chrome to ask for re-approval — the extension is disabled until you click **Keep** or **Allow** on the warning dialog in `chrome://extensions/`. Unpack-loaded extensions do not auto-update, so this only happens when you explicitly reload or update the extension folder.
+
 **Extension not connecting:**
 
 - Ensure the MCP Server is running and pointing to the correct port.

package/mcp-server/index.js

@@ -35,7 +35,11 @@ const {
 } = require("./recipes.js");
 const { extractAll } = require("./extract-all.js");
 const bridge = require("./bridge.js");
+const { validateUploadPaths, MAX_BYTES } = require("./upload-paths.js");
 const OWN_VERSION = require("./../package.json").version;
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
 
 let updateState = { latest: null, updateAvailable: false };
 let noticeDelivered = false;
@@ -179,6 +183,91 @@ const handleToolCall = async (request) => {
   const action = name.replace("browser_", "");
 
   try {
+    // Custom handling for file upload: path allowlist validation + byte reading for drop method
+    if (action === "upload_file") {
+      const opts = args || {};
+      const filePaths = opts.paths || [];
+      const method = opts.method || "picker";
+
+      // Reject unknown methods explicitly (schema enums aren't enforced by every MCP client)
+      if (method !== "drop" && method !== "picker") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown upload method: "${method}". Use "picker" or "drop".`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // Load allowlist from config.json
+      const configFile = path.join(POLTERTAB_HOME, "config.json");
+      let allowedPaths;
+      try {
+        const raw = fs.readFileSync(configFile, "utf8");
+        const cfg = JSON.parse(raw);
+        allowedPaths = Array.isArray(cfg.upload_allowed_paths)
+          ? cfg.upload_allowed_paths
+          : null;
+      } catch (_) {
+        allowedPaths = null;
+      }
+
+      // Validate all paths through the shared module (handles disabled check,
+      // symlink resolution, always-blocked, dotfile, allowlist, and size cap).
+      const validation = validateUploadPaths(filePaths, {
+        allowedPaths,
+        checkSize: method === "drop",
+      });
+      if (!validation.ok) {
+        return {
+          content: [{ type: "text", text: validation.errorText }],
+          isError: true,
+        };
+      }
+
+      // Use the realpathSync'd paths that validation already resolved — what was
+      // checked is what is sent (avoids a TOCTOU window between validate and read).
+      const { resolvedPaths } = validation;
+
+      let bridgeParams;
+      if (method === "drop") {
+        // Read file bytes and base64-encode for DataTransfer injection.
+        const files = [];
+        for (let i = 0; i < resolvedPaths.length; i++) {
+          const resolved = resolvedPaths[i];
+          const buf = fs.readFileSync(resolved);
+          const ext = path.extname(resolved).slice(1).toLowerCase();
+          const mimeMap = {
+            png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
+            gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
+            pdf: "application/pdf", txt: "text/plain", csv: "text/csv",
+            json: "application/json", zip: "application/zip",
+          };
+          const type = mimeMap[ext] || "application/octet-stream";
+          // Use the caller's original path for the file name so a symlink keeps its link name,
+          // not the target's name; bytes are still read from the realpathSync'd resolved path.
+          files.push({ name: path.basename(filePaths[i]), type, data: buf.toString("base64") });
+        }
+        bridgeParams = { selector: opts.selector, files, method: "drop", ...((opts.tabId != null) ? { tabId: opts.tabId } : {}), ...((opts.session != null) ? { session: opts.session } : {}) };
+      } else {
+        // picker method: send the realpathSync'd paths so CDP receives absolute real paths
+        bridgeParams = { selector: opts.selector, paths: resolvedPaths, method: "picker", ...((opts.tabId != null) ? { tabId: opts.tabId } : {}), ...((opts.session != null) ? { session: opts.session } : {}) };
+      }
+
+      process.stderr.write(
+        `[poltertab] upload_file method=${method} files=${filePaths.join(", ")}\n`,
+      );
+
+      const result = await bridge.sendCommand("upload_file", bridgeParams);
+      bridge.noteActiveTab(result && result.tabId);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+
     // Custom handling for network state tool
     if (action === "get_network_state") {
       const opts = args || {};

package/mcp-server/tools.js

@@ -563,6 +563,35 @@ const BROWSER_TOOLS = [
       required: ["obstacle", "solution"],
     },
   },
+  {
+    name: "browser_upload_file",
+    description:
+      "Upload one or more local files to the current page. Works with plain file inputs (visible or hidden), custom upload buttons, shadow-DOM inputs (open roots only, one level deep), top-level same-origin iframes, and drag-and-drop zones. For file inputs and upload buttons, uses CDP (Chrome DevTools Protocol) to intercept the OS file picker — a brief debugging banner appears during the upload. For drop zones, dispatches a DataTransfer drag-and-drop event. Paths must be within directories configured in upload_allowed_paths in ~/.poltertab/config.json. Nested iframes (iframe inside iframe) and cross-origin (out-of-process) iframes are not supported and return a clear error.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: {
+          type: "string",
+          description:
+            "CSS selector for the upload trigger — the visible button, label, or file input itself. For drop zones (method: 'drop'), the selector of the drop target element.",
+        },
+        paths: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Absolute paths to local files to upload. Each must be within a directory listed in upload_allowed_paths in ~/.poltertab/config.json.",
+        },
+        method: {
+          type: "string",
+          enum: ["picker", "drop"],
+          description:
+            "'picker' (default): click the selector and intercept the OS file chooser via CDP — works for any file input or button that opens one. 'drop': dispatch drag-and-drop events with the file bytes — use for drop zones that do not open an OS picker.",
+        },
+        ...TARGET,
+      },
+      required: ["selector", "paths"],
+    },
+  },
 ];
 
 module.exports = { BROWSER_TOOLS, TARGET, SINK };

package/mcp-server/upload-paths.js

@@ -0,0 +1,142 @@
+"use strict";
+
+// Shared path-validation logic for browser_upload_file.
+// Used by both index.js (the MCP server) and group-x.js (tests).
+// Validates an array of file paths against the configured allowlist,
+// the always-blocked list, and the home-dotfile rule.
+//
+// Returns { ok: true } on success, or { ok: false, errorText: string } on
+// the first rejected path. Callers wrap errorText in an MCP error response.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const MAX_BYTES = 10 * 1024 * 1024; // 10 MB per file
+
+// Paths that are never allowed regardless of the allowlist.
+// /private is NOT listed here because /private/tmp and /private/var/folders
+// are legitimate writable locations on macOS (they are the realpaths of /tmp
+// and the system temp dir). Sensitive subdirectories ARE listed instead.
+function buildAlwaysBlocked(homeDir) {
+  return [
+    path.join(homeDir, ".ssh"),
+    path.join(homeDir, ".aws"),
+    path.join(homeDir, ".gnupg"),
+    path.join(homeDir, ".config"),
+    "/etc",
+    "/private/etc",
+    "/System",
+    "/private/System",
+    "/Library",
+    "/private/Library",
+    "/proc",
+  ];
+}
+
+/**
+ * Expand ~ and resolve symlinks in a single allowlist entry.
+ * Returns the real absolute path, or the resolved-but-not-realpathd path if
+ * the directory does not exist yet (so future-created dirs still match).
+ */
+function expandAllowlistEntry(p) {
+  const expanded = p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+  try {
+    return fs.realpathSync(path.resolve(expanded));
+  } catch (_) {
+    return path.resolve(expanded);
+  }
+}
+
+/**
+ * Validate file paths for upload.
+ *
+ * @param {string[]} filePaths   - Raw paths as supplied by the caller.
+ * @param {object}   config
+ * @param {string[]|null} config.allowedPaths  - Raw allowlist entries from config.json;
+ *   null or empty array means uploads are disabled.
+ * @param {boolean}  [config.checkSize]   - When true, also enforce MAX_BYTES.
+ * @param {string}   [config.homeDir]     - Override os.homedir() (tests only).
+ * @returns {{ ok: true } | { ok: false, errorText: string }}
+ */
+function validateUploadPaths(filePaths, config) {
+  const {
+    allowedPaths = null,
+    checkSize = false,
+    homeDir = os.homedir(),
+  } = config;
+
+  if (!allowedPaths || allowedPaths.length === 0) {
+    return {
+      ok: false,
+      errorText:
+        "File uploads are disabled. To enable them, add an upload_allowed_paths array " +
+        "to ~/.poltertab/config.json listing the directories Claude may read files from.\n\n" +
+        "Example:\n{\n  \"upload_allowed_paths\": [\"/Users/you/Documents\", \"/Users/you/Downloads\"]\n}",
+    };
+  }
+
+  const expandedAllowed = allowedPaths.map(expandAllowlistEntry);
+  const alwaysBlocked = buildAlwaysBlocked(homeDir);
+  const resolvedPaths = [];
+
+  for (const p of filePaths) {
+    // Resolve symlinks so a symlink pointing outside the allowlist cannot
+    // bypass the check (e.g. ~/Downloads/key.pem -> ~/.ssh/id_ed25519).
+    let resolved;
+    try {
+      resolved = fs.realpathSync(path.resolve(p));
+    } catch (_) {
+      return { ok: false, errorText: `File not found: "${p}"` };
+    }
+
+    // Always-blocked check
+    for (const blocked of alwaysBlocked) {
+      if (resolved === blocked || resolved.startsWith(blocked + path.sep)) {
+        return {
+          ok: false,
+          errorText: `Access denied: "${p}" is in a protected system directory.`,
+        };
+      }
+    }
+
+    // Deny home dotfiles (direct children of homeDir starting with .)
+    const rel = path.relative(homeDir, resolved);
+    if (!rel.startsWith("..") && rel.startsWith(".") && !rel.includes(path.sep)) {
+      return {
+        ok: false,
+        errorText: `Access denied: "${p}" is a home directory dotfile.`,
+      };
+    }
+
+    // Allowlist check (both sides are realpathSync'd)
+    const allowed = expandedAllowed.some(
+      (a) => resolved === a || resolved.startsWith(a + path.sep),
+    );
+    if (!allowed) {
+      return {
+        ok: false,
+        errorText: `Access denied: "${p}" is not within any configured upload_allowed_paths directory. Check ~/.poltertab/config.json.`,
+      };
+    }
+
+    // Optional size check (drop method only)
+    if (checkSize) {
+      const stat = fs.statSync(resolved);
+      if (stat.size > MAX_BYTES) {
+        return {
+          ok: false,
+          errorText: `File too large: "${path.basename(p)}" is ${(stat.size / 1024 / 1024).toFixed(1)} MB. The drop method supports files up to 10 MB.`,
+        };
+      }
+    }
+
+    resolvedPaths.push(resolved);
+  }
+
+  // resolvedPaths contains the realpathSync'd path for each input — use these
+  // for subsequent reads and CDP calls so what was checked is what is sent.
+  return { ok: true, resolvedPaths };
+}
+
+module.exports = { validateUploadPaths, MAX_BYTES };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poltertab",
-  "version": "1.8.1-beta.1",
+  "version": "1.9.0-beta.2",
   "description": "Let any AI assistant drive and scrape your existing Chrome profile — no headless browser, no complex setup.",
   "bin": {
     "poltertab": "./bin/poltertab.js"