burnledger 0.7.0 → 0.8.1

package/src/cli.ts

@@ -12,6 +12,7 @@ import {
   publicKeyFromHex,
   verifyCertificateWithStatus,
   verifyTransparency,
+  KNOWN_FORMAT_VERSIONS,
   VALID_REVOCATION_UNKNOWN,
 } from "./verify.js";
 import {
@@ -288,12 +289,92 @@ const REVOCATION_UNKNOWN_ONLINE =
  * enclave measurement was unattributable when the signature covers it.
  * scripts/check-pcr0-signed-parity.py now pins this list to the Go function.
  */
-const ENCLAVE_PCR0_SIGNED_IN: readonly string[] = Object.freeze(["5.0", "6.0", "7.0", "8.0"]);
+const ENCLAVE_PCR0_SIGNED_IN: readonly string[] = Object.freeze(["5.0", "6.0", "7.0", "8.0", "9.0"]);
 
 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?
+ *
+ * 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
+ * can enroll a key of its own. What stops that being useful is that the record
+ * names the key id and the customer sees a key they do not hold. A verifier that
+ * reads the field and never shows it removes the only place that happens.
+ *
+ * Absence is stated rather than left silent. Records issued before 9.0 carry no
+ * field, and ADR-025 is explicit that their absence means "issued before this
+ * existed", never a pass — a blank where a control should be is exactly how a
+ * reader concludes the control ran.
+ */
+function pushRegistrationEvidence(L: string[], cert: Record<string, unknown>): void {
+  const version = cert.certificate_format_version as string;
+  if (!KNOWN_FORMAT_VERSIONS.includes(version) || !formatAtLeastV9(version)) {
+    L.push(
+      `  Registration: not stated (format ${version} predates the field; ` +
+        "its absence is not a pass)",
+    );
+    return;
+  }
+  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.",
+      );
+    } else if (sys.authorization === "none") {
+      L.push(
+        `  Registration [${name}]: none — this verification was NOT checked against ` +
+          "a customer-signed registration.",
+      );
+    } else {
+      // Unreachable through verifyCertificate, which rebuilds the payload and
+      // refuses an unrecognized value. Printed rather than skipped because a
+      // caller that formatted a record it never verified must not be handed a
+      // blank where a control belongs.
+      L.push(
+        `  Registration [${name}]: unreadable (${JSON.stringify(sys.authorization ?? null)} ` +
+          "is not a value this build knows)",
+      );
+    }
+  }
+}
+
+/** Mirrors core.FormatAtLeast for 9.0, by POSITION: "10.0" sorts before "7.0". */
+function formatAtLeastV9(version: string): boolean {
+  return KNOWN_FORMAT_VERSIONS.indexOf(version) >= KNOWN_FORMAT_VERSIONS.indexOf("9.0");
+}
+
 /** Byte fields arrive as number arrays (Go [N]byte) or strings; show hex. */
 function displayHash(v: unknown): string {
   if (Array.isArray(v)) {
@@ -364,6 +445,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;
@@ -393,6 +475,8 @@ export function formatOutput(
     }
   }
 
+  pushRegistrationEvidence(L, cert);
+
   if (transparency === "INCLUDED") {
     const t = cert.transparency as Record<string, unknown>;
     L.push(`  Transparency log: entry #${t.entry_index as number}, inclusion proof VALID`);

package/src/customer-keys.ts

@@ -0,0 +1,180 @@
+/**
+ * Customer key groups (ADR-025 §2), computed on the customer's own machine.
+ *
+ * WHY THIS IS CLIENT-SIDE AND NOT AN API CALL. The private halves never leave
+ * the customer's machines -- that is the entire point of the mechanism. What a
+ * customer needs from us is not a service that computes their key id, but the
+ * ability to compute it themselves and compare it against the id the enclave
+ * signed. An id returned over HTTP would be an id the parent could choose, and
+ * the one comparison this design rests on would be checking our answer against
+ * our answer.
+ *
+ * WHY IT MUST MATCH GO EXACTLY. `customer_key_id` is derived independently by
+ * the enclave and by the customer. If the two derivations disagree by so much
+ * as a JSON separator, enrollment SUCCEEDS, the enclave signs a statement
+ * naming an id, and the customer's comparison fails -- indistinguishable, from
+ * where they are standing, from a parent having substituted their key. Every
+ * expectation in tests/customer-key-parity.test.ts comes from a corpus the Go
+ * generator writes by calling core itself.
+ */
+
+import { canonicalJson } from "./verify.js";
+import type { CryptoOps } from "./crypto.js";
+
+/**
+ * Mirrors core.CustomerKeyIDPrefix. It distinguishes a customer's key id from
+ * an issuer key id, which are otherwise the same shape and would be confusable
+ * in a log line at exactly the wrong moment.
+ */
+export const CUSTOMER_KEY_ID_PREFIX = "cust_k_";
+
+/**
+ * Mirrors core.payloadTypeCustomerKeyGroup. Unexported in Go because it is
+ * never signed or transmitted -- only hashed -- but it IS inside the hash, so a
+ * reimplementation that omits it computes a different id for every group.
+ */
+const PAYLOAD_TYPE_CUSTOMER_KEY_GROUP = "burnledger.customer_key_group.v1";
+
+export const PAYLOAD_TYPE_KEY_ROTATION_REQUEST = "burnledger.key_rotation_request.v1";
+
+/** Mirrors core.MaxCustomerKeyGroupMembers. */
+export const MAX_CUSTOMER_KEY_GROUP_MEMBERS = 16;
+
+const ED25519_PUBLIC_KEY_SIZE = 32;
+
+/** A group that cannot be enrolled, for a reason stated in the message. */
+export class InvalidKeyGroupError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidKeyGroupError";
+  }
+}
+
+export interface CustomerKeyGroup {
+  /** How many distinct members must sign. 1 <= threshold <= members.length. */
+  threshold: number;
+  /**
+   * The enrolled public keys. Order is not significant: the id sorts the
+   * fingerprints, so two customers who list the same keys in a different order
+   * enrol the same group rather than two indistinguishable ones.
+   */
+  members: Uint8Array[];
+}
+
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** hex(SHA-256(public key)) -- a member's identity inside a group. */
+export async function memberFingerprint(
+  crypto: CryptoOps,
+  publicKey: Uint8Array,
+): Promise<string> {
+  return toHex(await crypto.sha256(publicKey));
+}
+
+/** Throws InvalidKeyGroupError unless this group could ever be used. */
+export async function validateKeyGroup(
+  crypto: CryptoOps,
+  group: CustomerKeyGroup,
+): Promise<void> {
+  if (group.members.length === 0) {
+    throw new InvalidKeyGroupError("a customer key group needs at least one member");
+  }
+  if (group.members.length > MAX_CUSTOMER_KEY_GROUP_MEMBERS) {
+    throw new InvalidKeyGroupError(
+      `a customer key group may have at most ${MAX_CUSTOMER_KEY_GROUP_MEMBERS} members, ` +
+        `got ${group.members.length}`,
+    );
+  }
+  if (
+    !Number.isInteger(group.threshold) ||
+    group.threshold < 1 ||
+    group.threshold > group.members.length
+  ) {
+    throw new InvalidKeyGroupError(
+      `threshold ${group.threshold} is not between 1 and the ${group.members.length} members`,
+    );
+  }
+  const seen = new Set<string>();
+  for (const member of group.members) {
+    if (member.length !== ED25519_PUBLIC_KEY_SIZE) {
+      throw new InvalidKeyGroupError(
+        `every member must be a ${ED25519_PUBLIC_KEY_SIZE}-byte Ed25519 key`,
+      );
+    }
+    const fingerprint = await memberFingerprint(crypto, member);
+    if (seen.has(fingerprint)) {
+      // A repeated member would let one holder satisfy a threshold meant to
+      // require several, which is the entire point of one.
+      throw new InvalidKeyGroupError("the same member key is listed twice");
+    }
+    seen.add(fingerprint);
+  }
+}
+
+/** The members' fingerprints, sorted, so the id does not depend on order. */
+export async function memberFingerprints(
+  crypto: CryptoOps,
+  group: CustomerKeyGroup,
+): Promise<string[]> {
+  const out: string[] = [];
+  for (const member of group.members) {
+    out.push(await memberFingerprint(crypto, member));
+  }
+  return out.sort();
+}
+
+/**
+ * The id the enclave will compute for this group.
+ *
+ * Throws rather than returning an id for a group that could never be enrolled:
+ * an id for an unusable group is a value a caller would go on to compare
+ * against, and it would never match anything.
+ */
+export async function customerKeyId(
+  crypto: CryptoOps,
+  group: CustomerKeyGroup,
+): Promise<string> {
+  await validateKeyGroup(crypto, group);
+  const document = {
+    member_key_ids: await memberFingerprints(crypto, group),
+    payload_type: PAYLOAD_TYPE_CUSTOMER_KEY_GROUP,
+    threshold: group.threshold,
+  };
+  return CUSTOMER_KEY_ID_PREFIX + toHex(await crypto.sha256(canonicalJson(document)));
+}
+
+/**
+ * The canonical bytes the OUTGOING group's members sign to authorise a rotation.
+ *
+ * This is the only payload in the scheme signed by the customer rather than by
+ * the enclave, so it is the only one where a signature captured elsewhere could
+ * be replayed into the mechanism -- hence its own payload type.
+ *
+ * Both ids are bound, not just the successor: a statement naming only the
+ * incoming key could be lifted onto a different predecessor, re-presenting the
+ * same signatures as though another group had approved it.
+ */
+export function buildKeyRotationRequestPayload(request: {
+  assertedTeamId: string;
+  prevKeyId: string;
+  nextKeyId: string;
+}): Uint8Array {
+  if (!request.prevKeyId || !request.nextKeyId) {
+    throw new Error("a rotation request names both the key being replaced and its replacement");
+  }
+  if (request.prevKeyId === request.nextKeyId) {
+    // A self-rotation is a cycle in the chain the enclave walks, and it walks
+    // without a visited set.
+    throw new Error(
+      "a rotation request cannot name the same key as both predecessor and successor",
+    );
+  }
+  return canonicalJson({
+    asserted_team_id: request.assertedTeamId,
+    next_key_id: request.nextKeyId,
+    payload_type: PAYLOAD_TYPE_KEY_ROTATION_REQUEST,
+    prev_key_id: request.prevKeyId,
+  });
+}

package/src/index.ts

@@ -165,3 +165,16 @@ export {
   verifyEnclaveConfigSealKey,
 } from "./enclave-seal.js";
 export type { SealOptions } from "./enclave-seal.js";
+
+export {
+  CUSTOMER_KEY_ID_PREFIX,
+  InvalidKeyGroupError,
+  MAX_CUSTOMER_KEY_GROUP_MEMBERS,
+  PAYLOAD_TYPE_KEY_ROTATION_REQUEST,
+  buildKeyRotationRequestPayload,
+  customerKeyId,
+  memberFingerprint,
+  memberFingerprints,
+  validateKeyGroup,
+} from "./customer-keys.js";
+export type { CustomerKeyGroup } from "./customer-keys.js";

package/src/verify.ts

@@ -73,6 +73,19 @@ const FORMAT_VERSION_V7 = "7.0";
 const PAYLOAD_TYPE_ATTESTATION_V8 = "burnledger.attestation.v8";
 const PAYLOAD_TYPE_VERIFICATION_RECORD_V8 = "burnledger.verification_record.v8";
 const FORMAT_VERSION_V8 = "8.0";
+// v9 adds two per-system fields, authorization and customer_key_id: whether the
+// enclave checked this system against a customer-signed registration
+// certificate (ADR-025 §4), and under which customer key group if it did.
+//
+// The attestation gains NO field at v9. Its tag still moves, because the tag
+// follows the record's version and the record's bytes changed — a v9
+// attestation rebuilt under burnledger.attestation.v8 is a different preimage.
+//
+// READ-ONLY IN THIS BUILD, mirroring core, for the same runbook-invariant-5
+// reason spelled out for v8 above.
+const PAYLOAD_TYPE_ATTESTATION_V9 = "burnledger.attestation.v9";
+const PAYLOAD_TYPE_VERIFICATION_RECORD_V9 = "burnledger.verification_record.v9";
+const FORMAT_VERSION_V9 = "9.0";
 const FORMAT_VERSION_V3 = "3.0";
 
 /**
@@ -99,6 +112,7 @@ export const KNOWN_FORMAT_VERSIONS: readonly string[] = Object.freeze([
   FORMAT_VERSION_V6,
   FORMAT_VERSION_V7,
   FORMAT_VERSION_V8,
+  FORMAT_VERSION_V9,
 ]);
 
 /**
@@ -165,6 +179,64 @@ function signatureCoversRecoverableState(version: string): boolean {
   return formatAtLeast(version, FORMAT_VERSION_V8);
 }
 
+/**
+ * Does this format sign the per-system authorization and customer_key_id?
+ *
+ * v9 onward. `authorization` is always present on a v9 record; `customer_key_id`
+ * only when it is certified, and OMITTED rather than empty when it is not — a
+ * key id of "" would sign as a value, and a reader comparing against their own
+ * key id must not have to know that "" means "nobody".
+ */
+function signatureCoversAuthorization(version: string): boolean {
+  return formatAtLeast(version, FORMAT_VERSION_V9);
+}
+
+/** The two values a v9 record's per-system authorization may take. */
+const AUTHORIZATION_CERTIFIED = "certified";
+const AUTHORIZATION_NONE = "none";
+
+/**
+ * Read a v9 system's authorization and key id, refusing what core refuses.
+ *
+ * Port of checkAuthorization in core/payload.go. It runs on the VERIFY side
+ * too, and must: an unset or unrecognized value is not something to rebuild
+ * bytes from and report as a bad signature — the record is malformed. The two
+ * refused combinations are the ones that would be a lie rather than a shape
+ * error: certified naming nobody is ADR-025 §2's second-key attack with the
+ * evidence removed, and none naming somebody claims an authority that was
+ * never checked.
+ */
+function requireAuthorization(
+  s: Record<string, unknown>,
+  systemName: unknown,
+): { authorization: string; customerKeyId: string } {
+  const a = s.authorization;
+  if (a !== AUTHORIZATION_CERTIFIED && a !== AUTHORIZATION_NONE) {
+    throw new VerificationError(
+      `system ${JSON.stringify(systemName)}: authorization is ${JSON.stringify(a ?? null)}, ` +
+        `which format ${FORMAT_VERSION_V9} requires to be one of certified, none`,
+    );
+  }
+  const raw = s.customer_key_id;
+  if (raw !== undefined && raw !== null && typeof raw !== "string") {
+    throw new VerificationError(
+      `system ${JSON.stringify(systemName)}: customer_key_id is not a string`,
+    );
+  }
+  const customerKeyId = typeof raw === "string" ? raw : "";
+  if (a === AUTHORIZATION_CERTIFIED && customerKeyId === "") {
+    throw new VerificationError(
+      `system ${JSON.stringify(systemName)}: authorization is certified but customer_key_id is empty`,
+    );
+  }
+  if (a === AUTHORIZATION_NONE && customerKeyId !== "") {
+    throw new VerificationError(
+      `system ${JSON.stringify(systemName)}: authorization is none but customer_key_id is set`,
+    );
+  }
+  return { authorization: a, customerKeyId };
+}
+
 const PAYLOAD_TYPE_TREE_HEAD = "burnledger.sth.v3";
 // The domain for a tree head that names its log. See buildTreeHeadPayload.
 const PAYLOAD_TYPE_TREE_HEAD_V7 = "burnledger.sth.v7";
@@ -739,7 +811,10 @@ export function issuanceBytes(certificate: Cert): Uint8Array {
 // RFC 8785 Canonical JSON
 // ---------------------------------------------------------------------------
 
-function canonicalJson(obj: unknown): Uint8Array {
+/** Exported for tests/verify.test.ts, which keeps a second implementation of
+ * this and must be able to prove the two agree. Not re-exported from index.ts,
+ * so it stays off the published API. */
+export function canonicalJson(obj: unknown): Uint8Array {
   return textToBytes(canonicalStringify(obj));
 }
 
@@ -1057,6 +1132,7 @@ function requireMeasured(
 /** Domain separator for the record itself, by certificate format version. */
 function certificatePayloadType(version: string): string {
   checkFormatVersion(version);
+  if (version === FORMAT_VERSION_V9) return PAYLOAD_TYPE_VERIFICATION_RECORD_V9;
   if (version === FORMAT_VERSION_V8) return PAYLOAD_TYPE_VERIFICATION_RECORD_V8;
   if (version === FORMAT_VERSION_V7) return PAYLOAD_TYPE_VERIFICATION_RECORD_V7;
   if (version === FORMAT_VERSION_V6) return PAYLOAD_TYPE_VERIFICATION_RECORD_V6;
@@ -1076,6 +1152,7 @@ function attestationPayloadType(version: string): string {
   // Equality here, deliberately: each format has its OWN separator, so this is
   // a lookup rather than a "this version onward" question. v3 and v4 share one
   // because their attestation bytes are identical.
+  if (version === FORMAT_VERSION_V9) return PAYLOAD_TYPE_ATTESTATION_V9;
   if (version === FORMAT_VERSION_V8) return PAYLOAD_TYPE_ATTESTATION_V8;
   if (version === FORMAT_VERSION_V7) return PAYLOAD_TYPE_ATTESTATION_V7;
   if (version === FORMAT_VERSION_V6) return PAYLOAD_TYPE_ATTESTATION_V6;
@@ -1094,6 +1171,7 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   const version = cert.certificate_format_version as string;
   const coversMeasured = signatureCoversMeasuredTransport(version);
   const coversRecoverable = signatureCoversRecoverableState(version);
+  const coversAuthorization = signatureCoversAuthorization(version);
   const systems = ((cert.systems as Record<string, unknown>[]) ?? []).map((s) => {
     const sys: Record<string, unknown> = {
       attested_at: formatTimestamp(s.attested_at),
@@ -1130,6 +1208,11 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
         version,
       );
     }
+    if (coversAuthorization) {
+      const { authorization, customerKeyId } = requireAuthorization(s, s.system_name);
+      sys.authorization = authorization;
+      if (customerKeyId !== "") sys.customer_key_id = customerKeyId;
+    }
     return sys;
   });
 

package/src/web-verifier.ts

@@ -29,6 +29,7 @@ import {
   verifyCertificateWithStatus as _verifyCertificateWithStatus,
   verifyTransparency as _verifyTransparency,
   publicKeyFromHex as _publicKeyFromHex,
+  KNOWN_FORMAT_VERSIONS,
 } from "./verify.js";
 import type { PublicKeyInfo, PublicKeyOptions } from "./verify.js";
 import { parseKeyListDocument, verifyKeyList as _verifyKeyList } from "./keys.js";
@@ -87,6 +88,19 @@ export function checkStatementAnchor(
 
 export { ANCHOR_CONFIRMED, ANCHOR_INCONSISTENT, ANCHOR_UNVERIFIED };
 
+/**
+ * Every record format this bundle can read, oldest first.
+ *
+ * The page needs it to answer "does this record's format predate a field?" —
+ * the registration row asks exactly that. Exported rather than restated in
+ * verify.js, because a hand-kept copy of this list going stale is the defect
+ * scripts/check-pcr0-signed-parity.py exists because of.
+ *
+ * ORDER IS LOAD-BEARING: "this format or newer" is answered by POSITION, never
+ * by comparing the strings, because "10.0" sorts before "7.0".
+ */
+export { KNOWN_FORMAT_VERSIONS };
+
 /** Verify the transparency proof embedded in a certificate. */
 export function verifyTransparency(
   certificate: Cert,