A Chrome Extension for TLSNotary with plugin SDK and verifier server.

• Monorepo Structure
• Architecture Overview
• Getting Started
• Development
• Production Build
• End-to-End Testing
• Running the Demo
• Websockify Integration
• Publishing
• License

This repository is organized as an npm workspaces monorepo with six main packages:

tlsn-extension/
├── packages/
│   ├── extension/           # Chrome Extension (Manifest V3)
│   │   ├── src/
│   │   │   ├── entries/
│   │   │   │   ├── Background/     # Service worker for extension logic
│   │   │   │   ├── Content/        # Content scripts injected into pages
│   │   │   │   ├── Popup/          # Extension popup UI (optional)
│   │   │   │   └── Offscreen/      # Offscreen document for DOM operations
│   │   │   ├── manifest.json
│   │   │   └── utils/
│   │   ├── webpack.config.js
│   │   └── package.json
│   │
│   ├── plugin-sdk/          # SDK for developing TLSN plugins
│   │   ├── src/
│   │   ├── examples/
│   │   └── package.json
│   │
│   ├── common/              # Shared utilities (logging system)
│   │   ├── src/
│   │   │   └── logger/           # Centralized logging with configurable levels
│   │   └── package.json
│   │
│   ├── verifier/            # Rust-based verifier server
│   │   ├── src/
│   │   │   └── main.rs           # Server setup, routing, and verification
│   │   ├── config.yaml           # Webhook configuration
│   │   └── Cargo.toml
│   │
│   ├── demo/                # Demo server with Docker setup
│   │   ├── *.js                  # Example plugin files
│   │   └── docker-compose.yml    # Docker services configuration
│   │
│   ├── tutorial/            # Tutorial examples
│   │   └── *.js                  # Tutorial plugin files
│   │
│   └── tlsn-wasm-pkg/       # Pre-built TLSN WebAssembly package
│       └── (WASM binaries)
│
├── package.json             # Root workspace configuration
└── README.md

A browser extension that enables TLSNotary functionality with the following key features:

• Multi-Window Management: Track multiple browser windows with request interception
• Request Interception: Capture HTTP/HTTPS requests from managed windows
• Plugin Execution: Run sandboxed JavaScript plugins using QuickJS
• TLSN Overlay: Visual display of intercepted requests

Key Entry Points:

• Background: Service worker for extension logic, window management, and message routing
• Content: Scripts injected into pages for communication and overlay display
• Popup: Optional extension popup UI
• Offscreen: Background DOM operations for service worker limitations

SDK for developing and running TLSN WebAssembly plugins with QuickJS sandboxing:

• Secure JavaScript execution in isolated WebAssembly environment
• Host capability system for controlled plugin access
• React-like hooks: useHeaders(), useRequests(), useEffect(), useState(), setState()
• Isomorphic package for Node.js and browser environments
• TypeScript support with full type declarations

Centralized logging system used across packages:

• Configurable log levels: DEBUG, INFO, WARN, ERROR
• Timestamped output with level prefixes
• Singleton pattern for consistent logging across modules

Rust-based HTTP/WebSocket server for TLSNotary verification:

• Health check endpoint (GET /health)
• Session creation endpoint (WS /session)
• WebSocket verification endpoint (WS /verifier?sessionId=<id>)
• WebSocket proxy endpoint (WS /proxy?token=<host>) - compatible with notary.pse.dev
• Webhook API for POST notifications to external services
• YAML configuration for webhook endpoints (config.yaml)
• CORS enabled for cross-origin requests
• Runs on localhost:7047 by default

Docker-based demo environment with:

• Pre-configured example plugins (Twitter, SwissBank)
• React + Vite frontend with environment-based configuration
• Docker Compose setup with verifier and nginx
• Configurable verifier URLs via .env files or Docker build args

Pre-built WebAssembly binaries for TLSNotary functionality in the browser.

The extension uses a message-passing architecture with five main entry points:

┌─────────────────────────────────────────────────────────────┐
│                     Browser Extension                         │
│                                                               │
│  ┌──────────────┐      ┌──────────────┐                      │
│  │  Background  │◄────►│   Content    │◄──── Page Scripts    │
│  │    (SW)      │      │   Script     │                      │
│  └──────┬───────┘      └──────────────┘                      │
│         │                                                     │
│         ├─► Window Management (WindowManager)                │
│         ├─► Request Interception (webRequest API)            │
│         ├─► Session Management (SessionManager)              │
│         └─► Message Routing                                  │
│                                                               │
│  ┌──────────────┐                                            │
│  │   Offscreen  │                                            │
│  │  (Background)│                                            │
│  └──────────────┘                                            │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
                   ┌──────────────┐
                   │   Verifier   │
                   │    Server    │
                   │ (localhost:  │
                   │    7047)     │
                   └──────────────┘

Opening a Managed Window:

Page → window.tlsn.open(url)
  ↓ window.postMessage(TLSN_OPEN_WINDOW)
Content Script → event listener
  ↓ browser.runtime.sendMessage(OPEN_WINDOW)
Background → WindowManager.registerWindow()
  ↓ browser.windows.create()
  ↓ Returns window info with UUID

Request Interception:

Browser → HTTP request in managed window
  ↓ webRequest.onBeforeRequest
Background → WindowManager.addRequest()
  ↓ browser.tabs.sendMessage(UPDATE_TLSN_REQUESTS)
Content Script → Update TLSN overlay UI

• Node.js >= 18
• Rust (for verifier server) - Install from rustup.rs
• Chrome/Chromium browser

1. Clone the repository:

git clone https://github.com/tlsnotary/tlsn-extension.git
cd tlsn-extension

2. Install all dependencies:

npm install

This installs dependencies for all packages in the monorepo and automatically sets up workspace links between packages.

1. Start the development server:

npm run dev

This automatically builds all dependencies (common, plugin-sdk) and then starts webpack-dev-server on port 3000 with hot module replacement. Files are written to packages/extension/build/.

2. Load the extension in Chrome:

   • Navigate to chrome://extensions/
   • Enable "Developer mode" toggle (top right)
   • Click "Load unpacked"
   • Select the packages/extension/build/ folder

3. The extension will auto-reload on file changes (manual refresh needed for manifest changes).

The verifier server is required for E2E testing. Run it in a separate terminal:

cd packages/verifier
cargo run

The server will start on http://localhost:7047.

Verifier API Endpoints:

• GET /health - Health check
• WS /session - Create new verification session
• WS /verifier?sessionId=<id> - WebSocket verification endpoint
• WS /proxy?token=<host> - WebSocket proxy for TLS connections (compatible with notary.pse.dev)

Webhook Configuration: Configure packages/verifier/config.yaml to receive POST notifications after successful verifications:

webhooks:
  'api.x.com':
    url: 'https://your-backend.example.com/webhook/twitter'
    headers:
      Authorization: 'Bearer your-secret-token'
  '*': # Wildcard for unmatched server names
    url: 'https://your-backend.example.com/webhook/default'

Extension:

cd packages/extension
npm run dev              # Development mode
npm run test             # Run tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report
npm run lint             # Lint check
npm run lint:fix         # Auto-fix linting issues

Plugin SDK:

cd packages/plugin-sdk
npm run build            # Build SDK
npm run test             # Run tests
npm run lint             # Run all linters
npm run lint:fix         # Auto-fix issues

Note: The plugin-SDK builds automatically when the extension is built, so manual building is usually not necessary.

Verifier:

cd packages/verifier
cargo run                # Development mode
cargo build --release    # Production build
cargo test               # Run tests

From the repository root:

NODE_ENV=production npm run build

This automatically:

1. Builds dependencies (@tlsn/common and @tlsn/plugin-sdk)
2. Builds the extension with production optimizations
3. Creates:
   • Optimized build in packages/extension/build/
   • Packaged extension in packages/extension/zip/extension-{version}.zip

The zip file is ready for Chrome Web Store submission.

Alternative build commands:

• npm run build:extension - Build only the extension (assumes dependencies are built)
• npm run build:deps - Build only the dependencies

npm run build:all

This builds all packages in the monorepo (extension, plugin-sdk).

cd packages/verifier
cargo build --release

The binary will be in target/release/.

To test the complete TLSN workflow:

In a terminal:

cd packages/verifier
cargo run

Verify it's running:

curl http://localhost:7047/health
# Should return: ok

In another terminal:

npm run dev

Load the extension in Chrome (see Getting Started).

Use the demo or tutorial packages to test plugins:

# Serve demo page
npm run demo
# Open http://localhost:8080 in your browser

1. Ensure the verifier is running on localhost:7047
2. Select a plugin from the demo page
3. The plugin will:
   • Open a new window to the target site
   • Intercept requests
   • Create a prover connection to the verifier
   • Display a UI overlay showing progress
   • Execute the proof workflow

When a managed window is opened:

1. An overlay appears showing "TLSN Plugin In Progress"
2. Intercepted requests are listed in real-time
3. Request count updates as more requests are captured

• Monitor Background Service Worker: Open Chrome DevTools for the background service worker via chrome://extensions/ → Extension Details → "Inspect views: service worker"
• Check Console Logs: Look for WindowManager logs, request interception logs, and message routing logs
• Test Multiple Windows: Try opening multiple managed windows simultaneously (max 10)
• Verifier Connection: Ensure verifier is accessible at localhost:7047 before running proofs

The demo package provides a complete environment for testing TLSNotary plugins.

# Start all services (verifier + demo server)
npm run docker:up

# Stop services
npm run docker:down

This starts:

• Verifier server on port 7047
• Demo static files served via nginx on port 80

# Serve demo files locally
npm run demo

# Open http://localhost:8080 in your browser

The demo uses .env files for configuration:

• .env - Local development defaults (localhost:7047)
• .env.production - Production settings (verifier.tlsnotary.org, SSL enabled)

For Docker deployments, override via environment variables:

# Local development (default)
npm run docker:up

# Production with custom verifier
VITE_VERIFIER_HOST=verifier.example.com VITE_SSL=true docker compose up --build

# Serve tutorial examples
npm run tutorial

# Open http://localhost:8080 in your browser

For WebSocket proxying of TLS connections (optional):

git clone https://github.com/novnc/websockify && cd websockify
./docker/build.sh

# For X.com
docker run -it --rm -p 55688:80 novnc/websockify 80 api.x.com:443

# For Twitter
docker run -it --rm -p 55688:80 novnc/websockify 80 api.twitter.com:443

This proxies HTTPS connections through WebSocket for browser-based TLS operations.

This repo includes a Claude Code slash command that scaffolds TLSNotary plugins interactively. It guides you through API discovery, auth interception strategy, and generates a complete plugin file.

# Add the TLSNotary marketplace
/plugin marketplace add tlsnotary/tlsn-extension

# Install the create-plugin command
/plugin install tlsn-create-plugin@tlsnotary

/create-plugin Garmin Connect badges
/create-plugin Reddit karma score
/create-plugin GitHub contribution count

The command will:

1. Research the target service's API endpoints
2. Plan the auth interception strategy
3. Generate a complete plugin .ts file with UI, proof handlers, and progress bar
4. Show you how to build and test it

1. Create a production build:

NODE_ENV=production npm run build

2. Test the extension thoroughly

3. Upload packages/extension/zip/extension-{version}.zip to Chrome Web Store Developer Dashboard

4. Follow the Chrome Web Store publishing guide

The easiest way to install the TLSN browser extension is from the Chrome Web Store.

• TLSNotary Documentation
• Webpack Documentation
• Chrome Extension Documentation
• Manifest V3 Migration Guide
• webextension-polyfill

This repository is licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.