@weavetab/mcp 2.5.0-beta.0

package/SECURITY.md

@@ -0,0 +1,196 @@
+# Weavetab MCP Security Policy
+
+> **Version:** 2.5.0 (Beta) | **Package:** `@weavetab/mcp` | **Last Updated:** August 2026
+
+---
+
+## Supported Versions
+
+Only the latest major release of Weavetab receives security updates. Users are strongly advised to keep their installation current.
+
+| Version | Supported | Security Updates |
+|---------|-----------|------------------|
+| 2.x.x | Yes | Yes |
+| < 2.0 | No | No |
+
+---
+
+## Architecture Context
+
+Weavetab interacts directly with the local Chromium browser instance via the Chrome DevTools Protocol (CDP). Because it can control the browser at the operating system level, Weavetab operates at a highly privileged layer (Layer 0).
+
+### Security Mechanisms
+
+| Mechanism | Description | Implementation |
+|-----------|-------------|----------------|
+| **Domain Blacklist** | High-risk domains (banking portals, IAM providers, cloud infrastructure consoles) are hard-blocked from navigation and interaction | Hardcoded entries + user-configurable `block`/`allow` lists in `~/.Weavetab/policy.json` |
+| **Domain Policy Engine** | Per-domain modes: `allow`, `read-only`, `deny`, `audit` | Policies defined as `{ pattern, mode }` entries; read-only mode blocks mutation tools |
+| **Localhost Binding** | The CDP WebSocket endpoint is strictly bound to `127.0.0.1` | No external network interfaces are exposed |
+| **Zero Cloud Dependency** | Weavetab executes entirely on the local machine | No telemetry, analytics, or user data transmitted unless `telemetry: true` is configured |
+| **Rate Limiting** | Configurable actions-per-minute threshold | Mutex-based enforcement prevents runaway agent behavior |
+| **Role-Based Access Control** | Four roles restrict tool access | `admin`, `operator`, `viewer`, `automation` with permission matrices |
+| **Root Guard** | Prevents execution as root or superuser at startup | `assertNotRoot()` check on Unix systems |
+| **Shadow DOM UI Isolation** | All injected interfaces run in isolated contexts | Prevents host page script tampering |
+| **Blind Injection** | Secrets injected via `browser_type_secret` are masked to `[REDACTED]` in all subsequent DOM reads and audit logs | Domain scoping, Shadow DOM isolation, JS property hardening |
+| **Secrets Management** | Resolves secrets from project-scoped or global `secrets.json` | `JsonSecretStore` with atomic file writes and `chmod 600` enforcement |
+| **Storage Blocker** | Optional nullification of `localStorage`, `sessionStorage`, and `document.cookie` | Prevents tracking and fingerprinting |
+| **Input Filter** | Strips elements with suspicious labels from DOM snapshots | Removes excessive length, invisible Unicode characters, prompt injection patterns |
+| **Two-Factor Lock Validation** | Browser process lock validated by PID liveness + TCP port connectivity | Prevents stale lock false-positives after crashes |
+| **Atomic Config Writes** | Config files written to temp file then renamed atomically | Prevents partial reads from concurrent processes |
+| **Path Traversal Protection** | `downloadDir` and `profileDir` paths validated to reject `..` traversal | Prevents directory escape attacks |
+| **Proxy Credential Detection** | Proxy URLs with embedded credentials rejected with warning | Users must use environment variables instead |
+
+---
+
+## Blind Injection Threat Model
+
+The **Blind Injection** architecture specifically ensures that credentials do not leak back into the LLM context or Weavetab logs.
+
+### Threats Mitigated
+
+- **Accidental context inclusion** — LLM reading the DOM and echoing passwords
+- **Log scraping** — Passwords appearing in plaintext audit logs
+- **DOM snapshot leakage** — Secret values masked as `[REDACTED]` in all subsequent maps, deltas, and AX tree dumps
+- **Prompt injection domain theft** — Domain check runs before the secret value is ever resolved
+
+### Threats NOT Mitigated
+
+- This does **not** protect against a compromised host or a malicious process reading the secrets file directly
+- It is not "zero-knowledge"; Weavetab must read the secret from `secrets.json` to inject it
+
+### Secrets Resolution Order
+
+When `browser_type_secret({ envKey: 'MY_SECRET' })` is called, the `JsonSecretStore` resolves from:
+
+1. `./.Weavetab/secrets.json` (project-scoped, opt-in via `Weavetab secrets init --project`)
+2. `~/.Weavetab/secrets.json` (global default)
+
+The old `EnvSecretProvider` (`.env`-based) is **deprecated and no longer supported**. All secrets must be stored in `secrets.json`. See the [README Secrets Management section](README.md#-secrets-management) for the full CLI workflow.
+
+### Secrets File Format
+
+```json
+{
+  "ACME_CORP_PASSWORD": {
+    "value": "hunter2",
+    "domains": ["login.example.com"],
+    "description": "Account password"
+  },
+  "GITHUB_2FA": {
+    "value": "123456",
+    "domains": ["github.com"],
+    "description": "2FA Code"
+  }
+}
+```
+
+---
+
+## RBAC Role Matrix
+
+| Tool Category | admin | viewer | system |
+|---------------|-------|--------|--------|
+| All mutation tools | ✅ | ❌ | ❌ |
+| Read-only (map, find, scrape, console, eval, inspect, snapshot, screenshot, pdf, cookies, tabs, wait, github_*) | ✅ | ✅ | ❌ |
+| burst, plan, wait, map | ✅ | ❌ | ✅ |
+| System (logs, detect, performance, reset_loop_counter) | ✅ | ❌ | ❌ |
+
+### Role Definitions
+
+- **admin** — Full access to all tools and system operations
+- **viewer** — Read-only access to observation tools only
+- **system** — Restricted to burst/plan/wait/map for automated workflows
+
+---
+
+## Security Architecture Flow
+
+```mermaid
+flowchart TD
+    Inv[Tool Invocation] --> Rate[Rate Limiter]
+    Rate --> Dom[Domain Policy Check]
+    Dom --> RBAC[RBAC Role Check]
+    RBAC --> Custom[Custom Black List?]
+    Custom -- Match --> Block1[Block: SecurityError]
+    Custom -- No Match --> Hard[Hardcoded Blacklist]
+    Hard -- Match --> Block2[Block: SecurityError]
+    Hard -- No Match --> Stop[User Stop Check]
+    Stop --> CDP[CDP Execution]
+    CDP --> Audit[Audit Log]
+    Audit --> Secret[Secret Tool?]
+    Secret -- Yes --> Tracker[SessionSecret Tracker<br/>Marks node as secret]
+    Tracker --> Ret[Return Result]
+    Secret -- No --> Ret
+```
+
+---
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Weavetab, please **do not** open a public GitHub issue.
+
+Instead, report via one of the following channels:
+
+- **Email**: security@Weavetab.dev
+- **GitHub**: Use the private vulnerability reporting feature on the repository
+
+### Disclosure Timeline
+
+1. **48 hours** — Acknowledgment of receipt
+2. **7 days** — Initial assessment and severity classification
+3. **30 days** — Fix deployed (critical) or mitigation plan communicated (moderate)
+
+We strive to provide regular updates on progress throughout the process. If a fix is required, an emergency patch will be published to the NPM registry.
+
+### Severity Classification
+
+| Severity | Definition | Response Time |
+|----------|------------|---------------|
+| **Critical** | Allows unauthorized system access or credential theft | 48 hours |
+| **High** | Allows data exfiltration or privilege escalation | 7 days |
+| **Medium** | Limited impact, requires user interaction | 30 days |
+| **Low** | Minor security issue with minimal impact | Next release |
+
+---
+
+
+
+## Security Best Practices
+
+### For Users
+
+1. **Keep Weavetab Updated** — Always use the latest version to ensure security patches
+2. **Use RBAC** — Restrict tool access using appropriate roles (`admin`, `viewer`, `system`)
+3. **Configure Domain Policies** — Block high-risk domains
+4. **Use Blind Injection** — Never pass passwords or 2FA codes directly to `browser_type`; use `browser_type_secret`
+
+### For Developers
+
+1. **Test Security Features** — Verify domain policies, RBAC, and rate limiting in tests
+2. **Use Least Privilege** - Tools should request only the permissions they need
+
+---
+
+## Security Notifications
+
+To receive security notifications:
+
+- **Watch the GitHub Repository** — Enable releases and security alerts
+- **Subscribe to Security Advisories** — Monitor GitHub Security Advisories for the repository
+- **Review CHANGELOG.md** — Check security updates in release notes
+
+---
+
+## Contact Information
+
+For security-related inquiries:
+
+- **Security Vulnerabilities**: security@Weavetab.dev
+- **Security Questions**: conduct@Weavetab.dev
+- **GitHub Security**: https://github.com/weavetab/mcp/security
+
+---
+
+## License
+
+Weavetab is licensed under AGPL-3.0. Security vulnerabilities should be reported responsibly as outlined in this document. Public disclosure of vulnerabilities before coordination with the maintainers is not permitted.

package/TROUBLESHOOTING.md

@@ -0,0 +1,365 @@
+# Weavetab MCP Troubleshooting Guide
+
+> **Version:** 2.5.0 (Beta) | **Package:** `@weavetab/mcp` | **Last Updated:** August 2026
+
+This guide covers common issues and their solutions when working with Weavetab's MCP tools.
+
+---
+
+## Table of Contents
+
+- [Common Issues](#common-issues)
+- [Configuration Issues](#configuration-issues)
+- [Browser Connection Issues](#browser-connection-issues)
+- [Performance Issues](#performance-issues)
+- [Security Issues](#security-issues)
+- [Debugging Tips](#debugging-tips)
+
+---
+
+## Common Issues
+
+### 1. `browser_map` returns "skipped: true" permanently
+
+**Symptom:** `browser_map` consistently returns a JSON object with `skipped: true` and refuses to map the page, citing a `w:NN` ref that doesn't exist on the current page.
+
+**Cause:** Weavetab's "smart skip" logic prevents wasting tokens on duplicate maps if the DOM hasn't changed. However, cross-session stale state on disk can poison this detection.
+
+**Solutions:**
+- Pass `force: true` to `browser_map` to force a rebuild
+- Navigate to a new page (which clears the URL-specific skip lock)
+- Clear the cache: `Weavetab reset` to clear all session state
+
+**Example:**
+```typescript
+browser_map({ force: true })
+```
+
+---
+
+### 2. `browser_fill` reports "0 succeeded" but the fields actually changed
+
+**Symptom:** The tool fills the form perfectly, but the MCP tool response says the fields failed to apply.
+
+**Cause:** (Fixed in v2.5.0+) Previously, verification was backwards. If you see this in older versions, upgrade to the latest version.
+
+**Solution:** None needed on v2.5.0+. The verification logic correctly compares pre-mutation and post-mutation state.
+
+---
+
+### 3. `browser_type` appends text instead of replacing it
+
+**Symptom:** When trying to type "NEW VALUE" into a field containing "Jane", the field becomes "JaneNEW VALUE".
+
+**Cause:** The auto-clear logic relies on keyboard shortcuts (Ctrl+A, Delete) which can fail if the element loses focus during the split-second execution.
+
+**Solution:** (Fixed in v2.5.0+) Auto-clear now uses atomic JavaScript evaluation to clear fields securely before typing. For older versions, use `clearFirst: true` parameter.
+
+**Example:**
+```typescript
+browser_type({ id: "w:1", text: "NEW VALUE", clearFirst: true })
+```
+
+---
+
+### 4. `browser_select` reports success but the value immediately reverts
+
+**Symptom:** The dropdown changes, but immediately snaps back to the old value, yet the tool reports `success: true`.
+
+**Cause:** Frameworks like React and Vue control form state asynchronously. If Weavetab checks too quickly, it sees the changed DOM before React overrides it.
+
+**Solution:** The tool now implements a 400ms multi-pass verification window for dropdowns to detect asynchronous reversion. If the issue persists, try using `browser_fill` with a small delay.
+
+---
+
+### 5. `browser_click` by label takes 50+ seconds
+
+**Symptom:** `browser_click({ label: "Submit" })` works, but the command hangs for nearly a minute before returning.
+
+**Cause:** Clicking by label requires a full DOM scan. If the click triggers a navigation, older versions would synchronously rebuild the heavy DOM map of the *new* page before returning.
+
+**Solutions:**
+- **Best Practice:** Always use `ref` IDs (`w:42`) from `browser_map` rather than text labels
+- **Fixed in v2.5.0+:** Label clicks now use an LRU cache, and post-navigation DOM mapping is deferred
+
+**Example:**
+```typescript
+// Get fresh refs
+const map = await browser_map()
+// Use ref instead of label
+browser_click({ id: "w:42" })
+```
+
+---
+
+### 6. `browser_inspect` returns `null` for boxModel or styles
+
+**Symptom:** Inspecting an element returns `null` for its box model, preventing layout debugging.
+
+**Cause:** The CDP query fired before the browser finished painting the layout.
+
+**Solution:** The tool now automatically waits 100ms for layout settling and retries up to 3 times. If the issue persists, manually add a small delay before inspection.
+
+---
+
+### 7. `stuck_warning` fires but the page clearly changed
+
+**Symptom:** The tool reports `stuck_warning: true`, but the visual page or text labels visibly changed.
+
+**Cause:** The warning previously relied on strict text matching.
+
+**Solution:** `stuck_warning` now respects the underlying `delta` computation. If the DOM changed, the warning will not fire. If you still see false positives, use `browser_reset_loop_counter` to manually reset.
+
+---
+
+### 8. Extension not loading in headless mode
+
+**Symptom:** The Weavetab extension features (HUD, Voice UI, etc.) don't appear in headless mode.
+
+**Cause:** Chrome extensions don't load in headless mode by default.
+
+**Solution:** Use headed mode (`headless: false` in config) or use the `--headless=new` Chrome flag which supports some extension features.
+
+---
+
+## Configuration Issues
+
+### 1. Domain blacklist not working
+
+**Symptom:** Weavetab allows navigation to blacklisted domains.
+
+**Cause:** Domain blacklist configuration may not be loaded correctly.
+
+**Solution:**
+- Verify `~/.Weavetab/policy.json` exists and is valid JSON
+- Check that the domain pattern matches (wildcards use `*` not regex)
+- Restart Weavetab after modifying policy.json
+
+**Example policy.json:**
+```json
+{
+  "policies": [
+    {
+      "pattern": "*.banking.com",
+      "mode": "deny"
+    }
+  ]
+}
+```
+
+---
+
+### 2. RBAC permissions not enforced
+
+**Symptom:** Restricted roles can access tools they shouldn't.
+
+**Cause:** Role configuration may not be set correctly.
+
+**Solution:**
+- Verify `role` is set in `~/.Weavetab/config.json`
+- Check that the role is one of: `admin`, `system`, `viewer`, `automation`
+- Restart Weavetab after changing roles
+
+---
+
+### 3. Secrets not being injected
+
+**Symptom:** `browser_type_secret` fails to find the secret.
+
+**Cause:** Secrets file may not exist or key may be misconfigured.
+
+**Solution:**
+- Verify `~/.Weavetab/secrets.json` exists
+- Check that the key matches exactly (case-sensitive)
+- For project-scoped secrets, verify `./.Weavetab/secrets.json` exists
+- Use `Weavetab secrets list` to verify keys are registered
+
+---
+
+## Browser Connection Issues
+
+### 1. "CDP connection failed" error
+
+**Symptom:** Weavetab cannot connect to Chrome.
+
+**Cause:** Chrome may not be running with remote debugging enabled, or another process is using the CDP port.
+
+**Solution:**
+- Start Chrome with remote debugging: Check if Chrome is running and listening on the expected port
+- Check if another Weavetab instance is running and bound to the port
+- Check Weavetab logs for port conflicts and restart
+- Verify port 9222 is not in use: `netstat -an | grep 9222` (Linux/macOS) or `netstat -an | findstr 9222` (Windows)
+
+---
+
+### 2. Browser crashes on startup
+
+**Symptom:** Chrome crashes immediately when Weavetab tries to connect.
+
+**Cause:** Extension incompatibility or corrupted Chrome profile.
+
+**Solution:**
+- Try running without extension: Set `loadExtension: false` in config
+- Use a fresh Chrome profile: Set `profileDir` to a new directory
+- Check Chrome version compatibility (requires Chrome 90+)
+- Disable hardware acceleration in Chrome settings
+
+---
+
+### 3. Multiple browser instances conflict
+
+**Symptom:** Weavetab connects to wrong Chrome instance or fails to connect.
+
+**Cause:** Multiple Chrome instances with remote debugging enabled.
+
+**Solution:**
+- Use different CDP ports for each instance
+- Specify port in Weavetab config: `cdpPort: 9223`
+- Close other Chrome instances before starting Weavetab
+
+---
+
+## Performance Issues
+
+### 1. High memory usage
+
+**Symptom:** Weavetab process consuming excessive memory (>500MB).
+
+**Cause:** Large DOM caches or memory leaks in long-running sessions.
+
+**Solution:**
+- Clear cache: `Weavetab reset`
+- Reduce `maxActionsPerMinute` to slow down execution
+- Enable `prune: true` in `browser_map` to reduce cache size
+- Restart Weavetab periodically for long-running sessions
+
+---
+
+### 2. Slow tool execution
+
+**Symptom:** Tools taking longer than expected (>100ms).
+
+**Cause:** Network latency, large DOM trees, or slow CDP responses.
+
+**Solution:**
+- Use `delta: true` in `browser_map` to avoid full DOM walks
+- Enable `prune: true` to reduce DOM size
+- Use `fast: true` in click operations for faster execution
+- Check network connection and Chrome performance
+
+---
+
+### 3. Token usage too high
+
+**Symptom:** LLM context filling up quickly with DOM data.
+
+**Cause:** Full DOM maps on every read.
+
+**Solution:**
+- Use `browser_map({ delta: true, prune: true })` for maximum efficiency
+- Use `browser_find` instead of `browser_map` for text searches
+- Use `browser_scrape` for targeted data extraction
+- Reduce `limit` parameter in `browser_map` for smaller results
+
+---
+
+## Security Issues
+
+### 1. Secrets appearing in logs
+
+**Symptom:** Sensitive data visible in audit logs.
+
+**Cause:** Using `browser_type` instead of `browser_type_secret`.
+
+**Solution:**
+- Always use `browser_type_secret` for credentials
+- Verify secrets are properly masked in logs as `[REDACTED]`
+- Check that `secrets.json` has correct permissions (`chmod 600`)
+
+---
+
+### 2. Domain policy not blocking sensitive sites
+
+**Symptom:** Can navigate to domains that should be blocked.
+
+**Cause:** Policy not configured or pattern doesn't match.
+
+**Solution:**
+- Verify policy.json syntax and patterns
+- Use `*.domain.com` pattern for subdomain matching
+- Restart Weavetab after policy changes
+- Check audit logs to see if policy is being evaluated
+
+---
+
+## Debugging Tips
+
+### Enable DevMode
+
+Set `devMode: true` in `~/.Weavetab/config.json` to see:
+
+- Real-time tool execution timing
+- Token usage estimates
+- Detailed error messages
+- HUD overlay in browser
+
+### Check Audit Logs
+
+Review `~/.Weavetab/logs/audit.log` for:
+
+- Tool invocation history
+- Error messages and stack traces
+- Domain policy violations
+- Security events
+
+### Use Verbose Logging
+
+Set environment variable for verbose output:
+
+```bash
+DEBUG=weavetab:* Weavetab
+```
+
+### Manual Browser Inspection
+
+Connect to Chrome DevTools directly:
+
+1. Start Chrome with remote debugging
+2. Navigate to `chrome://inspect`
+3. Click "inspect" on the target page
+4. Use DevTools to manually inspect DOM and network
+
+
+
+## General Fallbacks
+
+If a tool fails:
+
+1. **Always use `browser_map`** to get fresh `ref` IDs (`w:NN`) after navigation or dynamic changes
+2. If `browser_click` by `ref` fails because the element is occluded or unstable, fall back to `browser_click` with raw `x/y` coordinates
+3. If an element is hidden inside a shadow DOM, pass `ax_tree: true` to `browser_map` to bypass the standard DOM walker and read the raw accessibility tree
+4. If typing fails, try `paste: true` mode or use `browser_eval` to set the value directly
+5. If navigation hangs, try `force: true` or check for blocking dialogs with `browser_dialog`
+
+---
+
+## Getting Help
+
+If you continue to experience issues:
+
+1. **Check the logs** — Review `~/.Weavetab/logs/` for detailed error information
+2. **Search GitHub Issues** — Check if your issue has already been reported
+3. **Create a minimal reproduction** — Provide steps to reproduce the issue
+4. **Include environment details** — OS, Node version, Chrome version, Weavetab version
+5. **Report via GitHub** — Open an issue with all relevant information
+
+**For security issues**, please follow the reporting process in [SECURITY.md](SECURITY.md).
+
+---
+
+## Additional Resources
+
+- [Architecture Documentation](ARCHITECTURE.md)
+- [Tool Reference](docs/TOOLS.md)
+- [Security Policy](SECURITY.md)
+- [Contributing Guidelines](CONTRIBUTING.md)

package/dist/anticaptcha/detector.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Weavetab — anticaptcha/detector.ts
+ * Comprehensive CAPTCHA detection covering all major real-world CAPTCHA types.
+ * Detects: reCAPTCHA v2/v3, hCaptcha, Turnstile, GeeTest, FunCaptcha,
+ *          slider/drag, press-and-hold, DataDome, PerimeterX, and custom CAPTCHAs.
+ * No external API keys. All detection via DOM inspection + CDP.
+ * Weavetab by fy2ne
+ */
+import CDP from "chrome-remote-interface";
+export type CaptchaType = "recaptcha_v2" | "recaptcha_v3" | "hcaptcha" | "turnstile" | "geetest" | "geetest_v4" | "funcaptcha" | "slider" | "press_and_hold" | "datadome" | "perimeter_x" | "custom" | "unknown";
+export type InteractionType = "checkbox" | "image_select" | "drag" | "hold" | "text" | "math" | "rotate" | "none" | "unknown";
+export interface CaptchaDetection {
+    detected: boolean;
+    type: CaptchaType;
+    interactionType: InteractionType;
+    difficulty: "easy" | "medium" | "hard" | "extreme";
+    selector: string;
+    iframe?: string;
+    widgetId?: string;
+    confidence: number;
+    /** Approximate drag distance in pixels for slider CAPTCHAs (0 if unknown) */
+    sliderTrackWidth?: number;
+    /** Estimated hold duration in ms for press-and-hold CAPTCHAs */
+    holdDurationMs?: number;
+    metadata: {
+        siteKey?: string;
+        version?: string;
+        hasAudio?: boolean;
+        hasChallenge?: boolean;
+        requiresUserInteraction?: boolean;
+        geetestVersion?: number;
+        frameOrigin?: string;
+    };
+}
+/**
+ * Comprehensive CAPTCHA detection using multiple heuristics.
+ * Returns the highest-confidence detection found on the page.
+ */
+export declare function detectCaptcha(session: CDP.Client): Promise<CaptchaDetection>;
+/**
+ * Check if a CAPTCHA is currently blocking the workflow.
+ * Uses both detection and a visibility/blocking check.
+ */
+export declare function isCaptchaBlocking(session: CDP.Client): Promise<boolean>;
+/**
+ * Quickly check if the current page shows a CAPTCHA without the full detection.
+ * Cheaper than detectCaptcha — use for polling.
+ */
+export declare function quickCaptchaCheck(session: CDP.Client): Promise<boolean>;