burnledger 0.8.0 → 0.9.0

package/src/cli.ts

@@ -9,7 +9,9 @@ import { nodeCrypto } from "./crypto-node.js";
 import { CERTIFICATE_REVOKED, VerificationError } from "./errors.js";
 import {
   formatTimestamp,
+  issuingImage,
   publicKeyFromHex,
+  registrationQualifier,
   verifyCertificateWithStatus,
   verifyTransparency,
   KNOWN_FORMAT_VERSIONS,
@@ -24,23 +26,34 @@ import {
   type KeyListEvidence,
 } from "./keys.js";
 import { ANCHOR_INCONSISTENT, checkStatementAnchor, type AnchorResult } from "./anchor.js";
-import type { PublicKeyInfo } from "./verify.js";
+import { unwrapStatusStatement } from "./status-document.js";
+import type { AuthorizationPolicy, PublicKeyInfo } from "./verify.js";
+
+// Exported from here too: tests/cli-revocation-unknown.test.ts reads it as the
+// CLI's own parser.
+export { unwrapStatusStatement };
 
 type Cert = Record<string, unknown>;
 /** A published status statement, exactly as GET /v1/certificates/{id}/status
  * serves it: hex strings, not decoded bytes. verifyCertificateWithStatus reads
  * this shape, so nothing here re-encodes a field the signature covers. */
 type StatusStatement = Record<string, unknown>;
-const USAGE = "Usage: burnledger check --cert <file> --keys <file> [--online --api-url <url>]\n";
+const USAGE =
+  "Usage: burnledger check --cert <file> --keys <file> [--online --api-url <url>]\n" +
+  "       [[--require-certified | --require-certified-system <system_id>...] --customer-key-id <id>...]\n";
 
 function die(msg: string): never { process.stderr.write(msg); process.exit(2); }
 
 function parseArgs(argv: string[]): {
   certPath: string; keysPath: string; online: boolean; apiUrl: string;
+  policy: AuthorizationPolicy | undefined;
 } {
   const args = argv.slice(2);
   if (args[0] !== "check") die(USAGE);
   let certPath = "", keysPath = "", online = false, apiUrl = "";
+  let requireCertified = false;
+  const systems: string[] = [];
+  const keyIds: string[] = [];
   for (let i = 1; i < args.length; i++) {
     const a = args[i]!;
     if (a === "--cert") { certPath = args[++i] ?? die("--cert requires a value\n"); }
@@ -51,9 +64,29 @@ function parseArgs(argv: string[]): {
     // buys nothing — but it is a published flag that scripts already pass, and
     // failing on an unknown flag would break them for no gain.
     else if (a === "--api-key") { void (args[++i] ?? die("--api-key requires a value\n")); }
+    // ADR-025. Opt-in: without these, authorization: none verifies as it always
+    // has. The Go CLI has no equivalent yet; these names are the proposal for it.
+    else if (a === "--require-certified") { requireCertified = true; }
+    else if (a === "--require-certified-system") {
+      systems.push(args[++i] ?? die("--require-certified-system requires a value\n"));
+    }
+    else if (a === "--customer-key-id") { keyIds.push(args[++i] ?? die("--customer-key-id requires a value\n")); }
     else die(`Unknown argument: ${a}\n`);
   }
   if (!certPath || !keysPath) die("Both --cert and --keys are required.\n");
+  // Every system, or these systems: asking for both is a mistake to name, not
+  // one to resolve silently in either direction.
+  if (requireCertified && systems.length > 0) {
+    die("--require-certified and --require-certified-system are alternatives; use one\n");
+  }
+  // Certified under a key id you did not name proves nothing to you: the relay
+  // can enroll a key group of its own, and the record would name that one.
+  if ((requireCertified || systems.length > 0) && keyIds.length === 0) {
+    die(
+      "--require-certified and --require-certified-system need --customer-key-id <id>: " +
+        "certified under a key you did not name proves nothing\n",
+    );
+  }
   if (online) {
     try {
       apiUrl = resolveApiBaseUrl(apiUrl, process.env);
@@ -61,7 +94,9 @@ function parseArgs(argv: string[]): {
       die((e as Error).message + "\n");
     }
   }
-  return { certPath, keysPath, online, apiUrl };
+  const policy: AuthorizationPolicy | undefined =
+    keyIds.length > 0 ? { ...(systems.length > 0 ? { systems } : {}), customerKeyIds: keyIds } : undefined;
+  return { certPath, keysPath, online, apiUrl, policy };
 }
 
 /** Flag first, then environment — the precedence docs/cli.md promises and the
@@ -86,8 +121,8 @@ export function resolveApiBaseUrl(
  * carries a signed statement — key_id == sha256(public_key) makes every
  * identity self-checking — so an unsigned file is not refused. What changes is
  * what this CLI is entitled to say about the statuses and dates. Mirrors
- * loadKeysFromFile in cmd/cli/keys.go. */
-async function loadKeys(path: string): Promise<{ keys: Map<string, PublicKeyInfo>; keyList: KeyListEvidence }> {
+ * loadKeysFromFile in cmd/cli/keys.go. Exported for testing. */
+export async function loadKeys(path: string): Promise<{ keys: Map<string, PublicKeyInfo>; keyList: KeyListEvidence }> {
   let entries: KeyEntry[];
   let keyList: KeyListEvidence;
   try {
@@ -154,59 +189,6 @@ async function fetchStatusStatement(apiUrl: string, certId: string): Promise<Sta
   return unwrapStatusStatement(await res.json());
 }
 
-/** The API wraps every response in {"data": ...}; a caller may hand over either
- * the envelope or the document inside it. Mirrors
- * core.ParseCertificateStatusDocument, so this CLI and the Go one cannot
- * disagree about which shape the endpoint returns. Exported for testing.
- *
- * A document that does not parse THROWS, and the caller turns that into a
- * warning and a VALID_REVOCATION_UNKNOWN verdict. That is deliberate: an answer
- * this build cannot read is silence about revocation, not a finding about the
- * certificate. Handing a half-read document to the verifier instead would
- * report "status statement signature is invalid" — a claim about the issuer —
- * when what actually happened is that something returned nonsense.
- *
- * `status` itself is NOT validated against a known set. A statement saying
- * SUSPENDED is a statement this build cannot read, and the verifier already has
- * the right answer for that: it authenticates the signature first, then reports
- * VALID_REVOCATION_UNKNOWN. Refusing it here would discard the statement before
- * anyone authenticated it. */
-export function unwrapStatusStatement(parsed: unknown): StatusStatement {
-  if (parsed === null || typeof parsed !== "object") {
-    throw new Error("status statement: response is not a JSON object");
-  }
-  let doc = parsed as StatusStatement;
-  if (doc.certificate_id === undefined && doc.data !== null && typeof doc.data === "object") {
-    doc = doc.data as StatusStatement;
-  }
-  for (const f of ["certificate_id", "status", "key_id"]) {
-    if (typeof doc[f] !== "string" || doc[f] === "") throw new Error(`status statement: ${f} is missing`);
-  }
-  for (const f of ["statement_issued_at", "statement_expires_at"]) requireRfc3339(doc, f);
-  if (doc.revoked_at != null) requireRfc3339(doc, "revoked_at");
-  if (typeof doc.sth_tree_size !== "number") throw new Error("status statement: sth_tree_size is not a number");
-  // Refuse a short or long value rather than letting it through: a truncated
-  // signature or root hash that reaches the verifier is checked against bytes
-  // nobody sent.
-  requireHex(doc, "sth_root_hash", 32);
-  requireHex(doc, "signature", 64);
-  return doc;
-}
-
-function requireRfc3339(doc: StatusStatement, field: string): void {
-  const v = doc[field];
-  if (typeof v !== "string" || Number.isNaN(Date.parse(v))) {
-    throw new Error(`status statement: ${field} is not RFC 3339`);
-  }
-}
-
-function requireHex(doc: StatusStatement, field: string, bytes: number): void {
-  const v = doc[field];
-  if (typeof v !== "string" || !new RegExp(`^[0-9a-fA-F]{${bytes * 2}}$`).test(v)) {
-    throw new Error(`status statement: ${field} is not ${bytes} bytes of hex`);
-  }
-}
-
 /** The verdicts a reader can act on, and therefore the ones that exit 0.
  *
  * VALID_REVOCATION_UNKNOWN is here. It is the verdict every offline run now
@@ -295,9 +277,41 @@ function signatureCoversEnclavePcr0(version: string): boolean {
   return ENCLAVE_PCR0_SIGNED_IN.includes(version);
 }
 
+/** Follows a system that attested zero records. The same words in all three CLIs. */
+const MATCHED_NOTHING_NOTE =
+  " — the query matched nothing here, so this record is no evidence " +
+  "about this system; if it should hold the subject, its query is wrong";
+
+/**
+ * Each system's own counts. The totals hide a system that matched nothing: 11
+ * records across two systems read the same whether both held some or one held
+ * all eleven and the other's query found nothing. A zero is a legitimate answer
+ * — the subject was simply not there — so it is stated, not refused. But a
+ * query that CANNOT match (a wrong column, a term query on an analyzed field)
+ * also reads zero, and then the record is no evidence about that system at
+ * all. Only the reader knows which, so the line says both.
+ */
+function pushRecordCounts(L: string[], sys: Record<string, unknown>[]): void {
+  for (const s of sys) {
+    const attested = s.attested_count as number;
+    L.push(
+      `  Records [${s.system_name as string}]: ${attested} at attestation, ` +
+        `${s.verified_count as number} after deletion` +
+        (attested === 0 ? MATCHED_NOTHING_NOTE : ""),
+    );
+  }
+}
+
 /**
- * Per system: did the enclave check it against a customer-signed registration,
- * and under which key?
+ * Per system: did the enclave check it against a registration, under which key,
+ * and what does the image that signed the record make of that?
+ *
+ * Printed for exactly the verdicts that say the record's own signature
+ * verified: VALID, VALID_REVOCATION_UNKNOWN, the two soft key verdicts and
+ * REVOKED, as in the Go and Python CLIs and the /verify page. The qualifier is
+ * read from issuer.enclave_pcr0, which that signature covers, and
+ * verifyCertificate checks it before any of those verdicts is reached. Beside
+ * INVALID the field is unverified bytes, so nothing is printed there.
  *
  * This line is the WHOLE POINT of the field. ADR-025 §2: the enclave cannot
  * refuse a second enrollment for a team — that needs durable state — so a parent
@@ -319,14 +333,11 @@ function pushRegistrationEvidence(L: string[], cert: Record<string, unknown>): v
     );
     return;
   }
+  const qualifier = registrationQualifier(issuingImage(cert));
   for (const sys of (cert.systems as Record<string, unknown>[]) ?? []) {
     const name = sys.system_name as string;
     if (sys.authorization === "certified") {
-      L.push(
-        `  Registration [${name}]: certified under ${sys.customer_key_id as string} — ` +
-          "the enclave checked this system against a customer-signed registration. " +
-          "If that key id is not yours, someone else authorized this verification.",
-      );
+      L.push(`  Registration [${name}]: certified under ${sys.customer_key_id as string} — ${qualifier}`);
     } else if (sys.authorization === "none") {
       L.push(
         `  Registration [${name}]: none — this verification was NOT checked against ` +
@@ -363,8 +374,9 @@ export function formatOutput(
   status: StatusStatement | undefined, online: boolean, anchor?: AnchorResult,
   keyList?: KeyListEvidence,
 ): string {
-  const id = (cert.certificate_id as string).slice(0, 6);
-  const sub = displayHash((cert.subject as Record<string, unknown>).identifier_hash);
+  // This line prints for records that FAILED verification too, so it must not
+  // assume the shape verification would have checked.
+  const id = typeof cert.certificate_id === "string" ? cert.certificate_id.slice(0, 6) : "unknown";
   const att = cert.attestation as Record<string, unknown>;
   const L: string[] = [];
 
@@ -382,22 +394,33 @@ export function formatOutput(
     return L.join("\n") + "\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`;
   // Revocation is now a signed fact, so the reader gets the evidence with the
   // verdict: who said it, when, and which log entry it points at.
   if (sigResult === REVOKED) {
     L.push(`Verification record dc_${id}: INVALID (REVOKED)`);
+    pushRegistrationEvidence(L, cert);
     pushStatementEvidence(L, status);
     pushAnchorEvidence(L, anchor);
     return L.join("\n") + "\n";
   }
-  if (!USABLE_VERDICTS.has(sigResult)) return `Verification record dc_${id}: INVALID (${sigResult})\n`;
+  const note = SOFT_KEY_VERDICTS[sigResult];
+  if (!USABLE_VERDICTS.has(sigResult) && note === undefined) {
+    return `Verification record dc_${id}: INVALID (${sigResult})\n`;
+  }
+  // A failed proof refuses the record, and it outranks a soft key verdict: a
+  // verdict that asks for a human must not hide one that refuses. The Python
+  // CLI and the /verify page already put it first; this CLI and Go printed
+  // the soft verdict instead.
   if (transparencyFailed) return `Verification record 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.
+  if (note !== undefined) {
+    L.push(`Verification record dc_${id}: ${sigResult} (${note})`);
+    pushRegistrationEvidence(L, cert);
+    return L.join("\n") + "\n";
+  }
 
   // The two usable verdicts. VALID is sayable without a qualifier for the first
   // time: it is reached only when a fresh statement, signed by a key from the
@@ -408,6 +431,7 @@ export function formatOutput(
     ? `${VALID_REVOCATION_UNKNOWN} (${online ? REVOCATION_UNKNOWN_ONLINE : REVOCATION_UNKNOWN_OFFLINE})`
     : "VALID (a signed status statement says this record is live)";
   L.push(`Verification record dc_${id}: ${tag}`);
+  const sub = displayHash((cert.subject as Record<string, unknown>).identifier_hash);
   L.push(`  Subject: sha256:${sub.slice(0, 6)}...`);
   L.push(`  Format version: ${cert.certificate_format_version as string}`);
 
@@ -420,6 +444,7 @@ export function formatOutput(
   L.push(`  Systems: ${sys.length} (${sys.map((s) => `${s.connector_type} [${s.hash_scope}]`).join(", ")})`);
   L.push(`  Records before: ${sys.reduce((n, s) => n + (s.attested_count as number), 0)}`);
   L.push(`  Records after: ${sys.reduce((n, s) => n + (s.verified_count as number), 0)}`);
+  pushRecordCounts(L, sys);
   L.push(`  Committed: ${att.attested_at as string}`);
   L.push(`  Verified: ${sys.reduce((t, s) => {
     const v = s.verified_at as string;
@@ -557,7 +582,13 @@ export function unwrapCertificate(parsed: Cert): Cert {
 
 async function main(): Promise<void> {
   const args = parseArgs(process.argv);
-  const cert = unwrapCertificate(JSON.parse(await readFile(args.certPath, "utf-8")) as Cert);
+  const parsed: unknown = JSON.parse(await readFile(args.certPath, "utf-8"));
+  // No record to give a verdict about. Go's loader refuses the same file at
+  // unmarshal and exits 2, as this does.
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    die(`${args.certPath}: not a JSON object\n`);
+  }
+  const cert = unwrapCertificate(parsed as Cert);
   const { keys, keyList } = await loadKeys(args.keysPath);
 
   // Fetched first, because the verdict now depends on it. A status statement is
@@ -597,11 +628,19 @@ async function main(): Promise<void> {
   // and VALID_KEY_COMPROMISED_LATER are cases verifyCertificateWithStatus
   // deliberately refused to call VALID, and this is the tool an auditor runs in
   // a script — the one whose exit code gets trusted.
+  //
+  // Only a VerificationError is a verdict. Anything else is a defect in this
+  // CLI or the SDK under it; printing it as INVALID dressed a crash up as a
+  // finding about the record, so it propagates and exits 2 instead.
   let sigResult = "VALID";
-  try { sigResult = await verifyCertificateWithStatus(nodeCrypto, cert, keys, status ?? null); }
+  try {
+    sigResult = await verifyCertificateWithStatus(nodeCrypto, cert, keys, status ?? null, undefined, {
+      requireAuthorization: args.policy,
+    });
+  }
   catch (e) {
-    if (e instanceof VerificationError && e.code === CERTIFICATE_REVOKED) sigResult = REVOKED;
-    else sigResult = e instanceof Error ? e.message : "unknown error";
+    if (!(e instanceof VerificationError)) throw e;
+    sigResult = e.code === CERTIFICATE_REVOKED ? REVOKED : e.message;
   }
 
   // NOT_AVAILABLE (no proof) is a legitimate result; only a thrown error is a
@@ -609,7 +648,11 @@ async function main(): Promise<void> {
   let transparency = "NOT_AVAILABLE";
   let transparencyFailed = false;
   try { transparency = await verifyTransparency(nodeCrypto, cert, keys); }
-  catch (e) { transparency = e instanceof Error ? e.message : "unknown error"; transparencyFailed = true; }
+  catch (e) {
+    if (!(e instanceof VerificationError)) throw e;
+    transparency = e.message;
+    transparencyFailed = true;
+  }
 
   const valid = certVerdict(sigResult, transparencyFailed, anchor);
 

package/src/client.ts

@@ -48,7 +48,14 @@ import {
   parseWebhookDelivery,
   parseWebhookRotateResponse,
 } from "./models.js";
+import type { KeyEnrollmentResult, SystemRegistrationCertificate } from "./models.js";
 import { Paginator } from "./pagination.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 +109,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 +126,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,
@@ -458,6 +476,172 @@ 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 flow = await import("./enclave-registration.js");
+    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 flow = await import("./enclave-registration.js");
+    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 flow = await import("./enclave-registration.js");
+    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 flow = await import("./enclave-registration.js");
+    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 flow = await import("./enclave-registration.js");
+    const { sealToKey } = await import("./enclave-seal.js");
+    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 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> {
@@ -532,6 +716,14 @@ export class BurnLedger {
 // Connection config resolution
 // ---------------------------------------------------------------------------
 
+/** 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,