@enbox/dwn-sdk-js 0.0.1

package/src/utils/encoder.ts

@@ -0,0 +1,54 @@
+import { base64url } from 'multiformats/bases/base64';
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * Utility class for encoding/converting data into various formats.
+ */
+export class Encoder {
+
+  public static base64UrlToBytes(base64urlString: string): Uint8Array {
+    const content = base64url.baseDecode(base64urlString);
+    return content;
+  }
+
+  public static base64UrlToObject(base64urlString: string): any {
+    const payloadBytes = base64url.baseDecode(base64urlString);
+    const payloadObject = Encoder.bytesToObject(payloadBytes);
+    return payloadObject;
+  }
+
+  public static bytesToBase64Url(bytes: Uint8Array): string {
+    const base64UrlString = base64url.baseEncode(bytes);
+    return base64UrlString;
+  }
+
+  public static bytesToString(content: Uint8Array): string {
+    const bytes = textDecoder.decode(content);
+    return bytes;
+  }
+
+  public static bytesToObject(content: Uint8Array): object {
+    const contentString = Encoder.bytesToString(content);
+    const contentObject = JSON.parse(contentString);
+    return contentObject;
+  }
+
+  public static objectToBytes(obj: Record<string, any>): Uint8Array {
+    const objectString = JSON.stringify(obj);
+    const objectBytes = textEncoder.encode(objectString);
+    return objectBytes;
+  }
+
+  public static stringToBase64Url(content: string): string {
+    const bytes = textEncoder.encode(content);
+    const base64UrlString = base64url.baseEncode(bytes);
+    return base64UrlString;
+  }
+
+  public static stringToBytes(content: string): Uint8Array {
+    const bytes = textEncoder.encode(content);
+    return bytes;
+  }
+}

package/src/utils/encryption.ts

@@ -0,0 +1,145 @@
+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;
+
+/**
+ * Utility class for performing common, non-DWN specific encryption operations.
+ */
+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> {
+    const cipher = crypto.createCipheriv('aes-256-ctr', key, initializationVector);
+
+    const cipherStream = new Readable({
+      read(): void { }
+    });
+
+    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;
+  }
+
+  /**
+   * Decrypts the given cipher stream using AES-256-CTR algorithm.
+   */
+  public static async aes256CtrDecrypt(key: Uint8Array, initializationVector: Uint8Array, cipherStream: Readable): Promise<Readable> {
+    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);
+    });
+
+    return plaintextStream;
+  }
+
+  /**
+   * Encrypts the given plaintext using ECIES (Elliptic Curve Integrated Encryption Scheme)
+   * with SECP256K1 for the asymmetric calculations, HKDF as the key-derivation function,
+   * and AES-GCM for the symmetric encryption and MAC algorithms.
+   */
+  public static async eciesSecp256k1Encrypt(publicKeyBytes: Uint8Array, plaintext: Uint8Array): Promise<EciesEncryptionOutput> {
+    // underlying library requires Buffer as input
+    const publicKey = Buffer.from(publicKeyBytes);
+    const plaintextBuffer = Buffer.from(plaintext);
+
+    const cryptogram = eciesjs.encrypt(publicKey, plaintextBuffer);
+
+    // split cryptogram returned into constituent parts
+    let start = 0;
+    let end = Encryption.isEphemeralKeyCompressed ? 33 : 65;
+    const ephemeralPublicKey = cryptogram.subarray(start, end);
+
+    start = end;
+    end += eciesjs.ECIES_CONFIG.symmetricNonceLength;
+    const initializationVector = cryptogram.subarray(start, end);
+
+    start = end;
+    end += 16; // eciesjs.consts.AEAD_TAG_LENGTH
+    const messageAuthenticationCode = cryptogram.subarray(start, end);
+
+    const ciphertext = cryptogram.subarray(end);
+
+    return {
+      ciphertext,
+      ephemeralPublicKey,
+      initializationVector,
+      messageAuthenticationCode
+    };
+  }
+
+  /**
+   * Decrypt the given plaintext using ECIES (Elliptic Curve Integrated Encryption Scheme)
+   * with SECP256K1 for the asymmetric calculations, HKDF as the key-derivation function,
+   * and AES-GCM for the symmetric encryption and MAC algorithms.
+   */
+  public static async eciesSecp256k1Decrypt(input: EciesEncryptionInput): Promise<Uint8Array> {
+    // underlying library requires Buffer as input
+    const privateKeyBuffer = Buffer.from(input.privateKey);
+    const eciesEncryptionOutput = Buffer.concat([
+      input.ephemeralPublicKey,
+      input.initializationVector,
+      input.messageAuthenticationCode,
+      input.ciphertext
+    ]);
+
+    const plaintext = eciesjs.decrypt(privateKeyBuffer, eciesEncryptionOutput);
+
+    return plaintext;
+  }
+
+  /**
+   * Expose eciesjs library configuration
+   */
+  static get isEphemeralKeyCompressed():boolean {
+    return eciesjs.ECIES_CONFIG.isEphemeralKeyCompressed;
+  }
+}
+
+export type EciesEncryptionOutput = {
+  initializationVector: Uint8Array;
+  ephemeralPublicKey: Uint8Array;
+  ciphertext: Uint8Array;
+  messageAuthenticationCode: Uint8Array;
+};
+
+export type EciesEncryptionInput = EciesEncryptionOutput & {
+  privateKey: Uint8Array;
+};
+
+export enum EncryptionAlgorithm {
+  Aes256Ctr = 'A256CTR',
+  EciesSecp256k1 = 'ECIES-ES256K'
+}

package/src/utils/filter.ts

@@ -0,0 +1,245 @@
+import type { EqualFilter, Filter, FilterValue, KeyValues, OneOfFilter, RangeCriterion, RangeFilter, RangeValue } from '../types/query-types.js';
+
+/**
+ * A Utility class to help match indexes against filters.
+ */
+export class FilterUtility {
+  /**
+   * Matches the given key values against an array of filters, if any of the filters match, returns true.
+   *
+   * @returns true if any of the filters match.
+   */
+  static matchAnyFilter(keyValues: KeyValues, orFilters: Filter[]): boolean {
+    if (orFilters.length === 0) {
+      return true;
+    }
+
+    for (const filter of orFilters) {
+      // if any of the filters match the indexed values, we return true as it's a match
+      if (this.matchFilter(keyValues, filter)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Evaluates the given filter against the indexed values.
+   *
+   * @param indexedValues the indexed values for an item.
+   * @param filter
+   * @returns true if all of the filter properties match.
+   */
+  public static matchFilter(indexedValues: KeyValues, filter: Filter): boolean {
+
+    // we loop through each of the filter properties to check against the indexed values.
+    // if any of them do not match we return false.
+    for (const filterProperty in filter) {
+      const filterValue = filter[filterProperty];
+      const indexValue = indexedValues[filterProperty];
+      if (indexValue === undefined) {
+        return false;
+      }
+
+      const matched = Array.isArray(indexValue) ?
+        this.matchAnyIndexValue(filterValue, indexValue) :
+        this.matchIndexValue(filterValue, indexValue);
+
+      if (!matched) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Returns true if any of the index values match the filter.
+   *
+   * @param filterValue the filter for a particular property.
+   * @param indexValues an array of values to match the filter against.
+   */
+  private static matchAnyIndexValue(filterValue: FilterValue, indexValues: string[] | number[] | boolean[]): boolean {
+    for (const indexValue of indexValues) {
+      if (this.matchIndexValue(filterValue, indexValue)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Returns true if the filter matches the given index value.
+   *
+   * @param filterValue the filter for a particular property.
+   * @param indexValue a single value to match the filter against.
+   */
+  private static matchIndexValue(filterValue: FilterValue, indexValue: string | number | boolean) : boolean {
+    if (typeof filterValue === 'object') {
+      if (Array.isArray(filterValue)) {
+        // if `filterValue` is an array, it is a OneOfFilter
+        // Support OR matches by querying for each values separately,
+        if (this.matchOneOf(filterValue, indexValue)) {
+          return true;
+        }
+      } else {
+        // `filterValue` is a `RangeFilter`
+        // range filters cannot range over booleans
+        if (this.matchRange(filterValue, indexValue as RangeValue)) {
+          return true;
+        }
+      }
+    } else {
+      // filterValue is an EqualFilter, meaning it is a non-object primitive type
+      if (indexValue === filterValue) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Evaluates a OneOfFilter given an indexedValue extracted from the index.
+   *
+   * @param filter An array of EqualFilters. Treated as an OR.
+   * @param indexedValue the indexed value being compared.
+   * @returns true if any of the given filters match the indexedValue
+   */
+  private static matchOneOf(filter: OneOfFilter, indexedValue: string | number | boolean): boolean {
+    for (const orFilterValue of filter) {
+      if (indexedValue === orFilterValue) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Evaluates if the given indexedValue is within the range given by the RangeFilter.
+   *
+   * @returns true if all of the range filter conditions are met.
+   */
+  private static matchRange(rangeFilter: RangeFilter, indexedValue: string | number): boolean {
+    if (rangeFilter.lt !== undefined && indexedValue >= rangeFilter.lt) {
+      return false;
+    }
+    if (rangeFilter.lte !== undefined && indexedValue > rangeFilter.lte) {
+      return false;
+    }
+    if (rangeFilter.gt !== undefined && indexedValue <= rangeFilter.gt) {
+      return false;
+    }
+    if (rangeFilter.gte !== undefined && indexedValue < rangeFilter.gte) {
+      return false;
+    }
+    return true;
+  }
+
+  static isEqualFilter(filter: FilterValue): filter is EqualFilter {
+    if (typeof filter !== 'object') {
+      return true;
+    }
+    return false;
+  }
+
+  static isRangeFilter(filter: FilterValue): filter is RangeFilter {
+    if (typeof filter === 'object' && !Array.isArray(filter)) {
+      return 'gt' in filter || 'lt' in filter || 'lte' in filter || 'gte' in filter;
+    };
+    return false;
+  }
+
+  static isOneOfFilter(filter: FilterValue): filter is OneOfFilter {
+    if (typeof filter === 'object' && Array.isArray(filter)) {
+      return true;
+    };
+    return false;
+  }
+
+  static convertRangeCriterion(inputFilter: RangeCriterion): RangeFilter | undefined {
+    let rangeFilter: RangeFilter | undefined;
+    if (inputFilter.to !== undefined && inputFilter.from !== undefined) {
+      rangeFilter = {
+        gte : inputFilter.from,
+        lt  : inputFilter.to,
+      };
+    } else if (inputFilter.to !== undefined) {
+      rangeFilter = {
+        lt: inputFilter.to,
+      };
+    } else if (inputFilter.from !== undefined) {
+      rangeFilter = {
+        gte: inputFilter.from,
+      };
+    }
+    return rangeFilter;
+  }
+
+  static constructPrefixFilterAsRangeFilter(prefix: string): RangeFilter {
+    return {
+      gte : prefix,
+      lt  : prefix + '\uffff',
+    };
+  }
+
+}
+
+export class FilterSelector {
+
+  /**
+   * Reduce Filter so that it is a filter that can be quickly executed against the DB.
+   */
+  static reduceFilter(filter: Filter): Filter {
+    // if there is only one or no property, we have no way to reduce it further
+    const filterProperties = Object.keys(filter);
+    if (filterProperties.length <= 1) {
+      return filter;
+    }
+
+    // else there is are least 2 filter properties, since zero property is not allowed
+
+    const { recordId, attester, parentId, recipient, contextId, author, protocolPath, schema, protocol, ...remainingProperties } = filter;
+
+    if (recordId !== undefined) {
+      return { recordId };
+    }
+
+    if (attester !== undefined) {
+      return { attester };
+    }
+
+    if (parentId !== undefined) {
+      return { parentId };
+    }
+
+    if (recipient !== undefined) {
+      return { recipient };
+    }
+
+    if (contextId !== undefined) {
+      return { contextId };
+    }
+
+    if (protocolPath !== undefined) {
+      return { protocolPath };
+    }
+
+    if (schema !== undefined) {
+      return { schema };
+    }
+
+    if (protocol !== undefined) {
+      return { protocol };
+    }
+
+    // else just return whatever property, we can optimize further later
+    const remainingPropertyNames = Object.keys(remainingProperties);
+    const firstRemainingProperty = remainingPropertyNames[0];
+    const singlePropertyFilter: Filter = {};
+    singlePropertyFilter[firstRemainingProperty] = filter[firstRemainingProperty];
+    return singlePropertyFilter;
+  }
+}

package/src/utils/hd-key.ts

@@ -0,0 +1,126 @@
+import type { PrivateJwk, PublicJwk } from '../types/jose-types.js';
+
+import { Encoder } from './encoder.js';
+import { getWebcryptoSubtle } from '@noble/ciphers/webcrypto';
+import { Secp256k1 } from './secp256k1.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+export enum KeyDerivationScheme {
+  /**
+   * Key derivation using the `dataFormat` value for Flat-space records.
+   */
+  DataFormats = 'dataFormats',
+  ProtocolContext = 'protocolContext',
+  ProtocolPath = 'protocolPath',
+
+  /**
+   * Key derivation using the `schema` value for Flat-space records.
+   */
+  Schemas = 'schemas'
+}
+
+export type DerivedPrivateJwk = {
+  rootKeyId: string,
+  derivationScheme: KeyDerivationScheme;
+  derivationPath?: string[];
+  derivedPrivateKey: PrivateJwk,
+};
+
+/**
+ * Class containing hierarchical deterministic key related utility methods used by the DWN.
+ */
+export class HdKey {
+  /**
+   * Derives a descendant private key.
+   * NOTE: currently only supports SECP256K1 keys.
+   */
+  public static async derivePrivateKey(ancestorKey: DerivedPrivateJwk, subDerivationPath: string[]): Promise<DerivedPrivateJwk> {
+    const ancestorPrivateKey = Secp256k1.privateJwkToBytes(ancestorKey.derivedPrivateKey);
+    const ancestorPrivateKeyDerivationPath = ancestorKey.derivationPath ?? [];
+    const derivedPrivateKeyBytes = await HdKey.derivePrivateKeyBytes(ancestorPrivateKey, subDerivationPath);
+    const derivedPrivateJwk = await Secp256k1.privateKeyToJwk(derivedPrivateKeyBytes);
+    const derivedDescendantPrivateKey: DerivedPrivateJwk = {
+      rootKeyId         : ancestorKey.rootKeyId,
+      derivationScheme  : ancestorKey.derivationScheme,
+      derivationPath    : [...ancestorPrivateKeyDerivationPath, ...subDerivationPath],
+      derivedPrivateKey : derivedPrivateJwk
+    };
+
+    return derivedDescendantPrivateKey;
+  }
+
+  /**
+   * 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> {
+    const derivedDescendantPrivateKey = await HdKey.derivePrivateKey(ancestorKey, subDerivationPath);
+    const derivedDescendantPublicKey = await Secp256k1.getPublicJwk(derivedDescendantPrivateKey.derivedPrivateKey);
+
+    return derivedDescendantPublicKey;
+  }
+
+  /**
+   * Derives a hardened hierarchical deterministic private key.
+   */
+  public static async derivePrivateKeyBytes(privateKey: Uint8Array, relativePath: string[]): Promise<Uint8Array> {
+    HdKey.validateKeyDerivationPath(relativePath);
+
+    let currentPrivateKey = privateKey;
+    for (const segment of relativePath) {
+      const segmentBytes = Encoder.stringToBytes(segment);
+      currentPrivateKey = await HdKey.deriveKeyUsingHkdf({
+        hashAlgorithm      : 'SHA-256',
+        initialKeyMaterial : currentPrivateKey,
+        info               : segmentBytes, // use the segment as the application specific info for key derivation
+        keyLengthInBytes   : 32 // 32 bytes = 256 bits
+      });
+    }
+
+    return currentPrivateKey;
+  }
+
+  /**
+   * 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
+   */
+  public static async deriveKeyUsingHkdf(params: {
+    hashAlgorithm: 'SHA-256' | 'SHA-384' | 'SHA-512',
+    initialKeyMaterial: Uint8Array,
+    info: Uint8Array,
+    keyLengthInBytes: number
+  }): Promise<Uint8Array> {
+    const { hashAlgorithm, initialKeyMaterial, info, keyLengthInBytes } = params;
+
+    const webCrypto = getWebcryptoSubtle() as SubtleCrypto;
+
+    // Import the `initialKeyMaterial` into the Web Crypto API to use for the key derivation operation.
+    const webCryptoKey = await webCrypto.importKey('raw', initialKeyMaterial, { name: 'HKDF' }, false, ['deriveBits']);
+
+    // Derive the bytes using the Web Crypto API.
+    const derivedKeyBuffer = await crypto.subtle.deriveBits(
+      {
+        name : 'HKDF',
+        hash : hashAlgorithm,
+        salt : new Uint8Array(0), // `info` should be sufficient in our use case
+        info
+      },
+      webCryptoKey,
+      keyLengthInBytes * 8 // convert from bytes to bits
+    );
+
+    // Convert from ArrayBuffer to Uint8Array.
+    const derivedKeyBytes = new Uint8Array(derivedKeyBuffer);
+    return derivedKeyBytes;
+  }
+
+  /**
+   * Validates that no empty strings exist within the derivation path segments array.
+   * @throws {DwnError} with `DwnErrorCode.HdKeyDerivationPathInvalid` if derivation path fails validation.
+   */
+  private static validateKeyDerivationPath(pathSegments: string[]): void {
+    if (pathSegments.includes('')) {
+      throw new DwnError(DwnErrorCode.HdKeyDerivationPathInvalid, `Invalid key derivation path: ${pathSegments}`);
+    }
+  }
+}

package/src/utils/jws.ts

@@ -0,0 +1,95 @@
+import type { GeneralJws } from '../types/jws-types.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 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';
+
+
+/**
+ * Utility class for JWS related operations.
+ */
+export class Jws {
+  /**
+   * Gets the `kid` from a general JWS signature entry.
+   */
+  public static getKid(signatureEntry: SignatureEntry): string {
+    const { kid } = Encoder.base64UrlToObject(signatureEntry.protected);
+    return kid;
+  }
+
+  /**
+   * Gets the signer DID from a general JWS signature entry.
+   */
+  public static getSignerDid(signatureEntry: SignatureEntry): string {
+    const kid = Jws.getKid(signatureEntry);
+    const did = Jws.extractDid(kid);
+    return did;
+  }
+
+  /**
+   * 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];
+
+    if (!signatureAlgorithm) {
+      throw new DwnError(DwnErrorCode.JwsVerifySignatureUnsupportedCrv, `unsupported crv. crv must be one of ${Object.keys(signatureAlgorithms)}`);
+    }
+
+    const payload = Encoder.stringToBytes(`${signatureEntry.protected}.${base64UrlPayload}`);
+    const signatureBytes = Encoder.base64UrlToBytes(signatureEntry.signature);
+
+    return await signatureAlgorithm.verify(payload, signatureBytes, jwkPublic);
+  }
+
+  /**
+   * Decodes the payload of the given JWS object as a plain object.
+   */
+  public static decodePlainObjectPayload(jws: GeneralJws): any {
+    let payloadJson;
+    try {
+      payloadJson = Encoder.base64UrlToObject(jws.payload);
+    } catch {
+      throw new DwnError(DwnErrorCode.JwsDecodePlainObjectPayloadInvalid, 'payload is not a JSON object');
+    }
+
+    if (!isPlainObject(payloadJson)) {
+      throw new DwnError(DwnErrorCode.JwsDecodePlainObjectPayloadInvalid, 'signed payload must be a plain object');
+    }
+
+    return payloadJson;
+  }
+
+  /**
+   * Extracts the DID from the given `kid` string.
+   */
+  public static extractDid(kid: string): string {
+    const [ did ] = kid.split('#');
+    return did;
+  }
+
+  /**
+   * Creates a Signer[] from the given Personas.
+   */
+  public static createSigners(keyMaterials: KeyMaterial[]): Signer[] {
+    const signers = keyMaterials.map((keyMaterial) => Jws.createSigner(keyMaterial));
+    return signers;
+  }
+
+  /**
+   * Creates a Signer from the given Persona.
+   */
+  public static createSigner(keyMaterial: KeyMaterial): Signer {
+    const privateJwk = keyMaterial.keyPair.privateJwk;
+    const keyId = keyMaterial.keyId;
+    const signer = new PrivateKeySigner({ privateJwk, keyId });
+    return signer;
+  }
+}

package/src/utils/memory-cache.ts

@@ -0,0 +1,31 @@
+import type { Cache } from '../types/cache.js';
+import { LRUCache } from 'lru-cache';
+
+/**
+ * A cache using local memory.
+ */
+export class MemoryCache implements Cache {
+  private cache: LRUCache<string, any>;
+
+  /**
+   * @param timeToLiveInSeconds time-to-live for every key-value pair set in the cache
+   */
+  public constructor (private timeToLiveInSeconds: number) {
+    this.cache = new LRUCache({
+      max : 100_000,
+      ttl : timeToLiveInSeconds * 1000
+    });
+  }
+
+  async set(key: string, value: any): Promise<void> {
+    try {
+      this.cache.set(key, value);
+    } catch {
+      // let the code continue as this is a non-fatal error
+    }
+  }
+
+  async get(key: string): Promise<any | undefined> {
+    return this.cache.get(key);
+  }
+}