@bcts/spqr 1.0.0-alpha.21

package/src/proto/pq-ratchet-types.ts

@@ -0,0 +1,195 @@
+/**
+ * Copyright © 2025 Signal Messenger, LLC
+ * Copyright © 2026 Parity Technologies
+ *
+ * TypeScript interfaces matching pq_ratchet.proto exactly.
+ *
+ * NOTE: All optional properties use `| undefined` to satisfy
+ * `exactOptionalPropertyTypes: true` in tsconfig.
+ */
+
+/** PqRatchetState - top level state (proto field numbers in comments) */
+export interface PbPqRatchetState {
+  versionNegotiation?: PbVersionNegotiation | undefined; // field 1
+  chain?: PbChain | undefined; // field 2
+  v1?: PbV1State | undefined; // field 3 (oneof inner)
+}
+
+export interface PbVersionNegotiation {
+  authKey: Uint8Array; // field 1
+  direction: number; // field 2 (Direction enum)
+  minVersion: number; // field 3 (Version enum)
+  chainParams?: PbChainParams | undefined; // field 4
+}
+
+export interface PbChainParams {
+  maxJump: number; // field 1 (uint32)
+  maxOooKeys: number; // field 2 (uint32)
+}
+
+export interface PbChain {
+  direction: number; // field 1 (Direction enum)
+  currentEpoch: bigint; // field 2 (uint64)
+  links: PbEpoch[]; // field 3 (repeated)
+  nextRoot: Uint8Array; // field 4
+  sendEpoch: bigint; // field 5 (uint64)
+  params?: PbChainParams | undefined; // field 6
+}
+
+export interface PbEpoch {
+  send?: PbEpochDirection | undefined; // field 1
+  recv?: PbEpochDirection | undefined; // field 2
+}
+
+export interface PbEpochDirection {
+  ctr: number; // field 1 (uint32)
+  next: Uint8Array; // field 2 (bytes)
+  prev: Uint8Array; // field 3 (bytes)
+}
+
+export interface PbAuthenticator {
+  rootKey: Uint8Array; // field 1
+  macKey: Uint8Array; // field 2
+}
+
+export interface PbPolynomialEncoder {
+  idx: number; // field 1 (uint32)
+  pts: Uint8Array[]; // field 2 (repeated bytes)
+  polys: Uint8Array[]; // field 3 (repeated bytes)
+}
+
+export interface PbPolynomialDecoder {
+  ptsNeeded: number; // field 1 (uint32)
+  polys: number; // field 2 (uint32, always 16)
+  pts: Uint8Array[]; // field 3 (repeated bytes)
+  isComplete: boolean; // field 4 (bool)
+}
+
+/** V1Msg - wire message format */
+export interface PbV1Msg {
+  epoch: bigint; // field 1 (uint64)
+  index: number; // field 2 (uint32)
+  innerMsg?: PbV1MsgInner | undefined;
+}
+
+export type PbV1MsgInner =
+  | { type: "hdr"; chunk: PbChunk } // field 3
+  | { type: "ek"; chunk: PbChunk } // field 4
+  | { type: "ekCt1Ack"; chunk: PbChunk } // field 5
+  | { type: "ct1Ack"; value: boolean } // field 6
+  | { type: "ct1"; chunk: PbChunk } // field 7
+  | { type: "ct2"; chunk: PbChunk }; // field 8
+
+export interface PbChunk {
+  index: number; // field 1 (uint32)
+  data: Uint8Array; // field 2 (bytes, 32 bytes)
+}
+
+// V1State contains the oneof with 11 chunked states
+export interface PbV1State {
+  innerState?: PbChunkedState | undefined;
+  /** Epoch of the current state (field 12 in proto, used for deserialization) */
+  epoch?: bigint | undefined;
+}
+
+export type PbChunkedState =
+  // Send_EK states (fields 1-5 in V1State.Chunked)
+  | { type: "keysUnsampled"; uc: PbUnchunkedKeysUnsampled }
+  | { type: "keysSampled"; uc: PbUnchunkedKeysSampled; sendingHdr: PbPolynomialEncoder }
+  | {
+      type: "headerSent";
+      uc: PbUnchunkedHeaderSent;
+      sendingEk: PbPolynomialEncoder;
+      receivingCt1: PbPolynomialDecoder;
+    }
+  | { type: "ct1Received"; uc: PbUnchunkedCt1Received; sendingEk: PbPolynomialEncoder }
+  | {
+      type: "ekSentCt1Received";
+      uc: PbUnchunkedEkSentCt1Received;
+      receivingCt2: PbPolynomialDecoder;
+    }
+  // Send_CT states (fields 6-11 in V1State.Chunked)
+  | { type: "noHeaderReceived"; uc: PbUnchunkedNoHeaderReceived; receivingHdr: PbPolynomialDecoder }
+  | { type: "headerReceived"; uc: PbUnchunkedHeaderReceived; receivingEk: PbPolynomialDecoder }
+  | {
+      type: "ct1Sampled";
+      uc: PbUnchunkedCt1Sampled;
+      sendingCt1: PbPolynomialEncoder;
+      receivingEk: PbPolynomialDecoder;
+    }
+  | {
+      type: "ekReceivedCt1Sampled";
+      uc: PbUnchunkedEkReceivedCt1Sampled;
+      sendingCt1: PbPolynomialEncoder;
+    }
+  | { type: "ct1Acknowledged"; uc: PbUnchunkedCt1Acknowledged; receivingEk: PbPolynomialDecoder }
+  | { type: "ct2Sampled"; uc: PbUnchunkedCt2Sampled; sendingCt2: PbPolynomialEncoder };
+
+// Unchunked state data (carry actual KEM keys/ciphertexts)
+export interface PbUnchunkedKeysUnsampled {
+  auth?: PbAuthenticator | undefined;
+}
+
+export interface PbUnchunkedKeysSampled {
+  auth?: PbAuthenticator | undefined;
+  ek: Uint8Array;
+  dk: Uint8Array;
+  hdr: Uint8Array;
+  hdrMac: Uint8Array;
+}
+
+export interface PbUnchunkedHeaderSent {
+  auth?: PbAuthenticator | undefined;
+  ek: Uint8Array;
+  dk: Uint8Array;
+}
+
+export interface PbUnchunkedCt1Received {
+  auth?: PbAuthenticator | undefined;
+  dk: Uint8Array;
+  ct1: Uint8Array;
+}
+
+export interface PbUnchunkedEkSentCt1Received {
+  auth?: PbAuthenticator | undefined;
+  dk: Uint8Array;
+  ct1: Uint8Array;
+}
+
+export interface PbUnchunkedNoHeaderReceived {
+  auth?: PbAuthenticator | undefined;
+}
+
+export interface PbUnchunkedHeaderReceived {
+  auth?: PbAuthenticator | undefined;
+  hdr: Uint8Array;
+  es: Uint8Array;
+  ct1: Uint8Array;
+  ss: Uint8Array;
+}
+
+export interface PbUnchunkedCt1Sampled {
+  auth?: PbAuthenticator | undefined;
+  hdr: Uint8Array;
+  es: Uint8Array;
+  ct1: Uint8Array;
+}
+
+export interface PbUnchunkedEkReceivedCt1Sampled {
+  auth?: PbAuthenticator | undefined;
+  hdr: Uint8Array;
+  es: Uint8Array;
+  ek: Uint8Array;
+  ct1: Uint8Array;
+}
+
+export interface PbUnchunkedCt1Acknowledged {
+  auth?: PbAuthenticator | undefined;
+  hdr: Uint8Array;
+  es: Uint8Array;
+  ct1: Uint8Array;
+}
+
+export interface PbUnchunkedCt2Sampled {
+  auth?: PbAuthenticator | undefined;
+}

package/src/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Copyright © 2025 Signal Messenger, LLC
+ * Copyright © 2026 Parity Technologies
+ *
+ * Shared types for the SPQR protocol.
+ */
+
+/** Epoch identifier (u64 in Rust, bigint in TypeScript) */
+export type Epoch = bigint;
+
+/** Secret key material (32 bytes) */
+export type Secret = Uint8Array;
+
+/** Message key output from send/recv */
+export type MessageKey = Uint8Array | null;
+
+/** Opaque serialized state (protobuf bytes) */
+export type SerializedState = Uint8Array;
+
+/** Opaque serialized message (protobuf V1Msg bytes) */
+export type SerializedMessage = Uint8Array;
+
+/** Interface for random byte generation */
+export type RandomBytes = (length: number) => Uint8Array;
+
+/** Result of send() */
+export interface Send {
+  state: SerializedState;
+  msg: SerializedMessage;
+  key: Secret | null;
+}
+
+/** Result of recv() */
+export interface Recv {
+  state: SerializedState;
+  key: Secret | null;
+}
+
+/** Epoch secret output from state machine */
+export interface EpochSecret {
+  epoch: Epoch;
+  secret: Secret;
+}
+
+/** Parameters for initializing SPQR */
+export interface Params {
+  direction: Direction;
+  version: Version;
+  minVersion: Version;
+  authKey: Uint8Array;
+  chainParams: ChainParams;
+}
+
+/** Chain configuration parameters */
+export interface ChainParams {
+  maxJump: number;
+  maxOooKeys: number;
+}
+
+/** Protocol version */
+export enum Version {
+  V0 = 0,
+  V1 = 1,
+}
+
+/** Communication direction */
+export enum Direction {
+  A2B = 0,
+  B2A = 1,
+}
+
+/** Current version negotiation status */
+export type CurrentVersion =
+  | { type: "still_negotiating"; version: Version; minVersion: Version }
+  | { type: "negotiation_complete"; version: Version };
+
+/** Internal secret output from state transitions */
+export type SecretOutput =
+  | { type: "none" }
+  | { type: "send"; secret: Secret }
+  | { type: "recv"; secret: Secret };

package/src/util.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright © 2025 Signal Messenger, LLC
+ * Copyright © 2026 Parity Technologies
+ *
+ * Low-level utility functions for SPQR.
+ */
+
+/**
+ * Constant-time comparison of two byte arrays.
+ * Returns true if they are equal, false otherwise.
+ *
+ * Uses a XOR accumulator to avoid early-exit timing leaks.
+ *
+ * Limitation: Unlike Rust (#[inline(never)] + black_box), JavaScript
+ * cannot fully prevent JIT optimizations. In Node.js environments,
+ * callers requiring stronger guarantees should use
+ * crypto.timingSafeEqual directly.
+ */
+export function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}
+
+/** Convert a bigint to 8-byte big-endian Uint8Array */
+export function bigintToBE8(value: bigint): Uint8Array {
+  const buf = new Uint8Array(8);
+  const view = new DataView(buf.buffer);
+  view.setBigUint64(0, value, false);
+  return buf;
+}
+
+/** Convert an 8-byte big-endian Uint8Array to bigint */
+export function be8ToBigint(buf: Uint8Array): bigint {
+  const view = new DataView(buf.buffer, buf.byteOffset, 8);
+  return view.getBigUint64(0, false);
+}
+
+/** Convert a number to 4-byte big-endian Uint8Array */
+export function uint32ToBE4(value: number): Uint8Array {
+  const buf = new Uint8Array(4);
+  const view = new DataView(buf.buffer);
+  view.setUint32(0, value, false);
+  return buf;
+}
+
+/** Concatenate multiple Uint8Arrays */
+export function concat(...arrays: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const a of arrays) total += a.length;
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const a of arrays) {
+    result.set(a, offset);
+    offset += a.length;
+  }
+  return result;
+}

package/src/v1/chunked/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright © 2025 Signal Messenger, LLC
+ * Copyright © 2026 Parity Technologies
+ *
+ * Chunked state machine for SPQR V1.
+ *
+ * Provides erasure-coded chunk-by-chunk data transfer wrapping the
+ * unchunked V1 state machine.
+ */
+
+// Wire up the circular dependency factory before any re-exports
+import { _setCreateSendCtNoHeaderReceived } from "./send-ek.js";
+import { NoHeaderReceived } from "./send-ct.js";
+import type { PolyDecoder } from "../../encoding/polynomial.js";
+import type * as unchunkedSendCt from "../unchunked/send-ct.js";
+
+_setCreateSendCtNoHeaderReceived(
+  (uc: unchunkedSendCt.NoHeaderReceived, receivingHdr: PolyDecoder) =>
+    new NoHeaderReceived(uc, receivingHdr),
+);
+
+// States dispatcher
+export {
+  type States,
+  type Message,
+  type MessagePayload,
+  type SendResult,
+  type RecvResult,
+  initA,
+  initB,
+  send,
+  recv,
+} from "./states.js";
+
+// Message serialization
+export { serializeMessage, deserializeMessage } from "./message.js";
+
+// Chunked send_ek states
+export {
+  KeysUnsampled,
+  KeysSampled,
+  HeaderSent,
+  Ct1Received,
+  EkSentCt1Received,
+  type HeaderSentRecvChunk,
+  type EkSentCt1ReceivedRecvChunk,
+} from "./send-ek.js";
+
+// Chunked send_ct states
+export {
+  NoHeaderReceived,
+  HeaderReceived,
+  Ct1Sampled,
+  EkReceivedCt1Sampled,
+  Ct1Acknowledged,
+  Ct2Sampled,
+  type NoHeaderReceivedRecvChunk,
+  type Ct1SampledRecvChunk,
+  type Ct1AcknowledgedRecvChunk,
+} from "./send-ct.js";

package/src/v1/chunked/message.ts

@@ -0,0 +1,257 @@
+/**
+ * Copyright © 2025 Signal Messenger, LLC
+ * Copyright © 2026 Parity Technologies
+ *
+ * Custom binary V1 message serialization for chunked SPQR.
+ *
+ * Wire format:
+ *   [version: u8]          1 byte (V1 = 1)
+ *   [epoch: varint]        1-10 bytes (LEB128)
+ *   [index: varint]        1-5 bytes (LEB128)
+ *   [msg_type: u8]         1 byte (0=None, 1=Hdr, 2=Ek, 3=EkCt1Ack, 4=Ct1Ack, 5=Ct1, 6=Ct2)
+ *   [chunk_index: varint]  + [chunk_data: 32 bytes]  (optional, if msg_type has a chunk)
+ */
+
+import type { Chunk } from "../../encoding/polynomial.js";
+import type { Message, MessagePayload } from "./states.js";
+
+// ---------------------------------------------------------------------------
+// Message type enum
+// ---------------------------------------------------------------------------
+
+const enum MessageType {
+  None = 0,
+  Hdr = 1,
+  Ek = 2,
+  EkCt1Ack = 3,
+  Ct1Ack = 4,
+  Ct1 = 5,
+  Ct2 = 6,
+}
+
+// ---------------------------------------------------------------------------
+// Varint encoding/decoding (LEB128, matching protobuf varint)
+// ---------------------------------------------------------------------------
+
+/**
+ * Encode a bigint as LEB128 varint into the output array.
+ */
+export function encodeVarint(value: bigint, into: number[]): void {
+  let v = value;
+  if (v < 0n) v = 0n;
+  do {
+    let byte = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v > 0n) {
+      byte |= 0x80;
+    }
+    into.push(byte);
+  } while (v > 0n);
+}
+
+/**
+ * Decode a LEB128 varint from a Uint8Array at the given offset.
+ * Updates offset.offset in place.
+ */
+export function decodeVarint(from: Uint8Array, at: { offset: number }): bigint {
+  let result = 0n;
+  let shift = 0n;
+  while (shift < 70n) {
+    if (at.offset >= from.length) {
+      throw new Error("Varint: unexpected end of data");
+    }
+    const byte = from[at.offset++];
+    result |= BigInt(byte & 0x7f) << shift;
+    if ((byte & 0x80) === 0) {
+      return result;
+    }
+    shift += 7n;
+  }
+  throw new Error("Varint: too many bytes");
+}
+
+/**
+ * Encode a number (u32) as LEB128 varint into the output array.
+ */
+function encodeVarint32(value: number, into: number[]): void {
+  let v = value >>> 0;
+  do {
+    let byte = v & 0x7f;
+    v >>>= 7;
+    if (v > 0) {
+      byte |= 0x80;
+    }
+    into.push(byte);
+  } while (v > 0);
+}
+
+/**
+ * Decode a LEB128 varint as a u32 number.
+ */
+function decodeVarint32(from: Uint8Array, at: { offset: number }): number {
+  let result = 0;
+  let shift = 0;
+  while (shift < 35) {
+    if (at.offset >= from.length) {
+      throw new Error("Varint32: unexpected end of data");
+    }
+    const byte = from[at.offset++];
+    result |= (byte & 0x7f) << shift;
+    if ((byte & 0x80) === 0) {
+      return result >>> 0;
+    }
+    shift += 7;
+  }
+  throw new Error("Varint32: too many bytes");
+}
+
+// ---------------------------------------------------------------------------
+// Chunk serialization
+// ---------------------------------------------------------------------------
+
+const CHUNK_DATA_SIZE = 32;
+
+/** Encode a chunk (index varint + 32 data bytes) into the output array. */
+export function encodeChunk(chunk: Chunk, into: number[]): void {
+  encodeVarint32(chunk.index, into);
+  for (let i = 0; i < CHUNK_DATA_SIZE; i++) {
+    into.push(chunk.data[i]);
+  }
+}
+
+/** Decode a chunk from a Uint8Array at the given offset. */
+export function decodeChunk(from: Uint8Array, at: { offset: number }): Chunk {
+  const index = decodeVarint32(from, at);
+  if (at.offset + CHUNK_DATA_SIZE > from.length || index > 0xffff) {
+    throw new Error("Chunk: invalid chunk (data too short or index exceeds u16)");
+  }
+  const data = from.slice(at.offset, at.offset + CHUNK_DATA_SIZE);
+  at.offset += CHUNK_DATA_SIZE;
+  return { index, data };
+}
+
+// ---------------------------------------------------------------------------
+// Message serialization
+// ---------------------------------------------------------------------------
+
+/** Protocol version */
+const V1 = 1;
+
+/**
+ * Serialize a Message with a given sequence index into binary wire format.
+ */
+export function serializeMessage(msg: Message, index: number): Uint8Array {
+  const out: number[] = [];
+
+  // Version byte
+  out.push(V1);
+
+  // Epoch (bigint varint)
+  encodeVarint(msg.epoch, out);
+
+  // Index (u32 varint)
+  encodeVarint32(index, out);
+
+  // Message type + payload
+  const payload = msg.payload;
+  switch (payload.type) {
+    case "none":
+      out.push(MessageType.None);
+      break;
+    case "hdr":
+      out.push(MessageType.Hdr);
+      encodeChunk(payload.chunk, out);
+      break;
+    case "ek":
+      out.push(MessageType.Ek);
+      encodeChunk(payload.chunk, out);
+      break;
+    case "ekCt1Ack":
+      out.push(MessageType.EkCt1Ack);
+      encodeChunk(payload.chunk, out);
+      break;
+    case "ct1Ack":
+      out.push(MessageType.Ct1Ack);
+      // No value byte -- matches Rust wire format (Ct1Ack has no payload)
+      break;
+    case "ct1":
+      out.push(MessageType.Ct1);
+      encodeChunk(payload.chunk, out);
+      break;
+    case "ct2":
+      out.push(MessageType.Ct2);
+      encodeChunk(payload.chunk, out);
+      break;
+  }
+
+  return new Uint8Array(out);
+}
+
+/**
+ * Deserialize a Message from binary wire format.
+ */
+export function deserializeMessage(from: Uint8Array): {
+  msg: Message;
+  index: number;
+  bytesRead: number;
+} {
+  const at = { offset: 0 };
+
+  // Version byte
+  if (at.offset >= from.length) {
+    throw new Error("Message: empty data");
+  }
+  const version = from[at.offset++];
+  if (version !== V1) {
+    throw new Error(`Message: unsupported version ${version}`);
+  }
+
+  // Epoch
+  const epoch = decodeVarint(from, at);
+  if (epoch === 0n) {
+    throw new Error("Message: epoch must be > 0");
+  }
+
+  // Index
+  const index = decodeVarint32(from, at);
+
+  // Message type
+  if (at.offset >= from.length) {
+    throw new Error("Message: missing message type");
+  }
+  const msgType = from[at.offset++];
+
+  let payload: MessagePayload;
+  switch (msgType as MessageType) {
+    case MessageType.None:
+      payload = { type: "none" };
+      break;
+    case MessageType.Hdr:
+      payload = { type: "hdr", chunk: decodeChunk(from, at) };
+      break;
+    case MessageType.Ek:
+      payload = { type: "ek", chunk: decodeChunk(from, at) };
+      break;
+    case MessageType.EkCt1Ack:
+      payload = { type: "ekCt1Ack", chunk: decodeChunk(from, at) };
+      break;
+    case MessageType.Ct1Ack:
+      // No value byte -- matches Rust (hardcoded true, no data after type byte)
+      payload = { type: "ct1Ack" };
+      break;
+    case MessageType.Ct1:
+      payload = { type: "ct1", chunk: decodeChunk(from, at) };
+      break;
+    case MessageType.Ct2:
+      payload = { type: "ct2", chunk: decodeChunk(from, at) };
+      break;
+    default:
+      throw new Error(`Message: unknown message type ${msgType}`);
+  }
+
+  return {
+    msg: { epoch, payload },
+    index,
+    bytesRead: at.offset,
+  };
+}