tn-proto — Browser SDK

tn-proto is an attested-logging SDK: every call writes a signed, hash-chained, field-encrypted record. The browser build is a single self-contained ES module with the Rust/WASM core inlined — no separate .wasm to fetch. Every example on this page runs live in your browser against the real bundle. Edit any block and hit Run.

1 · Getting started 2 · Logging & reading back 3 · Shipping & restore 4 · Key storage

How this works. Each Run button loads the 0.6.5 browser bundle from the CDN (https://tn-proto.org/cdn/tn-proto.browser.mjs, served by Cloudflare), executes your code with a captured console, and renders the real return value plus any logged output below. Nothing is mocked and no output on this page is hand-written — it is whatever the bundle actually produced.

1Getting started

Import the bundle as a namespace and call tn.init(). The WASM core is inlined and initializes synchronously inside that call — there is no separate initWasm() step and no async font of .wasm to await. On first run in an origin a fresh ceremony is minted (device Ed25519 key, group publisher state, a tn.yaml manifest); later calls reload the same identity.

Import it straight from the CDN — one self-contained file, served by Cloudflare, no separate .wasm to host:
import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";
On npm the same surface is @cyaxios/tn-proto/browser.

These examples use a fresh in-memory keystore (memoryStorageAdapter()) so re-running never collides with a previous run. Section 4 covers persistent storage.

hello.attested-log.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";

// Mint or load a ceremony. WASM inits inside this call.
const client = await tn.Tn.init({ storage: tn.memoryStorageAdapter(), console: false });

client.info("hello.world", { who: "alice" });

print("did:", client.did());
print("usingRust:", client.usingRust());
print("entries:", client.read());

await client.close();

2Logging & reading backruns in browser

There are five write verbs. info / warning / error / debug carry a severity and respect the level threshold; log is severity-less and always emits (use it for audit facts). Each takes a dotted event type and a fields object. Fields are encrypted at rest; a few envelope basics (timestamp, event type, level, DID, sequence, id) stay in the clear.

log-verbs.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";
const t = await tn.Tn.init({ storage: tn.memoryStorageAdapter(), console: true });

t.info("user.signed_in",          { user_id: "u_123", plan: "pro" });
t.warning("rate_limit.approaching", { remaining: 5 });
t.error("payment.failed",          { code: "card_declined", order_id: "o_456" });
t.log("schema.migrated",           { from: "v1", to: "v2" });  // severity-less

// read() returns flat objects: envelope basics + your decrypted fields.
for (const e of t.read()) {
  print(e.sequence, e.level || "(log)", e.event_type, "->", JSON.stringify(
    Object.fromEntries(Object.entries(e).filter(([k]) =>
      !["timestamp","event_id","device_identity","sequence","level","event_type","run_id"].includes(k)))));
}
await t.close();

The receipt — full envelope with signature & chain hash

readRaw() returns { envelope, plaintext } per entry. The envelope is the audit-grade record: an Ed25519 signature over the row_hash, a prev_hash linking it to the entry before it, and the per-group ciphertext. plaintext is your decrypted fields, keyed by group. This is the receipt.

receipt.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";
const t = await tn.Tn.init({ storage: tn.memoryStorageAdapter(), console: false });

t.info("audit.event", { actor: "alice", action: "export" });

const [row] = t.readRaw();
print("envelope fields:", Object.keys(row.envelope));
print("signature:", row.envelope.signature.slice(0, 40) + "...");
print("row_hash :", row.envelope.row_hash);
print("prev_hash:", row.envelope.prev_hash);
print("decrypted plaintext:", row.plaintext);
await t.close();

Levels, context, and scopes

Tn.setLevel("warning") drops anything below WARNING — except log, which is severity-less by design. setContext stamps fields onto every subsequent event; scope overlays fields for one block only.

levels-and-context.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";
const t = await tn.Tn.init({ storage: tn.memoryStorageAdapter(), console: false });

tn.Tn.setLevel("warning");
print("level:", tn.Tn.getLevel(), "| info enabled?", tn.Tn.isEnabledFor("info"));

t.setContext({ tenant: "acme" });          // stamped on everything below
t.info("dropped.below.threshold", {});      // filtered out
t.scope({ request_id: "r1" }, () => {
  t.warning("handler.slow", { route: "/x" }); // gets tenant + request_id
});
t.log("audit.fact", { note: "always emits" });

for (const e of t.read())
  print(e.event_type, "tenant=" + e.tenant, "request_id=" + e.request_id);

tn.Tn.setLevel("debug");  // reset for other examples
await t.close();

3Shipping to a server / vault & restoring

The browser bundle ships attested envelopes one way: an HTTP handler. Pass http to init and every signed envelope is POSTed (batched, retried on 5xx, drained on page unload) to your endpoint — a witness, an ingest worker, or a hosted vault. The body is the exact canonical bytes that were attested, so server-side signature and chain checks run against precisely what the client emitted.

From the browser, the HTTP handler is the transport: it ships attested envelopes to a server you control. Account-connect and wallet-sync to a hosted vault are the Node and CLI surface.

HTTP shipping — the real transport

This runs entirely in-page: we pass a local fetch stand-in so you can inspect the exact bytes that would go over the wire. Swap in a real URL and it POSTs for real.

http-ship.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";

// Capture outgoing requests instead of hitting the network.
const wire = [];
const captureFetch = async (url, opts) => {
  wire.push({ url, body: new TextDecoder().decode(opts.body) });
  return { ok: true, status: 200, statusText: "OK" };
};

const t = await tn.Tn.init({
  storage: tn.memoryStorageAdapter(),
  console: false,
  http: { url: "https://ingest.example.com/intake",
          batchIntervalMs: 0,         // ship immediately
          fetch: captureFetch,        // omit in production -> uses window.fetch
          flushOnUnload: false },
});

t.info("checkout.completed", { order_id: "o_789", total: 42 });
await t.flush();                       // wait for the POST to settle
await t.close();

print("POSTed to:", wire[0].url);
const env = JSON.parse(wire[0].body);
print("envelope keys:", Object.keys(env));
print("signed?", !!env.signature, " chained?", !!env.row_hash);

Restore on another "device"

A keystore is just a bag of paths → bytes. To move an identity to another device, snapshot the storage adapter, ship the bytes, and replay them into a fresh adapter. The reopened client has the same DID and can decrypt the same log. This is the browser-native backup/restore — no server required.

backup-restore.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";

// --- Device A: create an identity and log to it ---
const devA = tn.memoryStorageAdapter();
const a = await tn.Tn.init({ storage: devA, console: false });
const didA = a.did();
a.info("note.created", { title: "Q3 plan" });
a.info("note.created", { title: "Q4 plan" });
await a.close();

// Snapshot the whole keystore + log (paths -> bytes).
const backup = devA.snapshot();
print("backup has", Object.keys(backup).length, "files");

// --- Device B: fresh adapter, replay the backup, reopen ---
const devB = tn.memoryStorageAdapter();
for (const [path, bytes] of Object.entries(backup)) devB.put(path, bytes);
const b = await tn.Tn.init({ storage: devB, console: false });

print("same DID?", didA === b.did());
print("recovered log:", b.read().map(e => e.title));
await b.close();

4Key storage, the JS way

The runtime never touches storage directly — it calls a small synchronous adapter for every read/write. You choose where keys live by choosing the adapter. The keystore that gets written is ten files: the device private seed, the group publisher state + your self-kit, an index-master HMAC key, the tn.yaml manifest, and the log.

In-memory — ephemeral, safest

memoryStorageAdapter(): keys live only in the JS heap, gone on reload. Best for tests, throwaway sessions, or "ship every envelope to a server and keep nothing local."

memory-keystore.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";
const mem = tn.memoryStorageAdapter();
const t = await tn.Tn.init({ storage: mem, console: false });
t.info("ephemeral.event", { ok: true });
await t.close();

print("keystore layout written by the runtime:");
for (const path of Object.keys(mem.snapshot()).sort()) print("  " + path);

localStorage — persistent across reloads

localStorageStorageAdapter(): synchronous, persists per-origin (~5 MB quota). The default for Tn.init() with no storage option. Bytes are base64-encoded into string slots. Tradeoff: readable by any script on the origin and any XSS — fine for low-stakes attested logs, not for high-value long-lived secrets. A keyPrefix lets independent identities coexist on one origin (think "two devices," or per-account separation). Quota overflow throws LocalStorageQuotaError.

localstorage-keystore.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";

// Two prefixes on the SAME origin -> two independent identities.
const appA = tn.localStorageStorageAdapter({ keyPrefix: "demo-appA/" });
const appB = tn.localStorageStorageAdapter({ keyPrefix: "demo-appB/" });

const a = await tn.Tn.init({ storage: appA, console: false });
const b = await tn.Tn.init({ storage: appB, console: false });
print("distinct DIDs?", a.did() !== b.did());
print("appA files in localStorage:", appA.size());

a.info("persisted.event", { survives: "reload" });
await a.close(); await b.close();

// Clean up this demo's keys so re-runs start fresh.
appA.clearAll(); appB.clearAll();
print("cleaned up. LocalStorageQuotaError available:", typeof tn.LocalStorageQuotaError === "function");

Custom adapter — IndexedDB, OPFS, encrypted-at-rest, anything

Because the adapter is just a nine-method synchronous interface, you can back it with whatever you like. The runtime requires the calls to be synchronous, so a truly async store (IndexedDB, OPFS) needs an in-memory write-through cache that you flush asynchronously yourself. The pattern below wraps memoryStorageAdapter() and intercepts write to also encrypt-and-persist each slot. This is the seam for passphrase-derived encryption: derive a key with crypto.subtle (PBKDF2 → AES-GCM) and wrap the bytes before they leave the page.

custom-adapter.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";

// Wrap the in-memory adapter and observe every write -> this is where
// you'd AES-GCM-wrap each slot under a passphrase-derived key before
// persisting it to IndexedDB/OPFS. Reads decrypt on the way back.
function instrumentedAdapter() {
  const base = tn.memoryStorageAdapter();
  const writes = [];
  return new Proxy(base, {
    get(target, prop) {
      if (prop === "write") return (path, data) => { writes.push(path); return target.write(path, data); };
      if (prop === "_writes") return writes;
      return target[prop];
    },
  });
}

const store = instrumentedAdapter();
const t = await tn.Tn.init({ storage: store, console: false });
t.info("secured.event", { secret: "redacted-at-rest" });
await t.close();

print("the adapter saw these slot writes (each one a wrap point):");
for (const p of store._writes) print("  " + p);

Recovery: identity = a 32-byte seed

The whole identity reduces to one 32-byte Ed25519 seed at .../keys/local.private. Hold that seed safely (the Node/CLI side also wraps it as a BIP-39 recovery phrase and pushes it to the hosted vault) and you can reconstruct the same DID anywhere with createFreshCeremony(storage, { devicePrivateBytes: seed }). The example proves the rebuilt ceremony has the identical DID.

Safe-where guidance: keep the seed in memory or a custom encrypted-at-rest adapter, never plain localStorage for a high-value identity. localStorage is fine for disposable per-session logging identities; for anything durable, encrypt the seed under a passphrase or push it to the hosted vault (Node/CLI) and treat the recovery phrase as the cold backup.

seed-recovery.mjs

import * as tn from "https://tn-proto.org/cdn/tn-proto.browser.mjs";

// Original identity.
const orig = tn.memoryStorageAdapter();
const a = await tn.Tn.init({ storage: orig, console: false });
const didA = a.did();
await a.close();

// Pull the 32-byte device seed (this is the ONE secret to back up).
const seed = orig.read("/v/.tn/tn/keys/local.private");
print("seed length:", seed.length, "bytes");

// Rebuild a brand-new ceremony bound to that seed -> same DID.
const rebuilt = tn.memoryStorageAdapter();
const res = tn.createFreshCeremony(rebuilt, { devicePrivateBytes: seed });
print("original DID:", didA);
print("rebuilt  DID:", res.did);
print("identity recovered?", res.did === didA);