burnledger 0.6.0 → 0.7.0

package/src/verify.ts

@@ -61,6 +61,18 @@ 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";
 const FORMAT_VERSION_V3 = "3.0";
 
 /**
@@ -86,6 +98,7 @@ export const KNOWN_FORMAT_VERSIONS: readonly string[] = Object.freeze([
   FORMAT_VERSION_V5,
   FORMAT_VERSION_V6,
   FORMAT_VERSION_V7,
+  FORMAT_VERSION_V8,
 ]);
 
 /**
@@ -106,6 +119,52 @@ 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);
+}
+
 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 +505,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 +966,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 +991,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 +1027,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 +1057,7 @@ 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_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 +1073,10 @@ 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_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 +1092,8 @@ 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 systems = ((cert.systems as Record<string, unknown>[]) ?? []).map((s) => {
     const sys: Record<string, unknown> = {
       attested_at: formatTimestamp(s.attested_at),
@@ -1017,16 +1108,26 @@ 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,
       );
     }
     return sys;
@@ -1043,12 +1144,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 +1159,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 +1254,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,
   }));
 }