The Node SDK.

pnpm add @tillstack/sdk-notary-node
# or: npm install @tillstack/sdk-notary-node

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,   // omit to read public logs
  logs: trustFromFile(trust),
})

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

const notary = new NotaryClient({
  baseUrl: 'https://notary.tilldev.dev',
  token: process.env.TILLDEV_NOTARY_TOKEN,
  logs: {
    'acme-releases': {
      origin: 'notary.tilldev.dev/acme-releases',
      logKeyName: 'tillnotary-log/acme-releases',
      publicKey: 'HXNpZy1lZDI1NTE5LW1sZHNhNjUtc2hhMjU2LnYx…',
      witnesses: [
        { keyName: 'tillnotary-witness/w1', publicKey: 'HXNpZy1lZDI1NTE5LW1sZHNhNjUtc2hhMjU2LnYx…' },
        { keyName: 'acme-witness/primary', publicKey: 'HXNpZy1lZDI1NTE5LW1sZHNhNjUtc2hhMjU2LnYx…' },
      ],
      requiredCosignatures: 2,
    },
  },
  timeoutMs: 15_000,                            // per request; this is the default
})

// a digest you computed; nothing but the hash leaves your process
const receipt = await notary.submit('acme-releases', sha256Hex)

receipt.leafIndex    // 5
receipt.checkpoint   // verified: { origin, treeSize, rootHash, timestamp, cosignatures, complete, … }
receipt.complete     // true once your pinned cosignature threshold is met
receipt.duplicate    // true when the value was already logged: this is its original receipt
receipt.evidence     // an evidence bundle for this entry

// publish the bytes themselves (4096 at most; they become publicly readable)
const attested = await notary.submit('acme-releases', {
  bytesB64: Buffer.from(sbomSummary).toString('base64'),
})

// strict: resolves only when a checkpoint that includes the leaf meets your threshold
const leaf = await notary.getLeaf('acme-releases', 5)
// → { leafIndex, leaf, bytesB64, contentClass, checkpoint, evidence }

// right after a submit, before the witnesses' next pass
const early = await notary.getLeaf('acme-releases', 8, { allowIncomplete: true })
early.checkpoint.complete   // false

// the entry holding a value (hex, or { bytesB64 }), verified the same way
const found = await notary.findLeaf('acme-releases', sha256Hex)
found?.leafIndex            // 5; null when the log holds no such value

// the newest witness-complete checkpoint, or the newest head with allowIncomplete
const head = await notary.getCheckpoint('acme-releases')
const newest = await notary.getCheckpoint('acme-releases', { allowIncomplete: true })

// prove the log still extends a head you recorded earlier
const now = await notary.verifyConsistencyFrom('acme-releases', {
  treeSize: 4,
  rootHash: 'a1d55691a4764f1c797f8849de205858215b2113e6f0dca650bc5c85f428a743',
})

// the checkpoint as a signed note, byte for byte, after verification
const { text, checkpoint } = await notary.getNote('acme-releases')

// a witness-complete evidence bundle
const bundle = await notary.exportEvidence('acme-releases', 5)

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

// no client and no network: the same pinned trust you give the client for this log
const verified = verifyEvidence(bundle, trustFromFile(trust)['acme-releases'])
// returns the verified checkpoint; throws NotaryVerificationError on any failure

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

keyFingerprint(trust.logs['acme-releases'].public_key)
// '1388 3e7f fc10 01f9 32c0 e322 13f6 aba7'  (the same as the CLI and the dashboard)

// newest first, 100 at most per page
let before: number | undefined
do {
  const page = await notary.getRefusals('acme-releases', { before, limit: 100 })
  for (const r of page.refusals) {
    // verified against the witness key you pinned
    console.error(`${r.witness} refused: ${r.reason} (${r.fromSize} ${r.fromRoot} → ${r.toSize} ${r.toRoot})`)
  }
  for (const x of page.rejected) {
    // listed by the service, but not verifiable with your pins: proves nothing either way
    console.warn('unverifiable refusal', x.id, x.witness, x.reason)
  }
  before = page.nextBefore ?? undefined
} while (before !== undefined)

import { NotaryClientError, NotaryIncompleteError, NotaryVerificationError } from '@tillstack/sdk-notary-node'

try {
  await notary.getLeaf('acme-releases', 9)
} catch (err) {
  if (err instanceof NotaryIncompleteError) {
    // verified, but your witnesses have not cosigned a head that covers it yet
    return retryAfterWitnessPass()
  }
  if (err instanceof NotaryVerificationError) {
    // not retryable and not ignorable: a signature failed, a root did not
    // recompute, or the history does not extend what you hold
    throw err
  }
  if (err instanceof NotaryClientError) {
    err.status        // 429
    err.code          // 'RATE_LIMITED'
    err.requestId     // quote this to support
    err.retryAfterMs  // how long the service asked you to wait, when it said
  }
  throw err
}

const patient = new NotaryClient({
  baseUrl: 'https://notary.tilldev.dev',
  token: process.env.TILLDEV_NOTARY_TOKEN,
  logs: trustFromFile(trust),
  retry: {
    retries: 5,             // attempts after the first; 0 turns retries off (default 3)
    maxDelayMs: 10_000,     // longest single wait (default 30000)
    onRetry: ({ attempt, delayMs, reason }) => console.warn(`${reason}; retry ${attempt} in ${delayMs} ms`),
  },
})

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

const admin = new NotaryAdminClient({
  baseUrl: 'https://notary.tilldev.dev',
  token: process.env.TILLDEV_NOTARY_ADMIN_TOKEN,   // admin scope
})

const created = await admin.createLog({
  slug: 'acme-releases',
  description: 'Release artifact digests',
  maxLeavesPerDay: 5000,   // new entries per rolling 24 hours; 50,000 when omitted
})
created.witnesses   // ['tillnotary-witness/w1']: the platform witnesses, unless you pass witnesses

await admin.registerWitness({
  name: 'acme-witness/primary',
  suite: 'sig-ed25519-mldsa65-sha256.v1',
  publicKey: 'HXNpZy1lZDI1NTE5LW1sZHNhNjUtc2hhMjU2LnYx…',
  custodyNote: 'Acme security team',
})
await admin.attachWitness('acme-releases', 'acme-witness/primary')
await admin.updateLog('acme-releases', { witnessThreshold: 2 })

// retiring a witness reports every log that can no longer reach its threshold
const { stranded } = await admin.setWitnessActive('acme-witness/primary', false)
for (const s of stranded) console.warn(`${s.slug} needs ${s.required} cosignatures, has ${s.active} active witnesses`)

import { witnessPass, witnessTransport } from '@tillstack/sdk-notary-node'
import { fileWitnessState, loadWitnessKey } from '@tillstack/sdk-notary-node/witness-state'

const signer = loadWitnessKey('./witness.key')   // made by: tilldev notary witness-node keygen
const outcomes = await witnessPass({
  signer,
  trust: [],
  discover: true,                                  // cosign every log this witness is attached to
  fetchJson: witnessTransport({ baseUrl: 'https://notary.tilldev.dev', signer }),
  state: fileWitnessState('./witness-state.json'), // keep with the key; losing it resets what was cosigned
  log: (level, message) => console.error(level, message),
})

for (const o of outcomes) {
  if (o.action === 'refused' || o.action === 'alarm') {
    // page someone: the log showed this witness a history it would not cosign
    console.error('WITNESS', o.action, o.origin, o.reason)
  }
}

// consistency-heartbeat.ts: run every 15 minutes from whatever scheduler you have
import { readFile, writeFile } from 'node:fs/promises'
import { NotaryClient, NotaryVerificationError, parseTrustFile, trustFromFile } from '@tillstack/sdk-notary-node'

const HEAD_FILE = 'notary-head.json'   // durable and backed up

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

export async function heartbeat(): Promise<void> {
  const prev = JSON.parse(await readFile(HEAD_FILE, 'utf8')) as { treeSize: number; rootHash: string }

  let head
  try {
    // today's head is signed and witness-complete, and extends the one we recorded
    head = await notary.verifyConsistencyFrom('acme-releases', prev)
  } catch (err) {
    if (err instanceof NotaryVerificationError) {
      // The log showed a history that does not extend the one we hold.
      // Keep HEAD_FILE (it is evidence), page a human, stop accepting receipts.
      console.error('NOTARY CONSISTENCY FAILED', err.message)
      process.exitCode = 1
      return
    }
    // a network error, or the service busy after retries: keep the old head, try next tick
    console.warn('notary heartbeat skipped:', String(err))
    return
  }

  // advance the recorded head only after the proof verified
  await writeFile(HEAD_FILE, JSON.stringify({ treeSize: head.treeSize, rootHash: head.rootHash }))
}

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

const trust = trustFromFile(parseTrustFile(readFileSync('notary-trust.json', 'utf8')))
const notary = new NotaryClient({ baseUrl: 'https://notary.tilldev.dev', logs: trust })
const dir = '/var/lib/notary-mirror/acme-releases'

try {
  const pass = await mirrorPass(notary, 'acme-releases', dir)
  // { origin, fromSize: 8, treeSize: 10, appended: 2, rootHash: 'bc62d10e…', complete: true }
} catch (err) {
  if (err instanceof MirrorAlarm) {
    err.record.reason  // 'shrank' | 'forked' | 'rewritten' | 'entries-mismatch'
    err.record.held    // the signed head the mirror held
    err.record.served  // the signed head that contradicts it
    await page(err.message) // the record is also appended to alarms.jsonl
  }
  throw err
}

// any time, no network: the log's signature on the held head, and every stored entry rebuilding its root
await verifyMirror(dir, trust['acme-releases'])