Skip to content

Commit c817bb9

Browse files
0xtsukino0xtsukino
authored
Merge pull request #43 from tlsnotary/update-extension-docs
Rewrite extension docs for the web ecosystem
1 parent 98233cd commit c817bb9

File tree

7 files changed

+2481
-262
lines changed

7 files changed

+2481
-262
lines changed

‎docs/extension/README.md‎

Lines changed: 113 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,122 @@
11
---
22
sidebar_label: Browser Extension
33
---
4-
# Chrome Extension (MV3) for TLSNotary
4+
# TLSNotary Web Browser extension
55

6-
:::warning
7-
When running the extension against a notary server, ensure that the notary server's version matches the version of this extension.
8-
:::
6+
## Overview
97

10-
:::warning
8+
The browser is the natural interface for users to interact with their private web2 data. Users already authenticate through familiar login flows, and their sessions are maintained through cookies and authentication tokens. The TLSNotary browser extension leverages this existing authentication infrastructure to generate cryptographic proofs of application-specific requests — without requiring users to share credentials or re-authenticate.
119

12-
The current browser extension will stay locked to version alpha.12 of the TLSNotary protocol while we are rewriting it on top of the upcoming TLSNotary SDK.
10+
The extension provides a secure development framework that balances flexibility with user protection. Developers write application-specific logic as JavaScript plugins that run in a sandboxed environment. This architecture enables rapid development while ensuring that sensitive authentication data never leaves the user's control. The sandbox isolates plugin code from credential access, preventing any possibility of data exfiltration.
1311

14-
:::
12+
## Architecture
1513

16-
The TLSNotary browser extension includes a plugin system that allows you to safely extend its functionality with custom plugins tailored to your specific data sources. This section also explains how to interact with the TLSN Extension within web applications.
14+
The TLSNotary Web Extension consists of four core components that work together to generate cryptographic proofs of web data:
1715

18-
- [Plugins](./plugins.md)
19-
- [Provider API](./provider.md)
16+
| Component | Role |
17+
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
18+
| **[Browser Extension](#installation)** | Runs in the user's browser. Intercepts requests, executes plugins, and drives the MPC-TLS prover. |
19+
| **[Plugin System](./plugins.md)** | JavaScript plugins that define *what* to prove — which site, which API call, and which fields to reveal. |
20+
| **[Verifier Server](./verifier.md)** | An independent server that participates in the MPC-TLS handshake, validates proofs, and optionally forwards results via webhooks. |
21+
| **[WebSocket Proxy](./verifier.md#built-in-websocket-proxy)** | Browser extensions are not allowed to setup TCP connections with the target server, so the WebSocket Proxy bridges WebSocket connections to TCP/TLS. |
22+
23+
```mermaid
24+
graph LR
25+
A["Browser<br/>Extension<br/>&lpar;Prover&rpar;"]
26+
A <-- WebSocket --> B["Verifier<br/>Server"]
27+
A <-- WebSocket --> C["WebSocket<br/>Proxy"]
28+
C <-- TCP/TLS --> D["Target Server<br/>&lpar;api.x.com, etc.&rpar;"]
29+
```
30+
31+
This architecture addresses three critical technical challenges:
32+
33+
### 1. Safe Header and Cookie Interception
34+
35+
Web applications rely on HTTP headers and cookies for authentication. The extension:
36+
37+
- Intercepts requests in a **sandboxed environment** before they leave the browser
38+
- **Never sends credentials to external servers** — everything happens locally
39+
- Uses Chrome's `webRequest` API to safely capture headers without exposing them
40+
- Gives the user **full control** over exactly what to reveal in proofs
41+
42+
### 2. Isolated Plugin Execution
43+
44+
Plugins define *what* to prove (e.g. "prove my X.com username" or "prove my bank balance exceeds $10,000"). The extension provides a secure execution environment:
45+
46+
- **QuickJS WebAssembly sandbox** isolates plugin code from the browser process
47+
- **No network access** — plugins cannot exfiltrate data
48+
- **Limited API surface** — plugins only access designed capabilities (`prove()`, `openWindow()`, etc.)
49+
- **User approval required** — plugins cannot execute without explicit consent
50+
51+
### 3. CORS-Compatible Architecture
52+
53+
Browsers enforce Same-Origin Policy and CORS, which prevents regular web pages from intercepting cross-origin requests. The extension runs with elevated permissions, allowing it to:
54+
55+
- Intercept any HTTPS request the browser makes
56+
- Capture full request and response data (headers, body, etc.)
57+
- Generate proofs for cross-origin API calls (X.com, GitHub, banks, etc.)
58+
59+
---
60+
61+
## Installation
62+
63+
### Chrome Web Store (Recommended)
64+
65+
1. Visit the [TLSNotary Extension on Chrome Web Store](https://chromewebstore.google.com/detail/gnoglgpcamodhflknhmafmjdahcejcgg)
66+
2. Click **Add to Chrome**
67+
3. Grant the required permissions
68+
69+
**Supported browsers:** Google Chrome, Microsoft Edge, Brave, and any Chromium-based browser.
70+
71+
### Build from Source
72+
73+
```bash
74+
git clone https://github.com/tlsnotary/tlsn-extension.git
75+
cd tlsn-extension
76+
npm install
77+
npm run build
78+
```
79+
80+
Then load the extension in Chrome:
81+
82+
1. Open `chrome://extensions/`
83+
2. Enable **Developer mode** (toggle in top right)
84+
3. Click **Load unpacked**
85+
4. Select the `packages/extension/build/` directory
86+
87+
For a production-optimized build:
88+
89+
```bash
90+
NODE_ENV=production npm run build
91+
```
92+
93+
---
94+
95+
## Getting Started
96+
97+
### Demo Site
98+
99+
The [demo site](https://demo.tlsnotary.org) provides pre-built plugins you can try immediately — no code required. It demonstrates end-to-end proof generation for popular services.
100+
101+
### Interactive Tutorial
102+
103+
The interactive tutorial walks you through the full development workflow:
104+
105+
1. **Concepts** — MPC-TLS, handlers, and selective disclosure
106+
2. **Running Your First Plugin** — See a complete example in action (X.com proof)
107+
3. **Writing Custom Handlers** — Add your own handler to prove bank balances
108+
4. **Advanced Challenges** — Nested JSON paths, header revelation, request/response handling
109+
5. **Breaking the Verifier** — Understand why proper verification logic matters
110+
111+
[**Start the Hosted Tutorial**](https://demo.tlsnotary.org/tutorial/) — The easiest way to get started, with a pre-configured verifier server.
112+
113+
**Run Locally:** Clone the [tutorial repository](https://github.com/tlsnotary/tlsn-extension/tree/main/packages/tutorial) and start a local verifier server (see [Verifier: Local Development](./verifier.md#local-development)). This gives you full control over the development environment.
114+
115+
---
116+
117+
## What's Next
118+
119+
- **[Plugin System](./plugins.md)** — Architecture, capabilities API, handler reference, and a full example plugin
120+
- **[Verifier Server](./verifier.md)** — Deployment, API endpoints, webhook integration, and configuration
121+
- **[Plugin SDK](https://github.com/tlsnotary/tlsn-extension/tree/main/packages/plugin-sdk)** — Source for `@tlsn/plugin-sdk`
122+
- **[Report Issues](https://github.com/tlsnotary/tlsn-extension/issues)** — Bug reports and feature requests

0 commit comments

Comments
 (0)