burnledger 0.6.1 → 0.8.0

package/src/verify.ts

@@ -61,6 +61,31 @@ const FORMAT_VERSION_V6 = "6.0";
 const PAYLOAD_TYPE_ATTESTATION_V7 = "burnledger.attestation.v7";
 const PAYLOAD_TYPE_VERIFICATION_RECORD_V7 = "burnledger.verification_record.v7";
 const FORMAT_VERSION_V7 = "7.0";
+// v8 adds one per-system field, recoverable_state: whether anything checked for
+// a restorable copy of what the record certifies gone. Its tags move for the
+// reason every earlier version's did, and this time the bytes under them differ
+// by that field. Everything v7 signs, v8 still signs.
+//
+// READ-ONLY IN THIS BUILD, mirroring core: nothing here issues a v8 record. A
+// verifier that can read a format has to ship BEFORE anything signs one, or a
+// genuine record reaches a holder whose SDK rebuilds it under the wrong domain
+// and reports a forgery (runbook invariant 5).
+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";
 
 /**
@@ -86,6 +111,8 @@ export const KNOWN_FORMAT_VERSIONS: readonly string[] = Object.freeze([
   FORMAT_VERSION_V5,
   FORMAT_VERSION_V6,
   FORMAT_VERSION_V7,
+  FORMAT_VERSION_V8,
+  FORMAT_VERSION_V9,
 ]);
 
 /**
@@ -106,6 +133,110 @@ function checkFormatVersion(version: unknown): string {
   }
   return version;
 }
+
+/**
+ * Is `version` the same format as `floor`, or a later one?
+ *
+ * Ordered by position in KNOWN_FORMAT_VERSIONS, never by string comparison:
+ * "10.0" sorts before "9.0". Port of core.formatAtLeast, and it exists for the
+ * reason the Go one does — four gates there were written as `v === "7.0"`, read
+ * by everyone as "7.0 and later", and behaved as "7.0 only". Three were live
+ * defects and one silently downgraded a security property the day v8 was
+ * defined.
+ *
+ * USE THIS, not equality, whenever the question is "does this format sign X".
+ * An unknown version answers false for every floor, which is safe only because
+ * checkFormatVersion has already refused it before any payload is rebuilt.
+ */
+function formatAtLeast(version: string, floor: string): boolean {
+  const vi = KNOWN_FORMAT_VERSIONS.indexOf(version);
+  const fi = KNOWN_FORMAT_VERSIONS.indexOf(floor);
+  return vi >= 0 && fi >= 0 && vi >= fi;
+}
+
+/** Ports of the core.SignatureCovers* predicates, one per signed field group. */
+function signatureCoversEnclavePcr0(version: string): boolean {
+  return formatAtLeast(version, FORMAT_VERSION_V5);
+}
+
+function signatureCoversAlgorithm(version: string): boolean {
+  return formatAtLeast(version, FORMAT_VERSION_V7);
+}
+
+function signatureCoversMeasuredTransport(version: string): boolean {
+  return formatAtLeast(version, FORMAT_VERSION_V7);
+}
+
+/**
+ * Does this format sign the per-system recoverable_state?
+ *
+ * v8 only, and everything after it. Emitting the field for v7 or older would
+ * rebuild bytes no signer ever produced and reject every record already issued;
+ * omitting it for v8 rebuilds a v7-shaped subset and reports a genuine v8
+ * record as forged.
+ */
+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";
@@ -446,8 +577,9 @@ export async function verifyCertificate(
   // Step 0b: can this SDK check the algorithm the record names? Asked before
   // any signature, because verifying an Ed25519 signature over a record that
   // says it was signed with something else answers a question nobody asked.
-  // Below v7 no record names one, so there is nothing to check.
-  if (formatVersion === FORMAT_VERSION_V7 && issuer.algorithm !== ALGORITHM_ED25519) {
+  // Below v7 no record names one, so there is nothing to check; from v7 on
+  // every record does, which is why this asks "v7 or later" rather than "v7".
+  if (signatureCoversAlgorithm(formatVersion) && issuer.algorithm !== ALGORITHM_ED25519) {
     throw new VerificationError(
       `record names signature algorithm ${JSON.stringify(issuer.algorithm)}; ` +
         `this version of the SDK verifies ${ALGORITHM_ED25519}. ` +
@@ -906,10 +1038,16 @@ function buildAttestationPayload(
   certFormatVersion: string,
 ): Uint8Array {
   const attestedAt = formatTimestamp(att.attested_at);
-  // v7 signs two per-system measurements v6 leaves on a mutable row. Gated on
-  // the record's OWN version: emitting them for an older format would rebuild
-  // bytes no signer ever produced and reject every record already issued.
-  const isV7 = certFormatVersion === FORMAT_VERSION_V7;
+  // v7 signs two per-system measurements v6 leaves on a mutable row, and v8
+  // adds recoverable_state beside them. Both gated on the record's OWN version:
+  // emitting a field for an older format would rebuild bytes no signer ever
+  // produced and reject every record already issued.
+  //
+  // Predicates, not equalities. v8 signs everything v7 signs, so a `=== "7.0"`
+  // here would drop read_only_enforcement and transport_security out of a v8
+  // payload and call every genuine v8 record a forgery.
+  const coversMeasured = signatureCoversMeasuredTransport(certFormatVersion);
+  const coversRecoverable = signatureCoversRecoverableState(certFormatVersion);
   const systems = (att.systems as Record<string, unknown>[]).map((s) => {
     const sys: Record<string, unknown> = {
       canonical_version: (s.canonical_version as string | null) ?? null,
@@ -925,16 +1063,26 @@ function buildAttestationPayload(
       system_id: s.system_id as string,
       system_name: s.system_name as string,
     };
-    if (isV7) {
+    if (coversMeasured) {
       sys.read_only_enforcement = requireMeasured(
         s.read_only_enforcement,
         "read_only_enforcement",
         s.system_name,
+        certFormatVersion,
       );
       sys.transport_security = requireMeasured(
         s.transport_security,
         "transport_security",
         s.system_name,
+        certFormatVersion,
+      );
+    }
+    if (coversRecoverable) {
+      sys.recoverable_state = requireMeasured(
+        s.recoverable_state,
+        "recoverable_state",
+        s.system_name,
+        certFormatVersion,
       );
     }
     return sys;
@@ -951,18 +1099,27 @@ function buildAttestationPayload(
 }
 
 /**
- * Read a v7 measured field that MUST be a non-empty string.
+ * Read a signed measured field that MUST be a non-empty string.
  *
  * A missing or non-string value cannot be turned into `""` and canonicalized:
  * the signer never emits an empty measurement, so an empty one here would
  * rebuild bytes no signature covers and be reported as forgery. Refusing with a
  * document-shape message says the true thing — this record is malformed, not
  * this record is fake.
+ *
+ * The version is passed in rather than written into the message: it was the
+ * literal "7.0" here, which would have told the holder of an incomplete v8
+ * record that their v8 document was a v7 one.
  */
-function requireMeasured(value: unknown, field: string, systemName: unknown): string {
+function requireMeasured(
+  value: unknown,
+  field: string,
+  systemName: unknown,
+  version: string,
+): string {
   if (typeof value !== "string" || value === "") {
     throw new VerificationError(
-      `system ${JSON.stringify(systemName)}: ${field} is missing from a 7.0 record, ` +
+      `system ${JSON.stringify(systemName)}: ${field} is missing from a ${version} record, ` +
         "which signs it; the document is incomplete rather than unverifiable",
     );
   }
@@ -972,6 +1129,8 @@ function requireMeasured(value: unknown, field: string, systemName: unknown): st
 /** 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;
   if (version === FORMAT_VERSION_V5) return PAYLOAD_TYPE_CERTIFICATE_V5;
@@ -987,6 +1146,11 @@ function certificatePayloadType(version: string): string {
  */
 function attestationPayloadType(version: string): string {
   checkFormatVersion(version);
+  // 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;
   if (version === FORMAT_VERSION_V5) return PAYLOAD_TYPE_ATTESTATION_V5;
@@ -1002,7 +1166,9 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // and a verification list joined only on the human-editable system_name,
   // which made a partial deletion indistinguishable from a complete one.
   const version = cert.certificate_format_version as string;
-  const isV7 = version === FORMAT_VERSION_V7;
+  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),
@@ -1017,18 +1183,33 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
       verified_at: formatTimestamp(s.verified_at),
       verified_count: s.verified_count as number,
     };
-    if (isV7) {
+    if (coversMeasured) {
       sys.read_only_enforcement = requireMeasured(
         s.read_only_enforcement,
         "read_only_enforcement",
         s.system_name,
+        version,
       );
       sys.transport_security = requireMeasured(
         s.transport_security,
         "transport_security",
         s.system_name,
+        version,
+      );
+    }
+    if (coversRecoverable) {
+      sys.recoverable_state = requireMeasured(
+        s.recoverable_state,
+        "recoverable_state",
+        s.system_name,
+        version,
       );
     }
+    if (coversAuthorization) {
+      const { authorization, customerKeyId } = requireAuthorization(s, s.system_name);
+      sys.authorization = authorization;
+      if (customerKeyId !== "") sys.customer_key_id = customerKeyId;
+    }
     return sys;
   });
 
@@ -1043,12 +1224,12 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // Fields added after v3 are gated on the certificate's OWN version. A v3
   // certificate must reconstruct to the same bytes forever; reading these
   // unconditionally would break every certificate already issued.
-  // v6 carries v5's shape exactly, so it takes every gate v5 takes. Naming
-  // these "Plus" rather than testing equality at each use is what stops a new
-  // version from silently missing one.
-  const isV5Plus =
-    version === FORMAT_VERSION_V5 || version === FORMAT_VERSION_V6 || isV7;
-  const isV4Plus = version === FORMAT_VERSION_V4 || isV5Plus;
+  // v6 carries v5's shape exactly, so it takes every gate v5 takes. Asking
+  // "this version onward" rather than listing versions at each use is what
+  // stops a new format from silently missing one: these were a chain of
+  // equalities that had to be extended by hand for v6, then v7, then v8.
+  const isV5Plus = formatAtLeast(version, FORMAT_VERSION_V5);
+  const isV4Plus = formatAtLeast(version, FORMAT_VERSION_V4);
 
   const issuerObj: Record<string, unknown> = {
     key_id: issuer.key_id as string,
@@ -1058,15 +1239,24 @@ function buildCertificatePayload(cert: Record<string, unknown>): Uint8Array {
   // v7 signs the algorithm, and does so unconditionally: unlike legal_entity
   // and enclave_pcr0, "which scheme signed this" is never unknown to a signer,
   // so a v7 record missing it is malformed rather than merely sparse.
-  if (isV7) {
-    issuerObj.algorithm = requireMeasured(issuer.algorithm, "issuer.algorithm", "issuer");
+  if (signatureCoversAlgorithm(version)) {
+    issuerObj.algorithm = requireMeasured(
+      issuer.algorithm,
+      "issuer.algorithm",
+      "issuer",
+      version,
+    );
   }
   if (isV4Plus && typeof issuer.legal_entity === "string" && issuer.legal_entity !== "") {
     issuerObj.legal_entity = issuer.legal_entity;
   }
   // Signed from v5, and omitted when absent or empty: a build with no
   // measurement signs none, and "" is a value a reader could mistake for one.
-  if (isV5Plus && typeof issuer.enclave_pcr0 === "string" && issuer.enclave_pcr0 !== "") {
+  if (
+    signatureCoversEnclavePcr0(version) &&
+    typeof issuer.enclave_pcr0 === "string" &&
+    issuer.enclave_pcr0 !== ""
+  ) {
     issuerObj.enclave_pcr0 = issuer.enclave_pcr0;
   }
 
@@ -1144,6 +1334,10 @@ function attestationSystems(cert: Record<string, unknown>): Record<string, unkno
     // reads them.
     read_only_enforcement: s.read_only_enforcement,
     transport_security: s.transport_security,
+    // Same reasoning for v8. It is measured at attest time and carried
+    // unchanged onto the outcome, so projecting it back is a copy; dropping it
+    // here would make every genuine v8 record fail its attestation signature.
+    recoverable_state: s.recoverable_state,
   }));
 }
 

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,