burnledger 0.2.2 → 0.3.1

package/src/errors.ts

@@ -0,0 +1,154 @@
+/** Exception hierarchy for the BurnLedger SDK.
+ *
+ * Maps HTTP status codes to typed errors. Every error includes
+ * enough context for log correlation.
+ */
+
+export class BurnLedgerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BurnLedgerError";
+  }
+}
+
+export class ApiError extends BurnLedgerError {
+  readonly code: string;
+  readonly statusCode: number;
+  readonly requestId: string;
+
+  constructor(opts: {
+    code: string;
+    message: string;
+    requestId: string;
+    statusCode: number;
+  }) {
+    super(
+      `[${opts.statusCode}] ${opts.code}: ${opts.message} (request_id=${opts.requestId})`,
+    );
+    this.name = "ApiError";
+    this.code = opts.code;
+    this.statusCode = opts.statusCode;
+    this.requestId = opts.requestId;
+  }
+}
+
+export class AuthenticationError extends ApiError {
+  constructor(opts: { code: string; message: string; requestId: string }) {
+    super({ ...opts, statusCode: 401 });
+    this.name = "AuthenticationError";
+  }
+}
+
+export class NotFoundError extends ApiError {
+  constructor(opts: { code: string; message: string; requestId: string }) {
+    super({ ...opts, statusCode: 404 });
+    this.name = "NotFoundError";
+  }
+}
+
+export class ConflictError extends ApiError {
+  constructor(opts: { code: string; message: string; requestId: string }) {
+    super({ ...opts, statusCode: 409 });
+    this.name = "ConflictError";
+  }
+}
+
+export class ValidationError extends ApiError {
+  constructor(opts: { code: string; message: string; requestId: string }) {
+    super({ ...opts, statusCode: 422 });
+    this.name = "ValidationError";
+  }
+}
+
+export class RateLimitError extends ApiError {
+  readonly retryAfter: number | undefined;
+
+  constructor(opts: {
+    code: string;
+    message: string;
+    requestId: string;
+    retryAfter?: number;
+  }) {
+    super({ ...opts, statusCode: 429 });
+    this.name = "RateLimitError";
+    this.retryAfter = opts.retryAfter;
+  }
+}
+
+export class ServerError extends ApiError {
+  constructor(opts: {
+    code: string;
+    message: string;
+    requestId: string;
+    statusCode: number;
+  }) {
+    super(opts);
+    this.name = "ServerError";
+  }
+}
+
+export class TimeoutError extends BurnLedgerError {
+  readonly operation: string;
+  readonly elapsed: number;
+
+  constructor(operation: string, elapsed: number) {
+    super(`${operation}: timed out after ${elapsed.toFixed(1)}s`);
+    this.name = "TimeoutError";
+    this.operation = operation;
+    this.elapsed = elapsed;
+  }
+}
+
+export class VerificationError extends BurnLedgerError {
+  readonly reason: string;
+
+  constructor(reason: string) {
+    super(reason);
+    this.name = "VerificationError";
+    this.reason = reason;
+  }
+}
+
+const STATUS_TO_CLASS: Record<
+  number,
+  new (opts: {
+    code: string;
+    message: string;
+    requestId: string;
+    retryAfter?: number;
+  }) => ApiError
+> = {
+  401: AuthenticationError,
+  404: NotFoundError,
+  409: ConflictError,
+  422: ValidationError,
+  429: RateLimitError,
+};
+
+/** Parse an API error envelope and throw the appropriate exception. */
+export function raiseForError(
+  statusCode: number,
+  body: Record<string, unknown>,
+  retryAfter?: number,
+): never {
+  const err = (body.error ?? {}) as Record<string, unknown>;
+  const code = (err.code as string) ?? "UNKNOWN";
+  const message = (err.message as string) ?? "";
+  const requestId = (err.request_id as string) ?? "";
+
+  const Cls = STATUS_TO_CLASS[statusCode];
+
+  if (Cls === RateLimitError) {
+    throw new RateLimitError({ code, message, requestId, retryAfter });
+  }
+
+  if (Cls) {
+    throw new Cls({ code, message, requestId });
+  }
+
+  if (statusCode >= 500) {
+    throw new ServerError({ code, message, requestId, statusCode });
+  }
+
+  throw new ApiError({ code, message, requestId, statusCode });
+}

package/src/http.ts

@@ -0,0 +1,209 @@
+/** HTTP transport layer wrapping native fetch.
+ *
+ * Handles: Bearer auth, response envelope unwrapping, retry on 5xx/transport
+ * errors, Retry-After respect on 429, and raw byte streaming for PDFs.
+ */
+
+import { raiseForError } from "./errors.js";
+
+export interface TransportOptions {
+  baseUrl: string;
+  apiKey: string;
+  timeout: number;
+  maxRetries: number;
+}
+
+export class Transport {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly timeout: number;
+  private readonly maxRetries: number;
+
+  constructor(opts: TransportOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.timeout = opts.timeout;
+    this.maxRetries = opts.maxRetries;
+  }
+
+  /** Make a request and return the unwrapped `data` field. */
+  async request(
+    method: string,
+    path: string,
+    opts?: {
+      json?: unknown;
+      params?: Record<string, string | number>;
+      authenticated?: boolean;
+    },
+  ): Promise<unknown> {
+    const envelope = await this.requestRaw(method, path, opts);
+    return (envelope as Record<string, unknown>).data;
+  }
+
+  /** Make a request and return the full response envelope (for pagination). */
+  async requestRaw(
+    method: string,
+    path: string,
+    opts?: {
+      json?: unknown;
+      params?: Record<string, string | number>;
+      authenticated?: boolean;
+    },
+  ): Promise<Record<string, unknown>> {
+    const authenticated = opts?.authenticated ?? true;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+    };
+    if (authenticated) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+
+    let url = `${this.baseUrl}${path}`;
+    if (opts?.params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(opts.params)) {
+        qs.set(k, String(v));
+      }
+      url += `?${qs.toString()}`;
+    }
+
+    const body =
+      opts?.json !== undefined ? JSON.stringify(opts.json) : undefined;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (method.toUpperCase() === "POST") {
+      // One key per logical call, reused across all retries of this call, so a
+      // 5xx/transport retry is deduplicated by the server instead of issuing a
+      // second certificate.
+      headers["Idempotency-Key"] = randomIdempotencyKey();
+    }
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (attempt > 0) {
+        // Backoff with ±25% jitter so coordinated 5xx events don't produce
+        // a synchronized retry storm from every client at the same instant.
+        const base = 500 * 2 ** (attempt - 1);
+        const jitter = base * 0.25 * (Math.random() * 2 - 1);
+        await sleep(base + jitter);
+      }
+
+      const controller = new AbortController();
+      const timer = setTimeout(
+        () => controller.abort(),
+        this.timeout * 1000,
+      );
+
+      let resp: Response;
+      try {
+        resp = await fetch(url, {
+          method,
+          headers,
+          body,
+          signal: controller.signal,
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        lastError = err instanceof Error ? err : new Error(String(err));
+        continue;
+      } finally {
+        clearTimeout(timer);
+      }
+
+      if (resp.status === 204) {
+        return {};
+      }
+
+      if (resp.status === 429) {
+        const retryAfter = parseRetryAfter(resp);
+        const errorBody = await safeJson(resp);
+        raiseForError(resp.status, errorBody, retryAfter);
+      }
+
+      if (resp.status >= 500 && attempt < this.maxRetries) {
+        lastError = new Error(`Server error ${resp.status}`);
+        continue;
+      }
+
+      if (resp.status >= 400) {
+        const errorBody = await safeJson(resp);
+        raiseForError(resp.status, errorBody);
+      }
+
+      return (await resp.json()) as Record<string, unknown>;
+    }
+
+    throw new Error(
+      `Request failed after ${this.maxRetries + 1} attempts: ${lastError?.message}`,
+    );
+  }
+
+  /** Make a request and return raw bytes (for PDF downloads). */
+  async requestBytes(
+    method: string,
+    path: string,
+    opts?: { authenticated?: boolean },
+  ): Promise<Uint8Array> {
+    const authenticated = opts?.authenticated ?? true;
+    const headers: Record<string, string> = {};
+    if (authenticated) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout * 1000);
+
+    let resp: Response;
+    try {
+      resp = await fetch(url, { method, headers, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (resp.status >= 400) {
+      const errorBody = await safeJson(resp);
+      raiseForError(resp.status, errorBody);
+    }
+
+    return new Uint8Array(await resp.arrayBuffer());
+  }
+}
+
+function parseRetryAfter(resp: Response): number | undefined {
+  const raw = resp.headers.get("Retry-After");
+  if (raw == null) return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+async function safeJson(resp: Response): Promise<Record<string, unknown>> {
+  // Read once. resp.json() consumes the stream on failure too — calling
+  // resp.text() afterward would throw "body already used" and the real
+  // status code would be lost.
+  const text = await resp.text();
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return {
+      error: { code: "UNKNOWN", message: text, request_id: "" },
+    };
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// randomIdempotencyKey returns a RFC 4122 v4 UUID using the Web Crypto API,
+// available in both browsers and Node 18+ (wherever fetch is present).
+function randomIdempotencyKey(): string {
+  const b = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(b);
+  b[6] = (b[6]! & 0x0f) | 0x40; // version 4
+  b[8] = (b[8]! & 0x3f) | 0x80; // variant 10
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}

package/src/index.browser.ts

@@ -0,0 +1,110 @@
+/** BurnLedger TypeScript SDK — browser entry point.
+ *
+ * Uses WebCrypto (crypto.subtle) for Ed25519 and SHA-256.
+ * Requires Chrome 113+, Firefox 128+, or Safari 17+.
+ *
+ * Does NOT export verifyWebhookSignature (server-side only, uses node:crypto).
+ */
+
+export { BurnLedger } from "./client.js";
+export type { BurnLedgerOptions } from "./client.js";
+
+export {
+  BurnLedgerError,
+  ApiError,
+  AuthenticationError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  VerificationError,
+} from "./errors.js";
+
+export { Transport } from "./http.js";
+export type { TransportOptions } from "./http.js";
+
+export type {
+  ProofMode,
+  AttestationStatus,
+  CertificateStatus,
+  TransparencyStatus,
+  HealthStatus,
+  TransportSecurity,
+  ReadOnlyEnforcement,
+  ConnectorType,
+  HashScope,
+  LogEntryType,
+  VerificationResult,
+  TransparencyResult,
+  System,
+  SystemAttestation,
+  Attestation,
+  VerificationSystem,
+  VerifyResult,
+  CertificateResponse,
+  RevocationStatus,
+  Webhook,
+  SignedTreeHead,
+  LogEntry,
+  InclusionProof,
+  ConsistencyProof,
+} from "./models.js";
+
+// Raw-JSON → model parsers, for consumers that fetch API responses outside
+// the client (the dashboard's paginated list hooks) but render SDK types.
+export { parseSystem, parseCertificateResponse, parseWebhook } from "./models.js";
+
+export { Paginator } from "./pagination.js";
+
+export type { CryptoOps } from "./crypto.js";
+export type { PublicKeyInfo } from "./verify.js";
+export { issuanceBytes, hexToBytes, bytesToHex } from "./verify.js";
+
+import { browserCrypto } from "./crypto-browser.js";
+import {
+  verifyCertificate as _verifyCertificate,
+  verifyTransparency as _verifyTransparency,
+  verifyConsistency as _verifyConsistency,
+  publicKeyFromHex as _publicKeyFromHex,
+} from "./verify.js";
+import type { PublicKeyInfo } from "./verify.js";
+import type { VerificationResult, TransparencyResult } from "./models.js";
+
+type Cert = Record<string, unknown>;
+
+/** Verify all signatures on a deletion certificate offline. */
+export function verifyCertificate(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<VerificationResult> {
+  return _verifyCertificate(browserCrypto, certificate, publicKeys);
+}
+
+/** Verify the transparency proof embedded in a certificate. */
+export function verifyTransparency(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<TransparencyResult> {
+  return _verifyTransparency(browserCrypto, certificate, publicKeys);
+}
+
+/** Construct a PublicKeyInfo from a hex-encoded Ed25519 public key. */
+export function publicKeyFromHex(
+  hexKey: string,
+  opts?: { revoked?: boolean },
+): Promise<PublicKeyInfo> {
+  return _publicKeyFromHex(browserCrypto, hexKey, opts);
+}
+
+/** Verify a Merkle consistency proof between two tree states (RFC 6962). */
+export function verifyConsistency(
+  oldSize: number,
+  newSize: number,
+  oldRoot: Uint8Array,
+  newRoot: Uint8Array,
+  proof: Uint8Array[],
+): Promise<boolean> {
+  return _verifyConsistency(browserCrypto, oldSize, newSize, oldRoot, newRoot, proof);
+}

package/src/index.ts

@@ -0,0 +1,134 @@
+/** BurnLedger TypeScript SDK — public API (Node.js entry point). */
+
+export { BurnLedger } from "./client.js";
+export type { BurnLedgerOptions } from "./client.js";
+
+export {
+  BurnLedgerError,
+  ApiError,
+  AuthenticationError,
+  NotFoundError,
+  ConflictError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  VerificationError,
+} from "./errors.js";
+
+export { Transport } from "./http.js";
+export type { TransportOptions } from "./http.js";
+
+export type {
+  ProofMode,
+  AttestationStatus,
+  CertificateStatus,
+  TransparencyStatus,
+  HealthStatus,
+  TransportSecurity,
+  ReadOnlyEnforcement,
+  ConnectorType,
+  HashScope,
+  LogEntryType,
+  VerificationResult,
+  TransparencyResult,
+  ApiKeyRole,
+  System,
+  SystemAttestation,
+  Attestation,
+  VerificationSystem,
+  VerifyResult,
+  CertificateResponse,
+  RevocationStatus,
+  Webhook,
+  SignedTreeHead,
+  LogEntry,
+  InclusionProof,
+  ConsistencyProof,
+  BatchAttestationResponse,
+  BatchAttestationError,
+  MonthlyCount,
+  CertificateStats,
+  WebhookRotateResponse,
+  WebhookDelivery,
+  ApiKeyListItem,
+  ApiKeyResponse,
+  PlanUsage,
+  Profile,
+  SystemHealth,
+} from "./models.js";
+
+// Raw-JSON → model parsers, for consumers that fetch API responses outside
+// the client (the dashboard's paginated list hooks) but render SDK types.
+export { parseSystem, parseCertificateResponse, parseWebhook } from "./models.js";
+
+export { Paginator } from "./pagination.js";
+
+export type { CryptoOps } from "./crypto.js";
+export type { PublicKeyInfo } from "./verify.js";
+export { issuanceBytes, hexToBytes, bytesToHex } from "./verify.js";
+
+import { nodeCrypto } from "./crypto-node.js";
+import {
+  verifyCertificate as _verifyCertificate,
+  verifyCertificateWithStatus as _verifyCertificateWithStatus,
+  verifyTransparency as _verifyTransparency,
+  verifyConsistency as _verifyConsistency,
+  publicKeyFromHex as _publicKeyFromHex,
+} from "./verify.js";
+import type { PublicKeyInfo } from "./verify.js";
+import type { VerificationResult, TransparencyResult } from "./models.js";
+
+type Cert = Record<string, unknown>;
+
+/** Verify all signatures on a deletion certificate offline. */
+export function verifyCertificate(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<VerificationResult> {
+  return _verifyCertificate(nodeCrypto, certificate, publicKeys);
+}
+
+/**
+ * Verify a certificate and, separately, what a signed statement says about its
+ * revocation. Returns "VALID_REVOCATION_UNKNOWN" when no fresh statement is
+ * supplied — never "VALID", because "not revoked" is not something an offline
+ * check can establish on its own.
+ */
+export function verifyCertificateWithStatus(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+  status?: Record<string, unknown> | null,
+  now?: Date,
+): Promise<string> {
+  return _verifyCertificateWithStatus(nodeCrypto, certificate, publicKeys, status, now);
+}
+
+/** Verify the transparency proof embedded in a certificate. */
+export function verifyTransparency(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<TransparencyResult> {
+  return _verifyTransparency(nodeCrypto, certificate, publicKeys);
+}
+
+/** Construct a PublicKeyInfo from a hex-encoded Ed25519 public key. */
+export function publicKeyFromHex(
+  hexKey: string,
+  opts?: { revoked?: boolean },
+): Promise<PublicKeyInfo> {
+  return _publicKeyFromHex(nodeCrypto, hexKey, opts);
+}
+
+/** Verify a Merkle consistency proof between two tree states (RFC 6962). */
+export function verifyConsistency(
+  oldSize: number,
+  newSize: number,
+  oldRoot: Uint8Array,
+  newRoot: Uint8Array,
+  proof: Uint8Array[],
+): Promise<boolean> {
+  return _verifyConsistency(nodeCrypto, oldSize, newSize, oldRoot, newRoot, proof);
+}
+
+export { verifyWebhookSignature } from "./webhooks.js";

package/src/keys.ts

@@ -0,0 +1,18 @@
+// Public-key file parsing shared by the CLI (and unit-testable in isolation).
+
+export type KeyEntry = { key_id: string; public_key: string; key_status: string };
+
+/**
+ * Normalize a parsed keys file to an array of key entries. Accepts a bare
+ * JSON array (the generated keys.json shape), a { "keys": [...] } envelope,
+ * or the { "data": { "keys": [...] } } envelope the /.well-known endpoint
+ * actually publishes. Throws on any other shape.
+ */
+export function parseKeyEntries(parsed: unknown): KeyEntry[] {
+  const root = (parsed as { data?: unknown })?.data ?? parsed;
+  const entries = Array.isArray(root) ? root : (root as { keys?: unknown })?.keys;
+  if (!Array.isArray(entries)) {
+    throw new Error('--keys file must be a JSON array of keys or a {"keys": [...]} object');
+  }
+  return entries as KeyEntry[];
+}