burnledger 0.3.1 → 0.5.0

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>;
@@ -112,10 +116,18 @@ export function verifyTransparency(
   return _verifyTransparency(nodeCrypto, certificate, publicKeys);
 }
 
-/** Construct a PublicKeyInfo from a hex-encoded Ed25519 public key. */
+/** Construct a PublicKeyInfo from a hex-encoded Ed25519 public key.
+ *
+ * The options mirror a published key entry from `/.well-known/burnledger-keys`.
+ * They were previously narrowed here to `{ revoked?: boolean }` while the
+ * implementation already accepted the ADR-017 fields — so a consumer could not
+ * express a compromised key or a validity interval through the public API at
+ * all, and every key they built looked unconditionally active. Widening only;
+ * `revoked` still works and still means "unusable".
+ */
 export function publicKeyFromHex(
   hexKey: string,
-  opts?: { revoked?: boolean },
+  opts?: PublicKeyOptions,
 ): Promise<PublicKeyInfo> {
   return _publicKeyFromHex(nodeCrypto, hexKey, opts);
 }
@@ -131,4 +143,4 @@ export function verifyConsistency(
   return _verifyConsistency(nodeCrypto, oldSize, newSize, oldRoot, newRoot, proof);
 }
 
-export { verifyWebhookSignature } from "./webhooks.js";
+export { verifyWebhookSignature, isTimestampFresh } from "./webhooks.js";

package/src/keys.ts

@@ -1,6 +1,16 @@
 // 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 };
+export type KeyEntry = {
+  key_id: string;
+  public_key: string;
+  key_status: string;
+  /** ADR-017 §1. Optional because key sets published before it carry none, and
+   * "no interval stated" is nothing to check rather than something the verifier
+   * failed to check. */
+  not_before?: string;
+  not_after?: string | null;
+  compromised_from?: string | null;
+};
 
 /**
  * Normalize a parsed keys file to an array of key entries. Accepts a bare

package/src/models.ts

@@ -91,6 +91,8 @@ export interface System {
   readonly connectorType: ConnectorType;
   readonly subjectQuery: string;
   readonly hashScope: HashScope;
+  /** Marked as holding PHI; changes the default proof mode to merkle. */
+  readonly phiInScope: boolean;
   readonly maxRecords: number;
   readonly maxBytes: number;
   readonly queryTimeout: string;
@@ -144,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 {
@@ -204,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;
@@ -216,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -231,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -264,6 +282,7 @@ export interface WebhookRotateResponse {
   readonly id: string;
   readonly url: string;
   readonly newSecret: string;
+  readonly rotationExpiresAt: Date | undefined;
 }
 
 export interface WebhookDelivery {
@@ -272,6 +291,7 @@ export interface WebhookDelivery {
   readonly eventType: string;
   readonly errorMessage: string;
   readonly attempts: number;
+  readonly nextAttemptAt: Date | undefined;
   readonly createdAt: Date;
 }
 
@@ -336,6 +356,7 @@ export function parseSystem(d: Raw): System {
     // 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".
+    phiInScope: d.phi_in_scope === true,
     readOnlyEnforcement: (d.read_only_enforcement ?? "unknown") as ReadOnlyEnforcement,
   };
 }
@@ -393,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,
   };
 }
 
@@ -452,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 ?? "",
   };
 }
 
@@ -489,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),
   };
 }
 
@@ -499,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),
   };
 }
@@ -541,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,
@@ -551,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,
   };
 }