@enbox/dwn-sdk-js 0.4.0 → 0.4.1

package/src/handlers/records-delete.ts

@@ -1,19 +1,17 @@
-import type { CoreProtocolRegistry } from '../core/core-protocol.js';
 import type { GenericMessageReply } from '../types/message-types.js';
-import type { MessageStore } from '../types//message-store.js';
+import type { ProgressToken } from '../types/subscriptions.js';
 import type { RecordsDeleteMessage } from '../types/records-types.js';
+import type { RecordsWrite } from '../interfaces/records-write.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 
 import { authenticate } from '../core/auth.js';
 import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
-import { PermissionsProtocol } from '../protocols/permissions.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { Records } from '../utils/records.js';
 import { RecordsDelete } from '../interfaces/records-delete.js';
 import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
-import { RecordsWrite } from '../interfaces/records-write.js';
 import { ResumableTaskName } from '../core/resumable-task-manager.js';
 
 export class RecordsDeleteHandler implements MethodHandler {
@@ -22,8 +20,8 @@ export class RecordsDeleteHandler implements MethodHandler {
 
   public async handle({
     tenant,
-    message
-  }: { tenant: string, message: RecordsDeleteMessage}): Promise<GenericMessageReply> {
+    message,
+  }: { tenant: string, message: RecordsDeleteMessage }): Promise<GenericMessageReply> {
     let recordsDelete: RecordsDelete;
     try {
       recordsDelete = await RecordsDelete.parse(message);
@@ -48,15 +46,20 @@ export class RecordsDeleteHandler implements MethodHandler {
     // find which message is the newest, and if the incoming message is the newest
     const newestExistingMessage = await Message.getNewestMessage(existingMessages);
 
-    if (!Records.canPerformDeleteAgainstRecord(message, newestExistingMessage)) {
+    if (newestExistingMessage === undefined) {
       return {
         status: { code: 404, detail: 'Not Found' }
       };
     }
 
-    // if the incoming message is not the newest, return Conflict
-    const incomingDeleteIsNewest = await Message.isNewer(message, newestExistingMessage!);
-    if (!incomingDeleteIsNewest) {
+    // Tombstone lattice: an incoming tombstone displaces ANY RecordsWrite, even a newer one — the
+    // write handler already rejects writes-after-delete regardless of timestamp, so this is the
+    // only rule that makes both arrival orders reach the same terminal state. Among competing
+    // tombstones one canonical winner stands on every replica: a prune beats a plain delete
+    // regardless of timestamp (the cascade is a side effect that must run everywhere), and within
+    // the same class the newest (messageTimestamp, then CID) wins. A beaten delete is a Conflict
+    // no-op; replication classifies the 409 as Superseded.
+    if (await Records.isDeleteBeatenByExistingTombstone(message, newestExistingMessage)) {
       return {
         status: { code: 409, detail: 'Conflict' }
       };
@@ -67,26 +70,26 @@ export class RecordsDeleteHandler implements MethodHandler {
       // NOTE: We need a RecordsWrite (doesn't have to be initial) to access the immutable properties for delete processing,
       // but if the latest record state is a RecordsDelete (ie. when we are pruning a non-prune delete),
       // we'd need to use the initial write because RecordsDelete does not contain the immutable properties needed for processing.
-      const initialWrite = await RecordsWrite.fetchInitialRecordsWrite(this.deps.messageStore, tenant, message.descriptor.recordId);
+      const initialWrite = await this.deps.validationStateReader.fetchInitialRecordsWrite(tenant, message.descriptor.recordId);
 
-      await RecordsDeleteHandler.authorizeRecordsDelete(
+      await this.authorizeRecordsDelete(
         tenant,
         recordsDelete,
         initialWrite!,
-        this.deps.messageStore,
-        this.deps.coreProtocols,
       );
+
     } catch (e) {
       return messageReplyFromError(e, 401);
     }
 
-    await this.deps.resumableTaskManager!.run({
+    const taskResult = await this.deps.resumableTaskManager!.run<{ position?: ProgressToken }>({
       name : ResumableTaskName.RecordsDelete,
       data : { tenant, message }
     });
 
     const messageReply = {
-      status: { code: 202, detail: 'Accepted' }
+      status   : { code: 202, detail: 'Accepted' },
+      position : taskResult.position,
     };
     return messageReply;
   };
@@ -96,33 +99,32 @@ export class RecordsDeleteHandler implements MethodHandler {
    *
    * @param recordsWrite A RecordsWrite of the record to be deleted.
    */
-  private static async authorizeRecordsDelete(
+  private async authorizeRecordsDelete(
     tenant: string,
     recordsDelete: RecordsDelete,
     recordsWrite: RecordsWrite,
-    messageStore: MessageStore,
-    coreProtocols?: CoreProtocolRegistry,
   ): Promise<void> {
 
     if (Message.isSignedByAuthorDelegate(recordsDelete.message)) {
-      await recordsDelete.authorizeDelegate(recordsWrite.message, messageStore);
+      await recordsDelete.authorizeDelegate(recordsWrite.message, this.deps.validationStateReader);
     }
 
     if (recordsDelete.author === tenant) {
       return;
     } else if (recordsDelete.author !== undefined && Message.getPermissionGrantId(recordsDelete.signaturePayload!) !== undefined) {
       const permissionGrantId = Message.getPermissionGrantId(recordsDelete.signaturePayload!)!;
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
+      const permissionGrant = await this.deps.validationStateReader.fetchGrant(tenant, permissionGrantId);
       await RecordsGrantAuthorization.authorizeDelete({
-        recordsDeleteMessage : recordsDelete.message,
-        recordsWriteToDelete : recordsWrite.message,
-        expectedGrantor      : tenant,
-        expectedGrantee      : recordsDelete.author,
+        recordsDeleteMessage  : recordsDelete.message,
+        recordsWriteToDelete  : recordsWrite.message,
+        expectedGrantor       : tenant,
+        expectedGrantee       : recordsDelete.author,
         permissionGrant,
-        messageStore,
+        validationStateReader : this.deps.validationStateReader,
       });
     } else {
-      await ProtocolAuthorization.authorizeDelete(tenant, recordsDelete, recordsWrite, messageStore, coreProtocols);
+      await ProtocolAuthorization.authorizeDelete(tenant, recordsDelete, recordsWrite, this.deps.validationStateReader);
     }
   }
+
 };

package/src/handlers/records-query.ts

@@ -1,5 +1,3 @@
-import type { CoreProtocolRegistry } from '../core/core-protocol.js';
-import type { MessageStore } from '../types//message-store.js';
 import type { Filter, PaginationCursor } from '../types/query-types.js';
 import type { GenericMessage, MessageSort } from '../types/message-types.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
@@ -9,8 +7,8 @@ import { authenticate } from '../core/auth.js';
 import { DateSort } from '../types/records-types.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
-import { PermissionsProtocol } from '../protocols/permissions.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
+import { queryRecordsWithRecordLimitOccupancy } from '../utils/record-limit-occupancy.js';
 import { Records } from '../utils/records.js';
 import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
 import { RecordsQuery } from '../interfaces/records-query.js';
@@ -24,7 +22,7 @@ export class RecordsQueryHandler implements MethodHandler {
 
   public async handle({
     tenant,
-    message
+    message,
   }: {tenant: string, message: RecordsQueryMessage}): Promise<RecordsQueryReply> {
     let recordsQuery: RecordsQuery;
     try {
@@ -45,7 +43,7 @@ export class RecordsQueryHandler implements MethodHandler {
       try {
         await authenticate(message.authorization!, this.deps.didResolver);
 
-        await RecordsQueryHandler.authorizeRecordsQuery(tenant, recordsQuery, this.deps.messageStore, this.deps.coreProtocols);
+        await RecordsQueryHandler.authorizeRecordsQuery(tenant, recordsQuery, this.deps);
       } catch (e) {
         return messageReplyFromError(e, 401);
       }
@@ -124,7 +122,15 @@ export class RecordsQueryHandler implements MethodHandler {
     };
 
     const messageSort = this.convertDateSort(dateSort);
-    return this.deps.messageStore.query(tenant, [ queryFilter ], messageSort, pagination);
+    return queryRecordsWithRecordLimitOccupancy({
+      messageStore          : this.deps.messageStore,
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      filters               : [queryFilter],
+      messageSort,
+      pagination,
+      messageTimestamp      : recordsQuery.message.descriptor.messageTimestamp,
+    });
   }
 
   /**
@@ -174,7 +180,15 @@ export class RecordsQueryHandler implements MethodHandler {
     }
 
     const messageSort = this.convertDateSort(dateSort);
-    return this.deps.messageStore.query(tenant, filters, messageSort, pagination );
+    return queryRecordsWithRecordLimitOccupancy({
+      messageStore          : this.deps.messageStore,
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      filters,
+      messageSort,
+      pagination,
+      messageTimestamp      : recordsQuery.message.descriptor.messageTimestamp,
+    });
   }
 
   /**
@@ -186,7 +200,15 @@ export class RecordsQueryHandler implements MethodHandler {
     const { dateSort, pagination } = recordsQuery.message.descriptor;
     const filter = RecordsQueryHandler.buildPublishedRecordsFilter(recordsQuery);
     const messageSort = this.convertDateSort(dateSort);
-    return this.deps.messageStore.query(tenant, [ filter ], messageSort, pagination);
+    return queryRecordsWithRecordLimitOccupancy({
+      messageStore          : this.deps.messageStore,
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      filters               : [filter],
+      messageSort,
+      pagination,
+      messageTimestamp      : recordsQuery.message.descriptor.messageTimestamp,
+    });
   }
 
   private static buildPublishedRecordsFilter(recordsQuery: RecordsQuery): Filter {
@@ -268,23 +290,22 @@ export class RecordsQueryHandler implements MethodHandler {
   private static async authorizeRecordsQuery(
     tenant: string,
     recordsQuery: RecordsQuery,
-    messageStore: MessageStore,
-    coreProtocols?: CoreProtocolRegistry,
+    deps: HandlerDependencies,
   ): Promise<void> {
 
     if (Message.isSignedByAuthorDelegate(recordsQuery.message)) {
-      await recordsQuery.authorizeDelegate(messageStore);
+      await recordsQuery.authorizeDelegate(deps.validationStateReader);
     }
 
     const permissionGrantId = Message.getPermissionGrantId(recordsQuery.signaturePayload!);
     if (permissionGrantId !== undefined) {
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
+      const permissionGrant = await deps.validationStateReader.fetchGrant(tenant, permissionGrantId);
       await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
-        incomingMessage : recordsQuery.message,
-        expectedGrantor : tenant,
-        expectedGrantee : recordsQuery.author!,
+        incomingMessage       : recordsQuery.message,
+        expectedGrantor       : tenant,
+        expectedGrantee       : recordsQuery.author!,
         permissionGrant,
-        messageStore,
+        validationStateReader : deps.validationStateReader,
       });
       return;
     }
@@ -293,7 +314,7 @@ export class RecordsQueryHandler implements MethodHandler {
     // 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(recordsQuery.signaturePayload!)) {
-      await ProtocolAuthorization.authorizeQueryOrSubscribe(tenant, recordsQuery, messageStore, coreProtocols);
+      await ProtocolAuthorization.authorizeQueryOrSubscribe(tenant, recordsQuery, deps.validationStateReader);
     }
   }
 }

package/src/handlers/records-read.ts

@@ -1,15 +1,13 @@
-import type { CoreProtocolRegistry } from '../core/core-protocol.js';
 import type { Filter } from '../types/query-types.js';
-import type { MessageStore } from '../types//message-store.js';
 import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { RecordsDeleteMessage, RecordsQueryReplyEntry, RecordsReadMessage, RecordsReadReply } from '../types/records-types.js';
 
 import { authenticate } from '../core/auth.js';
 import { DataStream } from '../utils/data-stream.js';
 import { Encoder } from '../utils/encoder.js';
+import { isRecordLimitOccupant } from '../utils/record-limit-occupancy.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
-import { PermissionsProtocol } from '../protocols/permissions.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { Records } from '../utils/records.js';
 import { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
@@ -24,7 +22,7 @@ export class RecordsReadHandler implements MethodHandler {
 
   public async handle({
     tenant,
-    message
+    message,
   }: { tenant: string, message: RecordsReadMessage }): Promise<RecordsReadReply> {
 
     let recordsRead: RecordsRead;
@@ -51,7 +49,7 @@ export class RecordsReadHandler implements MethodHandler {
       ...Records.convertFilter(message.descriptor.filter)
     };
     const messageSort = Records.convertDateSort(message.descriptor.dateSort);
-    const { messages: existingMessages } = await this.deps.messageStore.query(tenant, [ query ], messageSort, { limit: 1 });
+    const { messages: existingMessages } = await this.deps.messageStore.query(tenant, [query], messageSort, { limit: 1 });
     if (existingMessages.length === 0) {
       return {
         status: { code: 404, detail: 'Not Found' }
@@ -60,55 +58,29 @@ export class RecordsReadHandler implements MethodHandler {
 
     const matchedMessage = existingMessages[0];
 
-    // If the matched message is a RecordsDelete, authorize against the newest RecordsWrite
-    // (for parity with the live-record path which authorizes against the latest write),
-    // then return 404 with both the RecordsDelete and the initial RecordsWrite.
     if (matchedMessage.descriptor.method === DwnMethodName.Delete) {
-      const recordsDeleteMessage = matchedMessage as RecordsDeleteMessage;
-      const recordId = recordsDeleteMessage.descriptor.recordId;
-
-      const initialWrite = await RecordsWrite.fetchInitialRecordsWriteMessage(this.deps.messageStore, tenant, recordId);
-      if (initialWrite === undefined) {
-        return messageReplyFromError(new DwnError(
-          DwnErrorCode.RecordsReadInitialWriteNotFound,
-          'initial write for deleted record not found'
-        ), 400);
-      }
-
-      // Authorize against the newest RecordsWrite so that mutable properties like `published`
-      // reflect the record's state at the time of deletion, not just the initial write.
-      let newestWrite;
-      try {
-        newestWrite = await RecordsWrite.fetchNewestRecordsWrite(this.deps.messageStore, tenant, recordId);
-      } catch {
-        // If newest write is not found (should not happen since initial write exists),
-        // fall back to the initial write for authorization.
-        newestWrite = initialWrite;
-      }
-      const parsedNewestWrite = await RecordsWrite.parse(newestWrite);
+      return this.replyForDeletedRecord(tenant, recordsRead, matchedMessage as RecordsDeleteMessage);
+    }
 
-      try {
-        await RecordsReadHandler.authorizeRecordsRead(tenant, recordsRead, parsedNewestWrite, this.deps.messageStore, this.deps.coreProtocols);
-      } catch (error) {
-        return messageReplyFromError(error, 401);
-      }
+    // else the matched message is a RecordsWrite
+    const matchedRecordsWrite = matchedMessage as RecordsQueryReplyEntry;
 
+    if (!await isRecordLimitOccupant({
+      messageStore          : this.deps.messageStore,
+      validationStateReader : this.deps.validationStateReader,
+      tenant,
+      message               : matchedRecordsWrite,
+      messageTimestamp      : recordsRead.message.descriptor.messageTimestamp,
+    })) {
       return {
-        status : { code: 404, detail: 'Not Found' },
-        entry  : {
-          recordsDelete: recordsDeleteMessage,
-          initialWrite,
-        }
+        status: { code: 404, detail: 'Not Found' }
       };
     }
 
-    // else the matched message is a RecordsWrite
-    const matchedRecordsWrite = matchedMessage as RecordsQueryReplyEntry;
-
     try {
       const parsedWrite = await RecordsWrite.parse(matchedRecordsWrite);
       await RecordsReadHandler.authorizeRecordsRead(
-        tenant, recordsRead, parsedWrite, this.deps.messageStore, this.deps.coreProtocols,
+        tenant, recordsRead, parsedWrite, this.deps,
       );
     } catch (error) {
       return messageReplyFromError(error, 401);
@@ -155,6 +127,48 @@ export class RecordsReadHandler implements MethodHandler {
     return recordsReadReply;
   };
 
+  private async replyForDeletedRecord(
+    tenant: string,
+    recordsRead: RecordsRead,
+    recordsDeleteMessage: RecordsDeleteMessage,
+  ): Promise<RecordsReadReply> {
+    const recordId = recordsDeleteMessage.descriptor.recordId;
+
+    const initialWrite = await RecordsWrite.fetchInitialRecordsWriteMessage(this.deps.messageStore, tenant, recordId);
+    if (initialWrite === undefined) {
+      return messageReplyFromError(new DwnError(
+        DwnErrorCode.RecordsReadInitialWriteNotFound,
+        'initial write for deleted record not found'
+      ), 400);
+    }
+
+    // Authorize against the newest RecordsWrite so that mutable properties like `published`
+    // reflect the record's state at the time of deletion, not just the initial write.
+    let newestWrite;
+    try {
+      newestWrite = await RecordsWrite.fetchNewestRecordsWrite(this.deps.messageStore, tenant, recordId);
+    } catch {
+      // If newest write is not found (should not happen since initial write exists),
+      // fall back to the initial write for authorization.
+      newestWrite = initialWrite;
+    }
+    const parsedNewestWrite = await RecordsWrite.parse(newestWrite);
+
+    try {
+      await RecordsReadHandler.authorizeRecordsRead(tenant, recordsRead, parsedNewestWrite, this.deps);
+    } catch (error) {
+      return messageReplyFromError(error, 401);
+    }
+
+    return {
+      status : { code: 404, detail: 'Not Found' },
+      entry  : {
+        recordsDelete: recordsDeleteMessage,
+        initialWrite,
+      }
+    };
+  }
+
   /**
    * @param messageStore Used to check if the grant has been revoked.
    */
@@ -162,11 +176,10 @@ export class RecordsReadHandler implements MethodHandler {
     tenant: string,
     recordsRead: RecordsRead,
     matchedRecordsWrite: RecordsWrite,
-    messageStore: MessageStore,
-    coreProtocols?: CoreProtocolRegistry,
+    deps: HandlerDependencies,
   ): Promise<void> {
     if (Message.isSignedByAuthorDelegate(recordsRead.message)) {
-      await recordsRead.authorizeDelegate(matchedRecordsWrite.message, messageStore);
+      await recordsRead.authorizeDelegate(matchedRecordsWrite.message, deps.validationStateReader);
     }
 
     const { descriptor } = matchedRecordsWrite.message;
@@ -184,17 +197,17 @@ export class RecordsReadHandler implements MethodHandler {
       return;
     } else if (recordsRead.author !== undefined && Message.getPermissionGrantId(recordsRead.signaturePayload!) !== undefined) {
       const permissionGrantId = Message.getPermissionGrantId(recordsRead.signaturePayload!)!;
-      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
+      const permissionGrant = await deps.validationStateReader.fetchGrant(tenant, permissionGrantId);
       await RecordsGrantAuthorization.authorizeRead({
         recordsReadMessage          : recordsRead.message,
         recordsWriteMessageToBeRead : matchedRecordsWrite.message,
         expectedGrantor             : tenant,
         expectedGrantee             : recordsRead.author,
         permissionGrant,
-        messageStore
+        validationStateReader       : deps.validationStateReader
       });
     } else {
-      await ProtocolAuthorization.authorizeRead(tenant, recordsRead, matchedRecordsWrite, messageStore, coreProtocols);
+      await ProtocolAuthorization.authorizeRead(tenant, recordsRead, matchedRecordsWrite, deps.validationStateReader);
     }
   }
 }