burnledger 0.2.2 → 0.3.0

package/src/web-verifier.ts

@@ -0,0 +1,89 @@
+/**
+ * Entry point for the public browser verifier at `website/verify/`.
+ *
+ * Imports the leaf modules directly rather than re-exporting from
+ * `index.browser.ts`: that entry pulls in the HTTP client, which imports
+ * `node:fs/promises` and cannot be bundled for a browser at all. The page needs
+ * four functions, so this exposes four functions — the surface a relying party's
+ * browser is handed is then something you can read in one screen instead of
+ * inferring from a minified artifact.
+ *
+ * Built by `scripts/build-web-verifier.mjs`. The bundle this replaces was built
+ * by hand once and never regenerated, and had drifted into disagreeing with the
+ * Go reference on 24 of 29 fixture cases — accepting relabelled timestamps and
+ * an unsigned tree_size, and rejecting genuine certificates with a non-UTC
+ * offset (#457). It also contained `ed25519Supported`, which existed in no
+ * source file anywhere in the repository.
+ */
+import { browserCrypto } from "./crypto-browser.js";
+import {
+  verifyCertificate as _verifyCertificate,
+  verifyCertificateWithStatus as _verifyCertificateWithStatus,
+  verifyTransparency as _verifyTransparency,
+  publicKeyFromHex as _publicKeyFromHex,
+} from "./verify.js";
+import type { PublicKeyInfo } from "./verify.js";
+import type { VerificationResult, TransparencyResult } from "./models.js";
+
+type Cert = Record<string, unknown>;
+
+/** Verify all signatures on a deletion certificate offline. */
+export function verifyCertificate(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<VerificationResult> {
+  return _verifyCertificate(browserCrypto, certificate, publicKeys);
+}
+
+/**
+ * Verify a certificate and, separately, what a signed statement says about its
+ * revocation. Returns "VALID_REVOCATION_UNKNOWN" when no fresh statement is
+ * supplied — never "VALID", because "not revoked" is not something an offline
+ * check can establish on its own.
+ */
+export function verifyCertificateWithStatus(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+  status?: Record<string, unknown> | null,
+  now?: Date,
+): Promise<string> {
+  return _verifyCertificateWithStatus(browserCrypto, certificate, publicKeys, status, now);
+}
+
+/** Verify the transparency proof embedded in a certificate. */
+export function verifyTransparency(
+  certificate: Cert,
+  publicKeys: Map<string, PublicKeyInfo>,
+): Promise<TransparencyResult> {
+  return _verifyTransparency(browserCrypto, certificate, publicKeys);
+}
+
+/** Construct a PublicKeyInfo from a hex-encoded Ed25519 public key. */
+export function publicKeyFromHex(
+  hexKey: string,
+  opts?: { revoked?: boolean },
+): Promise<PublicKeyInfo> {
+  return _publicKeyFromHex(browserCrypto, hexKey, opts);
+}
+
+/**
+ * Report whether this browser's WebCrypto can verify Ed25519, so the page can
+ * say "your browser cannot check this" rather than failing silently.
+ *
+ * Feature-detected by importing a well-formed SPKI key rather than sniffing the
+ * user agent: support arrived at different versions across engines, and a
+ * capability question deserves a capability answer.
+ */
+export async function ed25519Supported(): Promise<boolean> {
+  try {
+    const spki = new Uint8Array([
+      0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+      1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+      17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32,
+    ]);
+    await crypto.subtle.importKey("spki", spki.buffer as ArrayBuffer, { name: "Ed25519" }, false, ["verify"]);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/webhooks.ts

@@ -0,0 +1,76 @@
+/** Webhook signature verification for incoming BurnLedger events.
+ *
+ * The server signs webhook payloads with HMAC-SHA256 using the webhook secret.
+ * The signature is sent in the X-BurnLedger-Signature header as a hex string,
+ * and the timestamp in the X-BurnLedger-Timestamp header as an RFC3339 string.
+ *
+ * CR-M01: the signed preimage is `timestamp + "." + body`, where `timestamp` is
+ * the exact RFC3339 string from the X-BurnLedger-Timestamp header. Binding the
+ * timestamp into the MAC prevents a captured delivery from being replayed under
+ * a different timestamp. Receivers MUST also verify the timestamp is fresh (see
+ * isTimestampFresh) — the signature proves authenticity, freshness prevents
+ * replay of an old-but-validly-signed delivery.
+ *
+ * Node-only — webhooks are received server-side.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Verify that a webhook payload was signed by the expected secret.
+ *
+ * @param secret  The webhook secret (raw UTF-8, as returned by the API)
+ * @param timestamp The RFC3339 timestamp from the X-BurnLedger-Timestamp header
+ * @param body    The raw request body bytes
+ * @param signature The hex-encoded HMAC-SHA256 signature from the X-BurnLedger-Signature header
+ * @returns true if the signature is valid
+ */
+export function verifyWebhookSignature(
+  secret: string,
+  timestamp: string,
+  body: Uint8Array | string,
+  signature: string,
+): boolean {
+  if (secret.length === 0) return false;
+  if (timestamp.length === 0) return false;
+  if (signature.length === 0) return false;
+
+  // Preimage: timestamp + "." + body. An RFC3339 timestamp never contains a
+  // ".", so the field boundary is unambiguous.
+  const bodyBytes =
+    typeof body === "string" ? Buffer.from(body, "utf-8") : Buffer.from(body);
+  const expected = createHmac("sha256", secret)
+    .update(Buffer.from(`${timestamp}.`, "utf-8"))
+    .update(bodyBytes)
+    .digest();
+
+  let received: Buffer;
+  try {
+    received = Buffer.from(signature, "hex");
+  } catch {
+    return false;
+  }
+
+  if (received.length !== expected.length) return false;
+
+  return timingSafeEqual(expected, received);
+}
+
+/**
+ * Verify that the webhook timestamp is within an acceptable freshness window.
+ * Receivers MUST call this (in addition to verifyWebhookSignature) to prevent
+ * replay of an old-but-validly-signed delivery.
+ *
+ * @param timestamp The RFC3339 timestamp from the X-BurnLedger-Timestamp header
+ * @param toleranceSeconds Maximum accepted age/skew in seconds (default 300)
+ * @returns true if the timestamp parses and is within +/- tolerance of now
+ */
+export function isTimestampFresh(
+  timestamp: string,
+  toleranceSeconds: number = 300,
+): boolean {
+  const parsed = Date.parse(timestamp);
+  if (Number.isNaN(parsed)) return false;
+  const ageSeconds = Math.abs(Date.now() - parsed) / 1000;
+  return ageSeconds <= toleranceSeconds;
+}