cbrowser 18.63.0 → 18.63.1

package/docs/DEMO-DEPLOYMENT.md

@@ -1,177 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[CBrowser MCP Demo Server Deployment](https://cbrowser.ai/docs/DEMO-DEPLOYMENT)**
-
----
-
-# CBrowser MCP Demo Server Deployment
-
-Deploy a rate-limited, resource-constrained MCP demo server.
-
-## Resource Limits
-
-The demo container is limited to protect your host:
-
-| Resource | Limit | Why |
-|----------|-------|-----|
-| CPU | 1 core | Prevents CPU exhaustion |
-| Memory | 2GB | Playwright needs ~1GB, buffer for operations |
-| PIDs | 100 | Prevents fork bombs |
-| Tmp storage | 500MB | Limits disk usage |
-| Logs | 3 x 10MB | Prevents log explosion |
-
-## Rate Limits (Built-in)
-
-The demo server has application-level rate limiting:
-- **5 requests per minute** per IP
-- **Burst of 10** requests allowed
-- Returns 429 Too Many Requests when exceeded
-
-## Quick Start
-
-```bash
-# Clone the repo
-git clone https://github.com/alexandriashai/cbrowser.git
-cd cbrowser
-
-# Build and run demo container
-docker-compose -f docker-compose.demo.yml up -d
-
-# Check status
-docker ps
-docker logs cbrowser-mcp-demo
-
-# Monitor resources
-docker stats cbrowser-mcp-demo
-```
-
-## Verify It's Running
-
-```bash
-# Health check
-curl http://localhost:3000/health
-
-# Server info
-curl http://localhost:3000/info
-```
-
-## Production Deployment (with nginx)
-
-### 1. Run the container
-
-```bash
-docker-compose -f docker-compose.demo.yml up -d
-```
-
-### 2. Configure nginx reverse proxy
-
-```nginx
-server {
-    listen 443 ssl http2;
-    server_name cbrowser-mcp-demo.yourdomain.com;
-
-    ssl_certificate /path/to/cert.pem;
-    ssl_certificate_key /path/to/key.pem;
-
-    # Rate limiting at nginx level (additional protection)
-    limit_req_zone $binary_remote_addr zone=mcp_demo:10m rate=10r/m;
-
-    location / {
-        limit_req zone=mcp_demo burst=5 nodelay;
-
-        proxy_pass http://127.0.0.1:3000;
-        proxy_http_version 1.1;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-
-        # SSE support for MCP
-        proxy_set_header Connection '';
-        proxy_buffering off;
-        proxy_cache off;
-        proxy_read_timeout 86400;
-    }
-}
-```
-
-### 3. Reload nginx
-
-```bash
-sudo nginx -t && sudo systemctl reload nginx
-```
-
-## Monitoring
-
-### Check container health
-
-```bash
-# Status
-docker inspect --format='{{.State.Health.Status}}' cbrowser-mcp-demo
-
-# Logs (last 100 lines)
-docker logs --tail 100 cbrowser-mcp-demo
-
-# Resource usage
-docker stats cbrowser-mcp-demo --no-stream
-```
-
-### Set up alerts (optional)
-
-```bash
-# Simple health check cron (add to crontab)
-*/5 * * * * curl -sf http://localhost:3000/health || echo "MCP Demo Down" | mail -s "Alert" you@email.com
-```
-
-## Troubleshooting
-
-### Container keeps restarting
-
-```bash
-# Check logs
-docker logs cbrowser-mcp-demo
-
-# Common issues:
-# - Port 3000 already in use
-# - Not enough memory (needs 2GB)
-# - Playwright browser install failed
-```
-
-### Out of memory
-
-If you see OOM kills, the 2GB limit may not be enough for your workload. Edit `docker-compose.demo.yml`:
-
-```yaml
-mem_limit: 3g  # Increase to 3GB
-```
-
-### Rate limit too strict
-
-The built-in rate limit is 5 req/min. For a private demo, you can disable it:
-
-```bash
-# In docker-compose.demo.yml, add:
-environment:
-  - MCP_DISABLE_RATE_LIMIT=true  # Only for private demos!
-```
-
-## Updating
-
-```bash
-# Pull latest
-docker-compose -f docker-compose.demo.yml pull
-
-# Recreate container
-docker-compose -f docker-compose.demo.yml up -d --force-recreate
-
-# Clean old images
-docker image prune -f
-```
-
-## Security Considerations
-
-1. **Don't expose without HTTPS** — Use nginx/Caddy with TLS
-2. **Keep rate limits on** — The demo is public
-3. **Monitor resource usage** — Set up alerts for high CPU/memory
-4. **Update regularly** — Keep the container image updated
-5. **Consider IP allowlisting** — If demo is for specific users only

package/docs/ENTERPRISE-INTEGRATION.md

@@ -1,250 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[CBrowser Enterprise Integration Guide](https://cbrowser.ai/docs/ENTERPRISE-INTEGRATION)**
-
----
-
-# CBrowser Enterprise Integration Guide
-
-This document explains how to integrate the private `cbrowser-enterprise` package with the public `cbrowser` package.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  cbrowser (public npm)                                      │
-│  ├── IConstitutionalEnforcer (interface)                    │
-│  ├── BaseConstitutionalEnforcer (abstract base class)       │
-│  ├── NoOpConstitutionalEnforcer (fallback)                  │
-│  └── getEnforcer() → dynamic loader                         │
-└─────────────────────────────────────────────────────────────┘
-                           │
-                           │ dynamic import (optional)
-                           ▼
-┌─────────────────────────────────────────────────────────────┐
-│  cbrowser-enterprise (private npm/GitHub Packages)          │
-│  ├── EnterpriseConstitutionalEnforcer                       │
-│  │   ├── applyStealthMeasures() — real implementation       │
-│  │   ├── persistAuditEntry() — database logging             │
-│  │   └── Full fingerprint evasion suite                     │
-│  └── exports { EnterpriseConstitutionalEnforcer, version }  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Enterprise Package Structure
-
-Create a private repository `cbrowser-enterprise`:
-
-```
-cbrowser-enterprise/
-├── package.json
-├── tsconfig.json
-├── src/
-│   ├── index.ts                    # Main exports
-│   ├── enforcer.ts                 # EnterpriseConstitutionalEnforcer
-│   ├── stealth/
-│   │   ├── fingerprint.ts          # Browser fingerprint normalization
-│   │   ├── webdriver.ts            # WebDriver flag patching
-│   │   ├── timing.ts               # Human-like timing injection
-│   │   └── canvas.ts               # Canvas/WebGL normalization
-│   └── audit/
-│       └── persistence.ts          # Audit log database
-└── dist/                           # Compiled output
-```
-
-### package.json (Enterprise)
-
-```json
-{
-  "name": "cbrowser-enterprise",
-  "version": "1.0.0",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "private": true,
-  "peerDependencies": {
-    "cbrowser": ">=15.0.0"
-  },
-  "publishConfig": {
-    "registry": "https://npm.pkg.github.com"
-  }
-}
-```
-
-### src/index.ts (Enterprise)
-
-```typescript
-export { EnterpriseConstitutionalEnforcer } from "./enforcer.js";
-export const version = "1.0.0";
-```
-
-### src/enforcer.ts (Enterprise Template)
-
-```typescript
-import {
-  BaseConstitutionalEnforcer,
-  type StealthConfig,
-  type StealthAuditEntry,
-} from "cbrowser";
-import type { Page } from "playwright";
-
-export class EnterpriseConstitutionalEnforcer extends BaseConstitutionalEnforcer {
-  constructor(config?: Partial<StealthConfig>) {
-    super(config);
-  }
-
-  /**
-   * Persist audit entries to database
-   */
-  protected async persistAuditEntry(entry: StealthAuditEntry): Promise<void> {
-    // TODO: Implement database persistence
-    // - SQLite for local
-    // - PostgreSQL for production
-    console.log("[Enterprise] Audit:", JSON.stringify(entry));
-  }
-
-  /**
-   * Apply stealth measures to page
-   */
-  async applyStealthMeasures(page: Page): Promise<void> {
-    // 1. Patch navigator.webdriver
-    await page.addInitScript(() => {
-      Object.defineProperty(navigator, "webdriver", {
-        get: () => undefined,
-      });
-    });
-
-    // 2. Inject realistic plugins
-    await page.addInitScript(() => {
-      Object.defineProperty(navigator, "plugins", {
-        get: () => [
-          { name: "Chrome PDF Plugin" },
-          { name: "Chrome PDF Viewer" },
-          { name: "Native Client" },
-        ],
-      });
-    });
-
-    // 3. Patch chrome object
-    await page.addInitScript(() => {
-      (window as any).chrome = {
-        runtime: {},
-        loadTimes: () => {},
-        csi: () => {},
-      };
-    });
-
-    // 4. Normalize WebGL fingerprint
-    await this.normalizeWebGL(page);
-
-    // 5. Add human-like mouse movement patterns
-    // (Injected via persona's humanBehavior traits)
-  }
-
-  private async normalizeWebGL(page: Page): Promise<void> {
-    await page.addInitScript(() => {
-      const getParameterProxy = new Proxy(
-        WebGLRenderingContext.prototype.getParameter,
-        {
-          apply(target, thisArg, args) {
-            const param = args[0];
-            // Normalize common fingerprint vectors
-            if (param === 37445) return "Intel Inc."; // UNMASKED_VENDOR
-            if (param === 37446) return "Intel Iris OpenGL Engine"; // UNMASKED_RENDERER
-            return Reflect.apply(target, thisArg, args);
-          },
-        }
-      );
-      WebGLRenderingContext.prototype.getParameter = getParameterProxy;
-    });
-  }
-}
-```
-
-## Publishing Enterprise Package
-
-### Option 1: GitHub Packages (Recommended)
-
-```bash
-# In cbrowser-enterprise repo
-npm login --registry=https://npm.pkg.github.com --scope=@yourorg
-npm publish
-```
-
-### Option 2: Private npm Registry
-
-```bash
-# Using Verdaccio or npm Enterprise
-npm publish --registry https://your-private-registry.com
-```
-
-### Option 3: Git Dependency
-
-```json
-{
-  "dependencies": {
-    "cbrowser-enterprise": "git+ssh://git@github.com:yourorg/cbrowser-enterprise.git"
-  }
-}
-```
-
-## Installing Enterprise for MCP Server
-
-On your MCP server host:
-
-```bash
-# Install public package
-npm install cbrowser
-
-# Install enterprise (with auth)
-npm install cbrowser-enterprise --registry https://npm.pkg.github.com
-
-# Or with .npmrc
-echo "@yourorg:registry=https://npm.pkg.github.com" >> .npmrc
-echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc
-npm install @yourorg/cbrowser-enterprise
-```
-
-## Usage in MCP Server
-
-The MCP server automatically detects enterprise:
-
-```typescript
-import { getEnforcer, printEnterpriseStatus } from "cbrowser";
-
-// On startup
-await printEnterpriseStatus();
-
-// When creating browser with stealth
-const enforcer = await getEnforcer({
-  enabled: true,
-  authorization: {
-    authorizedDomains: ["*.yourdomain.com"],
-  },
-});
-
-// Use enforcer with browser
-const browser = new CBrowser({ enforcer });
-```
-
-## Verification
-
-```bash
-# Check if enterprise is detected
-npx cbrowser status
-
-# Output with enterprise:
-# ╔══════════════════════════════════════════════════════════╗
-# ║  CBrowser Enterprise: ACTIVE                             ║
-# ║  Version: 1.0.0                                          ║
-# ║  Stealth capabilities: ENABLED                           ║
-# ╚══════════════════════════════════════════════════════════╝
-```
-
-## Security Notes
-
-1. **Never commit enterprise to public repo** - It's a separate private package
-2. **Use GitHub Packages or private npm** - Not public npm registry
-3. **Rotate access tokens** - Use short-lived tokens for CI/CD
-4. **Audit logs are immutable** - Cannot be disabled or cleared
-5. **Rate limits enforced** - Minimum limits cannot be lowered

package/docs/GETTING-STARTED.md

@@ -1,232 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[Getting Started with CBrowser](https://cbrowser.ai/docs/GETTING-STARTED)**
-
----
-
-# Getting Started with CBrowser
-
-CBrowser (Cognitive Browser) is the browser automation that thinks like your users. This guide will get you up and running quickly.
-
-## Installation
-
-```bash
-npm install cbrowser
-npx playwright install chromium
-```
-
-## Your First Commands
-
-### Navigate to a Page
-
-```bash
-npx cbrowser navigate "https://example.com"
-```
-
-### Click with Self-Healing Selectors
-
-```bash
-npx cbrowser smart-click "Add to Cart"
-```
-
-CBrowser uses AI to find elements by description, not brittle CSS selectors. If the DOM changes, the self-healing system adapts automatically.
-
-### Natural Language Assertions
-
-```bash
-npx cbrowser assert "page contains 'Order Confirmed'"
-```
-
-### Take a Screenshot
-
-```bash
-npx cbrowser screenshot --path order-confirmation.png
-```
-
-## Cognitive User Simulation
-
-This is what makes CBrowser unique. Instead of just clicking buttons, it simulates how real users think:
-
-```bash
-npx cbrowser cognitive-journey \
-  --persona first-timer \
-  --start "https://example.com" \
-  --goal "complete checkout"
-```
-
-The simulation tracks:
-- **Patience** - Will they wait for slow pages?
-- **Confusion** - Are they getting lost?
-- **Frustration** - Are errors piling up?
-- **Abandonment** - When will they give up?
-
-### Output Example
-
-```
-=== Cognitive Journey: first-timer ===
-Goal: complete checkout
-Start: https://example.com
-
-Step 1: Looking for product catalog
-  Action: click "Shop Now"
-  Patience: 95% | Confusion: 5%
-
-Step 2: Found products, browsing
-  Action: click first product
-  Patience: 90% | Confusion: 10%
-
-...
-
-Step 8: ABANDONED
-  Reason: Patience depleted (8%)
-  Thought: "This password form is too confusing..."
-  Friction points:
-    - Password requirements unclear (step 6)
-    - Form validation error not visible (step 7)
-```
-
-## Built-in Personas
-
-| Persona | Description |
-|---------|-------------|
-| `power-user` | Tech-savvy, expects efficiency |
-| `first-timer` | New user, explores carefully |
-| `mobile-user` | Smartphone, touch interface |
-| `elderly-user` | Patient, careful, vision/motor considerations |
-| `impatient-user` | Quick to abandon on friction |
-| `screen-reader-user` | Uses assistive technology |
-
-## Create Custom Personas
-
-Use the questionnaire system to create research-backed custom personas:
-
-```bash
-# Interactive questionnaire
-npx cbrowser persona-questionnaire start --name "anxious-newbie"
-
-# The system asks behavioral questions and derives trait values
-# with proper research-backed correlations
-```
-
-## Natural Language Tests
-
-Write tests in plain English:
-
-```txt
-# checkout-test.txt
-go to https://example.com/products
-click "Add to Cart" button
-verify page contains "1 item in cart"
-click checkout
-fill email with "test@example.com"
-click "Place Order"
-verify url contains "/confirmation"
-```
-
-Run them:
-
-```bash
-npx cbrowser test-suite checkout-test.txt --html
-```
-
-## Visual Testing
-
-### Capture Baseline
-
-```bash
-npx cbrowser ai-visual capture "https://example.com" --name homepage
-```
-
-### Test Against Baseline
-
-```bash
-npx cbrowser ai-visual test "https://staging.example.com" homepage --html
-```
-
-### Cross-Browser Comparison
-
-```bash
-npx cbrowser cross-browser "https://example.com" --html
-```
-
-### Responsive Testing
-
-```bash
-npx cbrowser responsive "https://example.com" --html
-```
-
-## Constitutional AI Safety
-
-CBrowser classifies every action by risk level:
-
-| Zone | Examples | Behavior |
-|------|----------|----------|
-| Green | Navigate, read, screenshot | Auto-execute |
-| Yellow | Click buttons, fill forms | Log and proceed |
-| Red | Submit, delete, purchase | Requires verification |
-| Black | Bypass auth, inject scripts | Never executes |
-
-This prevents AI agents from accidentally submitting forms, deleting data, or making purchases.
-
-## API Key for Cognitive Features
-
-Some features require an Anthropic API key:
-
-```bash
-npx cbrowser config set-api-key
-```
-
-## MCP Integration
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "cbrowser": {
-      "command": "npx",
-      "args": ["cbrowser", "mcp-server"]
-    }
-  }
-}
-```
-
-### claude.ai (Remote)
-
-Use the public demo server:
-```
-https://demo.cbrowser.ai/mcp
-```
-
-Or deploy your own: see [MCP Integration](./MCP-INTEGRATION.md).
-
-## Next Steps
-
-- [Cognitive Simulation](./COGNITIVE-SIMULATION.md) - Deep dive into user simulation
-- [Persona Questionnaire](./PERSONA-QUESTIONNAIRE.md) - Create custom personas
-- [Natural Language Tests](./NATURAL-LANGUAGE-TESTS.md) - Write tests in English
-- [Visual Testing](./VISUAL-TESTING.md) - Screenshot-based regression testing
-- [MCP Integration](./MCP-INTEGRATION.md) - Full Claude integration guide
-
-## Quick Reference
-
-| Command | Description |
-|---------|-------------|
-| `npx cbrowser navigate <url>` | Navigate to URL |
-| `npx cbrowser click <selector>` | Click element |
-| `npx cbrowser smart-click <text>` | AI-powered click |
-| `npx cbrowser fill <selector> <value>` | Fill input |
-| `npx cbrowser screenshot` | Capture screenshot |
-| `npx cbrowser assert <assertion>` | Verify condition |
-| `npx cbrowser cognitive-journey` | Run user simulation |
-| `npx cbrowser test-suite <file>` | Run NL tests |
-| `npx cbrowser ai-visual capture` | Capture baseline |
-| `npx cbrowser ai-visual test` | Run visual test |
-| `npx cbrowser cross-browser` | Cross-browser test |
-| `npx cbrowser responsive` | Responsive test |
-| `npx cbrowser agent-ready-audit` | Audit for AI agents |
-| `npx cbrowser empathy-audit` | Disability simulation |
-| `npx cbrowser persona-questionnaire` | Create custom persona |
-| `npx cbrowser status` | Check environment |