burnledger 0.2.2 → 0.3.0

package/src/models.ts

@@ -0,0 +1,558 @@
+/** Readonly interfaces and parser functions for all BurnLedger API types.
+ *
+ * String literal unions for enums (no runtime cost).
+ * Parser functions are pure — snake_case JSON to camelCase with Date parsing.
+ */
+
+// ---------------------------------------------------------------------------
+// Enum types (string literal unions)
+// ---------------------------------------------------------------------------
+
+export type ProofMode = "count" | "merkle";
+export type AttestationStatus =
+  | "PENDING_VERIFICATION"
+  | "VERIFICATION_FAILED"
+  | "CERTIFIED";
+export type CertificateStatus = "ACTIVE" | "REVOKED";
+export type TransparencyStatus = "INCLUDED" | "PENDING" | "FAILED";
+export type HealthStatus = "HEALTHY" | "UNHEALTHY" | "UNKNOWN";
+/** Transport a system's connection achieves, classified at registration.
+ *
+ * Under "plaintext" and "encrypted" (TLS whose certificate is never verified)
+ * an on-path attacker can alter the record count this system contributes to a
+ * certificate. "unknown" means the config could not be classified, and is
+ * never to be read as secure.
+ */
+export type TransportSecurity =
+  | "unknown"
+  | "plaintext"
+  | "encrypted"
+  | "verified";
+/**
+ * How BurnLedger established that a system's credential cannot write.
+ *
+ * Every connector refuses write-capable credentials, but they do not all
+ * establish it the same way, and the difference is evidentiary.
+ * "verified_by_introspection" means the engine's own privilege catalog was
+ * queried and showed no write capability — evidence an auditor can re-derive.
+ * "operator_asserted" means no privilege introspection was available and the
+ * credential was admitted on the read_only flag in the connector config, which
+ * is a management attestation and is exactly what California's proposed CPPA
+ * audit rule (11 CCR 7632(d)) will not let an audit finding rest on.
+ * "write_access_detected" means the credential CAN write. "unknown" means
+ * nothing was established — never read it as a guarantee.
+ */
+export type ReadOnlyEnforcement =
+  | "unknown"
+  | "verified_by_introspection"
+  | "operator_asserted"
+  | "write_access_detected";
+// Every connector the server accepts (core/types.go). This list was six entries
+// long and included "custom", which the server rejects — so the dashboard could
+// not offer a connector picker without colliding with its own SDK on the first
+// render.
+export type ConnectorType =
+  | "postgresql"
+  | "mysql"
+  | "sqlserver"
+  | "oracle"
+  | "redshift"
+  | "teradata"
+  | "snowflake"
+  | "databricks"
+  | "mongodb"
+  | "neo4j"
+  | "redis"
+  | "cassandra"
+  | "hbase"
+  | "marklogic"
+  | "elasticsearch"
+  | "s3"
+  | "dynamodb"
+  | "gcs"
+  | "bigquery"
+  | "azure_blob";
+export type HashScope = "full" | "existence";
+export type LogEntryType = "CERTIFICATE" | "REVOCATION";
+
+/** Result of offline certificate signature verification. */
+export type VerificationResult = "VALID" | "INVALID";
+
+/** Result of transparency proof verification. */
+export type TransparencyResult = "INCLUDED" | "INVALID" | "NOT_AVAILABLE";
+
+// ---------------------------------------------------------------------------
+// Model interfaces
+// ---------------------------------------------------------------------------
+
+export interface System {
+  readonly id: string;
+  readonly name: string;
+  readonly connectorType: ConnectorType;
+  readonly subjectQuery: string;
+  readonly hashScope: HashScope;
+  readonly maxRecords: number;
+  readonly maxBytes: number;
+  readonly queryTimeout: string;
+  readonly createdAt: Date;
+  readonly healthStatus: HealthStatus;
+  readonly healthCheckedAt: Date | undefined;
+  readonly healthError: string | undefined;
+  readonly transportSecurity: TransportSecurity;
+  readonly readOnlyEnforcement: ReadOnlyEnforcement;
+}
+
+export interface SystemAttestation {
+  readonly systemId: string;
+  readonly systemName: string;
+  readonly recordCount: number;
+  readonly hashScope: HashScope;
+  readonly observedAt: Date;
+}
+
+export interface Attestation {
+  readonly id: string;
+  readonly subjectHash: string;
+  readonly proofMode: ProofMode;
+  readonly status: AttestationStatus;
+  readonly systems: readonly SystemAttestation[];
+  readonly attestedAt: Date;
+  readonly expiresAt: Date;
+  readonly certificateId: string | undefined;
+}
+
+export interface VerificationSystem {
+  readonly systemId: string;
+  readonly systemName: string;
+  readonly recordCount: number;
+}
+
+export interface VerifyResult {
+  readonly attestationId: string;
+  readonly status: AttestationStatus;
+  readonly systems: readonly VerificationSystem[];
+  readonly certificate: CertificateResponse | undefined;
+}
+
+export interface CertificateResponse {
+  readonly id: string;
+  readonly attestationId: string;
+  readonly formatVersion: string;
+  readonly issuedAt: Date;
+  readonly status: CertificateStatus;
+  readonly transparencyStatus: TransparencyStatus;
+  readonly revokedAt: Date | undefined;
+  readonly revocationReason: string | undefined;
+  readonly certificate: Record<string, unknown>;
+}
+
+export interface RevocationStatus {
+  readonly certificateId: string;
+  readonly status: CertificateStatus;
+  readonly revokedAt: Date | undefined;
+  readonly reason: string | undefined;
+}
+
+export interface Webhook {
+  readonly id: string;
+  readonly url: string;
+  readonly secret: string | undefined;
+  readonly createdAt: Date;
+}
+
+export interface SignedTreeHead {
+  readonly treeSize: number;
+  readonly rootHash: string;
+  readonly timestamp: Date;
+  readonly signature: string;
+}
+
+export interface LogEntry {
+  readonly index: number;
+  readonly entryType: LogEntryType;
+  readonly certificateId: string;
+  readonly hash: string;
+  readonly appendedAt: Date;
+}
+
+export interface InclusionProof {
+  readonly index: number;
+  readonly treeSize: number;
+  readonly inclusionProof: readonly string[];
+  readonly signedTreeHead: SignedTreeHead;
+}
+
+export interface ConsistencyProof {
+  readonly oldSize: number;
+  readonly newSize: number;
+  readonly proof: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Profile types
+// ---------------------------------------------------------------------------
+
+export interface PlanUsage {
+  readonly certificatesUsed: number;
+  readonly certificatesLimit: number;
+  readonly systemsUsed: number;
+  readonly systemsLimit: number;
+  readonly trialExpiresAt: string | undefined;
+}
+
+export interface Profile {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly plan: string;
+  readonly planStartedAt: string | undefined;
+  readonly createdAt: string;
+  readonly planUsage: PlanUsage | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// System health types
+// ---------------------------------------------------------------------------
+
+export interface SystemHealth {
+  readonly systemId: string;
+  readonly status: HealthStatus;
+  readonly lastCheckAt: string | undefined;
+  readonly error: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Batch attestation types
+// ---------------------------------------------------------------------------
+
+export interface BatchAttestationResponse {
+  readonly attestations: readonly Attestation[];
+  readonly errors: readonly BatchAttestationError[];
+}
+
+export interface BatchAttestationError {
+  readonly subjectIdentifier: string;
+  readonly error: string;
+}
+
+// ---------------------------------------------------------------------------
+// Certificate stats types
+// ---------------------------------------------------------------------------
+
+export interface MonthlyCount {
+  readonly month: string;
+  readonly count: number;
+}
+
+export interface CertificateStats {
+  readonly total: number;
+  readonly active: number;
+  readonly revoked: number;
+  readonly transparencyIncluded: number;
+  readonly transparencyPending: number;
+  /** Certificates that will never be logged. Absent from older servers, 0 then. */
+  readonly transparencyFailed: number;
+  readonly issuedLast30Days: number;
+  readonly monthlyIssuance: readonly MonthlyCount[];
+}
+
+// ---------------------------------------------------------------------------
+// Webhook delivery types
+// ---------------------------------------------------------------------------
+
+export interface WebhookRotateResponse {
+  readonly id: string;
+  readonly url: string;
+  readonly newSecret: string;
+}
+
+export interface WebhookDelivery {
+  readonly id: string;
+  readonly webhookId: string;
+  readonly eventType: string;
+  readonly errorMessage: string;
+  readonly attempts: number;
+  readonly createdAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// API key types
+// ---------------------------------------------------------------------------
+
+export type ApiKeyRole = "read_only" | "read_write";
+
+export interface ApiKeyListItem {
+  readonly id: string;
+  readonly prefix: string;
+  readonly role: ApiKeyRole;
+  readonly createdAt: Date;
+  readonly revokedAt: Date | undefined;
+}
+
+export interface ApiKeyResponse {
+  readonly id: string;
+  readonly prefix: string;
+  readonly key: string;
+  readonly createdAt: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Timestamp parsing
+// ---------------------------------------------------------------------------
+
+function parseDt(raw: string): Date {
+  return new Date(raw);
+}
+
+function parseDtOpt(raw: string | null | undefined): Date | undefined {
+  if (raw == null) return undefined;
+  return parseDt(raw);
+}
+
+// ---------------------------------------------------------------------------
+// Parsers — one per type, pure dict → interface
+// ---------------------------------------------------------------------------
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Raw = Record<string, any>;
+
+export function parseSystem(d: Raw): System {
+  return {
+    id: d.id,
+    name: d.name,
+    connectorType: d.connector_type as ConnectorType,
+    subjectQuery: d.subject_query,
+    hashScope: d.hash_scope as HashScope,
+    maxRecords: d.max_records,
+    maxBytes: d.max_bytes,
+    queryTimeout: d.query_timeout,
+    createdAt: parseDt(d.created_at),
+    healthStatus: (d.health_status ?? "UNKNOWN") as HealthStatus,
+    healthCheckedAt: parseDtOpt(d.health_checked_at),
+    healthError: d.health_error ?? undefined,
+    // A server too old to classify the transport has not measured it, so the
+    // absent field is "unknown" and never "verified".
+    transportSecurity: (d.transport_security ?? "unknown") as TransportSecurity,
+    // A server too old to record how the read-only guarantee was established
+    // has established nothing, so the absent field is "unknown" and never
+    // "verified_by_introspection".
+    readOnlyEnforcement: (d.read_only_enforcement ?? "unknown") as ReadOnlyEnforcement,
+  };
+}
+
+function parseSystemAttestation(d: Raw): SystemAttestation {
+  return {
+    systemId: d.system_id,
+    systemName: d.system_name,
+    recordCount: d.record_count,
+    hashScope: d.hash_scope as HashScope,
+    observedAt: parseDt(d.observed_at),
+  };
+}
+
+export function parseAttestation(d: Raw): Attestation {
+  return {
+    id: d.id,
+    subjectHash: d.subject_hash,
+    proofMode: d.proof_mode as ProofMode,
+    status: d.status as AttestationStatus,
+    systems: (d.systems ?? []).map(parseSystemAttestation),
+    attestedAt: parseDt(d.attested_at),
+    expiresAt: parseDt(d.expires_at),
+    certificateId: d.certificate_id ?? undefined,
+  };
+}
+
+function parseVerificationSystem(d: Raw): VerificationSystem {
+  return {
+    systemId: d.system_id,
+    systemName: d.system_name,
+    recordCount: d.record_count,
+  };
+}
+
+export function parseVerifyResult(d: Raw): VerifyResult {
+  return {
+    attestationId: d.attestation_id,
+    status: d.status as AttestationStatus,
+    systems: (d.systems ?? []).map(parseVerificationSystem),
+    certificate: d.certificate
+      ? parseCertificateResponse(d.certificate)
+      : undefined,
+  };
+}
+
+export function parseCertificateResponse(d: Raw): CertificateResponse {
+  return {
+    id: d.id,
+    attestationId: d.attestation_id,
+    formatVersion: d.format_version,
+    issuedAt: parseDt(d.issued_at),
+    status: d.status as CertificateStatus,
+    transparencyStatus: d.transparency_status as TransparencyStatus,
+    revokedAt: parseDtOpt(d.revoked_at),
+    revocationReason: d.revocation_reason ?? undefined,
+    certificate: d.certificate,
+  };
+}
+
+export function parseRevocationStatus(d: Raw): RevocationStatus {
+  return {
+    certificateId: d.certificate_id,
+    status: d.status as CertificateStatus,
+    revokedAt: parseDtOpt(d.revoked_at),
+    reason: d.reason ?? undefined,
+  };
+}
+
+export function parseWebhook(d: Raw): Webhook {
+  return {
+    id: d.id,
+    url: d.url,
+    secret: d.secret ?? undefined,
+    createdAt: parseDt(d.created_at),
+  };
+}
+
+export function parseSignedTreeHead(d: Raw): SignedTreeHead {
+  return {
+    treeSize: d.tree_size,
+    rootHash: d.root_hash,
+    timestamp: parseDt(d.timestamp),
+    signature: d.signature,
+  };
+}
+
+export function parseLogEntry(d: Raw): LogEntry {
+  return {
+    index: d.index,
+    entryType: d.entry_type as LogEntryType,
+    certificateId: d.certificate_id,
+    hash: d.hash,
+    appendedAt: parseDt(d.appended_at),
+  };
+}
+
+export function parseInclusionProof(d: Raw): InclusionProof {
+  return {
+    index: d.index,
+    treeSize: d.tree_size,
+    inclusionProof: d.inclusion_proof ?? [],
+    signedTreeHead: parseSignedTreeHead(d.signed_tree_head),
+  };
+}
+
+export function parseConsistencyProof(d: Raw): ConsistencyProof {
+  return {
+    oldSize: d.old_size,
+    newSize: d.new_size,
+    proof: d.proof ?? [],
+  };
+}
+
+function parseBatchAttestationError(d: Raw): BatchAttestationError {
+  return {
+    subjectIdentifier: d.subject_identifier,
+    error: d.error,
+  };
+}
+
+export function parseBatchAttestationResponse(d: Raw): BatchAttestationResponse {
+  return {
+    attestations: (d.attestations ?? []).map(parseAttestation),
+    errors: (d.errors ?? []).map(parseBatchAttestationError),
+  };
+}
+
+function parseMonthlyCount(d: Raw): MonthlyCount {
+  return {
+    month: d.month,
+    count: d.count,
+  };
+}
+
+export function parseCertificateStats(d: Raw): CertificateStats {
+  return {
+    total: d.total,
+    active: d.active,
+    revoked: d.revoked,
+    transparencyIncluded: d.transparency_included,
+    transparencyPending: d.transparency_pending,
+    transparencyFailed: (d.transparency_failed as number | undefined) ?? 0,
+    issuedLast30Days: d.issued_last_30_days,
+    monthlyIssuance: (d.monthly_issuance ?? []).map(parseMonthlyCount),
+  };
+}
+
+export function parseWebhookRotateResponse(d: Raw): WebhookRotateResponse {
+  return {
+    id: d.id,
+    url: d.url,
+    newSecret: d.new_secret,
+  };
+}
+
+export function parseWebhookDelivery(d: Raw): WebhookDelivery {
+  return {
+    id: d.id,
+    webhookId: d.webhook_id,
+    eventType: d.event_type,
+    errorMessage: d.error_message,
+    attempts: d.attempts,
+    createdAt: parseDt(d.created_at),
+  };
+}
+
+export function parseApiKeyListItem(d: Raw): ApiKeyListItem {
+  return {
+    id: d.id,
+    prefix: d.prefix,
+    role: d.role as ApiKeyRole,
+    createdAt: parseDt(d.created_at),
+    revokedAt: parseDtOpt(d.revoked_at),
+  };
+}
+
+export function parseApiKeyResponse(d: Raw): ApiKeyResponse {
+  return {
+    id: d.id,
+    prefix: d.prefix,
+    key: d.key,
+    createdAt: parseDt(d.created_at),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Profile / SystemHealth parsers
+// ---------------------------------------------------------------------------
+
+function parsePlanUsage(d: Raw): PlanUsage {
+  return {
+    certificatesUsed: d.certificates_used,
+    certificatesLimit: d.certificates_limit,
+    systemsUsed: d.systems_used,
+    systemsLimit: d.systems_limit,
+    trialExpiresAt: d.trial_expires_at ?? undefined,
+  };
+}
+
+export function parseProfile(d: Raw): Profile {
+  return {
+    id: d.id,
+    name: d.name,
+    email: d.email,
+    plan: d.plan,
+    planStartedAt: d.plan_started_at ?? undefined,
+    createdAt: d.created_at,
+    planUsage: d.plan_usage ? parsePlanUsage(d.plan_usage) : undefined,
+  };
+}
+
+export function parseSystemHealth(d: Raw): SystemHealth {
+  return {
+    systemId: d.system_id,
+    status: d.status as HealthStatus,
+    lastCheckAt: d.last_check_at ?? undefined,
+    error: d.error ?? undefined,
+  };
+}

package/src/pagination.ts

@@ -0,0 +1,64 @@
+/** Cursor-based auto-pagination using AsyncIterable.
+ *
+ * Lazily fetches pages on first iteration and follows `next_cursor`
+ * until the server omits it.
+ */
+
+import type { Transport } from "./http.js";
+
+type Raw = Record<string, unknown>;
+
+export class Paginator<T> implements AsyncIterable<T> {
+  private readonly transport: Transport;
+  private readonly path: string;
+  private readonly parser: (d: Raw) => T;
+  private readonly params: Record<string, string | number>;
+  private readonly authenticated: boolean;
+
+  constructor(
+    transport: Transport,
+    path: string,
+    parser: (d: Raw) => T,
+    opts: {
+      params: Record<string, string | number>;
+      authenticated?: boolean;
+    },
+  ) {
+    this.transport = transport;
+    this.path = path;
+    this.parser = parser;
+    this.params = opts.params;
+    this.authenticated = opts.authenticated ?? true;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterableIterator<T> {
+    let cursor: string | undefined;
+    let started = false;
+
+    while (true) {
+      const params: Record<string, string | number> = { ...this.params };
+      if (cursor !== undefined) {
+        params["cursor"] = cursor;
+      } else if (started) {
+        return;
+      }
+
+      const envelope = await this.transport.requestRaw("GET", this.path, {
+        params,
+        authenticated: this.authenticated,
+      });
+
+      const items = (envelope.data ?? []) as Raw[];
+      for (const item of items) {
+        yield this.parser(item);
+      }
+
+      cursor = envelope.next_cursor as string | undefined;
+      started = true;
+
+      if (cursor == null) {
+        return;
+      }
+    }
+  }
+}