@enbox/dwn-sdk-js 0.0.2 → 0.0.4

package/src/interfaces/protocols-configure.ts

@@ -1,7 +1,7 @@
 import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
+import type { MessageSigner } from '../types/signer.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 type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureDescriptor, ProtocolsConfigureMessage, ProtocolUses } from '../types/protocols-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import Ajv from 'ajv/dist/2020.js';
@@ -11,13 +11,14 @@ import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorizati
 import { Time } from '../utils/time.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.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;
+  signer: MessageSigner;
   /**
    * The delegated grant invoked to sign on behalf of the logical author, which is the grantor of the delegated grant.
    */
@@ -40,7 +41,8 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       interface        : DwnInterfaceName.Protocols,
       method           : DwnMethodName.Configure,
       messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
-      definition       : ProtocolsConfigure.normalizeDefinition(options.definition)
+      definition       : ProtocolsConfigure.normalizeDefinition(options.definition),
+      ...(options.permissionGrantId !== undefined && { permissionGrantId: options.permissionGrantId }),
     };
 
     const authorization = await Message.createAuthorization({
@@ -77,7 +79,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
    * 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;
+    const { protocol, types, uses } = definition;
 
     // validate protocol url
     validateProtocolUrlNormalized(protocol);
@@ -90,16 +92,57 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       }
     }
 
-    // validate `structure
+    // validate `uses` — alias names must be simple identifiers, values must be normalized URLs, and no self-references
+    if (uses !== undefined) {
+      ProtocolsConfigure.validateUses(uses, protocol);
+    }
+
+    // validate `structure`
     ProtocolsConfigure.validateStructure(definition);
   }
 
+  /**
+   * Validates the `uses` map: alias names must match `^[a-zA-Z][a-zA-Z0-9_-]*$`,
+   * values must be normalized protocol URLs, and no alias may reference the protocol itself.
+   */
+  private static validateUses(uses: ProtocolUses, ownProtocolUri: string): void {
+    const aliasPattern = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+    for (const alias in uses) {
+      if (!aliasPattern.test(alias)) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidUsesAlias,
+          `invalid 'uses' alias '${alias}': must match pattern ${aliasPattern.toString()}.`
+        );
+      }
+
+      try {
+        validateProtocolUrlNormalized(uses[alias]);
+      } catch {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidUsesProtocolUrl,
+          `invalid 'uses' protocol URL for alias '${alias}': '${uses[alias]}' is not a valid normalized protocol URL.`
+        );
+      }
+
+      // reject self-references: a protocol cannot compose itself
+      if (uses[alias] === ownProtocolUri) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidUsesSelfReference,
+          `'uses' alias '${alias}' references the protocol's own URI '${ownProtocolUri}'. ` +
+          `a protocol cannot compose itself.`
+        );
+      }
+    }
+  }
+
   private static validateStructure(definition: ProtocolDefinition): void {
+    const { uses } = definition;
 
     // gather all declared record types
     const recordTypes = Object.keys(definition.types);
 
-    // gather all roles
+    // gather all roles (local roles only — cross-protocol roles are validated by alias existence)
     const roles = ProtocolsConfigure.fetchAllRolePathsRecursively('', definition.structure, []);
 
     // validate the entire rule set structure recursively
@@ -107,7 +150,8 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       ruleSet             : definition.structure,
       ruleSetProtocolPath : '',
       recordTypes,
-      roles
+      roles,
+      uses
     });
   }
 
@@ -152,11 +196,24 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
    * 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[] }
+    input: { ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, recordTypes: string[], roles: string[], uses?: ProtocolUses }
   ): void {
-    const { ruleSet, ruleSetProtocolPath, recordTypes, roles } = input;
+    const { ruleSet, ruleSetProtocolPath, recordTypes, roles, uses } = input;
 
-    // Validate $actions in the rule set
+    // Validate $ref constraints: $ref is only supported at root level (no `/` in protocol path),
+    // and a $ref node is a pure attachment point with no other directives.
+    if (ruleSet.$ref !== undefined) {
+      if (ruleSetProtocolPath.includes('/')) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidRefNotAtRoot,
+          `'$ref' at protocol path '${ruleSetProtocolPath}' is not allowed: '$ref' nodes are only supported at the root level of the structure.`
+        );
+      }
+
+      ProtocolsConfigure.validateRefNode(ruleSet, ruleSetProtocolPath, uses);
+    }
+
+    // Validate $size
     if (ruleSet.$size !== undefined) {
       const { min = 0, max } = ruleSet.$size;
 
@@ -190,20 +247,15 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
 
       // 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.`
-          );
+        if (isCrossProtocolRef(actionRule.role)) {
+          // Cross-protocol role reference: validate alias exists in `uses`
+          ProtocolsConfigure.validateCrossProtocolAlias(actionRule.role, uses, ruleSetProtocolPath, 'role');
         } 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))) {
+          // Local role: make sure the role contains a valid protocol path to a role record
+          if (!roles.includes(actionRule.role)) {
             throw new DwnError(
-              DwnErrorCode.ProtocolsConfigureRoleReadActionMissing,
-              `Role in action ${JSON.stringify(actionRule)} for rule set ${ruleSetProtocolPath} must contain all read actions (${readActions.join(', ')}).`
+              DwnErrorCode.ProtocolsConfigureRoleDoesNotExistAtGivenPath,
+              `Role in action ${JSON.stringify(actionRule)} for rule set ${ruleSetProtocolPath} does not exist.`
             );
           }
         }
@@ -218,12 +270,11 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       }
 
       // 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`.
+      // We do not allow `read` or `write` 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`
@@ -246,7 +297,29 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
         );
       }
 
-      // validate that if `can` contains `update` or `delete`, it must also contain `create`
+      // Validate that `of` points to the current protocol path or an ancestor of it.
+      // At runtime, `checkActor()` searches the record chain for a matching `protocolPath` equal to `actionRule.of`.
+      // If `of` is not the current path or one of its ancestors, the action rule would silently never authorize anyone.
+      if (actionRule.of !== undefined && ruleSetProtocolPath !== '') {
+        if (isCrossProtocolRef(actionRule.of)) {
+          // Cross-protocol `of` reference: validate alias exists in `uses`
+          ProtocolsConfigure.validateCrossProtocolAlias(actionRule.of, uses, ruleSetProtocolPath, 'of');
+        } else {
+          // Local `of`: must be self or ancestor
+          const isSelfOrAncestor = ruleSetProtocolPath === actionRule.of
+            || ruleSetProtocolPath.startsWith(actionRule.of + '/');
+          if (!isSelfOrAncestor) {
+            throw new DwnError(
+              DwnErrorCode.ProtocolsConfigureInvalidActionOfNotAnAncestor,
+              `'of' value '${actionRule.of}' is not an ancestor of protocol path '${ruleSetProtocolPath}' ` +
+              `in action rule ${JSON.stringify(actionRule)}.`
+            );
+          }
+        }
+      }
+
+      // validate that if `can` contains `update`, `delete`, or `prune`, it must also contain `create`
+      // because these are author-only actions, and you can only be the author if you can create
       if (actionRule.can !== undefined) {
         if (actionRule.can.includes(ProtocolAction.Update) && !actionRule.can.includes(ProtocolAction.Create)) {
           throw new DwnError(
@@ -261,6 +334,13 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
             `Action rule ${JSON.stringify(actionRule)} contains 'delete' action but missing the required 'create' action.`
           );
         }
+
+        if (actionRule.can.includes(ProtocolAction.Prune) && !actionRule.can.includes(ProtocolAction.Create)) {
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureInvalidActionPruneWithoutCreate,
+            `Action rule ${JSON.stringify(actionRule)} contains 'prune' action but missing the required 'create' action.`
+          );
+        }
       }
 
       // Validate that there are no duplicate actors or roles in the remaining action rules:
@@ -273,7 +353,8 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
           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)}`
+              `More than one action rule per actor ${actionRule.who} of ${actionRule.of} ` +
+              `not allowed within a rule set: ${JSON.stringify(actionRule)}`
             );
           }
         } else {
@@ -295,15 +376,17 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
         continue;
       }
 
-      if (!recordTypes.includes(recordType)) {
+      const childRuleSet = ruleSet[recordType];
+
+      // A structure key whose rule set has `$ref` does not need to be in the local `types` map —
+      // the type comes from the referenced protocol. All other keys must be in `types`.
+      if (childRuleSet.$ref === undefined && !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
@@ -315,13 +398,94 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
         ruleSet             : childRuleSet,
         ruleSetProtocolPath : childRuleSetProtocolPath,
         recordTypes,
-        roles
+        roles,
+        uses
       });
     }
   }
 
+  /**
+   * Validates that a `$ref` node is a pure attachment point: it must NOT have
+   * `$actions`, `$role`, `$size`, `$tags`, or `$encryption`.
+   * Also validates that the `$ref` alias exists in the `uses` map.
+   */
+  private static validateRefNode(ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, uses: ProtocolUses | undefined): void {
+    const ref = ruleSet.$ref!;
+    const parsed = parseCrossProtocolRef(ref);
+
+    if (parsed === undefined) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsConfigureInvalidRefAlias,
+        `'$ref' value '${ref}' at protocol path '${ruleSetProtocolPath}' must be in 'alias:typePath' format.`
+      );
+    }
+
+    // validate alias exists in `uses`
+    if (uses === undefined || uses[parsed.alias] === undefined) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsConfigureInvalidRefAlias,
+        `'$ref' alias '${parsed.alias}' at protocol path '${ruleSetProtocolPath}' does not exist in the 'uses' map.`
+      );
+    }
+
+    // validate that `$ref` nodes do not have other directives
+    const forbiddenDirectives = ['$actions', '$role', '$size', '$tags', '$encryption'] as const;
+    for (const directive of forbiddenDirectives) {
+      if (ruleSet[directive] !== undefined) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidRefNodeHasDirectives,
+          `'$ref' node at protocol path '${ruleSetProtocolPath}' must not have '${directive}'. ` +
+          `$ref nodes are pure attachment points — directives belong on child rule sets.`
+        );
+      }
+    }
+  }
+
+  /**
+   * Validates that a cross-protocol reference (in `alias:path` format) has a valid alias
+   * that exists in the `uses` map.
+   * @param ref - The cross-protocol reference string (e.g., "threads:thread/participant")
+   * @param uses - The protocol definition's `uses` map
+   * @param ruleSetProtocolPath - The current protocol path (for error messages)
+   * @param fieldName - The field name ('role' or 'of') for error messages
+   */
+  private static validateCrossProtocolAlias(
+    ref: string, uses: ProtocolUses | undefined, ruleSetProtocolPath: string, fieldName: string
+  ): void {
+    const parsed = parseCrossProtocolRef(ref);
+
+    if (parsed === undefined) {
+      // should not happen if isCrossProtocolRef() returned true, but guard defensively
+      const errorCode = fieldName === 'role'
+        ? DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolRole
+        : DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolOf;
+
+      throw new DwnError(
+        errorCode,
+        `cross-protocol '${fieldName}' reference '${ref}' at protocol path '${ruleSetProtocolPath}' ` +
+        `could not be parsed as a valid 'alias:path' format.`
+      );
+    }
+
+    if (uses === undefined || uses[parsed.alias] === undefined) {
+      const errorCode = fieldName === 'role'
+        ? DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolRole
+        : DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolOf;
+
+      throw new DwnError(
+        errorCode,
+        `cross-protocol '${fieldName}' alias '${parsed.alias}' in '${ref}' at protocol path '${ruleSetProtocolPath}' ` +
+        `does not exist in the 'uses' map.`
+      );
+    }
+  }
+
   private static normalizeDefinition(definition: ProtocolDefinition): ProtocolDefinition {
-    const typesCopy = { ...definition.types };
+    // Deep clone types to avoid mutating the caller's nested objects
+    const typesCopy: ProtocolDefinition['types'] = {};
+    for (const typeName in definition.types) {
+      typesCopy[typeName] = { ...definition.types[typeName] };
+    }
 
     // Normalize schema url
     for (const typeName in typesCopy) {
@@ -331,10 +495,24 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       }
     }
 
+    // Normalize `uses` protocol URLs (skip invalid URLs — they will be caught by validateUses)
+    let usesCopy: ProtocolDefinition['uses'];
+    if (definition.uses !== undefined) {
+      usesCopy = {};
+      for (const alias in definition.uses) {
+        try {
+          usesCopy[alias] = normalizeProtocolUrl(definition.uses[alias]);
+        } catch {
+          usesCopy[alias] = definition.uses[alias];
+        }
+      }
+    }
+
     return {
       ...definition,
       protocol : normalizeProtocolUrl(definition.protocol),
       types    : typesCopy,
+      ...(usesCopy !== undefined && { uses: usesCopy }),
     };
   }
 }

package/src/interfaces/protocols-query.ts

@@ -1,6 +1,6 @@
 import type { AuthorizationModel } from '../types/message-types.js';
+import type { MessageSigner } from '../types/signer.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';
@@ -16,7 +16,7 @@ import { normalizeProtocolUrl, validateProtocolUrlNormalized } from '../utils/ur
 export type ProtocolsQueryOptions = {
   messageTimestamp?: string;
   filter?: ProtocolsQueryFilter,
-  signer?: Signer;
+  signer?: MessageSigner;
   permissionGrantId?: string;
 };
 
@@ -38,10 +38,11 @@ export class ProtocolsQuery extends AbstractMessage<ProtocolsQueryMessage> {
   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,
+      interface         : DwnInterfaceName.Protocols,
+      method            : DwnMethodName.Query,
+      messageTimestamp  : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      filter            : options.filter ? ProtocolsQuery.normalizeFilter(options.filter) : undefined,
+      permissionGrantId : options.permissionGrantId,
     };
 
     // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:

package/src/interfaces/records-count.ts

@@ -0,0 +1,106 @@
+import type { MessageSigner } from '../types/signer.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { DataEncodedRecordsWriteMessage, RecordsCountDescriptor, RecordsCountMessage, RecordsFilter } 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 { 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 RecordsCountOptions = {
+  messageTimestamp?: string;
+  filter: RecordsFilter;
+  signer?: MessageSigner;
+  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 RecordsCount DWN message.
+ */
+export class RecordsCount extends AbstractMessage<RecordsCountMessage> {
+
+  public static async parse(message: RecordsCountMessage): Promise<RecordsCount> {
+    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.RecordsCountFilterMissingRequiredProperties,
+          'Role-authorized counts 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 RecordsCount(message);
+  }
+
+  public static async create(options: RecordsCountOptions): Promise<RecordsCount> {
+    const descriptor: RecordsCountDescriptor = {
+      interface        : DwnInterfaceName.Records,
+      method           : DwnMethodName.Count,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      filter           : Records.normalizeFilter(options.filter),
+    };
+
+    // 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 RecordsCount(message);
+  }
+
+  /**
+   * Authorizes the delegate who signed the 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,
+      expectedGrantor : this.author!,
+      expectedGrantee : this.signer!,
+      permissionGrant : delegatedGrant,
+      messageStore
+    });
+  }
+}

package/src/interfaces/records-delete.ts

@@ -1,6 +1,6 @@
 import type { KeyValues } from '../types/query-types.js';
+import type { MessageSigner } from '../types/signer.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';
@@ -16,7 +16,7 @@ export type RecordsDeleteOptions = {
   recordId: string;
   messageTimestamp?: string;
   protocolRole?: string;
-  signer: Signer;
+  signer: MessageSigner;
 
   /**
    * Denotes if all the descendent records should be purged. Defaults to `false`.

package/src/interfaces/records-query.ts

@@ -1,6 +1,6 @@
+import type { MessageSigner } from '../types/signer.js';
 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';
@@ -20,7 +20,7 @@ export type RecordsQueryOptions = {
   filter: RecordsFilter;
   dateSort?: DateSort;
   pagination?: Pagination;
-  signer?: Signer;
+  signer?: MessageSigner;
   protocolRole?: string;
 
   /**

package/src/interfaces/records-read.ts

@@ -1,20 +1,23 @@
+import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types//message-store.js';
-import type { Signer } from '../types/signer.js';
 import type { DataEncodedRecordsWriteMessage, RecordsFilter , RecordsReadDescriptor, RecordsReadMessage, RecordsWriteMessage } 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';
 
 export type RecordsReadOptions = {
   filter: RecordsFilter;
   messageTimestamp?: string;
-  signer?: Signer;
+  dateSort?: DateSort;
+  signer?: MessageSigner;
   permissionGrantId?: string;
   /**
    * Used when authorizing protocol records.
@@ -31,6 +34,15 @@ export type RecordsReadOptions = {
 export class RecordsRead extends AbstractMessage<RecordsReadMessage> {
 
   public static async parse(message: RecordsReadMessage): Promise<RecordsRead> {
+    if (message.descriptor.filter.published === false) {
+      if (message.descriptor.dateSort === DateSort.PublishedAscending || message.descriptor.dateSort === DateSort.PublishedDescending) {
+        throw new DwnError(
+          DwnErrorCode.RecordsReadParseFilterPublishedSortInvalid,
+          `reads 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);
@@ -52,14 +64,25 @@ export class RecordsRead extends AbstractMessage<RecordsReadMessage> {
    * @throws {DwnError} when a combination of required RecordsReadOptions are missing
    */
   public static async create(options: RecordsReadOptions): Promise<RecordsRead> {
-    const { filter, signer, permissionGrantId, protocolRole } = options;
+    const { filter, signer, permissionGrantId, protocolRole, dateSort } = options;
     const currentTime = Time.getCurrentTimestamp();
 
+    if (options.filter.published === false) {
+      if (dateSort === DateSort.PublishedAscending || dateSort === DateSort.PublishedDescending) {
+        throw new DwnError(
+          DwnErrorCode.RecordsReadCreateFilterPublishedSortInvalid,
+          `reads must not filter for \`published:false\` and sort by ${dateSort}`
+        );
+      }
+    }
+
     const descriptor: RecordsReadDescriptor = {
       interface        : DwnInterfaceName.Records,
       method           : DwnMethodName.Read,
       filter           : Records.normalizeFilter(filter),
       messageTimestamp : options.messageTimestamp ?? currentTime,
+      permissionGrantId,
+      dateSort,
     };
 
     removeUndefinedProperties(descriptor);

package/src/interfaces/records-subscribe.ts

@@ -1,5 +1,5 @@
+import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types/message-store.js';
-import type { Signer } from '../types/signer.js';
 import type { DataEncodedRecordsWriteMessage, RecordsFilter, RecordsSubscribeDescriptor, RecordsSubscribeMessage } from '../types/records-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
@@ -16,7 +16,7 @@ import { validateProtocolUrlNormalized, validateSchemaUrlNormalized } from '../u
 export type RecordsSubscribeOptions = {
   messageTimestamp?: string;
   filter: RecordsFilter;
-  signer?: Signer;
+  signer?: MessageSigner;
   protocolRole?: string;
 
   /**