Improved typing of PermissionGrant.parse() to avoid misuse (#760)

1. Improved typing of PermissionGrant.parse() to avoid misuse
2. Detected and fixed a couple of unimportant misuses in the tests after
the above change (case in point).

src/core/message.ts

@@ -1,5 +1,5 @@
+import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
 import type { GeneralJws } from '../types/jws-types.js';
-import type { RecordsWriteMessage } from '../types/records-types.js';
 import type { Signer } from '../types/signer.js';
 import type { AuthorizationModel, Descriptor, GenericMessage, GenericSignaturePayload } from '../types/message-types.js';
 
@@ -79,7 +79,7 @@ export class Message {
   public static async createAuthorization(input: {
     descriptor: Descriptor,
     signer: Signer,
-    delegatedGrant?: RecordsWriteMessage,
+    delegatedGrant?: DataEncodedRecordsWriteMessage,
     permissionGrantId?: string,
     protocolRole?: string
   }): Promise<AuthorizationModel> {

src/interfaces/records-delete.ts

@@ -1,7 +1,7 @@
 import type { KeyValues } from '../types/query-types.js';
 import type { MessageStore } from '../types//message-store.js';
 import type { Signer } from '../types/signer.js';
-import type { RecordsDeleteDescriptor, RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
+import type { DataEncodedRecordsWriteMessage, RecordsDeleteDescriptor, RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import { Message } from '../core/message.js';
@@ -26,7 +26,7 @@ export type RecordsDeleteOptions = {
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
    */
-  delegatedGrant?: RecordsWriteMessage;
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
 };
 
 export class RecordsDelete extends AbstractMessage<RecordsDeleteMessage> {

src/interfaces/records-query.ts

@@ -1,7 +1,7 @@
 import type { MessageStore } from '../types//message-store.js';
 import type { Pagination } from '../types/message-types.js';
 import type { Signer } from '../types/signer.js';
-import type { RecordsFilter, RecordsQueryDescriptor, RecordsQueryMessage, RecordsWriteMessage } from '../types/records-types.js';
+import type { DataEncodedRecordsWriteMessage, RecordsFilter, RecordsQueryDescriptor, RecordsQueryMessage } from '../types/records-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import { DateSort } from '../types/records-types.js';
@@ -26,7 +26,7 @@ export type RecordsQueryOptions = {
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
    */
-  delegatedGrant?: RecordsWriteMessage;
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
 };
 
 /**

src/interfaces/records-read.ts

@@ -1,6 +1,6 @@
 import type { MessageStore } from '../types//message-store.js';
 import type { Signer } from '../types/signer.js';
-import type { RecordsFilter , RecordsReadDescriptor, RecordsReadMessage, RecordsWriteMessage } from '../types/records-types.js';
+import type { DataEncodedRecordsWriteMessage, RecordsFilter , RecordsReadDescriptor, RecordsReadMessage, RecordsWriteMessage } from '../types/records-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import { Message } from '../core/message.js';
@@ -25,7 +25,7 @@ export type RecordsReadOptions = {
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
    */
-  delegatedGrant?: RecordsWriteMessage;
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
 };
 
 export class RecordsRead extends AbstractMessage<RecordsReadMessage> {

src/interfaces/records-subscribe.ts

@@ -1,6 +1,6 @@
 import type { MessageStore } from '../types/message-store.js';
 import type { Signer } from '../types/signer.js';
-import type { RecordsFilter, RecordsSubscribeDescriptor, RecordsSubscribeMessage, RecordsWriteMessage } from '../types/records-types.js';
+import type { DataEncodedRecordsWriteMessage, RecordsFilter, RecordsSubscribeDescriptor, RecordsSubscribeMessage } from '../types/records-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import { Message } from '../core/message.js';
@@ -22,7 +22,7 @@ export type RecordsSubscribeOptions = {
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
    */
-  delegatedGrant?: RecordsWriteMessage;
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
 };
 
 /**

src/interfaces/records-write.ts

@@ -5,6 +5,7 @@ import type { MessageStore } from '../types/message-store.js';
 import type { PublicJwk } from '../types/jose-types.js';
 import type { Signer } from '../types/signer.js';
 import type {
+  DataEncodedRecordsWriteMessage,
   EncryptedKey,
   EncryptionProperty,
   InternalRecordsWriteMessage,
@@ -66,7 +67,7 @@ export type RecordsWriteOptions = {
   /**
    * The delegated grant invoked to sign on behalf of the logical author, which is the grantor of the delegated grant.
    */
-  delegatedGrant?: RecordsWriteMessage;
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
 
   attestationSigners?: Signer[];
   encryptionInput?: EncryptionInput;
@@ -148,7 +149,7 @@ export type CreateFromOptions = {
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
    */
-  delegatedGrant?: RecordsWriteMessage;
+  delegatedGrant?: DataEncodedRecordsWriteMessage;
 
   attestationSigners?: Signer[];
   encryptionInput?: EncryptionInput;
@@ -491,7 +492,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    */
   public async sign(options: {
     signer: Signer,
-    delegatedGrant?: RecordsWriteMessage,
+    delegatedGrant?: DataEncodedRecordsWriteMessage,
     permissionGrantId?: string,
     protocolRole?: string
   }): Promise<void> {
@@ -576,7 +577,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    * This is used when a DWN owner-delegate wants to retain a copy of a message that the owner did not author.
    * NOTE: requires the `RecordsWrite` to already have the author's signature.
    */
-  public async signAsOwnerDelegate(signer: Signer, delegatedGrant: RecordsWriteMessage): Promise<void> {
+  public async signAsOwnerDelegate(signer: Signer, delegatedGrant: DataEncodedRecordsWriteMessage): Promise<void> {
     if (this._author === undefined) {
       throw new DwnError(
         DwnErrorCode.RecordsWriteSignAsOwnerDelegateUnknownAuthor,

src/protocols/permission-grant.ts

@@ -1,4 +1,4 @@
-import type { RecordsQueryReplyEntry, RecordsWriteMessage } from '../types/records-types.js';
+import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
 
 import type { PermissionConditions, PermissionGrantData, PermissionScope } from '../types/permission-types.js';
 
@@ -61,23 +61,23 @@ export class PermissionGrant {
    */
   public readonly conditions?: PermissionConditions;
 
-  public static async parse(message: RecordsWriteMessage): Promise<PermissionGrant> {
+  public static async parse(message: DataEncodedRecordsWriteMessage): Promise<PermissionGrant> {
     const permissionGrant = new PermissionGrant(message);
     return permissionGrant;
   }
 
   /**
    * Creates a Permission Grant abstraction for
    */
-  private constructor(message: RecordsWriteMessage) {
+  private constructor(message: DataEncodedRecordsWriteMessage) {
     // properties derived from the generic DWN message properties
     this.id = message.recordId;
     this.grantor = Message.getSigner(message)!;
     this.grantee = message.descriptor.recipient!;
     this.dateGranted = message.descriptor.dateCreated;
 
     // properties from the data payload itself.
-    const permissionGrantEncoded = (message as RecordsQueryReplyEntry).encodedData!;
+    const permissionGrantEncoded = message.encodedData;
     const permissionGrant = Encoder.base64UrlToObject(permissionGrantEncoded) as PermissionGrantData;
     this.dateExpires = permissionGrant.dateExpires;
     this.delegated = permissionGrant.delegated;

src/protocols/permissions.ts

@@ -377,7 +377,7 @@ export class PermissionsProtocol {
       );
     }
 
-    const permissionGrantMessage = possibleGrantMessage as RecordsWriteMessage;
+    const permissionGrantMessage = possibleGrantMessage as DataEncodedRecordsWriteMessage;
     const permissionGrant = await PermissionGrant.parse(permissionGrantMessage);
 
     return permissionGrant;

src/types/message-types.ts

@@ -45,7 +45,7 @@ type DelegatedGrantRecordsWriteMessage = {
   },
   recordId: string,
   contextId?: string;
-  // NOTE: This is a direct copy of `RecordsWriteDescriptor` to avoid circular references.
+  // NOTE: This is a direct expansion and copy of `DataEncodedRecordsWriteMessage` to avoid circular references.
   descriptor: {
     interface: DwnInterfaceName.Records;
     method: DwnMethodName.Write;
@@ -62,6 +62,7 @@ type DelegatedGrantRecordsWriteMessage = {
     datePublished?: string;
     dataFormat: string;
   };
+  encodedData: string;
 };
 
 /**

src/types/records-types.ts

@@ -112,7 +112,7 @@ export type DataEncodedRecordsWriteMessage = RecordsWriteMessage & {
   /**
    * The encoded data of the record if the data associated with the record is equal or smaller than `DwnConstant.maxDataSizeAllowedToBeEncoded`.
    */
-  encodedData?: string;
+  encodedData: string;
 };
 
 export type RecordsQueryDescriptor = {

tests/interfaces/records-write.spec.ts

@@ -278,7 +278,7 @@ describe('RecordsWrite', () => {
       });
 
       const createPromise = RecordsWrite.create({
-        delegatedGrant : grantToBob.recordsWrite.message,
+        delegatedGrant : grantToBob.dataEncodedMessage,
         dataFormat     : 'application/octet-stream',
         data           : TestDataGenerator.randomBytes(10),
       });
@@ -452,7 +452,7 @@ describe('RecordsWrite', () => {
         scope
       });
 
-      await expect(recordsWrite.signAsOwnerDelegate(Jws.createSigner(bob), ownerDelegatedGrant.recordsWrite.message))
+      await expect(recordsWrite.signAsOwnerDelegate(Jws.createSigner(bob), ownerDelegatedGrant.dataEncodedMessage))
         .to.be.rejectedWith(DwnErrorCode.RecordsWriteSignAsOwnerDelegateUnknownAuthor);
 
       expect(recordsWrite.owner).to.be.undefined;