burnledger 0.4.0 → 0.5.0

package/src/cli.ts

@@ -119,6 +119,45 @@ export function certVerdict(
   );
 }
 
+/** Verdicts that are neither a pass nor a refusal, and what each one leaves
+ * unestablished. ADR-017 §2 calls them results a reader must be SHOWN; the
+ * verdict string alone leaves them to guess which half of the check is
+ * missing. Mirrors softKeyVerdictNote in cmd/cli/format.go. */
+const SOFT_KEY_VERDICTS: Record<string, string> = {
+  VALID_KEY_WINDOW_UNKNOWN:
+    "signatures verify; the signing key states a validity interval and this " +
+    "certificate carries no transparency proof to date it against",
+  VALID_KEY_COMPROMISED_LATER:
+    "signatures verify and appear to predate the key's compromise; " +
+    "confirm against the witness's record",
+};
+
+/** Qualifies everything this CLI says from
+ * GET /v1/certificates/{id}/revocation-status. That response is a plain JSON
+ * envelope with no signature over it, so it is the API's word rather than
+ * something the reader can re-check. The signed form exists — a
+ * certificate-status statement, which verifyCertificateWithStatus verifies —
+ * and this CLI does not fetch one; until it does, saying whose word this is
+ * beats printing the field as an established fact. Mirrors
+ * unsignedRevocationNote in cmd/cli/format.go. */
+const UNSIGNED_REVOCATION_NOTE = "unsigned API response, not a signed status statement";
+
+/**
+ * The certificate formats whose signing payload covers enclave_pcr0.
+ * Mirrors core.SignatureCoversEnclavePCR0 (core/payload.go).
+ *
+ * A SET, not a single version, and a predicate rather than an equality test.
+ * It was `=== "5.0"`, which silently stopped being true the moment v6 was
+ * added: v6 signs the measurement exactly as v5 does, and this CLI told the
+ * reader the field was under no signature while the Go CLI said the opposite
+ * about the same file.
+ */
+const ENCLAVE_PCR0_SIGNED_IN: readonly string[] = Object.freeze(["5.0", "6.0"]);
+
+function signatureCoversEnclavePcr0(version: string): boolean {
+  return ENCLAVE_PCR0_SIGNED_IN.includes(version);
+}
+
 /** Byte fields arrive as number arrays (Go [N]byte) or strings; show hex. */
 function displayHash(v: unknown): string {
   if (Array.isArray(v)) {
@@ -136,18 +175,32 @@ export function formatOutput(
   const att = cert.attestation as Record<string, unknown>;
   const L: string[] = [];
 
-  if (sigResult !== "VALID") return `Certificate dc_${id}: INVALID (${sigResult})\n`;
-  if (transparencyFailed) return `Certificate dc_${id}: INVALID (transparency: ${transparency})\n`;
+  // A soft key verdict is not a forgery: every signature verified, and what
+  // could not be established is the key's authority. "INVALID" would send an
+  // auditor hunting for tampering that is not there, and "VALID" — which this
+  // CLI printed — claims a check that did not happen.
+  const note = SOFT_KEY_VERDICTS[sigResult];
+  if (note !== undefined) return `Verification record dc_${id}: ${sigResult} (${note})\n`;
+  if (sigResult !== "VALID") return `Verification record dc_${id}: INVALID (${sigResult})\n`;
+  if (transparencyFailed) return `Verification record dc_${id}: INVALID (transparency: ${transparency})\n`;
   if (online && revocation?.status === "REVOKED") {
-    L.push(`Certificate dc_${id}: INVALID (REVOKED)`);
+    L.push(`Verification record dc_${id}: INVALID (REVOKED)`);
     if (revocation.reason) L.push(`  Revocation reason: ${revocation.reason}`);
+    // Fail closed on the API's word — an unbelieved revocation is the worse
+    // error — but name the source: this verdict rests on the same unsigned
+    // field as the one below.
+    L.push(`  Revocation source: ${UNSIGNED_REVOCATION_NOTE}`);
     return L.join("\n") + "\n";
   }
 
-  const tag = online ? "" : " (offline — revocation status not checked)";
-  L.push(`Certificate dc_${id}: VALID${tag}`);
+  // An --online answer is not a stronger answer, only a different one, so the
+  // qualifier is replaced rather than dropped.
+  const tag = online
+    ? ` (the API reports it is not revoked; ${UNSIGNED_REVOCATION_NOTE})`
+    : " (offline — revocation status not checked)";
+  L.push(`Verification record dc_${id}: VALID${tag}`);
   L.push(`  Subject: sha256:${sub.slice(0, 6)}...`);
-  L.push(`  Canonical version: ${cert.certificate_format_version as string}`);
+  L.push(`  Format version: ${cert.certificate_format_version as string}`);
 
   // v3 carries ONE system list at the top level, with both counts on each
   // record. Reading att.systems here is what made this CLI die on every real
@@ -167,10 +220,24 @@ export function formatOutput(
   // Its own line, never appended to a verdict (ADR-020), and worded so it
   // cannot be read as a checked fact: nothing offline can verify a measurement.
   // Proof is the NSM attestation document.
+  //
+  // The attribution differs by version. From v5 the field is inside the signing
+  // payload, so it is the signer's claim about itself. On v4 — the format that
+  // is actually issued, and into which the enclave writes its real measurement —
+  // no signature covers it, so calling it the signer's claim names an author
+  // nothing established: it is whatever the last holder of the file wrote.
   const issuer = cert.issuer as Record<string, unknown> | undefined;
   const pcr0 = issuer?.enclave_pcr0;
   if (typeof pcr0 === "string" && pcr0 !== "") {
-    L.push(`  Enclave image (claimed by signer, not verified here): ${pcr0}`);
+    const version = cert.certificate_format_version as string;
+    if (signatureCoversEnclavePcr0(version)) {
+      L.push(`  Enclave image (claimed by signer, not verified here): ${pcr0}`);
+    } else {
+      L.push(
+        `  Enclave image (format ${version} puts this field under no signature — ` +
+          `unattributable, not verified here): ${pcr0}`,
+      );
+    }
   }
 
   if (transparency === "INCLUDED") {
@@ -179,7 +246,9 @@ export function formatOutput(
   } else {
     L.push(`  Transparency log: ${transparency === "NOT_AVAILABLE" ? "not included" : transparency}`);
   }
-  if (online && revocation) L.push(`  Revocation status: ${revocation.status}`);
+  if (online && revocation) {
+    L.push(`  Revocation status: ${revocation.status} (${UNSIGNED_REVOCATION_NOTE})`);
+  }
   return L.join("\n") + "\n";
 }
 
@@ -202,8 +271,12 @@ async function main(): Promise<void> {
   const cert = unwrapCertificate(JSON.parse(await readFile(args.certPath, "utf-8")) as Cert);
   const keys = await loadKeys(args.keysPath);
 
+  // The verifier's own verdict, never a hardcoded word. VALID_KEY_WINDOW_UNKNOWN
+  // and VALID_KEY_COMPROMISED_LATER are cases verifyCertificate deliberately
+  // refused to call VALID, and this is the tool an auditor runs in a script —
+  // the one whose exit code gets trusted.
   let sigResult = "VALID";
-  try { await verifyCertificate(nodeCrypto, cert, keys); }
+  try { sigResult = await verifyCertificate(nodeCrypto, cert, keys); }
   catch (e) { sigResult = e instanceof Error ? e.message : "unknown error"; }
 
   // NOT_AVAILABLE (no proof) is a legitimate result; only a thrown error is a

package/src/client.ts

@@ -55,6 +55,14 @@ export interface BurnLedgerOptions {
   baseUrl?: string;
   timeout?: number;
   maxRetries?: number;
+  /**
+   * Team to act as, sent as X-Team-ID beside the key.
+   *
+   * Omit it and the API uses the caller's default team — the first one they
+   * joined — which is the right answer for a single-team account and the wrong
+   * one for anybody else.
+   */
+  teamId?: string;
 }
 
 export class BurnLedger {
@@ -66,6 +74,7 @@ export class BurnLedger {
       apiKey: opts.apiKey,
       timeout: opts.timeout ?? 30,
       maxRetries: opts.maxRetries ?? 2,
+      teamId: opts.teamId,
     });
   }
 
@@ -405,6 +414,8 @@ export class BurnLedger {
     return parseProfile(data as Raw);
   }
 
+  /** Rename the account. `email` must be the current address: changing it
+   * needs a dashboard session, and an API key is refused with 403. */
   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 },

package/src/errors.ts

@@ -101,14 +101,44 @@ export class TimeoutError extends BurnLedgerError {
 
 export class VerificationError extends BurnLedgerError {
   readonly reason: string;
-
-  constructor(reason: string) {
+  /**
+   * A stable discriminator for the one rejection a caller must be able to tell
+   * apart from the rest: an authentic status statement that says REVOKED.
+   *
+   * Every other rejection on the status path — unknown key, revoked key, bad
+   * signature, a statement about a different certificate — means the statement
+   * could not be authenticated, which is not the same claim and must not be
+   * rendered as one. `reason` is prose and may be reworded; this is not.
+   *
+   * Undefined on every rejection that is not specifically coded.
+   */
+  readonly code?: string;
+
+  constructor(reason: string, code?: string) {
     super(reason);
     this.name = "VerificationError";
     this.reason = reason;
+    this.code = code;
   }
 }
 
+/** {@link VerificationError.code} for a verified statement that says REVOKED. */
+export const CERTIFICATE_REVOKED = "CERTIFICATE_REVOKED";
+
+/**
+ * The record is in a format this SDK does not know how to read.
+ *
+ * This is the second rejection a caller must be able to tell apart, for the
+ * same reason as the first: it is not a claim about the document. Before this
+ * code existed, a record in a newer format fell through to the oldest payload
+ * shape, the rebuilt bytes did not match, and the SDK threw "certificate
+ * signature is invalid" - telling a holder their genuine evidence had been
+ * tampered with when the answer was "upgrade this library".
+ *
+ * A UI must render it as "cannot check", never as a failure.
+ */
+export const UNSUPPORTED_FORMAT_VERSION = "UNSUPPORTED_FORMAT_VERSION";
+
 const STATUS_TO_CLASS: Record<
   number,
   new (opts: {

package/src/http.ts

@@ -1,16 +1,29 @@
 /** 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.
+ * errors and on 429, and raw byte streaming for PDFs.
+ *
+ * Retry delay: a `Retry-After` header (delta-seconds or HTTP-date) is honoured
+ * when the server sends one and it is at most `MAX_RETRY_AFTER`; otherwise
+ * exponential backoff with jitter. A 429 with no usable `Retry-After`, one
+ * beyond the cap, or one on the last attempt throws `RateLimitError` with
+ * `retryAfter` populated so the caller can decide.
  */
 
 import { raiseForError } from "./errors.js";
 
+/** Longest Retry-After, in seconds, the transport will wait on before
+ * throwing instead: a server asking for minutes gets the error and the
+ * number rather than a promise nobody can cancel. */
+export const MAX_RETRY_AFTER = 30;
+
 export interface TransportOptions {
   baseUrl: string;
   apiKey: string;
   timeout: number;
   maxRetries: number;
+  /** Team to act as. Omit to let the API use the caller's default team. */
+  teamId?: string;
 }
 
 export class Transport {
@@ -18,12 +31,18 @@ export class Transport {
   private readonly apiKey: string;
   private readonly timeout: number;
   private readonly maxRetries: number;
+  // Which team the caller is acting as. The API resolves scope from this
+  // header and otherwise falls back to the caller's default team, so a member
+  // of more than one team who does not send it silently acts as whichever they
+  // joined first.
+  private readonly teamId?: string;
 
   constructor(opts: TransportOptions) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     this.apiKey = opts.apiKey;
     this.timeout = opts.timeout;
     this.maxRetries = opts.maxRetries;
+    this.teamId = opts.teamId;
   }
 
   /** Make a request and return the unwrapped `data` field. */
@@ -56,6 +75,12 @@ export class Transport {
     };
     if (authenticated) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
+      // Alongside the key, never without it: the header names the scope the
+      // caller is acting in, which is meaningless for an unauthenticated
+      // request and is not a second credential.
+      if (this.teamId) {
+        headers["X-Team-ID"] = this.teamId;
+      }
     }
 
     let url = `${this.baseUrl}${path}`;
@@ -80,14 +105,14 @@ export class Transport {
     }
 
     let lastError: Error | undefined;
+    // Delay before the next attempt when the server named one; undefined
+    // means fall back to backoff.
+    let retryAfter: number | 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);
+        await sleep(retryDelayMs(attempt, retryAfter));
+        retryAfter = undefined;
       }
 
       const controller = new AbortController();
@@ -116,8 +141,19 @@ export class Transport {
         return {};
       }
 
+      retryAfter = parseRetryAfter(resp);
       if (resp.status === 429) {
-        const retryAfter = parseRetryAfter(resp);
+        // Only on the server's say-so: without Retry-After there is no delay
+        // known to be enough, and beyond the cap the caller gets the number
+        // (RateLimitError.retryAfter) rather than a hung promise.
+        if (
+          retryAfter !== undefined &&
+          retryAfter <= MAX_RETRY_AFTER &&
+          attempt < this.maxRetries
+        ) {
+          lastError = new Error(`Server error ${resp.status}`);
+          continue;
+        }
         const errorBody = await safeJson(resp);
         raiseForError(resp.status, errorBody, retryAfter);
       }
@@ -150,6 +186,11 @@ export class Transport {
     const headers: Record<string, string> = {};
     if (authenticated) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
+      // A downloaded certificate is as team-scoped as the JSON one; omitting
+      // the header here would hand a member their default team's PDF.
+      if (this.teamId) {
+        headers["X-Team-ID"] = this.teamId;
+      }
     }
 
     const url = `${this.baseUrl}${path}`;
@@ -172,11 +213,37 @@ export class Transport {
   }
 }
 
-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;
+/** Seconds to wait per the Retry-After header (RFC 9110 §10.2.3).
+ *
+ * Accepts both forms the header allows: non-negative delta-seconds and an
+ * HTTP-date, converted to seconds from now (a date already past reads as 0).
+ * Anything else is treated as absent.
+ */
+export function parseRetryAfter(resp: Response): number | undefined {
+  const raw = resp.headers.get("Retry-After")?.trim();
+  if (!raw) return undefined;
+  if (/^\d+(\.\d+)?$/.test(raw)) {
+    return Number(raw);
+  }
+  // Every HTTP-date form (IMF-fixdate, RFC 850, asctime) opens with a weekday
+  // name; Date.parse alone would also read "-3" or "2099" as a year.
+  if (!/^[A-Za-z]{3}/.test(raw)) return undefined;
+  const when = Date.parse(raw);
+  if (Number.isNaN(when)) return undefined;
+  return Math.max(0, (when - Date.now()) / 1000);
+}
+
+/** Milliseconds to sleep before retry `attempt` (1-based). A server-supplied
+ * delay within the cap wins; otherwise exponential backoff with ±25% jitter so
+ * coordinated 5xx events don't produce a synchronized retry storm from every
+ * client at the same instant. */
+function retryDelayMs(attempt: number, retryAfter: number | undefined): number {
+  if (retryAfter !== undefined && retryAfter <= MAX_RETRY_AFTER) {
+    return retryAfter * 1000;
+  }
+  const base = Math.min(500 * 2 ** (attempt - 1), MAX_RETRY_AFTER * 1000);
+  const jitter = base * 0.25 * (Math.random() * 2 - 1);
+  return base + jitter;
 }
 
 async function safeJson(resp: Response): Promise<Record<string, unknown>> {

package/src/index.browser.ts

@@ -69,7 +69,7 @@ import {
   verifyConsistency as _verifyConsistency,
   publicKeyFromHex as _publicKeyFromHex,
 } from "./verify.js";
-import type { PublicKeyInfo } from "./verify.js";
+import type { PublicKeyInfo, PublicKeyOptions } from "./verify.js";
 import type { VerificationResult, TransparencyResult } from "./models.js";
 
 type Cert = Record<string, unknown>;
@@ -93,7 +93,7 @@ export function verifyTransparency(
 /** Construct a PublicKeyInfo from a hex-encoded Ed25519 public key. */
 export function publicKeyFromHex(
   hexKey: string,
-  opts?: { revoked?: boolean },
+  opts?: PublicKeyOptions,
 ): Promise<PublicKeyInfo> {
   return _publicKeyFromHex(browserCrypto, hexKey, opts);
 }

package/src/index.ts

@@ -14,11 +14,15 @@ export {
   ServerError,
   TimeoutError,
   VerificationError,
+  CERTIFICATE_REVOKED,
+  UNSUPPORTED_FORMAT_VERSION,
 } from "./errors.js";
 
 export { Transport } from "./http.js";
 export type { TransportOptions } from "./http.js";
 
+export type { PublicKeyOptions } from "./verify.js";
+
 export type {
   ProofMode,
   AttestationStatus,
@@ -76,7 +80,7 @@ import {
   verifyConsistency as _verifyConsistency,
   publicKeyFromHex as _publicKeyFromHex,
 } from "./verify.js";
-import type { PublicKeyInfo } from "./verify.js";
+import type { PublicKeyInfo, PublicKeyOptions } from "./verify.js";
 import type { VerificationResult, TransparencyResult } from "./models.js";
 
 type Cert = Record<string, unknown>;
@@ -123,13 +127,7 @@ export function verifyTransparency(
  */
 export function publicKeyFromHex(
   hexKey: string,
-  opts?: {
-    revoked?: boolean;
-    keyStatus?: string;
-    notBefore?: string;
-    notAfter?: string;
-    compromisedFrom?: string;
-  },
+  opts?: PublicKeyOptions,
 ): Promise<PublicKeyInfo> {
   return _publicKeyFromHex(nodeCrypto, hexKey, opts);
 }

package/src/models.ts

@@ -146,6 +146,13 @@ export interface CertificateResponse {
   readonly revokedAt: Date | undefined;
   readonly revocationReason: string | undefined;
   readonly certificate: Record<string, unknown>;
+  /**
+   * Raw enclave-signed status statement stapled by the server. Best-effort on
+   * the server side, so undefined when it could not be produced; GET
+   * /v1/certificates/{id}/status is the call that errors instead. Kept raw so
+   * it can be handed straight to verifyCertificateWithStatus().
+   */
+  readonly statusStatement: Record<string, unknown> | undefined;
 }
 
 export interface RevocationStatus {
@@ -206,6 +213,9 @@ export interface Profile {
   readonly id: string;
   readonly name: string;
   readonly email: string;
+  /** A new address waiting for the code mailed to it; `email` stays the
+   * current one until the change is confirmed from the dashboard. */
+  readonly pendingEmail: string | undefined;
   readonly plan: string;
   readonly planStartedAt: string | undefined;
   readonly createdAt: string;
@@ -218,9 +228,9 @@ export interface Profile {
 
 export interface SystemHealth {
   readonly systemId: string;
-  readonly status: HealthStatus;
-  readonly lastCheckAt: string | undefined;
-  readonly error: string | undefined;
+  readonly healthStatus: HealthStatus;
+  readonly healthCheckedAt: Date | undefined;
+  readonly healthError: string | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -233,8 +243,14 @@ export interface BatchAttestationResponse {
 }
 
 export interface BatchAttestationError {
-  readonly subjectIdentifier: string;
+  /** Position in the submitted subjectIdentifiers list. index is the durable
+   * key: subjectIdentifier is verbatim on the live response, but a replayed
+   * (Idempotency-Key) response carries a "sha256:<hex>" placeholder instead,
+   * because the cached copy never holds a raw identifier (PRIV-2). Do not key
+   * a retry on it after a replay. */
+  readonly index: number;
   readonly error: string;
+  readonly subjectIdentifier: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -266,6 +282,7 @@ export interface WebhookRotateResponse {
   readonly id: string;
   readonly url: string;
   readonly newSecret: string;
+  readonly rotationExpiresAt: Date | undefined;
 }
 
 export interface WebhookDelivery {
@@ -274,6 +291,7 @@ export interface WebhookDelivery {
   readonly eventType: string;
   readonly errorMessage: string;
   readonly attempts: number;
+  readonly nextAttemptAt: Date | undefined;
   readonly createdAt: Date;
 }
 
@@ -396,6 +414,7 @@ export function parseCertificateResponse(d: Raw): CertificateResponse {
     revokedAt: parseDtOpt(d.revoked_at),
     revocationReason: d.revocation_reason ?? undefined,
     certificate: d.certificate,
+    statusStatement: d.status_statement ?? undefined,
   };
 }
 
@@ -455,8 +474,9 @@ export function parseConsistencyProof(d: Raw): ConsistencyProof {
 
 function parseBatchAttestationError(d: Raw): BatchAttestationError {
   return {
-    subjectIdentifier: d.subject_identifier,
+    index: d.index,
     error: d.error,
+    subjectIdentifier: d.subject_identifier ?? "",
   };
 }
 
@@ -492,6 +512,7 @@ export function parseWebhookRotateResponse(d: Raw): WebhookRotateResponse {
     id: d.id,
     url: d.url,
     newSecret: d.new_secret,
+    rotationExpiresAt: parseDtOpt(d.rotation_expires_at),
   };
 }
 
@@ -502,6 +523,7 @@ export function parseWebhookDelivery(d: Raw): WebhookDelivery {
     eventType: d.event_type,
     errorMessage: d.error_message,
     attempts: d.attempts,
+    nextAttemptAt: parseDtOpt(d.next_attempt_at),
     createdAt: parseDt(d.created_at),
   };
 }
@@ -544,6 +566,7 @@ export function parseProfile(d: Raw): Profile {
     id: d.id,
     name: d.name,
     email: d.email,
+    pendingEmail: d.pending_email ?? undefined,
     plan: d.plan,
     planStartedAt: d.plan_started_at ?? undefined,
     createdAt: d.created_at,
@@ -554,8 +577,8 @@ export function parseProfile(d: Raw): Profile {
 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,
+    healthStatus: (d.health_status ?? "UNKNOWN") as HealthStatus,
+    healthCheckedAt: parseDtOpt(d.health_checked_at),
+    healthError: d.health_error ?? undefined,
   };
 }