Ensure protocolRole is maintained between query/read and subscribe/read. (#954)

Before this PR that were some inconsistencies with using `protocolRole`.

There were instances where a user would query using a role but not be able to read the data of the given record because the role was not being applied. Same would happen during update/delete.

This PR allows the READ operation to inherit the `protocolRole` used for a `query` or `subscribe` if it exists.
Additionally it provides the user the ability to provide a different role when performing an `update` or `delete` operation.

Author: LiranCohen

.changeset/many-suns-think.md

@@ -0,0 +1,8 @@
+---
+"@web5/agent": patch
+"@web5/identity-agent": patch
+"@web5/proxy-agent": patch
+"@web5/user-agent": patch
+---
+
+Add `getProtocolRole` util

.changeset/slimy-mayflies-hide.md

@@ -0,0 +1,5 @@
+---
+"@web5/api": patch
+---
+
+Ensure protocolRole is maintained between query/read and subscribe/read.

packages/agent/src/utils.ts

@@ -1,5 +1,5 @@
 import type { DidUrlDereferencer } from '@web5/dids';
-import { PaginationCursor, RecordsDeleteMessage, RecordsWriteMessage } from '@tbd54566975/dwn-sdk-js';
+import { Jws, PaginationCursor, RecordsDeleteMessage, RecordsWriteMessage } from '@tbd54566975/dwn-sdk-js';
 
 import { Readable } from '@web5/common';
 import { utils as didUtils } from '@web5/dids';
@@ -42,6 +42,14 @@ export function getRecordAuthor(record: RecordsWriteMessage | RecordsDeleteMessa
   return Message.getAuthor(record);
 }
 
+/**
+ * Get the `protocolRole` string from the signature payload of the given RecordsWriteMessage or RecordsDeleteMessage.
+ */
+export function getRecordProtocolRole(message: RecordsWriteMessage | RecordsDeleteMessage): string | undefined {
+  const signaturePayload = Jws.decodePlainObjectPayload(message.authorization.signature);
+  return signaturePayload?.protocolRole;
+}
+
 export function isRecordsWrite(obj: unknown): obj is RecordsWrite {
   // Validate that the given value is an object.
   if (!obj || typeof obj !== 'object' || obj === null) return false;

packages/agent/tests/utils.spec.ts

@@ -1,9 +1,18 @@
 import { expect } from 'chai';
+import sinon from 'sinon';
 
-import { DateSort, Message, TestDataGenerator } from '@tbd54566975/dwn-sdk-js';
-import { getPaginationCursor, getRecordAuthor, getRecordMessageCid } from '../src/utils.js';
+import { DateSort, Jws, Message, TestDataGenerator } from '@tbd54566975/dwn-sdk-js';
+import { getPaginationCursor, getRecordAuthor, getRecordMessageCid, getRecordProtocolRole } from '../src/utils.js';
 
 describe('Utils', () => {
+  beforeEach(() => {
+    sinon.restore();
+  });
+
+  after(() => {
+    sinon.restore();
+  });
+
   describe('getPaginationCursor', () => {
     it('should return a PaginationCursor object', async () => {
       // create a RecordWriteMessage object which is published
@@ -84,4 +93,35 @@ describe('Utils', () => {
       expect(deleteAuthorFromFunction!).to.equal(recordsDeleteAuthor.did);
     });
   });
+
+  describe('getRecordProtocolRole', () => {
+    it('gets a protocol role from a RecordsWrite', async () => {
+      const recordsWrite = await TestDataGenerator.generateRecordsWrite({ protocolRole: 'some-role' });
+      const role = getRecordProtocolRole(recordsWrite.message);
+      expect(role).to.equal('some-role');
+    });
+
+    it('gets a protocol role from a RecordsDelete', async () => {
+      const recordsDelete = await TestDataGenerator.generateRecordsDelete({ protocolRole: 'some-role' });
+      const role = getRecordProtocolRole(recordsDelete.message);
+      expect(role).to.equal('some-role');
+    });
+
+    it('returns undefined if no role is defined', async () => {
+      const recordsWrite = await TestDataGenerator.generateRecordsWrite();
+      const writeRole = getRecordProtocolRole(recordsWrite.message);
+      expect(writeRole).to.be.undefined;
+
+      const recordsDelete = await TestDataGenerator.generateRecordsDelete();
+      const deleteRole = getRecordProtocolRole(recordsDelete.message);
+      expect(deleteRole).to.be.undefined;
+    });
+
+    it('returns undefined if decodedObject is undefined', async () => {
+      sinon.stub(Jws, 'decodePlainObjectPayload').returns(undefined);
+      const recordsWrite = await TestDataGenerator.generateRecordsWrite();
+      const writeRole = getRecordProtocolRole(recordsWrite.message);
+      expect(writeRole).to.be.undefined;
+    });
+  });
 });

packages/api/src/dwn-api.ts

@@ -699,6 +699,7 @@ export class DwnApi {
              */
             remoteOrigin : request.from,
             delegateDid  : this.delegateDid,
+            protocolRole : agentRequest.messageParams.protocolRole,
             ...entry as DwnMessage[DwnInterface.RecordsWrite]
           };
           const record = new Record(this.agent, recordOptions, this.permissionsApi);
@@ -829,6 +830,7 @@ export class DwnApi {
             connectedDid   : this.connectedDid,
             delegateDid    : this.delegateDid,
             permissionsApi : this.permissionsApi,
+            protocolRole   : request.message.protocolRole,
             request
           })
         };

packages/api/src/record.ts

@@ -21,6 +21,7 @@ import {
   SendDwnRequest,
   PermissionsApi,
   AgentPermissionsApi,
+  getRecordProtocolRole
 } from '@web5/agent';
 
 import { Convert, isEmptyObject, NodeStream, removeUndefinedProperties, Stream } from '@web5/common';
@@ -183,6 +184,9 @@ export type RecordDeleteParams = {
 
   /** The timestamp indicating when the record was deleted. */
   dateModified?: DwnMessageDescriptor[DwnInterface.RecordsDelete]['messageTimestamp'];
+
+  /** The protocol role under which this record will be deleted. */
+  protocolRole?: string;
 };
 
 /**
@@ -311,7 +315,6 @@ export class Record implements RecordModel {
   /** Tags of the record */
   get tags() { return this._recordsWriteDescriptor?.tags; }
 
-
   // Getters for for properties that depend on the current state of the Record.
   /** DID that is the logical author of the Record. */
   get author(): string { return this._author; }
@@ -703,7 +706,7 @@ export class Record implements RecordModel {
    *
    * @beta
    */
-  async update({ dateModified, data, ...params }: RecordUpdateParams): Promise<DwnResponseStatus> {
+  async update({ dateModified, data, protocolRole, ...params }: RecordUpdateParams): Promise<DwnResponseStatus> {
 
     if (this.deleted) {
       throw new Error('Record: Cannot revive a deleted record.');
@@ -718,6 +721,7 @@ export class Record implements RecordModel {
       ...descriptor,
       ...params,
       parentContextId,
+      protocolRole     : protocolRole ?? this._protocolRole, // Use the current protocolRole if not provided.
       messageTimestamp : dateModified, // Map Record class `dateModified` property to DWN SDK `messageTimestamp`
       recordId         : this._recordId
     };
@@ -786,7 +790,7 @@ export class Record implements RecordModel {
 
       // Only update the local Record instance mutable properties if the record was successfully (over)written.
       this._authorization = responseMessage.authorization;
-      this._protocolRole = params.protocolRole;
+      this._protocolRole = updateMessage.protocolRole;
       mutableDescriptorProperties.forEach(property => {
         this._descriptor[property] = responseMessage.descriptor[property];
       });
@@ -834,15 +838,19 @@ export class Record implements RecordModel {
       store
     };
 
-    if (this.deleted) {
-      // if we have a delete message we can just use it
+    // Check to see if the provided protocolRole within the deleteParams is different from the current protocolRole.
+    const differentRole = deleteParams?.protocolRole ? getRecordProtocolRole(this.rawMessage)  !== deleteParams.protocolRole : false;
+    // If the record is already in a deleted state but the protocolRole is different, we need to construct a delete message with the new protocolRole
+    // otherwise we can just use the existing delete message.
+    if (this.deleted && !differentRole) {
       deleteOptions.rawMessage = this.rawMessage as DwnMessage[DwnInterface.RecordsDelete];
     } else {
       // otherwise we construct a delete message given the `RecordDeleteParams`
       deleteOptions.messageParams = {
         prune            : prune,
         recordId         : this._recordId,
         messageTimestamp : dateModified,
+        protocolRole     : deleteParams?.protocolRole ?? this._protocolRole // if no protocolRole is provided, use the current protocolRole
       };
     }
 
@@ -1023,7 +1031,7 @@ export class Record implements RecordModel {
   private async readRecordData({ target, isRemote }: { target: string, isRemote: boolean }) {
     const readRequest: ProcessDwnRequest<DwnInterface.RecordsRead> = {
       author        : this._connectedDid,
-      messageParams : { filter: { recordId: this.id } },
+      messageParams : { filter: { recordId: this.id }, protocolRole: this._protocolRole },
       messageType   : DwnInterface.RecordsRead,
       target,
     };

packages/api/src/subscription-util.ts

@@ -9,10 +9,11 @@ export class SubscriptionUtil {
   /**
    * Creates a record subscription handler that can be used to process incoming {Record} messages.
    */
-  static recordSubscriptionHandler({ agent, connectedDid, request, delegateDid, permissionsApi }:{
+  static recordSubscriptionHandler({ agent, connectedDid, request, delegateDid, protocolRole, permissionsApi }:{
     agent: Web5Agent;
     connectedDid: string;
     delegateDid?: string;
+    protocolRole?: string;
     permissionsApi?: PermissionsApi;
     request: RecordsSubscribeRequest;
   }): DwnRecordSubscriptionHandler {
@@ -31,6 +32,7 @@ export class SubscriptionUtil {
       const record = new Record(agent, {
         ...message,
         ...recordOptions,
+        protocolRole,
         delegateDid: delegateDid,
       }, permissionsApi);