@enbox/dwn-sdk-js 0.4.12 → 0.4.13

package/src/core/protocol-authorization-action.ts

@@ -13,6 +13,11 @@ import { DwnError, DwnErrorCode } from './dwn-error.js';
 import { getRoleContextPrefix, getRuleSetAtPath, isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.js';
 import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
 
+/**
+ * A DWN message subject to protocol action-rule authorization checks.
+ */
+type ProtocolAuthorizableMessage = RecordsCount | RecordsDelete | RecordsQuery | RecordsRead | RecordsSubscribe | RecordsWrite;
+
 /**
  * Check if the incoming message is invoking a role. If so, validate the invoked role.
  * For cross-protocol role invocation, the role record may live in a different protocol
@@ -20,7 +25,7 @@ import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
  */
 export async function verifyInvokedRole(
   tenant: string,
-  incomingMessage: RecordsCount | RecordsDelete | RecordsQuery | RecordsRead | RecordsSubscribe | RecordsWrite,
+  incomingMessage: ProtocolAuthorizableMessage,
   protocolUri: string,
   contextId: string | undefined,
   protocolDefinition: ProtocolDefinition,
@@ -122,38 +127,8 @@ export async function getActionsSeekingARuleMatch(
 ): Promise<ProtocolAction[]> {
 
   switch (incomingMessage.message.descriptor.method) {
-  case DwnMethodName.Delete: {
-    const recordsDelete = incomingMessage as RecordsDelete;
-    const recordId = recordsDelete.message.descriptor.recordId;
-    const initialWrite = await validationStateReader.fetchInitialRecordsWrite(tenant, recordId);
-
-    // if there is no initial write, then no action rule can authorize the incoming message, because we won't know who the original author is
-    // NOTE: purely defensive programming: currently not reachable
-    // because RecordsDelete handler already have an existence check prior to this method being called.
-    if (initialWrite === undefined) {
-      return [];
-    }
-
-    const actionsThatWouldAuthorizeDelete: ProtocolAction[] = [];
-    const prune = recordsDelete.message.descriptor.prune;
-    if (prune) {
-      actionsThatWouldAuthorizeDelete.push(ProtocolAction.CoPrune);
-
-      // A prune by the original record author can also be authorized by a 'prune' rule.
-      if (incomingMessage.author === initialWrite.author) {
-        actionsThatWouldAuthorizeDelete.push(ProtocolAction.Prune);
-      }
-    } else {
-      actionsThatWouldAuthorizeDelete.push(ProtocolAction.CoDelete);
-
-      // A delete by the original record author can also be authorized by a 'delete' rule.
-      if (incomingMessage.author === initialWrite.author) {
-        actionsThatWouldAuthorizeDelete.push(ProtocolAction.Delete);
-      }
-    }
-
-    return actionsThatWouldAuthorizeDelete;
-  }
+  case DwnMethodName.Delete:
+    return getDeleteActionsSeekingARuleMatch(tenant, incomingMessage, validationStateReader);
 
   case DwnMethodName.Count:
     return [ProtocolAction.Read];
@@ -167,41 +142,91 @@ export async function getActionsSeekingARuleMatch(
   case DwnMethodName.Subscribe:
     return [ProtocolAction.Read];
 
-  case DwnMethodName.Write: {
-    const incomingRecordsWrite = incomingMessage as RecordsWrite;
+  case DwnMethodName.Write:
+    return getWriteActionsSeekingARuleMatch(tenant, incomingMessage, validationStateReader);
+  }
 
-    if (await incomingRecordsWrite.isInitialWrite()) {
-      // A squash write seeks the `squash` action first, with fallback to `create`.
-      // This means any DID authorized to `create` can also squash when no explicit `squash` rule exists.
-      if (incomingRecordsWrite.message.descriptor.squash === true) {
-        return [ProtocolAction.Squash, ProtocolAction.Create];
-      }
-      return [ProtocolAction.Create];
-    } else {
-      // else incoming RecordsWrite not an initial write
+  // purely defensive programming: should not be reachable
+  // setting to empty array will prevent any message from being authorized
+  return [];
+}
+
+/**
+ * Handles the `RecordsDelete` case of `getActionsSeekingARuleMatch()`.
+ */
+async function getDeleteActionsSeekingARuleMatch(
+  tenant: string,
+  incomingMessage: RecordsCount | RecordsDelete | RecordsQuery | RecordsRead | RecordsSubscribe | RecordsWrite,
+  validationStateReader: ValidationStateReader,
+): Promise<ProtocolAction[]> {
+  const recordsDelete = incomingMessage as RecordsDelete;
+  const recordId = recordsDelete.message.descriptor.recordId;
+  const initialWrite = await validationStateReader.fetchInitialRecordsWrite(tenant, recordId);
+
+  // if there is no initial write, then no action rule can authorize the incoming message, because we won't know who the original author is
+  // NOTE: purely defensive programming: currently not reachable
+  // because RecordsDelete handler already have an existence check prior to this method being called.
+  if (initialWrite === undefined) {
+    return [];
+  }
 
-      const recordId = (incomingMessage as RecordsWrite).message.recordId;
-      const initialWrite = await validationStateReader.fetchInitialRecordsWrite(tenant, recordId);
+  const actionsThatWouldAuthorizeDelete: ProtocolAction[] = [];
+  const prune = recordsDelete.message.descriptor.prune;
+  if (prune) {
+    actionsThatWouldAuthorizeDelete.push(ProtocolAction.CoPrune);
 
-      // if there is no initial write to update from, then no action rule can authorize the incoming message
-      if (initialWrite === undefined) {
-        return [];
-      }
+    // A prune by the original record author can also be authorized by a 'prune' rule.
+    if (incomingMessage.author === initialWrite.author) {
+      actionsThatWouldAuthorizeDelete.push(ProtocolAction.Prune);
+    }
+  } else {
+    actionsThatWouldAuthorizeDelete.push(ProtocolAction.CoDelete);
 
-      if (incomingMessage.author === initialWrite.author) {
-      // 'update' or 'co-update' action authorizes the incoming message
-        return [ProtocolAction.CoUpdate, ProtocolAction.Update];
-      } else {
-        // An update by someone who is not the record author can only be authorized by a 'co-update' rule.
-        return [ProtocolAction.CoUpdate];
-      }
+    // A delete by the original record author can also be authorized by a 'delete' rule.
+    if (incomingMessage.author === initialWrite.author) {
+      actionsThatWouldAuthorizeDelete.push(ProtocolAction.Delete);
     }
   }
-  }
 
-  // purely defensive programming: should not be reachable
-  // setting to empty array will prevent any message from being authorized
-  return [];
+  return actionsThatWouldAuthorizeDelete;
+}
+
+/**
+ * Handles the `RecordsWrite` case of `getActionsSeekingARuleMatch()`.
+ */
+async function getWriteActionsSeekingARuleMatch(
+  tenant: string,
+  incomingMessage: RecordsCount | RecordsDelete | RecordsQuery | RecordsRead | RecordsSubscribe | RecordsWrite,
+  validationStateReader: ValidationStateReader,
+): Promise<ProtocolAction[]> {
+  const incomingRecordsWrite = incomingMessage as RecordsWrite;
+
+  if (await incomingRecordsWrite.isInitialWrite()) {
+    // A squash write seeks the `squash` action first, with fallback to `create`.
+    // This means any DID authorized to `create` can also squash when no explicit `squash` rule exists.
+    if (incomingRecordsWrite.message.descriptor.squash === true) {
+      return [ProtocolAction.Squash, ProtocolAction.Create];
+    }
+    return [ProtocolAction.Create];
+  } else {
+    // else incoming RecordsWrite not an initial write
+
+    const recordId = (incomingMessage as RecordsWrite).message.recordId;
+    const initialWrite = await validationStateReader.fetchInitialRecordsWrite(tenant, recordId);
+
+    // if there is no initial write to update from, then no action rule can authorize the incoming message
+    if (initialWrite === undefined) {
+      return [];
+    }
+
+    if (incomingMessage.author === initialWrite.author) {
+    // 'update' or 'co-update' action authorizes the incoming message
+      return [ProtocolAction.CoUpdate, ProtocolAction.Update];
+    } else {
+      // An update by someone who is not the record author can only be authorized by a 'co-update' rule.
+      return [ProtocolAction.CoUpdate];
+    }
+  }
 }
 
 /**
@@ -235,76 +260,101 @@ export async function authorizeAgainstAllowedActions(
 
   // Iterate through the action rules to find a rule that authorizes the incoming message.
   for (const actionRule of actionRules) {
-    // If the action rule does not have an allowed action that matches an action that can authorize the message, skip to evaluate next action rule.
-    const ruleHasAMatchingAllowedAction = actionRule.can.some(
-      (allowedAction: string): boolean => actionsSeekingARuleMatch.includes(allowedAction as ProtocolAction)
+    const actionRuleAuthorizes = await actionRuleAuthorizesMessage(
+      actionRule, actionsSeekingARuleMatch, author, invokedRole, incomingMessage, recordChain, protocolDefinition
     );
-    if (!ruleHasAMatchingAllowedAction) {
-      continue;
+    if (actionRuleAuthorizes) {
+      return;
     }
+  }
 
-    // Code reaches here means this action rule has an allowed action that matches the action of the message.
-    // The remaining code checks the actor/author of the incoming message.
+  // No action rules were satisfied, message is not authorized
+  throw new DwnError(
+    DwnErrorCode.ProtocolAuthorizationActionNotAllowed,
+    `Inbound message action Records${incomingMessageMethod} by author ${incomingMessage.author} not allowed.`
+  );
+}
 
-    // If the action rule allows `anyone`, then no further checks are needed.
-    if (actionRule.who === ProtocolActor.Anyone) {
-      return;
-    }
+/**
+ * Evaluates whether a single action rule authorizes the incoming message, mirroring the
+ * original per-rule evaluation performed inline in the `authorizeAgainstAllowedActions()` loop.
+ * Returns `true` when the rule authorizes the message (the caller should stop and authorize);
+ * `false` when the rule does not match and the caller should move on to the next rule.
+ */
+async function actionRuleAuthorizesMessage(
+  actionRule: ProtocolActionRule,
+  actionsSeekingARuleMatch: ProtocolAction[],
+  author: string | undefined,
+  invokedRole: string | undefined,
+  incomingMessage: RecordsCount | RecordsDelete | RecordsQuery | RecordsRead | RecordsSubscribe | RecordsWrite,
+  recordChain: RecordsWriteMessage[],
+  protocolDefinition?: ProtocolDefinition,
+): Promise<boolean> {
+  // If the action rule does not have an allowed action that matches an action that can authorize the message, skip to evaluate next action rule.
+  const ruleHasAMatchingAllowedAction = actionRule.can.some(
+    (allowedAction: string): boolean => actionsSeekingARuleMatch.includes(allowedAction as ProtocolAction)
+  );
+  if (!ruleHasAMatchingAllowedAction) {
+    return false;
+  }
 
-    // Since not `anyone` is allowed in this action rule, we will need to check the author of the incoming message,
-    // if the author of incoming message is not defined, this action rule cannot authorize the incoming message.
-    if (author === undefined) {
-      continue;
-    }
+  // Code reaches here means this action rule has an allowed action that matches the action of the message.
+  // The remaining code checks the actor/author of the incoming message.
 
-    // go through role validation path if a role is invoked by the incoming message
-    if (invokedRole !== undefined) {
-      // When a protocol role is being invoked, we require that there is a matching `role` rule.
-      if (actionRule.role === invokedRole) {
-        // role is successfully invoked
-        return;
-      } else {
-        continue;
-      }
+  // If the action rule allows `anyone`, then no further checks are needed.
+  if (actionRule.who === ProtocolActor.Anyone) {
+    return true;
+  }
+
+  // Since not `anyone` is allowed in this action rule, we will need to check the author of the incoming message,
+  // if the author of incoming message is not defined, this action rule cannot authorize the incoming message.
+  if (author === undefined) {
+    return false;
+  }
+
+  // go through role validation path if a role is invoked by the incoming message
+  if (invokedRole !== undefined) {
+    // When a protocol role is being invoked, we require that there is a matching `role` rule.
+    if (actionRule.role === invokedRole) {
+      // role is successfully invoked
+      return true;
+    } else {
+      return false;
     }
+  }
 
-    // else we go through the actor (`who`) validation
-
-    // If `of` is not set, handle it as a special case
-    // NOTE: `of` is always set if `who` is set to `author` (we do this check in `validateRuleSetRecursively()`)
-    if (actionRule.who === ProtocolActor.Recipient && actionRule.of === undefined) {
-      // If the action rule specifies a recipient without `of` and the incoming message is authenticated:
-
-      // Author must be recipient of the record being accessed
-      let recordsWriteMessage: RecordsWriteMessage;
-      if (incomingMessage.message.descriptor.method === DwnMethodName.Write) {
-        recordsWriteMessage = incomingMessage.message as RecordsWriteMessage;
-      } else {
-        // else the incoming message must be a `RecordsDelete` because only `co-update`, `co-delete`, `co-prune` are allowed recipient actions,
-        // (we do this check in `validateRuleSetRecursively()`)
-        // and we have already checked that the incoming message is not a `RecordsWrite` above which covers `co-update` path.
-        recordsWriteMessage = recordChain[recordChain.length - 1];
-      }
+  // else we go through the actor (`who`) validation
 
-      if (recordsWriteMessage.descriptor.recipient === author) {
-        return;
-      } else {
-        continue;
-      }
+  // If `of` is not set, handle it as a special case
+  // NOTE: `of` is always set if `who` is set to `author` (we do this check in `validateRuleSetRecursively()`)
+  if (actionRule.who === ProtocolActor.Recipient && actionRule.of === undefined) {
+    // If the action rule specifies a recipient without `of` and the incoming message is authenticated:
+
+    // Author must be recipient of the record being accessed
+    let recordsWriteMessage: RecordsWriteMessage;
+    if (incomingMessage.message.descriptor.method === DwnMethodName.Write) {
+      recordsWriteMessage = incomingMessage.message as RecordsWriteMessage;
+    } else {
+      // else the incoming message must be a `RecordsDelete` because only `co-update`, `co-delete`, `co-prune` are allowed recipient actions,
+      // (we do this check in `validateRuleSetRecursively()`)
+      // and we have already checked that the incoming message is not a `RecordsWrite` above which covers `co-update` path.
+      recordsWriteMessage = recordChain.at(-1)!;
     }
 
-    // validate the actor is allowed by the current action rule
-    const ancestorRuleSuccess: boolean = await checkActor(author, actionRule, recordChain, protocolDefinition);
-    if (ancestorRuleSuccess) {
-      return;
+    if (recordsWriteMessage.descriptor.recipient === author) {
+      return true;
+    } else {
+      return false;
     }
   }
 
-  // No action rules were satisfied, message is not authorized
-  throw new DwnError(
-    DwnErrorCode.ProtocolAuthorizationActionNotAllowed,
-    `Inbound message action Records${incomingMessageMethod} by author ${incomingMessage.author} not allowed.`
-  );
+  // validate the actor is allowed by the current action rule
+  const ancestorRuleSuccess: boolean = await checkActor(author, actionRule, recordChain, protocolDefinition);
+  if (ancestorRuleSuccess) {
+    return true;
+  }
+
+  return false;
 }
 
 /**

package/src/core/protocol-authorization.ts

@@ -108,6 +108,19 @@ export class ProtocolAuthorization {
   ): Promise<void> {
     await ProtocolAuthorization.verifyStoredInitialWrite(incomingMessage);
 
+    // Encryption control records live at reserved virtual paths and are admitted through
+    // `EncryptionControl` validation (see `validateReferentialIntegrity()`), never against the
+    // app definition's structure. Revalidate their config-owned admission invariants against
+    // the role rule set that governed the record timestamp, then apply the same conservative
+    // static-create authorization replay used for ordinary records.
+    if (isEncryptionControlPath(incomingMessage.message.descriptor.protocolPath)) {
+      const governingRuleSet = await EncryptionControl.validateStoredControlRecord(
+        tenant, incomingMessage, validationStateReader
+      );
+      ProtocolAuthorization.verifyStoredInitialWriteCreateAction(tenant, incomingMessage, governingRuleSet);
+      return;
+    }
+
     const protocolDefinitionTimestamp = incomingMessage.message.descriptor.messageTimestamp;
     const protocolDefinition = await validationStateReader.fetchProtocolDefinition(
       tenant,

package/src/event-stream/broadcast-channel-wake-publisher.ts

@@ -0,0 +1,71 @@
+import type { WakeListener } from './event-emitter-wake-publisher.js';
+import type { Wake, WakePublisher, WakeSubscriber } from '../types/subscriptions.js';
+
+import { EventEmitterWakePublisher } from './event-emitter-wake-publisher.js';
+
+/**
+ * Cross-context {@link WakePublisher} + {@link WakeSubscriber}: fans each wake
+ * out to in-process listeners AND mirrors it over a named `BroadcastChannel`,
+ * so sibling execution contexts sharing the same underlying store (browser
+ * tabs, workers, a SharedWorker over one IndexedDB) observe each other's
+ * commits immediately instead of waiting for their event log's idle re-drain.
+ *
+ * Wakes received from the channel are delivered to in-process listeners only
+ * and never re-posted, so wakes cannot loop between contexts. Environments
+ * without `BroadcastChannel` degrade to in-process-only delivery, and
+ * publication stays best-effort by contract: channel failures must not affect
+ * the write path that already committed the row.
+ *
+ * In Node/Bun, `BroadcastChannel` spans only threads within one process —
+ * multi-process server deployments still converge through the event log's
+ * idle re-drain rather than through this bridge.
+ */
+export class BroadcastChannelWakePublisher implements WakePublisher, WakeSubscriber {
+  private readonly _local = new EventEmitterWakePublisher();
+  private readonly _channel?: BroadcastChannel;
+
+  /**
+   * @param channelName - Channel identity. Contexts sharing one physical
+   * store must use the same name; derive it from the store location so
+   * distinct stores on the same origin do not cross-wake.
+   */
+  public constructor(channelName: string) {
+    if (typeof BroadcastChannel === 'undefined') {
+      return;
+    }
+
+    this._channel = new BroadcastChannel(channelName);
+    // Node's channel keeps the event loop alive unless unreferenced; the
+    // browser implementation has no `unref` and needs none.
+    (this._channel as { unref?: () => void }).unref?.();
+    this._channel.onmessage = (event: MessageEvent): void => {
+      const wake = event.data as Wake | undefined;
+      if (typeof wake?.tenant !== 'string' || typeof wake?.seq !== 'string') {
+        return; // not a wake — ignore foreign traffic on the channel
+      }
+      this._local.publish(wake);
+    };
+  }
+
+  public publish(wake: Wake): void {
+    this._local.publish(wake);
+    try {
+      this._channel?.postMessage(wake);
+    } catch {
+      // Best-effort by contract — e.g. a closed channel.
+    }
+  }
+
+  public subscribe(listener: WakeListener): () => void {
+    return this._local.subscribe(listener);
+  }
+
+  public clear(): void {
+    this._local.clear();
+  }
+
+  /** Releases the underlying channel. In-process delivery keeps working. */
+  public close(): void {
+    this._channel?.close();
+  }
+}

package/src/handlers/protocols-configure.ts

@@ -20,6 +20,8 @@ import { getRuleSetAtPath, getTypeName, parseCrossProtocolRef } from '../utils/p
 type StoredInitialWriteConfigValidity = 'valid' | 'invalid' | 'unknown';
 
 const STORED_INITIAL_WRITE_CONFIG_INVALID_CODES = new Set<string>([
+  DwnErrorCode.EncryptionControlValidateAudienceRolePathInvalid,
+  DwnErrorCode.EncryptionControlValidateAudienceSealKeyIdMismatch,
   DwnErrorCode.ProtocolAuthorizationEncryptionRequired,
   DwnErrorCode.ProtocolAuthorizationIncorrectDataFormat,
   DwnErrorCode.ProtocolAuthorizationInitialWriteRevalidationNotInitial,

package/src/handlers/records-subscribe.ts

@@ -1,5 +1,5 @@
 import type { MessageSort } from '../types/message-types.js';
-import type { EventSubscription, ProgressGapInfo, SubscriptionEvent, SubscriptionListener, SubscriptionMessage } from '../types/subscriptions.js';
+import type { EventSubscription, ProgressGapInfo, ProgressToken, SubscriptionEvent, SubscriptionListener, SubscriptionMessage } from '../types/subscriptions.js';
 import type { Filter, PaginationCursor } from '../types/query-types.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { RecordsQueryReplyEntry, RecordsSubscribeMessage, RecordsSubscribeReply } from '../types/records-types.js';
@@ -51,34 +51,12 @@ export class RecordsSubscribeHandler implements MethodHandler {
       return messageReplyFromError(e, 400);
     }
 
-    let eventFilters: Filter[] = [];
-    let queryFilters: Filter[] = [];
     const requester = Message.getRequester(recordsSubscribe.message);
-
-    // if this is an anonymous subscribe and the filter supports published records, subscribe to only published records
-    if (Records.filterIncludesPublishedRecords(recordsSubscribe.message.descriptor.filter) && recordsSubscribe.author === undefined) {
-      eventFilters = [RecordsSubscribeHandler.buildPublishedEventFilter(recordsSubscribe)];
-      queryFilters = [RecordsSubscribeHandler.buildPublishedQueryFilter(recordsSubscribe)];
-      // delete the undefined authorization property else the code will encounter the following IPLD issue when attempting to generate CID:
-      // Error: `undefined` is not supported by the IPLD Data Model and cannot be encoded
-      delete message.authorization;
-    } else {
-      // authentication and authorization
-      try {
-        await authenticate(message.authorization!, this.deps.didResolver);
-        await RecordsSubscribeHandler.authorizeRecordsSubscribe(tenant, recordsSubscribe, this.deps);
-      } catch (error) {
-        return messageReplyFromError(error, 401);
-      }
-
-      if (recordsSubscribe.author === tenant) {
-        eventFilters = RecordsSubscribeHandler.buildOwnerEventFilters(recordsSubscribe);
-        queryFilters = RecordsSubscribeHandler.buildOwnerQueryFilters(recordsSubscribe);
-      } else {
-        eventFilters = RecordsSubscribeHandler.buildNonOwnerEventFilters(recordsSubscribe);
-        queryFilters = RecordsSubscribeHandler.buildNonOwnerQueryFilters(recordsSubscribe);
-      }
+    const filterResolution = await this.resolveSubscriptionFilters(tenant, message, recordsSubscribe);
+    if ('errorReply' in filterResolution) {
+      return filterResolution.errorReply;
     }
+    const { eventFilters, queryFilters } = filterResolution;
 
     const messageCid = await Message.getCid(message);
     const { cursor: eventLogCursor } = recordsSubscribe.message.descriptor;
@@ -95,34 +73,107 @@ export class RecordsSubscribeHandler implements MethodHandler {
       // All catch-up, buffering, dedup, and EOSE delivery are handled by the
       // EventLog implementation. The handler just passes the cursor and filters.
       // The subscriptionHandler receives SubscriptionMessage (event + EOSE) directly.
+      return this.handleCursorSubscription(tenant, messageCid, eventFilters, eventLogCursor, projectedSubscriptionHandler);
+    }
 
-      try {
-        const subscription = await this.deps.eventLog.subscribe(tenant, messageCid, projectedSubscriptionHandler.listener, {
-          cursor  : eventLogCursor,
-          filters : eventFilters,
-        });
-        await projectedSubscriptionHandler.setSubscription(subscription);
+    // ---- No cursor: existing behavior (initial snapshot from MessageStore) ----
+    return this.handleSnapshotSubscription(
+      tenant, messageCid, recordsSubscribe, requester, eventFilters, queryFilters, projectedSubscriptionHandler
+    );
+  }
+
+  /**
+   * Resolves the event/query filters for the subscription, performing authentication and
+   * authorization when the request is not an anonymous published-records-only subscribe.
+   * Returns the resolved filters, or an `errorReply` if authentication/authorization failed.
+   */
+  private async resolveSubscriptionFilters(
+    tenant: string,
+    message: RecordsSubscribeMessage,
+    recordsSubscribe: RecordsSubscribe,
+  ): Promise<{ eventFilters: Filter[]; queryFilters: Filter[] } | { errorReply: RecordsSubscribeReply }> {
+    // if this is an anonymous subscribe and the filter supports published records, subscribe to only published records
+    if (Records.filterIncludesPublishedRecords(recordsSubscribe.message.descriptor.filter) && recordsSubscribe.author === undefined) {
+      const eventFilters = [RecordsSubscribeHandler.buildPublishedEventFilter(recordsSubscribe)];
+      const queryFilters = [RecordsSubscribeHandler.buildPublishedQueryFilter(recordsSubscribe)];
+      // delete the undefined authorization property else the code will encounter the following IPLD issue when attempting to generate CID:
+      // Error: `undefined` is not supported by the IPLD Data Model and cannot be encoded
+      delete message.authorization;
+      return { eventFilters, queryFilters };
+    }
+
+    // authentication and authorization
+    try {
+      await authenticate(message.authorization!, this.deps.didResolver);
+      await RecordsSubscribeHandler.authorizeRecordsSubscribe(tenant, recordsSubscribe, this.deps);
+    } catch (error) {
+      return { errorReply: messageReplyFromError(error, 401) };
+    }
+
+    if (recordsSubscribe.author === tenant) {
+      return {
+        eventFilters : RecordsSubscribeHandler.buildOwnerEventFilters(recordsSubscribe),
+        queryFilters : RecordsSubscribeHandler.buildOwnerQueryFilters(recordsSubscribe),
+      };
+    }
+
+    return {
+      eventFilters : RecordsSubscribeHandler.buildNonOwnerEventFilters(recordsSubscribe),
+      queryFilters : RecordsSubscribeHandler.buildNonOwnerQueryFilters(recordsSubscribe),
+    };
+  }
+
+  /**
+   * Handles cursor-mode subscription: catch-up from EventLog + EOSE + live. All catch-up,
+   * buffering, dedup, and EOSE delivery are handled by the EventLog implementation. The handler
+   * just passes the cursor and filters. The subscriptionHandler receives SubscriptionMessage
+   * (event + EOSE) directly.
+   */
+  private async handleCursorSubscription(
+    tenant: string,
+    messageCid: string,
+    eventFilters: Filter[],
+    eventLogCursor: ProgressToken,
+    projectedSubscriptionHandler: ProjectedRecordsSubscriptionHandler,
+  ): Promise<RecordsSubscribeReply> {
+    try {
+      const subscription = await this.deps.eventLog!.subscribe(tenant, messageCid, projectedSubscriptionHandler.listener, {
+        cursor  : eventLogCursor,
+        filters : eventFilters,
+      });
+      await projectedSubscriptionHandler.setSubscription(subscription);
 
+      return {
+        status: { code: 200, detail: 'OK' },
+        subscription,
+      };
+    } catch (error) {
+      if (error instanceof DwnError && error.code === DwnErrorCode.EventLogProgressGap) {
+        const gapInfo = (error as any).gapInfo as ProgressGapInfo | undefined;
         return {
-          status: { code: 200, detail: 'OK' },
-          subscription,
+          status : { code: 410, detail: 'Progress token gap' },
+          error  : gapInfo === undefined ? undefined : { code: 'ProgressGap' as const, ...gapInfo },
         };
-      } catch (error) {
-        if (error instanceof DwnError && error.code === DwnErrorCode.EventLogProgressGap) {
-          const gapInfo = (error as any).gapInfo as ProgressGapInfo | undefined;
-          return {
-            status : { code: 410, detail: 'Progress token gap' },
-            error  : gapInfo === undefined ? undefined : { code: 'ProgressGap' as const, ...gapInfo },
-          };
-        }
-        return messageReplyFromError(error, 500);
       }
+      return messageReplyFromError(error, 500);
     }
+  }
 
-    // ---- No cursor: existing behavior (initial snapshot from MessageStore) ----
-
+  /**
+   * Handles the no-cursor path: registers the event listener first (so no events are missed
+   * between query and subscribe), then queries for the initial snapshot of matching records.
+   */
+  private async handleSnapshotSubscription(
+    tenant: string,
+    messageCid: string,
+    recordsSubscribe: RecordsSubscribe,
+    requester: string | undefined,
+    eventFilters: Filter[],
+    queryFilters: Filter[],
+    projectedSubscriptionHandler: ProjectedRecordsSubscriptionHandler,
+  ): Promise<RecordsSubscribeReply> {
     // Step 1: Register event listener FIRST to ensure no events are missed between query and subscribe
-    const subscription = await this.deps.eventLog.subscribe(tenant, messageCid, projectedSubscriptionHandler.listener, {
+    const subscription = await this.deps.eventLog!.subscribe(tenant, messageCid, projectedSubscriptionHandler.listener, {
       filters: eventFilters,
     });
     await projectedSubscriptionHandler.setSubscription(subscription);