@enbox/dwn-sdk-js 0.3.7 → 0.3.8

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;
+  }
+
 }

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

@@ -1,10 +1,12 @@
 import type { MessageStore } from '../types/message-store.js';
 import type { PermissionGrant } from '../protocols/permission-grant.js';
+import type { ProtocolScope } from '../utils/permission-scope.js';
 import type { PermissionConditions, RecordsPermissionScope } from '../types/permission-types.js';
 import type { RecordsCountMessage, RecordsDeleteMessage, RecordsQueryMessage, RecordsReadMessage, RecordsSubscribeMessage, RecordsWriteMessage } from '../types/records-types.js';
 
 import { GrantAuthorization } from './grant-authorization.js';
 import { PermissionConditionPublication } from '../types/permission-types.js';
+import { PermissionScopeMatcher } from '../utils/permission-scope.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 
 export class RecordsGrantAuthorization {
@@ -90,11 +92,15 @@ export class RecordsGrantAuthorization {
     // The grant's protocol must match the query/subscribe filter's protocol.
     // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
     const permissionScope = permissionGrant.scope as RecordsPermissionScope;
-    const protocolInMessage = incomingMessage.descriptor.filter.protocol;
-    if (protocolInMessage !== permissionScope.protocol) {
+    const messageFilter = incomingMessage.descriptor.filter;
+    if (!PermissionScopeMatcher.matches(permissionScope, {
+      protocol     : messageFilter.protocol,
+      protocolPath : messageFilter.protocolPath,
+      contextId    : messageFilter.contextId,
+    })) {
       throw new DwnError(
         DwnErrorCode.RecordsGrantAuthorizationQueryOrSubscribeProtocolScopeMismatch,
-        `Grant protocol scope ${permissionScope.protocol} does not match protocol in message ${protocolInMessage}`
+        `Grant scope does not match Records ${incomingMessage.descriptor.method} filter`
       );
     }
   }
@@ -123,16 +129,8 @@ export class RecordsGrantAuthorization {
       messageStore
     });
 
-    // The grant's protocol must match the protocol of the record being deleted.
     // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
-    const permissionScope = permissionGrant.scope as RecordsPermissionScope;
-    const protocolOfRecordToDelete = recordsWriteToDelete.descriptor.protocol;
-    if (protocolOfRecordToDelete !== permissionScope.protocol) {
-      throw new DwnError(
-        DwnErrorCode.RecordsGrantAuthorizationDeleteProtocolScopeMismatch,
-        `Grant protocol scope ${permissionScope.protocol} does not match protocol in record to delete ${protocolOfRecordToDelete}`
-      );
-    }
+    RecordsGrantAuthorization.verifyDeleteScope(recordsWriteToDelete, permissionGrant.scope as RecordsPermissionScope);
   }
 
   /**
@@ -142,32 +140,77 @@ export class RecordsGrantAuthorization {
     recordsWriteMessage: RecordsWriteMessage,
     grantScope: RecordsPermissionScope
   ): void {
+    const target = RecordsGrantAuthorization.getProtocolScopeTarget(recordsWriteMessage);
+
+    if (PermissionScopeMatcher.matches(grantScope, target)) {
+      return;
+    }
 
-    // The record's protocol must match the protocol specified in the record
-    if (grantScope.protocol !== recordsWriteMessage.descriptor.protocol) {
+    if (grantScope.protocol !== target.protocol) {
       throw new DwnError(
         DwnErrorCode.RecordsGrantAuthorizationScopeProtocolMismatch,
         `Grant scope specifies different protocol than what appears in the record`
       );
     }
 
+    RecordsGrantAuthorization.throwScopeMismatchAfterProtocolMatch(grantScope, target);
+  }
+
+  /**
+   * Verifies RecordsDelete scope while preserving the delete-specific protocol mismatch code.
+   */
+  private static verifyDeleteScope(
+    recordsWriteMessage: RecordsWriteMessage,
+    grantScope: RecordsPermissionScope
+  ): void {
+    const target = RecordsGrantAuthorization.getProtocolScopeTarget(recordsWriteMessage);
+
+    if (PermissionScopeMatcher.matches(grantScope, target)) {
+      return;
+    }
+
+    if (grantScope.protocol !== target.protocol) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationDeleteProtocolScopeMismatch,
+        `Grant protocol scope ${grantScope.protocol} does not match protocol in record to delete ${target.protocol}`
+      );
+    }
+
+    RecordsGrantAuthorization.throwScopeMismatchAfterProtocolMatch(grantScope, target);
+  }
+
+  private static getProtocolScopeTarget(recordsWriteMessage: RecordsWriteMessage): ProtocolScope {
+    return {
+      protocol     : recordsWriteMessage.descriptor.protocol,
+      protocolPath : recordsWriteMessage.descriptor.protocolPath,
+      contextId    : recordsWriteMessage.contextId,
+    };
+  }
+
+  private static throwScopeMismatchAfterProtocolMatch(
+    grantScope: RecordsPermissionScope,
+    target: ProtocolScope
+  ): never {
     // If grant specifies a contextId, check that record falls under that contextId
     if (grantScope.contextId !== undefined) {
-      if (!recordsWriteMessage.contextId?.startsWith(grantScope.contextId)) {
-        throw new DwnError(
-          DwnErrorCode.RecordsGrantAuthorizationScopeContextIdMismatch,
-          `Grant scope specifies different contextId than what appears in the record`
-        );
-      }
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationScopeContextIdMismatch,
+        `Grant scope specifies different contextId than what appears in the record`
+      );
     }
 
     // If grant specifies protocolPath, check that record is at that protocolPath
-    if (grantScope.protocolPath !== undefined && grantScope.protocolPath !== recordsWriteMessage.descriptor.protocolPath) {
+    if (grantScope.protocolPath !== undefined && grantScope.protocolPath !== target.protocolPath) {
       throw new DwnError(
         DwnErrorCode.RecordsGrantAuthorizationScopeProtocolPathMismatch,
         `Grant scope specifies different protocolPath than what appears in the record`
       );
     }
+
+    throw new DwnError(
+      DwnErrorCode.RecordsGrantAuthorizationScopeMismatch,
+      `Grant scope does not match the record`
+    );
   }
 
   /**

package/src/handlers/messages-read.ts

@@ -7,10 +7,10 @@ import type { MessagesReadMessage, MessagesReadReply, MessagesReadReplyEntry } f
 import { authenticate } from '../core/auth.js';
 import { DataStream } from '../utils/data-stream.js';
 import { Encoder } from '../utils/encoder.js';
+import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
 import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
 import { MessagesRead } from '../interfaces/messages-read.js';
-import { PermissionsProtocol } from '../protocols/permissions.js';
 import { Records } from '../utils/records.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
@@ -84,15 +84,17 @@ export class MessagesReadHandler implements MethodHandler {
     if (messagesRead.author === tenant) {
       // If the author is the tenant, no further authorization is needed
       return;
-    } else if (messagesRead.author !== undefined && messagesRead.signaturePayload!.permissionGrantId !== undefined) {
-      // if the author is not the tenant and the message has a permissionGrantId, we need to authorize the grant
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, messagesRead.signaturePayload!.permissionGrantId);
+    }
+
+    const permissionGrantIds = Message.getPermissionGrantIds(messagesRead.signaturePayload!);
+    if (messagesRead.author !== undefined && permissionGrantIds.length > 0) {
+      const permissionGrants = await MessagesGrantAuthorization.fetchPermissionGrants(tenant, messageStore, permissionGrantIds);
       await MessagesGrantAuthorization.authorizeMessagesRead({
         messagesReadMessage : messagesRead.message,
         messageToRead       : matchedMessage,
         expectedGrantor     : tenant,
         expectedGrantee     : messagesRead.author,
-        permissionGrant,
+        permissionGrants,
         messageStore
       });
     } else {

package/src/handlers/messages-subscribe.ts

@@ -1,7 +1,8 @@
 import type { MessageStore } from '../types/message-store.js';
+import type { PermissionGrant } from '../protocols/permission-grant.js';
+import type { EventSubscription, ProgressGapInfo, SubscriptionEvent, SubscriptionListener, SubscriptionMessage } from '../types/subscriptions.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { MessagesSubscribeMessage, MessagesSubscribeReply } from '../types/messages-types.js';
-import type { ProgressGapInfo, SubscriptionListener } from '../types/subscriptions.js';
 
 import { authenticate } from '../core/auth.js';
 import { Message } from '../core/message.js';
@@ -9,9 +10,23 @@ import { messageReplyFromError } from '../core/message-reply.js';
 import { Messages } from '../utils/messages.js';
 import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
 import { MessagesSubscribe } from '../interfaces/messages-subscribe.js';
-import { PermissionsProtocol } from '../protocols/permissions.js';
+import { Time } from '../utils/time.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
+type MessagesSubscribeAuthorization =
+  | { kind: 'owner' }
+  | {
+    kind: 'delegate';
+    expectedGrantor: string;
+    expectedGrantee: string;
+    permissionGrants: PermissionGrant[];
+  };
+
+type GuardedSubscriptionHandler = {
+  listener: SubscriptionListener;
+  setSubscription(subscription: EventSubscription): Promise<void>;
+};
+
 export class MessagesSubscribeHandler implements MethodHandler {
 
   constructor(private readonly deps: HandlerDependencies) {}
@@ -39,22 +54,31 @@ export class MessagesSubscribeHandler implements MethodHandler {
       return messageReplyFromError(e, 400);
     }
 
+    let authorization: MessagesSubscribeAuthorization;
     try {
       await authenticate(message.authorization, this.deps.didResolver);
-      await MessagesSubscribeHandler.authorizeMessagesSubscribe(tenant, messagesSubscribe, this.deps.messageStore);
+      authorization = await MessagesSubscribeHandler.authorizeMessagesSubscribe(tenant, messagesSubscribe, this.deps.messageStore);
     } catch (error) {
       return messageReplyFromError(error, 401);
     }
 
+    const guardedHandler = MessagesSubscribeHandler.createAuthorizationGuard({
+      authorization,
+      messagesSubscribe,
+      messageStore: this.deps.messageStore,
+      subscriptionHandler,
+    });
+
     const { filters, cursor: eventLogCursor } = message.descriptor;
     const messagesFilters = Messages.convertFilters(filters, this.deps.coreProtocols);
     const messageCid = await Message.getCid(message);
 
     try {
-      const subscription = await this.deps.eventLog.subscribe(tenant, messageCid, subscriptionHandler, {
+      const subscription = await this.deps.eventLog.subscribe(tenant, messageCid, guardedHandler.listener, {
         cursor  : eventLogCursor,
         filters : messagesFilters,
       });
+      await guardedHandler.setSubscription(subscription);
 
       return {
         status: { code: 200, detail: 'OK' },
@@ -72,21 +96,137 @@ export class MessagesSubscribeHandler implements MethodHandler {
     }
   }
 
-  private static async authorizeMessagesSubscribe(tenant: string, messagesSubscribe: MessagesSubscribe, messageStore: MessageStore): Promise<void> {
+  private static async authorizeMessagesSubscribe(
+    tenant: string,
+    messagesSubscribe: MessagesSubscribe,
+    messageStore: MessageStore
+  ): Promise<MessagesSubscribeAuthorization> {
     // if `MessagesSubscribe` author is the same as the target tenant, we can directly grant access
     if (messagesSubscribe.author === tenant) {
-      return;
-    } else if (messagesSubscribe.author !== undefined && messagesSubscribe.signaturePayload!.permissionGrantId !== undefined) {
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, messagesSubscribe.signaturePayload!.permissionGrantId);
+      return { kind: 'owner' };
+    }
+
+    const permissionGrantIds = Message.getPermissionGrantIds(messagesSubscribe.signaturePayload!);
+    if (messagesSubscribe.author !== undefined && permissionGrantIds.length > 0) {
+      const permissionGrants = await MessagesGrantAuthorization.fetchPermissionGrants(tenant, messageStore, permissionGrantIds);
       await MessagesGrantAuthorization.authorizeSubscribeOrSync({
         incomingMessage : messagesSubscribe.message,
         expectedGrantor : tenant,
         expectedGrantee : messagesSubscribe.author,
-        permissionGrant,
+        permissionGrants,
         messageStore
       });
+      return {
+        kind            : 'delegate',
+        expectedGrantor : tenant,
+        expectedGrantee : messagesSubscribe.author,
+        permissionGrants,
+      };
     } else {
       throw new DwnError(DwnErrorCode.MessagesSubscribeAuthorizationFailed, 'message failed authorization');
     }
   }
+
+  private static createAuthorizationGuard(input: {
+    authorization: MessagesSubscribeAuthorization;
+    messagesSubscribe: MessagesSubscribe;
+    messageStore: MessageStore;
+    subscriptionHandler: SubscriptionListener;
+  }): GuardedSubscriptionHandler {
+    const { authorization, messagesSubscribe, messageStore, subscriptionHandler } = input;
+    if (authorization.kind === 'owner') {
+      return {
+        listener        : subscriptionHandler,
+        setSubscription : async (): Promise<void> => {},
+      };
+    }
+
+    let subscription: EventSubscription | undefined;
+    let closeRequested = false;
+    let terminalErrorEmitted = false;
+    let deliveryQueue: Promise<void> = Promise.resolve();
+
+    const closeSubscription = (): void => {
+      if (closeRequested) {
+        return;
+      }
+      closeRequested = true;
+      Promise.resolve(subscription?.close()).catch(() => {});
+    };
+
+    const emitTerminalAuthorizationError = (cursor: SubscriptionEvent['cursor']): void => {
+      if (terminalErrorEmitted) {
+        return;
+      }
+      terminalErrorEmitted = true;
+      subscriptionHandler({
+        type  : 'error',
+        cursor,
+        error : {
+          code   : DwnErrorCode.MessagesSubscribeDeliveryAuthorizationFailed,
+          detail : 'subscription authorization failed during delivery',
+        },
+      });
+    };
+
+    // Deliberately do not cache delivery authorization here. Subscribe-open
+    // authorization validates static grant shape and filter scope; this per-event
+    // check revalidates dynamic grant state so expiry or revocation stops delivery
+    // before the next event is forwarded. Future throughput optimizations should
+    // split static and dynamic checks explicitly and document any bounded staleness
+    // introduced by caching revocation lookups.
+    const authorizeAndDeliverEvent = async (subMessage: SubscriptionEvent): Promise<void> => {
+      try {
+        await MessagesGrantAuthorization.authorizeSubscribeDelivery({
+          messagesSubscribeMessage : messagesSubscribe.message,
+          expectedGrantor          : authorization.expectedGrantor,
+          expectedGrantee          : authorization.expectedGrantee,
+          permissionGrants         : authorization.permissionGrants,
+          messageStore,
+          deliveryTimestamp        : Time.getCurrentTimestamp(),
+        });
+      } catch {
+        emitTerminalAuthorizationError(subMessage.cursor);
+        closeSubscription();
+        return;
+      }
+
+      if (!closeRequested) {
+        subscriptionHandler(subMessage);
+      }
+    };
+
+    const deliverQueuedMessage = async (subMessage: SubscriptionMessage): Promise<void> => {
+      if (closeRequested) {
+        return;
+      }
+
+      if (subMessage.type !== 'event') {
+        subscriptionHandler(subMessage);
+        return;
+      }
+
+      await authorizeAndDeliverEvent(subMessage);
+    };
+
+    const enqueueDelivery = (subMessage: SubscriptionMessage): void => {
+      deliveryQueue = deliveryQueue
+        .then(() => deliverQueuedMessage(subMessage))
+        .catch(() => {});
+    };
+
+    const listener: SubscriptionListener = (subMessage: SubscriptionMessage): void => {
+      enqueueDelivery(subMessage);
+    };
+
+    return {
+      listener,
+      setSubscription: async (eventSubscription: EventSubscription): Promise<void> => {
+        subscription = eventSubscription;
+        if (closeRequested) {
+          await eventSubscription.close();
+        }
+      },
+    };
+  }
 }