@enbox/dwn-sdk-js 0.0.1

package/src/handlers/protocols-configure.ts

@@ -0,0 +1,137 @@
+import type { DidResolver } from '@enbox/dids';
+import type { EventLog } from '../types/event-log.js';
+import type { EventStream } from '../types/subscriptions.js';
+import type { GenericMessageReply } from '../types/message-types.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { ProtocolsConfigureMessage } from '../types/protocols-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { Message } from '../core/message.js';
+import { messageReplyFromError } from '../core/message-reply.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { ProtocolsConfigure } from '../interfaces/protocols-configure.js';
+import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export class ProtocolsConfigureHandler implements MethodHandler {
+
+  constructor(
+    private didResolver: DidResolver,
+    private messageStore: MessageStore,
+    private eventLog: EventLog,
+    private eventStream?: EventStream
+  ) { }
+
+  public async handle({
+    tenant,
+    message,
+  }: {tenant: string, message: ProtocolsConfigureMessage }): Promise<GenericMessageReply> {
+    let protocolsConfigure: ProtocolsConfigure;
+    try {
+      protocolsConfigure = await ProtocolsConfigure.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    // authentication & authorization
+    try {
+      await authenticate(message.authorization, this.didResolver);
+      await ProtocolsConfigureHandler.authorizeProtocolsConfigure(tenant, protocolsConfigure, this.messageStore);
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    // attempt to get existing protocol
+    const query = {
+      interface : DwnInterfaceName.Protocols,
+      method    : DwnMethodName.Configure,
+      protocol  : message.descriptor.definition.protocol
+    };
+    const { messages: existingMessages } = await this.messageStore.query(tenant, [ query ]);
+
+    // find newest message, and if the incoming message is the newest
+    let newestMessage = await Message.getNewestMessage(existingMessages);
+    let incomingMessageIsNewest = false;
+    if (newestMessage === undefined || await Message.isNewer(message, newestMessage)) {
+      incomingMessageIsNewest = true;
+      newestMessage = message;
+    }
+
+    // write the incoming message to DB if incoming message is newest
+    let messageReply: GenericMessageReply;
+    if (incomingMessageIsNewest) {
+      const indexes = ProtocolsConfigureHandler.constructIndexes(protocolsConfigure);
+
+      await this.messageStore.put(tenant, message, indexes);
+      const messageCid = await Message.getCid(message);
+      await this.eventLog.append(tenant, messageCid, indexes);
+
+      // only emit if the event stream is set
+      if (this.eventStream !== undefined) {
+        this.eventStream.emit(tenant, { message }, indexes);
+      }
+
+      messageReply = {
+        status: { code: 202, detail: 'Accepted' }
+      };
+    } else {
+      messageReply = {
+        status: { code: 409, detail: 'Conflict' }
+      };
+    }
+
+    // delete all existing records that are smaller
+    const deletedMessageCids: string[] = [];
+    for (const message of existingMessages) {
+      if (await Message.isNewer(newestMessage, message)) {
+        const messageCid = await Message.getCid(message);
+        deletedMessageCids.push(messageCid);
+
+        await this.messageStore.delete(tenant, messageCid);
+      }
+    }
+
+    await this.eventLog.deleteEventsByCid(tenant, deletedMessageCids);
+
+    return messageReply;
+  };
+
+  static constructIndexes(protocolsConfigure: ProtocolsConfigure): { [key: string]: string | boolean } {
+    // strip out `definition` as it is not indexable
+    const { definition, ...propertiesToIndex } = protocolsConfigure.message.descriptor;
+    const { author } = protocolsConfigure;
+
+    const indexes: { [key: string]: string | boolean } = {
+      ...propertiesToIndex,
+      author    : author!,
+      protocol  : definition.protocol, // retain protocol url from `definition`,
+      published : definition.published // retain published state from definition
+    };
+
+    return indexes;
+  }
+
+  private static async authorizeProtocolsConfigure(tenant: string, protocolConfigure: ProtocolsConfigure, messageStore: MessageStore): Promise<void> {
+
+    if (protocolConfigure.isSignedByAuthorDelegate) {
+      await protocolConfigure.authorizeAuthorDelegate(messageStore);
+    }
+
+    if (protocolConfigure.author === tenant) {
+      return;
+    } else if (protocolConfigure.author !== undefined && protocolConfigure.signaturePayload!.permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, protocolConfigure.signaturePayload!.permissionGrantId);
+      await ProtocolsGrantAuthorization.authorizeConfigure({
+        protocolsConfigureMessage : protocolConfigure.message,
+        expectedGrantor           : tenant,
+        expectedGrantee           : protocolConfigure.author,
+        permissionGrant,
+        messageStore
+      });
+    } else {
+      throw new DwnError(DwnErrorCode.ProtocolsConfigureAuthorizationFailed, 'message failed authorization');
+    }
+  }
+}

package/src/handlers/protocols-query.ts

@@ -0,0 +1,82 @@
+import type { DataStore } from '../types/data-store.js';
+import type { DidResolver } from '@enbox/dids';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply } from '../types/protocols-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { DwnErrorCode } from '../core/dwn-error.js';
+import { messageReplyFromError } from '../core/message-reply.js';
+import { ProtocolsQuery } from '../interfaces/protocols-query.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export class ProtocolsQueryHandler implements MethodHandler {
+
+  constructor(private didResolver: DidResolver, private messageStore: MessageStore,private dataStore: DataStore) { }
+
+  public async handle({
+    tenant,
+    message
+  }: { tenant: string, message: ProtocolsQueryMessage}): Promise<ProtocolsQueryReply> {
+
+    let protocolsQuery: ProtocolsQuery;
+    try {
+      protocolsQuery = await ProtocolsQuery.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    // authentication & authorization
+    try {
+      await authenticate(message.authorization, this.didResolver);
+      await protocolsQuery.authorize(tenant, this.messageStore);
+    } catch (error: any) {
+
+      // return public ProtocolsConfigures if query fails with a certain authentication or authorization code
+      if (error.code === DwnErrorCode.AuthenticateJwsMissing || // unauthenticated
+        error.code === DwnErrorCode.ProtocolsQueryUnauthorized ||
+        error.code === DwnErrorCode.ProtocolsGrantAuthorizationQueryProtocolScopeMismatch
+      ) {
+
+        const entries: ProtocolsConfigureMessage[] = await this.fetchPublishedProtocolsConfigure(tenant, protocolsQuery);
+        return {
+          status: { code: 200, detail: 'OK' },
+          entries
+        };
+      } else {
+        return messageReplyFromError(error, 401);
+      }
+    }
+
+    const query = {
+      ...message.descriptor.filter,
+      interface : DwnInterfaceName.Protocols,
+      method    : DwnMethodName.Configure
+    };
+    removeUndefinedProperties(query);
+
+    const { messages } = await this.messageStore.query(tenant, [ query ]);
+
+    return {
+      status  : { code: 200, detail: 'OK' },
+      entries : messages as ProtocolsConfigureMessage[]
+    };
+  };
+
+  /**
+   * Fetches only published `ProtocolsConfigure`.
+   */
+  private async fetchPublishedProtocolsConfigure(tenant: string, protocolsQuery: ProtocolsQuery): Promise<ProtocolsConfigureMessage[]> {
+    // fetch all published `ProtocolConfigure` matching the query
+    const filter = {
+      ...protocolsQuery.message.descriptor.filter,
+      interface : DwnInterfaceName.Protocols,
+      method    : DwnMethodName.Configure,
+      published : true
+    };
+    const { messages: publishedProtocolsConfigure } = await this.messageStore.query(tenant, [ filter ]);
+    return publishedProtocolsConfigure as ProtocolsConfigureMessage[];
+  }
+}

package/src/handlers/records-delete.ts

@@ -0,0 +1,124 @@
+import type { DidResolver } from '@enbox/dids';
+import type { GenericMessageReply } from '../types/message-types.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { RecordsDeleteMessage } from '../types/records-types.js';
+import type { ResumableTaskManager } from '../core/resumable-task-manager.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 { ProtocolAuthorization } from '../core/protocol-authorization.js';
+import { Records } from '../utils/records.js';
+import { RecordsDelete } from '../interfaces/records-delete.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { ResumableTaskName } from '../core/resumable-task-manager.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+export class RecordsDeleteHandler implements MethodHandler {
+
+  constructor(
+    private didResolver: DidResolver,
+    private messageStore: MessageStore,
+    private resumableTaskManager: ResumableTaskManager,
+  ) { }
+
+  public async handle({
+    tenant,
+    message
+  }: { tenant: string, message: RecordsDeleteMessage}): Promise<GenericMessageReply> {
+    let recordsDelete: RecordsDelete;
+    try {
+      recordsDelete = await RecordsDelete.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    // authentication
+    try {
+      await authenticate(message.authorization, this.didResolver);
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    // get existing records matching the `recordId`
+    const query = {
+      interface : DwnInterfaceName.Records,
+      recordId  : message.descriptor.recordId
+    };
+    const { messages: existingMessages } = await this.messageStore.query(tenant, [ query ]);
+
+    // 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)) {
+      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) {
+      return {
+        status: { code: 409, detail: 'Conflict' }
+      };
+    }
+
+    // authorization
+    try {
+      // 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.messageStore, tenant, message.descriptor.recordId);
+
+      await RecordsDeleteHandler.authorizeRecordsDelete(
+        tenant,
+        recordsDelete,
+        initialWrite!,
+        this.messageStore
+      );
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    await this.resumableTaskManager.run({
+      name : ResumableTaskName.RecordsDelete,
+      data : { tenant, message }
+    });
+
+    const messageReply = {
+      status: { code: 202, detail: 'Accepted' }
+    };
+    return messageReply;
+  };
+
+  /**
+   * Authorizes a RecordsDelete message.
+   *
+   * @param recordsWrite A RecordsWrite of the record to be deleted.
+   */
+  private static async authorizeRecordsDelete(
+    tenant: string,
+    recordsDelete: RecordsDelete,
+    recordsWrite: RecordsWrite,
+    messageStore: MessageStore
+  ): Promise<void> {
+
+    if (Message.isSignedByAuthorDelegate(recordsDelete.message)) {
+      await recordsDelete.authorizeDelegate(recordsWrite.message, messageStore);
+    }
+
+    if (recordsDelete.author === tenant) {
+      return;
+    } else if (recordsWrite.message.descriptor.protocol !== undefined) {
+      await ProtocolAuthorization.authorizeDelete(tenant, recordsDelete, recordsWrite, messageStore);
+    } else {
+      throw new DwnError(
+        DwnErrorCode.RecordsDeleteAuthorizationFailed,
+        'RecordsDelete message failed authorization'
+      );
+    }
+  }
+};

package/src/handlers/records-query.ts

@@ -0,0 +1,262 @@
+import type { DataStore } from '../types/data-store.js';
+import type { DidResolver } from '@enbox/dids';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { Filter, PaginationCursor } from '../types/query-types.js';
+import type { GenericMessage, MessageSort } from '../types/message-types.js';
+import type { RecordsQueryMessage, RecordsQueryReply, RecordsQueryReplyEntry } from '../types/records-types.js';
+
+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 { ProtocolAuthorization } from '../core/protocol-authorization.js';
+import { Records } from '../utils/records.js';
+import { RecordsQuery } from '../interfaces/records-query.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { SortDirection } from '../types/query-types.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export class RecordsQueryHandler implements MethodHandler {
+
+  constructor(private didResolver: DidResolver, private messageStore: MessageStore, private dataStore: DataStore) { }
+
+  public async handle({
+    tenant,
+    message
+  }: {tenant: string, message: RecordsQueryMessage}): Promise<RecordsQueryReply> {
+    let recordsQuery: RecordsQuery;
+    try {
+      recordsQuery = await RecordsQuery.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    let recordsWrites: RecordsQueryReplyEntry[];
+    let cursor: PaginationCursor | undefined;
+    // if this is an anonymous query and the filter supports published records, query only published records
+    if (Records.filterIncludesPublishedRecords(recordsQuery.message.descriptor.filter) && recordsQuery.author === undefined) {
+      const results = await this.fetchPublishedRecords(tenant, recordsQuery);
+      recordsWrites = results.messages as RecordsQueryReplyEntry[];
+      cursor = results.cursor;
+    } else {
+      // authentication and authorization
+      try {
+        await authenticate(message.authorization!, this.didResolver);
+
+        await RecordsQueryHandler.authorizeRecordsQuery(tenant, recordsQuery, this.messageStore);
+      } catch (e) {
+        return messageReplyFromError(e, 401);
+      }
+
+      if (recordsQuery.author === tenant) {
+        const results = await this.fetchRecordsAsOwner(tenant, recordsQuery);
+        recordsWrites = results.messages as RecordsQueryReplyEntry[];
+        cursor = results.cursor;
+      } else {
+        const results = await this.fetchRecordsAsNonOwner(tenant, recordsQuery);
+        recordsWrites = results.messages as RecordsQueryReplyEntry[];
+        cursor = results.cursor;
+      }
+    }
+
+    // attach initial write if returned RecordsWrite is not initial write
+    for (const recordsWrite of recordsWrites) {
+      if (!await RecordsWrite.isInitialWrite(recordsWrite)) {
+        const initialWriteQueryResult = await this.messageStore.query(
+          tenant,
+          [{ recordId: recordsWrite.recordId, isLatestBaseState: false, method: DwnMethodName.Write }]
+        );
+        const initialWrite = initialWriteQueryResult.messages[0] as RecordsQueryReplyEntry;
+        delete initialWrite.encodedData; // defensive measure but technically optional because we do this when an update RecordsWrite takes place
+        recordsWrite.initialWrite = initialWrite;
+      }
+    }
+
+    return {
+      status  : { code: 200, detail: 'OK' },
+      entries : recordsWrites,
+      cursor
+    };
+  }
+
+  /**
+   * Convert an incoming DateSort to a sort type accepted by MessageStore
+   * Defaults to 'dateCreated' in Descending order if no sort is supplied.
+   *
+   * @param dateSort the optional DateSort from the RecordsQuery message descriptor.
+   * @returns {MessageSort} for MessageStore sorting.
+   */
+  private convertDateSort(dateSort?: DateSort): MessageSort {
+    switch (dateSort) {
+    case DateSort.CreatedAscending:
+      return { dateCreated: SortDirection.Ascending };
+    case DateSort.CreatedDescending:
+      return { dateCreated: SortDirection.Descending };
+    case DateSort.PublishedAscending:
+      return { datePublished: SortDirection.Ascending };
+    case DateSort.PublishedDescending:
+      return { datePublished: SortDirection.Descending };
+    default:
+      return { dateCreated: SortDirection.Ascending };
+    }
+  }
+
+  /**
+   * Fetches the records as the owner of the DWN with no additional filtering.
+   */
+  private async fetchRecordsAsOwner(
+    tenant: string,
+    recordsQuery: RecordsQuery
+  ): Promise<{ messages: GenericMessage[], cursor?: PaginationCursor }> {
+    const { dateSort, filter, pagination } = recordsQuery.message.descriptor;
+    // fetch all published records matching the query
+    const queryFilter = {
+      ...Records.convertFilter(filter, dateSort),
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      isLatestBaseState : true
+    };
+
+    const messageSort = this.convertDateSort(dateSort);
+    return this.messageStore.query(tenant, [ queryFilter ], messageSort, pagination);
+  }
+
+  /**
+   * Fetches the records as a non-owner.
+   *
+   * Filters can support returning both published and unpublished records,
+   * as well as explicitly only published or only unpublished records.
+   *
+   * A) BOTH published and unpublished:
+   *    1. published records; and
+   *    2. unpublished records intended for the query author (where `recipient` is the query author); and
+   *    3. unpublished records authorized by a protocol rule.
+   *
+   * B) PUBLISHED:
+   *    1. only published records;
+   *
+   * C) UNPUBLISHED:
+   *    1. unpublished records intended for the query author (where `recipient` is the query author); and
+   *    2. unpublished records authorized by a protocol rule.
+   *
+   */
+  private async fetchRecordsAsNonOwner(
+    tenant: string, recordsQuery: RecordsQuery
+  ): Promise<{ messages: GenericMessage[], cursor?: PaginationCursor }> {
+    const { dateSort, pagination, filter } = recordsQuery.message.descriptor;
+    const filters = [];
+    if (Records.filterIncludesPublishedRecords(filter)) {
+      filters.push(RecordsQueryHandler.buildPublishedRecordsFilter(recordsQuery));
+    }
+
+    if (Records.filterIncludesUnpublishedRecords(filter)) {
+      if (Records.shouldBuildUnpublishedAuthorFilter(filter, recordsQuery.author!)) {
+        filters.push(RecordsQueryHandler.buildUnpublishedRecordsByQueryAuthorFilter(recordsQuery));
+      }
+
+      if (Records.shouldProtocolAuthorize(recordsQuery.signaturePayload!)) {
+        filters.push(RecordsQueryHandler.buildUnpublishedProtocolAuthorizedRecordsFilter(recordsQuery));
+      }
+
+      if (Records.shouldBuildUnpublishedRecipientFilter(filter, recordsQuery.author!)) {
+        filters.push(RecordsQueryHandler.buildUnpublishedRecordsForQueryAuthorFilter(recordsQuery));
+      }
+    }
+
+    const messageSort = this.convertDateSort(dateSort);
+    return this.messageStore.query(tenant, filters, messageSort, pagination );
+  }
+
+  /**
+   * Fetches only published records.
+   */
+  private async fetchPublishedRecords(
+    tenant: string, recordsQuery: RecordsQuery
+  ): Promise<{ messages: GenericMessage[], cursor?: PaginationCursor }> {
+    const { dateSort, pagination } = recordsQuery.message.descriptor;
+    const filter = RecordsQueryHandler.buildPublishedRecordsFilter(recordsQuery);
+    const messageSort = this.convertDateSort(dateSort);
+    return this.messageStore.query(tenant, [ filter ], messageSort, pagination);
+  }
+
+  private static buildPublishedRecordsFilter(recordsQuery: RecordsQuery): Filter {
+    const { dateSort, filter } = recordsQuery.message.descriptor;
+    // fetch all published records matching the query
+    return {
+      ...Records.convertFilter(filter, dateSort),
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      published         : true,
+      isLatestBaseState : true
+    };
+  }
+
+  /**
+   * Creates a filter for unpublished records that are intended for the query author (where `recipient` is the author).
+   */
+  private static buildUnpublishedRecordsForQueryAuthorFilter(recordsQuery: RecordsQuery): Filter {
+    const { dateSort, filter } = recordsQuery.message.descriptor;
+    // include records where recipient is query author
+    return {
+      ...Records.convertFilter(filter, dateSort),
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      recipient         : recordsQuery.author!,
+      isLatestBaseState : true,
+      published         : false
+    };
+  }
+
+  /**
+   * Creates a filter for unpublished records that are within the specified protocol.
+   * Validation that `protocol` and other required protocol-related fields occurs before this method.
+   */
+  private static buildUnpublishedProtocolAuthorizedRecordsFilter(recordsQuery: RecordsQuery): Filter {
+    const { dateSort, filter } = recordsQuery.message.descriptor;
+    return {
+      ...Records.convertFilter(filter, dateSort),
+      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 query author.
+   */
+  private static buildUnpublishedRecordsByQueryAuthorFilter(recordsQuery: RecordsQuery): Filter {
+    const { dateSort, filter } = recordsQuery.message.descriptor;
+    // include records where author is the same as the query author
+    return {
+      ...Records.convertFilter(filter, dateSort),
+      author            : recordsQuery.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 authorizeRecordsQuery(
+    tenant: string,
+    recordsQuery: RecordsQuery,
+    messageStore: MessageStore
+  ): Promise<void> {
+
+    if (Message.isSignedByAuthorDelegate(recordsQuery.message)) {
+      await recordsQuery.authorizeDelegate(messageStore);
+    }
+
+    // NOTE: not all RecordsQuery 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(recordsQuery.signaturePayload!)) {
+      await ProtocolAuthorization.authorizeQueryOrSubscribe(tenant, recordsQuery, messageStore);
+    }
+  }
+}