@enbox/dwn-sdk-js 0.4.12 → 0.4.14

package/src/handlers/records-write.ts

@@ -1,3 +1,4 @@
+import type { CoreProtocol } from '../core/core-protocol.js';
 import type { ProgressToken } from '../types/subscriptions.js';
 import type { GenericMessage, GenericMessageReply } from '../types/message-types.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
@@ -49,13 +50,9 @@ export class RecordsWriteHandler implements MethodHandler {
     // mutable validation. An already-stored message has already passed
     // admission; replay should not be reinterpreted against current protocol,
     // parent, role, grant, or record-limit state.
-    const incomingCid = await Message.getCid(message);
-    for (const existingMessage of existingMessages) {
-      if (await Message.getCid(existingMessage) !== incomingCid) {
-        continue;
-      }
-
-      return { status: { code: 409, detail: 'Conflict' } };
+    const conflictReply = await this.findConflictingMessageReply(message, existingMessages);
+    if (conflictReply !== undefined) {
+      return conflictReply;
     }
 
     const newMessageIsInitialWrite = await recordsWrite.isInitialWrite();
@@ -81,12 +78,9 @@ export class RecordsWriteHandler implements MethodHandler {
       return messageReplyFromError(e, 401);
     }
 
-    if (initialWrite !== undefined) {
-      try {
-        this.verifyImmutableProperties(initialWrite, message);
-      } catch (e) {
-        return messageReplyFromError(e, 400);
-      }
+    const immutablePropertyReply = this.verifyImmutablePropertiesReply(initialWrite, message);
+    if (immutablePropertyReply !== undefined) {
+      return immutablePropertyReply;
     }
 
     // Squash backstop: if the protocol path has $squash: true, reject any write whose
@@ -111,88 +105,23 @@ export class RecordsWriteHandler implements MethodHandler {
 
     // Look up the core protocol (if any) for the incoming message so that lifecycle hooks
     // can be dispatched generically rather than checking for specific protocol URIs.
-    const coreProtocol = message.descriptor.protocol === undefined
-      ? undefined
-      : this.deps.coreProtocols?.get(message.descriptor.protocol);
+    const coreProtocol = this.getCoreProtocolForWrite(message);
     let position: ProgressToken | undefined;
 
     try {
-      if (newestExistingMessage?.descriptor.method === DwnMethodName.Delete) {
-        throw new DwnError(
-          DwnErrorCode.RecordsWriteNotAllowedAfterDelete,
-          'RecordsWrite is not allowed after a RecordsDelete.'
-        );
-      }
-
-      // Dispatch pre-processing hooks to the core protocol, if applicable.
-      // This allows core protocols to perform cross-record validation before storage
-      // (e.g. ensuring revocation tag consistency with the parent grant's scoped protocol).
-      if (coreProtocol?.preProcessWrite !== undefined) {
-        await coreProtocol.preProcessWrite(tenant, message, this.deps.validationStateReader);
-      }
-      if (EncryptionControl.isControlMessage(message)) {
-        await EncryptionControl.preProcessWrite(tenant, message, this.deps.validationStateReader);
-        if (dataStream === undefined) {
-          throw new DwnError(
-            DwnErrorCode.EncryptionControlValidateUnexpectedRecord,
-            'encryption control records require data.'
-          );
-        }
-      }
-
-      // NOTE: We allow isLatestBaseState to be true ONLY if the incoming message comes with data, or if the incoming message is NOT an initial write
-      // This would allow an initial write to be written to the DB without data, but having it not queryable,
-      // because query implementation filters on `isLatestBaseState` being `true`
-      // thus preventing a user's attempt to gain authorized access to data by referencing the dataCid of a private data in their initial writes,
-      // See: https://github.com/enboxorg/enbox/issues/359 for more info
-      let isLatestBaseState = false;
-      let messageWithOptionalEncodedData = message as RecordsQueryReplyEntry;
-
-      if (dataStream === undefined) {
-        // data stream is NOT provided
-
-        // if the incoming message is not an initial write, and no dataStream is provided, we would allow it provided it passes validation
-        // processMessageWithoutDataStream() abstracts that logic
-        if (!newMessageIsInitialWrite) {
-          const newestExistingWrite = newestExistingMessage as RecordsQueryReplyEntry;
-          messageWithOptionalEncodedData = await this.processMessageWithoutDataStream(tenant, message, newestExistingWrite );
-          isLatestBaseState = true;
-        }
-      } else {
-        messageWithOptionalEncodedData = await this.processMessageWithDataStream(tenant, message, dataStream);
-        isLatestBaseState = true;
-      }
-
-      const indexes = await recordsWrite.constructIndexes(isLatestBaseState);
-
-      // store the new message and displace every other message for this record in one atomic
-      // commit, retaining only the initial write as non-latest state — readers can never observe
-      // two latest-state rows for the record
-      const putResult = await StorageController.commitLatestStateTransition(
-        tenant,
+      const commitResult = await this.commitRecordsWrite({
+        coreProtocol,
+        dataStream,
         existingMessages,
-        { message: messageWithOptionalEncodedData, indexes },
-        [],
-        this.deps.messageStore,
-        this.deps.dataStore!,
-      );
-      position = putResult.position;
+        message,
+        newestExistingMessage,
+        newMessageIsInitialWrite,
+        recordsWrite,
+        tenant,
+      });
+      position = commitResult.position;
     } catch (error) {
-      if (error instanceof DwnError) {
-        if (error.code === DwnErrorCode.RecordsWriteMissingEncodedDataInPrevious ||
-          error.code === DwnErrorCode.RecordsWriteMissingDataInPrevious ||
-          error.code === DwnErrorCode.RecordsWriteNotAllowedAfterDelete ||
-          error.code === DwnErrorCode.RecordsWriteDataCidMismatch ||
-          error.code === DwnErrorCode.RecordsWriteDataSizeMismatch ||
-          error.code.startsWith('SchemaValidator') ||
-          EncryptionControl.mapErrorToStatusCode(error.code) !== undefined ||
-          this.deps.coreProtocols?.mapErrorToStatusCode(error.code) !== undefined) {
-          return messageReplyFromError(error, 400);
-        }
-      }
-
-      // else throw
-      throw error;
+      return this.mapCommitWriteErrorToReply(error);
     }
 
     const messageReply = {
@@ -227,6 +156,162 @@ export class RecordsWriteHandler implements MethodHandler {
     return messageReply;
   };
 
+  /**
+   * Returns a 409 Conflict reply if a message with the same CID as the incoming message already
+   * exists among `existingMessages`, else `undefined`. An already-stored message has already
+   * passed admission; replay should not be reinterpreted against current protocol, parent, role,
+   * grant, or record-limit state.
+   */
+  private async findConflictingMessageReply(
+    message: RecordsWriteMessage,
+    existingMessages: GenericMessage[],
+  ): Promise<GenericMessageReply | undefined> {
+    const incomingCid = await Message.getCid(message);
+    for (const existingMessage of existingMessages) {
+      if (await Message.getCid(existingMessage) !== incomingCid) {
+        continue;
+      }
+
+      return { status: { code: 409, detail: 'Conflict' } };
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Verifies that immutable properties are unchanged relative to the `initialWrite`, returning a
+   * 400 reply if verification fails. Returns `undefined` (skipping verification) when there is no
+   * `initialWrite` to compare against, i.e. the incoming message is itself the initial write.
+   */
+  private verifyImmutablePropertiesReply(
+    initialWrite: RecordsWriteMessage | undefined,
+    message: RecordsWriteMessage,
+  ): GenericMessageReply | undefined {
+    if (initialWrite === undefined) {
+      return undefined;
+    }
+
+    try {
+      this.verifyImmutableProperties(initialWrite, message);
+      return undefined;
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+  }
+
+  /**
+   * Looks up the core protocol (if any) for the incoming message so that lifecycle hooks
+   * can be dispatched generically rather than checking for specific protocol URIs.
+   */
+  private getCoreProtocolForWrite(message: RecordsWriteMessage): CoreProtocol | undefined {
+    if (message.descriptor.protocol === undefined) {
+      return undefined;
+    }
+
+    return this.deps.coreProtocols?.get(message.descriptor.protocol);
+  }
+
+  /**
+   * Runs the pre-processing hooks, resolves whether the write is queryable (`isLatestBaseState`),
+   * and commits the new message and its indexes as the latest state transition for the record.
+   */
+  private async commitRecordsWrite(input: {
+    coreProtocol: CoreProtocol | undefined;
+    dataStream?: ReadableStream<Uint8Array>;
+    existingMessages: GenericMessage[];
+    message: RecordsWriteMessage;
+    newestExistingMessage: GenericMessage | undefined;
+    newMessageIsInitialWrite: boolean;
+    recordsWrite: RecordsWrite;
+    tenant: string;
+  }): Promise<{ position?: ProgressToken }> {
+    const { coreProtocol, dataStream, existingMessages, message, newestExistingMessage, newMessageIsInitialWrite, recordsWrite, tenant } = input;
+
+    if (newestExistingMessage?.descriptor.method === DwnMethodName.Delete) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteNotAllowedAfterDelete,
+        'RecordsWrite is not allowed after a RecordsDelete.'
+      );
+    }
+
+    // Dispatch pre-processing hooks to the core protocol, if applicable.
+    // This allows core protocols to perform cross-record validation before storage
+    // (e.g. ensuring revocation tag consistency with the parent grant's scoped protocol).
+    if (coreProtocol?.preProcessWrite !== undefined) {
+      await coreProtocol.preProcessWrite(tenant, message, this.deps.validationStateReader);
+    }
+    if (EncryptionControl.isControlMessage(message)) {
+      await EncryptionControl.preProcessWrite(tenant, message, this.deps.validationStateReader);
+      if (dataStream === undefined) {
+        throw new DwnError(
+          DwnErrorCode.EncryptionControlValidateUnexpectedRecord,
+          'encryption control records require data.'
+        );
+      }
+    }
+
+    // NOTE: We allow isLatestBaseState to be true ONLY if the incoming message comes with data, or if the incoming message is NOT an initial write
+    // This would allow an initial write to be written to the DB without data, but having it not queryable,
+    // because query implementation filters on `isLatestBaseState` being `true`
+    // thus preventing a user's attempt to gain authorized access to data by referencing the dataCid of a private data in their initial writes,
+    // See: https://github.com/enboxorg/enbox/issues/359 for more info
+    let isLatestBaseState = false;
+    let messageWithOptionalEncodedData = message as RecordsQueryReplyEntry;
+
+    if (dataStream === undefined) {
+      // data stream is NOT provided
+
+      // if the incoming message is not an initial write, and no dataStream is provided, we would allow it provided it passes validation
+      // processMessageWithoutDataStream() abstracts that logic
+      if (!newMessageIsInitialWrite) {
+        const newestExistingWrite = newestExistingMessage as RecordsQueryReplyEntry;
+        messageWithOptionalEncodedData = await this.processMessageWithoutDataStream(tenant, message, newestExistingWrite );
+        isLatestBaseState = true;
+      }
+    } else {
+      messageWithOptionalEncodedData = await this.processMessageWithDataStream(tenant, message, dataStream);
+      isLatestBaseState = true;
+    }
+
+    const indexes = await recordsWrite.constructIndexes(isLatestBaseState);
+
+    // store the new message and displace every other message for this record in one atomic
+    // commit, retaining only the initial write as non-latest state — readers can never observe
+    // two latest-state rows for the record
+    const putResult = await StorageController.commitLatestStateTransition(
+      tenant,
+      existingMessages,
+      { message: messageWithOptionalEncodedData, indexes },
+      [],
+      this.deps.messageStore,
+      this.deps.dataStore!,
+    );
+
+    return { position: putResult.position };
+  }
+
+  /**
+   * Maps a `commitRecordsWrite()` failure to a 400 reply when the error is a recognized,
+   * client-facing validation failure; otherwise rethrows the original error.
+   */
+  private mapCommitWriteErrorToReply(error: unknown): GenericMessageReply {
+    if (error instanceof DwnError) {
+      if (error.code === DwnErrorCode.RecordsWriteMissingEncodedDataInPrevious ||
+        error.code === DwnErrorCode.RecordsWriteMissingDataInPrevious ||
+        error.code === DwnErrorCode.RecordsWriteNotAllowedAfterDelete ||
+        error.code === DwnErrorCode.RecordsWriteDataCidMismatch ||
+        error.code === DwnErrorCode.RecordsWriteDataSizeMismatch ||
+        error.code.startsWith('SchemaValidator') ||
+        EncryptionControl.mapErrorToStatusCode(error.code) !== undefined ||
+        this.deps.coreProtocols?.mapErrorToStatusCode(error.code) !== undefined) {
+        return messageReplyFromError(error, 400);
+      }
+    }
+
+    // else throw
+    throw error;
+  }
+
   /**
    * Returns a `RecordsQueryReplyEntry` with a copy of the incoming message and the incoming data encoded to `Base64URL`.
    */
@@ -414,7 +499,8 @@ export class RecordsWriteHandler implements MethodHandler {
         DwnErrorCode.ProtocolAuthorizationSquashBackstop,
         `incoming message timestamp '${message.descriptor.messageTimestamp}' is not newer than ` +
         `the most recent squash record timestamp '${newestSquash.descriptor.messageTimestamp}' ` +
-        `at protocol path '${message.descriptor.protocolPath}'.`
+        `at protocol path '${message.descriptor.protocolPath}'.`,
+        { info: { squashFloorTimestamp: newestSquash.descriptor.messageTimestamp } }
       );
     }
   }

package/src/index.ts

@@ -48,6 +48,7 @@ export { Dwn } from './dwn.js';
 export type { MessageOptions } from './dwn.js';
 export { DwnConstant } from './core/dwn-constant.js';
 export { DwnError, DwnErrorCode } from './core/dwn-error.js';
+export type { DwnErrorInfo } from './core/dwn-error.js';
 export { DwnInterfaceName, DwnMethodName } from './enums/dwn-interface-method.js';
 export { Encoder } from './utils/encoder.js';
 export { MessagesSubscribe } from './interfaces/messages-subscribe.js';
@@ -135,6 +136,7 @@ export * from './types/permission-types.js';
 export * from './types/records-types.js';
 
 // concrete event log implementations
+export { BroadcastChannelWakePublisher } from './event-stream/broadcast-channel-wake-publisher.js';
 export { EventEmitterWakePublisher } from './event-stream/event-emitter-wake-publisher.js';
 export { DurableEventLog } from './event-stream/durable-event-log.js';
 export type { DurableEventLogConfig, DurableEventLogStore } from './event-stream/durable-event-log.js';

package/src/interfaces/protocols-configure.ts

@@ -464,14 +464,12 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
               `More than one action rule per role ${actionRule.role} not allowed within a rule set: ${JSON.stringify(actionRule)}`
             );
           }
-        } else {
-          if (actionRule.who === otherActionRule.who && actionRule.of === otherActionRule.of) {
-            throw new DwnError(
-              DwnErrorCode.ProtocolsConfigureDuplicateActorInRuleSet,
-              `More than one action rule per actor ${actionRule.who} of ${actionRule.of} ` +
-              `not allowed within a rule set: ${JSON.stringify(actionRule)}`
-            );
-          }
+        } else if (actionRule.who === otherActionRule.who && actionRule.of === otherActionRule.of) {
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureDuplicateActorInRuleSet,
+            `More than one action rule per actor ${actionRule.who} of ${actionRule.of} ` +
+            `not allowed within a rule set: ${JSON.stringify(actionRule)}`
+          );
         }
       }
     }

package/src/interfaces/records-write-query.ts

@@ -44,14 +44,13 @@ export function verifyEqualityOfImmutableProperties(
 
   // get distinct property names that exist in either the existing message given or new message
   let descriptorPropertyNames: string[] = [];
-  descriptorPropertyNames.push(...Object.keys(existingWriteMessage.descriptor));
-  descriptorPropertyNames.push(...Object.keys(newMessage.descriptor));
+  descriptorPropertyNames.push(...Object.keys(existingWriteMessage.descriptor), ...Object.keys(newMessage.descriptor));
   descriptorPropertyNames = [...new Set(descriptorPropertyNames)]; // step to remove duplicates
 
   // ensure all immutable properties are not modified
   for (const descriptorPropertyName of descriptorPropertyNames) {
     // if property is supposed to be immutable
-    if (mutableDescriptorProperties.indexOf(descriptorPropertyName) === -1) {
+    if (!mutableDescriptorProperties.includes(descriptorPropertyName)) {
       const valueInExistingWrite = (existingWriteMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
       const valueInNewMessage = (newMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
       if (valueInNewMessage !== valueInExistingWrite) {

package/src/interfaces/records-write.ts

@@ -253,7 +253,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    */
   public static async parse(recordsWriteMessage: RecordsWriteMessage): Promise<RecordsWrite> {
     // Make a copy so that the stored copy is not subject to external, unexpected modification.
-    const message = JSON.parse(JSON.stringify(recordsWriteMessage)) as RecordsWriteMessage;
+    const message = structuredClone(recordsWriteMessage);
 
     // Validate the message against the JSON schema.
     // We strip internal properties that the MessageStore may attach to stored messages
@@ -438,16 +438,14 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     // if given explicitly published dated
     if (options.datePublished) {
       datePublished = options.datePublished;
-    } else {
+    } else if (published) {
       // if this RecordsWrite will publish the record
-      if (published) {
-        // the parent was already published, inherit the same published date
-        if (sourceMessage.descriptor.published) {
-          datePublished = sourceMessage.descriptor.datePublished;
-        } else {
-          // this is a toggle from unpublished to published, use current time
-          datePublished = currentTime;
-        }
+      // the parent was already published, inherit the same published date
+      if (sourceMessage.descriptor.published) {
+        datePublished = sourceMessage.descriptor.datePublished;
+      } else {
+        // this is a toggle from unpublished to published, use current time
+        datePublished = currentTime;
       }
     }
 
@@ -630,29 +628,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   private async validateIntegrity(): Promise<void> {
     // if the new message is the initial write
     const isInitialWrite = await this.isInitialWrite();
-    if (isInitialWrite) {
-      // `messageTimestamp` and `dateCreated` equality check
-      const dateRecordCreated = this.message.descriptor.dateCreated;
-      const messageTimestamp = this.message.descriptor.messageTimestamp;
-      if (messageTimestamp !== dateRecordCreated) {
-        throw new DwnError(
-          DwnErrorCode.RecordsWriteValidateIntegrityDateCreatedMismatch,
-          `messageTimestamp ${messageTimestamp} must match dateCreated ${dateRecordCreated} for the initial write`
-        );
-      }
-
-      // if the message is a protocol context root, the `contextId` must match the expected deterministic value
-      if (this.message.descriptor.parentId === undefined) {
-        const expectedContextId = await this.getEntryId();
-
-        if (this.message.contextId !== expectedContextId) {
-          throw new DwnError(
-            DwnErrorCode.RecordsWriteValidateIntegrityContextIdMismatch,
-            `contextId in message: ${this.message.contextId} does not match deterministic contextId: ${expectedContextId}`
-          );
-        }
-      }
-    }
+    await this.validateInitialWriteIntegrity(isInitialWrite);
 
     // NOTE: validateSignatureStructure() call earlier enforces the presence of `authorization` and thus `signature` in RecordsWrite
     const signaturePayload = this.signaturePayload!;
@@ -687,6 +663,59 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       }
     }
 
+    await this.validateEncryptionCidIntegrity(signaturePayload);
+
+    validateProtocolUrlNormalized(this.message.descriptor.protocol);
+    if (this.message.descriptor.schema !== undefined) {
+      validateSchemaUrlNormalized(this.message.descriptor.schema);
+    }
+
+    Time.validateTimestamp(this.message.descriptor.messageTimestamp);
+    Time.validateTimestamp(this.message.descriptor.dateCreated);
+    if (this.message.descriptor.datePublished) {
+      Time.validateTimestamp(this.message.descriptor.datePublished);
+    }
+  }
+
+  /**
+   * Validates the `messageTimestamp`/`dateCreated` equality and, for a protocol context root,
+   * the deterministic `contextId` — both of which only apply to the initial write of a record.
+   * No-op when `isInitialWrite` is `false`.
+   */
+  private async validateInitialWriteIntegrity(isInitialWrite: boolean): Promise<void> {
+    if (!isInitialWrite) {
+      return;
+    }
+
+    // `messageTimestamp` and `dateCreated` equality check
+    const dateRecordCreated = this.message.descriptor.dateCreated;
+    const messageTimestamp = this.message.descriptor.messageTimestamp;
+    if (messageTimestamp !== dateRecordCreated) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteValidateIntegrityDateCreatedMismatch,
+        `messageTimestamp ${messageTimestamp} must match dateCreated ${dateRecordCreated} for the initial write`
+      );
+    }
+
+    // if the message is a protocol context root, the `contextId` must match the expected deterministic value
+    if (this.message.descriptor.parentId === undefined) {
+      const expectedContextId = await this.getEntryId();
+
+      if (this.message.contextId !== expectedContextId) {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteValidateIntegrityContextIdMismatch,
+          `contextId in message: ${this.message.contextId} does not match deterministic contextId: ${expectedContextId}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Validates that `encryption` in the message and `encryptionCid` in the signature payload are
+   * consistently present/absent, and that when both are present, `encryptionCid` matches the CID
+   * computed from `encryption`.
+   */
+  private async validateEncryptionCidIntegrity(signaturePayload: RecordsWriteSignaturePayload): Promise<void> {
     // if `encryption` is given in message, make sure the correct `encryptionCid` is in the payload of the message signature
     if (this.message.encryption !== undefined && signaturePayload.encryptionCid === undefined) {
       throw new DwnError(
@@ -712,17 +741,6 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
         );
       }
     }
-
-    validateProtocolUrlNormalized(this.message.descriptor.protocol);
-    if (this.message.descriptor.schema !== undefined) {
-      validateSchemaUrlNormalized(this.message.descriptor.schema);
-    }
-
-    Time.validateTimestamp(this.message.descriptor.messageTimestamp);
-    Time.validateTimestamp(this.message.descriptor.dateCreated);
-    if (this.message.descriptor.datePublished) {
-      Time.validateTimestamp(this.message.descriptor.datePublished);
-    }
   }
 
   /**

package/src/jose/jws/general/verifier.ts

@@ -24,7 +24,7 @@ export class GeneralJwsVerifier {
   cache: Cache;
 
   private constructor(cache?: Cache) {
-    this.cache = cache || new MemoryCache(600);
+    this.cache = cache ?? new MemoryCache(600);
   }
 
   private static get singleton(): GeneralJwsVerifier {

package/src/store/blockstore-mock.ts

@@ -17,9 +17,11 @@ import {
 export class BlockstoreMock implements Blockstore {
 
   async open(): Promise<void> {
+    // no-op: mock blockstore has no underlying storage to open
   }
 
   async close(): Promise<void> {
+    // no-op: mock blockstore has no underlying storage to close
   }
 
   async put(key: CID, _val: BlockstoreInput, _options?: BlockstoreAbortOptions): Promise<CID> {
@@ -62,5 +64,6 @@ export class BlockstoreMock implements Blockstore {
    * deletes all entries
    */
   async clear(): Promise<void> {
+    // no-op: mock blockstore has no underlying storage to clear
   }
 }

package/src/store/index-level-compound.ts

@@ -1,5 +1,5 @@
 import type { CompoundIndexDefinition, IndexedItem, IndexLevelOptions } from './index-level.js';
-import type { Filter, KeyValues, QueryOptions } from '../types/query-types.js';
+import type { Filter, KeyValues, PaginationCursor, QueryOptions } from '../types/query-types.js';
 import type { LevelWrapper, LevelWrapperBatchOperation, LevelWrapperIteratorOptions } from './level-wrapper.js';
 
 import { FilterUtility } from '../utils/filter.js';
@@ -8,6 +8,9 @@ import { SortDirection } from '../types/query-types.js';
 /** Separator between compound key segments (higher than \x00 so prefix scans work correctly). */
 export const COMPOUND_SEGMENT_SEPARATOR = '\x01';
 
+/** A value that can be encoded into a lexicographically sortable index key. */
+type IndexableValue = string | number | boolean;
+
 /**
  * Gets the compound index partition for a given compound index definition.
  * Compound index sublevels use the naming convention `__compound:<name>__`.
@@ -28,7 +31,7 @@ export async function getCompoundIndexPartition(
  */
 export function buildCompoundKey(
   messageCid: string, indexes: KeyValues, compoundIndex: CompoundIndexDefinition,
-  encodeValue: (value: string | number | boolean) => string, delimiter: string
+  encodeValue: (value: IndexableValue) => string, delimiter: string
 ): string | undefined {
   const segments: string[] = [];
 
@@ -198,6 +201,45 @@ export async function queryWithCompoundIndex(
   const partition = await getCompoundIndexPartition(db, tenant, compoundIndex);
 
   // determine the iterator bounds from the prefix
+  const iteratorOptions = buildCompoundQueryIteratorOptions(prefix, sortDirection, cursor, encodeValue, delimiter);
+
+  // determine which filter properties are NOT covered by the compound index
+  // (need in-memory verification for these)
+  // NOTE: the compound index equality properties are fully covered by the prefix scan,
+  // but the sort property is only covered for ordering — any range filter on the sort
+  // property must still be applied as a residual filter.
+  const { residualFilter, hasResidualFilter } = computeCompoundIndexResidualFilter(filter, compoundIndex);
+
+  const matches: IndexedItem[] = [];
+  for await (const [_key, value] of partition.iterator(iteratorOptions, options)) {
+    if (limit !== undefined && matches.length === limit) {
+      break;
+    }
+
+    const item = JSON.parse(value) as IndexedItem;
+
+    // verify any residual filter properties in memory
+    if (hasResidualFilter && !FilterUtility.matchFilter(item.indexes, residualFilter)) {
+      continue;
+    }
+
+    matches.push(item);
+  }
+
+  return matches;
+}
+
+/**
+ * Determines the LevelDB iterator bounds for a compound-index prefix scan, accounting for the
+ * sort direction and an optional pagination cursor.
+ */
+function buildCompoundQueryIteratorOptions(
+  prefix: string,
+  sortDirection: SortDirection,
+  cursor: PaginationCursor | undefined,
+  encodeValue: (value: IndexableValue) => string,
+  delimiter: string,
+): LevelWrapperIteratorOptions<string> {
   const iteratorOptions: LevelWrapperIteratorOptions<string> = {};
 
   if (cursor === undefined) {
@@ -226,11 +268,16 @@ export async function queryWithCompoundIndex(
     }
   }
 
-  // determine which filter properties are NOT covered by the compound index
-  // (need in-memory verification for these)
-  // NOTE: the compound index equality properties are fully covered by the prefix scan,
-  // but the sort property is only covered for ordering — any range filter on the sort
-  // property must still be applied as a residual filter.
+  return iteratorOptions;
+}
+
+/**
+ * Determines which filter properties are NOT covered by a compound index's equality-prefix scan
+ * and therefore require in-memory verification.
+ */
+function computeCompoundIndexResidualFilter(
+  filter: Filter, compoundIndex: CompoundIndexDefinition
+): { residualFilter: Filter; hasResidualFilter: boolean } {
   const coveredEqualityProperties = new Set(compoundIndex.properties);
   const residualFilter: Filter = {};
   let hasResidualFilter = false;
@@ -241,23 +288,7 @@ export async function queryWithCompoundIndex(
     }
   }
 
-  const matches: IndexedItem[] = [];
-  for await (const [_key, value] of partition.iterator(iteratorOptions, options)) {
-    if (limit !== undefined && matches.length === limit) {
-      break;
-    }
-
-    const item = JSON.parse(value) as IndexedItem;
-
-    // verify any residual filter properties in memory
-    if (hasResidualFilter && !FilterUtility.matchFilter(item.indexes, residualFilter)) {
-      continue;
-    }
-
-    matches.push(item);
-  }
-
-  return matches;
+  return { residualFilter, hasResidualFilter };
 }
 
 /**