cbrowser 7.4.4 → 7.4.7

package/docs/AUTH0-SETUP.md

@@ -0,0 +1,201 @@
+# Auth0 OAuth Setup for CBrowser MCP Server
+
+This guide walks you through setting up Auth0 authentication for the CBrowser Remote MCP Server, enabling integration with claude.ai's custom connector feature.
+
+## Quick Start
+
+### 1. Create Auth0 Account
+
+1. Go to [auth0.com](https://auth0.com) and sign up (free tier works)
+2. Create a new tenant (e.g., `cbrowser` or use your existing tenant)
+
+### 2. Create an API
+
+1. Go to **Applications → APIs**
+2. Click **+ Create API**
+3. Configure:
+   - **Name:** `CBrowser MCP API`
+   - **Identifier:** `https://cbrowser-mcp.wyldfyre.ai` (your server URL)
+   - **Signing Algorithm:** RS256
+4. Click **Create**
+
+### 3. Create an Application (Static Registration)
+
+For secure integration, we use static client registration:
+
+1. Go to **Applications → Applications**
+2. Click **+ Create Application**
+3. Configure:
+   - **Name:** `Claude.ai MCP Client`
+   - **Type:** Regular Web Application
+4. Click **Create**
+5. In Settings tab, configure:
+   - **Allowed Callback URLs:**
+     ```
+     https://claude.ai/api/mcp/auth_callback,
+     https://claude.com/api/mcp/auth_callback
+     ```
+   - **Allowed Web Origins:** `https://claude.ai, https://claude.com`
+6. Save Changes
+7. Note down:
+   - **Domain** (e.g., `your-tenant.auth0.com`)
+   - **Client ID**
+   - **Client Secret**
+
+### 4. Configure MCP Server
+
+Add these environment variables to your systemd service:
+
+```bash
+sudo nano /etc/systemd/system/cbrowser-mcp.service
+```
+
+Add under `[Service]`:
+
+```ini
+Environment=AUTH0_DOMAIN=your-tenant.auth0.com
+Environment=AUTH0_AUDIENCE=https://cbrowser-mcp.wyldfyre.ai
+Environment=AUTH0_CLIENT_ID=your-client-id
+```
+
+Reload and restart:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart cbrowser-mcp
+```
+
+### 5. Verify Setup
+
+```bash
+# Check protected resource metadata
+curl https://cbrowser-mcp.wyldfyre.ai/.well-known/oauth-protected-resource
+
+# Should return:
+{
+  "resource": "https://cbrowser-mcp.wyldfyre.ai",
+  "authorization_servers": ["https://your-tenant.auth0.com"],
+  "bearer_methods_supported": ["header"],
+  "scopes_supported": ["openid", "profile", "cbrowser:read", "cbrowser:write"]
+}
+```
+
+### 6. Connect from Claude.ai
+
+1. Go to [claude.ai](https://claude.ai)
+2. Open **Settings → Connectors**
+3. Click **Add custom connector**
+4. Enter: `https://cbrowser-mcp.wyldfyre.ai/mcp`
+5. Claude will:
+   - Fetch the OAuth metadata from `/.well-known/oauth-protected-resource`
+   - Redirect you to Auth0 for authentication
+   - Exchange tokens and connect
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐     ┌────────────────┐     ┌─────────────────┐
+│   Claude.ai     │────▶│    Auth0       │────▶│  CBrowser MCP   │
+│                 │     │                │     │     Server      │
+│  1. Discover    │     │  2. Authorize  │     │                 │
+│  OAuth metadata │     │  3. Get token  │     │  4. Validate    │
+│                 │     │                │     │     JWT         │
+└─────────────────┘     └────────────────┘     └─────────────────┘
+```
+
+## Flow Details
+
+1. **Discovery**: Claude fetches `/.well-known/oauth-protected-resource` to find Auth0
+2. **Authorization**: User is redirected to Auth0 login
+3. **Token Exchange**: Auth0 issues JWT access token
+4. **API Access**: Claude sends requests with `Authorization: Bearer <jwt>`
+5. **Validation**: CBrowser validates JWT against Auth0 JWKS
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AUTH0_DOMAIN` | Yes | Your Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
+| `AUTH0_AUDIENCE` | Yes | API identifier (your server URL) |
+| `AUTH0_CLIENT_ID` | No | Client ID for static registration info |
+
+---
+
+## Scopes
+
+The server supports these OAuth scopes:
+
+| Scope | Description |
+|-------|-------------|
+| `openid` | OpenID Connect authentication |
+| `profile` | User profile information |
+| `cbrowser:read` | Read-only access to CBrowser tools |
+| `cbrowser:write` | Full access to CBrowser tools |
+
+---
+
+## Troubleshooting
+
+### "Invalid token" errors
+
+1. Check Auth0 domain is correct
+2. Verify audience matches exactly (including trailing slash if needed)
+3. Check token hasn't expired
+
+### "OAuth not configured" response
+
+1. Ensure `AUTH0_DOMAIN` and `AUTH0_AUDIENCE` are set
+2. Restart the service after config changes
+
+### Claude.ai can't connect
+
+1. Verify callback URLs include both `claude.ai` and `claude.com`
+2. Check CORS is working (test with browser dev tools)
+3. Ensure `/.well-known/oauth-protected-resource` is accessible
+
+### Rate limit errors (429)
+
+Auth0 free tier has strict rate limits. CBrowser caches validated tokens for 30 minutes to avoid hitting these limits. If you're still seeing rate limits:
+
+1. Upgrade to Auth0 paid tier
+2. Reduce concurrent users
+
+### Opaque token instead of JWT
+
+If Auth0 returns an opaque (encrypted) token instead of a JWT, CBrowser validates it via Auth0's `/userinfo` endpoint. This works but:
+
+1. Ensure API Identifier in Auth0 exactly matches your audience (including trailing slash)
+2. Check the Application is authorized for the API in Auth0
+
+---
+
+## Security Best Practices
+
+1. **Use static registration** - Don't enable open DCR without IP restrictions
+2. **Restrict callback URLs** - Only allow Claude's official callbacks
+3. **Monitor logs** - Check Auth0 logs for unauthorized access attempts
+4. **Rotate secrets** - Periodically rotate client secrets
+5. **Use scopes** - Implement scope-based access control for sensitive tools
+
+---
+
+## Dual Authentication
+
+The server supports both API keys and OAuth simultaneously:
+
+- **API Key**: For Claude Code CLI and programmatic access
+- **OAuth**: For claude.ai web interface
+
+Both can be enabled at the same time. The server checks OAuth JWT first, then falls back to API key.
+
+---
+
+## Related Documentation
+
+- [Auth0 MCP Documentation](https://auth0.com/ai/docs/mcp/)
+- [MCP Authorization Spec](https://spec.modelcontextprotocol.io/specification/architecture/transports/)
+- [RFC 9728 - OAuth Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)

package/docs/REMOTE-MCP-SERVER.md

@@ -295,7 +295,7 @@ Create a page rule to bypass caching:
 
 ```bash
 curl https://cbrowser-mcp.yourdomain.com/health
-# {"status":"ok","version":"7.4.2"}
+# {"status":"ok","version":"7.4.6","auth":true,"auth_methods":{"api_key":true,"oauth":true}}
 ```
 
 ### Info Endpoint
@@ -317,14 +317,34 @@ curl -X POST https://cbrowser-mcp.yourdomain.com/mcp \
 
 ## Step 6: Connect to Claude.ai
 
-1. Go to [claude.ai](https://claude.ai)
-2. Open **Settings → Integrations → Custom MCP Servers**
-3. Add new connector:
-   - **Name:** CBrowser
-   - **URL:** `https://cbrowser-mcp.yourdomain.com/mcp`
-4. Click **Connect**
+### Option A: With Auth0 OAuth (Recommended)
 
-You should see 31 CBrowser tools become available in Claude.
+For secure authentication with claude.ai, set up Auth0 OAuth:
+
+1. See the [Auth0 Setup Guide](AUTH0-SETUP.md) to configure Auth0
+2. Add Auth0 environment variables to your systemd service:
+   ```ini
+   Environment=AUTH0_DOMAIN=your-tenant.auth0.com
+   Environment=AUTH0_AUDIENCE=https://cbrowser-mcp.yourdomain.com/
+   ```
+3. Restart the service: `sudo systemctl restart cbrowser-mcp`
+4. Go to [claude.ai](https://claude.ai) → **Settings → Connectors**
+5. Click **Add Custom Connector**
+6. Enter URL: `https://cbrowser-mcp.yourdomain.com/mcp`
+7. Enter your Auth0 **Client ID** and **Client Secret** when prompted
+8. Complete the OAuth login flow
+
+### Option B: Open Access (Public Demo)
+
+For a public demo server without authentication:
+
+1. Remove `MCP_API_KEY` from your systemd service
+2. Remove `AUTH0_*` variables
+3. Add rate limiting in nginx (see Security section)
+4. Go to [claude.ai](https://claude.ai) → **Settings → Connectors**
+5. Add URL: `https://cbrowser-mcp.yourdomain.com/mcp`
+
+You should see 31+ CBrowser tools become available in Claude.
 
 ---
 
@@ -340,11 +360,29 @@ sudo ufw allow 443/tcp   # HTTPS
 sudo ufw enable
 ```
 
-### Authentication (v7.4.3+)
+### Authentication (v7.4.6+)
+
+CBrowser Remote MCP Server supports two authentication methods:
+
+#### Method 1: Auth0 OAuth (for claude.ai)
+
+Claude.ai requires OAuth 2.1 authentication. Set up Auth0:
+
+```bash
+# Auth0 OAuth (enables claude.ai login)
+Environment=AUTH0_DOMAIN=your-tenant.auth0.com
+Environment=AUTH0_AUDIENCE=https://cbrowser-mcp.yourdomain.com/
+```
+
+See [Auth0 Setup Guide](AUTH0-SETUP.md) for full configuration.
 
-CBrowser Remote MCP Server supports API key authentication:
+**OAuth Endpoints:**
+- `/.well-known/oauth-protected-resource` - OAuth metadata discovery
+- `/mcp` - MCP endpoint (requires valid JWT)
 
-**Enable authentication:**
+#### Method 2: API Key (for Claude Code CLI)
+
+For programmatic access and Claude Code CLI:
 
 ```bash
 # Single API key
@@ -370,14 +408,24 @@ curl -H "Authorization: Bearer your-api-key" https://your-server/mcp
 curl -H "X-API-Key: your-api-key" https://your-server/mcp
 ```
 
-**Endpoints:**
-- `/health` and `/info` are always open (no auth required)
-- `/mcp` requires authentication when `MCP_API_KEY` or `MCP_API_KEYS` is set
+#### Dual Authentication
+
+Both methods can be enabled simultaneously:
+- **OAuth** - For claude.ai web interface
+- **API Key** - For Claude Code CLI and scripts
+
+**Public Endpoints (no auth required):**
+- `/health` - Server health status
+- `/info` - Server information
+- `/.well-known/oauth-protected-resource` - OAuth metadata
+
+**Protected Endpoints:**
+- `/mcp` - MCP endpoint (requires valid auth)
 
 **Additional security layers:**
-1. Use Cloudflare Access for additional authentication
-2. Restrict to IP whitelist in nginx
-3. Enable rate limiting (see below)
+1. Rate limiting in nginx
+2. Cloudflare WAF rules
+3. IP whitelisting
 
 ### Rate Limiting
 

package/examples/remote-mcp.ts

@@ -0,0 +1,137 @@
+/**
+ * CBrowser v7.4.6 Remote MCP Server Examples
+ *
+ * Demonstrates:
+ * - Starting a remote MCP server
+ * - Authentication options (API key, OAuth)
+ * - Connecting from claude.ai
+ *
+ * Run the server: npx cbrowser mcp-remote
+ * Or with authentication: MCP_API_KEY=your-key npx cbrowser mcp-remote
+ */
+
+import { createServer } from "http";
+
+/**
+ * Example: Start Remote MCP Server Programmatically
+ *
+ * Note: In most cases, use the CLI:
+ *   npx cbrowser mcp-remote
+ *
+ * This example shows programmatic configuration.
+ */
+async function startRemoteMCPServer() {
+  console.log("=== Remote MCP Server Configuration ===\n");
+
+  console.log("Environment Variables:\n");
+
+  console.log("Basic Configuration:");
+  console.log("  PORT=3100                     # Server port (default: 3000)");
+  console.log("  HOST=127.0.0.1                # Bind address");
+  console.log("  MCP_SESSION_MODE=stateless    # Session handling\n");
+
+  console.log("API Key Authentication:");
+  console.log("  MCP_API_KEY=your-secret-key   # Single API key");
+  console.log("  MCP_API_KEYS=key1,key2,key3   # Multiple API keys\n");
+
+  console.log("Auth0 OAuth (for claude.ai):");
+  console.log("  AUTH0_DOMAIN=your-tenant.auth0.com");
+  console.log("  AUTH0_AUDIENCE=https://your-server.com/\n");
+
+  console.log("Start command:");
+  console.log("  npx cbrowser mcp-remote\n");
+}
+
+/**
+ * Example: Client Configuration for claude.ai
+ */
+function claudeAISetup() {
+  console.log("=== claude.ai Custom Connector Setup ===\n");
+
+  console.log("Demo Server (rate-limited, no auth):");
+  console.log("  URL: https://cbrowser-mcp-demo.wyldfyre.ai/mcp");
+  console.log("  Rate limit: 5 requests/minute, burst of 10");
+  console.log("  Purpose: Evaluation only\n");
+
+  console.log("Authenticated Server (full access):");
+  console.log("  URL: https://cbrowser-mcp.wyldfyre.ai/mcp");
+  console.log("  Auth: Auth0 OAuth 2.1");
+  console.log("  Rate limit: None\n");
+
+  console.log("Setup Steps:");
+  console.log("  1. Go to claude.ai");
+  console.log("  2. Open Settings -> Integrations -> Custom MCP Servers");
+  console.log("  3. Add the server URL");
+  console.log("  4. Complete OAuth login when prompted (for authenticated server)");
+  console.log("  5. You now have 31 browser automation tools!\n");
+}
+
+/**
+ * Example: API Key Authentication
+ */
+function apiKeyAuth() {
+  console.log("=== API Key Authentication ===\n");
+
+  console.log("Set API key when starting server:");
+  console.log("  MCP_API_KEY=your-secret-key npx cbrowser mcp-remote\n");
+
+  console.log("Client usage (Bearer token - recommended):");
+  console.log('  curl -H "Authorization: Bearer your-api-key" https://server/mcp\n');
+
+  console.log("Client usage (X-API-Key header):");
+  console.log('  curl -H "X-API-Key: your-api-key" https://server/mcp\n');
+
+  console.log("Generate a secure key:");
+  console.log("  openssl rand -hex 32\n");
+}
+
+/**
+ * Example: OAuth Protected Resource Metadata
+ */
+function oauthMetadata() {
+  console.log("=== OAuth Protected Resource Metadata ===\n");
+
+  console.log("Endpoint: /.well-known/oauth-protected-resource\n");
+
+  console.log("Response example:");
+  const metadata = {
+    resource: "https://cbrowser-mcp.wyldfyre.ai",
+    authorization_servers: ["https://your-tenant.auth0.com"],
+    bearer_methods_supported: ["header"],
+    scopes_supported: ["openid", "profile", "cbrowser:read", "cbrowser:write"],
+  };
+  console.log(JSON.stringify(metadata, null, 2));
+  console.log();
+}
+
+/**
+ * Example: Health Check
+ */
+function healthCheck() {
+  console.log("=== Health Check Endpoint ===\n");
+
+  console.log("Endpoint: /health\n");
+
+  console.log("Response example:");
+  const health = {
+    status: "ok",
+    version: "7.4.6",
+    auth: true,
+    auth_methods: {
+      api_key: true,
+      oauth: true,
+    },
+  };
+  console.log(JSON.stringify(health, null, 2));
+  console.log();
+}
+
+async function main() {
+  await startRemoteMCPServer();
+  claudeAISetup();
+  apiKeyAuth();
+  oauthMetadata();
+  healthCheck();
+}
+
+main().catch(console.error);

package/examples/smart-automation.ts

@@ -1,16 +1,19 @@
 /**
- * CBrowser v5.0.0 Smart Automation Examples
+ * CBrowser v7.x Smart Automation Examples
  *
  * Demonstrates:
  * - Smart click with auto-retry
  * - Natural language assertions
  * - Self-healing selector cache
  * - AI test generation
+ * - Modular imports
  *
  * Run with: npx ts-node examples/smart-automation.ts
+ * Or: bun run examples/smart-automation.ts
  */
 
-import { CBrowser } from "../src/index.js";
+import { CBrowser } from "cbrowser";
+// For local development: import { CBrowser } from "../src/index.js";
 
 async function smartClickExample() {
   console.log("=== Smart Click with Auto-Retry ===\n");

package/examples/visual-testing.ts

@@ -0,0 +1,177 @@
+/**
+ * CBrowser v7.x Visual Testing Examples
+ *
+ * Demonstrates:
+ * - AI Visual Regression (v7.0)
+ * - Cross-Browser Testing (v7.1)
+ * - Responsive Testing (v7.2)
+ * - A/B Comparison (v7.3)
+ *
+ * Run with: npx ts-node examples/visual-testing.ts
+ * Or: bun run examples/visual-testing.ts
+ */
+
+import { CBrowser } from "cbrowser";
+// Modular imports for tree-shaking:
+// import { runVisualRegression, runCrossBrowserTest, runResponsiveTest, runABComparison } from "cbrowser/visual";
+
+async function visualRegressionExample() {
+  console.log("=== AI Visual Regression (v7.0) ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Capture a baseline
+    const baseline = await browser.captureVisualBaseline(
+      "https://example.com",
+      "homepage"
+    );
+    console.log(`Baseline captured: ${baseline.name}`);
+    console.log(`Screenshot: ${baseline.screenshotPath}`);
+    console.log(`Timestamp: ${baseline.timestamp}`);
+
+    // Later, compare against baseline
+    const result = await browser.runVisualRegression(
+      "https://example.com",
+      "homepage"
+    );
+
+    console.log(`\nComparison result:`);
+    console.log(`  Match: ${result.match}`);
+    console.log(`  Similarity: ${(result.similarity * 100).toFixed(1)}%`);
+    console.log(`  AI Analysis: ${result.aiAnalysis}`);
+
+    if (result.differences.length > 0) {
+      console.log(`\nDifferences found:`);
+      for (const diff of result.differences) {
+        console.log(`  - ${diff.type}: ${diff.description}`);
+        console.log(`    Severity: ${diff.severity}`);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function crossBrowserExample() {
+  console.log("\n=== Cross-Browser Testing (v7.1) ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Compare rendering across browsers
+    const result = await browser.runCrossBrowserTest("https://example.com", {
+      browsers: ["chromium", "firefox", "webkit"],
+    });
+
+    console.log(`URL tested: ${result.url}`);
+    console.log(`Browsers: ${result.browsers.join(", ")}`);
+    console.log(`Overall match: ${result.overallMatch}`);
+
+    console.log(`\nBrowser comparisons:`);
+    for (const comparison of result.comparisons) {
+      console.log(`  ${comparison.browserA} vs ${comparison.browserB}:`);
+      console.log(`    Similarity: ${(comparison.similarity * 100).toFixed(1)}%`);
+      console.log(`    Differences: ${comparison.differences.length}`);
+    }
+
+    if (result.criticalDifferences.length > 0) {
+      console.log(`\nCritical differences:`);
+      for (const diff of result.criticalDifferences) {
+        console.log(`  - ${diff.browser}: ${diff.description}`);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function responsiveExample() {
+  console.log("\n=== Responsive Testing (v7.2) ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Test across viewport sizes
+    const result = await browser.runResponsiveTest("https://example.com", {
+      viewports: ["mobile", "tablet", "desktop"],
+    });
+
+    console.log(`URL tested: ${result.url}`);
+    console.log(`Viewports tested: ${result.viewports.length}`);
+
+    console.log(`\nViewport results:`);
+    for (const viewport of result.viewports) {
+      console.log(`  ${viewport.name} (${viewport.width}x${viewport.height}):`);
+      console.log(`    Layout: ${viewport.layoutType}`);
+      console.log(`    Issues: ${viewport.issues.length}`);
+
+      if (viewport.issues.length > 0) {
+        for (const issue of viewport.issues) {
+          console.log(`      - ${issue.type}: ${issue.description}`);
+        }
+      }
+    }
+
+    // Breakpoint analysis
+    if (result.breakpointIssues.length > 0) {
+      console.log(`\nBreakpoint issues:`);
+      for (const issue of result.breakpointIssues) {
+        console.log(`  At ${issue.breakpoint}px: ${issue.description}`);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function abComparisonExample() {
+  console.log("\n=== A/B Comparison (v7.3) ===\n");
+
+  const browser = new CBrowser({ headless: true });
+
+  try {
+    // Compare two URLs (staging vs production, old vs new design)
+    const result = await browser.runABComparison(
+      "https://staging.example.com",
+      "https://example.com",
+      {
+        labelA: "Staging",
+        labelB: "Production",
+      }
+    );
+
+    console.log(`Comparison: ${result.labelA} vs ${result.labelB}`);
+    console.log(`Overall similarity: ${(result.similarity * 100).toFixed(1)}%`);
+    console.log(`Match: ${result.match}`);
+
+    console.log(`\nDifferences:`);
+    for (const diff of result.differences) {
+      console.log(`  - ${diff.category}: ${diff.description}`);
+      console.log(`    Severity: ${diff.severity}`);
+      console.log(`    Location: ${diff.location}`);
+    }
+
+    // AI summary
+    console.log(`\nAI Summary:`);
+    console.log(`  ${result.aiSummary}`);
+
+    if (result.recommendations.length > 0) {
+      console.log(`\nRecommendations:`);
+      for (const rec of result.recommendations) {
+        console.log(`  - ${rec}`);
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  await visualRegressionExample();
+  await crossBrowserExample();
+  await responsiveExample();
+  await abComparisonExample();
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbrowser",
-  "version": "7.4.4",
+  "version": "7.4.7",
   "description": "AI-powered browser automation with constitutional safety, AI visual regression, persona testing, and natural language test suites. Modular architecture for visual, testing, analysis, and performance modules.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -89,6 +89,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
+    "jose": "^5.2.0",
     "playwright": "^1.40.0",
     "zod": "^3.25.76"
   },