@enbox/dwn-sdk-js 0.0.2 → 0.0.4

package/src/types/smt-types.ts

@@ -0,0 +1,95 @@
+/**
+ * Types for the Sparse Merkle Tree implementation.
+ */
+
+/**
+ * A 32-byte hash (SHA-256 output).
+ */
+export type Hash = Uint8Array;
+
+/**
+ * Represents the path through the tree as a sequence of bits derived from the key hash.
+ * Each bit determines whether to go left (0) or right (1) at each depth level.
+ */
+export type BitPath = boolean[];
+
+/**
+ * A node in the Sparse Merkle Tree.
+ *
+ * - `internal`: has left and right child hashes but no leaf data
+ * - `leaf`: has a key hash and value (the messageCid) but no children
+ * - empty subtrees are represented implicitly via precomputed default hashes
+ */
+export type SMTNode =
+  | SMTInternalNode
+  | SMTLeafNode;
+
+export type SMTInternalNode = {
+  type : 'internal';
+  leftHash : Hash;
+  rightHash : Hash;
+};
+
+export type SMTLeafNode = {
+  type : 'leaf';
+  keyHash : Hash;
+  valueCid : string;
+};
+
+/**
+ * An inclusion or non-inclusion proof for a key in the SMT.
+ *
+ * - `siblings`: the sibling hashes along the path from leaf to root
+ * - `leafNode`: the leaf node at the path (undefined if non-inclusion proof for an empty slot)
+ * - `depth`: the depth at which the proof terminates
+ */
+export type SMTProof = {
+  siblings : Hash[];
+  leafNode : SMTLeafNode | undefined;
+  depth : number;
+};
+
+/**
+ * Result of diffing two SMT roots.
+ */
+export type SMTDiffResult = {
+  /** messageCids present in the local tree but not the remote tree */
+  onlyLocal : string[];
+  /** messageCids present in the remote tree but not the local tree */
+  onlyRemote : string[];
+};
+
+/**
+ * Interface for persisting SMT nodes. Implementations can use LevelDB, SQL, or in-memory maps.
+ * Nodes are keyed by their hash. The root hash is stored separately.
+ */
+export interface SMTNodeStore {
+  open(): Promise<void>;
+  close(): Promise<void>;
+  clear(): Promise<void>;
+
+  /**
+   * Get a node by its hash. Returns undefined if not found.
+   */
+  getNode(hash: Hash): Promise<SMTNode | undefined>;
+
+  /**
+   * Store a node, keyed by its hash.
+   */
+  putNode(hash: Hash, node: SMTNode): Promise<void>;
+
+  /**
+   * Delete a node by its hash.
+   */
+  deleteNode(hash: Hash): Promise<void>;
+
+  /**
+   * Get the current root hash. Returns undefined if no root has been set.
+   */
+  getRoot(): Promise<Hash | undefined>;
+
+  /**
+   * Set the root hash.
+   */
+  setRoot(hash: Hash): Promise<void>;
+}

package/src/types/state-index.ts

@@ -0,0 +1,100 @@
+import type { Hash } from './smt-types.js';
+import type { KeyValues } from './query-types.js';
+
+/**
+ * A Sparse Merkle Tree-backed state index that tracks the set of messageCids
+ * for each tenant. Replaces the EventLog as the mechanism for sync state tracking.
+ *
+ * Key differences from EventLog:
+ * - No watermark ordering — the SMT is a set, not a log
+ * - Root hash provides O(1) "are we in sync?" comparison
+ * - Supports subtree hashing for O(log n) set reconciliation
+ * - Per-protocol sub-trees for scoped sync
+ */
+export interface StateIndex {
+  /**
+   * Opens a connection to the underlying store.
+   */
+  open(): Promise<void>;
+
+  /**
+   * Closes the connection to the underlying store.
+   */
+  close(): Promise<void>;
+
+  /**
+   * Clears all data. Mainly used for cleaning up in test environments.
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Insert a message into the state index.
+   *
+   * @param tenant - the tenant's DID
+   * @param messageCid - the CID of the message
+   * @param indexes - key-value pairs from the message (used to extract `protocol` for
+   *   per-protocol sub-tree maintenance, and stored for reverse lookup during deletion)
+   */
+  insert(tenant: string, messageCid: string, indexes: KeyValues): Promise<void>;
+
+  /**
+   * Delete messages from the state index.
+   *
+   * @param tenant - the tenant's DID
+   * @param messageCids - the CIDs of the messages to remove
+   */
+  delete(tenant: string, messageCids: string[]): Promise<void>;
+
+  /**
+   * Get the SMT root hash for a tenant's global state (all protocols).
+   *
+   * @param tenant - the tenant's DID
+   * @returns the root hash. Returns the default empty root if no messages exist.
+   */
+  getRoot(tenant: string): Promise<Hash>;
+
+  /**
+   * Get the SMT root hash for a specific protocol's state within a tenant.
+   *
+   * @param tenant - the tenant's DID
+   * @param protocol - the protocol URI
+   * @returns the root hash. Returns the default empty root if no messages exist for this protocol.
+   */
+  getProtocolRoot(tenant: string, protocol: string): Promise<Hash>;
+
+  /**
+   * Get the hash of a subtree at a given bit prefix within a tenant's global tree.
+   * Used by the sync protocol for tree walking during set reconciliation.
+   *
+   * @param tenant - the tenant's DID
+   * @param prefix - array of booleans representing the path (false=left, true=right)
+   */
+  getSubtreeHash(tenant: string, prefix: boolean[]): Promise<Hash>;
+
+  /**
+   * Get the hash of a subtree at a given bit prefix within a protocol-scoped tree.
+   *
+   * @param tenant - the tenant's DID
+   * @param protocol - the protocol URI
+   * @param prefix - array of booleans representing the path (false=left, true=right)
+   */
+  getProtocolSubtreeHash(tenant: string, protocol: string, prefix: boolean[]): Promise<Hash>;
+
+  /**
+   * Get all leaf messageCids under a given prefix in the tenant's global tree.
+   * Used by the sync protocol to enumerate leaves in a divergent subtree.
+   *
+   * @param tenant - the tenant's DID
+   * @param prefix - array of booleans representing the path
+   */
+  getLeaves(tenant: string, prefix: boolean[]): Promise<string[]>;
+
+  /**
+   * Get all leaf messageCids under a given prefix in a protocol-scoped tree.
+   *
+   * @param tenant - the tenant's DID
+   * @param protocol - the protocol URI
+   * @param prefix - array of booleans representing the path
+   */
+  getProtocolLeaves(tenant: string, protocol: string, prefix: boolean[]): Promise<string[]>;
+}

package/src/utils/cid.ts

@@ -1,9 +1,8 @@
 import * as cbor from '@ipld/dag-cbor';
 
-import type { Readable } from 'readable-stream';
-
 import { BlockstoreMock } from '../store/blockstore-mock.js';
 import { CID } from 'multiformats/cid';
+import { DataStream } from './data-stream.js';
 import { importer } from 'ipfs-unixfs-importer';
 import { sha256 } from 'multiformats/hashes/sha2';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
@@ -89,8 +88,8 @@ export class Cid {
   /**
    * @returns V1 CID of the DAG comprised by chunking data into unixfs DAG-PB encoded blocks
    */
-  public static async computeDagPbCidFromStream(dataStream: Readable): Promise<string> {
-    const asyncDataBlocks = importer([{ content: dataStream }], new BlockstoreMock(), { cidVersion: 1 });
+  public static async computeDagPbCidFromStream(dataStream: ReadableStream<Uint8Array>): Promise<string> {
+    const asyncDataBlocks = importer([{ content: DataStream.asAsyncIterable(dataStream) }], new BlockstoreMock(), { cidVersion: 1 });
 
     // NOTE: the last block contains the root CID
     let block;

package/src/utils/data-stream.ts

@@ -1,33 +1,38 @@
 import { Encoder } from './encoder.js';
-import { PassThrough, Readable } from 'readable-stream';
 
 /**
- * Utility class for readable data stream, intentionally named to disambiguate from ReadableStream, readable-stream, Readable etc.
+ * Utility class for readable data stream using Web ReadableStream API.
  */
 export class DataStream {
   /**
    * Reads the entire readable stream given into array of bytes.
+   * @throws TypeError if `readableStream` is null or undefined.
    */
-  public static async toBytes(readableStream: Readable): Promise<Uint8Array> {
-    return new Promise((resolve, reject) => {
-      const chunks: any[] = [];
-      readableStream.on('data', chunk => {
-        chunks.push(chunk);
-      });
-
-      readableStream.on('end', () => {
-        const uint8Array = DataStream.concatenateArrayOfBytes(chunks);
-        resolve(uint8Array);
-      });
-
-      readableStream.on('error', reject);
-    });
+  public static async toBytes(readableStream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+    if (readableStream == null) {
+      throw new TypeError('DataStream.toBytes(): expected a ReadableStream but received ' + readableStream);
+    }
+
+    const reader = readableStream.getReader();
+    const chunks: Uint8Array[] = [];
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) { break; }
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+
+    return DataStream.concatenateArrayOfBytes(chunks);
   }
 
   /**
    * Reads the entire readable stream and JSON parses it into an object.
    */
-  public static async toObject(readableStream: Readable): Promise<object> {
+  public static async toObject(readableStream: ReadableStream<Uint8Array>): Promise<object> {
     const contentBytes = await DataStream.toBytes(readableStream);
     const contentObject = Encoder.bytesToObject(contentBytes);
     return contentObject;
@@ -54,45 +59,77 @@ export class DataStream {
   /**
    * Creates a readable stream from the bytes given.
    */
-  public static fromBytes(bytes: Uint8Array): Readable {
+  public static fromBytes(bytes: Uint8Array): ReadableStream<Uint8Array> {
     // chunk up the bytes to simulate a more real-world like behavior
     const chunkLength = 100_000;
-    let currentIndex = 0;
-    const readableStream = new Readable({
-      read(_size): void {
-        // if this is the last chunk
-        if (currentIndex + chunkLength > bytes.length) {
-          this.push(bytes.subarray(currentIndex));
-          this.push(null);
-        } else {
-          this.push(bytes.subarray(currentIndex, currentIndex + chunkLength));
-
-          currentIndex = currentIndex + chunkLength;
+    let offset = 0;
+    return new ReadableStream({
+      pull(controller): void {
+        if (offset >= bytes.length) {
+          controller.close();
+          return;
         }
+        const end = Math.min(offset + chunkLength, bytes.length);
+        controller.enqueue(bytes.subarray(offset, end));
+        offset = end;
       }
     });
-
-    return readableStream;
   }
 
   /**
    * Creates a readable stream from the object given.
    */
-  public static fromObject(object: Record<string, any>): Readable {
+  public static fromObject(object: Record<string, any>): ReadableStream<Uint8Array> {
     const bytes = Encoder.objectToBytes(object);
     return DataStream.fromBytes(bytes);
   }
 
+  /**
+   * Adapts a Web ReadableStream into an AsyncIterable for compatibility with libraries
+   * like `ipfs-unixfs-importer` that expect `AsyncIterable<Uint8Array>`.
+   * @throws TypeError if `stream` is null or undefined.
+   */
+  public static async * asAsyncIterable(stream: ReadableStream<Uint8Array>): AsyncIterable<Uint8Array> {
+    if (stream == null) {
+      throw new TypeError('DataStream.asAsyncIterable(): expected a ReadableStream but received ' + stream);
+    }
+
+    const reader = stream.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) { break; }
+        yield value;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
   /**
    * Duplicates the given data stream into the number of streams specified so that multiple handlers can consume the same data stream.
+   * Uses the native `ReadableStream.tee()` method for 2 copies, or a custom fan-out for N copies.
    */
-  public static duplicateDataStream(dataStream: Readable, count: number): Readable[] {
-    const streams: Readable[] = [];
-    for (let i = 0; i < count; i++) {
-      const passThrough = new PassThrough();
-      dataStream.pipe(passThrough);
-      streams.push(passThrough as unknown as Readable);
+  public static duplicateDataStream(dataStream: ReadableStream<Uint8Array>, count: number): ReadableStream<Uint8Array>[] {
+    if (count < 1) {
+      return [];
+    }
+    if (count === 1) {
+      return [dataStream];
+    }
+    if (count === 2) {
+      return dataStream.tee();
+    }
+
+    // For N > 2, recursively tee: tee the stream, keep one copy, and tee the other (count - 1) times
+    const streams: ReadableStream<Uint8Array>[] = [];
+    let remaining: ReadableStream<Uint8Array> = dataStream;
+    for (let i = 0; i < count - 1; i++) {
+      const [copy, rest] = remaining.tee();
+      streams.push(copy);
+      remaining = rest;
     }
+    streams.push(remaining);
 
     return streams;
   }

package/src/utils/encryption.ts

@@ -1,6 +1,5 @@
 import * as crypto from 'crypto';
 import * as eciesjs from 'eciesjs';
-import { Readable } from 'readable-stream';
 
 // compress publicKey for message encryption
 eciesjs.ECIES_CONFIG.isEphemeralKeyCompressed = true;
@@ -12,57 +11,43 @@ export class Encryption {
   /**
    * Encrypts the given plaintext stream using AES-256-CTR algorithm.
    */
-  public static async aes256CtrEncrypt(key: Uint8Array, initializationVector: Uint8Array, plaintextStream: Readable): Promise<Readable> {
+  public static async aes256CtrEncrypt(
+    key: Uint8Array, initializationVector: Uint8Array, plaintextStream: ReadableStream<Uint8Array>
+  ): Promise<ReadableStream<Uint8Array>> {
     const cipher = crypto.createCipheriv('aes-256-ctr', key, initializationVector);
 
-    const cipherStream = new Readable({
-      read(): void { }
+    const transform = new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller): void {
+        controller.enqueue(new Uint8Array(cipher.update(chunk)));
+      },
+      flush(controller): void {
+        const finalChunk = cipher.final();
+        if (finalChunk.length > 0) { controller.enqueue(new Uint8Array(finalChunk)); }
+      }
     });
 
-    plaintextStream.on('data', (chunk) => {
-      const encryptedChunk = cipher.update(chunk);
-      cipherStream.push(encryptedChunk);
-    });
-
-    plaintextStream.on('end', () => {
-      const finalChunk = cipher.final();
-      cipherStream.push(finalChunk);
-      cipherStream.push(null);
-    });
-
-    plaintextStream.on('error', (err) => {
-      cipherStream.emit('error', err);
-    });
-
-    return cipherStream;
+    return plaintextStream.pipeThrough(transform);
   }
 
   /**
    * Decrypts the given cipher stream using AES-256-CTR algorithm.
    */
-  public static async aes256CtrDecrypt(key: Uint8Array, initializationVector: Uint8Array, cipherStream: Readable): Promise<Readable> {
+  public static async aes256CtrDecrypt(
+    key: Uint8Array, initializationVector: Uint8Array, cipherStream: ReadableStream<Uint8Array>
+  ): Promise<ReadableStream<Uint8Array>> {
     const decipher = crypto.createDecipheriv('aes-256-ctr', key, initializationVector);
 
-    const plaintextStream = new Readable({
-      read(): void { }
-    });
-
-    cipherStream.on('data', (chunk) => {
-      const decryptedChunk = decipher.update(chunk);
-      plaintextStream.push(decryptedChunk);
-    });
-
-    cipherStream.on('end', () => {
-      const finalChunk = decipher.final();
-      plaintextStream.push(finalChunk);
-      plaintextStream.push(null);
-    });
-
-    cipherStream.on('error', (err) => {
-      plaintextStream.emit('error', err);
+    const transform = new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller): void {
+        controller.enqueue(new Uint8Array(decipher.update(chunk)));
+      },
+      flush(controller): void {
+        const finalChunk = decipher.final();
+        if (finalChunk.length > 0) { controller.enqueue(new Uint8Array(finalChunk)); }
+      }
     });
 
-    return plaintextStream;
+    return cipherStream.pipeThrough(transform);
   }
 
   /**

package/src/utils/hd-key.ts

@@ -1,4 +1,4 @@
-import type { PrivateJwk, PublicJwk } from '../types/jose-types.js';
+import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
 
 import { Encoder } from './encoder.js';
 import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
@@ -23,7 +23,7 @@ export type DerivedPrivateJwk = {
   rootKeyId: string,
   derivationScheme: KeyDerivationScheme;
   derivationPath?: string[];
-  derivedPrivateKey: PrivateJwk,
+  derivedPrivateKey: PrivateKeyJwk,
 };
 
 /**
@@ -38,12 +38,12 @@ export class HdKey {
     const ancestorPrivateKey = Secp256k1.privateJwkToBytes(ancestorKey.derivedPrivateKey);
     const ancestorPrivateKeyDerivationPath = ancestorKey.derivationPath ?? [];
     const derivedPrivateKeyBytes = await HdKey.derivePrivateKeyBytes(ancestorPrivateKey, subDerivationPath);
-    const derivedPrivateJwk = await Secp256k1.privateKeyToJwk(derivedPrivateKeyBytes);
+    const derivedPrivateKeyJwk = await Secp256k1.privateKeyToJwk(derivedPrivateKeyBytes);
     const derivedDescendantPrivateKey: DerivedPrivateJwk = {
       rootKeyId         : ancestorKey.rootKeyId,
       derivationScheme  : ancestorKey.derivationScheme,
       derivationPath    : [...ancestorPrivateKeyDerivationPath, ...subDerivationPath],
-      derivedPrivateKey : derivedPrivateJwk
+      derivedPrivateKey : derivedPrivateKeyJwk
     };
 
     return derivedDescendantPrivateKey;
@@ -53,7 +53,7 @@ export class HdKey {
    * Derives a descendant public key from an ancestor private key.
    * NOTE: currently only supports SECP256K1 keys.
    */
-  public static async derivePublicKey(ancestorKey: DerivedPrivateJwk, subDerivationPath: string[]): Promise<PublicJwk> {
+  public static async derivePublicKey(ancestorKey: DerivedPrivateJwk, subDerivationPath: string[]): Promise<PublicKeyJwk> {
     const derivedDescendantPrivateKey = await HdKey.derivePrivateKey(ancestorKey, subDerivationPath);
     const derivedDescendantPublicKey = await Secp256k1.getPublicJwk(derivedDescendantPrivateKey.derivedPrivateKey);
 
@@ -82,7 +82,7 @@ export class HdKey {
 
   /**
    * Derives a key using  HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869.
-   * TODO: Consolidate HKDF implementation and usage with web5-js - https://github.com/TBD54566975/dwn-sdk-js/issues/742
+   * TODO: Consolidate HKDF implementation and usage with web5-js - https://github.com/enboxorg/enbox/issues/742
    */
   public static async deriveKeyUsingHkdf(params: {
     hashAlgorithm: 'SHA-256' | 'SHA-384' | 'SHA-512',

package/src/utils/jws.ts

@@ -1,14 +1,14 @@
 import type { GeneralJws } from '../types/jws-types.js';
+import type { MessageSigner } from '../types/signer.js';
 import type { SignatureEntry } from '../types/jws-types.js';
-import type { Signer } from '../types/signer.js';
-import type { KeyMaterial, PublicJwk } from '../types/jose-types.js';
+import type { KeyMaterial, PublicKeyJwk } from '../types/jose-types.js';
 
 import isPlainObject from 'lodash/isPlainObject.js';
 
 import { Encoder } from './encoder.js';
 import { PrivateKeySigner } from './private-key-signer.js';
-import { signatureAlgorithms } from '../jose/algorithms/signing/signature-algorithms.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { signatureAlgorithms, type SupportedCurve } from '../jose/algorithms/signing/signature-algorithms.js';
 
 
 /**
@@ -36,8 +36,8 @@ export class Jws {
    * Verifies the signature against the given payload.
    * @returns `true` if signature is valid; `false` otherwise
    */
-  public static async verifySignature(base64UrlPayload: string, signatureEntry: SignatureEntry, jwkPublic: PublicJwk): Promise<boolean> {
-    const signatureAlgorithm = signatureAlgorithms[jwkPublic.crv];
+  public static async verifySignature(base64UrlPayload: string, signatureEntry: SignatureEntry, jwkPublic: PublicKeyJwk): Promise<boolean> {
+    const signatureAlgorithm = signatureAlgorithms[('crv' in jwkPublic ? jwkPublic.crv : undefined) as SupportedCurve];
 
     if (!signatureAlgorithm) {
       throw new DwnError(DwnErrorCode.JwsVerifySignatureUnsupportedCrv, `unsupported crv. crv must be one of ${Object.keys(signatureAlgorithms)}`);
@@ -76,17 +76,17 @@ export class Jws {
   }
 
   /**
-   * Creates a Signer[] from the given Personas.
+   * Creates a MessageSigner[] from the given Personas.
    */
-  public static createSigners(keyMaterials: KeyMaterial[]): Signer[] {
+  public static createSigners(keyMaterials: KeyMaterial[]): MessageSigner[] {
     const signers = keyMaterials.map((keyMaterial) => Jws.createSigner(keyMaterial));
     return signers;
   }
 
   /**
-   * Creates a Signer from the given Persona.
+   * Creates a MessageSigner from the given Persona.
    */
-  public static createSigner(keyMaterial: KeyMaterial): Signer {
+  public static createSigner(keyMaterial: KeyMaterial): MessageSigner {
     const privateJwk = keyMaterial.keyPair.privateJwk;
     const keyId = keyMaterial.keyId;
     const signer = new PrivateKeySigner({ privateJwk, keyId });

package/src/utils/private-key-signer.ts

@@ -1,8 +1,8 @@
-import type { PrivateJwk } from '../types/jose-types.js';
-import type { Signer } from '../types/signer.js';
+import type { MessageSigner } from '../types/signer.js';
+import type { PrivateKeyJwk } from '../types/jose-types.js';
 
-import { signatureAlgorithms } from '../jose/algorithms/signing/signature-algorithms.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { signatureAlgorithms, type SupportedCurve } from '../jose/algorithms/signing/signature-algorithms.js';
 
 /**
  * Input to `PrivateKeySigner` constructor.
@@ -11,7 +11,7 @@ export type PrivateKeySignerOptions = {
   /**
    * Private JWK to create the signer from.
    */
-  privateJwk: PrivateJwk;
+  privateJwk: PrivateKeyJwk;
 
   /**
    * If not specified, the constructor will attempt to default/fall back to the `kid` value in the given `privateJwk`.
@@ -27,10 +27,10 @@ export type PrivateKeySignerOptions = {
 /**
  * A signer that signs using a private key.
  */
-export class PrivateKeySigner implements Signer {
+export class PrivateKeySigner implements MessageSigner {
   public keyId;
   public algorithm;
-  private privateJwk: PrivateJwk;
+  private privateJwk: PrivateKeyJwk;
   private signatureAlgorithm;
 
   public constructor(options: PrivateKeySignerOptions) {
@@ -52,12 +52,13 @@ export class PrivateKeySigner implements Signer {
     this.keyId = options.keyId ?? options.privateJwk.kid!;
     this.algorithm = options.algorithm ?? options.privateJwk.alg!;
     this.privateJwk = options.privateJwk;
-    this.signatureAlgorithm = signatureAlgorithms[options.privateJwk.crv];
+    const crv = 'crv' in options.privateJwk ? options.privateJwk.crv : undefined;
+    this.signatureAlgorithm = signatureAlgorithms[crv as SupportedCurve];
 
     if (!this.signatureAlgorithm) {
       throw new DwnError(
         DwnErrorCode.PrivateKeySignerUnsupportedCurve,
-        `Unsupported crv ${options.privateJwk.crv}, crv must be one of ${Object.keys(signatureAlgorithms)}`
+        `Unsupported crv ${crv}, crv must be one of ${Object.keys(signatureAlgorithms)}`
       );
     }
   }