`webtessera/browser`

openBrowserLog, device keys, receipts.

It has no Go counterpart: it is an addition of webtessera’s. Its source is src/browser/index.ts.

Functions

deleteDeviceKey: deleteDeviceKey deletes this device's key for the log with the given origin, and reports whether there was one.
detectRuntime: detectRuntime reports which kind of runtime g (by default globalThis) belongs to.
fromCryptoKey: fromCryptoKey makes a LogKey for the log with the given origin from an Ed25519 CryptoKeyPair the application already holds, such as one it keeps in a store of its own.
generateLogKey: generateLogKey generates a new Ed25519 key for the log with the given origin: a non-extractable WebCrypto key where the runtime supports one (see webCryptoEd25519), and otherwise, unless fallback is "error", a key held in memory by
loadDeviceKey: loadDeviceKey returns this device's stored key for the log with the given origin, or undefined if there is none.
openBrowserLog: openBrowserLog opens the log kept in this browser, creating it on first use, and starts appending to it with key.
openDeviceKey: openDeviceKey returns this device's key for the log with the given origin, generating it the first time: a non-extractable Ed25519 WebCrypto key, kept in IndexedDB, that no script (this library included) can export, so that it cannot be exfiltrated.
parseReceipt: parseReceipt decodes a tlog-proof, as text or bytes (or a ReceiptJSON, for its text), without verifying anything.
saveDeviceKey: saveDeviceKey stores a WebCrypto-backed key, such as one from fromCryptoKey, as this device's key for its log, so that openDeviceKey and loadDeviceKey return it from now on.
verifyReceipt: verifyReceipt checks a receipt offline, following the verification steps of C2SP tlog-proof, and returns what it proves, or throws a ReceiptError: 1. the leaf hash is the RFC 6962 hash of data, or leafHash as given, or, with dataInExtra, the hash of the proof's extra data, which must then match data or leafHash if either is given; 2. the checkpoint's origin is the log's, and the log's key signed it; 3. every cosignature by a witness in the policy verifies, and the policy is satisfied; 4. the inclusion proof binds the leaf hash at the receipt's index to the checkpoint's root hash.
webCryptoEd25519: webCryptoEd25519 resolves to whether this runtime's WebCrypto API (crypto.subtle) can hold and use Ed25519 keys, and signs exactly as RFC 8032 specifies.

Classes

ReceiptError: ReceiptError is thrown by verifyReceipt when a receipt does not prove what it is checked against.
WebtesseraError: WebtesseraError is what the safe API throws when one of its own checks fails.

Interfaces

AppendCallOptions: AppendCallOptions bounds one append, and says what its receipt carries besides the proof.
AppendManyOptions: AppendManyOptions bounds one appendMany.
BrowserLog: BrowserLog is the log openBrowserLog returns: a TransparencyLog kept in this browser.
BrowserLogOptions: BrowserLogOptions configures openBrowserLog: the options every log takes (LogOptions), and where a browser log is kept.
DeviceKeyOptions: DeviceKeyOptions says where a device key is kept.
FsckOptions: FsckOptions bounds one fsck.
FsckResult: FsckResult is what fsck reports once the whole log has verified.
GenerateLogKeyOptions: GenerateLogKeyOptions configures generateLogKey.
LogCheckpoint: LogCheckpoint is a checkpoint whose log signature has been verified: the log's origin, its size, its root hash, and the signed note it came from, cosignatures included.
LogCheckpointJSON: LogCheckpointJSON is a checkpoint as JSON.stringify writes it: the size as a decimal string, the root hash in standard base64 (as the checkpoint's own text has it), and the signed note as text.
LogEntry: LogEntry is one entry of a log, read back from its storage.
LogKey: LogKey is a log's Ed25519 signing key, held so that its secret cannot leak by accident.
LogOptions: LogOptions are the options openServerLog and openBrowserLog have in common.
ProveOptions: ProveOptions bounds one prove, and says what its receipt carries besides the proof.
Receipt: Receipt proves, offline, that an entry is in a log: it is a C2SP tlog-proof holding the entry's index, an inclusion proof, and the log's signed checkpoint with any witness cosignatures.
ReceiptJSON: ReceiptJSON is a receipt as JSON.stringify writes it: the index as a decimal string, since JSON has no 64-bit integers, and the tlog-proof text, which carries everything else. verifyReceipt and parseReceipt take it back as it is, and refuse it as malformed if its index is not the one its text proves.
TransparencyLog: TransparencyLog is a tamper-evident, append-only log whose every append hands back a receipt that proves offline that the entry is in it. openServerLog and openBrowserLog return one.
VerifiedReceipt: VerifiedReceipt is what verifyReceipt returns once every check has passed.
VerifiedReceiptJSON: VerifiedReceiptJSON is a verified receipt as JSON.stringify writes it: the index as a decimal string, the checkpoint as LogCheckpointJSON, and bytes in standard base64.
VerifyReceiptKey: VerifyReceiptKey is the part of VerifyReceiptOptions that names the log.
WitnessPolicy: WitnessPolicy is the simplest witness policy: at least threshold of witnesses must have cosigned the checkpoint.

Types

AsyncDisposableLog: AsyncDisposableLog is what lets await using log = await openServerLog(…) close the log when the scope ends: TypeScript's AsyncDisposable where the lib in use declares it, and nothing where it does not.
BrowserStorage: BrowserStorage says where a browser log is kept: - { indexedDB: name }: the IndexedDB database called name, which every tab and worker of the page's origin shares, with writes serialised by Web Locks.
KeyBackend: KeyBackend says what holds a LogKey's secret: the platform's WebCrypto API, as a CryptoKey, or
RuntimeKind: RuntimeKind names the kind of JavaScript runtime the code is running in. - node, deno, bun: the server runtimes, identified by their own globals. - workerd: Cloudflare Workers, and anything else built on workerd. - edge-light: Vercel's Edge Runtime. - browser: a browser window or frame (the main thread). - browser-worker: a dedicated, shared or service worker in a browser. - react-native: a React Native app, whose code ships to users' devices. - unknown: none of the above, and nothing that looks like a browser.
VerifyReceiptEntry: VerifyReceiptEntry is the part of VerifyReceiptOptions that names the entry: its data, its leafHash, or dataInExtra: true for a receipt that carries it. - data is the entry the receipt is for. - leafHash is the RFC 6962 leaf hash of the entry, for a verifier that holds only the hash. - dataInExtra says that the proof's extra line carries the entry itself, as a receipt from append(data, { extraData: data }) does.
VerifyReceiptOptions: VerifyReceiptOptions says what verifyReceipt checks a receipt against: the log's key, and the entry, as one of data, leafHash or dataInExtra: true.
WebtesseraErrorCode: WebtesseraErrorCode says which of the safe API's checks failed, as a stable string to branch on.

Constants and variables

DefaultCheckpointIntervalMs: DefaultCheckpointIntervalMs is how often a high-level log publishes a checkpoint while it grows.
DefaultDeviceKeyDatabase: DefaultDeviceKeyDatabase is the IndexedDB database device keys are kept in by default.
DefaultFsckWorkers: DefaultFsckWorkers is how many log resources fsck compares at once, unless told otherwise.
DefaultPublishTimeoutMs: DefaultPublishTimeoutMs is how long append waits for a checkpoint that covers its entry.
MaxExtraDataBytes: MaxExtraDataBytes is the most extra data a receipt can carry: the longest that, base64 encoded on the extra line, the tlog-proof decoders of this library and of transparency-dev/formats can read back.