Added prune protocol action + ProtocolAuthorization refactoring (#…

…735)

- Added support for `prune` protocol action.
- Renamed "ancestor chain" to "record chain" because the chain often contains not just the ancestor records, but also record in concern which leads to confusion.
-  Simplified context and implementation of `constructRecordChain()` 
-  Refactored `authorizeAgainstAllowedActions()` to make it more easily understood.

json-schemas/interface-methods/protocol-rule-set.json

@@ -47,9 +47,11 @@
                   "type": "string",
                   "enum": [
                     "co-delete",
+                    "co-prune",
                     "co-update",
                     "create",
                     "delete",
+                    "prune",
                     "read",
                     "update"
                   ]

src/core/dwn-error.ts

@@ -68,7 +68,7 @@ export enum DwnErrorCode {
   ProtocolAuthorizationMissingRuleSet = 'ProtocolAuthorizationMissingRuleSet',
   ProtocolAuthorizationParentlessIncorrectProtocolPath = 'ProtocolAuthorizationParentlessIncorrectProtocolPath',
   ProtocolAuthorizationNotARole = 'ProtocolAuthorizationNotARole',
-  ProtocolAuthorizationParentNotFoundConstructingAncestorChain = 'ProtocolAuthorizationParentNotFoundConstructingAncestorChain',
+  ProtocolAuthorizationParentNotFoundConstructingRecordChain = 'ProtocolAuthorizationParentNotFoundConstructingRecordChain',
   ProtocolAuthorizationProtocolNotFound = 'ProtocolAuthorizationProtocolNotFound',
   ProtocolAuthorizationQueryWithoutRole = 'ProtocolAuthorizationQueryWithoutRole',
   ProtocolAuthorizationRoleMissingRecipient = 'ProtocolAuthorizationRoleMissingRecipient',

src/handlers/records-delete.ts

@@ -116,21 +116,26 @@ export class RecordsDeleteHandler implements MethodHandler {
     return messageReply;
   };
 
+  /**
+   * Authorizes a RecordsDelete message.
+   *
+   * @param newestRecordsWrite Newest RecordsWrite of the record to be deleted.
+   */
   private static async authorizeRecordsDelete(
     tenant: string,
     recordsDelete: RecordsDelete,
-    recordsWriteToDelete: RecordsWrite,
+    newestRecordsWrite: RecordsWrite,
     messageStore: MessageStore
   ): Promise<void> {
 
     if (Message.isSignedByAuthorDelegate(recordsDelete.message)) {
-      await recordsDelete.authorizeDelegate(recordsWriteToDelete.message, messageStore);
+      await recordsDelete.authorizeDelegate(newestRecordsWrite.message, messageStore);
     }
 
     if (recordsDelete.author === tenant) {
       return;
-    } else if (recordsWriteToDelete.message.descriptor.protocol !== undefined) {
-      await ProtocolAuthorization.authorizeDelete(tenant, recordsDelete, recordsWriteToDelete, messageStore);
+    } else if (newestRecordsWrite.message.descriptor.protocol !== undefined) {
+      await ProtocolAuthorization.authorizeDelete(tenant, recordsDelete, newestRecordsWrite, messageStore);
     } else {
       throw new DwnError(
         DwnErrorCode.RecordsDeleteAuthorizationFailed,

src/interfaces/protocols-configure.ts

@@ -183,7 +183,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
         );
       }
 
-      // Validate that if `who === recipient` and `of === undefined`, then `can` can only contain `co-delete` and `co-update`
+      // Validate that if `who === recipient` and `of === undefined`, then `can` can only contain `co-update`, `co-delete`, and `co-prune`.
       // We do not allow `read`, `write`, or `query` in the `can` array because:
       // - `read` - Recipients are always allowed to `read`.
       // - `write` - Entails ability to create and update.
@@ -192,11 +192,14 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       // - `query` - Only authorized using roles, so allowing direct recipients to query is outside the scope.
       if (actionRule.who === ProtocolActor.Recipient && actionRule.of === undefined) {
 
-        // throw if `can` contains a value that is not `co-update` or `co-delete`
-        if (actionRule.can.some((allowedAction) => ![ProtocolAction.CoUpdate, ProtocolAction.CoDelete].includes(allowedAction as ProtocolAction))) {
+        // throw if `can` contains a value that is not `co-update`, `co-delete`, or `co-prune`
+        const hasDisallowedAction = actionRule.can.some(
+          action => ![ProtocolAction.CoUpdate, ProtocolAction.CoDelete, ProtocolAction.CoPrune].includes(action as ProtocolAction)
+        );
+        if (hasDisallowedAction) {
           throw new DwnError(
             DwnErrorCode.ProtocolsConfigureInvalidRecipientOfAction,
-            'Rules for `recipient` without `of` property must have `can` containing only `co-update` or `co-delete`'
+            'Rules for `recipient` without `of` property must have `can` containing only `co-update`, `co-delete`, and `co-prune`.'
           );
         }
       }

src/interfaces/records-write.ts

@@ -957,7 +957,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   }
 
   /**
-   * Gets the initial write from the given list or record write.
+   * Gets the initial write from the given list of `RecordsWrite`.
    */
   public static async getInitialWrite(messages: GenericMessage[]): Promise<RecordsWriteMessage> {
     for (const message of messages) {
@@ -966,7 +966,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       }
     }
 
-    throw new DwnError(DwnErrorCode.RecordsWriteGetInitialWriteNotFound, `initial write is not found`);
+    throw new DwnError(DwnErrorCode.RecordsWriteGetInitialWriteNotFound, `Initial write is not found.`);
   }
 
   /**
@@ -1001,7 +1001,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   }
 
   /**
-   * Gets the DID of the author of the given message.
+   * Gets the DID of the attesters of the given message.
    */
   public static getAttesters(message: InternalRecordsWriteMessage): string[] {
     const attestationSignatures = message.attestation?.signatures ?? [];

src/types/protocols-types.ts

@@ -38,9 +38,11 @@ export enum ProtocolActor {
 
 export enum ProtocolAction {
   CoDelete = 'co-delete',
+  CoPrune = 'co-prune',
   CoUpdate = 'co-update',
   Create = 'create',
   Delete = 'delete',
+  Prune = 'prune',
   Query = 'query',
   Read = 'read',
   Subscribe = 'subscribe',

src/utils/records.ts

@@ -495,7 +495,7 @@ export class Records {
    * Checks if the filter supports returning published records.
    */
   static filterIncludesPublishedRecords(filter: RecordsFilter): boolean {
-    // When `published` and `datePublished` range are both undefined, published records can be returned.
+    // NOTE: published records should still be returned when `published` and `datePublished` range are both undefined.
     return filter.datePublished !== undefined || filter.published !== false;
   }
 

tests/core/protocol-authorization.spec.ts

@@ -21,7 +21,7 @@ describe('ProtocolAuthorization', () => {
       messageStoreStub.query.resolves({ messages: [] }); // simulate parent not in message store
 
       await expect(ProtocolAuthorization.authorizeWrite(alice.did, recordsWrite, messageStoreStub)).to.be.rejectedWith(
-        DwnErrorCode.ProtocolAuthorizationParentNotFoundConstructingAncestorChain
+        DwnErrorCode.ProtocolAuthorizationParentNotFoundConstructingRecordChain
       );
     });
   });