@abaxxtech/id 0.0.0

package/src/utils/hd-key.ts

@@ -0,0 +1,58 @@
+import type { PrivateJwk, PublicJwk } from '../types/jose-types.js';
+
+import { Secp256k1 } from './secp256k1.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 Secp256k1.derivePrivateKey(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;
+  }
+}

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);
+  }
+}

package/src/utils/object.ts

@@ -0,0 +1,55 @@
+import flat from 'flat';
+
+/**
+ * Flattens the given object.
+ * e.g. `{ a: { b: { c: 42 } } }` becomes `{ 'a.b.c': 42 }`
+ */
+export function flatten(obj: unknown): Record<string, unknown> {
+  const flattened = flat.flatten<unknown, Record<string, unknown>>(obj);
+  removeEmptyObjects(flattened);
+  return flattened;
+}
+
+/**
+ * Checks whether the given object has any properties.
+ */
+export function isEmptyObject(obj: unknown): boolean {
+  if (typeof(obj) !== 'object') {
+    return false;
+  }
+
+  for (const _ in obj) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Recursively removes all properties with an empty object or array as its value from the given object.
+ */
+export function removeEmptyObjects(obj: Record<string, unknown>): void {
+  Object.keys(obj).forEach(key => {
+    if (typeof(obj[key]) === 'object') {
+      // recursive remove empty object or array properties in nested objects
+      removeEmptyObjects(obj[key] as Record<string, unknown>);
+    }
+
+    if (isEmptyObject(obj[key])) {
+      delete obj[key];
+    }
+  });
+}
+
+/**
+ * Recursively removes all properties with `undefined` as its value from the given object.
+ */
+export function removeUndefinedProperties(obj: Record<string, unknown>): void {
+  Object.keys(obj).forEach(key => {
+    if (obj[key] === undefined) {
+      delete obj[key];
+    } else if (typeof(obj[key]) === 'object') {
+      removeUndefinedProperties(obj[key] as Record<string, unknown>); // recursive remove `undefined` properties in nested objects
+    }
+  });
+}

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

@@ -0,0 +1,72 @@
+import type { PrivateJwk } from '../types/jose-types.js';
+import type { Signer } from '../types/signer.js';
+
+import { signatureAlgorithms } from '../jose/algorithms/signing/signature-algorithms.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+/**
+ * Input to `PrivateKeySigner` constructor.
+ */
+export type PrivateKeySignerOptions = {
+  /**
+   * Private JWK to create the signer from.
+   */
+  privateJwk: PrivateJwk;
+
+  /**
+   * If not specified, the constructor will attempt to default/fall back to the `kid` value in the given `privateJwk`.
+   */
+  keyId?: string;
+
+  /**
+   * If not specified, the constructor will attempt to default/fall back to the `alg` value in the given `privateJwk`.
+   */
+  algorithm?: string;
+};
+
+/**
+ * A signer that signs using a private key.
+ */
+export class PrivateKeySigner implements Signer {
+  public keyId;
+  public algorithm;
+  private privateJwk: PrivateJwk;
+  private signatureAlgorithm;
+
+  public constructor(options: PrivateKeySignerOptions) {
+    if (options.keyId === undefined && options.privateJwk.kid === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PrivateKeySignerUnableToDeduceKeyId,
+        `Unable to deduce the key ID`
+      );
+    }
+
+    // NOTE: `alg` is optional for a JWK as specified in https://datatracker.ietf.org/doc/html/rfc7517#section-4.4
+    if (options.algorithm === undefined && options.privateJwk.alg === undefined) {
+      throw new DwnError(
+        DwnErrorCode.PrivateKeySignerUnableToDeduceAlgorithm,
+        `Unable to deduce the signature algorithm`
+      );
+    }
+
+    this.keyId = options.keyId ?? options.privateJwk.kid!;
+    this.algorithm = options.algorithm ?? options.privateJwk.alg!;
+    this.privateJwk = options.privateJwk;
+    this.signatureAlgorithm = signatureAlgorithms[options.privateJwk.crv];
+
+    if (!this.signatureAlgorithm) {
+      throw new DwnError(
+        DwnErrorCode.PrivateKeySignerUnsupportedCurve,
+        `Unsupported crv ${options.privateJwk.crv}, crv must be one of ${Object.keys(signatureAlgorithms)}`
+      );
+    }
+  }
+
+  /**
+   * Signs the given content and returns the signature as bytes.
+   */
+  public async sign (content: Uint8Array): Promise<Uint8Array> {
+    const signatureBytes = await this.signatureAlgorithm.sign(content, this.privateJwk);
+    return signatureBytes;
+  }
+}

package/src/utils/protocols.ts

@@ -0,0 +1,50 @@
+import type { DerivedPrivateJwk } from '../utils/hd-key.js';
+import type { PrivateJwk } from '../types/jose-types.js';
+import type { ProtocolDefinition, ProtocolRuleSet } from '../types/protocols-types.js';
+
+import { Secp256k1 } from './secp256k1.js';
+import { HdKey, KeyDerivationScheme } from '../utils/hd-key.js';
+
+/**
+ * Class containing Protocol related utility methods.
+ */
+export class Protocols {
+  /**
+   * Derives public encryptions keys and inject it in the `$encryption` property for each protocol path segment of the given Protocol definition,
+   * then returns the final encryption-enabled protocol definition.
+   * NOTE: The original definition passed in is unmodified.
+   */
+  public static async deriveAndInjectPublicEncryptionKeys(
+    protocolDefinition: ProtocolDefinition,
+    rootKeyId: string,
+    privateJwk: PrivateJwk
+  ): Promise<ProtocolDefinition> {
+    // clone before modify
+    const encryptionEnabledProtocolDefinition = JSON.parse(JSON.stringify(protocolDefinition)) as ProtocolDefinition;
+
+    // a function that recursively creates and adds `$encryption` property to every rule set
+    async function addEncryptionProperty(ruleSet: ProtocolRuleSet, parentKey: DerivedPrivateJwk): Promise<void> {
+      for (const key in ruleSet) {
+        // if we encounter a nested rule set (a property name that doesn't begin with '$'), recursively inject the `$encryption` property
+        if (!key.startsWith('$')) {
+          const derivedPrivateKey = await HdKey.derivePrivateKey(parentKey, [key]);
+          const publicKeyJwk = await Secp256k1.getPublicJwk(derivedPrivateKey.derivedPrivateKey);
+
+          ruleSet[key].$encryption = { rootKeyId, publicKeyJwk };
+          await addEncryptionProperty(ruleSet[key], derivedPrivateKey);
+        }
+      }
+    }
+
+    // inject encryption property starting from each root level record type
+    const rootKey: DerivedPrivateJwk = {
+      derivationScheme  : KeyDerivationScheme.ProtocolPath,
+      derivedPrivateKey : privateJwk,
+      rootKeyId
+    };
+    const protocolLevelDerivedKey = await HdKey.derivePrivateKey(rootKey, [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol]);
+    await addEncryptionProperty(encryptionEnabledProtocolDefinition.structure, protocolLevelDerivedKey);
+
+    return encryptionEnabledProtocolDefinition;
+  }
+}

package/src/utils/records.ts

@@ -0,0 +1,326 @@
+import type { DerivedPrivateJwk } from './hd-key.js';
+import type { Readable } from 'readable-stream';
+import type { Filter, GenericSignaturePayload, RangeFilter } from '../types/message-types.js';
+import type { RangeCriterion, RecordsDeleteMessage, RecordsFilter, RecordsQueryMessage, RecordsReadMessage, RecordsWriteDescriptor, RecordsWriteMessage } from '../types/records-types.js';
+
+import { Encoder } from './encoder.js';
+import { Encryption } from './encryption.js';
+import { KeyDerivationScheme } from './hd-key.js';
+import { Message } from '../core/message.js';
+import { Secp256k1 } from './secp256k1.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { normalizeProtocolUrl, normalizeSchemaUrl } from './url.js';
+
+/**
+ * Class containing useful utilities related to the Records interface.
+ */
+export class Records {
+  /**
+   * Decrypts the encrypted data in a message reply using the given ancestor private key.
+   * @param ancestorPrivateKey Any ancestor private key in the key derivation path.
+   */
+  public static async decrypt(
+    recordsWrite: RecordsWriteMessage,
+    ancestorPrivateKey: DerivedPrivateJwk,
+    cipherStream: Readable
+  ): Promise<Readable> {
+    const { encryption } = recordsWrite;
+
+    // look for an encrypted symmetric key that is encrypted by the public key corresponding to the given private key
+    const matchingEncryptedKey = encryption!.keyEncryption.find(key =>
+      key.rootKeyId === ancestorPrivateKey.rootKeyId &&
+      key.derivationScheme === ancestorPrivateKey.derivationScheme
+    );
+    if (matchingEncryptedKey === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsDecryptNoMatchingKeyEncryptedFound,
+        `Unable to find a symmetric key encrypted using key \
+        with ID '${ancestorPrivateKey.rootKeyId}' and '${ancestorPrivateKey.derivationScheme}' derivation scheme.`
+      );
+    }
+
+    const fullDerivationPath = Records.constructKeyDerivationPath(matchingEncryptedKey.derivationScheme, recordsWrite);
+
+    // NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
+    // so we will assume that's the algorithm without additional switch/if statements
+    const leafPrivateKey = await Records.derivePrivateKey(ancestorPrivateKey, fullDerivationPath);
+    const encryptedKeyBytes = Encoder.base64UrlToBytes(matchingEncryptedKey.encryptedKey);
+    const ephemeralPublicKey = Secp256k1.publicJwkToBytes(matchingEncryptedKey.ephemeralPublicKey);
+    const keyEncryptionInitializationVector = Encoder.base64UrlToBytes(matchingEncryptedKey.initializationVector);
+    const messageAuthenticationCode = Encoder.base64UrlToBytes(matchingEncryptedKey.messageAuthenticationCode);
+    const dataEncryptionKey = await Encryption.eciesSecp256k1Decrypt({
+      ciphertext           : encryptedKeyBytes,
+      ephemeralPublicKey,
+      initializationVector : keyEncryptionInitializationVector,
+      messageAuthenticationCode,
+      privateKey           : leafPrivateKey
+    });
+
+
+    // NOTE: right now only `A256CTR` algorithm is supported for symmetric encryption,
+    // so we will assume that's the algorithm without additional switch/if statements
+    const dataEncryptionInitializationVector = Encoder.base64UrlToBytes(encryption!.initializationVector);
+    const plaintextStream = await Encryption.aes256CtrDecrypt(dataEncryptionKey, dataEncryptionInitializationVector, cipherStream);
+
+    return plaintextStream;
+  }
+
+  /**
+   * Constructs full key derivation path using the specified scheme.
+   */
+  public static constructKeyDerivationPath(
+    keyDerivationScheme: KeyDerivationScheme,
+    recordsWriteMessage: RecordsWriteMessage
+  ): string[] {
+
+    const descriptor = recordsWriteMessage.descriptor;
+    const contextId = recordsWriteMessage.contextId;
+
+    let fullDerivationPath;
+    if (keyDerivationScheme === KeyDerivationScheme.DataFormats) {
+      fullDerivationPath = Records.constructKeyDerivationPathUsingDataFormatsScheme(descriptor.schema, descriptor.dataFormat);
+    } else if (keyDerivationScheme === KeyDerivationScheme.ProtocolPath) {
+      fullDerivationPath = Records.constructKeyDerivationPathUsingProtocolPathScheme(descriptor);
+    } else if (keyDerivationScheme === KeyDerivationScheme.ProtocolContext) {
+      fullDerivationPath = Records.constructKeyDerivationPathUsingProtocolContextScheme(contextId);
+    } else {
+      // `schemas` scheme
+      fullDerivationPath = Records.constructKeyDerivationPathUsingSchemasScheme(descriptor.schema);
+    }
+
+    return fullDerivationPath;
+  }
+
+  /**
+   * Constructs the full key derivation path using `dataFormats` scheme.
+   */
+  public static constructKeyDerivationPathUsingDataFormatsScheme(schema: string | undefined, dataFormat: string ): string[] {
+    if (schema !== undefined) {
+      return [
+        KeyDerivationScheme.DataFormats,
+        schema, // this is as spec-ed on TP27, the intent is to support sharing the key for just a specific data type under a schema
+        dataFormat
+      ];
+    } else {
+      return [
+        KeyDerivationScheme.DataFormats,
+        dataFormat
+      ];
+    }
+  }
+
+  /**
+   * Constructs the full key derivation path using `protocolPath` scheme.
+   */
+  public static constructKeyDerivationPathUsingProtocolPathScheme(descriptor: RecordsWriteDescriptor): string[] {
+    // ensure `protocol` is defined
+    // NOTE: no need to check `protocolPath` and `contextId` because earlier code ensures that if `protocol` is defined, those are defined also
+    if (descriptor.protocol === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsProtocolPathDerivationSchemeMissingProtocol,
+        'Unable to construct key derivation path using `protocols` scheme because `protocol` is missing.'
+      );
+    }
+
+    const protocolPathSegments = descriptor.protocolPath!.split('/');
+    const fullDerivationPath = [
+      KeyDerivationScheme.ProtocolPath,
+      descriptor.protocol,
+      ...protocolPathSegments
+    ];
+
+    return fullDerivationPath;
+  }
+
+  /**
+   * Constructs the full key derivation path using `protocolContext` scheme.
+   */
+  public static constructKeyDerivationPathUsingProtocolContextScheme(contextId: string | undefined): string[] {
+    if (contextId === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsProtocolContextDerivationSchemeMissingContextId,
+        'Unable to construct key derivation path using `protocolContext` scheme because `contextId` is missing.'
+      );
+    }
+
+    const fullDerivationPath = [
+      KeyDerivationScheme.ProtocolContext,
+      contextId
+    ];
+
+    return fullDerivationPath;
+  }
+
+  /**
+   * Constructs the full key derivation path using `schemas` scheme.
+   */
+  public static constructKeyDerivationPathUsingSchemasScheme( schema: string | undefined ): string[] {
+    if (schema === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsSchemasDerivationSchemeMissingSchema,
+        'Unable to construct key derivation path using `schemas` scheme because `schema` is missing.'
+      );
+    }
+
+    const fullDerivationPath = [
+      KeyDerivationScheme.Schemas,
+      schema
+    ];
+
+    return fullDerivationPath;
+  }
+
+  /**
+   * Derives a descendant private key given an ancestor private key and the full absolute derivation path.
+   * NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
+   *       so we will only derive SECP256K1 key without additional conditional checks
+   */
+  public static async derivePrivateKey(ancestorPrivateKey: DerivedPrivateJwk, fullDescendantDerivationPath: string[]): Promise<Uint8Array> {
+    if (ancestorPrivateKey.derivedPrivateKey.crv !== 'secp256k1') {
+      throw new DwnError(
+        DwnErrorCode.RecordsDerivePrivateKeyUnSupportedCurve,
+        `Curve ${ancestorPrivateKey.derivedPrivateKey.crv} is not supported.`
+      );
+    }
+
+    const ancestorPrivateKeyDerivationPath = ancestorPrivateKey.derivationPath ?? [];
+
+    Records.validateAncestorKeyAndDescentKeyDerivationPathsMatch(ancestorPrivateKeyDerivationPath, fullDescendantDerivationPath);
+
+    const subDerivationPath = fullDescendantDerivationPath.slice(ancestorPrivateKeyDerivationPath.length);
+    const ancestorPrivateKeyBytes = Secp256k1.privateJwkToBytes(ancestorPrivateKey.derivedPrivateKey);
+    const leafPrivateKey = await Secp256k1.derivePrivateKey(ancestorPrivateKeyBytes, subDerivationPath);
+
+    return leafPrivateKey;
+  }
+
+  /**
+   * Validates that ancestor derivation path matches the descendant derivation path completely.
+   * @throws {DwnError} with `DwnErrorCode.RecordsInvalidAncestorKeyDerivationSegment` if fails validation.
+   */
+  public static validateAncestorKeyAndDescentKeyDerivationPathsMatch(
+    ancestorKeyDerivationPath: string[],
+    descendantKeyDerivationPath: string[]
+  ): void {
+    for (let i = 0; i < ancestorKeyDerivationPath.length; i++) {
+      const ancestorSegment = ancestorKeyDerivationPath[i];
+      const descendantSegment = descendantKeyDerivationPath[i];
+      if (ancestorSegment !== descendantSegment) {
+        throw new DwnError(
+          DwnErrorCode.RecordsInvalidAncestorKeyDerivationSegment,
+          `Ancestor key derivation segment '${ancestorSegment}' mismatches against the descendant key derivation segment '${descendantSegment}'.`);
+      }
+    }
+  }
+
+  /**
+   * Normalizes the protocol and schema URLs within a provided RecordsFilter and returns a copy of RecordsFilter with the modified values.
+   *
+   * @param filter incoming RecordsFilter to normalize.
+   * @returns {RecordsFilter} a copy of the incoming RecordsFilter with the normalized properties.
+   */
+  public static normalizeFilter(filter: RecordsFilter): RecordsFilter {
+    let protocol;
+    if (filter.protocol === undefined) {
+      protocol = undefined;
+    } else {
+      protocol = normalizeProtocolUrl(filter.protocol);
+    }
+
+    let schema;
+    if (filter.schema === undefined) {
+      schema = undefined;
+    } else {
+      schema = normalizeSchemaUrl(filter.schema);
+    }
+
+    return {
+      ...filter,
+      protocol,
+      schema,
+    };
+  }
+
+  /**
+   *  Converts an incoming RecordsFilter into a Filter usable by MessageStore.
+   *
+   * @param filter A RecordsFilter
+   * @returns {Filter} a generic Filter able to be used with MessageStore.
+   */
+  public static convertFilter(filter: RecordsFilter): Filter {
+    const filterCopy = { ...filter } as Filter;
+
+    const { dateCreated, datePublished, dateUpdated } = filter;
+    const dateCreatedFilter = dateCreated ? this.convertRangeCriterion(dateCreated) : undefined;
+    if (dateCreatedFilter) {
+      filterCopy.dateCreated = dateCreatedFilter;
+    }
+
+    const datePublishedFilter = datePublished ? this.convertRangeCriterion(datePublished): undefined;
+    if (datePublishedFilter) {
+      // only return published records when filtering with a datePublished range.
+      filterCopy.published = true;
+      filterCopy.datePublished = datePublishedFilter;
+    }
+
+    const messageTimestampFilter = dateUpdated ? this.convertRangeCriterion(dateUpdated) : undefined;
+    if (messageTimestampFilter) {
+      filterCopy.messageTimestamp = messageTimestampFilter;
+      delete filterCopy.dateUpdated;
+    }
+    return filterCopy as Filter;
+  }
+
+  private 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;
+  }
+
+  /**
+   * Validates the referential integrity regarding delegated grant.
+   * @param signaturePayload Decoded payload of the signature of the message. `undefined` if message is not signed.
+   *                         Usage of this property is purely for performance optimization so we don't have to decode the signature payload again.
+   */
+  public static validateDelegatedGrantReferentialIntegrity(
+    message: RecordsReadMessage | RecordsQueryMessage | RecordsWriteMessage | RecordsDeleteMessage,
+    signaturePayload: GenericSignaturePayload | undefined
+  ): void {
+    // `deletedGrantId` in the payload of the message signature and `authorDelegatedGrant` in `authorization` must both exist or be both undefined
+    const delegatedGrantIdDefined = signaturePayload?.delegatedGrantId !== undefined;
+    const authorDelegatedGrantDefined = message.authorization?.authorDelegatedGrant !== undefined;
+    if (delegatedGrantIdDefined !== authorDelegatedGrantDefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsValidateIntegrityDelegatedGrantAndIdExistenceMismatch,
+        `delegatedGrantId and authorDelegatedGrant must both exist or be undefined. \
+           delegatedGrantId defined: ${delegatedGrantIdDefined}, authorDelegatedGrant defined: ${authorDelegatedGrantDefined}`
+      );
+    }
+
+    // when delegated grant exists, the grantee (grantedTo) must be the same as the signer of the message
+    if (authorDelegatedGrantDefined) {
+      const delegatedGrant = message.authorization!.authorDelegatedGrant!;
+      const grantedTo = delegatedGrant.descriptor.grantedTo;
+      const signer = Message.getSigner(message);
+      if (grantedTo !== signer) {
+        throw new DwnError(
+          DwnErrorCode.RecordsValidateIntegrityGrantedToAndSignerMismatch,
+          `grantedTo ${grantedTo} must be the same as the signer ${signer} of the message`
+        );
+      }
+    }
+  }
+}