@enbox/dwn-sdk-js 0.3.6 → 0.3.8

package/src/core/messages-grant-authorization.ts

@@ -3,11 +3,14 @@ import type { MessagesPermissionScope } from '../types/permission-types.js';
 import type { MessageStore } from '../types/message-store.js';
 import type { PermissionGrant } from '../protocols/permission-grant.js';
 import type { ProtocolsConfigureMessage } from '../types/protocols-types.js';
+import type { ProtocolScope } from '../utils/permission-scope.js';
 import type { DataEncodedRecordsWriteMessage, RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
 import type { MessagesReadMessage, MessagesSubscribeMessage, MessagesSyncMessage } from '../types/messages-types.js';
 
 import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
 import { GrantAuthorization } from './grant-authorization.js';
+import { isRecordsPrimaryProjectionExcludedProtocol } from './constants.js';
+import { PermissionScopeMatcher } from '../utils/permission-scope.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
 import { Records } from '../utils/records.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
@@ -15,6 +18,16 @@ import { DwnError, DwnErrorCode } from './dwn-error.js';
 
 export class MessagesGrantAuthorization {
 
+  public static async fetchPermissionGrants(
+    tenant: string,
+    messageStore: MessageStore,
+    permissionGrantIds: string[]
+  ): Promise<PermissionGrant[]> {
+    return Promise.all(
+      permissionGrantIds.map(permissionGrantId => PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId))
+    );
+  }
+
   /**
    * Authorizes a MessagesReadMessage using the given permission grant.
    * @param messageStore Used to check if the given grant has been revoked; and to fetch related RecordsWrites if needed.
@@ -24,23 +37,29 @@ export class MessagesGrantAuthorization {
     messageToRead: GenericMessage,
     expectedGrantor: string,
     expectedGrantee: string,
-    permissionGrant: PermissionGrant,
+    permissionGrants: PermissionGrant[],
     messageStore: MessageStore,
   }): Promise<void> {
     const {
-      messagesReadMessage, messageToRead, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+      messagesReadMessage, messageToRead, expectedGrantor, expectedGrantee, permissionGrants, messageStore
     } = input;
 
-    await GrantAuthorization.performBaseValidation({
+    await MessagesGrantAuthorization.performBaseValidationForGrantSet({
       incomingMessage: messagesReadMessage,
       expectedGrantor,
       expectedGrantee,
-      permissionGrant,
+      permissionGrants,
       messageStore
     });
 
-    const scope = permissionGrant.scope as MessagesPermissionScope;
-    await MessagesGrantAuthorization.verifyScope(expectedGrantor, messageToRead, scope, messageStore);
+    for (const permissionGrant of permissionGrants) {
+      const scope = permissionGrant.scope as MessagesPermissionScope;
+      if (await MessagesGrantAuthorization.isScopeAuthorized(expectedGrantor, messageToRead, scope, messageStore)) {
+        return;
+      }
+    }
+
+    throw new DwnError(DwnErrorCode.MessagesReadVerifyScopeFailed, 'record message failed scope authorization');
   }
 
   /**
@@ -51,98 +70,291 @@ export class MessagesGrantAuthorization {
     incomingMessage: MessagesSubscribeMessage | MessagesSyncMessage,
     expectedGrantor: string,
     expectedGrantee: string,
-    permissionGrant: PermissionGrant,
+    permissionGrants: PermissionGrant[],
     messageStore: MessageStore,
   }): Promise<void> {
     const {
-      incomingMessage, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+      incomingMessage, expectedGrantor, expectedGrantee, permissionGrants, messageStore
     } = input;
 
-    await GrantAuthorization.performBaseValidation({
+    await MessagesGrantAuthorization.performBaseValidationForGrantSet({
       incomingMessage,
       expectedGrantor,
       expectedGrantee,
-      permissionGrant,
+      permissionGrants,
       messageStore
     });
 
-    // if the grant is scoped to a specific protocol, ensure that the message targets that protocol
-    if (PermissionsProtocol.hasProtocolScope(permissionGrant.scope)) {
-      const scopedProtocol = permissionGrant.scope.protocol;
-
-      // MessagesSync uses a direct `protocol` field on the descriptor
-      if ('action' in incomingMessage.descriptor) {
-        const syncMessage = incomingMessage as MessagesSyncMessage;
-        if (syncMessage.descriptor.protocol !== scopedProtocol) {
-          throw new DwnError(
-            DwnErrorCode.MessagesGrantAuthorizationMismatchedProtocol,
-            `The protocol ${syncMessage.descriptor.protocol} does not match the scoped protocol ${scopedProtocol}`
-          );
-        }
-      } else {
-        // MessagesSubscribe uses filters
-        const filteredMessage = incomingMessage as MessagesSubscribeMessage;
-        for (const filter of filteredMessage.descriptor.filters) {
-          if (filter.protocol !== scopedProtocol) {
-            throw new DwnError(
-              DwnErrorCode.MessagesGrantAuthorizationMismatchedProtocol,
-              `The protocol ${filter.protocol} does not match the scoped protocol ${scopedProtocol}`
-            );
-          }
-        }
+    const scopes = permissionGrants.map(permissionGrant => permissionGrant.scope as MessagesPermissionScope);
+
+    if ('action' in incomingMessage.descriptor) {
+      MessagesGrantAuthorization.authorizeSyncScope(incomingMessage as MessagesSyncMessage, scopes);
+      return;
+    }
+
+    MessagesGrantAuthorization.authorizeSubscribeScope(incomingMessage as MessagesSubscribeMessage, scopes);
+  }
+
+  private static authorizeSyncScope(
+    syncMessage: MessagesSyncMessage,
+    scopes: MessagesPermissionScope[]
+  ): void {
+    const { projectionScopes, protocol } = syncMessage.descriptor;
+
+    if (projectionScopes === undefined) {
+      MessagesGrantAuthorization.authorizeProtocolSyncScope(scopes, protocol);
+      return;
+    }
+
+    MessagesGrantAuthorization.authorizeProjectionScopes(scopes, projectionScopes);
+  }
+
+  private static authorizeProtocolSyncScope(
+    scopes: MessagesPermissionScope[],
+    protocol: string | undefined
+  ): void {
+    if (isRecordsPrimaryProjectionExcludedProtocol(protocol)) {
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationProtocolSyncInfrastructureProtocol,
+        `Protocol-scoped MessagesSync cannot authorize infrastructure protocol ${protocol}`
+      );
+    }
+
+    if (!MessagesGrantAuthorization.someScopeMatches(scopes, { protocol })) {
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationMismatchedProtocol,
+        `No permission grant scope matches protocol ${protocol}`
+      );
+    }
+  }
+
+  private static authorizeProjectionScopes(
+    scopes: MessagesPermissionScope[],
+    projectionScopes: ProtocolScope[],
+  ): void {
+    for (const projectionScope of projectionScopes) {
+      if (isRecordsPrimaryProjectionExcludedProtocol(projectionScope.protocol)) {
+        throw new DwnError(
+          DwnErrorCode.MessagesGrantAuthorizationProjectionInfrastructureProtocol,
+          `Projected MessagesSync cannot authorize infrastructure protocol ${projectionScope.protocol}`
+        );
+      }
+
+      if (MessagesGrantAuthorization.someScopeMatches(scopes, projectionScope)) {
+        continue;
+      }
+
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationProjectionScopeMismatch,
+        `No permission grant scope matches projection scope ${JSON.stringify(projectionScope)}`
+      );
+    }
+  }
+
+  private static authorizeSubscribeScope(
+    subscribeMessage: MessagesSubscribeMessage,
+    scopes: MessagesPermissionScope[]
+  ): void {
+    const { filters } = subscribeMessage.descriptor;
+
+    if (filters.length === 0 && !MessagesGrantAuthorization.hasUnscopedGrant(scopes)) {
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationUnfilteredSubscribeProtocolScope,
+        `A protocol-scoped grant cannot authorize an unfiltered subscription`
+      );
+    }
+
+    for (const filter of filters) {
+      if (MessagesGrantAuthorization.someScopeMatches(scopes, { protocol: filter.protocol })) {
+        continue;
       }
+
+      throw new DwnError(
+        DwnErrorCode.MessagesGrantAuthorizationSubscribeProtocolMismatch,
+        `No permission grant scope matches protocol ${filter.protocol}`
+      );
     }
   }
 
+  private static someScopeMatches(scopes: MessagesPermissionScope[], target: ProtocolScope): boolean {
+    return scopes.some(scope => PermissionScopeMatcher.matches(scope, target));
+  }
+
+  private static hasUnscopedGrant(scopes: MessagesPermissionScope[]): boolean {
+    return scopes.some(scope => scope.protocol === undefined);
+  }
+
   /**
-   * Verifies the given record against the scope of the given grant.
+   * Revalidates an already-open delegated MessagesSubscribe grant set at event
+   * delivery time. Subscription messages are signed at open time, but grant
+   * expiry and revocation must stop future delivery after the grant set becomes
+   * invalid.
    */
-  private static async verifyScope(
+  public static async authorizeSubscribeDelivery(input: {
+    messagesSubscribeMessage: MessagesSubscribeMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrants: PermissionGrant[],
+    messageStore: MessageStore,
+    deliveryTimestamp: string,
+  }): Promise<void> {
+    const {
+      messagesSubscribeMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrants,
+      messageStore,
+      deliveryTimestamp,
+    } = input;
+
+    const deliveryMessage: MessagesSubscribeMessage = {
+      ...messagesSubscribeMessage,
+      descriptor: {
+        ...messagesSubscribeMessage.descriptor,
+        messageTimestamp: deliveryTimestamp,
+      },
+    };
+
+    await MessagesGrantAuthorization.authorizeSubscribeOrSync({
+      incomingMessage: deliveryMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrants,
+      messageStore,
+    });
+  }
+
+  /**
+   * Performs base validation on every invoked grant. The grant set is all-or-nothing:
+   * unresolved, revoked, expired, or interface/method-mismatched grants fail the request.
+   */
+  private static async performBaseValidationForGrantSet(input: {
+    incomingMessage: MessagesReadMessage | MessagesSubscribeMessage | MessagesSyncMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrants: PermissionGrant[],
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      incomingMessage, expectedGrantor, expectedGrantee, permissionGrants, messageStore
+    } = input;
+
+    for (const permissionGrant of permissionGrants) {
+      await GrantAuthorization.performBaseValidation({
+        incomingMessage,
+        expectedGrantor,
+        expectedGrantee,
+        permissionGrant,
+        messageStore
+      });
+    }
+  }
+
+  /**
+   * Determines whether the given record is inside a grant scope.
+   */
+  private static async isScopeAuthorized(
     tenant: string,
     messageToGet: GenericMessage,
     incomingScope: MessagesPermissionScope,
     messageStore: MessageStore,
-  ): Promise<void> {
+  ): Promise<boolean> {
     if (incomingScope.protocol === undefined) {
-      // if no protocol is specified in the scope, then the grant is for all records
-      return;
+      return true;
     }
 
     if (messageToGet.descriptor.interface === DwnInterfaceName.Records) {
-      // if the message is a Records interface message, get the RecordsWrite message associated with the record
-      const recordsMessage = messageToGet as RecordsWriteMessage | RecordsDeleteMessage;
-      const recordsWriteMessage = Records.isRecordsWrite(recordsMessage) ? recordsMessage :
-        await RecordsWrite.fetchNewestRecordsWrite(messageStore, tenant, recordsMessage.descriptor.recordId);
+      return MessagesGrantAuthorization.isRecordsMessageScopeAuthorized(
+        tenant,
+        messageToGet as RecordsWriteMessage | RecordsDeleteMessage,
+        incomingScope,
+        messageStore
+      );
+    }
 
-      if (recordsWriteMessage.descriptor.protocol === incomingScope.protocol) {
-        // the record protocol matches the incoming scope protocol
-        return;
-      }
+    if (messageToGet.descriptor.interface === DwnInterfaceName.Protocols) {
+      return MessagesGrantAuthorization.isProtocolsConfigureScopeAuthorized(
+        messageToGet as ProtocolsConfigureMessage,
+        incomingScope
+      );
+    }
 
-      // we check if the protocol is the internal PermissionsProtocol for further validation
-      if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri) {
-        // get the permission scope from the permission message
-        const permissionScope = await PermissionsProtocol.getScopeFromPermissionRecord(
-          tenant,
-          messageStore,
-          recordsWriteMessage as DataEncodedRecordsWriteMessage
-        );
+    return false;
+  }
 
-        if (PermissionsProtocol.hasProtocolScope(permissionScope) && permissionScope.protocol === incomingScope.protocol) {
-          // the permissions record scoped protocol matches the incoming scope protocol
-          return;
-        }
-      }
-    } else if (messageToGet.descriptor.interface === DwnInterfaceName.Protocols) {
-      // if the message is a protocol message, it must be a `ProtocolConfigure` message
-      const protocolsConfigureMessage = messageToGet as ProtocolsConfigureMessage;
-      const configureProtocol = protocolsConfigureMessage.descriptor.definition.protocol;
-      if (configureProtocol === incomingScope.protocol) {
-        // the configured protocol matches the incoming scope protocol
-        return;
-      }
+  private static async isRecordsMessageScopeAuthorized(
+    tenant: string,
+    recordsMessage: RecordsWriteMessage | RecordsDeleteMessage,
+    incomingScope: MessagesPermissionScope,
+    messageStore: MessageStore,
+  ): Promise<boolean> {
+    const recordsWriteMessage = await MessagesGrantAuthorization.getAssociatedRecordsWrite(
+      tenant,
+      recordsMessage,
+      messageStore
+    );
+
+    if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri) {
+      return MessagesGrantAuthorization.isPermissionRecordScopeAuthorized(
+        tenant,
+        recordsWriteMessage,
+        incomingScope,
+        messageStore
+      );
     }
 
-    throw new DwnError(DwnErrorCode.MessagesReadVerifyScopeFailed, 'record message failed scope authorization');
+    return PermissionScopeMatcher.matches(incomingScope, MessagesGrantAuthorization.getRecordsScopeTarget(recordsWriteMessage));
+  }
+
+  private static async isPermissionRecordScopeAuthorized(
+    tenant: string,
+    recordsWriteMessage: RecordsWriteMessage,
+    incomingScope: MessagesPermissionScope,
+    messageStore: MessageStore,
+  ): Promise<boolean> {
+    if (MessagesGrantAuthorization.isSubtreeScope(incomingScope)) {
+      return false;
+    }
+
+    const permissionScope = await PermissionsProtocol.getScopeFromPermissionRecord(
+      tenant,
+      messageStore,
+      recordsWriteMessage as DataEncodedRecordsWriteMessage
+    );
+
+    return PermissionsProtocol.hasProtocolScope(permissionScope)
+      && PermissionScopeMatcher.matches(incomingScope, permissionScope);
+  }
+
+  private static isProtocolsConfigureScopeAuthorized(
+    protocolsConfigureMessage: ProtocolsConfigureMessage,
+    incomingScope: MessagesPermissionScope
+  ): boolean {
+    // A delegate with any Messages.Read grant inside a protocol needs that
+    // protocol definition to interpret and validate the records it can read.
+    return incomingScope.protocol !== undefined &&
+      incomingScope.protocol === protocolsConfigureMessage.descriptor.definition.protocol;
+  }
+
+  private static async getAssociatedRecordsWrite(
+    tenant: string,
+    recordsMessage: RecordsWriteMessage | RecordsDeleteMessage,
+    messageStore: MessageStore,
+  ): Promise<RecordsWriteMessage> {
+    if (Records.isRecordsWrite(recordsMessage)) {
+      return recordsMessage;
+    }
+
+    return RecordsWrite.fetchNewestRecordsWrite(messageStore, tenant, recordsMessage.descriptor.recordId);
+  }
+
+  private static getRecordsScopeTarget(recordsWriteMessage: RecordsWriteMessage): ProtocolScope {
+    const { protocol, protocolPath } = recordsWriteMessage.descriptor;
+    const { contextId } = recordsWriteMessage;
+    return { protocol, protocolPath, contextId };
+  }
+
+  private static isSubtreeScope(scope: MessagesPermissionScope): boolean {
+    return scope.protocolPath !== undefined || scope.contextId !== undefined;
   }
-}
+}

package/src/core/protocol-authorization.ts

@@ -14,6 +14,7 @@ import { getRuleSetAtPath } from '../utils/protocols.js';
 import { SortDirection } from '../types/query-types.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
 
 import { authorizeAgainstAllowedActions, verifyInvokedRole } from './protocol-authorization-action.js';
 import { constructRecordChain, fetchInitialWrite, getGoverningTimestamp } from './record-chain.js';
@@ -113,6 +114,52 @@ export class ProtocolAuthorization {
     await verifyRecordLimit(tenant, incomingMessage, ruleSet, messageStore);
   }
 
+  /**
+   * Revalidates a stored initial write against the protocol definition that governed its creation timestamp.
+   *
+   * This is used only for destructive config-history repair, so it deliberately validates config-owned
+   * structure and avoids live dependency checks. Missing grant, role, or parent records must not cause
+   * an already-admitted record to be hard-purged.
+   */
+  public static async validateStoredInitialWrite(
+    tenant: string,
+    incomingMessage: RecordsWrite,
+    messageStore: MessageStore,
+    coreProtocols?: CoreProtocolRegistry,
+  ): Promise<void> {
+    await ProtocolAuthorization.verifyStoredInitialWrite(incomingMessage);
+
+    const governingTimestamp = incomingMessage.message.descriptor.messageTimestamp;
+    const protocolDefinition = await ProtocolAuthorization.fetchProtocolDefinition(
+      tenant,
+      incomingMessage.message.descriptor.protocol,
+      messageStore,
+      governingTimestamp,
+      coreProtocols,
+    );
+
+    const boundFetchDefinition = ProtocolAuthorization.createBoundFetchDefinition(coreProtocols);
+
+    await verifyTypeWithComposition(
+      tenant, incomingMessage.message, protocolDefinition, messageStore, boundFetchDefinition, governingTimestamp
+    );
+
+    const ruleSet = ProtocolAuthorization.getRuleSet(
+      incomingMessage.message.descriptor.protocolPath,
+      protocolDefinition,
+    );
+
+    ProtocolAuthorization.verifyStoredInitialWriteRoleRecipientIfNeeded(incomingMessage, ruleSet);
+    verifySizeLimit(incomingMessage, ruleSet);
+    verifyTagsIfNeeded(incomingMessage, ruleSet);
+    await verifySquashEligibility(incomingMessage, ruleSet);
+    ProtocolAuthorization.verifyStoredInitialWriteCreateAction(tenant, incomingMessage, ruleSet);
+
+    // `verifyRecordLimit()` is not replayed here. It is stateful and counts the present
+    // latest live set, which would incorrectly reject the record being revalidated.
+    // Inbound writes continue to enforce record limits at admission time.
+  }
+
   /**
    * Performs protocol-based authorization against the incoming RecordsWrite message.
    * @throws {Error} if authorization fails.
@@ -444,4 +491,87 @@ export class ProtocolAuthorization {
     return ruleSet;
   }
 
+  private static async verifyStoredInitialWrite(incomingMessage: RecordsWrite): Promise<void> {
+    if (await incomingMessage.isInitialWrite()) {
+      return;
+    }
+
+    throw new DwnError(
+      DwnErrorCode.ProtocolAuthorizationInitialWriteRevalidationNotInitial,
+      'stored write revalidation only supports initial RecordsWrite messages'
+    );
+  }
+
+  private static verifyStoredInitialWriteRoleRecipientIfNeeded(
+    incomingMessage: RecordsWrite,
+    ruleSet: ProtocolRuleSet,
+  ): void {
+    if (ruleSet.$role !== true || incomingMessage.message.descriptor.recipient !== undefined) {
+      return;
+    }
+
+    throw new DwnError(
+      DwnErrorCode.ProtocolAuthorizationStoredInitialWriteRoleMissingRecipient,
+      'role records must have a recipient'
+    );
+  }
+
+  private static verifyStoredInitialWriteCreateAction(
+    tenant: string,
+    incomingMessage: RecordsWrite,
+    ruleSet: ProtocolRuleSet,
+  ): void {
+    if (ProtocolAuthorization.isStoredInitialWriteDirectlyAuthorized(tenant, incomingMessage)) {
+      return;
+    }
+
+    const actions = incomingMessage.message.descriptor.squash === true
+      ? [ProtocolAction.Squash, ProtocolAction.Create]
+      : [ProtocolAction.Create];
+    const actionRules = ruleSet.$actions;
+    if (actionRules === undefined) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolAuthorizationStoredInitialWriteActionRulesNotFound,
+        `no create action rule defined for stored RecordsWrite by author ${incomingMessage.author}`
+      );
+    }
+
+    const invokedRole = incomingMessage.signaturePayload?.protocolRole;
+    for (const actionRule of actionRules) {
+      if (!actionRule.can.some((allowedAction: string): boolean => actions.includes(allowedAction as ProtocolAction))) {
+        continue;
+      }
+
+      if (invokedRole !== undefined) {
+        if (actionRule.role === invokedRole) {
+          return;
+        }
+        continue;
+      }
+
+      if (actionRule.who === ProtocolActor.Anyone) {
+        return;
+      }
+
+      // Author/recipient-of rules depend on the parent chain. This repair path preserves
+      // instead of hard-purging when validity depends on mutable or missing dependency records.
+      if (actionRule.who === ProtocolActor.Author || actionRule.who === ProtocolActor.Recipient) {
+        return;
+      }
+    }
+
+    throw new DwnError(
+      DwnErrorCode.ProtocolAuthorizationStoredInitialWriteActionNotAllowed,
+      `stored RecordsWrite by author ${incomingMessage.author} is not allowed by the governing protocol config`
+    );
+  }
+
+  private static isStoredInitialWriteDirectlyAuthorized(tenant: string, incomingMessage: RecordsWrite): boolean {
+    return incomingMessage.owner !== undefined ||
+      incomingMessage.author === tenant ||
+      incomingMessage.isSignedByAuthorDelegate ||
+      incomingMessage.isSignedByOwnerDelegate ||
+      incomingMessage.signaturePayload?.permissionGrantId !== undefined;
+  }
+
 }