burnledger 0.8.0 → 0.8.1

package/src/cli.ts

@@ -295,6 +295,31 @@ 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?
@@ -420,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;

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

@@ -811,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));
 }