burnledger 0.8.1 → 0.9.0

package/src/customer-keys.ts

@@ -18,8 +18,9 @@
  * generator writes by calling core itself.
  */
 
-import { canonicalJson } from "./verify.js";
+import { canonicalJson, formatTimestamp } from "./verify.js";
 import type { CryptoOps } from "./crypto.js";
+import { VerificationError } from "./errors.js";
 
 /**
  * Mirrors core.CustomerKeyIDPrefix. It distinguishes a customer's key id from
@@ -35,7 +36,11 @@ export const CUSTOMER_KEY_ID_PREFIX = "cust_k_";
  */
 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.PayloadTypeKeyRotationRequest. v2 carries not_after, which bounds
+ * the request itself; a protocol-12 enclave refuses v1.
+ */
+export const PAYLOAD_TYPE_KEY_ROTATION_REQUEST = "burnledger.key_rotation_request.v2";
 
 /** Mirrors core.MaxCustomerKeyGroupMembers. */
 export const MAX_CUSTOMER_KEY_GROUP_MEMBERS = 16;
@@ -103,6 +108,15 @@ export async function validateKeyGroup(
         `every member must be a ${ED25519_PUBLIC_KEY_SIZE}-byte Ed25519 key`,
       );
     }
+    if (!isNotSmallOrder(member)) {
+      // A small-order key is held by nobody: with the identity point as the
+      // public key, R = identity and S = 0 verify over ANY message, so it
+      // would pass proof of possession and count toward a threshold for free.
+      throw new InvalidKeyGroupError(
+        "every member must be an Ed25519 public key on the curve and not of small order " +
+          "(small-order and off-curve keys are refused)",
+      );
+    }
     const fingerprint = await memberFingerprint(crypto, member);
     if (seen.has(fingerprint)) {
       // A repeated member would let one holder satisfy a threshold meant to
@@ -145,6 +159,17 @@ export async function customerKeyId(
   return CUSTOMER_KEY_ID_PREFIX + toHex(await crypto.sha256(canonicalJson(document)));
 }
 
+/**
+ * A request's `not_after` as Go signs it (core.KeyTimeFormat): UTC, whole
+ * seconds, the fraction truncated as Go's Format truncates it.
+ */
+export function keyTime(value: Date): string {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new Error("not_after is required");
+  }
+  return value.toISOString().slice(0, 19) + "Z";
+}
+
 /**
  * The canonical bytes the OUTGOING group's members sign to authorise a rotation.
  *
@@ -160,10 +185,19 @@ export function buildKeyRotationRequestPayload(request: {
   assertedTeamId: string;
   prevKeyId: string;
   nextKeyId: string;
+  /**
+   * Bounds the request: the enclave ends the successor's window no later than
+   * this and refuses the request once it has passed, so a replay cannot renew
+   * the window. Signed as whole seconds, UTC.
+   */
+  notAfter: Date;
 }): Uint8Array {
   if (!request.prevKeyId || !request.nextKeyId) {
     throw new Error("a rotation request names both the key being replaced and its replacement");
   }
+  if (!(request.notAfter instanceof Date) || Number.isNaN(request.notAfter.getTime())) {
+    throw new Error("not_after is required");
+  }
   if (request.prevKeyId === request.nextKeyId) {
     // A self-rotation is a cycle in the chain the enclave walks, and it walks
     // without a visited set.
@@ -172,9 +206,345 @@ export function buildKeyRotationRequestPayload(request: {
     );
   }
   return canonicalJson({
-    asserted_team_id: request.assertedTeamId,
+    asserted_team_id: canonicalUuid(request.assertedTeamId, "assertedTeamId"),
     next_key_id: request.nextKeyId,
+    not_after: keyTime(request.notAfter),
     payload_type: PAYLOAD_TYPE_KEY_ROTATION_REQUEST,
     prev_key_id: request.prevKeyId,
   });
 }
+
+// Ed25519 arithmetic for one question only: is a member key a curve point
+// outside the small-order subgroup? It mirrors the decoding Go's
+// filippo.io/edwards25519 performs in core.CustomerKeyGroup.Validate, so both
+// sides refuse exactly the same keys: bit 255 of y is ignored and y is reduced
+// mod p (non-canonical encodings are accepted), a y with no matching x is
+// refused, and the sign bit selects the negative root even when x = 0.
+const FIELD_P = 2n ** 255n - 19n;
+const fieldMod = (a: bigint): bigint => ((a % FIELD_P) + FIELD_P) % FIELD_P;
+function fieldPow(base: bigint, exp: bigint): bigint {
+  let result = 1n;
+  let b = fieldMod(base);
+  for (let e = exp; e > 0n; e >>= 1n) {
+    if (e & 1n) result = (result * b) % FIELD_P;
+    b = (b * b) % FIELD_P;
+  }
+  return result;
+}
+const fieldInv = (a: bigint): bigint => fieldPow(a, FIELD_P - 2n);
+const CURVE_D = fieldMod(-121665n * fieldInv(121666n));
+const SQRT_MINUS_ONE = fieldPow(2n, (FIELD_P - 1n) / 4n);
+
+function decodePoint(bytes: Uint8Array): [bigint, bigint] | null {
+  // validateKeyGroup has already required exactly 32 bytes.
+  const top = bytes[31] ?? 0;
+  let y = 0n;
+  for (let i = 31; i >= 0; i--) {
+    y = (y << 8n) | BigInt(i === 31 ? top & 0x7f : (bytes[i] ?? 0));
+  }
+  y = fieldMod(y);
+  const u = fieldMod(y * y - 1n);
+  const v = fieldMod(CURVE_D * y * y + 1n);
+  let x = fieldMod(u * fieldPow(v, 3n) * fieldPow(u * fieldPow(v, 7n), (FIELD_P - 5n) / 8n));
+  const vx2 = fieldMod(v * x * x);
+  if (vx2 === fieldMod(-u)) {
+    x = fieldMod(x * SQRT_MINUS_ONE);
+  } else if (vx2 !== u) {
+    return null;
+  }
+  if (Number(x & 1n) !== top >> 7) x = fieldMod(-x);
+  return [x, y];
+}
+
+// The complete twisted-Edwards addition law (a = -1); its denominators are
+// never zero because d is not a square.
+function addPoints(p: [bigint, bigint], q: [bigint, bigint]): [bigint, bigint] {
+  const t = fieldMod(CURVE_D * p[0] * q[0] * p[1] * q[1]);
+  return [
+    fieldMod((p[0] * q[1] + p[1] * q[0]) * fieldInv(1n + t)),
+    fieldMod((p[1] * q[1] + p[0] * q[0]) * fieldInv(fieldMod(1n - t))),
+  ];
+}
+
+/**
+ * Whether key decodes to a curve point that is not of small order (8·P ≠ identity).
+ * Not a prime-order check: a mixed-order key passes, as it does in Go.
+ */
+function isNotSmallOrder(key: Uint8Array): boolean {
+  let point = decodePoint(key);
+  if (point === null) return false;
+  for (let i = 0; i < 3; i++) point = addPoints(point, point);
+  return !(point[0] === 0n && point[1] === 1n);
+}
+
+/** Mirrors core.PayloadTypeKeyEnrollmentRequest. */
+export const PAYLOAD_TYPE_KEY_ENROLLMENT_REQUEST = "burnledger.key_enrollment_request.v1";
+/** Mirrors core.PayloadTypeSystemRegistrationRequest. */
+export const PAYLOAD_TYPE_SYSTEM_REGISTRATION_REQUEST = "burnledger.system_registration_request.v1";
+
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+
+/**
+ * A UUID in the one form Go prints it (uuid.UUID.String()): lowercase and
+ * hyphenated. The enclave rebuilds every customer-signed payload from the
+ * uuid.UUID it parsed, so a team id signed as the caller happened to type it —
+ * uppercase, say — would be different bytes, and the refusal would be a 401 with
+ * nothing in it to say why.
+ */
+function canonicalUuid(value: string, field: string): string {
+  if (typeof value !== "string" || !UUID_RE.test(value)) {
+    throw new Error(`${field} must be a UUID, got ${JSON.stringify(value)}`);
+  }
+  return value.toLowerCase();
+}
+
+function requireSha256(value: Uint8Array, field: string): string {
+  if (!(value instanceof Uint8Array) || value.length !== 32) {
+    throw new Error(`${field} must be a 32-byte SHA-256 digest`);
+  }
+  return toHex(value);
+}
+
+/**
+ * The canonical bytes EVERY member of a group signs to enrol it for a team.
+ *
+ * Port of core.BuildKeyEnrollmentRequestPayload. Without these signatures
+ * whoever relays the request could enrol public keys it does not hold — the
+ * customer's included — so the enclave demands one from each member, not a
+ * threshold: the statement it signs vouches for every key. `notAfter` is the
+ * latest the resulting authorization may end, and when the request itself stops
+ * being usable: the enclave cannot recognize a replay, so this is what keeps a
+ * relayed copy from renewing the window.
+ */
+export function buildKeyEnrollmentRequestPayload(request: {
+  assertedTeamId: string;
+  customerKeyId: string;
+  notAfter: Date;
+}): Uint8Array {
+  if (!request.customerKeyId) throw new Error("customer_key_id is required");
+  return canonicalJson({
+    asserted_team_id: canonicalUuid(request.assertedTeamId, "assertedTeamId"),
+    customer_key_id: request.customerKeyId,
+    not_after: keyTime(request.notAfter),
+    payload_type: PAYLOAD_TYPE_KEY_ENROLLMENT_REQUEST,
+  });
+}
+
+/**
+ * The canonical bytes an enrolled group signs, at its threshold, to register one
+ * system under it.
+ *
+ * Port of core.BuildSystemRegistrationRequestPayload. Both digests are over bytes
+ * the CUSTOMER holds: `configDigest` is SHA-256 of the exact config bytes
+ * submitted when the system was created (the plaintext that was sealed), and
+ * `queryTemplateSha256` is SHA-256 of the template exactly as it will be sent —
+ * raw, not normalized. The enclave recomputes both from what it decrypted and
+ * was given, so a relay that substitutes either changes the bytes and the
+ * signatures fail.
+ */
+export function buildSystemRegistrationRequestPayload(request: {
+  assertedTeamId: string;
+  systemId: string;
+  configDigest: Uint8Array;
+  queryTemplateSha256: Uint8Array;
+  connectorType: string;
+  customerKeyId: string;
+}): Uint8Array {
+  if (!request.customerKeyId) throw new Error("customer_key_id is required");
+  const systemId = canonicalUuid(request.systemId, "systemId");
+  if (systemId === NIL_UUID) throw new Error("system_id is required");
+  return canonicalJson({
+    asserted_team_id: canonicalUuid(request.assertedTeamId, "assertedTeamId"),
+    config_digest: requireSha256(request.configDigest, "configDigest"),
+    connector_type: request.connectorType,
+    customer_key_id: request.customerKeyId,
+    payload_type: PAYLOAD_TYPE_SYSTEM_REGISTRATION_REQUEST,
+    query_template_sha256: requireSha256(request.queryTemplateSha256, "queryTemplateSha256"),
+    system_id: systemId,
+  });
+}
+
+// --- The documents the ENCLAVE signs -----------------------------------------
+//
+// Ports of core.VerifyKeyEnrollment, core.VerifyTeamAuthorization and
+// core.VerifySystemRegistration. Each takes the key rather than finding one, as
+// Go's do: a document that names the key vouching for it proves only that its
+// author holds that key. The key to pass is the signing key of an enclave you
+// attested against your pinned PCR0 (EnclaveIdentity.signingKey) -- the client's
+// enrol, rotate and register calls use exactly that. Each reads the document as
+// the API returns it, because the signed bytes are rebuilt from the wire
+// strings (whole-second UTC timestamps, lowercase UUIDs), and throws
+// VerificationError on anything that does not verify.
+
+// v2 from wire protocol 12, and v2 is the only version a protocol-12 enclave
+// issues or honors: a v1 document could have been minted by an earlier image
+// without the customer's signature.
+const PAYLOAD_TYPE_KEY_ENROLLMENT = "burnledger.key_enrollment.v2";
+const PAYLOAD_TYPE_TEAM_AUTHORIZATION = "burnledger.team_authorization.v2";
+const PAYLOAD_TYPE_SYSTEM_REGISTRATION = "burnledger.system_registration.v2";
+
+type Doc = Record<string, unknown>;
+
+function docObject(value: unknown, what: string): Doc {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new VerificationError(`${what} is not an object`);
+  }
+  return value as Doc;
+}
+
+function docString(doc: Doc, what: string, field: string): string {
+  const value = doc[field];
+  if (typeof value !== "string") throw new VerificationError(`${what}.${field} is not a string`);
+  return value;
+}
+
+function docKeyId(doc: Doc, what: string): string {
+  const value = docString(doc, what, "customer_key_id");
+  if (value === "") throw new VerificationError(`${what}.customer_key_id is empty`);
+  return value;
+}
+
+function docUuid(doc: Doc, what: string, field: string): string {
+  const value = docString(doc, what, field);
+  if (!UUID_RE.test(value)) throw new VerificationError(`${what}.${field} is not a UUID`);
+  return value.toLowerCase();
+}
+
+/** Go encodes [N]byte as an array of numbers. */
+function docBytes(doc: Doc, what: string, field: string, length: number): Uint8Array {
+  const value = doc[field];
+  if (
+    !Array.isArray(value) ||
+    value.length !== length ||
+    !value.every((b) => Number.isInteger(b) && b >= 0 && b <= 255)
+  ) {
+    throw new VerificationError(`${what}.${field} is not ${length} bytes`);
+  }
+  return new Uint8Array(value as number[]);
+}
+
+/** Go encodes []byte as padded standard base64. */
+function base64Bytes(value: unknown, what: string): Uint8Array {
+  if (typeof value !== "string" || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+    throw new VerificationError(`${what} is not base64`);
+  }
+  const bin = atob(value);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+async function requireEnclaveSignature(
+  crypto: CryptoOps,
+  enclaveKey: Uint8Array,
+  payload: Uint8Array,
+  signature: Uint8Array,
+  what: string,
+): Promise<void> {
+  if (!(enclaveKey instanceof Uint8Array) || enclaveKey.length !== ED25519_PUBLIC_KEY_SIZE) {
+    throw new TypeError(`enclaveKey must be a ${ED25519_PUBLIC_KEY_SIZE}-byte Ed25519 public key`);
+  }
+  if (!(await crypto.ed25519Verify(enclaveKey, payload, signature))) {
+    const keyId = "dp_k_" + toHex(await crypto.sha256(enclaveKey));
+    throw new VerificationError(
+      `the ${what} is not signed by enclave key ${keyId}. Do not use it: a relay that ` +
+        "forged or altered one would produce exactly this.",
+    );
+  }
+}
+
+/**
+ * Verify the enclave's signature on a key enrolment statement (the `enrollment`
+ * object ENROLL_KEY and ROTATE_KEY return). Also refuses a statement whose
+ * `customer_key_id` is not the id its own group derives, as Go's payload
+ * builder does -- so a statement that verifies names exactly its members and
+ * threshold, and comparing its key id with yours compares those too.
+ */
+export async function verifyKeyEnrollmentStatement(
+  crypto: CryptoOps,
+  statement: unknown,
+  enclaveKey: Uint8Array,
+): Promise<void> {
+  const what = "enrollment";
+  const doc = docObject(statement, what);
+  const rawGroup = docObject(doc.group, `${what}.group`);
+  if (!Array.isArray(rawGroup.members)) throw new VerificationError(`${what}.group.members is not an array`);
+  const group: CustomerKeyGroup = {
+    threshold: rawGroup.threshold as number,
+    members: rawGroup.members.map((m, i) => base64Bytes(m, `${what}.group.members[${i}]`)),
+  };
+  let derived: string;
+  try {
+    derived = await customerKeyId(crypto, group);
+  } catch (err) {
+    if (err instanceof InvalidKeyGroupError) throw new VerificationError(`${what}.group: ${err.message}`);
+    throw err;
+  }
+  const keyId = docKeyId(doc, what);
+  if (keyId !== derived) {
+    throw new VerificationError(`${what}.customer_key_id ${keyId} is not the id its own group derives (${derived})`);
+  }
+  const payload = canonicalJson({
+    asserted_team_id: docUuid(doc, what, "asserted_team_id"),
+    customer_key_id: keyId,
+    enclave_pcr0: docString(doc, what, "enclave_pcr0"),
+    enrolled_at: formatTimestamp(doc.enrolled_at, `${what}.enrolled_at`),
+    member_key_ids: await memberFingerprints(crypto, group),
+    payload_type: PAYLOAD_TYPE_KEY_ENROLLMENT,
+    threshold: group.threshold,
+  });
+  await requireEnclaveSignature(crypto, enclaveKey, payload, docBytes(doc, what, "signature", 64), "enrollment statement");
+}
+
+/**
+ * Verify the enclave's signature on a team authorization (the `authorization`
+ * object ENROLL_KEY and ROTATE_KEY return). The signature only: whether it is
+ * in force now is a separate question, as in Go.
+ */
+export async function verifyTeamAuthorization(
+  crypto: CryptoOps,
+  certificate: unknown,
+  enclaveKey: Uint8Array,
+): Promise<void> {
+  const what = "authorization";
+  const doc = docObject(certificate, what);
+  const notBefore = formatTimestamp(doc.not_before, `${what}.not_before`);
+  const notAfter = formatTimestamp(doc.not_after, `${what}.not_after`);
+  // Go compares at full precision; the whole-second strings disagree with it
+  // only for a window shorter than a second, which no enclave issues.
+  if (notAfter <= notBefore) throw new VerificationError(`${what}.not_after is not after not_before`);
+  // prev_key_id is omitempty in Go: absent on a first enrolment, and absent
+  // from the signed payload too.
+  const prevKeyId = doc.prev_key_id == null ? "" : docString(doc, what, "prev_key_id");
+  const payload = canonicalJson({
+    asserted_team_id: docUuid(doc, what, "asserted_team_id"),
+    customer_key_id: docKeyId(doc, what),
+    not_after: notAfter,
+    not_before: notBefore,
+    payload_type: PAYLOAD_TYPE_TEAM_AUTHORIZATION,
+    ...(prevKeyId === "" ? {} : { prev_key_id: prevKeyId }),
+  });
+  await requireEnclaveSignature(crypto, enclaveKey, payload, docBytes(doc, what, "signature", 64), "team authorization");
+}
+
+/** Verify the enclave's signature on a system registration (the
+ * `registration` object REGISTER_SYSTEM returns). */
+export async function verifySystemRegistration(
+  crypto: CryptoOps,
+  certificate: unknown,
+  enclaveKey: Uint8Array,
+): Promise<void> {
+  const what = "registration";
+  const doc = docObject(certificate, what);
+  const payload = canonicalJson({
+    config_digest: toHex(docBytes(doc, what, "config_digest", 32)),
+    connector_type: docString(doc, what, "connector_type"),
+    customer_key_id: docKeyId(doc, what),
+    payload_type: PAYLOAD_TYPE_SYSTEM_REGISTRATION,
+    query_template_hash: toHex(docBytes(doc, what, "query_template_hash", 32)),
+    registered_at: formatTimestamp(doc.registered_at, `${what}.registered_at`),
+    system_id: docUuid(doc, what, "system_id"),
+  });
+  await requireEnclaveSignature(crypto, enclaveKey, payload, docBytes(doc, what, "signature", 64), "system registration");
+}