tlsn-js

NPM modules for proving and verifying using TLSNotary in the browser.

Important

tlsn-js is developed specifically for browser environments and does not work in Node.js.

Important

The primary goal of tlsn-js is to support the development of the TLSNotary browser extension.
Please do not treat this as a public API (yet).

License

This repository is licensed under either:

• Apache License, Version 2.0
• MIT License

...at your option.

Examples

tlsn-js can be used in several modes depending on your use case.

The ./demo folder contains three demos:

• react-ts-webpack: Create an attestation with a Notary and render the result.
• interactive-demo: Prove data interactively to a Verifier.
• web-to-web-p2p: Prove data between two browser peers.

Running a Local WebSocket Proxy

In the demos, we attest data from https://raw.githubusercontent.com. Since browsers do not support raw TCP connections, a WebSocket proxy is required:

1. Install wstcp:

   Tool	Command
   cargo	cargo install wstcp
   brew	brew install wstcp
   source	https://github.com/sile/wstcp

2. Run a WebSocket proxy for https://raw.githubusercontent.com:

   wstcp --bind-addr 127.0.0.1:55688 raw.githubusercontent.com:443

Install as NPM Package

npm install tlsn-js

Development

This library wraps the tlsn-wasm module.

To work on both tlsn-wasm and tlsn-js locally, update package.json:

"tlsn-wasm": "./tlsn-wasm/pkg"

Then build tlsn-wasm:

npm run build:wasm

Next:

npm install
npm run test

ℹ️ To switch back to the npm-published version of tlsn-wasm, delete or reset package-lock.json to remove the local path reference.

Build for NPM

npm install
npm run build

Testing

Testing is slightly complex due to the need for browser-based workers.

• Tests live in the test/ directory.
• The tests/ directory contains a Playwright test runner that opens a Chromium browser and runs the actual test page.

Some tests require a running Notary. You can start one via Docker:

npm run notary

Adding a New tlsn-js Test

1. Create a new-test.spec.ts file in the test/ directory.

2. Add your spec file to the entry object in webpack.web.dev.config.js.

3. Create a corresponding new-test.spec.ts file in the playwright-test/ directory.

4. Add an expect() call for it in tests/test.spec.ts.

Testing the Demos

Playwright is also used to test the demos.

npm install
npm run test

• View tests in the browser:

  npx playwright test --ui

• Debug tests:

  npx playwright test --debug