BurnLedger TypeScript SDK

TypeScript/JavaScript client for the BurnLedger API — cryptographic deletion certificates for regulatory compliance.

Install

npm install burnledger

Requirements: Node.js 18+

Quick Start

import { BurnLedger } from "burnledger";

const dp = new BurnLedger({ apiKey: "dp_..." });

// 1. Attest — snapshot systems before deletion
const att = await dp.attest("[email protected]", {
  systemIds: ["sys_abc", "sys_def"],
});

// 2. Delete data (your code, your tools)

// 3. Verify — confirm deletion and get certificate
const result = await dp.verify(att.id, "[email protected]", { timeout: 60 });

// 4. Download certificate PDF
await dp.savePdf(result.certificate!.id, "./deletion-cert.pdf");

Browser Support

For browser environments (verification only, no API client):

import { verifyCertificate, publicKeyFromHex } from "burnledger/browser";

Uses WebCrypto (crypto.subtle) instead of node:crypto. Requires Chrome 113+, Firefox 128+, or Safari 17+.

Offline Verification

Verify certificates without network access using Ed25519 signatures:

import {
  verifyCertificate,
  verifyTransparency,
  publicKeyFromHex,
} from "burnledger";

const key = await publicKeyFromHex("abcdef...", { revoked: false });
const keys = new Map([[key.keyId, key]]);

const certResult = await verifyCertificate(certificate, keys);
// "VALID" | "INVALID"

const logResult = await verifyTransparency(certificate, keys);
// "INCLUDED" | "INVALID" | "NOT_AVAILABLE"

Webhook Verification

Verify incoming webhook signatures (HMAC-SHA256):

import { verifyWebhookSignature } from "burnledger";

const valid = verifyWebhookSignature(
  webhookSecret,       // from dp.registerWebhook()
  request.body,        // raw request body
  request.headers["x-burnledger-signature"],
);

API Reference

Client

new BurnLedger({
  apiKey: string,
  baseUrl?: string,    // default: "https://api.burnledger.com"
  timeout?: number,    // seconds, default: 30
  maxRetries?: number, // default: 2
})

Systems

| Method | Returns | |--------|---------| | registerSystem(opts) | Promise<System> | | getSystem(id) | Promise<System> | | listSystems(opts?) | Paginator<System> | | deregisterSystem(id) | Promise<void> | | healthCheck(id) | Promise<System> |

Attestations

| Method | Returns | |--------|---------| | attest(subject, opts?) | Promise<Attestation> | | getAttestation(id) | Promise<Attestation> | | waitFor(id, opts?) | Promise<Attestation> | | verify(id, subject, opts?) | Promise<VerifyResult> |

Certificates

| Method | Returns | |--------|---------| | getCertificate(id) | Promise<CertificateResponse> | | listCertificates(opts?) | Paginator<CertificateResponse> | | downloadPdf(id) | Promise<Uint8Array> | | savePdf(id, path) | Promise<void> | | getRevocationStatus(id) | Promise<RevocationStatus> | | revokeCertificate(id, opts) | Promise<CertificateResponse> |

Webhooks

| Method | Returns | |--------|---------| | registerWebhook(opts) | Promise<Webhook> | | listWebhooks(opts?) | Paginator<Webhook> | | deleteWebhook(id) | Promise<void> |

Transparency Log

These methods do not require authentication.

| Method | Returns | |--------|---------| | getLogHead() | Promise<SignedTreeHead> | | getLogEntry(index) | Promise<LogEntry> | | getLogEntries(opts) | Promise<LogEntry[]> | | getInclusionProof(opts) | Promise<InclusionProof> | | getConsistencyProof(opts) | Promise<ConsistencyProof> |

Pagination

All list* methods return a Paginator that auto-fetches pages:

for await (const cert of dp.listCertificates()) {
  console.log(cert.id);
}

Dual ESM/CJS

The package ships both ESM and CommonJS builds:

// ESM
import { BurnLedger } from "burnledger";

// CommonJS
const { BurnLedger } = require("burnledger");

License

MIT