@enbox/dwn-sdk-js 0.0.1

package/src/utils/messages.ts

@@ -0,0 +1,109 @@
+import type { Filter } from '../types/query-types.js';
+import type { MessagesFilter } from '../types/messages-types.js';
+
+import { FilterUtility } from './filter.js';
+import { normalizeProtocolUrl } from './url.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { Records } from './records.js';
+import { isEmptyObject, removeUndefinedProperties } from './object.js';
+
+
+/**
+ * Class containing Messages related utility methods.
+ */
+export class Messages {
+  /**
+   * Normalizes/fixes the formatting of the given filters (such as URLs) so that they provide a consistent search experience.
+   */
+  public static normalizeFilters(filters: MessagesFilter[]): MessagesFilter[] {
+
+    const messagesQueryFilters: MessagesFilter[] = [];
+
+    // normalize each filter, and only add non-empty filters to the returned array
+    for (const filter of filters) {
+      // normalize the protocol URL if it exists
+      const protocol = filter.protocol !== undefined ? normalizeProtocolUrl(filter.protocol) : undefined;
+
+      const messagesFilter = {
+        ...filter,
+        protocol,
+      };
+
+      // remove any empty filter properties and do not add if empty
+      removeUndefinedProperties(messagesFilter);
+      if (!isEmptyObject(messagesFilter)) {
+        messagesQueryFilters.push(messagesFilter);
+      }
+    }
+
+    return messagesQueryFilters;
+  }
+
+  /**
+   *  Converts an incoming array of MessagesFilter into an array of Filter usable by MessageLog.
+   *
+   * @param filters An array of MessagesFilter
+   * @returns {Filter[]} an array of generic Filter able to be used when querying.
+   */
+  public static convertFilters(filters: MessagesFilter[]): Filter[] {
+
+    const messagesQueryFilters: Filter[] = [];
+
+    // convert each filter individually by the specific type of filter it is
+    // we must check for the type of filter in a specific order to make a reductive decision as to which filters need converting
+    // first we check for `MessagesRecordsFilter` fields for conversion
+    // otherwise it is `MessagesMessageFilter` fields for conversion
+    for (const filter of filters) {
+      // extract the protocol tag filter from the incoming message record filter
+      // this filters for permission grants, requests and revocations associated with a targeted protocol
+      // since permissions are their own protocol, we added an additional tag index when writing the permission messages
+      // so that we can filter for permission records here
+      const permissionRecordsFilter = this.constructPermissionRecordsFilter(filter);
+      if (permissionRecordsFilter) {
+        messagesQueryFilters.push(permissionRecordsFilter);
+      }
+
+      messagesQueryFilters.push(this.convertFilter(filter));
+    }
+
+    return messagesQueryFilters;
+  }
+
+  /**
+   * Constructs a filter that gets associated permission records if protocol is in the given filter.
+   */
+  private static constructPermissionRecordsFilter(filter: MessagesFilter): Filter | undefined {
+    const { protocol, messageTimestamp } = filter;
+    if (protocol !== undefined) {
+      const taggedFilter = {
+        protocol: PermissionsProtocol.uri,
+        ...Records.convertTagsFilter({ protocol })
+      } as Filter;
+
+      if (messageTimestamp != undefined) {
+        // if we filter by message timestamp, we also want to filter the permission messages by the same timestamp range
+        const messageTimestampFilter = FilterUtility.convertRangeCriterion(messageTimestamp);
+        if (messageTimestampFilter) {
+          taggedFilter.messageTimestamp = messageTimestampFilter;
+        }
+      }
+
+      return taggedFilter;
+    }
+  }
+
+  /**
+   * Converts an external-facing filter model into an internal-facing filer model used by data store.
+   */
+  private static convertFilter(filter: MessagesFilter): Filter {
+    const filterCopy = { ...filter } as Filter;
+
+    const { messageTimestamp } = filter;
+    const messageTimestampFilter = messageTimestamp ? FilterUtility.convertRangeCriterion(messageTimestamp) : undefined;
+    if (messageTimestampFilter) {
+      filterCopy.messageTimestamp = messageTimestampFilter;
+      delete filterCopy.dateUpdated;
+    }
+    return filterCopy as Filter;
+  }
+}

package/src/utils/object.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+  }
+}