@enbox/dwn-sdk-js 0.4.16 → 0.4.18

package/src/handlers/records-collection.ts

@@ -0,0 +1,269 @@
+import type { HandlerDependencies } from '../types/method-handler.js';
+import type { RecordsCount } from '../interfaces/records-count.js';
+import type { RecordsQuery } from '../interfaces/records-query.js';
+import type { RecordsSubscribe } from '../interfaces/records-subscribe.js';
+import type { Filter, PaginationCursor } from '../types/query-types.js';
+import type { RecordsFilter, RecordsQueryReplyEntry } from '../types/records-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { DateSort } from '../types/records-types.js';
+import { EncryptionControl } from '../core/encryption-control.js';
+import { Message } from '../core/message.js';
+import { ProtocolAuthorization } from '../core/protocol-authorization.js';
+import { Records } from '../utils/records.js';
+import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { queryRecordsWithRecordLimitOccupancy, resolveRecordLimitOccupancy } from '../utils/record-limit-occupancy.js';
+
+type RecordsCollectionRequest = RecordsCount | RecordsQuery | RecordsSubscribe;
+
+export type RecordsCollectionVisibility = 'nonOwner' | 'owner' | 'published';
+
+/**
+ * Resolves the visible population for a Records collection request, authenticating and
+ * authorizing every request that is not an anonymous published-records read.
+ */
+export async function resolveRecordsCollectionVisibility(
+  tenant: string,
+  request: RecordsCollectionRequest,
+  deps: HandlerDependencies,
+): Promise<RecordsCollectionVisibility> {
+  const recordsFilter = request.message.descriptor.filter;
+  if (Records.filterIncludesPublishedRecords(recordsFilter) && request.author === undefined) {
+    return 'published';
+  }
+
+  await authenticate(request.message.authorization!, deps.didResolver);
+
+  if (Message.isSignedByAuthorDelegate(request.message) && !EncryptionControl.filterTargetsOnlyControlRecords(recordsFilter)) {
+    await request.authorizeDelegate(deps.validationStateReader);
+  } else if (EncryptionControl.filterTargetsOnlyControlRecords(recordsFilter)) {
+    await EncryptionControl.authorizeControlReadRequest({
+      tenant,
+      incomingMessage       : request.message,
+      requester             : Message.getRequester(request.message),
+      validationStateReader : deps.validationStateReader,
+    });
+  }
+
+  const permissionGrantId = Message.getPermissionGrantId(request.signaturePayload!);
+  if (permissionGrantId !== undefined) {
+    const permissionGrant = await deps.validationStateReader.fetchGrant(tenant, permissionGrantId);
+    await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
+      incomingMessage       : request.message,
+      expectedGrantor       : tenant,
+      expectedGrantee       : request.author!,
+      permissionGrant,
+      validationStateReader : deps.validationStateReader,
+    });
+  } else if (invokesProtocolRole(request)) {
+    // A protocol filter alone does not require protocol authorization because unauthorized
+    // records are removed by the visibility filters. An invoked protocol role does.
+    await ProtocolAuthorization.authorizeQueryOrSubscribe(tenant, request, deps.validationStateReader);
+  }
+
+  return request.author === tenant ? 'owner' : 'nonOwner';
+}
+
+/** Builds latest-write filters shared by Records Query, Count, and Subscribe snapshots. */
+export function buildRecordsSnapshotFilters(
+  request: RecordsCollectionRequest,
+  visibility: RecordsCollectionVisibility,
+): Filter[] {
+  const descriptor = request.message.descriptor;
+  const dateSort = 'dateSort' in descriptor ? descriptor.dateSort : undefined;
+  return buildRecordsVisibilityFilters({
+    request,
+    visibility,
+    filter  : descriptor.filter,
+    purpose : 'snapshot',
+    dateSort,
+  });
+}
+
+/** Builds Write-and-Delete filters for Records Subscribe event delivery. */
+export function buildRecordsEventFilters(
+  request: RecordsSubscribe,
+  visibility: RecordsCollectionVisibility,
+): Filter[] {
+  return buildRecordsVisibilityFilters({
+    request,
+    visibility,
+    filter  : request.message.descriptor.filter,
+    purpose : 'event',
+  });
+}
+
+/**
+ * Queries one visible Records page after applying record-limit occupancy, current-audience
+ * projection, and encryption-control authorization in their required order.
+ */
+export async function queryVisibleRecordsPage(input: {
+  deps: HandlerDependencies;
+  request: RecordsQuery | RecordsSubscribe;
+  tenant: string;
+  visibility: RecordsCollectionVisibility;
+}): Promise<{ messages: RecordsQueryReplyEntry[]; cursor?: PaginationCursor }> {
+  const { deps, request, tenant, visibility } = input;
+  const { dateSort, filter, messageTimestamp, pagination } = request.message.descriptor;
+  const filters = buildRecordsSnapshotFilters(request, visibility);
+  const recordLimit = await resolveRecordLimitOccupancy({
+    validationStateReader : deps.validationStateReader,
+    tenant,
+    recordsFilter         : filter,
+    messageTimestamp,
+  });
+  const controlFilters = Records.buildControlRecordsFilters(filters);
+  const currentAudienceRecordIdCache = new Map<string, string | undefined>();
+  const requester = Message.getRequester(request.message);
+  const messageSort = Records.convertDateSort(dateSort ?? DateSort.CreatedAscending);
+
+  const queryProjectedPage = async (page = pagination): Promise<{
+    messages: RecordsQueryReplyEntry[];
+    cursor?: PaginationCursor;
+  }> => {
+    const result = await queryRecordsWithRecordLimitOccupancy({
+      messageStore : deps.messageStore,
+      tenant,
+      filters,
+      recordLimit,
+      messageSort,
+      pagination   : page,
+    });
+    return EncryptionControl.projectCurrentAudienceRecordPage({
+      messageStore: deps.messageStore,
+      tenant,
+      filters,
+      currentAudienceRecordIdCache,
+      result,
+    });
+  };
+
+  const filterVisibleControlRecords = (messages: RecordsQueryReplyEntry[]): Promise<RecordsQueryReplyEntry[]> =>
+    EncryptionControl.filterVisibleControlRecords({
+      tenant,
+      incomingMessage       : request.message,
+      requester,
+      recordsWriteMessages  : messages,
+      validationStateReader : deps.validationStateReader,
+    });
+
+  if (controlFilters.length === 0) {
+    return queryProjectedPage();
+  }
+
+  if (pagination?.limit === undefined || pagination.limit <= 0) {
+    const result = await queryProjectedPage();
+    return {
+      messages : await filterVisibleControlRecords(result.messages),
+      cursor   : result.cursor,
+    };
+  }
+
+  const visibleMessages: RecordsQueryReplyEntry[] = [];
+  let cursor = pagination.cursor;
+  let nextCursor: PaginationCursor | undefined;
+  // Keeps visible-page pagination stable until #1100 moves control visibility into indexed store filters.
+  do {
+    const remainingLimit = pagination.limit - visibleMessages.length;
+    const result = await queryProjectedPage({ ...pagination, cursor, limit: remainingLimit });
+    visibleMessages.push(...await filterVisibleControlRecords(result.messages));
+    nextCursor = result.cursor;
+    cursor = result.cursor;
+  } while (visibleMessages.length < pagination.limit && cursor !== undefined);
+
+  return { messages: visibleMessages, cursor: nextCursor };
+}
+
+function buildRecordsVisibilityFilters(input: {
+  dateSort?: DateSort;
+  filter: RecordsFilter;
+  purpose: 'event' | 'snapshot';
+  request: RecordsCollectionRequest;
+  visibility: RecordsCollectionVisibility;
+}): Filter[] {
+  const { dateSort, filter, purpose, request, visibility } = input;
+  if (visibility === 'owner') {
+    return [buildRecordsFilter({ dateSort, filter, purpose })];
+  }
+
+  if (visibility === 'published') {
+    return [buildRecordsFilter({ dateSort, filter, purpose, published: true })];
+  }
+
+  const filters: Filter[] = [];
+  if (Records.filterIncludesPublishedRecords(filter)) {
+    filters.push(buildRecordsFilter({ dateSort, filter, purpose, published: true }));
+  }
+
+  if (!Records.filterIncludesUnpublishedRecords(filter)) {
+    return filters;
+  }
+
+  if (EncryptionControl.isExactAudienceFilter(filter)) {
+    filters.push(buildRecordsFilter({ dateSort, filter, purpose, published: false }));
+  }
+
+  if (shouldBuildUnpublishedAuthorFilter(filter, request.author!)) {
+    filters.push(buildRecordsFilter({ author: request.author, dateSort, filter, purpose, published: false }));
+  }
+
+  if (invokesProtocolRole(request) || Message.getPermissionGrantId(request.signaturePayload!) !== undefined) {
+    filters.push(buildRecordsFilter({ dateSort, filter, purpose, published: false }));
+  }
+
+  if (shouldBuildUnpublishedRecipientFilter(filter, request.author!)) {
+    filters.push(buildRecordsFilter({ dateSort, filter, purpose, published: false, recipient: request.author }));
+  }
+
+  return filters;
+}
+
+function buildRecordsFilter(input: {
+  author?: string;
+  dateSort?: DateSort;
+  filter: RecordsFilter;
+  purpose: 'event' | 'snapshot';
+  published?: boolean;
+  recipient?: string;
+}): Filter {
+  const { author, dateSort, filter, purpose, published, recipient } = input;
+  const result: Filter = {
+    ...Records.convertFilter(filter, purpose === 'snapshot' ? dateSort : undefined),
+    interface : DwnInterfaceName.Records,
+    method    : purpose === 'snapshot' ? DwnMethodName.Write : [DwnMethodName.Write, DwnMethodName.Delete],
+  };
+
+  if (purpose === 'snapshot') {
+    result.isLatestBaseState = true;
+  }
+  if (author !== undefined) {
+    result.author = author;
+  }
+  if (published !== undefined) {
+    result.published = published;
+  }
+  if (recipient !== undefined) {
+    result.recipient = recipient;
+  }
+
+  return result;
+}
+
+function invokesProtocolRole(request: RecordsCollectionRequest): boolean {
+  return request.signaturePayload?.protocolRole !== undefined;
+}
+
+function shouldBuildUnpublishedRecipientFilter(filter: RecordsFilter, recipient: string): boolean {
+  const { recipient: recipientFilter } = filter;
+  return Array.isArray(recipientFilter)
+    ? recipientFilter.length === 0 || recipientFilter.includes(recipient)
+    : recipientFilter === undefined || recipientFilter === recipient;
+}
+
+function shouldBuildUnpublishedAuthorFilter(filter: RecordsFilter, author: string): boolean {
+  const { author: authorFilter } = filter;
+  return Array.isArray(authorFilter)
+    ? authorFilter.length === 0 || authorFilter.includes(author)
+    : authorFilter === undefined || authorFilter === author;
+}

package/src/handlers/records-count.ts

@@ -1,17 +1,20 @@
 import type { Filter } from '../types/query-types.js';
+import type { RecordLimitOccupancy } from '../types/message-store.js';
+import type { RecordsCollectionVisibility } from './records-collection.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { RecordsCountMessage, RecordsCountReply } from '../types/records-types.js';
 
-import { authenticate } from '../core/auth.js';
 import { EncryptionControl } from '../core/encryption-control.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
-import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { Records } from '../utils/records.js';
 import { RecordsCount } from '../interfaces/records-count.js';
-import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
-import { countRecordsWithRecordLimitOccupancy, queryRecordsWithRecordLimitOccupancy } from '../utils/record-limit-occupancy.js';
-import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { buildRecordsSnapshotFilters, resolveRecordsCollectionVisibility } from './records-collection.js';
+import {
+  countRecordsWithRecordLimitOccupancy,
+  queryRecordsWithRecordLimitOccupancy,
+  resolveRecordLimitOccupancy,
+} from '../utils/record-limit-occupancy.js';
 
 export class RecordsCountHandler implements MethodHandler {
 
@@ -24,34 +27,29 @@ export class RecordsCountHandler implements MethodHandler {
     let recordsCount: RecordsCount;
     try {
       recordsCount = await RecordsCount.parse(message);
-    } catch (e) {
-      return messageReplyFromError(e, 400);
+    } catch (error) {
+      return messageReplyFromError(error, 400);
     }
 
-    let count: number;
     const requester = Message.getRequester(recordsCount.message);
+    let visibility: RecordsCollectionVisibility;
+    try {
+      visibility = await resolveRecordsCollectionVisibility(tenant, recordsCount, this.deps);
+    } catch (error) {
+      return messageReplyFromError(error, 401);
+    }
 
-    // if this is an anonymous count and the filter supports published records, count only published records
-    if (Records.filterIncludesPublishedRecords(recordsCount.message.descriptor.filter) && recordsCount.author === undefined) {
-      count = await this.countPublishedRecords(tenant, recordsCount, requester);
-    } else {
-      // authentication and authorization
-      try {
-        await authenticate(message.authorization!, this.deps.didResolver);
-
-        await RecordsCountHandler.authorizeRecordsCount(tenant, recordsCount, this.deps);
-      } catch (e) {
-        return messageReplyFromError(e, 401);
-      }
+    const filters = buildRecordsSnapshotFilters(recordsCount, visibility);
+    const recordLimit = await resolveRecordLimitOccupancy({
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      recordsFilter         : recordsCount.message.descriptor.filter,
+      messageTimestamp      : recordsCount.message.descriptor.messageTimestamp,
+    });
 
-      if (recordsCount.author === tenant && requester === tenant) {
-        count = await this.countRecordsAsOwner(tenant, recordsCount);
-      } else if (recordsCount.author === tenant) {
-        count = await this.countRecordsAsOwnerDelegate(tenant, recordsCount, requester);
-      } else {
-        count = await this.countRecordsAsNonOwner(tenant, recordsCount, requester);
-      }
-    }
+    const count = recordsCount.author === tenant && requester === tenant
+      ? await this.countProjectedRecords(tenant, filters, recordLimit)
+      : await this.countProjectedRecordsForRequester(tenant, recordsCount, requester, filters, recordLimit);
 
     return {
       status: { code: 200, detail: 'OK' },
@@ -59,96 +57,16 @@ export class RecordsCountHandler implements MethodHandler {
     };
   }
 
-  /**
-   * Counts records as the owner of the DWN with no additional filtering.
-   */
-  private async countRecordsAsOwner(tenant: string, recordsCount: RecordsCount): Promise<number> {
-    const { filter } = recordsCount.message.descriptor;
-    const countFilter = {
-      ...Records.convertFilter(filter),
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      isLatestBaseState : true
-    };
-
-    return this.countProjectedRecords(tenant, recordsCount, [countFilter]);
-  }
-
-  private async countRecordsAsOwnerDelegate(
-    tenant: string,
-    recordsCount: RecordsCount,
-    requester: string | undefined,
-  ): Promise<number> {
-    const { filter } = recordsCount.message.descriptor;
-    const countFilter = {
-      ...Records.convertFilter(filter),
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      isLatestBaseState : true
-    };
-
-    return this.countProjectedRecordsForRequester(tenant, recordsCount, requester, [countFilter]);
-  }
-
-  /**
-   * Counts records as a non-owner, applying the same filter logic as RecordsQuery.
-   */
-  private async countRecordsAsNonOwner(
+  private async countProjectedRecords(
     tenant: string,
-    recordsCount: RecordsCount,
-    requester: string | undefined,
-  ): Promise<number> {
-    const { filter } = recordsCount.message.descriptor;
-    const filters: Filter[] = [];
-
-    if (Records.filterIncludesPublishedRecords(filter)) {
-      filters.push(RecordsCountHandler.buildPublishedRecordsFilter(recordsCount));
-    }
-
-    if (Records.filterIncludesUnpublishedRecords(filter)) {
-      if (EncryptionControl.isExactAudienceFilter(filter)) {
-        filters.push(Records.buildUnpublishedControlRecordsFilter(filter));
-      }
-
-      if (Records.shouldBuildUnpublishedAuthorFilter(filter, recordsCount.author!)) {
-        filters.push(RecordsCountHandler.buildUnpublishedRecordsByCountAuthorFilter(recordsCount));
-      }
-
-      if (Records.shouldProtocolAuthorize(recordsCount.signaturePayload!)) {
-        filters.push(RecordsCountHandler.buildUnpublishedProtocolAuthorizedRecordsFilter(recordsCount));
-      }
-
-      if (Message.getPermissionGrantId(recordsCount.signaturePayload!) !== undefined) {
-        filters.push(RecordsCountHandler.buildUnpublishedPermissionGrantAuthorizedRecordsFilter(recordsCount));
-      }
-
-      if (Records.shouldBuildUnpublishedRecipientFilter(filter, recordsCount.author!)) {
-        filters.push(RecordsCountHandler.buildUnpublishedRecordsForCountAuthorFilter(recordsCount));
-      }
-    }
-
-    return this.countProjectedRecordsForRequester(tenant, recordsCount, requester, filters);
-  }
-
-  /**
-   * Counts only published records.
-   */
-  private async countPublishedRecords(
-    tenant: string,
-    recordsCount: RecordsCount,
-    requester: string | undefined,
+    filters: Filter[],
+    recordLimit: RecordLimitOccupancy | undefined,
   ): Promise<number> {
-    const filter = RecordsCountHandler.buildPublishedRecordsFilter(recordsCount);
-    return this.countProjectedRecordsForRequester(tenant, recordsCount, requester, [filter]);
-  }
-
-  private async countProjectedRecords(tenant: string, recordsCount: RecordsCount, filters: Filter[]): Promise<number> {
     const totalCount = await countRecordsWithRecordLimitOccupancy({
-      messageStore          : this.deps.messageStore,
-      validationStateReader : this.deps.validationStateReader,
+      messageStore: this.deps.messageStore,
       tenant,
       filters,
-      messageTimestamp      : recordsCount.message.descriptor.messageTimestamp,
+      recordLimit,
     });
 
     const audienceFilters = EncryptionControl.buildAudienceRecordFilters(filters);
@@ -177,24 +95,24 @@ export class RecordsCountHandler implements MethodHandler {
     recordsCount: RecordsCount,
     requester: string | undefined,
     filters: Filter[],
+    recordLimit: RecordLimitOccupancy | undefined,
   ): Promise<number> {
     const controlFilters = Records.buildControlRecordsFilters(filters);
     if (controlFilters.length === 0) {
-      return this.countProjectedRecords(tenant, recordsCount, filters);
+      return this.countProjectedRecords(tenant, filters, recordLimit);
     }
 
-    const totalCount = await this.countProjectedRecords(tenant, recordsCount, filters);
-    const controlCount = await this.countProjectedRecords(tenant, recordsCount, controlFilters);
+    const totalCount = await this.countProjectedRecords(tenant, filters, recordLimit);
+    const controlCount = await this.countProjectedRecords(tenant, controlFilters, recordLimit);
     if (controlCount === 0) {
       return totalCount;
     }
 
     const { messages } = await queryRecordsWithRecordLimitOccupancy({
-      messageStore          : this.deps.messageStore,
-      validationStateReader : this.deps.validationStateReader,
+      messageStore : this.deps.messageStore,
       tenant,
-      filters               : controlFilters,
-      messageTimestamp      : recordsCount.message.descriptor.messageTimestamp,
+      filters      : controlFilters,
+      recordLimit,
     });
     const projectedMessages = await EncryptionControl.projectCurrentAudienceRecords({
       messageStore         : this.deps.messageStore,
@@ -211,116 +129,4 @@ export class RecordsCountHandler implements MethodHandler {
     });
     return totalCount - controlCount + visibleMessages.length;
   }
-
-  private static buildPublishedRecordsFilter(recordsCount: RecordsCount): Filter {
-    const { filter } = recordsCount.message.descriptor;
-    return {
-      ...Records.convertFilter(filter),
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      published         : true,
-      isLatestBaseState : true
-    };
-  }
-
-  /**
-   * Creates a filter for unpublished records that are intended for the count author (where `recipient` is the author).
-   */
-  private static buildUnpublishedRecordsForCountAuthorFilter(recordsCount: RecordsCount): Filter {
-    const { filter } = recordsCount.message.descriptor;
-    return {
-      ...Records.convertFilter(filter),
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      recipient         : recordsCount.author!,
-      isLatestBaseState : true,
-      published         : false
-    };
-  }
-
-  /**
-   * Creates a filter for unpublished records that are within the specified protocol.
-   */
-  private static buildUnpublishedProtocolAuthorizedRecordsFilter(recordsCount: RecordsCount): Filter {
-    const { filter } = recordsCount.message.descriptor;
-    return {
-      ...Records.convertFilter(filter),
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      isLatestBaseState : true,
-      published         : false
-    };
-  }
-
-  /**
-   * Creates a filter for unpublished records authorized by a permission grant.
-   */
-  private static buildUnpublishedPermissionGrantAuthorizedRecordsFilter(recordsCount: RecordsCount): Filter {
-    const { filter } = recordsCount.message.descriptor;
-    return {
-      ...Records.convertFilter(filter),
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      isLatestBaseState : true,
-      published         : false
-    };
-  }
-
-  /**
-   * Creates a filter for only unpublished records where the author is the same as the count author.
-   */
-  private static buildUnpublishedRecordsByCountAuthorFilter(recordsCount: RecordsCount): Filter {
-    const { filter } = recordsCount.message.descriptor;
-    return {
-      ...Records.convertFilter(filter),
-      author            : recordsCount.author!,
-      interface         : DwnInterfaceName.Records,
-      method            : DwnMethodName.Write,
-      isLatestBaseState : true,
-      published         : false
-    };
-  }
-
-  /**
-   * @param messageStore Used to check if the grant has been revoked.
-   */
-  private static async authorizeRecordsCount(
-    tenant: string,
-    recordsCount: RecordsCount,
-    deps: HandlerDependencies,
-  ): Promise<void> {
-
-    if (Message.isSignedByAuthorDelegate(recordsCount.message) &&
-        !EncryptionControl.filterTargetsOnlyControlRecords(recordsCount.message.descriptor.filter)) {
-      await recordsCount.authorizeDelegate(deps.validationStateReader);
-    } else if (EncryptionControl.filterTargetsOnlyControlRecords(recordsCount.message.descriptor.filter)) {
-      await EncryptionControl.authorizeControlReadRequest({
-        tenant,
-        incomingMessage       : recordsCount.message,
-        requester             : Message.getRequester(recordsCount.message),
-        validationStateReader : deps.validationStateReader,
-      });
-    }
-
-    const permissionGrantId = Message.getPermissionGrantId(recordsCount.signaturePayload!);
-    if (permissionGrantId !== undefined) {
-      const permissionGrant = await deps.validationStateReader.fetchGrant(tenant, permissionGrantId);
-      await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
-        incomingMessage       : recordsCount.message,
-        expectedGrantor       : tenant,
-        expectedGrantee       : recordsCount.author!,
-        permissionGrant,
-        validationStateReader : deps.validationStateReader,
-      });
-      return;
-    }
-
-    // NOTE: not all RecordsCount messages require protocol authorization even if the filter includes protocol-related fields,
-    // this is because we dynamically filter out records that the caller is not authorized to see.
-    // Currently only run protocol authorization if message deliberately invokes a protocol role.
-    if (Records.shouldProtocolAuthorize(recordsCount.signaturePayload!)) {
-      await ProtocolAuthorization.authorizeQueryOrSubscribe(tenant, recordsCount, deps.validationStateReader);
-    }
-  }
-
 }