Added support for owner-delegated grant (#707)

1. Added support for owner-delegated grant
2. Added missing checks for author-deleted grant:
   a. Disallowed invocation of non-delegated grant as delegated grant
   b. Disallowed mismatching of grant ID referenced and CID of actual given grant
3. Added numerous tests to catch up on missing scenario tests for delegated grants in general

json-schemas/authorization-owner.json

@@ -12,6 +12,9 @@
     },
     "ownerSignature": {
       "$ref": "https://identity.foundation/dwn/json-schemas/general-jws.json"
+    },
+    "ownerDelegatedGrant": {
+      "$ref": "https://identity.foundation/dwn/json-schemas/permissions-grant.json"
     }
   },
   "description": "`signature` can exist by itself. But if `ownerSignature` is present, then `signature` must also exist",

src/core/auth.ts

@@ -24,10 +24,16 @@ export async function authenticate(authorizationModel: AuthorizationModel | unde
   }
 
   if (authorizationModel.authorDelegatedGrant !== undefined) {
-    // verify the signature of the grantor of the delegated grant
+    // verify the signature of the grantor of the author-delegated grant
     const authorDelegatedGrant = await PermissionsGrant.parse(authorizationModel.authorDelegatedGrant);
     await GeneralJwsVerifier.verifySignatures(authorDelegatedGrant.message.authorization.signature, didResolver);
   }
+
+  if (authorizationModel.ownerDelegatedGrant !== undefined) {
+    // verify the signature of the grantor of the owner-delegated grant
+    const ownerDelegatedGrant = await PermissionsGrant.parse(authorizationModel.ownerDelegatedGrant);
+    await GeneralJwsVerifier.verifySignatures(ownerDelegatedGrant.message.authorization.signature, didResolver);
+  }
 }
 
 /**

src/core/dwn-error.ts

@@ -90,6 +90,10 @@ export enum DwnErrorCode {
   ProtocolsConfigureRoleDoesNotExistAtGivenPath = 'ProtocolsConfigureRoleDoesNotExistAtGivenPath',
   ProtocolsConfigureUnauthorized = 'ProtocolsConfigureUnauthorized',
   ProtocolsQueryUnauthorized = 'ProtocolsQueryUnauthorized',
+  RecordsAuthorDelegatedGrantAndIdExistenceMismatch = 'RecordsAuthorDelegatedGrantAndIdExistenceMismatch',
+  RecordsAuthorDelegatedGrantCidMismatch = 'RecordsAuthorDelegatedGrantCidMismatch',
+  RecordsAuthorDelegatedGrantGrantedToAndOwnerSignatureMismatch = 'RecordsAuthorDelegatedGrantGrantedToAndOwnerSignatureMismatch',
+  RecordsAuthorDelegatedGrantNotADelegatedGrant = 'RecordsAuthorDelegatedGrantNotADelegatedGrant',
   RecordsDecryptNoMatchingKeyEncryptedFound = 'RecordsDecryptNoMatchingKeyEncryptedFound',
   RecordsDeleteAuthorizationFailed = 'RecordsDeleteAuthorizationFailed',
   RecordsQueryCreateFilterPublishedSortInvalid = 'RecordsQueryCreateFilterPublishedSortInvalid',
@@ -105,6 +109,10 @@ export enum DwnErrorCode {
   RecordsGrantAuthorizationScopeSchema = 'RecordsGrantAuthorizationScopeSchema',
   RecordsDerivePrivateKeyUnSupportedCurve = 'RecordsDerivePrivateKeyUnSupportedCurve',
   RecordsInvalidAncestorKeyDerivationSegment = 'RecordsInvalidAncestorKeyDerivationSegment',
+  RecordsOwnerDelegatedGrantAndIdExistenceMismatch = 'RecordsOwnerDelegatedGrantAndIdExistenceMismatch',
+  RecordsOwnerDelegatedGrantCidMismatch = 'RecordsOwnerDelegatedGrantCidMismatch',
+  RecordsOwnerDelegatedGrantGrantedToAndOwnerSignatureMismatch = 'RecordsOwnerDelegatedGrantGrantedToAndOwnerSignatureMismatch',
+  RecordsOwnerDelegatedGrantNotADelegatedGrant = 'RecordsOwnerDelegatedGrantNotADelegatedGrant',
   RecordsProtocolContextDerivationSchemeMissingContextId = 'RecordsProtocolContextDerivationSchemeMissingContextId',
   RecordsProtocolPathDerivationSchemeMissingProtocol = 'RecordsProtocolPathDerivationSchemeMissingProtocol',
   RecordsQueryFilterMissingRequiredProperties = 'RecordsQueryFilterMissingRequiredProperties',
@@ -113,8 +121,6 @@ export enum DwnErrorCode {
   RecordsSubscribeEventStreamUnimplemented = 'RecordsSubscribeEventStreamUnimplemented',
   RecordsSubscribeFilterMissingRequiredProperties = 'RecordsSubscribeFilterMissingRequiredProperties',
   RecordsSchemasDerivationSchemeMissingSchema = 'RecordsSchemasDerivationSchemeMissingSchema',
-  RecordsValidateIntegrityDelegatedGrantAndIdExistenceMismatch = 'RecordsValidateIntegrityDelegatedGrantAndIdExistenceMismatch',
-  RecordsValidateIntegrityGrantedToAndSignerMismatch = 'RecordsValidateIntegrityGrantedToAndSignerMismatch',
   RecordsWriteAttestationIntegrityMoreThanOneSignature = 'RecordsWriteAttestationIntegrityMoreThanOneSignature',
   RecordsWriteAttestationIntegrityDescriptorCidMismatch = 'RecordsWriteAttestationIntegrityDescriptorCidMismatch',
   RecordsWriteAttestationIntegrityInvalidPayloadProperty = 'RecordsWriteAttestationIntegrityInvalidPayloadProperty',
@@ -135,6 +141,7 @@ export enum DwnErrorCode {
   RecordsWriteMissingProtocol = 'RecordsWriteMissingProtocol',
   RecordsWriteMissingSchema = 'RecordsWriteMissingSchema',
   RecordsWriteOwnerAndTenantMismatch = 'RecordsWriteOwnerAndTenantMismatch',
+  RecordsWriteSignAsOwnerDelegateUnknownAuthor = 'RecordsWriteSignAsOwnerDelegateUnknownAuthor',
   RecordsWriteSignAsOwnerUnknownAuthor = 'RecordsWriteSignAsOwnerUnknownAuthor',
   RecordsWriteValidateIntegrityAttestationMismatch = 'RecordsWriteValidateIntegrityAttestationMismatch',
   RecordsWriteValidateIntegrityContextIdMismatch = 'RecordsWriteValidateIntegrityContextIdMismatch',

src/core/message.ts

@@ -172,12 +172,19 @@ export class Message {
   }
 
   /**
-   * See if the given message is signed by a delegate
+   * See if the given message is signed by an author-delegate.
    */
-  public static isSignedByDelegate(message: GenericMessage): boolean {
+  public static isSignedByAuthorDelegate(message: GenericMessage): boolean {
     return message.authorization?.authorDelegatedGrant !== undefined;
   }
 
+  /**
+   * See if the given message is signed by an owner-delegate.
+   */
+  public static isSignedByOwnerDelegate(message: GenericMessage): boolean {
+    return message.authorization?.ownerDelegatedGrant !== undefined;
+  }
+
   /**
    * Compares the `messageTimestamp` of the given messages with a fallback to message CID according to the spec.
    * @returns 1 if `a` is larger/newer than `b`; -1 if `a` is smaller/older than `b`; 0 otherwise (same age)
@@ -194,7 +201,6 @@ export class Message {
     return Message.compareCid(a, b);
   }
 
-
   /**
    * Validates the structural integrity of the message signature given:
    * 1. The message signature must contain exactly 1 signature

src/handlers/records-delete.ts

@@ -118,7 +118,7 @@ export class RecordsDeleteHandler implements MethodHandler {
     messageStore: MessageStore
   ): Promise<void> {
 
-    if (Message.isSignedByDelegate(recordsDelete.message)) {
+    if (Message.isSignedByAuthorDelegate(recordsDelete.message)) {
       await recordsDelete.authorizeDelegate(recordsWriteToDelete.message, messageStore);
     }
 

src/handlers/records-query.ts

@@ -247,7 +247,7 @@ export class RecordsQueryHandler implements MethodHandler {
     messageStore: MessageStore
   ): Promise<void> {
 
-    if (Message.isSignedByDelegate(recordsQuery.message)) {
+    if (Message.isSignedByAuthorDelegate(recordsQuery.message)) {
       await recordsQuery.authorizeDelegate(messageStore);
     }
 

src/handlers/records-read.ts

@@ -117,7 +117,7 @@ export class RecordsReadHandler implements MethodHandler {
     matchedRecordsWrite: RecordsWrite,
     messageStore: MessageStore
   ): Promise<void> {
-    if (Message.isSignedByDelegate(recordsRead.message)) {
+    if (Message.isSignedByAuthorDelegate(recordsRead.message)) {
       await recordsRead.authorizeDelegate(matchedRecordsWrite.message, messageStore);
     }
 

src/handlers/records-subscribe.ts

@@ -203,7 +203,7 @@ export class RecordsSubscribeHandler implements MethodHandler {
     messageStore: MessageStore
   ): Promise<void> {
 
-    if (Message.isSignedByDelegate(recordsSubscribe.message)) {
+    if (Message.isSignedByAuthorDelegate(recordsSubscribe.message)) {
       await recordsSubscribe.authorizeDelegate(messageStore);
     }
 

src/handlers/records-write.ts

@@ -43,7 +43,7 @@ export class RecordsWriteHandler implements MethodHandler {
     try {
       recordsWrite = await RecordsWrite.parse(message);
 
-      // Protocol record specific validation
+      // Protocol-authorized record specific validation
       if (message.descriptor.protocol !== undefined) {
         await ProtocolAuthorization.validateReferentialIntegrity(tenant, recordsWrite, this.messageStore);
       }
@@ -280,16 +280,20 @@ export class RecordsWriteHandler implements MethodHandler {
   }
 
   private static async authorizeRecordsWrite(tenant: string, recordsWrite: RecordsWrite, messageStore: MessageStore): Promise<void> {
-    // if owner DID is specified, it must be the same as the tenant DID
+    // if owner signature is given (`owner` is not `undefined`), it must be the same as the tenant DID
     if (recordsWrite.owner !== undefined && recordsWrite.owner !== tenant) {
       throw new DwnError(
         DwnErrorCode.RecordsWriteOwnerAndTenantMismatch,
         `Owner ${recordsWrite.owner} must be the same as tenant ${tenant} when specified.`
       );
     }
 
-    if (recordsWrite.isSignedByDelegate) {
-      await recordsWrite.authorizeDelegate(messageStore);
+    if (recordsWrite.isSignedByAuthorDelegate) {
+      await recordsWrite.authorizeAuthorDelegate(messageStore);
+    }
+
+    if (recordsWrite.isSignedByOwnerDelegate) {
+      await recordsWrite.authorizeOwnerDelegate(messageStore);
     }
 
     if (recordsWrite.owner !== undefined) {

src/interfaces/permissions-grant.ts

@@ -14,6 +14,10 @@ import { normalizeProtocolUrl, normalizeSchemaUrl } from '../utils/url.js';
 
 export type PermissionsGrantOptions = {
   messageTimestamp?: string;
+
+  /**
+   * Expire time in UTC ISO-8601 format with microsecond precision.
+   */
   dateExpires: string;
   description?: string;
   grantedTo: string;

src/interfaces/records-delete.ts

@@ -32,7 +32,7 @@ export class RecordsDelete extends AbstractMessage<RecordsDeleteMessage> {
       signaturePayload = await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
     }
 
-    Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
+    await Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
 
     Time.validateTimestamp(message.descriptor.messageTimestamp);
 

src/interfaces/records-query.ts

@@ -50,7 +50,7 @@ export class RecordsQuery extends AbstractMessage<RecordsQueryMessage> {
       signaturePayload = await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
     }
 
-    Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
+    await Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
 
     if (signaturePayload?.protocolRole !== undefined) {
       if (message.descriptor.filter.protocolPath === undefined) {

src/interfaces/records-read.ts

@@ -36,7 +36,7 @@ export class RecordsRead extends AbstractMessage<RecordsReadMessage> {
       signaturePayload = await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
     }
 
-    Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
+    await Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
 
     Time.validateTimestamp(message.descriptor.messageTimestamp);
 

src/interfaces/records-subscribe.ts

@@ -36,7 +36,7 @@ export class RecordsSubscribe extends AbstractMessage<RecordsSubscribeMessage> {
       signaturePayload = await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
     }
 
-    Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
+    await Records.validateDelegatedGrantReferentialIntegrity(message, signaturePayload);
 
     if (signaturePayload?.protocolRole !== undefined) {
       if (message.descriptor.filter.protocolPath === undefined) {