@bcts/spqr 1.0.0-alpha.21

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@bcts/spqr",
+  "version": "1.0.0-alpha.21",
+  "type": "module",
+  "description": "Signal's Sparse Post-Quantum Ratchet (SPQR) for TypeScript",
+  "license": "AGPL-3.0-only",
+  "author": "Parity Technologies <admin@parity.io> (https://parity.io)",
+  "homepage": "https://bcts.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paritytech/bcts",
+    "directory": "packages/spqr"
+  },
+  "bugs": {
+    "url": "https://github.com/paritytech/bcts/issues"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "spqr",
+    "post-quantum",
+    "ml-kem",
+    "ratchet",
+    "signal-protocol",
+    "erasure-coding",
+    "blockchain-commons"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@bcts/crypto": "workspace:*",
+    "@bcts/rand": "workspace:*",
+    "@noble/hashes": "^2.0.1",
+    "@noble/post-quantum": "^0.5.4"
+  },
+  "devDependencies": {
+    "@bcts/eslint": "workspace:*",
+    "@bcts/tsconfig": "workspace:*",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.2",
+    "eslint": "^10.0.2",
+    "prettier": "^3.8.1",
+    "tsdown": "^0.20.3",
+    "typedoc": "^0.28.17",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/authenticator.ts

@@ -0,0 +1,163 @@
+/**
+ * Copyright © 2025 Signal Messenger, LLC
+ * Copyright © 2026 Parity Technologies
+ *
+ * SPQR Authenticator -- HMAC-SHA256 MAC for KEM exchanges.
+ *
+ * Ported from Signal's spqr crate: authenticator.rs
+ *
+ * The Authenticator produces and verifies MACs over ciphertext and header
+ * data using HMAC-SHA256. The internal rootKey and macKey are updated
+ * via HKDF at each epoch transition.
+ *
+ * All info strings and data formats MUST match the Rust implementation exactly.
+ */
+
+import { hkdfSha256, hmacSha256 } from "./kdf.js";
+import { concat, bigintToBE8, constantTimeEqual } from "./util.js";
+import {
+  ZERO_SALT,
+  MAC_SIZE,
+  LABEL_AUTH_UPDATE,
+  LABEL_CT_MAC,
+  LABEL_HDR_MAC,
+} from "./constants.js";
+import { AuthenticatorError } from "./error.js";
+import type { Epoch } from "./types.js";
+import type { PbAuthenticator } from "./proto/pq-ratchet-types.js";
+
+// Pre-encode label strings
+const enc = new TextEncoder();
+const AUTH_UPDATE_INFO = enc.encode(LABEL_AUTH_UPDATE);
+const CT_MAC_PREFIX = enc.encode(LABEL_CT_MAC);
+const HDR_MAC_PREFIX = enc.encode(LABEL_HDR_MAC);
+
+export { MAC_SIZE };
+
+/**
+ * Authenticator manages root_key and mac_key state for producing
+ * and verifying MACs over KEM ciphertext and headers.
+ *
+ * The update operation uses HKDF:
+ *   IKM  = [rootKey || key]
+ *   Salt = ZERO_SALT (32 zeros)
+ *   Info = LABEL_AUTH_UPDATE + epoch_be8
+ *   Output: 64 bytes -> [0..32] = new rootKey, [32..64] = new macKey
+ *
+ * MAC operations use HMAC-SHA256:
+ *   Key  = macKey
+ *   Data = [label_prefix || epoch_be8 || payload]
+ */
+export class Authenticator {
+  private rootKey: Uint8Array;
+  private macKey: Uint8Array;
+
+  constructor(rootKey: Uint8Array, macKey: Uint8Array) {
+    this.rootKey = rootKey;
+    this.macKey = macKey;
+  }
+
+  /**
+   * Create a new Authenticator from a root key and initial epoch.
+   * Matches Rust: `Authenticator::new(root_key, ep)`
+   *
+   * Initializes with zero keys, then immediately updates with
+   * the provided root key and epoch.
+   */
+  static create(rootKey: Uint8Array, epoch: Epoch): Authenticator {
+    const auth = new Authenticator(new Uint8Array(32), new Uint8Array(32));
+    auth.update(epoch, rootKey);
+    return auth;
+  }
+
+  /**
+   * Update the authenticator with a new epoch and key material.
+   *
+   * HKDF(IKM=[rootKey||key], salt=ZERO_SALT, info=[label||epoch_be8], length=64)
+   *
+   * Output split: rootKey = [0..32], macKey = [32..64]
+   */
+  update(epoch: Epoch, key: Uint8Array): void {
+    // ikm = [root_key || key]
+    const ikm = concat(this.rootKey, key);
+
+    const epochBe8 = bigintToBE8(epoch);
+    const info = concat(AUTH_UPDATE_INFO, epochBe8);
+
+    const derived = hkdfSha256(ikm, ZERO_SALT, info, 64);
+    this.rootKey = derived.slice(0, 32);
+    this.macKey = derived.slice(32, 64);
+  }
+
+  /**
+   * Compute MAC over ciphertext.
+   *
+   * HMAC-SHA256(macKey, [LABEL_CT_MAC || epoch_be8 || ct])
+   */
+  macCt(epoch: Epoch, ct: Uint8Array): Uint8Array {
+    const epochBe8 = bigintToBE8(epoch);
+    const data = concat(CT_MAC_PREFIX, epochBe8, ct);
+    return hmacSha256(this.macKey, data);
+  }
+
+  /**
+   * Verify ciphertext MAC (constant-time comparison).
+   * Throws AuthenticatorError if the MAC does not match.
+   */
+  verifyCt(epoch: Epoch, ct: Uint8Array, expectedMac: Uint8Array): void {
+    const computed = this.macCt(epoch, ct);
+    if (!constantTimeEqual(computed, expectedMac)) {
+      throw new AuthenticatorError("Ciphertext MAC is invalid", "INVALID_CT_MAC");
+    }
+  }
+
+  /**
+   * Compute MAC over header (encapsulation key header).
+   *
+   * HMAC-SHA256(macKey, [LABEL_HDR_MAC || epoch_be8 || hdr])
+   */
+  macHdr(epoch: Epoch, hdr: Uint8Array): Uint8Array {
+    const epochBe8 = bigintToBE8(epoch);
+    const data = concat(HDR_MAC_PREFIX, epochBe8, hdr);
+    return hmacSha256(this.macKey, data);
+  }
+
+  /**
+   * Verify header MAC (constant-time comparison).
+   * Throws AuthenticatorError if the MAC does not match.
+   */
+  verifyHdr(epoch: Epoch, hdr: Uint8Array, expectedMac: Uint8Array): void {
+    const computed = this.macHdr(epoch, hdr);
+    if (!constantTimeEqual(computed, expectedMac)) {
+      throw new AuthenticatorError("Encapsulation key MAC is invalid", "INVALID_HDR_MAC");
+    }
+  }
+
+  /**
+   * Deep clone this authenticator.
+   */
+  clone(): Authenticator {
+    return new Authenticator(Uint8Array.from(this.rootKey), Uint8Array.from(this.macKey));
+  }
+
+  // ---- Protobuf serialization ----
+
+  /**
+   * Serialize to protobuf representation.
+   * Matches Rust Authenticator::into_pb().
+   */
+  toProto(): PbAuthenticator {
+    return {
+      rootKey: Uint8Array.from(this.rootKey),
+      macKey: Uint8Array.from(this.macKey),
+    };
+  }
+
+  /**
+   * Deserialize from protobuf representation.
+   * Matches Rust Authenticator::from_pb().
+   */
+  static fromProto(pb: PbAuthenticator): Authenticator {
+    return new Authenticator(Uint8Array.from(pb.rootKey), Uint8Array.from(pb.macKey));
+  }
+}