burnledger 0.4.0 → 0.6.0

package/src/enclave-seal.ts

@@ -0,0 +1,582 @@
+/**
+ * Seal a connection config to the enclave, so the BurnLedger host never reads it.
+ *
+ * WHY THIS MODULE EXISTS. Registering a system used to mean POSTing your
+ * datastore credentials to the API in the clear. The host then handed them to
+ * the enclave to be sealed, and everything after that point was ciphertext only
+ * the enclave could open — but the host held the plaintext for the length of
+ * that request, and nothing recorded that it had. This removes that step: you
+ * seal the config yourself, and the host relays bytes it cannot open.
+ *
+ * WHAT MAKES IT WORK, AND WHAT WOULD MAKE IT THEATRE. The enclave publishes an
+ * X25519 public key inside its AWS Nitro attestation document, beside the
+ * Ed25519 signing key it already published. `verifyEnclaveConfigSealKey` checks
+ * that document — the COSE signature, the certificate chain to the pinned AWS
+ * Nitro root, and the image's PCR0 — and returns the key. Sealing to a key the
+ * API simply handed over protects nothing: the host would supply its own key,
+ * read the config, and re-seal to the real enclave, and your registration would
+ * succeed exactly as it does today. So `sealConnectionConfig` takes the
+ * attestation document and the PCR0 you expect, never a bare key.
+ *
+ * WHERE `expectedPcr0` COMES FROM. Not from this API. A measurement served by
+ * the same host that serves the document pins nothing. Take BurnLedger's
+ * published measurement for the enclave image out of band and pin it in your own
+ * configuration. That is a trust-on-first-use anchor in the operator's
+ * publication — the same anchor every other claim in this product rests on.
+ *
+ * WHAT IT DOES NOT DO. It stops the host reading a config in transit. It does
+ * not stop the host composing a config of ITS own and having the enclave seal
+ * that, and it does nothing if the machine running this code is compromised.
+ *
+ * NODE ONLY. Verifying an attestation document needs X.509 chain building,
+ * which browsers do not expose, and sealing a datastore credential is not a
+ * thing a browser should be doing. This module is not part of the browser entry
+ * point.
+ */
+
+import { X509Certificate, verify as nodeVerify, webcrypto } from "node:crypto";
+
+/**
+ * Envelope wire format (v1). Must match enclave/configsealkey.go byte for byte:
+ *
+ *   magic      8   "BLCFGSL1"
+ *   recipient 32   the X25519 key this envelope is addressed to
+ *   ephemeral 32   this sender's one-time X25519 key
+ *   nonce     12   AES-GCM nonce
+ *   sealed     n   AES-256-GCM(plaintext), tag appended
+ *
+ * The key is HKDF-SHA256 over the X25519 shared secret salted with the whole
+ * header; the same header is the GCM additional data.
+ */
+export const ENVELOPE_MAGIC = new Uint8Array([0x42, 0x4c, 0x43, 0x46, 0x47, 0x53, 0x4c, 0x31]); // "BLCFGSL1"
+const KEY_SIZE = 32;
+const NONCE_SIZE = 12;
+export const HEADER_SIZE = ENVELOPE_MAGIC.length + 2 * KEY_SIZE + NONCE_SIZE;
+const KDF_INFO = new TextEncoder().encode("burnledger/config-seal/v1");
+
+/**
+ * The AWS Nitro Enclaves root CA (G1), pinned. A root fetched at runtime is not
+ * a pin; this is the anchor the whole verification hangs from.
+ */
+export const NITRO_ROOT_G1_PEM = `-----BEGIN CERTIFICATE-----
+MIICETCCAZagAwIBAgIRAPkxdWgbkK/hHUbMtOTn+FYwCgYIKoZIzj0EAwMwSTEL
+MAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMRswGQYD
+VQQDDBJhd3Mubml0cm8tZW5jbGF2ZXMwHhcNMTkxMDI4MTMyODA1WhcNNDkxMDI4
+MTQyODA1WjBJMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQL
+DANBV1MxGzAZBgNVBAMMEmF3cy5uaXRyby1lbmNsYXZlczB2MBAGByqGSM49AgEG
+BSuBBAAiA2IABPwCVOumCMHzaHDimtqQvkY4MpJzbolL//Zy2YlES1BR5TSksfbb
+48C8WBoyt7F2Bw7eEtaaP+ohG2bnUs990d0JX28TcPQXCEPZ3BABIeTPYwEoCWZE
+h8l5YoQwTcU/9KNCMEAwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUkCW1DdkF
+R+eWw5b6cp3PmanfS5YwDgYDVR0PAQH/BAQDAgGGMAoGCCqGSM49BAMDA2kAMGYC
+MQCjfy+Rocm9Xue4YnwWmNJVA44fA0P5W2OpYow9OYCVRaEevL8uO1XYru5xtMPW
+rfMCMQCi85sWBbJwKKXdS6BptQFuZbT73o/gBh1qUxl/nNr12UO8Yfwr6wPLb+6N
+IwLz3/Y=
+-----END CERTIFICATE-----
+`;
+
+/** Same bound as enclave.MaxAttestationClockSkew. */
+const MAX_CLOCK_SKEW_MS = 5 * 60 * 1000;
+const COSE_ALG_ES384 = -35;
+
+/** Raised when an attestation document is not one this client will seal to. */
+export class EnclaveAttestationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EnclaveAttestationError";
+  }
+}
+
+export interface SealOptions {
+  /** Hex PCR0 of the enclave image you accept, pinned out of band. Required. */
+  expectedPcr0: string;
+  /** Further PCRs to pin, hex-encoded, by index. */
+  expectedPcrs?: Record<number, string>;
+  /** The reference time the document must describe. Defaults to now. */
+  now?: Date;
+  /**
+   * Override the pinned AWS Nitro root. Leave unset in production — a root
+   * supplied per call is not a pin.
+   */
+  rootPem?: string;
+}
+
+/**
+ * Seal `config` to the enclave the attestation document describes. Pass the
+ * result as `sealed_connection_config` when registering a system.
+ *
+ * Throws {@link EnclaveAttestationError} if the document is not a genuine Nitro
+ * attestation from the pinned image. Nothing is sealed in that case.
+ */
+export async function sealConnectionConfig(
+  config: Record<string, unknown> | string | Uint8Array,
+  attestationDocument: Uint8Array,
+  options: SealOptions,
+): Promise<Uint8Array> {
+  const key = await verifyEnclaveConfigSealKey(attestationDocument, options);
+  return sealToKey(key, configBytes(config));
+}
+
+/**
+ * Seal `plaintext` to an already-verified enclave config-seal key.
+ *
+ * Prefer {@link sealConnectionConfig}, which verifies the key for you. This is
+ * the lower half, for a caller that verified the document itself.
+ */
+export async function sealToKey(
+  recipientPublicKey: Uint8Array,
+  plaintext: Uint8Array,
+): Promise<Uint8Array> {
+  if (recipientPublicKey.length !== KEY_SIZE) {
+    throw new EnclaveAttestationError(
+      `config-seal recipient key is ${recipientPublicKey.length} bytes, want ${KEY_SIZE}`,
+    );
+  }
+  let peer: webcrypto.CryptoKey;
+  try {
+    peer = await webcrypto.subtle.importKey(
+      "raw",
+      bufferSource(recipientPublicKey),
+      { name: "X25519" },
+      false,
+      [],
+    );
+  } catch (err) {
+    throw new EnclaveAttestationError(`config-seal recipient key: ${(err as Error).message}`);
+  }
+  const ephemeral = (await webcrypto.subtle.generateKey({ name: "X25519" }, true, [
+    "deriveBits",
+  ])) as unknown as webcrypto.CryptoKeyPair;
+  const shared = new Uint8Array(
+    await webcrypto.subtle.deriveBits({ name: "X25519", public: peer }, ephemeral.privateKey, 256),
+  );
+  const ephemeralPublic = new Uint8Array(
+    await webcrypto.subtle.exportKey("raw", ephemeral.publicKey),
+  );
+
+  const nonce = webcrypto.getRandomValues(new Uint8Array(NONCE_SIZE));
+  const header = concat(ENVELOPE_MAGIC, recipientPublicKey, ephemeralPublic, nonce);
+  const aesKey = await deriveEnvelopeKey(shared, header);
+  const sealed = new Uint8Array(
+    await webcrypto.subtle.encrypt(
+      { name: "AES-GCM", iv: nonce, additionalData: header },
+      aesKey,
+      bufferSource(plaintext),
+    ),
+  );
+  return concat(header, sealed);
+}
+
+/**
+ * Verify an enclave attestation document and return the X25519 config-seal key
+ * bound in it.
+ *
+ * Checks, in order: the COSE_Sign1 structure and its ES384 algorithm; the
+ * certificate chain from the document's leaf through its CA bundle to the
+ * pinned AWS Nitro root; the ES384 signature over the RFC 8152 Sig_structure;
+ * the document's own AWS-signed timestamp against `now`; the PCRs; and that the
+ * bound key is 32 bytes.
+ *
+ * PCR0 must be pinned. Without it any genuinely-signed Nitro document — including
+ * one from an enclave the host itself booted — would pass.
+ */
+export async function verifyEnclaveConfigSealKey(
+  attestationDocument: Uint8Array,
+  options: SealOptions,
+): Promise<Uint8Array> {
+  if (!attestationDocument || attestationDocument.length === 0) {
+    throw new EnclaveAttestationError(
+      "no attestation document (nothing to verify — this is not a pass)",
+    );
+  }
+  const expected: Record<number, string> = { ...(options.expectedPcrs ?? {}) };
+  if (options.expectedPcr0) expected[0] = options.expectedPcr0;
+  if (expected[0] === undefined) {
+    throw new EnclaveAttestationError(
+      "no expected PCR0; refusing to accept an unpinned enclave image",
+    );
+  }
+  const now = options.now ?? new Date();
+
+  const { protected: protectedBytes, payload: payloadBytes, signature } =
+    decodeCoseSign1(attestationDocument);
+  checkAlgEs384(protectedBytes);
+
+  const payload = cborDecode(payloadBytes);
+  if (!(payload instanceof Map)) {
+    throw new EnclaveAttestationError("attestation payload is not a CBOR map");
+  }
+  const leafDer = payload.get("certificate");
+  if (!(leafDer instanceof Uint8Array) || leafDer.length === 0) {
+    throw new EnclaveAttestationError("attestation payload missing certificate");
+  }
+  const pcrs = payload.get("pcrs");
+  if (!(pcrs instanceof Map)) {
+    throw new EnclaveAttestationError("attestation payload missing pcrs");
+  }
+
+  const leaf = verifyChain(leafDer, payload.get("cabundle"), now, options.rootPem ?? NITRO_ROOT_G1_PEM);
+  verifyCoseSignature(leaf, protectedBytes, payloadBytes, signature);
+  checkClock(payload.get("timestamp"), now);
+  matchPcrs(pcrs, expected);
+
+  const publicKey = payload.get("public_key");
+  if (!(publicKey instanceof Uint8Array) || publicKey.length !== KEY_SIZE) {
+    const got = publicKey instanceof Uint8Array ? publicKey.length : 0;
+    throw new EnclaveAttestationError(
+      `the document binds a ${got}-byte public key, want a ${KEY_SIZE}-byte X25519 ` +
+        "config-seal key (this enclave image may not publish one)",
+    );
+  }
+  return publicKey;
+}
+
+// --- verification internals -------------------------------------------------
+
+/**
+ * Build and verify leaf -> cabundle -> pinned root, valid at `now`.
+ *
+ * The path is not general: the NSM hands over an ORDERED bundle, root first, so
+ * the chain is walked in order and every hop must check out. Nothing is
+ * searched for an alternative path — an ambiguous chain is a refusal.
+ */
+function verifyChain(
+  leafDer: Uint8Array,
+  cabundle: unknown,
+  now: Date,
+  rootPem: string,
+): X509Certificate {
+  let root: X509Certificate;
+  try {
+    root = new X509Certificate(rootPem);
+  } catch (err) {
+    throw new EnclaveAttestationError(`pinned Nitro root is unreadable: ${(err as Error).message}`);
+  }
+  if (!Array.isArray(cabundle) || cabundle.length === 0) {
+    throw new EnclaveAttestationError("attestation payload carries no CA bundle");
+  }
+
+  const chain: X509Certificate[] = [];
+  cabundle.forEach((der, i) => {
+    if (!(der instanceof Uint8Array)) {
+      throw new EnclaveAttestationError(`cabundle[${i}] is not a byte string`);
+    }
+    try {
+      chain.push(new X509Certificate(Buffer.from(der)));
+    } catch (err) {
+      throw new EnclaveAttestationError(`cabundle[${i}] is not a certificate: ${(err as Error).message}`);
+    }
+  });
+  let leaf: X509Certificate;
+  try {
+    leaf = new X509Certificate(Buffer.from(leafDer));
+  } catch (err) {
+    throw new EnclaveAttestationError(`leaf certificate is unreadable: ${(err as Error).message}`);
+  }
+
+  if (chain[0]!.fingerprint256 !== root.fingerprint256) {
+    throw new EnclaveAttestationError(
+      "the document's CA bundle does not start at the pinned AWS Nitro root",
+    );
+  }
+
+  const ordered = [...chain, leaf];
+  for (const cert of ordered) checkValidity(cert, now);
+  for (let i = 1; i < ordered.length; i++) {
+    const issuer = ordered[i - 1]!;
+    const subject = ordered[i]!;
+    if (!subject.checkIssued(issuer) || !subject.verify(issuer.publicKey)) {
+      throw new EnclaveAttestationError(
+        `certificate chain is broken at ${subject.subject.replace(/\n/g, ", ")}`,
+      );
+    }
+  }
+  return leaf;
+}
+
+function checkValidity(cert: X509Certificate, now: Date): void {
+  const from = Date.parse(cert.validFrom);
+  const to = Date.parse(cert.validTo);
+  if (Number.isNaN(from) || Number.isNaN(to)) {
+    throw new EnclaveAttestationError(
+      `certificate ${cert.subject.replace(/\n/g, ", ")} has an unreadable validity window`,
+    );
+  }
+  const t = now.getTime();
+  if (t < from || t > to) {
+    throw new EnclaveAttestationError(
+      `certificate ${cert.subject.replace(/\n/g, ", ")} is not valid at ${now.toISOString()} ` +
+        `(valid ${new Date(from).toISOString()} to ${new Date(to).toISOString()})`,
+    );
+  }
+}
+
+function verifyCoseSignature(
+  leaf: X509Certificate,
+  protectedBytes: Uint8Array,
+  payload: Uint8Array,
+  signature: Uint8Array,
+): void {
+  if (signature.length !== 96) {
+    throw new EnclaveAttestationError(
+      `signature is ${signature.length} bytes, want 96 (P-384 r||s)`,
+    );
+  }
+  const sigStructure = cborEncode(["Signature1", protectedBytes, new Uint8Array(0), payload]);
+  // ieee-p1363 is the raw r||s pair COSE carries; the default would expect DER.
+  const ok = nodeVerify(
+    "sha384",
+    sigStructure,
+    { key: leaf.publicKey, dsaEncoding: "ieee-p1363" },
+    signature,
+  );
+  if (!ok) throw new EnclaveAttestationError("the attestation COSE signature is invalid");
+}
+
+function checkClock(timestamp: unknown, now: Date): void {
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp) || timestamp <= 0) {
+    throw new EnclaveAttestationError(
+      "the document carries no timestamp (nothing to check the clock against)",
+    );
+  }
+  const skew = Math.abs(now.getTime() - timestamp);
+  if (skew > MAX_CLOCK_SKEW_MS) {
+    throw new EnclaveAttestationError(
+      `the NSM signed this document at ${new Date(timestamp).toISOString()} but it is being ` +
+        `verified against ${now.toISOString()} — ${Math.round(skew / 1000)}s of clock skew ` +
+        `exceeds the ${MAX_CLOCK_SKEW_MS / 1000}s bound`,
+    );
+  }
+}
+
+function matchPcrs(actual: Map<unknown, unknown>, expected: Record<number, string>): void {
+  for (const [key, wantHex] of Object.entries(expected)) {
+    const index = Number(key);
+    const got = actual.get(index);
+    if (!(got instanceof Uint8Array)) {
+      throw new EnclaveAttestationError(`the document carries no PCR${index}`);
+    }
+    if (toHex(got) !== wantHex.toLowerCase()) {
+      throw new EnclaveAttestationError(
+        `PCR${index} is ${toHex(got)}, expected ${wantHex} — this is not the enclave image you pinned`,
+      );
+    }
+  }
+}
+
+async function deriveEnvelopeKey(
+  shared: Uint8Array,
+  header: Uint8Array<ArrayBuffer>,
+): Promise<webcrypto.CryptoKey> {
+  const ikm = await webcrypto.subtle.importKey("raw", bufferSource(shared), "HKDF", false, [
+    "deriveKey",
+  ]);
+  return webcrypto.subtle.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt: header, info: KDF_INFO },
+    ikm,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+function configBytes(config: Record<string, unknown> | string | Uint8Array): Uint8Array {
+
+  if (config instanceof Uint8Array) return config;
+  if (typeof config === "string") return new TextEncoder().encode(config);
+  return new TextEncoder().encode(JSON.stringify(config));
+}
+
+/**
+ * Copy into a view whose backing store TypeScript knows is a plain ArrayBuffer.
+ *
+ * WebCrypto's `BufferSource` excludes `SharedArrayBuffer`-backed views, and a
+ * `Uint8Array` parameter is `Uint8Array<ArrayBufferLike>`, which could be one.
+ * The copy is what makes that provably false rather than asserted away with a
+ * cast; the buffers here are a few kilobytes at most.
+ */
+function bufferSource(b: Uint8Array): Uint8Array<ArrayBuffer> {
+  return new Uint8Array(b);
+}
+
+function concat(...parts: Uint8Array[]): Uint8Array<ArrayBuffer> {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let offset = 0;
+  for (const p of parts) {
+    out.set(p, offset);
+    offset += p.length;
+  }
+  return out;
+}
+
+function toHex(b: Uint8Array): string {
+  return Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}
+
+// --- a CBOR subset ----------------------------------------------------------
+//
+// Enough of RFC 8949 to read an NSM attestation document and re-encode the
+// fixed four-element Sig_structure. Hand-rolled because this SDK ships with no
+// runtime dependencies, which is a published contract. Indefinite-length items
+// are refused rather than supported: a genuine NSM document uses definite
+// lengths throughout, and accepting two encodings for one value is how
+// signature checks get bypassed.
+
+function decodeCoseSign1(doc: Uint8Array): {
+  protected: Uint8Array;
+  payload: Uint8Array;
+  signature: Uint8Array;
+} {
+  const body = doc[0] === 0xd2 ? doc.subarray(1) : doc; // CBOR tag 18
+  const value = cborDecode(body);
+  if (!Array.isArray(value) || value.length !== 4) {
+    throw new EnclaveAttestationError("COSE_Sign1 must be a 4-element array");
+  }
+  const [prot, , payload, signature] = value;
+  for (const [name, item] of [
+    ["protected header", prot],
+    ["payload", payload],
+    ["signature", signature],
+  ] as const) {
+    if (!(item instanceof Uint8Array)) {
+      throw new EnclaveAttestationError(`COSE_Sign1 ${name} is not a byte string`);
+    }
+  }
+  return {
+    protected: prot as Uint8Array,
+    payload: payload as Uint8Array,
+    signature: signature as Uint8Array,
+  };
+}
+
+function checkAlgEs384(protectedBytes: Uint8Array): void {
+  if (protectedBytes.length === 0) {
+    throw new EnclaveAttestationError("empty COSE protected header (no alg)");
+  }
+  const header = cborDecode(protectedBytes);
+  if (!(header instanceof Map) || !header.has(1)) {
+    throw new EnclaveAttestationError("COSE protected header missing alg");
+  }
+  const alg = header.get(1);
+  if (alg !== COSE_ALG_ES384) {
+    throw new EnclaveAttestationError(`COSE alg is ${alg}, want ES384 (${COSE_ALG_ES384})`);
+  }
+}
+
+type CborValue = number | string | Uint8Array | boolean | null | CborValue[] | Map<CborValue, CborValue>;
+
+function cborDecode(data: Uint8Array): CborValue {
+  const [value, offset] = cborRead(data, 0);
+  if (offset !== data.length) {
+    throw new EnclaveAttestationError(
+      `${data.length - offset} trailing bytes after the CBOR value`,
+    );
+  }
+  return value;
+}
+
+function cborRead(data: Uint8Array, start: number): [CborValue, number] {
+  if (start >= data.length) throw new EnclaveAttestationError("CBOR input ended mid-value");
+  const initial = data[start]!;
+  const major = initial >> 5;
+  const info = initial & 0x1f;
+  let i = start + 1;
+  let arg: number;
+
+  if (info < 24) {
+    arg = info;
+  } else if (info === 24) [arg, i] = cborUint(data, i, 1);
+  else if (info === 25) [arg, i] = cborUint(data, i, 2);
+  else if (info === 26) [arg, i] = cborUint(data, i, 4);
+  else if (info === 27) [arg, i] = cborUint(data, i, 8);
+  else if (info === 31) {
+    throw new EnclaveAttestationError("indefinite-length CBOR items are not accepted");
+  } else throw new EnclaveAttestationError(`reserved CBOR additional information ${info}`);
+
+  switch (major) {
+    case 0:
+      return [arg, i];
+    case 1:
+      return [-1 - arg, i];
+    case 2:
+    case 3: {
+      const end = i + arg;
+      if (end > data.length) {
+        throw new EnclaveAttestationError("CBOR string runs past the end of the input");
+      }
+      const chunk = data.subarray(i, end);
+      return [major === 2 ? chunk : new TextDecoder("utf-8", { fatal: true }).decode(chunk), end];
+    }
+    case 4: {
+      const items: CborValue[] = [];
+      for (let n = 0; n < arg; n++) {
+        const [item, next] = cborRead(data, i);
+        items.push(item);
+        i = next;
+      }
+      return [items, i];
+    }
+    case 5: {
+      const out = new Map<CborValue, CborValue>();
+      for (let n = 0; n < arg; n++) {
+        const [key, afterKey] = cborRead(data, i);
+        const [val, afterVal] = cborRead(data, afterKey);
+        if (out.has(key)) {
+          // Two readers could disagree about the same document. Refuse.
+          throw new EnclaveAttestationError(`duplicate CBOR map key ${String(key)}`);
+        }
+        out.set(key, val);
+        i = afterVal;
+      }
+      return [out, i];
+    }
+    case 6: // tag: transparent, the tagged value is what matters
+      return cborRead(data, i);
+    case 7:
+      if (info === 20) return [false, i];
+      if (info === 21) return [true, i];
+      if (info === 22) return [null, i];
+      throw new EnclaveAttestationError(`unsupported CBOR simple value ${info}`);
+    default:
+      throw new EnclaveAttestationError(`unsupported CBOR major type ${major}`);
+  }
+}
+
+function cborUint(data: Uint8Array, i: number, width: number): [number, number] {
+  if (i + width > data.length) {
+    throw new EnclaveAttestationError("CBOR integer runs past the end of the input");
+  }
+  let value = 0;
+  for (let n = 0; n < width; n++) value = value * 256 + data[i + n]!;
+  if (!Number.isSafeInteger(value)) {
+    throw new EnclaveAttestationError("CBOR integer exceeds the safe integer range");
+  }
+  return [value, i + width];
+}
+
+function cborEncode(value: CborValue): Uint8Array {
+  if (Array.isArray(value)) {
+    return concat(cborHead(4, value.length), ...value.map(cborEncode));
+  }
+  if (typeof value === "string") {
+    const raw = new TextEncoder().encode(value);
+    return concat(cborHead(3, raw.length), raw);
+  }
+  if (value instanceof Uint8Array) {
+    return concat(cborHead(2, value.length), value);
+  }
+  throw new EnclaveAttestationError(`cannot CBOR-encode ${typeof value}`);
+}
+
+function cborHead(major: number, arg: number): Uint8Array {
+  const base = major << 5;
+  if (arg < 24) return new Uint8Array([base | arg]);
+  if (arg < 0x100) return new Uint8Array([base | 24, arg]);
+  if (arg < 0x10000) return new Uint8Array([base | 25, arg >> 8, arg & 0xff]);
+  return new Uint8Array([
+    base | 26,
+    (arg >>> 24) & 0xff,
+    (arg >>> 16) & 0xff,
+    (arg >>> 8) & 0xff,
+    arg & 0xff,
+  ]);
+}

package/src/errors.ts

@@ -101,14 +101,59 @@ export class TimeoutError extends BurnLedgerError {
 
 export class VerificationError extends BurnLedgerError {
   readonly reason: string;
-
-  constructor(reason: string) {
+  /**
+   * A stable discriminator for the one rejection a caller must be able to tell
+   * apart from the rest: an authentic status statement that says REVOKED.
+   *
+   * Every other rejection on the status path — unknown key, revoked key, bad
+   * signature, a statement about a different certificate — means the statement
+   * could not be authenticated, which is not the same claim and must not be
+   * rendered as one. `reason` is prose and may be reworded; this is not.
+   *
+   * Undefined on every rejection that is not specifically coded.
+   */
+  readonly code?: string;
+
+  constructor(reason: string, code?: string) {
     super(reason);
     this.name = "VerificationError";
     this.reason = reason;
+    this.code = code;
   }
 }
 
+/** {@link VerificationError.code} for a verified statement that says REVOKED. */
+export const CERTIFICATE_REVOKED = "CERTIFICATE_REVOKED";
+
+/**
+ * The record is in a format this SDK does not know how to read.
+ *
+ * This is the second rejection a caller must be able to tell apart, for the
+ * same reason as the first: it is not a claim about the document. Before this
+ * code existed, a record in a newer format fell through to the oldest payload
+ * shape, the rebuilt bytes did not match, and the SDK threw "certificate
+ * signature is invalid" - telling a holder their genuine evidence had been
+ * tampered with when the answer was "upgrade this library".
+ *
+ * A UI must render it as "cannot check", never as a failure.
+ */
+export const UNSUPPORTED_FORMAT_VERSION = "UNSUPPORTED_FORMAT_VERSION";
+
+/**
+ * The record names a signature scheme this SDK cannot check.
+ *
+ * The third rejection a caller must tell apart, for the same reason as the
+ * other two: it is not a claim about the document. Records below format 7.0
+ * name no algorithm and every verifier simply assumed Ed25519, so had Ed25519
+ * needed replacing, a record signed under the replacement would have been fed
+ * to an Ed25519 verifier, failed, and been reported as a bad signature — a
+ * genuine record accused of forgery for being signed with the algorithm it says
+ * it was signed with.
+ *
+ * A UI must render it as "cannot check", never as a failure.
+ */
+export const UNSUPPORTED_ALGORITHM = "UNSUPPORTED_ALGORITHM";
+
 const STATUS_TO_CLASS: Record<
   number,
   new (opts: {