@enbox/dwn-sdk-js 0.3.7 → 0.3.8

package/src/handlers/protocols-configure.ts

@@ -1,5 +1,6 @@
 import type { GenericMessageReply } from '../types/message-types.js';
 import type { MessageStore } from '../types//message-store.js';
+import type { RecordsWriteMessage } from '../types/records-types.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureMessage } from '../types/protocols-types.js';
 
@@ -7,12 +8,34 @@ import { authenticate } from '../core/auth.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
+import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { ProtocolsConfigure } from '../interfaces/protocols-configure.js';
 import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { StorageController } from '../store/storage-controller.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import { getRuleSetAtPath, parseCrossProtocolRef } from '../utils/protocols.js';
 
+type StoredInitialWriteConfigValidity = 'valid' | 'invalid' | 'unknown';
+
+const STORED_INITIAL_WRITE_CONFIG_INVALID_CODES = new Set<string>([
+  DwnErrorCode.ProtocolAuthorizationEncryptionRequired,
+  DwnErrorCode.ProtocolAuthorizationIncorrectDataFormat,
+  DwnErrorCode.ProtocolAuthorizationInitialWriteRevalidationNotInitial,
+  DwnErrorCode.ProtocolAuthorizationInvalidSchema,
+  DwnErrorCode.ProtocolAuthorizationInvalidType,
+  DwnErrorCode.ProtocolAuthorizationMaxSizeInvalid,
+  DwnErrorCode.ProtocolAuthorizationMinSizeInvalid,
+  DwnErrorCode.ProtocolAuthorizationMissingRuleSet,
+  DwnErrorCode.ProtocolAuthorizationSquashNotEnabled,
+  DwnErrorCode.ProtocolAuthorizationSquashNotInitialWrite,
+  DwnErrorCode.ProtocolAuthorizationStoredInitialWriteActionNotAllowed,
+  DwnErrorCode.ProtocolAuthorizationStoredInitialWriteActionRulesNotFound,
+  DwnErrorCode.ProtocolAuthorizationStoredInitialWriteRoleMissingRecipient,
+  DwnErrorCode.ProtocolAuthorizationTagsInvalidSchema,
+]);
+
 export class ProtocolsConfigureHandler implements MethodHandler {
 
   constructor(private readonly deps: HandlerDependencies) { }
@@ -115,6 +138,8 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       }
     }
 
+    await this.purgeRecordsInvalidatedByProtocolConfig(tenant, message.descriptor.definition.protocol);
+
     return messageReply;
   };
 
@@ -142,8 +167,9 @@ export class ProtocolsConfigureHandler implements MethodHandler {
 
     if (protocolConfigure.author === tenant) {
       return;
-    } else if (protocolConfigure.author !== undefined && protocolConfigure.signaturePayload!.permissionGrantId !== undefined) {
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, protocolConfigure.signaturePayload!.permissionGrantId);
+    } else if (protocolConfigure.author !== undefined && Message.getPermissionGrantId(protocolConfigure.signaturePayload!) !== undefined) {
+      const permissionGrantId = Message.getPermissionGrantId(protocolConfigure.signaturePayload!)!;
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
       await ProtocolsGrantAuthorization.authorizeConfigure({
         protocolsConfigureMessage : protocolConfigure.message,
         expectedGrantor           : tenant,
@@ -156,6 +182,81 @@ export class ProtocolsConfigureHandler implements MethodHandler {
     }
   }
 
+  private async purgeRecordsInvalidatedByProtocolConfig(tenant: string, protocol: string): Promise<void> {
+    const dataStore = this.deps.dataStore;
+    const stateIndex = this.deps.stateIndex;
+    if (dataStore === undefined || stateIndex === undefined) {
+      return;
+    }
+
+    const { messages } = await this.deps.messageStore.query(tenant, [{
+      interface : DwnInterfaceName.Records,
+      method    : DwnMethodName.Write,
+      protocol,
+    }]);
+
+    const checkedRecordIds = new Set<string>();
+    for (const message of messages) {
+      const recordsWriteMessage = message as RecordsWriteMessage;
+      if (checkedRecordIds.has(recordsWriteMessage.recordId)) {
+        continue;
+      }
+
+      const isInitialWrite = await RecordsWrite.isInitialWrite(recordsWriteMessage);
+      if (!isInitialWrite) {
+        continue;
+      }
+
+      checkedRecordIds.add(recordsWriteMessage.recordId);
+
+      const validity = await this.getStoredInitialWriteConfigValidity(tenant, recordsWriteMessage);
+      if (validity !== 'invalid') {
+        continue;
+      }
+
+      const { messages: recordMessages } = await this.deps.messageStore.query(tenant, [{
+        interface : DwnInterfaceName.Records,
+        recordId  : recordsWriteMessage.recordId,
+      }]);
+      if (recordMessages.length === 0) {
+        continue;
+      }
+
+      // A DWN cannot synthesize a valid RecordsDelete on behalf of the record author.
+      // This repair therefore performs a local hard purge of only the invalid initial
+      // record. Descendants are evaluated independently so valid child records are not
+      // destroyed as collateral.
+      await StorageController.purgeRecordMessages(
+        tenant, recordMessages, this.deps.messageStore, dataStore, stateIndex
+      );
+    }
+  }
+
+  private async getStoredInitialWriteConfigValidity(
+    tenant: string,
+    message: RecordsWriteMessage,
+  ): Promise<StoredInitialWriteConfigValidity> {
+    try {
+      const recordsWrite = await RecordsWrite.parse(message);
+      // Stored records were authenticated when admitted. Reconciliation should not make
+      // record retention depend on fresh DID resolution availability or mutable dependency state.
+      await ProtocolAuthorization.validateStoredInitialWrite(
+        tenant, recordsWrite, this.deps.messageStore, this.deps.coreProtocols
+      );
+      return 'valid';
+    } catch (error) {
+      if (ProtocolsConfigureHandler.isStoredInitialWriteConfigInvalidError(error)) {
+        return 'invalid';
+      }
+
+      return 'unknown';
+    }
+  }
+
+  private static isStoredInitialWriteConfigInvalidError(error: unknown): boolean {
+    return error instanceof DwnError && STORED_INITIAL_WRITE_CONFIG_INVALID_CODES.has(error.code);
+  }
+
   /**
    * Validates composition dependencies at install time:
    * 1. All `uses` protocols must already be installed for the tenant.

package/src/handlers/records-count.ts

@@ -7,9 +7,11 @@ import type { RecordsCountMessage, RecordsCountReply } from '../types/records-ty
 import { authenticate } from '../core/auth.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { Records } from '../utils/records.js';
 import { RecordsCount } from '../interfaces/records-count.js';
+import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 
 export class RecordsCountHandler implements MethodHandler {
@@ -90,6 +92,10 @@ export class RecordsCountHandler implements MethodHandler {
         filters.push(RecordsCountHandler.buildUnpublishedProtocolAuthorizedRecordsFilter(recordsCount));
       }
 
+      if (Message.getPermissionGrantId(recordsCount.signaturePayload!) !== undefined) {
+        filters.push(RecordsCountHandler.buildUnpublishedPermissionGrantAuthorizedRecordsFilter(recordsCount));
+      }
+
       if (Records.shouldBuildUnpublishedRecipientFilter(filter, recordsCount.author!)) {
         filters.push(RecordsCountHandler.buildUnpublishedRecordsForCountAuthorFilter(recordsCount));
       }
@@ -146,6 +152,20 @@ export class RecordsCountHandler implements MethodHandler {
     };
   }
 
+  /**
+   * Creates a filter for unpublished records authorized by a permission grant.
+   */
+  private static buildUnpublishedPermissionGrantAuthorizedRecordsFilter(recordsCount: RecordsCount): Filter {
+    const { filter } = recordsCount.message.descriptor;
+    return {
+      ...Records.convertFilter(filter),
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      isLatestBaseState : true,
+      published         : false
+    };
+  }
+
   /**
    * Creates a filter for only unpublished records where the author is the same as the count author.
    */
@@ -175,6 +195,19 @@ export class RecordsCountHandler implements MethodHandler {
       await recordsCount.authorizeDelegate(messageStore);
     }
 
+    const permissionGrantId = Message.getPermissionGrantId(recordsCount.signaturePayload!);
+    if (permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
+      await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
+        incomingMessage : recordsCount.message,
+        expectedGrantor : tenant,
+        expectedGrantee : recordsCount.author!,
+        permissionGrant,
+        messageStore,
+      });
+      return;
+    }
+
     // NOTE: not all RecordsCount messages require protocol authorization even if the filter includes protocol-related fields,
     // this is because we dynamically filter out records that the caller is not authorized to see.
     // Currently only run protocol authorization if message deliberately invokes a protocol role.

package/src/handlers/records-delete.ts

@@ -110,8 +110,9 @@ export class RecordsDeleteHandler implements MethodHandler {
 
     if (recordsDelete.author === tenant) {
       return;
-    } else if (recordsDelete.author !== undefined && recordsDelete.signaturePayload!.permissionGrantId !== undefined) {
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, recordsDelete.signaturePayload!.permissionGrantId);
+    } else if (recordsDelete.author !== undefined && Message.getPermissionGrantId(recordsDelete.signaturePayload!) !== undefined) {
+      const permissionGrantId = Message.getPermissionGrantId(recordsDelete.signaturePayload!)!;
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
       await RecordsGrantAuthorization.authorizeDelete({
         recordsDeleteMessage : recordsDelete.message,
         recordsWriteToDelete : recordsWrite.message,

package/src/handlers/records-query.ts

@@ -9,8 +9,10 @@ import { authenticate } from '../core/auth.js';
 import { DateSort } from '../types/records-types.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { Records } from '../utils/records.js';
+import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
 import { RecordsQuery } from '../interfaces/records-query.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
 import { SortDirection } from '../types/query-types.js';
@@ -162,6 +164,10 @@ export class RecordsQueryHandler implements MethodHandler {
         filters.push(RecordsQueryHandler.buildUnpublishedProtocolAuthorizedRecordsFilter(recordsQuery));
       }
 
+      if (Message.getPermissionGrantId(recordsQuery.signaturePayload!) !== undefined) {
+        filters.push(RecordsQueryHandler.buildUnpublishedPermissionGrantAuthorizedRecordsFilter(recordsQuery));
+      }
+
       if (Records.shouldBuildUnpublishedRecipientFilter(filter, recordsQuery.author!)) {
         filters.push(RecordsQueryHandler.buildUnpublishedRecordsForQueryAuthorFilter(recordsQuery));
       }
@@ -226,6 +232,20 @@ export class RecordsQueryHandler implements MethodHandler {
     };
   }
 
+  /**
+   * Creates a filter for unpublished records authorized by a permission grant.
+   */
+  private static buildUnpublishedPermissionGrantAuthorizedRecordsFilter(recordsQuery: RecordsQuery): Filter {
+    const { dateSort, filter } = recordsQuery.message.descriptor;
+    return {
+      ...Records.convertFilter(filter, dateSort),
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      isLatestBaseState : true,
+      published         : false
+    };
+  }
+
   /**
    * Creates a filter for only unpublished records where the author is the same as the query author.
    */
@@ -256,6 +276,19 @@ export class RecordsQueryHandler implements MethodHandler {
       await recordsQuery.authorizeDelegate(messageStore);
     }
 
+    const permissionGrantId = Message.getPermissionGrantId(recordsQuery.signaturePayload!);
+    if (permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
+      await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
+        incomingMessage : recordsQuery.message,
+        expectedGrantor : tenant,
+        expectedGrantee : recordsQuery.author!,
+        permissionGrant,
+        messageStore,
+      });
+      return;
+    }
+
     // NOTE: not all RecordsQuery messages require protocol authorization even if the filter includes protocol-related fields,
     // this is because we dynamically filter out records that the caller is not authorized to see.
     // Currently only run protocol authorization if message deliberately invokes a protocol role.

package/src/handlers/records-read.ts

@@ -182,8 +182,9 @@ export class RecordsReadHandler implements MethodHandler {
     ) {
       // The recipient or author of a message may always read it
       return;
-    } else if (recordsRead.author !== undefined && recordsRead.signaturePayload!.permissionGrantId !== undefined) {
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, recordsRead.signaturePayload!.permissionGrantId);
+    } else if (recordsRead.author !== undefined && Message.getPermissionGrantId(recordsRead.signaturePayload!) !== undefined) {
+      const permissionGrantId = Message.getPermissionGrantId(recordsRead.signaturePayload!)!;
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
       await RecordsGrantAuthorization.authorizeRead({
         recordsReadMessage          : recordsRead.message,
         recordsWriteMessageToBeRead : matchedRecordsWrite.message,

package/src/handlers/records-subscribe.ts

@@ -10,8 +10,10 @@ import { authenticate } from '../core/auth.js';
 import { DateSort } from '../types/records-types.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { Records } from '../utils/records.js';
+import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
 import { RecordsSubscribe } from '../interfaces/records-subscribe.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
 import { SortDirection } from '../types/query-types.js';
@@ -218,6 +220,15 @@ export class RecordsSubscribeHandler implements MethodHandler {
         });
       }
 
+      if (Message.getPermissionGrantId(recordsSubscribe.signaturePayload!) !== undefined) {
+        filters.push({
+          ...Records.convertFilter(filter),
+          interface : DwnInterfaceName.Records,
+          method    : [DwnMethodName.Write, DwnMethodName.Delete],
+          published : false,
+        });
+      }
+
       if (Records.shouldBuildUnpublishedRecipientFilter(filter, recordsSubscribe.author!)) {
         filters.push({
           ...Records.convertFilter(filter),
@@ -293,6 +304,16 @@ export class RecordsSubscribeHandler implements MethodHandler {
         });
       }
 
+      if (Message.getPermissionGrantId(recordsSubscribe.signaturePayload!) !== undefined) {
+        filters.push({
+          ...Records.convertFilter(filter, dateSort),
+          interface         : DwnInterfaceName.Records,
+          method            : DwnMethodName.Write,
+          isLatestBaseState : true,
+          published         : false,
+        });
+      }
+
       if (Records.shouldBuildUnpublishedRecipientFilter(filter, recordsSubscribe.author!)) {
         filters.push({
           ...Records.convertFilter(filter, dateSort),
@@ -335,6 +356,19 @@ export class RecordsSubscribeHandler implements MethodHandler {
       await recordsSubscribe.authorizeDelegate(messageStore);
     }
 
+    const permissionGrantId = Message.getPermissionGrantId(recordsSubscribe.signaturePayload!);
+    if (permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
+      await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
+        incomingMessage : recordsSubscribe.message,
+        expectedGrantor : tenant,
+        expectedGrantee : recordsSubscribe.author!,
+        permissionGrant,
+        messageStore,
+      });
+      return;
+    }
+
     // NOTE: not all RecordsSubscribe messages require protocol authorization even if the filter includes protocol-related fields,
     // this is because we dynamically filter out records that the caller is not authorized to see.
     // Currently only run protocol authorization if message deliberately invokes a protocol role.

package/src/handlers/records-write.ts

@@ -515,8 +515,9 @@ export class RecordsWriteHandler implements MethodHandler {
     } else if (recordsWrite.author === tenant) {
       // if author is the same as the target tenant, we can directly grant access
       return;
-    } else if (recordsWrite.author !== undefined && recordsWrite.signaturePayload!.permissionGrantId !== undefined) {
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, recordsWrite.signaturePayload!.permissionGrantId);
+    } else if (recordsWrite.author !== undefined && Message.getPermissionGrantId(recordsWrite.signaturePayload!) !== undefined) {
+      const permissionGrantId = Message.getPermissionGrantId(recordsWrite.signaturePayload!)!;
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
       await RecordsGrantAuthorization.authorizeWrite({
         recordsWriteMessage : recordsWrite.message,
         expectedGrantor     : tenant,

package/src/index.ts

@@ -1,8 +1,8 @@
 // export everything that we want to be consumable
 export type { DwnConfig } from './dwn.js';
-export type { EventListener, EventLog, EventLogEntry, EventLogReadOptions, EventLogReadResult, EventLogSubscribeOptions, EventSubscription, MessageEvent, ProgressGapInfo, ProgressGapReason, ProgressToken, SubscriptionEose, SubscriptionEvent, SubscriptionListener, SubscriptionMessage, SubscriptionReply } from './types/subscriptions.js';
+export type { EventListener, EventLog, EventLogEntry, EventLogReadOptions, EventLogReadResult, EventLogSubscribeOptions, EventSubscription, MessageEvent, ProgressGapInfo, ProgressGapReason, ProgressToken, SubscriptionEose, SubscriptionError, SubscriptionEvent, SubscriptionListener, SubscriptionMessage, SubscriptionReply } from './types/subscriptions.js';
 export type { AuthorizationModel, Descriptor, DelegatedGrantRecordsWriteMessage, GenericMessage, GenericMessageReply, GenericSignaturePayload, MessageSort, MessageSubscription, Pagination, QueryResultEntry, Status } from './types/message-types.js';
-export type { MessagesFilter, MessagesReadMessage, MessagesReadReply, MessagesReadReplyEntry, MessagesReadDescriptor, MessagesSubscribeDescriptor, MessagesSubscribeMessage, MessagesSubscribeReply, MessagesSubscribeMessageOptions, MessagesSyncAction, MessagesSyncDescriptor, MessagesSyncDiffEntry, MessagesSyncMessage, MessagesSyncReply } from './types/messages-types.js';
+export type { MessagesFilter, MessagesReadMessage, MessagesReadReply, MessagesReadReplyEntry, MessagesReadDescriptor, MessagesSubscribeDescriptor, MessagesSubscribeMessage, MessagesSubscribeReply, MessagesSubscribeMessageOptions, MessagesSyncAction, MessagesSyncDependencyClass, MessagesSyncDependencyEntry, MessagesSyncDescriptor, MessagesSyncDiffEntry, MessagesSyncMessage, MessagesSyncReply } from './types/messages-types.js';
 export type { GT, LT, Filter, FilterValue, KeyValues, EqualFilter, OneOfFilter, RangeFilter, RangeCriterion, PaginationCursor, QueryOptions, RangeValue, StartsWithFilter } from './types/query-types.js';
 export type { ProtocolsConfigureDescriptor, ProtocolDefinition, ProtocolTypes, ProtocolRuleSet, ProtocolsQueryFilter, ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply, ProtocolActionRule, ProtocolDeliveryStrategy, ProtocolPathEncryption, ProtocolsQueryDescriptor, ProtocolRecordLimitDefinition, ProtocolSizeDefinition, ProtocolTagsDefinition, ProtocolTagSchema, ProtocolType, ProtocolUses } from './types/protocols-types.js';
 export { ProtocolRecordLimitStrategy } from './types/protocols-types.js';
@@ -51,6 +51,8 @@ export { PermissionGrant } from './protocols/permission-grant.js';
 export { PermissionRequest } from './protocols/permission-request.js';
 export { PermissionsProtocol } from './protocols/permissions.js';
 export type { PermissionGrantCreateOptions, PermissionRequestCreateOptions, PermissionRevocationCreateOptions } from './protocols/permissions.js';
+export { PermissionScopeMatcher } from './utils/permission-scope.js';
+export type { ProtocolScope } from './utils/permission-scope.js';
 export { PrivateKeySigner } from './utils/private-key-signer.js';
 export type { PrivateKeySignerOptions } from './utils/private-key-signer.js';
 export { Protocols, parseCrossProtocolRef, isCrossProtocolRef, getRuleSetAtPath } from './utils/protocols.js';
@@ -101,8 +103,10 @@ export { SMTStoreLevel } from './smt/smt-store-level.js';
 export { SMTStoreMemory } from './smt/smt-store-memory.js';
 export type { Hash, SMTNode, SMTInternalNode, SMTLeafNode, SMTProof, SMTDiffResult, SMTNodeStore } from './types/smt-types.js';
 export { hashChildren, hashEquals, hashKey, hashLeaf, hashToHex, hexToHash, getBit, initDefaultHashes, getDefaultHashes, SMT_DEPTH, ZERO_HASH } from './smt/smt-utils.js';
+export { RECORDS_PROJECTION_ROOT_VERSION, RecordsProjection } from './sync/records-projection.js';
+export type { NormalizedRecordsProjectionScope, RecordsProjectionInput, RecordsProjectionScope, RecordsProjectionSnapshot, RecordsProjectionTreeInput } from './sync/records-projection.js';
 
 // test library exports
 export type { GenerateFromRecordsWriteInput, GenerateFromRecordsWriteOut, GenerateGrantCreateInput, GenerateGrantCreateOutput, GenerateMessagesReadInput, GenerateMessagesReadOutput, GenerateMessagesSubscribeInput, GenerateMessagesSubscribeOutput, GenerateProtocolsConfigureInput, GenerateProtocolsConfigureOutput, GenerateProtocolsQueryInput, GenerateProtocolsQueryOutput, GenerateRecordsCountInput, GenerateRecordsCountOutput, GenerateRecordsDeleteInput, GenerateRecordsDeleteOutput, GenerateRecordsQueryInput, GenerateRecordsQueryOutput, GenerateRecordsSubscribeInput, GenerateRecordsSubscribeOutput, GenerateRecordsWriteInput, GenerateRecordsWriteOutput, Persona } from '../tests/utils/test-data-generator.js';
 export { TestDataGenerator } from '../tests/utils/test-data-generator.js';
-export { Poller } from '../tests/utils/poller.js';
+export { Poller } from '../tests/utils/poller.js';

package/src/interfaces/messages-read.ts

@@ -12,7 +12,7 @@ export type MessagesReadOptions = {
   messageCid: string;
   signer: MessageSigner;
   messageTimestamp?: string;
-  permissionGrantId?: string;
+  permissionGrantIds?: string[];
 };
 
 export class MessagesRead extends AbstractMessage<MessagesReadMessage> {
@@ -27,19 +27,22 @@ export class MessagesRead extends AbstractMessage<MessagesReadMessage> {
   }
 
   public static async create(options: MessagesReadOptions): Promise<MessagesRead> {
-    const { signer, permissionGrantId } = options;
+    const { signer } = options;
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantIds: options.permissionGrantIds
+    });
 
     const descriptor: MessagesReadDescriptor = {
       interface        : DwnInterfaceName.Messages,
       method           : DwnMethodName.Read,
       messageCid       : options.messageCid,
       messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
-      ...(permissionGrantId !== undefined && { permissionGrantId }),
+      ...permissionGrantInvocation,
     };
     const authorization = await Message.createAuthorization({
       descriptor,
       signer,
-      permissionGrantId,
+      ...permissionGrantInvocation,
     });
     const message = { descriptor, authorization };
 
@@ -61,4 +64,4 @@ export class MessagesRead extends AbstractMessage<MessagesReadMessage> {
       throw new DwnError(DwnErrorCode.MessagesReadInvalidCid, `${messageCid} is not a valid CID`);
     }
   }
-}
+}

package/src/interfaces/messages-subscribe.ts

@@ -15,7 +15,7 @@ export type MessagesSubscribeOptions = {
   signer: MessageSigner;
   messageTimestamp?: string;
   filters?: MessagesFilter[];
-  permissionGrantId?: string;
+  permissionGrantIds?: string[];
   /**
    * Progress token to resume from. When provided, catch-up events are replayed
    * from the EventLog and an EOSE marker is delivered before live events.
@@ -47,22 +47,25 @@ export class MessagesSubscribe extends AbstractMessage<MessagesSubscribeMessage>
     options: MessagesSubscribeOptions
   ): Promise<MessagesSubscribe> {
     const currentTime = Time.getCurrentTimestamp();
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantIds: options.permissionGrantIds
+    });
 
     const descriptor: MessagesSubscribeDescriptor = {
-      interface         : DwnInterfaceName.Messages,
-      method            : DwnMethodName.Subscribe,
-      filters           : options.filters ?? [],
-      messageTimestamp  : options.messageTimestamp ?? currentTime,
-      permissionGrantId : options.permissionGrantId,
-      cursor            : options.cursor,
+      interface        : DwnInterfaceName.Messages,
+      method           : DwnMethodName.Subscribe,
+      filters          : options.filters ?? [],
+      messageTimestamp : options.messageTimestamp ?? currentTime,
+      cursor           : options.cursor,
+      ...permissionGrantInvocation,
     };
 
     removeUndefinedProperties(descriptor);
-    const { permissionGrantId, signer } = options;
+    const { signer } = options;
     const authorization = await Message.createAuthorization({
       descriptor,
       signer,
-      permissionGrantId
+      ...permissionGrantInvocation
     });
 
     const message: MessagesSubscribeMessage = { descriptor, authorization };

package/src/interfaces/messages-sync.ts

@@ -1,20 +1,25 @@
 import type { MessageSigner } from '../types/signer.js';
+import type { RecordsProjectionScope } from '../sync/records-projection.js';
 import type { MessagesSyncAction, MessagesSyncDescriptor, MessagesSyncMessage } from '../types/messages-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import { Message } from '../core/message.js';
+import { RECORDS_PROJECTION_ROOT_VERSION } from '../sync/records-projection.js';
 import { removeUndefinedProperties } from '@enbox/common';
 import { Time } from '../utils/time.js';
 import { validateProtocolUrlNormalized } from '../utils/url.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 
 export type MessagesSyncOptions = {
   signer : MessageSigner;
   action : MessagesSyncAction;
   protocol? : string;
+  projectionRootVersion?: string;
+  projectionScopes?: RecordsProjectionScope[];
   prefix? : string;
   messageTimestamp? : string;
-  permissionGrantId? : string;
+  permissionGrantIds? : string[];
   /** For `action: 'diff'`: client's subtree hashes at `depth`. */
   hashes? : Record<string, string>;
   /** For `action: 'diff'`: bit depth at which hashes were computed. */
@@ -30,30 +35,46 @@ export class MessagesSync extends AbstractMessage<MessagesSyncMessage> {
     if (message.descriptor.protocol !== undefined) {
       validateProtocolUrlNormalized(message.descriptor.protocol);
     }
+    if (message.descriptor.projectionRootVersion !== undefined &&
+      message.descriptor.projectionRootVersion !== RECORDS_PROJECTION_ROOT_VERSION) {
+      throw new DwnError(
+        DwnErrorCode.MessagesSyncUnsupportedProjectionRootVersion,
+        `Unsupported projection root version ${message.descriptor.projectionRootVersion}`
+      );
+    }
+    for (const scope of message.descriptor.projectionScopes ?? []) {
+      validateProtocolUrlNormalized(scope.protocol);
+    }
 
     return new MessagesSync(message);
   }
 
   public static async create(options: MessagesSyncOptions): Promise<MessagesSync> {
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantIds: options.permissionGrantIds
+    });
+
     const descriptor: MessagesSyncDescriptor = {
-      interface         : DwnInterfaceName.Messages,
-      method            : DwnMethodName.Sync,
-      messageTimestamp  : options.messageTimestamp ?? Time.getCurrentTimestamp(),
-      action            : options.action,
-      protocol          : options.protocol,
-      prefix            : options.prefix,
-      permissionGrantId : options.permissionGrantId,
-      hashes            : options.hashes,
-      depth             : options.depth,
+      interface             : DwnInterfaceName.Messages,
+      method                : DwnMethodName.Sync,
+      messageTimestamp      : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      action                : options.action,
+      protocol              : options.protocol,
+      projectionRootVersion : options.projectionRootVersion,
+      projectionScopes      : options.projectionScopes,
+      prefix                : options.prefix,
+      hashes                : options.hashes,
+      depth                 : options.depth,
+      ...permissionGrantInvocation,
     };
 
     removeUndefinedProperties(descriptor);
 
-    const { permissionGrantId, signer } = options;
+    const { signer } = options;
     const authorization = await Message.createAuthorization({
       descriptor,
       signer,
-      permissionGrantId
+      ...permissionGrantInvocation
     });
 
     const message = { descriptor, authorization };

package/src/interfaces/protocols-configure.ts

@@ -40,19 +40,23 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
   }
 
   public static async create(options: ProtocolsConfigureOptions): Promise<ProtocolsConfigure> {
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId,
+    });
+
     const descriptor: ProtocolsConfigureDescriptor = {
       interface        : DwnInterfaceName.Protocols,
       method           : DwnMethodName.Configure,
       messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
       definition       : ProtocolsConfigure.normalizeDefinition(options.definition),
-      ...(options.permissionGrantId !== undefined && { permissionGrantId: options.permissionGrantId }),
+      ...permissionGrantInvocation,
     };
 
     const authorization = await Message.createAuthorization({
       descriptor,
-      signer            : options.signer,
-      delegatedGrant    : options.delegatedGrant,
-      permissionGrantId : options.permissionGrantId
+      signer         : options.signer,
+      delegatedGrant : options.delegatedGrant,
+      ...permissionGrantInvocation
     });
     const message = { descriptor, authorization };
 

package/src/interfaces/protocols-query.ts

@@ -36,13 +36,16 @@ export class ProtocolsQuery extends AbstractMessage<ProtocolsQueryMessage> {
   }
 
   public static async create(options: ProtocolsQueryOptions): Promise<ProtocolsQuery> {
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId,
+    });
 
     const descriptor: ProtocolsQueryDescriptor = {
-      interface         : DwnInterfaceName.Protocols,
-      method            : DwnMethodName.Query,
-      messageTimestamp  : options.messageTimestamp ?? Time.getCurrentTimestamp(),
-      filter            : options.filter ? ProtocolsQuery.normalizeFilter(options.filter) : undefined,
-      permissionGrantId : options.permissionGrantId,
+      interface        : DwnInterfaceName.Protocols,
+      method           : DwnMethodName.Query,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      filter           : options.filter ? ProtocolsQuery.normalizeFilter(options.filter) : undefined,
+      ...permissionGrantInvocation,
     };
 
     // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:
@@ -54,8 +57,8 @@ export class ProtocolsQuery extends AbstractMessage<ProtocolsQueryMessage> {
     if (options.signer !== undefined) {
       authorization = await Message.createAuthorization({
         descriptor,
-        signer            : options.signer,
-        permissionGrantId : options.permissionGrantId
+        signer: options.signer,
+        ...permissionGrantInvocation
       });
     }
 
@@ -78,8 +81,9 @@ export class ProtocolsQuery extends AbstractMessage<ProtocolsQueryMessage> {
     // 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);
+    } else if (this.author !== undefined && Message.getPermissionGrantId(this.signaturePayload!) !== undefined) {
+      const permissionGrantId = Message.getPermissionGrantId(this.signaturePayload!)!;
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
       await ProtocolsGrantAuthorization.authorizeQuery({
         expectedGrantor : tenant,
         expectedGrantee : this.author,