@weavetab/mcp 2.5.0 → 2.5.1

package/docs/PLUGINS.md

@@ -1,121 +1,139 @@
-# Weavetab Plugin System & SDK Specification
-
-> **Version:** 2.5.0 | **SDK:** @weavetab/sdk (MIT) | **Runtime:** AGPL-3.0-only
-
-The **Weavetab Plugin System** allows developers to extend the MCP runtime with custom tools, visual HUD overlays, thought bubbles, lifecycle hooks, and tool overrides.
-
----
-
-## 1. Quick Start
-
-### Scaffold a New Plugin
-````bash
-npx @weavetab/sdk init my-custom-plugin
-cd my-custom-plugin
-npm install
-`
-
-### Build & Compile
-````bash
-npm run build
-`
-
----
-
-## 2. Plugin Architecture
-
-Every Weavetab plugin exports a plugin definition created with definePlugin:
-
-`	ypescript
-// src/index.ts
-import { definePlugin, type PluginContext } from @weavetab/sdk;
-
-export default definePlugin({
-  name: weavetab-plugin-sample,
-  version: 1.0.0,
-  description: Sample custom tool plugin for Weavetab,
-
-  defaultConfig: {
-    enableHud: true,
-  },
-
-  async onLoad(ctx: PluginContext) {
-    // Register a custom MCP tool
-    ctx.mcp.registerTool({
-      name: custom_analyzer,
-      description: Performs custom DOM analysis,
-      schema: {
-        type: object,
-        properties: {
-          selector: { type: string, description: Target CSS selector }
-        },
-        required: [selector]
-      },
-      handler: async (args: { selector: string }, session: any) => {
-        // Show thought bubble on browser tab
-        if (ctx.config.enableHud && session) {
-          await ctx.extension.showThought(session, Analyzing ...);
-        }
-
-        return {
-          content: [
-            { type: text, text: Analysis complete for  }
-          ]
-        };
-      }
-    });
-  },
-
-  async onUnload(ctx: PluginContext) {
-    // Cleanup resources
-  }
-});
-`
-
----
-
-## 3. Manifest Specification (weavetab.json)
-
-Plugins require a weavetab.json manifest in their package root:
-
-`json
-{
-  name: weavetab-plugin-sample,
-  version: 1.0.0,
-  entry: ./dist/index.js,
-  permissions: [storage, extension, cdp],
-  tools: [custom_analyzer]
-}
-`
-
----
-
-## 4. Plugin Capabilities
-
-| Capability | API | Description |
-| :--- | :--- | :--- |
-| **Sandboxed Storage** | ctx.storage.get(), ctx.storage.set() | Isolated key-value storage in ~/.weavetab/plugins/<name>/. |
-| **Thought Bubbles** | ctx.extension.showThought(session, text) | Floating green thoughts on the live browser tab. |
-| **HUD Badges** | ctx.extension.setHudState(session, state) | Real-time status in the Weavetab overlay. |
-| **Tool Overrides** | ctx.mcp.overrideTool(name, wrapperFn) | Wrap or intercept built-in MCP tools with custom pre/post logic. |
-| **Lifecycle Hooks** | ctx.hooks.beforeToolCall, ctx.hooks.afterToolCall | Global auditing and security filters. |
-
----
-
-## 5. Installing Plugins
-
-```bash
-# Install an official plugin
-weavetab plugin add @weavetab/plugin-youtube
-
-# Install community plugins (any npm package)
-weavetab plugin add my-custom-plugin
-
-# List installed plugins
-weavetab plugin list
-
-# Remove a plugin
-weavetab plugin rm my-custom-plugin
-`
-
-Restart weavetab to load the newly installed plugin tools into the MCP server.
+# Weavetab Plugin System & SDK Specification
+
+> **Version:** 2.5.1 | **SDK:** @weavetab/sdk (MIT) | **Runtime:** AGPL-3.0-only
+
+The **Weavetab Plugin System** allows developers to extend the MCP runtime with custom tools, visual HUD overlays, thought bubbles, lifecycle hooks, and tool overrides.
+
+---
+
+## 1. Quick Start
+
+### Scaffold a New Plugin
+
+```bash
+npx @weavetab/sdk init my-custom-plugin
+cd my-custom-plugin
+npm install
+```
+
+### Build & Compile
+
+```bash
+npm run build
+```
+
+---
+
+## 2. Plugin Architecture
+
+Every Weavetab plugin exports a plugin definition created with `definePlugin`:
+
+```typescript
+// src/index.ts
+import { definePlugin, type PluginContext } from "@weavetab/sdk";
+
+export default definePlugin({
+  name: "weavetab-plugin-sample",
+  version: "1.0.0",
+  description: "Sample custom tool plugin for Weavetab",
+
+  defaultConfig: {
+    enableHud: true,
+  },
+
+  async onLoad(ctx: PluginContext) {
+    // Register a custom MCP tool
+    ctx.mcp.registerTool({
+      name: "custom_analyzer",
+      description: "Performs custom DOM analysis",
+      schema: {
+        type: "object",
+        properties: {
+          selector: { type: "string", description: "Target CSS selector" }
+        },
+        required: ["selector"]
+      },
+      handler: async (args: { selector: string }, session: any) => {
+        // Show thought bubble on the browser tab
+        if (ctx.config.enableHud && session) {
+          await ctx.extension.showThought(session, `Analyzing ${args.selector}`);
+        }
+
+        return {
+          content: [
+            { type: "text", text: `Analysis complete for ${args.selector}` }
+          ]
+        };
+      }
+    });
+  },
+
+  async onUnload(ctx: PluginContext) {
+    // Cleanup resources
+  }
+});
+```
+
+---
+
+## 3. Manifest Specification (weavetab.json)
+
+Plugins require a `weavetab.json` manifest in their package root:
+
+```json
+{
+  "$schema": "https://weavetab.dev/schema/plugin.json",
+  "name": "weavetab-plugin-sample",
+  "version": "1.0.0",
+  "entry": "dist/index.js",
+  "engines": {
+    "weavetab": "^2.5.1",
+    "node": ">=18.0.0"
+  },
+  "permissions": {
+    "extension": { "hud": true, "reason": "Displays HUD thoughts" },
+    "cdp": { "evaluate": true, "reason": "Runs DOM analysis" },
+    "tools": { "add": true, "reason": "Registers the custom_analyzer tool" }
+  },
+  "tools": [
+    {
+      "name": "custom_analyzer",
+      "description": "Performs custom DOM analysis"
+    }
+  ]
+}
+```
+
+> Registering tools at runtime via `ctx.mcp.registerTool()` requires the `permissions.tools.add` permission.
+
+---
+
+## 4. Plugin Capabilities
+
+| Capability | API | Description |
+| :--- | :--- | :--- |
+| **Sandboxed Storage** | `ctx.storage.get()`, `ctx.storage.set()` | Isolated key-value storage in `~/.weavetab/plugins/<name>/`. |
+| **Thought Bubbles** | `ctx.extension.showThought(session, text)` | Floating green thoughts on the live browser tab. |
+| **HUD Badges** | `ctx.extension.setHudState(session, state)` | Real-time status in the Weavetab overlay. |
+| **Tool Overrides** | `ctx.mcp.overrideTool(name, wrapperFn)` | Wrap or intercept built-in MCP tools with custom pre/post logic. |
+| **Lifecycle Hooks** | `ctx.hooks.beforeToolCall`, `ctx.hooks.afterToolCall` | Global auditing and security filters. |
+
+---
+
+## 5. Installing Plugins
+
+```bash
+# Install a plugin by npm package name
+weavetab plugin add my-custom-plugin
+
+# Install from a local path
+weavetab plugin add ./my-plugin
+
+# List installed plugins
+weavetab plugin list
+
+# Remove a plugin
+weavetab plugin rm my-custom-plugin
+```
+
+Restart Weavetab to load the newly installed plugin tools into the MCP server.

package/docs/TOOLS.md

@@ -1,8 +1,8 @@
 # Weavetab MCP Tool Reference
 
-> **Version:** 2.5.0 | **Total Tools:** 42 | **Architecture:** Layer 0 Direct CDP
+> **Version:** 2.5.1 | **Total Tools:** 41 | **Architecture:** Layer 0 Direct CDP
 
-Weavetab provides 42 production-grade MCP tools organized into functional categories.
+Weavetab provides 41 production-grade MCP tools organized into functional categories.
 
 | Tool Name | Category | Description | Key Features |
 | :--- | :--- | :--- | :--- |
@@ -45,10 +45,9 @@ Weavetab provides 42 production-grade MCP tools organized into functional catego
 | `browser_detect` | `tabs` | CRITICAL INITIALIZATION TOOL. Detect available browsers and configured desktop apps (Discord, Slack, etc.). Call this FIRST before interacting with the environment to know if apps are online/offline and what tabs they have open. | Local browser engine discovery, Engine CDP API coverage analysis, Tool compatibility reporting per browser engine |
 | `browser_performance` | `performance` | Retrieve page performance metrics. Collects Core Web Vitals (FCP, LCP, CLS) and detailed network resource timing distributions. | First Contentful Paint (FCP) and Largest Contentful Paint (LCP) capture, Cumulative Layout Shift (CLS) tracking, Resource loading timing distributions |
 | `browser_pattern_learn` | `memory` | Read (action=get), register (action=learn), update, or record execution outcome for a named workflow pattern on a given origin in ~/.weavetab-system/memory/sites/. Use action=get at session start to inspect site profiles and reliability scores. Use learn after completing a flow to persist it for future fast-path replay. | Site profile inspection via action=get (reads ~/.weavetab-system/memory/sites/), Named pattern creation and update (merge-on-write, no duplicates), Volatile selector stabilization before persistence |
-| `browser_github` | `github` | Interact with GitHub repositories without burning browser turns. Analyze repo trees, read raw source files, search/inspect issues, and examine PR diffs and review comments. | Action-based repo analysis, file reading, issues, and PR review, Zero GitHub API token requirement for raw reads, Automated active tab repository context resolution |
 | `browser_office` | `documents` | Read and extract structured content from office documents (Excel, Word, PDF, CSV) via live browser session cookies or local downloads directory. | In-session authenticated document fetching, Structured tabular extraction (.xlsx, .csv), Document text and metadata extraction (.docx, .pdf) |
 | `browser_emulate` | `environment` | Emulate browser environmental conditions over CDP: network throttling profiles, CPU slowdown multipliers, geolocation overrides, timezone IDs, and custom User-Agent strings. | Network throttling (Offline, Slow 3G, Fast 3G, 4G), CPU throttling multipliers, Geolocation and timezone overrides |
 
 ---
 
-*Auto-generated via `npm run docs:generate` on 2026-10-17.*
+*Auto-generated via `npm run docs:generate` on 2026-10-18.*

package/docs/architecture/blind-injection.md

@@ -1,83 +1,83 @@
----
-title: "Blind Injection"
-description: "Enterprise-grade credential injection that never exposes secrets to the LLM."
-product: mcp
-section: architecture
-icon: Lock
-slug: blind-injection
----
-
-# Blind Injection & Secret Containment
-
-The `browser_type_secret` tool and automated secret detection engine resolve passwords, tokens, API keys, PINs, and credentials directly from encrypted storage on the local host — **ensuring sensitive values never cross into the AI agent's context stream or tool outputs**.
-
-## Core Architecture
-
-```
-[Encrypted secrets.json]
-         │
-         ▼ (In-process resolution & domain validation)
-[Weavetab Server]
-         │
-         ▼ (Atomic CDP Input.insertText / ghostType)
-[Chromium Target Field]
-         │
-         ├─► DOM Property Hardening (getter override, symbol coercion, toJSON)
-         ├─► In-Memory SessionSecretTracker (backendNodeId & text redaction)
-         └─► Dynamic Visual Masking (screenshot, snapshot, PDF blanking)
-```
-
-## Multi-Layer Containment Mechanisms
-
-### 1. Zero-Exposure Injection
-- Secrets are stored encrypted with AES-256-GCM via `weavetab secrets set <KEY>`.
-- The agent passes the key name (`envKey: "MY_KEY"`), never the plaintext value.
-- Domain scoping validates that the active tab's hostname matches the secret's allowed domains before any value is read from disk.
-- Injection bypasses standard paste or readback mechanisms and writes directly via atomic CDP events.
-
-### 2. Universal Element Selector Resolution
-`browser_type_secret` supports:
-- Direct CSS Selectors (e.g. `id: "#password"`, `id: "input[type='password']"`, `id: ".pwd-field"`)
-- Element ActionMap IDs (e.g. `id: "w:5"` or `id: "5"`)
-- Focused Active Element (`target: "focused"`)
-
-### 3. DOM Property & Coercion Hardening
-Upon injection or typing into any sensitive input:
-- `data-wt-secret="true"` is attached to the DOM node.
-- The element's `.value` getter is overridden at the instance level to return `"[REDACTED]"`.
-- `Symbol.iterator`, `Symbol.toPrimitive`, and `toJSON` are overridden to prevent leakages via array spreads, template literals, or JSON serialization.
-
-### 4. Cross-Tool Containment Matrix
-
-| Tool | Protection Mechanism |
-|---|---|
-| `browser_type_secret` | In-process secret resolution, domain check, atomic CDP typing. |
-| `browser_type` | Broad secret detection (`type`, `name`, `id`, `autocomplete`, `aria-label`); disables value readbacks and redactions in action logging. |
-| `browser_fill` | Auto-registers secret fields in both single and `blast_mode`; masks values as `[REDACTED]` in return results and scan discovery mode (`scan: true`). |
-| `browser_map` | DOM and Accessibility (AX) tree walkers redact values, placeholders, and labels for all sensitive fields. |
-| `browser_scrape` | Evaluates in-page attribute extraction with automatic `[REDACTED]` substitution; filters live properties. |
-| `browser_screenshot` | Applies dynamic security masking (`webkitTextSecurity: disc` / blanking) during capture and restores safely in `finally`. |
-| `browser_snapshot` | Pre-masks all secret fields before MHTML export. |
-| `browser_pdf` | Masks sensitive inputs during PDF generation. |
-
-## CLI Usage
-
-```powershell
-# Store an encrypted secret with domain scoping
-weavetab secrets set GITHUB_TOKEN
-
-# List stored keys (never prints values)
-weavetab secrets list
-
-# Remove a stored key
-weavetab secrets rm GITHUB_TOKEN
-```
-
-## Agent Tool Invocation
-
-```json
-{
-  "id": "#password",
-  "envKey": "GITHUB_TOKEN"
-}
-```
+---
+title: "Blind Injection"
+description: "Enterprise-grade credential injection that never exposes secrets to the LLM."
+product: mcp
+section: architecture
+icon: Lock
+slug: blind-injection
+---
+
+# Blind Injection & Secret Containment
+
+The `browser_type_secret` tool and automated secret detection engine resolve passwords, tokens, API keys, PINs, and credentials directly from encrypted storage on the local host — **ensuring sensitive values never cross into the AI agent's context stream or tool outputs**.
+
+## Core Architecture
+
+```
+[Encrypted secrets.json]
+         │
+         ▼ (In-process resolution & domain validation)
+[Weavetab Server]
+         │
+         ▼ (Atomic CDP Input.insertText / ghostType)
+[Chromium Target Field]
+         │
+         ├─► DOM Property Hardening (getter override, symbol coercion, toJSON)
+         ├─► In-Memory SessionSecretTracker (backendNodeId & text redaction)
+         └─► Dynamic Visual Masking (screenshot, snapshot, PDF blanking)
+```
+
+## Multi-Layer Containment Mechanisms
+
+### 1. Zero-Exposure Injection
+- Secrets are stored encrypted with AES-256-GCM via `weavetab secrets set <KEY>`.
+- The agent passes the key name (`envKey: "MY_KEY"`), never the plaintext value.
+- Domain scoping validates that the active tab's hostname matches the secret's allowed domains before any value is read from disk.
+- Injection bypasses standard paste or readback mechanisms and writes directly via atomic CDP events.
+
+### 2. Universal Element Selector Resolution
+`browser_type_secret` supports:
+- Direct CSS Selectors (e.g. `id: "#password"`, `id: "input[type='password']"`, `id: ".pwd-field"`)
+- Element ActionMap IDs (e.g. `id: "w:5"` or `id: "5"`)
+- Focused Active Element (`target: "focused"`)
+
+### 3. DOM Property & Coercion Hardening
+Upon injection or typing into any sensitive input:
+- `data-wt-secret="true"` is attached to the DOM node.
+- The element's `.value` getter is overridden at the instance level to return `"[REDACTED]"`.
+- `Symbol.iterator`, `Symbol.toPrimitive`, and `toJSON` are overridden to prevent leakages via array spreads, template literals, or JSON serialization.
+
+### 4. Cross-Tool Containment Matrix
+
+| Tool | Protection Mechanism |
+|---|---|
+| `browser_type_secret` | In-process secret resolution, domain check, atomic CDP typing. |
+| `browser_type` | Broad secret detection (`type`, `name`, `id`, `autocomplete`, `aria-label`); disables value readbacks and redactions in action logging. |
+| `browser_fill` | Auto-registers secret fields in both single and `blast_mode`; masks values as `[REDACTED]` in return results and scan discovery mode (`scan: true`). |
+| `browser_map` | DOM and Accessibility (AX) tree walkers redact values, placeholders, and labels for all sensitive fields. |
+| `browser_scrape` | Evaluates in-page attribute extraction with automatic `[REDACTED]` substitution; filters live properties. |
+| `browser_screenshot` | Applies dynamic security masking (`webkitTextSecurity: disc` / blanking) during capture and restores safely in `finally`. |
+| `browser_snapshot` | Pre-masks all secret fields before MHTML export. |
+| `browser_pdf` | Masks sensitive inputs during PDF generation. |
+
+## CLI Usage
+
+```powershell
+# Store an encrypted secret with domain scoping
+weavetab secrets set GITHUB_TOKEN
+
+# List stored keys (never prints values)
+weavetab secrets list
+
+# Remove a stored key
+weavetab secrets rm GITHUB_TOKEN
+```
+
+## Agent Tool Invocation
+
+```json
+{
+  "id": "#password",
+  "envKey": "GITHUB_TOKEN"
+}
+```

package/docs/architecture/overview.md

@@ -1,49 +1,49 @@
----
-title: "Overview"
-description: "Five layers, deterministic pipeline, zero cloud."
-product: mcp
-section: architecture
-icon: Layers
-slug: overview
----
-
-# Architecture Overview
-
-Weavetab is decomposed into **five functional layers**, all running in-process without external daemon dependencies.
-
-## Layer Map
-
-| # | Layer | Responsibility |
-|---|---|---|
-| 1 | **Transport** | JSON-RPC 2.0 over stdio (default) or WebSocket (`--ws --port 3000`) |
-| 2 | **Security & Governance** | Domain blacklist, rate limiter (mutex), RBAC roles, policy engine, root guard |
-| 3 | **Intelligence Engine** | Session memory, semantic delta diffing, DOM pruner, loop detection, intent intercept |
-| 4 | **Sensor Systems** | Network telemetry, DOM mutation observer, human pacing, agent state machine |
-| 5 | **CDP Bridge** | DOM walker, Ghost Cursor (Bézier trajectories), keystroke engine, shadow-DOM injector |
-
-## Tool Execution Pipeline
-
-```text
-Agent → withSecurity()
-        ├── Rate limiter (mutex)
-        ├── Domain policy check (allow/deny/audit/read-only)
-        ├── RBAC role verification
-        ├── User-stop polling
-        ├── Chat queue draining
-        ├── Agent state transition (idle → weaving → reading)
-        └── Tool handler → CDP Bridge → Browser / Desktop App
-```
-
-Any validation or security failure short-circuits the pipeline immediately and returns a structured `WeaveError` — no partial side-effects are left on the browser.
-
-## Why Direct CDP
-
-| Feature | Weavetab | Playwright | Puppeteer | Selenium |
-|---|---|---|---|---|
-| **Architecture** | Direct CDP Layer 0 | Node bridge abstraction | CDP wrapper | WebDriver |
-| **Mean latency** | **3–8 ms** | 15–40 ms | 10–25 ms | 50–150 ms |
-| **Token efficiency** | **Semantic Deltas (97% reduction)** | Full DOM dumps | Full DOM dumps | Full DOM dumps |
-| **Desktop Electron Apps** | **Native (any Electron app)** | Experimental | Limited | Third-party driver |
-| **CAPTCHA Solver** | **Autonomous Zero-API** | None | None | None |
-| **MCP native** | **Yes (44 tools)** | No | No | No |
-| **Cloud dependency** | **Zero** | Optional | Optional | Grid required |
+---
+title: "Overview"
+description: "Five layers, deterministic pipeline, zero cloud."
+product: mcp
+section: architecture
+icon: Layers
+slug: overview
+---
+
+# Architecture Overview
+
+Weavetab is decomposed into **five functional layers**, all running in-process without external daemon dependencies.
+
+## Layer Map
+
+| # | Layer | Responsibility |
+|---|---|---|
+| 1 | **Transport** | JSON-RPC 2.0 over stdio (default) or WebSocket (`--ws --port 3000`) |
+| 2 | **Security & Governance** | Domain blacklist, rate limiter (mutex), RBAC roles, policy engine, root guard |
+| 3 | **Intelligence Engine** | Session memory, semantic delta diffing, DOM pruner, loop detection, intent intercept |
+| 4 | **Sensor Systems** | Network telemetry, DOM mutation observer, human pacing, agent state machine |
+| 5 | **CDP Bridge** | DOM walker, Ghost Cursor (Bézier trajectories), keystroke engine, shadow-DOM injector |
+
+## Tool Execution Pipeline
+
+```text
+Agent → withSecurity()
+        ├── Rate limiter (mutex)
+        ├── Domain policy check (allow/deny/audit/read-only)
+        ├── RBAC role verification
+        ├── User-stop polling
+        ├── Chat queue draining
+        ├── Agent state transition (idle → weaving → reading)
+        └── Tool handler → CDP Bridge → Browser / Desktop App
+```
+
+Any validation or security failure short-circuits the pipeline immediately and returns a structured `WeaveError` — no partial side-effects are left on the browser.
+
+## Why Direct CDP
+
+| Feature | Weavetab | Playwright | Puppeteer | Selenium |
+|---|---|---|---|---|
+| **Architecture** | Direct CDP Layer 0 | Node bridge abstraction | CDP wrapper | WebDriver |
+| **Mean latency** | **3–8 ms** | 15–40 ms | 10–25 ms | 50–150 ms |
+| **Token efficiency** | **Semantic Deltas (97% reduction)** | Full DOM dumps | Full DOM dumps | Full DOM dumps |
+| **Desktop Electron Apps** | **Native (any Electron app)** | Experimental | Limited | Third-party driver |
+| **CAPTCHA Solver** | **Autonomous Zero-API** | None | None | None |
+| **MCP native** | **Yes (41 Tools)** | No | No | No |
+| **Cloud dependency** | **Zero** | Optional | Optional | Grid required |

package/docs/architecture/security.md

@@ -1,36 +1,36 @@
----
-title: "Security Model"
-description: "Layered defenses that gate every tool invocation."
-product: mcp
-section: architecture
-icon: ShieldCheck
-slug: security
----
-
-# Security Model
-
-Weavetab executes direct Layer 0 CDP commands — security is layered and **deny-by-default for risky surfaces**.
-
-## Defense-in-Depth Mechanisms
-
-| Mechanism | Description |
-|---|---|
-| **Domain Blacklist** | Hard-blocked high-risk domains (banking, IAM consoles, internal infrastructure). |
-| **Domain Policy Engine** | Per-domain enforcement modes: `allow`, `read-only`, `deny`, `audit`. |
-| **Localhost Binding** | WebSocket server and CDP endpoints strictly bound to `127.0.0.1`. |
-| **Rate Limiting** | Mutex-enforced actions-per-minute rate limiter. |
-| **RBAC Roles** | 5 roles gating tool access (`admin`, `operator`, `viewer`, `automation`, `system`). |
-| **Root Guard** | Prevents execution as root/superuser on Unix systems. |
-| **Blind Injection** | Credential injection from `secrets.json` without exposing raw text to LLM context. |
-| **Shadow DOM Isolation** | All injected HUD and modal overlays run in isolated Shadow DOM trees. |
-| **Path Traversal Guard** | File upload and download paths strictly validated against path traversal. |
-
-## RBAC Role Matrix
-
-| Tool Category | admin | operator | viewer | automation | system |
-|---|:---:|:---:|:---:|:---:|:---:|
-| Mutation tools (`click`, `type`, `fill`, etc.) | yes | yes | no | yes | no |
-| Read-only tools (`map`, `find`, `scrape`, `screenshot`) | yes | yes | yes | yes | no |
-| High-level orchestration (`burst`, `automation`, `wait`) | yes | yes | no | yes | no |
-| Interactive HUD (`thoughts`) | yes | yes | no | no | yes |
-| System introspection (`detect`, `performance`, `checkpoint`) | yes | yes | no | yes | yes |
+---
+title: "Security Model"
+description: "Layered defenses that gate every tool invocation."
+product: mcp
+section: architecture
+icon: ShieldCheck
+slug: security
+---
+
+# Security Model
+
+Weavetab executes direct Layer 0 CDP commands — security is layered and **deny-by-default for risky surfaces**.
+
+## Defense-in-Depth Mechanisms
+
+| Mechanism | Description |
+|---|---|
+| **Domain Blacklist** | Hard-blocked high-risk domains (banking, IAM consoles, internal infrastructure). |
+| **Domain Policy Engine** | Per-domain enforcement modes: `allow`, `read-only`, `deny`, `audit`. |
+| **Localhost Binding** | WebSocket server and CDP endpoints strictly bound to `127.0.0.1`. |
+| **Rate Limiting** | Mutex-enforced actions-per-minute rate limiter. |
+| **RBAC Roles** | 5 roles gating tool access (`admin`, `operator`, `viewer`, `automation`, `system`). |
+| **Root Guard** | Prevents execution as root/superuser on Unix systems. |
+| **Blind Injection** | Credential injection from `secrets.json` without exposing raw text to LLM context. |
+| **Shadow DOM Isolation** | All injected HUD and modal overlays run in isolated Shadow DOM trees. |
+| **Path Traversal Guard** | File upload and download paths strictly validated against path traversal. |
+
+## RBAC Role Matrix
+
+| Tool Category | admin | operator | viewer | automation | system |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Mutation tools (`click`, `type`, `fill`, etc.) | yes | yes | no | yes | no |
+| Read-only tools (`map`, `find`, `scrape`, `screenshot`) | yes | yes | yes | yes | no |
+| High-level orchestration (`burst`, `automation`, `wait`) | yes | yes | no | yes | no |
+| Interactive HUD (`thoughts`) | yes | yes | no | no | yes |
+| System introspection (`detect`, `performance`, `checkpoint`) | yes | yes | no | yes | yes |