@enbox/dwn-sdk-js 0.0.1

package/src/interfaces/protocols-configure.ts

@@ -0,0 +1,340 @@
+import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { Signer } from '../types/signer.js';
+import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureDescriptor, ProtocolsConfigureMessage } from '../types/protocols-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import Ajv from 'ajv/dist/2020.js';
+import { Message } from '../core/message.js';
+import { PermissionGrant } from '../protocols/permission-grant.js';
+import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
+import { Time } from '../utils/time.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { normalizeProtocolUrl, normalizeSchemaUrl, validateProtocolUrlNormalized, validateSchemaUrlNormalized } from '../utils/url.js';
+import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
+
+export type ProtocolsConfigureOptions = {
+  messageTimestamp?: string;
+  definition: ProtocolDefinition;
+  signer: Signer;
+  /**
+   * The delegated grant invoked to sign on behalf of the logical author, which is the grantor of the delegated grant.
+   */
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
+  permissionGrantId?: string;
+};
+
+export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessage> {
+  public static async parse(message: ProtocolsConfigureMessage): Promise<ProtocolsConfigure> {
+    Message.validateJsonSchema(message);
+    ProtocolsConfigure.validateProtocolDefinition(message.descriptor.definition);
+    await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new ProtocolsConfigure(message);
+  }
+
+  public static async create(options: ProtocolsConfigureOptions): Promise<ProtocolsConfigure> {
+    const descriptor: ProtocolsConfigureDescriptor = {
+      interface        : DwnInterfaceName.Protocols,
+      method           : DwnMethodName.Configure,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      definition       : ProtocolsConfigure.normalizeDefinition(options.definition)
+    };
+
+    const authorization = await Message.createAuthorization({
+      descriptor,
+      signer            : options.signer,
+      delegatedGrant    : options.delegatedGrant,
+      permissionGrantId : options.permissionGrantId
+    });
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+    ProtocolsConfigure.validateProtocolDefinition(message.descriptor.definition);
+
+    const protocolsConfigure = new ProtocolsConfigure(message);
+    return protocolsConfigure;
+  }
+
+  /**
+   * Authorizes the author-delegate who signed this message.
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public async authorizeAuthorDelegate(messageStore: MessageStore): Promise<void> {
+    const delegatedGrant = await PermissionGrant.parse(this.message.authorization.authorDelegatedGrant!);
+    await ProtocolsGrantAuthorization.authorizeConfigure({
+      protocolsConfigureMessage : this.message,
+      expectedGrantor           : this.author!,
+      expectedGrantee           : this.signer!,
+      permissionGrant           : delegatedGrant,
+      messageStore
+    });
+  }
+
+  /**
+   * Performs validation on the given protocol definition that are not easy to do using a JSON schema.
+   */
+  private static validateProtocolDefinition(definition: ProtocolDefinition): void {
+    const { protocol, types } = definition;
+
+    // validate protocol url
+    validateProtocolUrlNormalized(protocol);
+
+    // validate schema url normalized
+    for (const typeName in types) {
+      const schema = types[typeName].schema;
+      if (schema !== undefined) {
+        validateSchemaUrlNormalized(schema);
+      }
+    }
+
+    // validate `structure
+    ProtocolsConfigure.validateStructure(definition);
+  }
+
+  private static validateStructure(definition: ProtocolDefinition): void {
+
+    // gather all declared record types
+    const recordTypes = Object.keys(definition.types);
+
+    // gather all roles
+    const roles = ProtocolsConfigure.fetchAllRolePathsRecursively('', definition.structure, []);
+
+    // validate the entire rule set structure recursively
+    ProtocolsConfigure.validateRuleSetRecursively({
+      ruleSet             : definition.structure,
+      ruleSetProtocolPath : '',
+      recordTypes,
+      roles
+    });
+  }
+
+  /**
+   * Parses the given rule set hierarchy to get all the role protocol paths.
+   * @throws DwnError if the hierarchy depth goes beyond 10 levels.
+   */
+  private static fetchAllRolePathsRecursively(ruleSetProtocolPath: string, ruleSet: ProtocolRuleSet, roles: string[]): string[] {
+    // Limit the depth of the record hierarchy to 10 levels
+    // There is opportunity to optimize here to avoid repeated string splitting
+    if (ruleSetProtocolPath.split('/').length > 10) {
+      throw new DwnError(DwnErrorCode.ProtocolsConfigureRecordNestingDepthExceeded, 'Record nesting depth exceeded 10 levels.');
+    }
+
+    for (const recordType in ruleSet) {
+      // ignore non-nested-record properties
+      if (recordType.startsWith('$')) {
+        continue;
+      }
+
+      const childRuleSet = ruleSet[recordType];
+
+      let childRuleSetProtocolPath;
+      if (ruleSetProtocolPath === '') {
+        childRuleSetProtocolPath = recordType;
+      } else {
+        childRuleSetProtocolPath = `${ruleSetProtocolPath}/${recordType}`;
+      }
+
+      // if this is a role record, add it to the list, else continue to traverse
+      if (childRuleSet.$role) {
+        roles.push(childRuleSetProtocolPath);
+      } else {
+        ProtocolsConfigure.fetchAllRolePathsRecursively(childRuleSetProtocolPath, childRuleSet, roles);
+      }
+    }
+
+    return roles;
+  }
+
+  /**
+   * Validates the given rule set structure then recursively validates its nested child rule sets.
+   */
+  private static validateRuleSetRecursively(
+    input: { ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, recordTypes: string[], roles: string[] }
+  ): void {
+    const { ruleSet, ruleSetProtocolPath, recordTypes, roles } = input;
+
+    // Validate $actions in the rule set
+    if (ruleSet.$size !== undefined) {
+      const { min = 0, max } = ruleSet.$size;
+
+      if (max !== undefined && max < min) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidSize,
+          `Invalid size range found: max limit ${max} less than min limit ${min} at protocol path '${ruleSetProtocolPath}'`
+        );
+      }
+    }
+
+    if (ruleSet.$tags) {
+      const ajv = new Ajv.default();
+      const { $allowUndefinedTags, $requiredTags, ...tagProperties } = ruleSet.$tags;
+
+      // we validate each tag's expected schema to ensure it is a valid JSON schema
+      for (const tag in tagProperties) {
+        const tagSchemaDefinition = tagProperties[tag];
+
+        if (!ajv.validateSchema(tagSchemaDefinition)) {
+          const schemaError = ajv.errorsText(ajv.errors, { dataVar: `${ruleSetProtocolPath}/$tags/${tag}` });
+          throw new DwnError(DwnErrorCode.ProtocolsConfigureInvalidTagSchema, `tags schema validation error: ${schemaError}`);
+        }
+      }
+    }
+
+    // validate each action rule
+    const actionRules = ruleSet.$actions ?? [];
+    for (let i = 0; i < actionRules.length; i++) {
+      const actionRule = actionRules[i];
+
+      // Validate the `role` property of an `action` if exists.
+      if (actionRule.role !== undefined) {
+        // make sure the role contains a valid protocol paths to a role record
+        if (!roles.includes(actionRule.role)) {
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureRoleDoesNotExistAtGivenPath,
+            `Role in action ${JSON.stringify(actionRule)} for rule set ${ruleSetProtocolPath} does not exist.`
+          );
+        } else {
+          // it is a role record, we ensure that if any of the `can` actions are 'read' type of actions ('read', 'query', 'subscribe'),
+          // that they are all present.
+          const readActions = [ProtocolAction.Read, ProtocolAction.Query, ProtocolAction.Subscribe];
+          if (readActions.find( action => actionRule.can.includes(action)) && !readActions.every(action => actionRule.can.includes(action))) {
+            throw new DwnError(
+              DwnErrorCode.ProtocolsConfigureRoleReadActionMissing,
+              `Role in action ${JSON.stringify(actionRule)} for rule set ${ruleSetProtocolPath} must contain all read actions (${readActions.join(', ')}).`
+            );
+          }
+        }
+      }
+
+      // Validate that if `who` is set to `anyone` then `of` is not set
+      if (actionRule.who === 'anyone' && actionRule.of) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidActionOfNotAllowed,
+          `'of' is not allowed at rule set protocol path (${ruleSetProtocolPath})`
+        );
+      }
+
+      // Validate that if `who === recipient` and `of === undefined`, then `can` can only contain `co-update`, `co-delete`, and `co-prune`.
+      // We do not allow `read`, `write`, or `query` in the `can` array because:
+      // - `read` - Recipients are always allowed to `read`.
+      // - `write` - Entails ability to create and update.
+      //             Since `of` is undefined, it implies the recipient of THIS record,
+      //             there is no 'recipient' until this record has been created, so it makes no sense to allow recipient to write this record.
+      // - `query` - Only authorized using roles, so allowing direct recipients to query is outside the scope.
+      if (actionRule.who === ProtocolActor.Recipient && actionRule.of === undefined) {
+
+        // throw if `can` contains a value that is not `co-update`, `co-delete`, or `co-prune`
+        const hasDisallowedAction = actionRule.can.some(
+          action => ![ProtocolAction.CoUpdate, ProtocolAction.CoDelete, ProtocolAction.CoPrune].includes(action as ProtocolAction)
+        );
+        if (hasDisallowedAction) {
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureInvalidRecipientOfAction,
+            'Rules for `recipient` without `of` property must have `can` containing only `co-update`, `co-delete`, and `co-prune`.'
+          );
+        }
+      }
+
+      // Validate that if `who` is set to `author` then `of` is set
+      if (actionRule.who === ProtocolActor.Author && !actionRule.of) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidActionMissingOf,
+          `'of' is required when 'author' is specified as 'who'`
+        );
+      }
+
+      // validate that if `can` contains `update` or `delete`, it must also contain `create`
+      if (actionRule.can !== undefined) {
+        if (actionRule.can.includes(ProtocolAction.Update) && !actionRule.can.includes(ProtocolAction.Create)) {
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureInvalidActionUpdateWithoutCreate,
+            `Action rule ${JSON.stringify(actionRule)} contains 'update' action but missing the required 'create' action.`
+          );
+        }
+
+        if (actionRule.can.includes(ProtocolAction.Delete) && !actionRule.can.includes(ProtocolAction.Create)) {
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureInvalidActionDeleteWithoutCreate,
+            `Action rule ${JSON.stringify(actionRule)} contains 'delete' action but missing the required 'create' action.`
+          );
+        }
+      }
+
+      // Validate that there are no duplicate actors or roles in the remaining action rules:
+      // ie. no two action rules can have the same combination of `who` + `of` or `role`.
+      // NOTE: we only need to check the remaining action rules that have yet to go through action rule validation loop, as a perf shortcut.
+      for (let j = i + 1; j < actionRules.length; j++) {
+        const otherActionRule = actionRules[j];
+
+        if (actionRule.who !== undefined) {
+          if (actionRule.who === otherActionRule.who && actionRule.of === otherActionRule.of) {
+            throw new DwnError(
+              DwnErrorCode.ProtocolsConfigureDuplicateActorInRuleSet,
+              `More than one action rule per actor ${actionRule.who} of ${actionRule.of} not allowed within a rule set: ${JSON.stringify(actionRule)}`
+            );
+          }
+        } else {
+          // else implicitly a role-based action rule
+
+          if (actionRule.role === otherActionRule.role) {
+            throw new DwnError(
+              DwnErrorCode.ProtocolsConfigureDuplicateRoleInRuleSet,
+              `More than one action rule per role ${actionRule.role} not allowed within a rule set: ${JSON.stringify(actionRule)}`
+            );
+          }
+        }
+      }
+    }
+
+    // Validate nested rule sets
+    for (const recordType in ruleSet) {
+      if (recordType.startsWith('$')) {
+        continue;
+      }
+
+      if (!recordTypes.includes(recordType)) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidRuleSetRecordType,
+          `Rule set ${recordType} is not declared as an allowed type in the protocol definition.`
+        );
+      }
+
+      const childRuleSet = ruleSet[recordType];
+
+      let childRuleSetProtocolPath;
+      if (ruleSetProtocolPath === '') {
+        childRuleSetProtocolPath = recordType; // case of initial definition structure
+      } else {
+        childRuleSetProtocolPath = `${ruleSetProtocolPath}/${recordType}`;
+      }
+
+      ProtocolsConfigure.validateRuleSetRecursively({
+        ruleSet             : childRuleSet,
+        ruleSetProtocolPath : childRuleSetProtocolPath,
+        recordTypes,
+        roles
+      });
+    }
+  }
+
+  private static normalizeDefinition(definition: ProtocolDefinition): ProtocolDefinition {
+    const typesCopy = { ...definition.types };
+
+    // Normalize schema url
+    for (const typeName in typesCopy) {
+      const schema = typesCopy[typeName].schema;
+      if (schema !== undefined) {
+        typesCopy[typeName].schema = normalizeSchemaUrl(schema);
+      }
+    }
+
+    return {
+      ...definition,
+      protocol : normalizeProtocolUrl(definition.protocol),
+      types    : typesCopy,
+    };
+  }
+}

package/src/interfaces/protocols-query.ts

@@ -0,0 +1,96 @@
+import type { AuthorizationModel } from '../types/message-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { Signer } from '../types/signer.js';
+import type { ProtocolsQueryDescriptor, ProtocolsQueryFilter, ProtocolsQueryMessage } from '../types/protocols-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { Message } from '../core/message.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+import { Time } from '../utils/time.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { normalizeProtocolUrl, validateProtocolUrlNormalized } from '../utils/url.js';
+
+export type ProtocolsQueryOptions = {
+  messageTimestamp?: string;
+  filter?: ProtocolsQueryFilter,
+  signer?: Signer;
+  permissionGrantId?: string;
+};
+
+export class ProtocolsQuery extends AbstractMessage<ProtocolsQueryMessage> {
+
+  public static async parse(message: ProtocolsQueryMessage): Promise<ProtocolsQuery> {
+    if (message.authorization !== undefined) {
+      await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
+    }
+
+    if (message.descriptor.filter !== undefined) {
+      validateProtocolUrlNormalized(message.descriptor.filter.protocol);
+    }
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new ProtocolsQuery(message);
+  }
+
+  public static async create(options: ProtocolsQueryOptions): Promise<ProtocolsQuery> {
+
+    const descriptor: ProtocolsQueryDescriptor = {
+      interface        : DwnInterfaceName.Protocols,
+      method           : DwnMethodName.Query,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      filter           : options.filter ? ProtocolsQuery.normalizeFilter(options.filter) : undefined,
+    };
+
+    // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:
+    // Error: `undefined` is not supported by the IPLD Data Model and cannot be encoded
+    removeUndefinedProperties(descriptor);
+
+    // only generate the `authorization` property if signature input is given
+    let authorization: AuthorizationModel | undefined;
+    if (options.signer !== undefined) {
+      authorization = await Message.createAuthorization({
+        descriptor,
+        signer            : options.signer,
+        permissionGrantId : options.permissionGrantId
+      });
+    }
+
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+
+    const protocolsQuery = new ProtocolsQuery(message);
+    return protocolsQuery;
+  }
+
+  static normalizeFilter(filter: ProtocolsQueryFilter): ProtocolsQueryFilter {
+    return {
+      ...filter,
+      protocol: normalizeProtocolUrl(filter.protocol),
+    };
+  }
+
+  public async authorize(tenant: string, messageStore: MessageStore): Promise<void> {
+    // if author is the same as the target tenant, we can directly grant access
+    if (this.author === tenant) {
+      return;
+    } else if (this.author !== undefined && this.signaturePayload!.permissionGrantId) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, this.signaturePayload!.permissionGrantId);
+      await ProtocolsGrantAuthorization.authorizeQuery({
+        expectedGrantor : tenant,
+        expectedGrantee : this.author,
+        incomingMessage : this.message,
+        permissionGrant,
+        messageStore
+      });
+    } else {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsQueryUnauthorized,
+        'The ProtocolsQuery failed authorization'
+      );
+    }
+  }
+}

package/src/interfaces/records-delete.ts

@@ -0,0 +1,117 @@
+import type { KeyValues } from '../types/query-types.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { Signer } from '../types/signer.js';
+import type { DataEncodedRecordsWriteMessage, RecordsDeleteDescriptor, RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { Message } from '../core/message.js';
+import { PermissionGrant } from '../protocols/permission-grant.js';
+import { Records } from '../utils/records.js';
+import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+import { Time } from '../utils/time.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export type RecordsDeleteOptions = {
+  recordId: string;
+  messageTimestamp?: string;
+  protocolRole?: string;
+  signer: Signer;
+
+  /**
+   * Denotes if all the descendent records should be purged. Defaults to `false`.
+   */
+  prune?: boolean
+
+  /**
+   * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
+   */
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
+};
+
+export class RecordsDelete extends AbstractMessage<RecordsDeleteMessage> {
+
+  public static async parse(message: RecordsDeleteMessage): Promise<RecordsDelete> {
+    let signaturePayload;
+    if (message.authorization !== undefined) {
+      signaturePayload = await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
+    }
+
+    await Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
+
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    const recordsDelete = new RecordsDelete(message);
+    return recordsDelete;
+  }
+
+  /**
+   * Creates a RecordsDelete message.
+   * @param options.recordId If `undefined`, will be auto-filled as a originating message as convenience for developer.
+   * @param options.messageTimestamp If `undefined`, it will be auto-filled with current time.
+   */
+  public static async create(options: RecordsDeleteOptions): Promise<RecordsDelete> {
+    const recordId = options.recordId;
+    const currentTime = Time.getCurrentTimestamp();
+
+    const descriptor: RecordsDeleteDescriptor = {
+      interface        : DwnInterfaceName.Records,
+      method           : DwnMethodName.Delete,
+      messageTimestamp : options.messageTimestamp ?? currentTime,
+      recordId,
+      prune            : options.prune ?? false
+    };
+
+    const authorization = await Message.createAuthorization({
+      descriptor,
+      signer         : options.signer,
+      protocolRole   : options.protocolRole,
+      delegatedGrant : options.delegatedGrant
+    });
+    const message: RecordsDeleteMessage = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+
+    return new RecordsDelete(message);
+  }
+
+  /**
+   * Indexed properties needed for MessageStore indexing.
+   */
+  public constructIndexes(
+    initialWrite: RecordsWriteMessage,
+  ): KeyValues {
+    const message = this.message;
+    const descriptor = { ...message.descriptor };
+
+    // we add the immutable properties from the initial RecordsWrite message in order to use them when querying relevant deletes.
+    const { protocol, protocolPath, recipient, schema, parentId, dateCreated } = initialWrite.descriptor;
+
+    const indexes: { [key:string]: string | boolean | undefined } = {
+      isLatestBaseState : true,
+      protocol, protocolPath, recipient, schema, parentId, dateCreated,
+      contextId         : initialWrite.contextId,
+      author            : this.author!,
+      ...descriptor
+    };
+    removeUndefinedProperties(indexes);
+
+    return indexes as KeyValues;
+  }
+
+  /*
+   * Authorizes the delegate who signed the message.
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public async authorizeDelegate(recordsWriteToDelete: RecordsWriteMessage, messageStore: MessageStore): Promise<void> {
+    const delegatedGrant = await PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
+    await RecordsGrantAuthorization.authorizeDelete({
+      recordsDeleteMessage : this.message,
+      recordsWriteToDelete,
+      expectedGrantor      : this.author!,
+      expectedGrantee      : this.signer!,
+      permissionGrant      : delegatedGrant,
+      messageStore
+    });
+  }
+}

package/src/interfaces/records-query.ts

@@ -0,0 +1,131 @@
+import type { MessageStore } from '../types//message-store.js';
+import type { Pagination } from '../types/message-types.js';
+import type { Signer } from '../types/signer.js';
+import type { DataEncodedRecordsWriteMessage, RecordsFilter, RecordsQueryDescriptor, RecordsQueryMessage } from '../types/records-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { DateSort } from '../types/records-types.js';
+import { Message } from '../core/message.js';
+import { PermissionGrant } from '../protocols/permission-grant.js';
+import { Records } from '../utils/records.js';
+import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+import { Time } from '../utils/time.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { validateProtocolUrlNormalized, validateSchemaUrlNormalized } from '../utils/url.js';
+
+export type RecordsQueryOptions = {
+  messageTimestamp?: string;
+  filter: RecordsFilter;
+  dateSort?: DateSort;
+  pagination?: Pagination;
+  signer?: Signer;
+  protocolRole?: string;
+
+  /**
+   * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
+   */
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
+};
+
+/**
+ * A class representing a RecordsQuery DWN message.
+ */
+export class RecordsQuery extends AbstractMessage<RecordsQueryMessage> {
+
+  public static async parse(message: RecordsQueryMessage): Promise<RecordsQuery> {
+
+    if (message.descriptor.filter.published === false) {
+      if (message.descriptor.dateSort === DateSort.PublishedAscending || message.descriptor.dateSort === DateSort.PublishedDescending) {
+        throw new DwnError(
+          DwnErrorCode.RecordsQueryParseFilterPublishedSortInvalid,
+          `queries must not filter for \`published:false\` and sort by ${message.descriptor.dateSort}`
+        );
+      }
+    }
+
+    let signaturePayload;
+    if (message.authorization !== undefined) {
+      signaturePayload = await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
+    }
+
+    await Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
+
+    if (signaturePayload?.protocolRole !== undefined) {
+      if (message.descriptor.filter.protocolPath === undefined) {
+        throw new DwnError(
+          DwnErrorCode.RecordsQueryFilterMissingRequiredProperties,
+          'Role-authorized queries must include `protocolPath` in the filter'
+        );
+      }
+    }
+
+    if (message.descriptor.filter.protocol !== undefined) {
+      validateProtocolUrlNormalized(message.descriptor.filter.protocol);
+    }
+    if (message.descriptor.filter.schema !== undefined) {
+      validateSchemaUrlNormalized(message.descriptor.filter.schema);
+    }
+
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new RecordsQuery(message);
+  }
+
+  public static async create(options: RecordsQueryOptions): Promise<RecordsQuery> {
+    const descriptor: RecordsQueryDescriptor = {
+      interface        : DwnInterfaceName.Records,
+      method           : DwnMethodName.Query,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      filter           : Records.normalizeFilter(options.filter),
+      dateSort         : options.dateSort,
+      pagination       : options.pagination,
+    };
+
+    if (options.filter.published === false) {
+      if (options.dateSort === DateSort.PublishedAscending || options.dateSort === DateSort.PublishedDescending) {
+        throw new DwnError(
+          DwnErrorCode.RecordsQueryCreateFilterPublishedSortInvalid,
+          `queries must not filter for \`published:false\` and sort by ${options.dateSort}`
+        );
+      }
+    }
+
+    // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:
+    // Error: `undefined` is not supported by the IPLD Data Model and cannot be encoded
+    removeUndefinedProperties(descriptor);
+
+    // only generate the `authorization` property if signature input is given
+    const signer = options.signer;
+    let authorization;
+    if (signer) {
+      authorization = await Message.createAuthorization({
+        descriptor,
+        signer,
+        protocolRole   : options.protocolRole,
+        delegatedGrant : options.delegatedGrant
+      });
+    }
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+
+    return new RecordsQuery(message);
+  }
+
+  /**
+   * Authorizes the delegate who signed this message.
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public async authorizeDelegate(messageStore: MessageStore): Promise<void> {
+    const delegatedGrant = await PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
+    await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
+      incomingMessage : this.message,
+      expectedGrantee : this.signer!,
+      expectedGrantor : this.author!,
+      permissionGrant : delegatedGrant,
+      messageStore
+    });
+  }
+}