@enbox/dwn-sdk-js 0.3.7 → 0.3.8

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'
+      );
+    }
+
   }
-};
+};

package/src/sync/records-projection.ts

@@ -0,0 +1,328 @@
+import type { Filter } from '../types/query-types.js';
+import type { Hash } from '../types/smt-types.js';
+import type { MessageStore, MessageStoreOptions } from '../types/message-store.js';
+
+import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
+import { FilterUtility } from '../utils/filter.js';
+import { hashToHex } from '../smt/smt-utils.js';
+import { isRecordsPrimaryProjectionExcludedProtocol } from '../core/constants.js';
+import { lexicographicalCompare } from '../utils/string.js';
+import { Message } from '../core/message.js';
+import { SMTStoreMemory } from '../smt/smt-store-memory.js';
+import { SparseMerkleTree } from '../smt/sparse-merkle-tree.js';
+
+/**
+ * Projection-root algorithm for record-primary scoped subsets.
+ *
+ * This version builds an on-demand SMT over latest Records primary message CIDs
+ * selected by protocol plus optional exact protocolPath or context subtree.
+ * Dependency records, protocol configs, and record data payloads are not part
+ * of this root.
+ */
+export const RECORDS_PROJECTION_ROOT_VERSION = 'records-primary-scope-root-v1';
+
+/**
+ * A Records primary projection scope.
+ *
+ * `protocolPath` is an exact type-path match. `contextId` is a boundary-aware
+ * subtree match: the candidate context must equal the scoped context or start
+ * with `${contextId}/`. `protocolPath` and `contextId` are mutually exclusive.
+ */
+export type RecordsProjectionScope = {
+  protocol: string;
+  protocolPath?: string;
+  contextId?: string;
+};
+
+export type RecordsProjectionInput = {
+  tenant: string;
+  messageStore: MessageStore;
+  scopes: readonly [RecordsProjectionScope, ...RecordsProjectionScope[]];
+  options?: MessageStoreOptions;
+};
+
+export type RecordsProjectionTreeInput = RecordsProjectionInput & {
+  prefix: boolean[];
+};
+
+export type RecordsProjectionSnapshot = {
+  getRoot(): Promise<Hash>;
+  getRootHex(): Promise<string>;
+  getSubtreeHash(prefix: boolean[]): Promise<Hash>;
+  getLeaves(prefix: boolean[]): Promise<string[]>;
+  close(): Promise<void>;
+};
+
+export type NormalizedRecordsProjectionScope = {
+  protocol: string;
+} | {
+  protocol: string;
+  protocolPath: string;
+} | {
+  protocol: string;
+  contextId: string;
+};
+
+/**
+ * Computes deterministic on-demand roots for Records projections.
+ *
+ * The snapshot API performs one store enumeration and serves tree operations
+ * from that in-memory view. A future store-level snapshot/high-watermark can be
+ * threaded through the `options` input without changing the projection shape.
+ */
+export class RecordsProjection {
+
+  /**
+   * Returns the sorted latest Records primary message CIDs covered by a scope union.
+   */
+  public static async getPrimaryMessageCids({
+    tenant,
+    messageStore,
+    scopes,
+    options,
+  }: RecordsProjectionInput): Promise<string[]> {
+    const filters = RecordsProjection.normalizeScopes(scopes)
+      .filter(scope => !isRecordsPrimaryProjectionExcludedProtocol(scope.protocol))
+      .flatMap(scope => RecordsProjection.constructFilters(scope));
+    if (filters.length === 0) {
+      return [];
+    }
+
+    const { messages } = await messageStore.query(tenant, filters, undefined, undefined, options);
+    const messageCids = await Promise.all(messages.map(message => Message.getCid(message)));
+
+    return [...new Set(messageCids)].sort(lexicographicalCompare); // NOSONAR — projection IDs require locale-independent bytewise ordering.
+  }
+
+  /**
+   * Returns the projection root hash.
+   */
+  public static async getRoot(input: RecordsProjectionInput): Promise<Hash> {
+    return RecordsProjection.withTree(input, tree => tree.getRoot());
+  }
+
+  /**
+   * Returns the projection root hash encoded as lowercase hex.
+   */
+  public static async getRootHex(input: RecordsProjectionInput): Promise<string> {
+    return hashToHex(await RecordsProjection.getRoot(input));
+  }
+
+  /**
+   * Returns the subtree hash for a bit prefix within this projection.
+   */
+  public static async getSubtreeHash(input: RecordsProjectionTreeInput): Promise<Hash> {
+    return RecordsProjection.withTree(input, tree => tree.getSubtreeHash(input.prefix));
+  }
+
+  /**
+   * Returns the message CIDs under a bit prefix within this projection.
+   */
+  public static async getLeaves(input: RecordsProjectionTreeInput): Promise<string[]> {
+    return RecordsProjection.withTree(input, tree => tree.getLeaves(input.prefix));
+  }
+
+  /**
+   * Builds an in-memory projection tree from one primary-CID enumeration.
+   */
+  public static async createSnapshot(input: RecordsProjectionInput): Promise<RecordsProjectionSnapshot> {
+    const tree = await RecordsProjection.createTree(input);
+    return {
+      close          : () => tree.close(),
+      getLeaves      : (prefix: boolean[]) => tree.getLeaves(prefix),
+      getRoot        : () => tree.getRoot(),
+      getRootHex     : async () => hashToHex(await tree.getRoot()),
+      getSubtreeHash : (prefix: boolean[]) => tree.getSubtreeHash(prefix),
+    };
+  }
+
+  /**
+   * Normalizes a scope union into sorted, duplicate-free, subsumption-reduced entries.
+   */
+  public static normalizeScopes(
+    scopes: readonly [RecordsProjectionScope, ...RecordsProjectionScope[]],
+  ): [NormalizedRecordsProjectionScope, ...NormalizedRecordsProjectionScope[]] {
+    if (scopes.length === 0) {
+      throw new Error('RecordsProjection: scopes must contain at least one scope.');
+    }
+
+    const normalized = scopes.map(scope => RecordsProjection.normalizeScope(scope));
+    const deduped = new Map<string, NormalizedRecordsProjectionScope>();
+    for (const scope of normalized) {
+      deduped.set(RecordsProjection.scopeKey(scope), scope);
+    }
+
+    const uniqueScopes = [...deduped.values()];
+    const protocolWide = new Set(
+      uniqueScopes
+        .filter(scope => RecordsProjection.isProtocolWideScope(scope))
+        .map(scope => scope.protocol)
+    );
+
+    const reduced = uniqueScopes.filter(scope => {
+      if (protocolWide.has(scope.protocol)) {
+        return RecordsProjection.isProtocolWideScope(scope);
+      }
+
+      if (RecordsProjection.isContextScope(scope)) {
+        return !uniqueScopes.some(candidate =>
+          candidate !== scope &&
+          RecordsProjection.isContextScope(candidate) &&
+          candidate.protocol === scope.protocol &&
+          RecordsProjection.contextIdSubsumes(candidate.contextId, scope.contextId)
+        );
+      }
+
+      return true;
+    });
+
+    const result = reduced.sort(RecordsProjection.compareScopes);
+    return result as [NormalizedRecordsProjectionScope, ...NormalizedRecordsProjectionScope[]];
+  }
+
+  private static async withTree<T>(
+    input: RecordsProjectionInput,
+    fn: (tree: SparseMerkleTree) => Promise<T>,
+  ): Promise<T> {
+    const tree = await RecordsProjection.createTree(input);
+
+    try {
+      return await fn(tree);
+    } finally {
+      await tree.close();
+    }
+  }
+
+  private static async createTree(input: RecordsProjectionInput): Promise<SparseMerkleTree> {
+    const tree = new SparseMerkleTree(new SMTStoreMemory());
+    await tree.initialize();
+
+    try {
+      const messageCids = await RecordsProjection.getPrimaryMessageCids(input);
+      for (const messageCid of messageCids) {
+        await tree.insert(messageCid);
+      }
+
+      return tree;
+    } catch (error) {
+      await tree.close();
+      throw error;
+    }
+  }
+
+  private static normalizeScope(scope: RecordsProjectionScope): NormalizedRecordsProjectionScope {
+    const protocol = RecordsProjection.requireNonEmptyString(scope.protocol, 'protocol');
+
+    if (scope.protocolPath !== undefined && scope.contextId !== undefined) {
+      throw new Error('RecordsProjection: protocolPath and contextId scopes are mutually exclusive.');
+    }
+
+    if (scope.protocolPath !== undefined) {
+      return {
+        protocol,
+        protocolPath: RecordsProjection.requireNonEmptyString(scope.protocolPath, 'protocolPath'),
+      };
+    }
+
+    if (scope.contextId !== undefined) {
+      return {
+        protocol,
+        contextId: RecordsProjection.requireNonEmptyString(scope.contextId, 'contextId'),
+      };
+    }
+
+    return { protocol };
+  }
+
+  private static constructFilters(scope: NormalizedRecordsProjectionScope): Filter[] {
+    const baseFilter: Filter = {
+      interface         : DwnInterfaceName.Records,
+      isLatestBaseState : true,
+      protocol          : scope.protocol,
+    };
+
+    if ('protocolPath' in scope) {
+      return [{ ...baseFilter, protocolPath: scope.protocolPath }];
+    }
+
+    if ('contextId' in scope) {
+      const childContextPrefix = `${scope.contextId}/`;
+      return [
+        { ...baseFilter, contextId: scope.contextId },
+        {
+          ...baseFilter,
+          contextId: FilterUtility.constructPrefixFilterAsRangeFilter(childContextPrefix),
+        },
+      ];
+    }
+
+    return [baseFilter];
+  }
+
+  private static requireNonEmptyString(value: string, field: string): string {
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error(`RecordsProjection: ${field} must be a non-empty string.`);
+    }
+
+    return value;
+  }
+
+  private static scopeKey(scope: NormalizedRecordsProjectionScope): string {
+    if ('protocolPath' in scope) {
+      return `${scope.protocol}\u001fprotocolPath\u001f${scope.protocolPath}`;
+    }
+
+    if ('contextId' in scope) {
+      return `${scope.protocol}\u001fcontextId\u001f${scope.contextId}`;
+    }
+
+    return `${scope.protocol}\u001fprotocol`;
+  }
+
+  private static isProtocolWideScope(
+    scope: NormalizedRecordsProjectionScope,
+  ): scope is { protocol: string } {
+    return !('protocolPath' in scope) && !('contextId' in scope);
+  }
+
+  private static isContextScope(
+    scope: NormalizedRecordsProjectionScope,
+  ): scope is { protocol: string; contextId: string } {
+    return 'contextId' in scope;
+  }
+
+  private static contextIdSubsumes(parentContextId: string, childContextId: string): boolean {
+    return childContextId === parentContextId ||
+      childContextId.startsWith(`${parentContextId}/`);
+  }
+
+  private static compareScopes(
+    a: NormalizedRecordsProjectionScope,
+    b: NormalizedRecordsProjectionScope,
+  ): number {
+    const protocolCompare = lexicographicalCompare(a.protocol, b.protocol);
+    if (protocolCompare !== 0) {
+      return protocolCompare;
+    }
+
+    const aRank = RecordsProjection.scopeRank(a);
+    const bRank = RecordsProjection.scopeRank(b);
+    if (aRank !== bRank) {
+      return aRank - bRank;
+    }
+
+    return lexicographicalCompare(RecordsProjection.scopeValue(a), RecordsProjection.scopeValue(b));
+  }
+
+  private static scopeRank(scope: NormalizedRecordsProjectionScope): number {
+    if ('protocolPath' in scope) { return 1; }
+    if ('contextId' in scope) { return 2; }
+    return 0;
+  }
+
+  private static scopeValue(scope: NormalizedRecordsProjectionScope): string {
+    if ('protocolPath' in scope) { return scope.protocolPath; }
+    if ('contextId' in scope) { return scope.contextId; }
+    return '';
+  }
+}

package/src/types/message-types.ts

@@ -92,6 +92,7 @@ export type DelegatedGrantRecordsWriteMessage = {
 export type GenericSignaturePayload = {
   descriptorCid: string;
   permissionGrantId?: string;
+  permissionGrantIds?: string[];
 
   /**
    * Record ID of a permission grant DWN `RecordsWrite` with `delegated` set to `true`.