@enbox/dwn-sdk-js 0.3.7 → 0.3.8

package/src/core/message.ts

@@ -12,6 +12,20 @@ import { removeUndefinedProperties } from '@enbox/common';
 import { validateJsonSchema } from '../schema-validator.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 
+type PermissionGrantInvocation = {
+  permissionGrantId?: string;
+  permissionGrantIds?: string[];
+};
+
+type ValidateSignatureStructureOptions = {
+  /**
+   * Permission grant invocations are bound to the author signature payload.
+   * Owner signatures only prove owner retention/consent and do not repeat
+   * the author's grant invocation fields.
+   */
+  validatePermissionGrantInvocation?: boolean;
+};
+
 /**
  * A class containing utility methods for working with DWN messages.
  */
@@ -100,16 +114,17 @@ export class Message {
     signer: MessageSigner,
     delegatedGrant?: DataEncodedRecordsWriteMessage,
     permissionGrantId?: string,
+    permissionGrantIds?: string[],
     protocolRole?: string
   }): Promise<AuthorizationModel> {
-    const { descriptor, signer, delegatedGrant, permissionGrantId, protocolRole } = input;
+    const { descriptor, signer, delegatedGrant, permissionGrantId, permissionGrantIds, protocolRole } = input;
 
     let delegatedGrantId;
     if (delegatedGrant !== undefined) {
       delegatedGrantId = await Message.getCid(delegatedGrant);
     }
 
-    const signature = await Message.createSignature(descriptor, signer, { delegatedGrantId, permissionGrantId, protocolRole });
+    const signature = await Message.createSignature(descriptor, signer, { delegatedGrantId, permissionGrantId, permissionGrantIds, protocolRole });
 
     const authorization: AuthorizationModel = {
       signature
@@ -129,11 +144,23 @@ export class Message {
   public static async createSignature(
     descriptor: Descriptor,
     signer: MessageSigner,
-    additionalPayloadProperties?: { delegatedGrantId?: string, permissionGrantId?: string, protocolRole?: string }
+    additionalPayloadProperties?: { delegatedGrantId?: string, permissionGrantId?: string, permissionGrantIds?: string[], protocolRole?: string }
   ): Promise<GeneralJws> {
     const descriptorCid = await Cid.computeCid(descriptor);
-
-    const signaturePayload: GenericSignaturePayload = { descriptorCid, ...additionalPayloadProperties };
+    const {
+      delegatedGrantId,
+      permissionGrantId,
+      permissionGrantIds,
+      protocolRole
+    } = additionalPayloadProperties ?? {};
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({ permissionGrantId, permissionGrantIds });
+
+    const signaturePayload: GenericSignaturePayload = {
+      descriptorCid,
+      delegatedGrantId,
+      protocolRole,
+      ...permissionGrantInvocation
+    };
     removeUndefinedProperties(signaturePayload);
 
     const signaturePayloadBytes = Encoder.objectToBytes(signaturePayload);
@@ -144,6 +171,55 @@ export class Message {
     return signature;
   }
 
+  /**
+   * Normalizes permission grant invocation before it is written into a descriptor
+   * and signed payload.
+   *
+   * Direct operation messages use `permissionGrantId`; Messages operations use
+   * canonicalized `permissionGrantIds` so a request can invoke a grant set.
+   */
+  public static normalizePermissionGrantInvocation(input: PermissionGrantInvocation): PermissionGrantInvocation {
+    if (input.permissionGrantId !== undefined && input.permissionGrantIds !== undefined) {
+      throw new DwnError(
+        DwnErrorCode.MessagePermissionGrantCreateInvocationAmbiguous,
+        'permission grant invocation must use either `permissionGrantId` or `permissionGrantIds`, not both'
+      );
+    }
+
+    if (input.permissionGrantId !== undefined) {
+      return { permissionGrantId: input.permissionGrantId };
+    }
+
+    if (input.permissionGrantIds === undefined) {
+      return {};
+    }
+
+    const permissionGrantIds = Message.normalizePermissionGrantIds(input);
+    return { permissionGrantIds };
+  }
+
+  /**
+   * Returns the permission grant ID carried by a direct operation signature payload.
+   */
+  public static getPermissionGrantId(signaturePayload: GenericSignaturePayload): string | undefined {
+    return signaturePayload.permissionGrantId;
+  }
+
+  /**
+   * Returns all permission grant IDs invoked by a signature payload.
+   *
+   * Direct Records/Protocols operations carry a single `permissionGrantId`.
+   * Messages operations carry `permissionGrantIds`. Generic cleanup and
+   * revocation code uses this helper across both wire shapes.
+   */
+  public static getPermissionGrantIds(signaturePayload: GenericSignaturePayload): string[] {
+    if (signaturePayload.permissionGrantId !== undefined) {
+      return [signaturePayload.permissionGrantId];
+    }
+
+    return signaturePayload.permissionGrantIds ?? [];
+  }
+
   /**
    * @returns newest message in the array. `undefined` if given array is empty.
    */
@@ -227,12 +303,14 @@ export class Message {
    * 3. The `descriptorCid` property matches the CID of the message descriptor
    * NOTE: signature is NOT verified.
    * @param payloadJsonSchemaKey The key to look up the JSON schema referenced in `compile-validators.js` and perform payload schema validation on.
+   * @param options Additional structural validation controls.
    * @returns the parsed JSON payload object if validation succeeds.
    */
   public static async validateSignatureStructure(
     messageSignature: GeneralJws,
     messageDescriptor: Descriptor,
     payloadJsonSchemaKey: string = 'GenericSignaturePayload',
+    options: ValidateSignatureStructureOptions = {},
   ): Promise<GenericSignaturePayload> {
 
     if (messageSignature.signatures.length !== 1) {
@@ -254,6 +332,75 @@ export class Message {
       );
     }
 
+    if (options.validatePermissionGrantInvocation !== false) {
+      Message.validatePermissionGrantInvocationMatchesPayload(messageDescriptor, payloadJson);
+    }
+
     return payloadJson;
   }
-}
+
+  private static normalizePermissionGrantIds(input: PermissionGrantInvocation): string[] {
+    if (input.permissionGrantIds === undefined) {
+      return [];
+    }
+
+    if (input.permissionGrantIds.length === 0) {
+      throw new DwnError(
+        DwnErrorCode.MessagePermissionGrantIdsEmpty,
+        '`permissionGrantIds` must contain at least one grant ID'
+      );
+    }
+
+    return [...new Set(input.permissionGrantIds)].sort(lexicographicalCompare);
+  }
+
+  private static validatePermissionGrantInvocationCanonical(input: PermissionGrantInvocation): string[] {
+    if (input.permissionGrantId !== undefined && input.permissionGrantIds !== undefined) {
+      throw new DwnError(
+        DwnErrorCode.MessagePermissionGrantValidateInvocationAmbiguous,
+        'permission grant invocation must use either `permissionGrantId` or `permissionGrantIds`, not both'
+      );
+    }
+
+    if (input.permissionGrantId !== undefined) {
+      return [input.permissionGrantId];
+    }
+
+    const normalizedPermissionGrantIds = Message.normalizePermissionGrantIds(input);
+
+    if (input.permissionGrantIds !== undefined && !Message.areStringArraysEqual(input.permissionGrantIds, normalizedPermissionGrantIds)) {
+      throw new DwnError(
+        DwnErrorCode.MessagePermissionGrantIdsNotCanonical,
+        '`permissionGrantIds` must be sorted and deduplicated'
+      );
+    }
+
+    return normalizedPermissionGrantIds;
+  }
+
+  private static validatePermissionGrantInvocationMatchesPayload(
+    descriptor: Descriptor & PermissionGrantInvocation,
+    signaturePayload: GenericSignaturePayload
+  ): void {
+    if (descriptor.permissionGrantId !== signaturePayload.permissionGrantId) {
+      throw new DwnError(
+        DwnErrorCode.MessagePermissionGrantDescriptorPayloadMismatch,
+        'permission grant invocation in descriptor does not match signature payload'
+      );
+    }
+
+    const descriptorPermissionGrantIds = Message.validatePermissionGrantInvocationCanonical(descriptor);
+    const payloadPermissionGrantIds = Message.validatePermissionGrantInvocationCanonical(signaturePayload);
+
+    if (!Message.areStringArraysEqual(descriptorPermissionGrantIds, payloadPermissionGrantIds)) {
+      throw new DwnError(
+        DwnErrorCode.MessagePermissionGrantIdsDescriptorPayloadMismatch,
+        'permission grant invocation in descriptor does not match signature payload'
+      );
+    }
+  }
+
+  private static areStringArraysEqual(a: string[], b: string[]): boolean {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+  }
+}

package/src/core/messages-grant-authorization.ts

@@ -3,11 +3,14 @@ import type { MessagesPermissionScope } from '../types/permission-types.js';
 import type { MessageStore } from '../types/message-store.js';
 import type { PermissionGrant } from '../protocols/permission-grant.js';
 import type { ProtocolsConfigureMessage } from '../types/protocols-types.js';
+import type { ProtocolScope } from '../utils/permission-scope.js';
 import type { DataEncodedRecordsWriteMessage, RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
 import type { MessagesReadMessage, MessagesSubscribeMessage, MessagesSyncMessage } from '../types/messages-types.js';
 
 import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
 import { GrantAuthorization } from './grant-authorization.js';
+import { isRecordsPrimaryProjectionExcludedProtocol } from './constants.js';
+import { PermissionScopeMatcher } from '../utils/permission-scope.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
 import { Records } from '../utils/records.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
@@ -15,6 +18,16 @@ import { DwnError, DwnErrorCode } from './dwn-error.js';
 
 export class MessagesGrantAuthorization {
 
+  public static async fetchPermissionGrants(
+    tenant: string,
+    messageStore: MessageStore,
+    permissionGrantIds: string[]
+  ): Promise<PermissionGrant[]> {
+    return Promise.all(
+      permissionGrantIds.map(permissionGrantId => PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId))
+    );
+  }
+
   /**
    * Authorizes a MessagesReadMessage using the given permission grant.
    * @param messageStore Used to check if the given grant has been revoked; and to fetch related RecordsWrites if needed.
@@ -24,23 +37,29 @@ export class MessagesGrantAuthorization {
     messageToRead: GenericMessage,
     expectedGrantor: string,
     expectedGrantee: string,
-    permissionGrant: PermissionGrant,
+    permissionGrants: PermissionGrant[],
     messageStore: MessageStore,
   }): Promise<void> {
     const {
-      messagesReadMessage, messageToRead, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+      messagesReadMessage, messageToRead, expectedGrantor, expectedGrantee, permissionGrants, messageStore
     } = input;
 
-    await GrantAuthorization.performBaseValidation({
+    await MessagesGrantAuthorization.performBaseValidationForGrantSet({
       incomingMessage: messagesReadMessage,
       expectedGrantor,
       expectedGrantee,
-      permissionGrant,
+      permissionGrants,
       messageStore
     });
 
-    const scope = permissionGrant.scope as MessagesPermissionScope;
-    await MessagesGrantAuthorization.verifyScope(expectedGrantor, messageToRead, scope, messageStore);
+    for (const permissionGrant of permissionGrants) {
+      const scope = permissionGrant.scope as MessagesPermissionScope;
+      if (await MessagesGrantAuthorization.isScopeAuthorized(expectedGrantor, messageToRead, scope, messageStore)) {
+        return;
+      }
+    }
+
+    throw new DwnError(DwnErrorCode.MessagesReadVerifyScopeFailed, 'record message failed scope authorization');
   }
 
   /**
@@ -51,98 +70,291 @@ export class MessagesGrantAuthorization {
     incomingMessage: MessagesSubscribeMessage | MessagesSyncMessage,
     expectedGrantor: string,
     expectedGrantee: string,
-    permissionGrant: PermissionGrant,
+    permissionGrants: PermissionGrant[],
     messageStore: MessageStore,
   }): Promise<void> {
     const {
-      incomingMessage, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+      incomingMessage, expectedGrantor, expectedGrantee, permissionGrants, messageStore
     } = input;
 
-    await GrantAuthorization.performBaseValidation({
+    await MessagesGrantAuthorization.performBaseValidationForGrantSet({
       incomingMessage,
       expectedGrantor,
       expectedGrantee,
-      permissionGrant,
+      permissionGrants,
       messageStore
     });
 
-    // if the grant is scoped to a specific protocol, ensure that the message targets that protocol
-    if (PermissionsProtocol.hasProtocolScope(permissionGrant.scope)) {
-      const scopedProtocol = permissionGrant.scope.protocol;
-
-      // MessagesSync uses a direct `protocol` field on the descriptor
-      if ('action' in incomingMessage.descriptor) {
-        const syncMessage = incomingMessage as MessagesSyncMessage;
-        if (syncMessage.descriptor.protocol !== scopedProtocol) {
-          throw new DwnError(
-            DwnErrorCode.MessagesGrantAuthorizationMismatchedProtocol,
-            `The protocol ${syncMessage.descriptor.protocol} does not match the scoped protocol ${scopedProtocol}`
-          );
-        }
-      } else {
-        // MessagesSubscribe uses filters
-        const filteredMessage = incomingMessage as MessagesSubscribeMessage;
-        for (const filter of filteredMessage.descriptor.filters) {
-          if (filter.protocol !== scopedProtocol) {
-            throw new DwnError(
-              DwnErrorCode.MessagesGrantAuthorizationMismatchedProtocol,
-              `The protocol ${filter.protocol} does not match the scoped protocol ${scopedProtocol}`
-            );
-          }
-        }
+    const scopes = permissionGrants.map(permissionGrant => permissionGrant.scope as MessagesPermissionScope);
+
+    if ('action' in incomingMessage.descriptor) {
+      MessagesGrantAuthorization.authorizeSyncScope(incomingMessage as MessagesSyncMessage, scopes);
+      return;
+    }
+
+    MessagesGrantAuthorization.authorizeSubscribeScope(incomingMessage as MessagesSubscribeMessage, scopes);
+  }
+
+  private static authorizeSyncScope(
+    syncMessage: MessagesSyncMessage,
+    scopes: MessagesPermissionScope[]
+  ): void {
+    const { projectionScopes, protocol } = syncMessage.descriptor;
+
+    if (projectionScopes === undefined) {
+      MessagesGrantAuthorization.authorizeProtocolSyncScope(scopes, protocol);
+      return;
+    }
+
+    MessagesGrantAuthorization.authorizeProjectionScopes(scopes, projectionScopes);
+  }
+
+  private static authorizeProtocolSyncScope(
+    scopes: MessagesPermissionScope[],
+    protocol: string | undefined
+  ): void {
+    if (isRecordsPrimaryProjectionExcludedProtocol(protocol)) {
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationProtocolSyncInfrastructureProtocol,
+        `Protocol-scoped MessagesSync cannot authorize infrastructure protocol ${protocol}`
+      );
+    }
+
+    if (!MessagesGrantAuthorization.someScopeMatches(scopes, { protocol })) {
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationMismatchedProtocol,
+        `No permission grant scope matches protocol ${protocol}`
+      );
+    }
+  }
+
+  private static authorizeProjectionScopes(
+    scopes: MessagesPermissionScope[],
+    projectionScopes: ProtocolScope[],
+  ): void {
+    for (const projectionScope of projectionScopes) {
+      if (isRecordsPrimaryProjectionExcludedProtocol(projectionScope.protocol)) {
+        throw new DwnError(
+          DwnErrorCode.MessagesGrantAuthorizationProjectionInfrastructureProtocol,
+          `Projected MessagesSync cannot authorize infrastructure protocol ${projectionScope.protocol}`
+        );
+      }
+
+      if (MessagesGrantAuthorization.someScopeMatches(scopes, projectionScope)) {
+        continue;
+      }
+
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationProjectionScopeMismatch,
+        `No permission grant scope matches projection scope ${JSON.stringify(projectionScope)}`
+      );
+    }
+  }
+
+  private static authorizeSubscribeScope(
+    subscribeMessage: MessagesSubscribeMessage,
+    scopes: MessagesPermissionScope[]
+  ): void {
+    const { filters } = subscribeMessage.descriptor;
+
+    if (filters.length === 0 && !MessagesGrantAuthorization.hasUnscopedGrant(scopes)) {
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationUnfilteredSubscribeProtocolScope,
+        `A protocol-scoped grant cannot authorize an unfiltered subscription`
+      );
+    }
+
+    for (const filter of filters) {
+      if (MessagesGrantAuthorization.someScopeMatches(scopes, { protocol: filter.protocol })) {
+        continue;
       }
+
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationSubscribeProtocolMismatch,
+        `No permission grant scope matches protocol ${filter.protocol}`
+      );
     }
   }
 
+  private static someScopeMatches(scopes: MessagesPermissionScope[], target: ProtocolScope): boolean {
+    return scopes.some(scope => PermissionScopeMatcher.matches(scope, target));
+  }
+
+  private static hasUnscopedGrant(scopes: MessagesPermissionScope[]): boolean {
+    return scopes.some(scope => scope.protocol === undefined);
+  }
+
   /**
-   * Verifies the given record against the scope of the given grant.
+   * Revalidates an already-open delegated MessagesSubscribe grant set at event
+   * delivery time. Subscription messages are signed at open time, but grant
+   * expiry and revocation must stop future delivery after the grant set becomes
+   * invalid.
    */
-  private static async verifyScope(
+  public static async authorizeSubscribeDelivery(input: {
+    messagesSubscribeMessage: MessagesSubscribeMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrants: PermissionGrant[],
+    messageStore: MessageStore,
+    deliveryTimestamp: string,
+  }): Promise<void> {
+    const {
+      messagesSubscribeMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrants,
+      messageStore,
+      deliveryTimestamp,
+    } = input;
+
+    const deliveryMessage: MessagesSubscribeMessage = {
+      ...messagesSubscribeMessage,
+      descriptor: {
+        ...messagesSubscribeMessage.descriptor,
+        messageTimestamp: deliveryTimestamp,
+      },
+    };
+
+    await MessagesGrantAuthorization.authorizeSubscribeOrSync({
+      incomingMessage: deliveryMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrants,
+      messageStore,
+    });
+  }
+
+  /**
+   * Performs base validation on every invoked grant. The grant set is all-or-nothing:
+   * unresolved, revoked, expired, or interface/method-mismatched grants fail the request.
+   */
+  private static async performBaseValidationForGrantSet(input: {
+    incomingMessage: MessagesReadMessage | MessagesSubscribeMessage | MessagesSyncMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrants: PermissionGrant[],
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      incomingMessage, expectedGrantor, expectedGrantee, permissionGrants, messageStore
+    } = input;
+
+    for (const permissionGrant of permissionGrants) {
+      await GrantAuthorization.performBaseValidation({
+        incomingMessage,
+        expectedGrantor,
+        expectedGrantee,
+        permissionGrant,
+        messageStore
+      });
+    }
+  }
+
+  /**
+   * Determines whether the given record is inside a grant scope.
+   */
+  private static async isScopeAuthorized(
     tenant: string,
     messageToGet: GenericMessage,
     incomingScope: MessagesPermissionScope,
     messageStore: MessageStore,
-  ): Promise<void> {
+  ): Promise<boolean> {
     if (incomingScope.protocol === undefined) {
-      // if no protocol is specified in the scope, then the grant is for all records
-      return;
+      return true;
     }
 
     if (messageToGet.descriptor.interface === DwnInterfaceName.Records) {
-      // if the message is a Records interface message, get the RecordsWrite message associated with the record
-      const recordsMessage = messageToGet as RecordsWriteMessage | RecordsDeleteMessage;
-      const recordsWriteMessage = Records.isRecordsWrite(recordsMessage) ? recordsMessage :
-        await RecordsWrite.fetchNewestRecordsWrite(messageStore, tenant, recordsMessage.descriptor.recordId);
+      return MessagesGrantAuthorization.isRecordsMessageScopeAuthorized(
+        tenant,
+        messageToGet as RecordsWriteMessage | RecordsDeleteMessage,
+        incomingScope,
+        messageStore
+      );
+    }
 
-      if (recordsWriteMessage.descriptor.protocol === incomingScope.protocol) {
-        // the record protocol matches the incoming scope protocol
-        return;
-      }
+    if (messageToGet.descriptor.interface === DwnInterfaceName.Protocols) {
+      return MessagesGrantAuthorization.isProtocolsConfigureScopeAuthorized(
+        messageToGet as ProtocolsConfigureMessage,
+        incomingScope
+      );
+    }
 
-      // we check if the protocol is the internal PermissionsProtocol for further validation
-      if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri) {
-        // get the permission scope from the permission message
-        const permissionScope = await PermissionsProtocol.getScopeFromPermissionRecord(
-          tenant,
-          messageStore,
-          recordsWriteMessage as DataEncodedRecordsWriteMessage
-        );
+    return false;
+  }
 
-        if (PermissionsProtocol.hasProtocolScope(permissionScope) && permissionScope.protocol === incomingScope.protocol) {
-          // the permissions record scoped protocol matches the incoming scope protocol
-          return;
-        }
-      }
-    } else if (messageToGet.descriptor.interface === DwnInterfaceName.Protocols) {
-      // if the message is a protocol message, it must be a `ProtocolConfigure` message
-      const protocolsConfigureMessage = messageToGet as ProtocolsConfigureMessage;
-      const configureProtocol = protocolsConfigureMessage.descriptor.definition.protocol;
-      if (configureProtocol === incomingScope.protocol) {
-        // the configured protocol matches the incoming scope protocol
-        return;
-      }
+  private static async isRecordsMessageScopeAuthorized(
+    tenant: string,
+    recordsMessage: RecordsWriteMessage | RecordsDeleteMessage,
+    incomingScope: MessagesPermissionScope,
+    messageStore: MessageStore,
+  ): Promise<boolean> {
+    const recordsWriteMessage = await MessagesGrantAuthorization.getAssociatedRecordsWrite(
+      tenant,
+      recordsMessage,
+      messageStore
+    );
+
+    if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri) {
+      return MessagesGrantAuthorization.isPermissionRecordScopeAuthorized(
+        tenant,
+        recordsWriteMessage,
+        incomingScope,
+        messageStore
+      );
     }
 
-    throw new DwnError(DwnErrorCode.MessagesReadVerifyScopeFailed, 'record message failed scope authorization');
+    return PermissionScopeMatcher.matches(incomingScope, MessagesGrantAuthorization.getRecordsScopeTarget(recordsWriteMessage));
+  }
+
+  private static async isPermissionRecordScopeAuthorized(
+    tenant: string,
+    recordsWriteMessage: RecordsWriteMessage,
+    incomingScope: MessagesPermissionScope,
+    messageStore: MessageStore,
+  ): Promise<boolean> {
+    if (MessagesGrantAuthorization.isSubtreeScope(incomingScope)) {
+      return false;
+    }
+
+    const permissionScope = await PermissionsProtocol.getScopeFromPermissionRecord(
+      tenant,
+      messageStore,
+      recordsWriteMessage as DataEncodedRecordsWriteMessage
+    );
+
+    return PermissionsProtocol.hasProtocolScope(permissionScope)
+      && PermissionScopeMatcher.matches(incomingScope, permissionScope);
+  }
+
+  private static isProtocolsConfigureScopeAuthorized(
+    protocolsConfigureMessage: ProtocolsConfigureMessage,
+    incomingScope: MessagesPermissionScope
+  ): boolean {
+    // A delegate with any Messages.Read grant inside a protocol needs that
+    // protocol definition to interpret and validate the records it can read.
+    return incomingScope.protocol !== undefined &&
+      incomingScope.protocol === protocolsConfigureMessage.descriptor.definition.protocol;
+  }
+
+  private static async getAssociatedRecordsWrite(
+    tenant: string,
+    recordsMessage: RecordsWriteMessage | RecordsDeleteMessage,
+    messageStore: MessageStore,
+  ): Promise<RecordsWriteMessage> {
+    if (Records.isRecordsWrite(recordsMessage)) {
+      return recordsMessage;
+    }
+
+    return RecordsWrite.fetchNewestRecordsWrite(messageStore, tenant, recordsMessage.descriptor.recordId);
+  }
+
+  private static getRecordsScopeTarget(recordsWriteMessage: RecordsWriteMessage): ProtocolScope {
+    const { protocol, protocolPath } = recordsWriteMessage.descriptor;
+    const { contextId } = recordsWriteMessage;
+    return { protocol, protocolPath, contextId };
+  }
+
+  private static isSubtreeScope(scope: MessagesPermissionScope): boolean {
+    return scope.protocolPath !== undefined || scope.contextId !== undefined;
   }
-}
+}