@enbox/dwn-sdk-js 0.3.6 → 0.3.8

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,

package/src/interfaces/records-count.ts

@@ -17,6 +17,7 @@ export type RecordsCountOptions = {
   messageTimestamp?: string;
   filter: RecordsFilter;
   signer?: MessageSigner;
+  permissionGrantId?: string;
   protocolRole?: string;
 
   /**
@@ -60,11 +61,16 @@ export class RecordsCount extends AbstractMessage<RecordsCountMessage> {
   }
 
   public static async create(options: RecordsCountOptions): Promise<RecordsCount> {
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId,
+    });
+
     const descriptor: RecordsCountDescriptor = {
       interface        : DwnInterfaceName.Records,
       method           : DwnMethodName.Count,
       messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
       filter           : Records.normalizeFilter(options.filter),
+      ...permissionGrantInvocation,
     };
 
     // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:
@@ -78,6 +84,7 @@ export class RecordsCount extends AbstractMessage<RecordsCountMessage> {
       authorization = await Message.createAuthorization({
         descriptor,
         signer,
+        ...permissionGrantInvocation,
         protocolRole   : options.protocolRole,
         delegatedGrant : options.delegatedGrant
       });

package/src/interfaces/records-delete.ts

@@ -58,21 +58,25 @@ export class RecordsDelete extends AbstractMessage<RecordsDeleteMessage> {
   public static async create(options: RecordsDeleteOptions): Promise<RecordsDelete> {
     const recordId = options.recordId;
     const currentTime = Time.getCurrentTimestamp();
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId,
+    });
 
     const descriptor: RecordsDeleteDescriptor = {
       interface        : DwnInterfaceName.Records,
       method           : DwnMethodName.Delete,
       messageTimestamp : options.messageTimestamp ?? currentTime,
       recordId,
-      prune            : options.prune ?? false
+      prune            : options.prune ?? false,
+      ...permissionGrantInvocation,
     };
 
     const authorization = await Message.createAuthorization({
       descriptor,
-      signer            : options.signer,
-      protocolRole      : options.protocolRole,
-      permissionGrantId : options.permissionGrantId,
-      delegatedGrant    : options.delegatedGrant
+      signer         : options.signer,
+      protocolRole   : options.protocolRole,
+      ...permissionGrantInvocation,
+      delegatedGrant : options.delegatedGrant
     });
     const message: RecordsDeleteMessage = { descriptor, authorization };
 

package/src/interfaces/records-query.ts

@@ -21,6 +21,7 @@ export type RecordsQueryOptions = {
   dateSort?: DateSort;
   pagination?: Pagination;
   signer?: MessageSigner;
+  permissionGrantId?: string;
   protocolRole?: string;
 
   /**
@@ -74,11 +75,16 @@ export class RecordsQuery extends AbstractMessage<RecordsQueryMessage> {
   }
 
   public static async create(options: RecordsQueryOptions): Promise<RecordsQuery> {
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId,
+    });
+
     const descriptor: RecordsQueryDescriptor = {
       interface        : DwnInterfaceName.Records,
       method           : DwnMethodName.Query,
       messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
       filter           : Records.normalizeFilter(options.filter),
+      ...permissionGrantInvocation,
       dateSort         : options.dateSort,
       pagination       : options.pagination,
     };
@@ -103,6 +109,7 @@ export class RecordsQuery extends AbstractMessage<RecordsQueryMessage> {
       authorization = await Message.createAuthorization({
         descriptor,
         signer,
+        ...permissionGrantInvocation,
         protocolRole   : options.protocolRole,
         delegatedGrant : options.delegatedGrant
       });

package/src/interfaces/records-read.ts

@@ -64,8 +64,11 @@ 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, dateSort } = options;
+    const { filter, signer, protocolRole, dateSort } = options;
     const currentTime = Time.getCurrentTimestamp();
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId
+    });
 
     if (options.filter.published === false) {
       if (dateSort === DateSort.PublishedAscending || dateSort === DateSort.PublishedDescending) {
@@ -81,8 +84,8 @@ export class RecordsRead extends AbstractMessage<RecordsReadMessage> {
       method           : DwnMethodName.Read,
       filter           : Records.normalizeFilter(filter),
       messageTimestamp : options.messageTimestamp ?? currentTime,
-      permissionGrantId,
       dateSort,
+      ...permissionGrantInvocation,
     };
 
     removeUndefinedProperties(descriptor);
@@ -93,7 +96,7 @@ export class RecordsRead extends AbstractMessage<RecordsReadMessage> {
       authorization = await Message.createAuthorization({
         descriptor,
         signer,
-        permissionGrantId,
+        ...permissionGrantInvocation,
         protocolRole,
         delegatedGrant: options.delegatedGrant
       });

package/src/interfaces/records-subscribe.ts

@@ -21,6 +21,7 @@ export type RecordsSubscribeOptions = {
   dateSort?: DateSort;
   pagination?: Pagination;
   signer?: MessageSigner;
+  permissionGrantId?: string;
   protocolRole?: string;
 
   /**
@@ -68,11 +69,16 @@ export class RecordsSubscribe extends AbstractMessage<RecordsSubscribeMessage> {
   }
 
   public static async create(options: RecordsSubscribeOptions): Promise<RecordsSubscribe> {
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId,
+    });
+
     const descriptor: RecordsSubscribeDescriptor = {
       interface        : DwnInterfaceName.Records,
       method           : DwnMethodName.Subscribe,
       messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
       filter           : Records.normalizeFilter(options.filter),
+      ...permissionGrantInvocation,
       dateSort         : options.dateSort,
       pagination       : options.pagination,
       cursor           : options.cursor,
@@ -89,6 +95,7 @@ export class RecordsSubscribe extends AbstractMessage<RecordsSubscribeMessage> {
       authorization = await Message.createAuthorization({
         descriptor,
         signer,
+        ...permissionGrantInvocation,
         protocolRole   : options.protocolRole,
         delegatedGrant : options.delegatedGrant
       });

package/src/interfaces/records-write.ts

@@ -267,7 +267,12 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     await Message.validateSignatureStructure(message.authorization.signature, message.descriptor, 'RecordsWriteSignaturePayload');
 
     if (message.authorization.ownerSignature !== undefined) {
-      await Message.validateSignatureStructure(message.authorization.ownerSignature, message.descriptor);
+      await Message.validateSignatureStructure(
+        message.authorization.ownerSignature,
+        message.descriptor,
+        'GenericSignaturePayload',
+        { validatePermissionGrantInvocation: false }
+      );
     }
 
     await validateAttestationIntegrity(message);
@@ -314,25 +319,28 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     const dataSize = options.dataSize ?? options.data!.length;
 
     const currentTime = Time.getCurrentTimestamp();
+    const permissionGrantInvocation = Message.normalizePermissionGrantInvocation({
+      permissionGrantId: options.permissionGrantId,
+    });
 
     const descriptor: RecordsWriteDescriptor = {
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      protocol          : normalizeProtocolUrl(options.protocol),
-      protocolPath      : options.protocolPath,
-      recipient         : options.recipient,
-      schema            : options.schema === undefined ? undefined : normalizeSchemaUrl(options.schema),
-      tags              : options.tags,
-      parentId          : RecordsWrite.getRecordIdFromContextId(options.parentContextId),
+      interface        : DwnInterfaceName.Records,
+      method           : DwnMethodName.Write,
+      protocol         : normalizeProtocolUrl(options.protocol),
+      protocolPath     : options.protocolPath,
+      recipient        : options.recipient,
+      schema           : options.schema === undefined ? undefined : normalizeSchemaUrl(options.schema),
+      tags             : options.tags,
+      parentId         : RecordsWrite.getRecordIdFromContextId(options.parentContextId),
       dataCid,
       dataSize,
-      dateCreated       : options.dateCreated ?? currentTime,
-      messageTimestamp  : options.messageTimestamp ?? currentTime,
-      published         : options.published,
-      datePublished     : options.datePublished,
-      dataFormat        : options.dataFormat,
-      permissionGrantId : options.permissionGrantId,
-      squash            : options.squash,
+      dateCreated      : options.dateCreated ?? currentTime,
+      messageTimestamp : options.messageTimestamp ?? currentTime,
+      published        : options.published,
+      datePublished    : options.datePublished,
+      dataFormat       : options.dataFormat,
+      squash           : options.squash,
+      ...permissionGrantInvocation,
     };
 
     // generate `datePublished` if the message is to be published but `datePublished` is not given
@@ -370,7 +378,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       await recordsWrite.sign({
         signer                     : options.signer,
         delegatedGrant             : options.delegatedGrant,
-        permissionGrantId          : options.permissionGrantId,
+        ...permissionGrantInvocation,
         protocolRole               : options.protocolRole,
         authorKeyDeliveryPublicKey : options.authorKeyDeliveryPublicKey,
       });

package/src/protocols/permissions.ts

@@ -14,6 +14,7 @@ import { FilterUtility } from '../utils/filter.js';
 import { Message } from '../core/message.js';
 import { PermissionGrant } from './permission-grant.js';
 import { PermissionRequest } from './permission-request.js';
+import { PERMISSIONS_PROTOCOL_URI } from '../core/constants.js';
 import { Records } from '../utils/records.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
 import { Time } from '../utils/time.js';
@@ -95,7 +96,7 @@ export class PermissionsProtocol implements CoreProtocol {
   /**
    * The URI of the DWN Permissions protocol.
    */
-  public static readonly uri = 'https://identity.foundation/dwn/permissions';
+  public static readonly uri = PERMISSIONS_PROTOCOL_URI;
 
   /**
    * The protocol path of the `request` record.
@@ -312,12 +313,24 @@ export class PermissionsProtocol implements CoreProtocol {
     dataEncodedMessage: DataEncodedRecordsWriteMessage,
   }> {
 
+    if (this.hasConflictingSubtreeScope(options.scope)) {
+      throw new DwnError(
+        DwnErrorCode.PermissionsProtocolCreateRequestScopeContextIdProtocolPathConflict,
+        'Permission request scopes cannot have both `contextId` and `protocolPath` present'
+      );
+    }
     if (this.isRecordPermissionScope(options.scope) && options.scope.protocol === undefined) {
       throw new DwnError(
         DwnErrorCode.PermissionsProtocolCreateRequestRecordsScopeMissingProtocol,
         'Permission request for Records must have a scope with a `protocol` property'
       );
     }
+    if (this.hasSubtreeScope(options.scope) && !this.hasProtocolScope(options.scope)) {
+      throw new DwnError(
+        DwnErrorCode.PermissionsProtocolCreateRequestSubtreeScopeMissingProtocol,
+        'Permission request subtree scopes must have a `protocol` property'
+      );
+    }
 
     const scope = PermissionsProtocol.normalizePermissionScope(options.scope);
 
@@ -371,12 +384,24 @@ export class PermissionsProtocol implements CoreProtocol {
     dataEncodedMessage: DataEncodedRecordsWriteMessage,
   }> {
 
+    if (this.hasConflictingSubtreeScope(options.scope)) {
+      throw new DwnError(
+        DwnErrorCode.PermissionsProtocolCreateGrantScopeContextIdProtocolPathConflict,
+        'Permission grant scopes cannot have both `contextId` and `protocolPath` present'
+      );
+    }
     if (this.isRecordPermissionScope(options.scope) && options.scope.protocol === undefined) {
       throw new DwnError(
         DwnErrorCode.PermissionsProtocolCreateGrantRecordsScopeMissingProtocol,
         'Permission grants for Records must have a scope with a `protocol` property'
       );
     }
+    if (this.hasSubtreeScope(options.scope) && !this.hasProtocolScope(options.scope)) {
+      throw new DwnError(
+        DwnErrorCode.PermissionsProtocolCreateGrantSubtreeScopeMissingProtocol,
+        'Permission grant subtree scopes must have a `protocol` property'
+      );
+    }
 
     const scope = PermissionsProtocol.normalizePermissionScope(options.scope);
 
@@ -600,6 +625,16 @@ export class PermissionsProtocol implements CoreProtocol {
     return 'protocol' in scope && scope.protocol !== undefined;
   }
 
+  private static hasSubtreeScope(scope: PermissionScope): scope is PermissionScope & ({ contextId: string } | { protocolPath: string }) {
+    return ('contextId' in scope && scope.contextId !== undefined)
+      || ('protocolPath' in scope && scope.protocolPath !== undefined);
+  }
+
+  private static hasConflictingSubtreeScope(scope: PermissionScope): boolean {
+    return ('contextId' in scope && scope.contextId !== undefined)
+      && ('protocolPath' in scope && scope.protocolPath !== undefined);
+  }
+
   /**
    * Validates that tags must include a protocol tag that matches the scoped protocol.
    */
@@ -633,18 +668,21 @@ export class PermissionsProtocol implements CoreProtocol {
       this.validateTags(requestOrGrant, scope.protocol);
     }
 
-    // if the scope is not a record permission scope, no additional validation is required
-    if (!this.isRecordPermissionScope(scope)) {
-      return;
-    }
-    // otherwise this is a record permission scope, more validation needed below
-
     // `contextId` and `protocolPath` are mutually exclusive
-    if (scope.contextId !== undefined && scope.protocolPath !== undefined) {
+    const hasContextId = 'contextId' in scope && scope.contextId !== undefined;
+    const hasProtocolPath = 'protocolPath' in scope && scope.protocolPath !== undefined;
+    if (hasContextId && hasProtocolPath) {
       throw new DwnError(
         DwnErrorCode.PermissionsProtocolValidateScopeContextIdProhibitedProperties,
         'Permission grants cannot have both `contextId` and `protocolPath` present'
       );
     }
+    if ((hasContextId || hasProtocolPath) && !this.hasProtocolScope(scope)) {
+      throw new DwnError(
+        DwnErrorCode.PermissionsProtocolValidateScopeSubtreeScopeMissingProtocol,
+        'Permission grant subtree scopes must have a `protocol` property'
+      );
+    }
+
   }
-};
+};