burnledger 0.8.1 → 0.9.1

package/src/client.ts

@@ -48,7 +48,18 @@ import {
   parseWebhookDelivery,
   parseWebhookRotateResponse,
 } from "./models.js";
+import type { KeyEnrollmentResult, SystemRegistrationCertificate } from "./models.js";
 import { Paginator } from "./pagination.js";
+// Node-only work (enrolment, registration, savePdf) is reached through here, not
+// by naming the Node modules — so the browser entry that shares this class never
+// pulls node:crypto or node:fs into a bundle. See node-runtime.ts.
+import { loadNodeRuntime } from "./node-runtime.js";
+// Types only: erased at build, so the browser entry that shares this module
+// never loads node:crypto. The code behind them is imported lazily, on use.
+import type { CustomerKeyGroup } from "./customer-keys.js";
+import type { EnclavePinOptions, RegisteredSystem } from "./enclave-registration.js";
+import type { EnclaveIdentity } from "./enclave-seal.js";
+import type { KeyGroupSigner } from "./key-group.js";
 
 type Raw = Record<string, unknown>;
 
@@ -102,6 +113,13 @@ export class BurnLedger {
     connectionConfig?: Record<string, unknown>;
     dsn?: string;
     uri?: string;
+    /**
+     * The connection config already sealed to the enclave — by
+     * sealConnectionConfig, or by createRegisteredSystem, which does it for you.
+     * The API relays these bytes and cannot open them. Instead of
+     * connectionConfig/dsn/uri, never beside them.
+     */
+    sealedConnectionConfig?: Uint8Array;
     subjectQuery: string;
     hashScope?: string;
     /** The system holds data you treat as PHI. Makes the default proof mode
@@ -112,15 +130,19 @@ export class BurnLedger {
     maxBytes?: number;
     queryTimeout?: string;
   }): Promise<System> {
-    const config = resolveConnectionConfig(
-      opts.connectionConfig,
-      opts.dsn,
-      opts.uri,
-    );
+    const sealed = opts.sealedConnectionConfig;
+    if (
+      sealed !== undefined &&
+      (opts.connectionConfig !== undefined || opts.dsn !== undefined || opts.uri !== undefined)
+    ) {
+      throw new Error("Cannot provide both sealedConnectionConfig and connectionConfig/dsn/uri.");
+    }
     const body = {
       name: opts.name,
       connector_type: opts.connectorType,
-      connection_config: config,
+      ...(sealed === undefined
+        ? { connection_config: resolveConnectionConfig(opts.connectionConfig, opts.dsn, opts.uri) }
+        : { sealed_connection_config: bytesToBase64(sealed) }),
       subject_query: opts.subjectQuery,
       hash_scope: opts.hashScope ?? "existence",
       phi_in_scope: opts.phiInScope ?? false,
@@ -137,7 +159,7 @@ export class BurnLedger {
   async getSystem(systemId: string): Promise<System> {
     const data = await this.transport.request(
       "GET",
-      `/v1/systems/${systemId}`,
+      `/v1/systems/${encodeId(systemId)}`,
     );
     return parseSystem(data as Raw);
   }
@@ -149,13 +171,13 @@ export class BurnLedger {
   }
 
   async deregisterSystem(systemId: string): Promise<void> {
-    await this.transport.request("DELETE", `/v1/systems/${systemId}`);
+    await this.transport.request("DELETE", `/v1/systems/${encodeId(systemId)}`);
   }
 
   async healthCheck(systemId: string): Promise<System> {
     const data = await this.transport.request(
       "POST",
-      `/v1/systems/${systemId}/health-check`,
+      `/v1/systems/${encodeId(systemId)}/health-check`,
     );
     return parseSystem(data as Raw);
   }
@@ -188,7 +210,7 @@ export class BurnLedger {
   async getAttestation(attestationId: string): Promise<Attestation> {
     const data = await this.transport.request(
       "GET",
-      `/v1/attestations/${attestationId}`,
+      `/v1/attestations/${encodeId(attestationId)}`,
     );
     return parseAttestation(data as Raw);
   }
@@ -214,7 +236,7 @@ export class BurnLedger {
     const body = { subject_identifier: subjectIdentifier };
     const data = await this.transport.request(
       "POST",
-      `/v1/attestations/${attestationId}/verify`,
+      `/v1/attestations/${encodeId(attestationId)}/verify`,
       { json: body },
     );
     const result = parseVerifyResult(data as Raw);
@@ -228,7 +250,7 @@ export class BurnLedger {
       fetch: async () => {
         const d = await this.transport.request(
           "POST",
-          `/v1/attestations/${attestationId}/verify`,
+          `/v1/attestations/${encodeId(attestationId)}/verify`,
           { json: body },
         );
         return parseVerifyResult(d as Raw);
@@ -263,7 +285,7 @@ export class BurnLedger {
   async getCertificate(certificateId: string): Promise<CertificateResponse> {
     const data = await this.transport.request(
       "GET",
-      `/v1/certificates/${certificateId}`,
+      `/v1/certificates/${encodeId(certificateId)}`,
     );
     return parseCertificateResponse(data as Raw);
   }
@@ -282,20 +304,20 @@ export class BurnLedger {
   async downloadPdf(certificateId: string): Promise<Uint8Array> {
     return this.transport.requestBytes(
       "GET",
-      `/v1/certificates/${certificateId}/pdf`,
+      `/v1/certificates/${encodeId(certificateId)}/pdf`,
     );
   }
 
   async savePdf(certificateId: string, path: string): Promise<void> {
     const pdf = await this.downloadPdf(certificateId);
-    const { writeFile } = await import("node:fs/promises");
+    const { writeFile } = await loadNodeRuntime();
     await writeFile(path, pdf);
   }
 
   async getRevocationStatus(certificateId: string): Promise<RevocationStatus> {
     const data = await this.transport.request(
       "GET",
-      `/v1/certificates/${certificateId}/revocation-status`,
+      `/v1/certificates/${encodeId(certificateId)}/revocation-status`,
     );
     return parseRevocationStatus(data as Raw);
   }
@@ -306,7 +328,7 @@ export class BurnLedger {
   ): Promise<CertificateResponse> {
     const data = await this.transport.request(
       "POST",
-      `/v1/certificates/${certificateId}/revoke`,
+      `/v1/certificates/${encodeId(certificateId)}/revoke`,
       { json: { reason: opts.reason } },
     );
     return parseCertificateResponse(data as Raw);
@@ -371,13 +393,13 @@ export class BurnLedger {
   }
 
   async deleteWebhook(webhookId: string): Promise<void> {
-    await this.transport.request("DELETE", `/v1/webhooks/${webhookId}`);
+    await this.transport.request("DELETE", `/v1/webhooks/${encodeId(webhookId)}`);
   }
 
   async rotateWebhookSecret(webhookId: string): Promise<WebhookRotateResponse> {
     const data = await this.transport.request(
       "POST",
-      `/v1/webhooks/${webhookId}/rotate-secret`,
+      `/v1/webhooks/${encodeId(webhookId)}/rotate-secret`,
     );
     return parseWebhookRotateResponse(data as Raw);
   }
@@ -385,7 +407,7 @@ export class BurnLedger {
   async commitWebhookRotation(webhookId: string): Promise<void> {
     await this.transport.request(
       "POST",
-      `/v1/webhooks/${webhookId}/commit-rotation`,
+      `/v1/webhooks/${encodeId(webhookId)}/commit-rotation`,
     );
   }
 
@@ -401,14 +423,14 @@ export class BurnLedger {
   async retryDelivery(deliveryId: string): Promise<void> {
     await this.transport.request(
       "POST",
-      `/v1/webhooks/deliveries/${deliveryId}/retry`,
+      `/v1/webhooks/deliveries/${encodeId(deliveryId)}/retry`,
     );
   }
 
   async resolveDelivery(deliveryId: string): Promise<void> {
     await this.transport.request(
       "DELETE",
-      `/v1/webhooks/deliveries/${deliveryId}`,
+      `/v1/webhooks/deliveries/${encodeId(deliveryId)}`,
     );
   }
 
@@ -435,7 +457,7 @@ export class BurnLedger {
   }
 
   async revokeApiKey(keyId: string): Promise<void> {
-    await this.transport.request("DELETE", `/v1/api-keys/${keyId}`);
+    await this.transport.request("DELETE", `/v1/api-keys/${encodeId(keyId)}`);
   }
 
   // --- Profile ---
@@ -458,12 +480,177 @@ export class BurnLedger {
     await this.transport.request("DELETE", "/v1/me");
   }
 
+  // --- Customer key groups and enclave registration (ADR-025; Node only) ---
+  //
+  // These load node:crypto on first use, lazily, because this class is also the
+  // browser entry's. ADR-025 §2 makes a client the customer runs locally the
+  // only place enrolment can happen, so a browser has no business here anyway.
+  // `teamId` is the team every signed payload binds; it is also sent as
+  // asserted_team_id, so naming the wrong team is a 403 that says so rather than
+  // an enclave 401 that cannot.
+
+  /**
+   * Verify the enclave: `GET /v1/enclave/attestation` over a 32-byte challenge
+   * drawn here (or `pin.nonce`), checked against the PCR0 you pinned out of band.
+   * Returns the keys the document binds. Throws EnclaveAttestationError on
+   * anything short of a document from the pinned image answering this challenge.
+   * Pass the result as `enclave` to the calls below: configs are sealed to it,
+   * and every document they return must verify under its signing key.
+   */
+  async attestEnclaveIdentity(pin: EnclavePinOptions): Promise<EnclaveIdentity> {
+    const { registration: flow } = await loadNodeRuntime();
+    const { nonce, params } = flow.attestationParams(pin.nonce);
+    const data = await this.transport.request("GET", "/v1/enclave/attestation", {
+      params,
+      authenticated: false,
+    });
+    return flow.identityFromResponse(data, { ...pin, nonce });
+  }
+
+  /**
+   * Enrol a key group for your team (ENROLL_KEY). Every member signs; the private
+   * keys stay with the signers. `notAfter` is the latest the authorization may
+   * end, signed by every member so a relayed copy of this request cannot renew
+   * it; it defaults to the enclave's 90-day maximum. Throws VerificationError
+   * unless both documents that come back verify under `enclave`'s signing key,
+   * name exactly this group — ADR-025 §2's one comparison — and your team, end
+   * exactly at `notAfter` and do not start after `now` (this machine's clock by default).
+   */
+  async enrollKeyGroup(opts: {
+    teamId: string;
+    group: CustomerKeyGroup;
+    signers: readonly KeyGroupSigner[];
+    enclave: EnclaveIdentity;
+    notAfter?: Date;
+    /** The time to judge the answer's not_before against. Defaults to now. */
+    now?: Date;
+  }): Promise<KeyEnrollmentResult> {
+    const { registration: flow } = await loadNodeRuntime();
+    const { body, keyId, notAfter } = await flow.enrollBody(opts);
+    const data = await this.transport.request("POST", "/v1/enclave/keys", { json: body });
+    return flow.checkEnrollment(data, {
+      enclave: opts.enclave,
+      keyId,
+      prevKeyId: undefined,
+      teamId: opts.teamId,
+      notAfter,
+      now: opts.now,
+    });
+  }
+
+  /**
+   * Replace an enrolled group with another (ROTATE_KEY). The OUTGOING group
+   * signs at its threshold and EVERY incoming member signs, over the same
+   * request and `notAfter`. Systems registered under the old group keep working
+   * through the link this issues; nothing is re-registered. The answer is checked
+   * as `enrollKeyGroup`'s is, and must also link to the outgoing group.
+   */
+  async rotateKeyGroup(opts: {
+    teamId: string;
+    previousGroup: CustomerKeyGroup;
+    previousSigners: readonly KeyGroupSigner[];
+    nextGroup: CustomerKeyGroup;
+    nextSigners: readonly KeyGroupSigner[];
+    enclave: EnclaveIdentity;
+    notAfter?: Date;
+    /** The time to judge the answer's not_before against. Defaults to now. */
+    now?: Date;
+  }): Promise<KeyEnrollmentResult> {
+    const { registration: flow } = await loadNodeRuntime();
+    const { body, prevKeyId, nextKeyId, notAfter } = await flow.rotateBody(opts);
+    const data = await this.transport.request("POST", "/v1/enclave/keys/rotate", { json: body });
+    return flow.checkEnrollment(data, {
+      enclave: opts.enclave,
+      keyId: nextKeyId,
+      prevKeyId,
+      teamId: opts.teamId,
+      notAfter,
+      now: opts.now,
+    });
+  }
+
+  /**
+   * Register an existing system under your key group (REGISTER_SYSTEM), signed at
+   * the group's threshold. `config` must be the exact bytes submitted when the
+   * system was created, and `queryTemplate` the system's subject query exactly.
+   * The registration that comes back must verify under `enclave`'s signing key.
+   */
+  async registerSystemWithKey(opts: {
+    teamId: string;
+    group: CustomerKeyGroup;
+    signers: readonly KeyGroupSigner[];
+    enclave: EnclaveIdentity;
+    systemId: string;
+    config: Uint8Array | string;
+    queryTemplate: string;
+    connectorType: string;
+  }): Promise<SystemRegistrationCertificate> {
+    const { registration: flow } = await loadNodeRuntime();
+    const { body, keyId, configDigest } = await flow.registrationBody(opts);
+    const data = await this.transport.request("POST", "/v1/enclave/registrations", { json: body });
+    return flow.checkRegistration(data, {
+      enclave: opts.enclave,
+      keyId,
+      systemId: opts.systemId,
+      configDigest,
+      connectorType: opts.connectorType,
+    });
+  }
+
+  /**
+   * ADR-025's whole customer path for a new system: seal the config to `enclave`
+   * (from {@link attestEnclaveIdentity}), create the system with only the sealed
+   * bytes, and register it under your key group.
+   */
+  async createRegisteredSystem(opts: {
+    teamId: string;
+    group: CustomerKeyGroup;
+    signers: readonly KeyGroupSigner[];
+    enclave: EnclaveIdentity;
+    name: string;
+    connectorType: string;
+    connectionConfig?: Record<string, unknown>;
+    dsn?: string;
+    uri?: string;
+    subjectQuery: string;
+    hashScope?: string;
+    phiInScope?: boolean;
+    maxRecords?: number;
+    maxBytes?: number;
+    queryTimeout?: string;
+  }): Promise<RegisteredSystem> {
+    const { registration: flow, seal } = await loadNodeRuntime();
+    const config = flow.configBytes(resolveConnectionConfig(opts.connectionConfig, opts.dsn, opts.uri));
+    const system = await this.registerSystem({
+      name: opts.name,
+      connectorType: opts.connectorType,
+      subjectQuery: opts.subjectQuery,
+      hashScope: opts.hashScope,
+      phiInScope: opts.phiInScope,
+      maxRecords: opts.maxRecords,
+      maxBytes: opts.maxBytes,
+      queryTimeout: opts.queryTimeout,
+      sealedConnectionConfig: await seal.sealToKey(opts.enclave.configSealKey, config),
+    });
+    const registration = await this.registerSystemWithKey({
+      teamId: opts.teamId,
+      group: opts.group,
+      signers: opts.signers,
+      enclave: opts.enclave,
+      systemId: system.id,
+      config,
+      queryTemplate: opts.subjectQuery,
+      connectorType: opts.connectorType,
+    });
+    return { system, registration };
+  }
+
   // --- System Health ---
 
   async getSystemHealth(systemId: string): Promise<SystemHealth> {
     const data = await this.transport.request(
       "GET",
-      `/v1/systems/${systemId}/health`,
+      `/v1/systems/${encodeId(systemId)}/health`,
     );
     return parseSystemHealth(data as Raw);
   }
@@ -532,6 +719,28 @@ export class BurnLedger {
 // Connection config resolution
 // ---------------------------------------------------------------------------
 
+/** Percent-encode an id before it goes into a URL path, and refuse `.`/`..`.
+ *
+ * A raw id lets untrusted input escape its segment: `deregisterSystem("x/../../
+ * api-keys/k1")` would otherwise resolve to `DELETE /v1/api-keys/k1`.
+ * encodeURIComponent escapes the `/`, but it leaves `.` and `..` untouched, and
+ * a segment that IS `.` or `..` is still traversal — so those are rejected
+ * outright. An empty id is rejected too: it collapses two path segments into one. */
+function encodeId(id: string): string {
+  if (id === "" || id === "." || id === "..") {
+    throw new Error(`invalid id path segment: ${JSON.stringify(id)}`);
+  }
+  return encodeURIComponent(id);
+}
+
+/** Standard base64, as Go decodes a []byte field. No Buffer: this module is
+ * also the browser entry's. */
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
 function resolveConnectionConfig(
   connectionConfig: Record<string, unknown> | undefined,
   dsn: string | undefined,
@@ -577,7 +786,14 @@ async function poll<T>(opts: {
       result = await opts.fetch();
     } catch (err) {
       if (err instanceof RateLimitError && err.retryAfter !== undefined) {
-        await sleep(err.retryAfter * 1000);
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+          throw new TimeoutError(opts.operation, elapsed);
+        }
+        // Bound the wait to the caller's remaining budget: a server asking for a
+        // day, or an Infinity Retry-After, must not block past the timeout the
+        // caller set (Math.min(Infinity, remaining) === remaining).
+        await sleep(Math.min(err.retryAfter * 1000, remaining));
         continue;
       }
       throw err;