burnledger 0.8.1 → 0.9.0

package/src/key-group.ts

@@ -0,0 +1,181 @@
+/**
+ * The members of a customer key group as signers (ADR-025 §2–3).
+ *
+ * Node only, like enclave-seal.ts: ADR-025 §2 makes a client the customer runs
+ * locally the only place enrolment can happen, because whoever serves a page
+ * controls the check the page would make.
+ *
+ * WHY A SIGNER AND NOT A PRIVATE KEY. Everything in this SDK that needs a
+ * member's signature takes a {@link KeyGroupSigner} — a public key and a
+ * function that signs bytes. The SDK never needs, holds or transmits a private
+ * key, so a member can live in an HSM, a cloud KMS, a hardware token or another
+ * process, and the SDK's only job is to hand it the exact canonical bytes and
+ * check what comes back. {@link InMemorySigner} is the convenience for tests and
+ * for customers who keep keys on the machine running the SDK.
+ *
+ * CUSTODY, stated plainly because nothing recovers from getting it wrong. The
+ * private halves are the customer's alone; BurnLedger never sees them and cannot
+ * reissue them. Lose enough members that the group can no longer meet its
+ * threshold and it can neither sign a registration nor authorise its own
+ * rotation — and an operator who could re-enrol on the customer's behalf is an
+ * operator who could mint, so there is no recovery path (ADR-025 §3 "Key loss").
+ * The only way back is to enrol a NEW group and re-register every system, and
+ * records issued before and after will name different `customer_key_id`s,
+ * visibly. Hedge before it happens: enrol more members than the threshold and
+ * keep at least one offline (the simplest is two members, threshold one).
+ */
+
+import {
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as nodeSign,
+  type KeyObject,
+} from "node:crypto";
+import { nodeCrypto } from "./crypto-node.js";
+import {
+  InvalidKeyGroupError,
+  memberFingerprint,
+  validateKeyGroup,
+  type CustomerKeyGroup,
+} from "./customer-keys.js";
+
+/** One member of a key group, able to sign. */
+export interface KeyGroupSigner {
+  /** The member's raw 32-byte Ed25519 public key. */
+  readonly publicKey: Uint8Array;
+  /** Sign exactly `payload` with the member's Ed25519 key; return the 64-byte signature. */
+  sign(payload: Uint8Array): Promise<Uint8Array>;
+}
+
+// RFC 8410: an Ed25519 private key as PKCS#8 is this fixed prefix and the seed.
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const SEED_SIZE = 32;
+
+/**
+ * A member whose private key is held in this process.
+ *
+ * Convenient, and exactly as safe as the memory and disk of the machine running
+ * it. `exportSeed()` is the one way the key leaves: store the seed as you would
+ * any credential that cannot be reissued.
+ */
+export class InMemorySigner implements KeyGroupSigner {
+  readonly publicKey: Uint8Array;
+  readonly #privateKey: KeyObject;
+
+  private constructor(privateKey: KeyObject) {
+    this.#privateKey = privateKey;
+    const spki = createPublicKey(privateKey).export({ format: "der", type: "spki" });
+    this.publicKey = new Uint8Array(spki.subarray(spki.length - 32));
+  }
+
+  /** A fresh member, from the operating system's CSPRNG. */
+  static generate(): InMemorySigner {
+    return new InMemorySigner(generateKeyPairSync("ed25519").privateKey);
+  }
+
+  /** The member a 32-byte seed (as returned by `exportSeed`) describes. */
+  static fromSeed(seed: Uint8Array): InMemorySigner {
+    if (!(seed instanceof Uint8Array) || seed.length !== SEED_SIZE) {
+      throw new Error(`an Ed25519 seed is ${SEED_SIZE} bytes`);
+    }
+    return new InMemorySigner(
+      createPrivateKey({
+        key: Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(seed)]),
+        format: "der",
+        type: "pkcs8",
+      }),
+    );
+  }
+
+  /** The 32-byte seed. Whoever holds it IS this member. */
+  exportSeed(): Uint8Array {
+    const der = this.#privateKey.export({ format: "der", type: "pkcs8" });
+    return new Uint8Array(der.subarray(der.length - SEED_SIZE));
+  }
+
+  async sign(payload: Uint8Array): Promise<Uint8Array> {
+    return new Uint8Array(nodeSign(null, payload, this.#privateKey));
+  }
+}
+
+/** A freshly generated group and the signers that hold its members. */
+export interface GeneratedKeyGroup {
+  readonly group: CustomerKeyGroup;
+  readonly signers: readonly InMemorySigner[];
+}
+
+/**
+ * Generate `members` Ed25519 keys and the group requiring `threshold` of them.
+ *
+ * The private halves are returned to the caller and go nowhere else. Read the
+ * custody note at the top of this module before choosing `members` and
+ * `threshold`: a group whose members fall below its threshold is unrecoverable.
+ */
+export async function generateKeyGroup(opts: {
+  members: number;
+  threshold: number;
+}): Promise<GeneratedKeyGroup> {
+  if (!Number.isInteger(opts.members) || opts.members < 1) {
+    throw new InvalidKeyGroupError(`a key group needs at least one member, got ${opts.members}`);
+  }
+  const signers = Array.from({ length: opts.members }, () => InMemorySigner.generate());
+  const group: CustomerKeyGroup = {
+    threshold: opts.threshold,
+    members: signers.map((s) => s.publicKey),
+  };
+  await validateKeyGroup(nodeCrypto, group);
+  return { group, signers };
+}
+
+function toHex(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("hex");
+}
+
+/**
+ * Collect member signatures over `payload`, keyed by member fingerprint — the
+ * wire form every ADR-025 request carries.
+ *
+ * Refuses before anything is sent, with a reason, where the enclave would refuse
+ * after with a bare 401: a signer that is not a member of `group`, the same
+ * member twice, a signature that does not verify under the signer's own public
+ * key, or fewer distinct members than `required`.
+ */
+export async function signWithGroup(
+  payload: Uint8Array,
+  group: CustomerKeyGroup,
+  signers: readonly KeyGroupSigner[],
+  required: number,
+): Promise<Record<string, string>> {
+  const members = new Set<string>();
+  for (const member of group.members) members.add(await memberFingerprint(nodeCrypto, member));
+
+  const signatures: Record<string, string> = {};
+  for (const signer of signers) {
+    const fingerprint = await memberFingerprint(nodeCrypto, signer.publicKey);
+    if (!members.has(fingerprint)) {
+      throw new InvalidKeyGroupError(`signer ${fingerprint} is not a member of this key group`);
+    }
+    if (fingerprint in signatures) {
+      throw new InvalidKeyGroupError(`member ${fingerprint} is listed twice among the signers`);
+    }
+    const signature = await signer.sign(payload);
+    if (
+      !(signature instanceof Uint8Array) ||
+      signature.length !== 64 ||
+      !(await nodeCrypto.ed25519Verify(signer.publicKey, payload, signature))
+    ) {
+      throw new Error(
+        `the signer for member ${fingerprint} returned a signature that does not verify over the request`,
+      );
+    }
+    signatures[fingerprint] = toHex(signature);
+  }
+  const count = Object.keys(signatures).length;
+  if (count < required) {
+    throw new InvalidKeyGroupError(
+      `this request needs signatures from ${required} distinct members, got ${count}`,
+    );
+  }
+  return signatures;
+}

package/src/models.ts

@@ -153,6 +153,17 @@ export interface CertificateResponse {
    * it can be handed straight to verifyCertificateWithStatus().
    */
   readonly statusStatement: Record<string, unknown> | undefined;
+  /**
+   * Base64 AWS Nitro NSM attestation document produced while this record was
+   * signed, exactly as the server sent it. Its PCRs identify the enclave image
+   * that held the signing key and its user_data binds this record's canonical
+   * payload. Carried so it can be archived beside the record; this SDK does NOT
+   * verify it (that needs COSE ES384 and an x509 chain to the Nitro root, which
+   * only the Go verifier implements). undefined for records issued before it
+   * was recorded and for dev-mode issuance; absence is not a verification
+   * result.
+   */
+  readonly nsmAttestation: string | undefined;
 }
 
 export interface RevocationStatus {
@@ -440,6 +451,7 @@ export function parseCertificateResponse(d: Raw): CertificateResponse {
     revocationReason: d.revocation_reason ?? undefined,
     certificate: d.certificate,
     statusStatement: d.status_statement ?? undefined,
+    nsmAttestation: d.nsm_attestation ?? undefined,
   };
 }
 
@@ -624,3 +636,122 @@ export function parseSystemHealth(d: Raw): SystemHealth {
     healthError: d.health_error ?? undefined,
   };
 }
+
+// ---------------------------------------------------------------------------
+// ADR-025 documents: enrolment, team authorization, system registration
+// ---------------------------------------------------------------------------
+
+/** The enclave's statement of which key group it was told to trust for a team
+ * (core.KeyEnrollmentStatement). Trust on first use: compare `customerKeyId` —
+ * a hash over the members and threshold — against the group you hold. The SDK's
+ * enrol and rotate calls do, after verifying the enclave's signature. */
+export interface KeyEnrollmentStatement {
+  readonly assertedTeamId: string;
+  readonly customerKeyId: string;
+  readonly threshold: number;
+  readonly members: readonly Uint8Array[];
+  readonly enrolledAt: Date;
+  readonly enclavePcr0: string;
+  readonly signature: Uint8Array;
+}
+
+/** The bounded authority that makes an enrolled group usable
+ * (core.TeamAuthorizationCertificate). It expires rather than being revoked;
+ * renew it by enrolling the same group again before `notAfter`. */
+export interface TeamAuthorizationCertificate {
+  readonly assertedTeamId: string;
+  readonly customerKeyId: string;
+  readonly notBefore: Date;
+  readonly notAfter: Date;
+  /** The key this one replaced; undefined on a first enrolment. */
+  readonly prevKeyId: string | undefined;
+  readonly signature: Uint8Array;
+}
+
+/** Binds one system to the config and query it may be measured with, under a
+ * customer key (core.SystemRegistrationCertificate). No expiry: it states a
+ * fact about bytes. */
+export interface SystemRegistrationCertificate {
+  readonly systemId: string;
+  /** SHA-256 of the exact config plaintext submitted for the system. */
+  readonly configDigest: Uint8Array;
+  /** HashQuery over the NORMALIZED subject query — not the raw-template hash
+   * the registration request signs. */
+  readonly queryTemplateHash: Uint8Array;
+  readonly connectorType: string;
+  readonly customerKeyId: string;
+  readonly registeredAt: Date;
+  readonly signature: Uint8Array;
+}
+
+/** What enrolling or rotating a key group returns. */
+export interface KeyEnrollmentResult {
+  readonly enrollment: KeyEnrollmentStatement;
+  readonly authorization: TeamAuthorizationCertificate;
+}
+
+/** Go encodes [N]byte as an array of numbers; anything else here is a response
+ * this SDK cannot read, and is refused rather than coerced. */
+function bytesFromInts(v: unknown, field: string, length: number): Uint8Array {
+  if (
+    !Array.isArray(v) ||
+    v.length !== length ||
+    !v.every((b) => Number.isInteger(b) && b >= 0 && b <= 255)
+  ) {
+    throw new Error(`${field} is not ${length} bytes`);
+  }
+  return new Uint8Array(v as number[]);
+}
+
+function bytesFromBase64(v: unknown, field: string): Uint8Array {
+  if (typeof v !== "string") throw new Error(`${field} is not base64`);
+  const bin = atob(v);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function parseKeyEnrollmentStatement(d: Raw): KeyEnrollmentStatement {
+  const group = (d.group ?? {}) as Raw;
+  return {
+    assertedTeamId: d.asserted_team_id,
+    customerKeyId: d.customer_key_id,
+    threshold: group.threshold,
+    members: ((group.members ?? []) as unknown[]).map((m, i) =>
+      bytesFromBase64(m, `enrollment.group.members[${i}]`),
+    ),
+    enrolledAt: parseDt(d.enrolled_at),
+    enclavePcr0: d.enclave_pcr0,
+    signature: bytesFromInts(d.signature, "enrollment.signature", 64),
+  };
+}
+
+export function parseTeamAuthorizationCertificate(d: Raw): TeamAuthorizationCertificate {
+  return {
+    assertedTeamId: d.asserted_team_id,
+    customerKeyId: d.customer_key_id,
+    notBefore: parseDt(d.not_before),
+    notAfter: parseDt(d.not_after),
+    prevKeyId: d.prev_key_id || undefined,
+    signature: bytesFromInts(d.signature, "authorization.signature", 64),
+  };
+}
+
+export function parseSystemRegistrationCertificate(d: Raw): SystemRegistrationCertificate {
+  return {
+    systemId: d.system_id,
+    configDigest: bytesFromInts(d.config_digest, "registration.config_digest", 32),
+    queryTemplateHash: bytesFromInts(d.query_template_hash, "registration.query_template_hash", 32),
+    connectorType: d.connector_type,
+    customerKeyId: d.customer_key_id,
+    registeredAt: parseDt(d.registered_at),
+    signature: bytesFromInts(d.signature, "registration.signature", 64),
+  };
+}
+
+export function parseKeyEnrollmentResult(d: Raw): KeyEnrollmentResult {
+  return {
+    enrollment: parseKeyEnrollmentStatement(d.enrollment ?? {}),
+    authorization: parseTeamAuthorizationCertificate(d.authorization ?? {}),
+  };
+}

package/src/status-document.ts

@@ -0,0 +1,59 @@
+/** Reading a status statement as the status endpoint serves it, before anything
+ * verifies it. Shared by the CLI and the /verify page's status button, so the two
+ * agree on what counts as a statement: an answer that is not one is silence
+ * about revocation, while a statement that is one and fails is a refusal. */
+
+type StatusStatement = Record<string, unknown>;
+
+/** The API wraps every response in {"data": ...}; a caller may hand over either
+ * the envelope or the document inside it. Mirrors
+ * core.ParseCertificateStatusDocument, so this CLI and the Go one cannot
+ * disagree about which shape the endpoint returns. Exported for testing.
+ *
+ * A document that does not parse THROWS, and the caller turns that into a
+ * warning and a VALID_REVOCATION_UNKNOWN verdict. That is deliberate: an answer
+ * this build cannot read is silence about revocation, not a finding about the
+ * certificate. Handing a half-read document to the verifier instead would
+ * report "status statement signature is invalid" — a claim about the issuer —
+ * when what actually happened is that something returned nonsense.
+ *
+ * `status` itself is NOT validated against a known set. A statement saying
+ * SUSPENDED is a statement this build cannot read, and the verifier already has
+ * the right answer for that: it authenticates the signature first, then reports
+ * VALID_REVOCATION_UNKNOWN. Refusing it here would discard the statement before
+ * anyone authenticated it. */
+export function unwrapStatusStatement(parsed: unknown): StatusStatement {
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error("status statement: response is not a JSON object");
+  }
+  let doc = parsed as StatusStatement;
+  if (doc.certificate_id === undefined && doc.data !== null && typeof doc.data === "object") {
+    doc = doc.data as StatusStatement;
+  }
+  for (const f of ["certificate_id", "status", "key_id"]) {
+    if (typeof doc[f] !== "string" || doc[f] === "") throw new Error(`status statement: ${f} is missing`);
+  }
+  for (const f of ["statement_issued_at", "statement_expires_at"]) requireRfc3339(doc, f);
+  if (doc.revoked_at != null) requireRfc3339(doc, "revoked_at");
+  if (typeof doc.sth_tree_size !== "number") throw new Error("status statement: sth_tree_size is not a number");
+  // Refuse a short or long value rather than letting it through: a truncated
+  // signature or root hash that reaches the verifier is checked against bytes
+  // nobody sent.
+  requireHex(doc, "sth_root_hash", 32);
+  requireHex(doc, "signature", 64);
+  return doc;
+}
+
+function requireRfc3339(doc: StatusStatement, field: string): void {
+  const v = doc[field];
+  if (typeof v !== "string" || Number.isNaN(Date.parse(v))) {
+    throw new Error(`status statement: ${field} is not RFC 3339`);
+  }
+}
+
+function requireHex(doc: StatusStatement, field: string, bytes: number): void {
+  const v = doc[field];
+  if (typeof v !== "string" || !new RegExp(`^[0-9a-fA-F]{${bytes * 2}}$`).test(v)) {
+    throw new Error(`status statement: ${field} is not ${bytes} bytes of hex`);
+  }
+}