burnledger 0.2.2 → 0.3.0

package/src/client.ts

@@ -0,0 +1,555 @@
+/** Async BurnLedger API client.
+ *
+ * Single class — Node.js is all-async, no sync/async split needed.
+ * Pagination uses AsyncIterable<T> via Paginator.
+ */
+
+import { RateLimitError, TimeoutError } from "./errors.js";
+import { Transport } from "./http.js";
+import type {
+  ApiKeyListItem,
+  ApiKeyResponse,
+  Attestation,
+  BatchAttestationResponse,
+  CertificateResponse,
+  CertificateStats,
+  ConsistencyProof,
+  InclusionProof,
+  LogEntry,
+  Profile,
+  RevocationStatus,
+  SignedTreeHead,
+  System,
+  SystemHealth,
+  VerifyResult,
+  Webhook,
+  WebhookDelivery,
+  WebhookRotateResponse,
+} from "./models.js";
+import {
+  parseApiKeyListItem,
+  parseApiKeyResponse,
+  parseAttestation,
+  parseBatchAttestationResponse,
+  parseCertificateResponse,
+  parseCertificateStats,
+  parseConsistencyProof,
+  parseInclusionProof,
+  parseLogEntry,
+  parseProfile,
+  parseRevocationStatus,
+  parseSignedTreeHead,
+  parseSystem,
+  parseSystemHealth,
+  parseVerifyResult,
+  parseWebhook,
+  parseWebhookDelivery,
+  parseWebhookRotateResponse,
+} from "./models.js";
+import { Paginator } from "./pagination.js";
+
+type Raw = Record<string, unknown>;
+
+export interface BurnLedgerOptions {
+  apiKey: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+export class BurnLedger {
+  private readonly transport: Transport;
+
+  constructor(opts: BurnLedgerOptions) {
+    this.transport = new Transport({
+      baseUrl: opts.baseUrl ?? "https://api.burnledger.io",
+      apiKey: opts.apiKey,
+      timeout: opts.timeout ?? 30,
+      maxRetries: opts.maxRetries ?? 2,
+    });
+  }
+
+  close(): void {
+    // Transport uses native fetch — no persistent connections to close.
+    // Method exists for API symmetry and future extensibility.
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    this.close();
+    return Promise.resolve();
+  }
+
+  // --- Systems ---
+
+  async registerSystem(opts: {
+    name: string;
+    connectorType: string;
+    connectionConfig?: Record<string, unknown>;
+    dsn?: string;
+    uri?: string;
+    subjectQuery: string;
+    hashScope?: string;
+    maxRecords?: number;
+    maxBytes?: number;
+    queryTimeout?: string;
+  }): Promise<System> {
+    const config = resolveConnectionConfig(
+      opts.connectionConfig,
+      opts.dsn,
+      opts.uri,
+    );
+    const body = {
+      name: opts.name,
+      connector_type: opts.connectorType,
+      connection_config: config,
+      subject_query: opts.subjectQuery,
+      hash_scope: opts.hashScope ?? "existence",
+      max_records: opts.maxRecords ?? 1_000_000,
+      max_bytes: opts.maxBytes ?? 10 * 1024 * 1024 * 1024,
+      query_timeout: opts.queryTimeout ?? "30s",
+    };
+    const data = await this.transport.request("POST", "/v1/systems", {
+      json: body,
+    });
+    return parseSystem(data as Raw);
+  }
+
+  async getSystem(systemId: string): Promise<System> {
+    const data = await this.transport.request(
+      "GET",
+      `/v1/systems/${systemId}`,
+    );
+    return parseSystem(data as Raw);
+  }
+
+  listSystems(opts?: { limit?: number }): Paginator<System> {
+    return new Paginator(this.transport, "/v1/systems", parseSystem, {
+      params: { limit: opts?.limit ?? 25 },
+    });
+  }
+
+  async deregisterSystem(systemId: string): Promise<void> {
+    await this.transport.request("DELETE", `/v1/systems/${systemId}`);
+  }
+
+  async healthCheck(systemId: string): Promise<System> {
+    const data = await this.transport.request(
+      "POST",
+      `/v1/systems/${systemId}/health-check`,
+    );
+    return parseSystem(data as Raw);
+  }
+
+  // --- Attestations ---
+
+  async attest(
+    subjectIdentifier: string,
+    opts?: {
+      systemIds?: string[];
+      proofMode?: string;
+      expiresIn?: string;
+      webhookUrl?: string;
+    },
+  ): Promise<Attestation> {
+    const body: Record<string, unknown> = {
+      subject_identifier: subjectIdentifier,
+      proof_mode: opts?.proofMode ?? "count",
+      expires_in: opts?.expiresIn ?? "72h",
+    };
+    if (opts?.systemIds !== undefined) body.system_ids = opts.systemIds;
+    if (opts?.webhookUrl !== undefined) body.webhook_url = opts.webhookUrl;
+
+    const data = await this.transport.request("POST", "/v1/attestations", {
+      json: body,
+    });
+    return parseAttestation(data as Raw);
+  }
+
+  async getAttestation(attestationId: string): Promise<Attestation> {
+    const data = await this.transport.request(
+      "GET",
+      `/v1/attestations/${attestationId}`,
+    );
+    return parseAttestation(data as Raw);
+  }
+
+  async waitFor(
+    attestationId: string,
+    opts?: { timeout?: number; pollInterval?: number },
+  ): Promise<Attestation> {
+    return poll({
+      fetch: () => this.getAttestation(attestationId),
+      done: (att) => att.status !== "PENDING_VERIFICATION",
+      operation: `waitFor(${attestationId})`,
+      timeout: opts?.timeout ?? 60,
+      pollInterval: opts?.pollInterval ?? 2,
+    });
+  }
+
+  async verify(
+    attestationId: string,
+    subjectIdentifier: string,
+    opts?: { timeout?: number; pollInterval?: number },
+  ): Promise<VerifyResult> {
+    const body = { subject_identifier: subjectIdentifier };
+    const data = await this.transport.request(
+      "POST",
+      `/v1/attestations/${attestationId}/verify`,
+      { json: body },
+    );
+    const result = parseVerifyResult(data as Raw);
+
+    const timeout = opts?.timeout ?? 0;
+    if (timeout <= 0 || result.status === "CERTIFIED") {
+      return result;
+    }
+
+    return poll({
+      fetch: async () => {
+        const d = await this.transport.request(
+          "POST",
+          `/v1/attestations/${attestationId}/verify`,
+          { json: body },
+        );
+        return parseVerifyResult(d as Raw);
+      },
+      done: (r) => r.status === "CERTIFIED",
+      operation: `verify(${attestationId})`,
+      timeout,
+      pollInterval: opts?.pollInterval ?? 2,
+    });
+  }
+
+  async batchAttest(opts: {
+    subjectIdentifiers: string[];
+    systemIds: string[];
+    proofMode?: string;
+    expiresIn?: string;
+  }): Promise<BatchAttestationResponse> {
+    const body = {
+      subject_identifiers: opts.subjectIdentifiers,
+      system_ids: opts.systemIds,
+      proof_mode: opts.proofMode ?? "count",
+      expires_in: opts.expiresIn ?? "72h",
+    };
+    const data = await this.transport.request("POST", "/v1/attestations/batch", {
+      json: body,
+    });
+    return parseBatchAttestationResponse(data as Raw);
+  }
+
+  // --- Certificates ---
+
+  async getCertificate(certificateId: string): Promise<CertificateResponse> {
+    const data = await this.transport.request(
+      "GET",
+      `/v1/certificates/${certificateId}`,
+    );
+    return parseCertificateResponse(data as Raw);
+  }
+
+  listCertificates(opts?: {
+    limit?: number;
+  }): Paginator<CertificateResponse> {
+    return new Paginator(
+      this.transport,
+      "/v1/certificates",
+      parseCertificateResponse,
+      { params: { limit: opts?.limit ?? 25 } },
+    );
+  }
+
+  async downloadPdf(certificateId: string): Promise<Uint8Array> {
+    return this.transport.requestBytes(
+      "GET",
+      `/v1/certificates/${certificateId}/pdf`,
+    );
+  }
+
+  async savePdf(certificateId: string, path: string): Promise<void> {
+    const pdf = await this.downloadPdf(certificateId);
+    const { writeFile } = await import("node:fs/promises");
+    await writeFile(path, pdf);
+  }
+
+  async getRevocationStatus(certificateId: string): Promise<RevocationStatus> {
+    const data = await this.transport.request(
+      "GET",
+      `/v1/certificates/${certificateId}/revocation-status`,
+    );
+    return parseRevocationStatus(data as Raw);
+  }
+
+  async revokeCertificate(
+    certificateId: string,
+    opts: { reason: string },
+  ): Promise<CertificateResponse> {
+    const data = await this.transport.request(
+      "POST",
+      `/v1/certificates/${certificateId}/revoke`,
+      { json: { reason: opts.reason } },
+    );
+    return parseCertificateResponse(data as Raw);
+  }
+
+  async getCertificateStats(): Promise<CertificateStats> {
+    const data = await this.transport.request("GET", "/v1/certificates/stats");
+    return parseCertificateStats(data as Raw);
+  }
+
+  async exportCertificates(opts?: {
+    format?: "csv" | "jsonl";
+    status?: "ACTIVE" | "REVOKED";
+    issuedAfter?: string;
+    issuedBefore?: string;
+  }): Promise<Uint8Array> {
+    const params: Record<string, string> = {};
+    if (opts?.format !== undefined) params.format = opts.format;
+    if (opts?.status !== undefined) params.status = opts.status;
+    if (opts?.issuedAfter !== undefined) params.issued_after = opts.issuedAfter;
+    if (opts?.issuedBefore !== undefined) params.issued_before = opts.issuedBefore;
+
+    const qs = new URLSearchParams(params).toString();
+    const path = qs ? `/v1/certificates/export?${qs}` : "/v1/certificates/export";
+    return this.transport.requestBytes("GET", path);
+  }
+
+  // --- Webhooks ---
+
+  async registerWebhook(opts: { url: string }): Promise<Webhook> {
+    const data = await this.transport.request("POST", "/v1/webhooks", {
+      json: { url: opts.url },
+    });
+    return parseWebhook(data as Raw);
+  }
+
+  listWebhooks(opts?: { limit?: number }): Paginator<Webhook> {
+    return new Paginator(this.transport, "/v1/webhooks", parseWebhook, {
+      params: { limit: opts?.limit ?? 25 },
+    });
+  }
+
+  async deleteWebhook(webhookId: string): Promise<void> {
+    await this.transport.request("DELETE", `/v1/webhooks/${webhookId}`);
+  }
+
+  async rotateWebhookSecret(webhookId: string): Promise<WebhookRotateResponse> {
+    const data = await this.transport.request(
+      "POST",
+      `/v1/webhooks/${webhookId}/rotate-secret`,
+    );
+    return parseWebhookRotateResponse(data as Raw);
+  }
+
+  async commitWebhookRotation(webhookId: string): Promise<void> {
+    await this.transport.request(
+      "POST",
+      `/v1/webhooks/${webhookId}/commit-rotation`,
+    );
+  }
+
+  listFailedDeliveries(opts?: { limit?: number }): Paginator<WebhookDelivery> {
+    return new Paginator(
+      this.transport,
+      "/v1/webhooks/deliveries/failed",
+      parseWebhookDelivery,
+      { params: { limit: opts?.limit ?? 25 } },
+    );
+  }
+
+  async retryDelivery(deliveryId: string): Promise<void> {
+    await this.transport.request(
+      "POST",
+      `/v1/webhooks/deliveries/${deliveryId}/retry`,
+    );
+  }
+
+  async resolveDelivery(deliveryId: string): Promise<void> {
+    await this.transport.request(
+      "DELETE",
+      `/v1/webhooks/deliveries/${deliveryId}`,
+    );
+  }
+
+  // --- API Keys ---
+
+  listApiKeys(opts?: { limit?: number }): Paginator<ApiKeyListItem> {
+    return new Paginator(
+      this.transport,
+      "/v1/api-keys",
+      parseApiKeyListItem,
+      { params: { limit: opts?.limit ?? 25 } },
+    );
+  }
+
+  async createApiKey(): Promise<ApiKeyResponse> {
+    const data = await this.transport.request("POST", "/v1/api-keys", {
+      json: {},
+    });
+    return parseApiKeyResponse(data as Raw);
+  }
+
+  async revokeApiKey(keyId: string): Promise<void> {
+    await this.transport.request("DELETE", `/v1/api-keys/${keyId}`);
+  }
+
+  // --- Profile ---
+
+  async getMe(): Promise<Profile> {
+    const data = await this.transport.request("GET", "/v1/me");
+    return parseProfile(data as Raw);
+  }
+
+  async updateMe(params: { name: string; email: string }): Promise<Profile> {
+    const data = await this.transport.request("PATCH", "/v1/me", {
+      json: { name: params.name, email: params.email },
+    });
+    return parseProfile(data as Raw);
+  }
+
+  async deleteMe(): Promise<void> {
+    await this.transport.request("DELETE", "/v1/me");
+  }
+
+  // --- System Health ---
+
+  async getSystemHealth(systemId: string): Promise<SystemHealth> {
+    const data = await this.transport.request(
+      "GET",
+      `/v1/systems/${systemId}/health`,
+    );
+    return parseSystemHealth(data as Raw);
+  }
+
+  // --- Transparency log (public, no auth) ---
+
+  async getLogHead(): Promise<SignedTreeHead> {
+    const data = await this.transport.request("GET", "/v1/log/head", {
+      authenticated: false,
+    });
+    return parseSignedTreeHead(data as Raw);
+  }
+
+  async getLogEntry(index: number): Promise<LogEntry> {
+    const data = await this.transport.request(
+      "GET",
+      `/v1/log/entry/${index}`,
+      { authenticated: false },
+    );
+    return parseLogEntry(data as Raw);
+  }
+
+  async getLogEntries(opts: {
+    start: number;
+    end: number;
+  }): Promise<LogEntry[]> {
+    const data = await this.transport.request("GET", "/v1/log/entries", {
+      params: { start: opts.start, end: opts.end },
+      authenticated: false,
+    });
+    return (data as Raw[]).map(parseLogEntry);
+  }
+
+  async getInclusionProof(opts: {
+    index: number;
+    treeSize: number;
+  }): Promise<InclusionProof> {
+    const data = await this.transport.request(
+      "GET",
+      "/v1/log/proof/inclusion",
+      {
+        params: { index: opts.index, tree_size: opts.treeSize },
+        authenticated: false,
+      },
+    );
+    return parseInclusionProof(data as Raw);
+  }
+
+  async getConsistencyProof(opts: {
+    oldSize: number;
+    newSize: number;
+  }): Promise<ConsistencyProof> {
+    const data = await this.transport.request(
+      "GET",
+      "/v1/log/proof/consistency",
+      {
+        params: { old_size: opts.oldSize, new_size: opts.newSize },
+        authenticated: false,
+      },
+    );
+    return parseConsistencyProof(data as Raw);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Connection config resolution
+// ---------------------------------------------------------------------------
+
+function resolveConnectionConfig(
+  connectionConfig: Record<string, unknown> | undefined,
+  dsn: string | undefined,
+  uri: string | undefined,
+): Record<string, unknown> {
+  const convenience = (dsn !== undefined ? 1 : 0) + (uri !== undefined ? 1 : 0);
+  if (convenience > 0 && connectionConfig !== undefined) {
+    throw new Error(
+      "Cannot provide both connectionConfig and a convenience parameter (dsn/uri). Use one or the other.",
+    );
+  }
+  if (convenience > 1) {
+    throw new Error("Cannot provide both dsn and uri.");
+  }
+  if (dsn !== undefined) return { dsn };
+  if (uri !== undefined) return { uri };
+  if (connectionConfig !== undefined) return connectionConfig;
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Polling helper
+// ---------------------------------------------------------------------------
+
+async function poll<T>(opts: {
+  fetch: () => Promise<T>;
+  done: (result: T) => boolean;
+  operation: string;
+  timeout: number;
+  pollInterval: number;
+}): Promise<T> {
+  const deadline = Date.now() + opts.timeout * 1000;
+  let interval = opts.pollInterval * 1000;
+
+  while (true) {
+    const elapsed = (Date.now() - (deadline - opts.timeout * 1000)) / 1000;
+    if (Date.now() >= deadline) {
+      throw new TimeoutError(opts.operation, elapsed);
+    }
+
+    let result: T;
+    try {
+      result = await opts.fetch();
+    } catch (err) {
+      if (err instanceof RateLimitError && err.retryAfter !== undefined) {
+        await sleep(err.retryAfter * 1000);
+        continue;
+      }
+      throw err;
+    }
+
+    if (opts.done(result)) {
+      return result;
+    }
+
+    const remaining = deadline - Date.now();
+    const sleepTime = Math.min(interval, remaining);
+    if (sleepTime <= 0) {
+      throw new TimeoutError(opts.operation, elapsed);
+    }
+    await sleep(sleepTime);
+    interval = Math.min(interval * 1.5, 30_000);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/crypto-browser.ts

@@ -0,0 +1,49 @@
+/** Browser CryptoOps implementation using WebCrypto (crypto.subtle).
+ *
+ * Ed25519 support: Chrome 113+, Firefox 128+, Safari 17+.
+ */
+
+import type { CryptoOps } from "./crypto.js";
+
+export const browserCrypto: CryptoOps = {
+  async sha256(data: Uint8Array): Promise<Uint8Array> {
+    const hash = await crypto.subtle.digest("SHA-256", toBuffer(data));
+    return new Uint8Array(hash);
+  },
+
+  async ed25519Verify(
+    publicKey: Uint8Array,
+    data: Uint8Array,
+    signature: Uint8Array,
+  ): Promise<boolean> {
+    try {
+      const spki = concatBytes(ED25519_DER_PREFIX, publicKey);
+      const key = await crypto.subtle.importKey(
+        "spki",
+        toBuffer(spki),
+        { name: "Ed25519" },
+        false,
+        ["verify"],
+      );
+      return crypto.subtle.verify("Ed25519", key, toBuffer(signature), toBuffer(data));
+    } catch {
+      return false;
+    }
+  },
+};
+
+const ED25519_DER_PREFIX = new Uint8Array([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+
+/** Ensure the Uint8Array is backed by a plain ArrayBuffer (not SharedArrayBuffer). */
+function toBuffer(data: Uint8Array): ArrayBuffer {
+  return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}

package/src/crypto-node.ts

@@ -0,0 +1,40 @@
+/** Node.js CryptoOps implementation wrapping node:crypto. */
+
+import { createHash, verify } from "node:crypto";
+import type { CryptoOps } from "./crypto.js";
+
+const ED25519_DER_PREFIX = new Uint8Array([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+
+export const nodeCrypto: CryptoOps = {
+  async sha256(data: Uint8Array): Promise<Uint8Array> {
+    const hash = createHash("sha256").update(data).digest();
+    return new Uint8Array(hash);
+  },
+
+  async ed25519Verify(
+    publicKey: Uint8Array,
+    data: Uint8Array,
+    signature: Uint8Array,
+  ): Promise<boolean> {
+    try {
+      const spki = concatBytes(ED25519_DER_PREFIX, publicKey);
+      return verify(
+        null,
+        data,
+        { key: Buffer.from(spki), format: "der", type: "spki" },
+        signature,
+      );
+    } catch {
+      return false;
+    }
+  },
+};
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}

package/src/crypto.ts

@@ -0,0 +1,10 @@
+/** Pluggable cryptographic operations for Node.js and browser environments. */
+
+export interface CryptoOps {
+  sha256(data: Uint8Array): Promise<Uint8Array>;
+  ed25519Verify(
+    publicKey: Uint8Array,
+    data: Uint8Array,
+    signature: Uint8Array,
+  ): Promise<boolean>;
+}