Documentation

Start with the safe API, then follow the guide for your use case. Each guide has a runnable example with its own tests.

Start here

The safe API has two entry points. What you import says where your code runs, and what key it may hold:

Open a log on a server, append an entry and verify its receipt:

import { DatabaseSync } from "node:sqlite";
import { importLogKey, openServerLog, verifyReceipt } from "webtessera/server";
import { fromSqliteSync } from "webtessera/storage/sqlite";

// The key comes from your secret store, never from source code.
const log = await openServerLog({
  key: await importLogKey(process.env.LOG_SKEY),
  storage: { sqlite: fromSqliteSync(new DatabaseSync("log.db")) },
});

// append resolves once a published checkpoint covers the entry, with a verified receipt.
const entry = new TextEncoder().encode("hello");
const receipt = await log.append(entry);

// Anyone with the log's vkey and the entry can check the receipt, offline.
const { index, checkpoint } = verifyReceipt(receipt.text, { vkey: log.vkey, data: entry });

To make the key, call generateKey(undefined, "example.com/log") from webtessera/note once. Keep the skey it returns in your secret store, and publish the vkey. The safe API guide explains each default, and what each entry point refuses.

Guides

One guide per use case, each walking through an example:

A client-only log

A browser keeps its own tamper-evident log in IndexedDB, signed by a device key that no script can export. Runs on browsers.

Session receipts

The browser records every exchange with your server; the server witnesses the record and commits it, verified, to a bucket. Neither side can rewrite it alone. Runs on browser + Node, Bun, Deno.

A notary

A service that logs document digests with their submitters' signatures, and returns receipts anyone can verify offline. Runs on Node, Bun, Deno.

A log server

A public log: POST /add and the tlog-tiles read API, on any SQLite. Runs on Node, Bun, Deno.

A monitor

A process that follows a log, proves it only grows, and reports forks and rollbacks. Runs on Node, Bun, Deno.

At the edge

The log server as a Worker on a SQLite-backed Durable Object, one deployment target among several. Runs on Cloudflare Workers.

And one per topic:

The safe API: webtessera/server and webtessera/browser

Read this guide before you open your first log: it covers the safe API’s environment model, key custody, the log object and its errors, and when to drop down to the ported API. Receipts covers what append returns and how anyone verifies it.

Receipts

append and prove return a receipt: everything a verifier needs to check, offline, that an entry is in the log. This guide covers its format, how to verify one, and the data it can carry. It follows the safe API.

Choosing storage

This guide compares the storage that webtessera supports and explains how locking keeps a log from forking; read it before you decide where a log lives.

The ported API

This guide walks through Tessera’s own API as webtessera ports it, and maps every package to its Go counterpart; read it when you need what the safe API leaves out, such as custom storage, migration, antispam, witness policies, key rotation or Static CT.

Serving, witnessing and mirroring

This guide covers serving a log (webtessera/http), witnessing other logs (webtessera/witness) and mirroring a log into storage you control (webtessera/mirror); read it when you deploy a log, run a witness, or keep a copy of someone else’s log.

Concepts

Transparency logs, explained covers the design of a transparency log: Merkle trees, tiles, checkpoints, proofs, receipts and witnesses, with the specifications they come from.

Reference

The API reference has a page for each of the 22 entry points, with its exports, its Go counterpart and its source.