@tillstack/sdk-notary-node

Verifying client for TillNotary, a tamper-evident transparency log.

Submit a hash and get back a receipt the SDK has already checked: the checkpoint signature (hybrid Ed25519 + ML-DSA), the witness cosignature threshold, and the RFC 6962 inclusion proof. All of it is checked against keys you pin, so you don't have to take the server's word. Receipts export as portable evidence bundles that verify offline.

Install

npm install @tillstack/sdk-notary-node

Node 18+.

Pin trust

tilldev notary trust-init <log> writes a trust file with the log's public key and its witnesses. Check the key fingerprints out of band once, commit the file, then load it:

import { NotaryClient, parseTrustFile, trustFromFile } from '@tillstack/sdk-notary-node'
import { readFile } from 'node:fs/promises'

const trust = parseTrustFile(await readFile('./notary-trust.json', 'utf8'), 'notary-trust.json')
const notary = new NotaryClient({
  baseUrl: trust.base_url ?? 'https://notary.tilldev.dev',
  token: process.env.TILLDEV_NOTARY_TOKEN,
  logs: trustFromFile(trust),
})

Submit and verify

import { createHash } from 'node:crypto'
import { writeFile } from 'node:fs/promises'

const digest = createHash('sha256').update(artifact).digest('hex')
const receipt = await notary.submit('acme-releases', digest)

receipt.leafIndex // position in the log
receipt.complete  // true once the witness threshold is met
await writeFile('release.evidence.json', JSON.stringify(receipt.evidence))

Only the hash leaves your process. Submitting a value the log already holds returns its original receipt, so a retried submit never logs twice.

Look up entries

const leaf = await notary.findLeaf('acme-releases', digest) // verified, or null if absent
const again = await notary.getLeaf('acme-releases', 41)      // verified
const page = await notary.listLeaves('acme-releases', { limit: 50 }) // newest first, as served

listLeaves returns entries unverified; use getLeaf or findLeaf for a proof, or a mirror to check every entry.

Detect a rewritten log

Keep the last checkpoint you trusted and prove each new one extends it:

const head = await notary.verifyConsistencyFrom('acme-releases', { treeSize: 4096, rootHash: storedRootHex })

If the log shrank, forked or was rewritten, it throws NotaryVerificationError.

Keep a mirror

A mirror is a full local copy of a log in which every entry must rebuild the signed root. Each pass fetches only new entries:

import { MirrorAlarm, mirrorPass, verifyMirror } from '@tillstack/sdk-notary-node/mirror'

try {
  const pass = await mirrorPass(notary, 'acme-releases', './notary-mirror/acme-releases')
  console.log(pass.treeSize, pass.appended)
} catch (err) {
  if (err instanceof MirrorAlarm) console.error(err.record.reason) // shrank, forked, rewritten or entries-mismatch
  throw err
}

await verifyMirror('./notary-mirror/acme-releases', trustFromFile(trust)['acme-releases']) // offline

On an alarm, the log's conflicting signed heads are kept in alarms.jsonl in the mirror directory as evidence.

Verify offline

import { verifyEvidence } from '@tillstack/sdk-notary-node'

const checkpoint = verifyEvidence(bundle, trustFromFile(trust)['acme-releases'])

This makes no network calls. It throws if any check fails.

Errors and retries

• NotaryClientError: transport or usage problems (network, 401/403/429, bad input), with code, requestId and retryAfterMs. Reads and submissions are retried on network errors, 429 and 502 to 504, honouring Retry-After (retry: { retries, maxDelayMs } on the client; retries: 0 turns it off).
• NotaryIncompleteError: the answer verified, but witnesses have not yet cosigned a head that covers it. Retry after their next pass, or pass { allowIncomplete: true } to accept the log's signature alone. It extends NotaryVerificationError, so catch it first.
• NotaryVerificationError: the server returned something the math rejects. Never catch this and carry on.

Docs

https://tilldev.dev/docs/tillnotary/sdk

License

Apache-2.0