@enbox/dwn-sdk-js 0.0.1

package/src/handlers/records-read.ts

@@ -0,0 +1,187 @@
+import type { DataStore } from '../types/data-store.js';
+import type { DidResolver } from '@enbox/dids';
+import type { Filter } from '../types/query-types.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { 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 { 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';
+import { RecordsRead } from '../interfaces/records-read.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export class RecordsReadHandler implements MethodHandler {
+
+  constructor(private didResolver: DidResolver, private messageStore: MessageStore, private dataStore: DataStore) { }
+
+  public async handle({
+    tenant,
+    message
+  }: { tenant: string, message: RecordsReadMessage }): Promise<RecordsReadReply> {
+
+    let recordsRead: RecordsRead;
+    try {
+      recordsRead = await RecordsRead.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    // authentication
+    try {
+      if (recordsRead.author !== undefined) {
+        await authenticate(message.authorization!, this.didResolver);
+      }
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    // get the latest active messages matching the supplied filter
+    const query: Filter = {
+      // NOTE: we don't filter by `method` so that we get both RecordsWrite and RecordsDelete messages
+      interface         : DwnInterfaceName.Records,
+      isLatestBaseState : true,
+      ...Records.convertFilter(message.descriptor.filter)
+    };
+    const { messages: existingMessages } = await this.messageStore.query(tenant, [ query ]);
+    if (existingMessages.length === 0) {
+      return {
+        status: { code: 404, detail: 'Not Found' }
+      };
+    } else if (existingMessages.length > 1) {
+      return messageReplyFromError(new DwnError(
+        DwnErrorCode.RecordsReadReturnedMultiple,
+        'Multiple records exist for the RecordsRead filter'
+      ), 400);
+    }
+
+    const matchedMessage = existingMessages[0];
+
+    // if the matched message is a RecordsDelete, we mark the record as not-found and return both the RecordsDelete and the initial RecordsWrite
+    // TODO: https://github.com/TBD54566975/dwn-sdk-js/issues/819:
+    // Consider performing authorization checks like when records exists before returning RecordsDelete and initial RecordsWrite of a deleted record
+    if (matchedMessage.descriptor.method === DwnMethodName.Delete) {
+      const recordsDeleteMessage = matchedMessage as RecordsDeleteMessage;
+      const initialWrite = await RecordsWrite.fetchInitialRecordsWriteMessage(this.messageStore, tenant, recordsDeleteMessage.descriptor.recordId);
+
+      if (initialWrite === undefined) {
+        return messageReplyFromError(new DwnError(
+          DwnErrorCode.RecordsReadInitialWriteNotFound,
+          'Initial write for deleted record not found'
+        ), 400);
+      }
+
+      // Perform authorization before returning the delete and initial write messages
+      const parsedInitialWrite = await RecordsWrite.parse(initialWrite);
+      try {
+        await RecordsReadHandler.authorizeRecordsRead(tenant, recordsRead, parsedInitialWrite, this.messageStore);
+      } catch (error) {
+        return messageReplyFromError(error, 401);
+      }
+
+      return {
+        status : { code: 404, detail: 'Not Found' },
+        entry  : {
+          recordsDelete: recordsDeleteMessage,
+          initialWrite
+        }
+      };
+    }
+
+    // else the matched message is a RecordsWrite
+    const matchedRecordsWrite = matchedMessage as RecordsQueryReplyEntry;
+
+    try {
+      await RecordsReadHandler.authorizeRecordsRead(tenant, recordsRead, await RecordsWrite.parse(matchedRecordsWrite), this.messageStore);
+    } catch (error) {
+      return messageReplyFromError(error, 401);
+    }
+
+    let data;
+    if (matchedRecordsWrite.encodedData !== undefined) {
+      const dataBytes = Encoder.base64UrlToBytes(matchedRecordsWrite.encodedData);
+      data = DataStream.fromBytes(dataBytes);
+      delete matchedRecordsWrite.encodedData;
+    } else {
+      const result = await this.dataStore.get(tenant, matchedRecordsWrite.recordId, matchedRecordsWrite.descriptor.dataCid);
+      if (result?.dataStream === undefined) {
+        return {
+          status: { code: 404, detail: 'Not Found' }
+        };
+      }
+      data = result.dataStream;
+    }
+
+    const recordsReadReply: RecordsReadReply = {
+      status : { code: 200, detail: 'OK' },
+      entry  : {
+        recordsWrite: matchedRecordsWrite,
+        data
+      }
+    };
+
+    // attach initial write if latest RecordsWrite is not initial write
+    if (!await RecordsWrite.isInitialWrite(matchedRecordsWrite)) {
+      const initialWriteQueryResult = await this.messageStore.query(
+        tenant,
+        [{ recordId: matchedRecordsWrite.recordId, isLatestBaseState: false, method: DwnMethodName.Write }]
+      );
+      const initialWrite = initialWriteQueryResult.messages[0] as RecordsQueryReplyEntry;
+      delete initialWrite.encodedData; // just defensive because technically should already be deleted when a later RecordsWrite is written
+      recordsReadReply.entry!.initialWrite = initialWrite;
+    }
+
+    return recordsReadReply;
+  };
+
+  /**
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  private static async authorizeRecordsRead(
+    tenant: string,
+    recordsRead: RecordsRead,
+    matchedRecordsWrite: RecordsWrite,
+    messageStore: MessageStore
+  ): Promise<void> {
+    if (Message.isSignedByAuthorDelegate(recordsRead.message)) {
+      await recordsRead.authorizeDelegate(matchedRecordsWrite.message, messageStore);
+    }
+
+    const { descriptor } = matchedRecordsWrite.message;
+
+    // if author is the same as the target tenant, we can directly grant access
+    if (recordsRead.author === tenant) {
+      return;
+    } else if (descriptor.published === true) {
+      // authentication is not required for published data
+      return;
+    } else if (recordsRead.author !== undefined &&
+      (recordsRead.author === descriptor.recipient || recordsRead.author === matchedRecordsWrite.author)
+    ) {
+      // The recipient or author of a message may always read it
+      return;
+    } else if (recordsRead.author !== undefined && recordsRead.signaturePayload!.permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, recordsRead.signaturePayload!.permissionGrantId);
+      await RecordsGrantAuthorization.authorizeRead({
+        recordsReadMessage          : recordsRead.message,
+        recordsWriteMessageToBeRead : matchedRecordsWrite.message,
+        expectedGrantor             : tenant,
+        expectedGrantee             : recordsRead.author,
+        permissionGrant,
+        messageStore
+      });
+    } else if (descriptor.protocol !== undefined) {
+      await ProtocolAuthorization.authorizeRead(tenant, recordsRead, matchedRecordsWrite, messageStore);
+    } else {
+      throw new DwnError(DwnErrorCode.RecordsReadAuthorizationFailed, 'message failed authorization');
+    }
+  }
+}

package/src/handlers/records-subscribe.ts

@@ -0,0 +1,218 @@
+import type { DidResolver } from '@enbox/dids';
+import type { Filter } from '../types/query-types.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { EventListener, EventStream } from '../types/subscriptions.js';
+import type { RecordEvent, RecordsSubscribeMessage, RecordsSubscribeReply, RecordSubscriptionHandler } from '../types/records-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { FilterUtility } from '../utils/filter.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 { RecordsSubscribe } from '../interfaces/records-subscribe.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export class RecordsSubscribeHandler implements MethodHandler {
+
+  constructor(private didResolver: DidResolver, private messageStore: MessageStore, private eventStream?: EventStream) { }
+
+  public async handle({
+    tenant,
+    message,
+    subscriptionHandler
+  }: {
+    tenant: string,
+    message: RecordsSubscribeMessage,
+    subscriptionHandler: RecordSubscriptionHandler,
+  }): Promise<RecordsSubscribeReply> {
+    if (this.eventStream === undefined) {
+      return messageReplyFromError(new DwnError(
+        DwnErrorCode.RecordsSubscribeEventStreamUnimplemented,
+        'Subscriptions are not supported'
+      ), 501);
+    }
+
+    let recordsSubscribe: RecordsSubscribe;
+    try {
+      recordsSubscribe = await RecordsSubscribe.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    let filters:Filter[] = [];
+    // if this is an anonymous subscribe and the filter supports published records, subscribe to only published records
+    if (Records.filterIncludesPublishedRecords(recordsSubscribe.message.descriptor.filter) && recordsSubscribe.author === undefined) {
+      // build filters for a stream of published records
+      filters = [ RecordsSubscribeHandler.buildPublishedRecordsFilter(recordsSubscribe) ];
+      // delete the undefined authorization property else the code will encounter the following IPLD issue when attempting to generate CID:
+      // Error: `undefined` is not supported by the IPLD Data Model and cannot be encoded
+      delete message.authorization;
+    } else {
+      // authentication and authorization
+      try {
+        await authenticate(message.authorization!, this.didResolver);
+        await RecordsSubscribeHandler.authorizeRecordsSubscribe(tenant, recordsSubscribe, this.messageStore);
+      } catch (error) {
+        return messageReplyFromError(error, 401);
+      }
+
+      if (recordsSubscribe.author === tenant) {
+        // if the subscribe author is the tenant, filter as owner.
+        filters = await RecordsSubscribeHandler.filterAsOwner(recordsSubscribe);
+      } else {
+        // otherwise build filters based on published records, permissions, or protocol rules
+        filters = await RecordsSubscribeHandler.filterAsNonOwner(recordsSubscribe);
+      }
+    }
+
+    const listener: EventListener = (eventTenant, event, eventIndexes):void => {
+      if (tenant === eventTenant && FilterUtility.matchAnyFilter(eventIndexes, filters)) {
+        // the filters check for interface and method
+        // if matched the message is either a `RecordsWriteMessage` or `RecordsDeleteMessage` so we cast the event to a `RecordEvent`
+        subscriptionHandler(event as RecordEvent);
+      }
+    };
+
+    const messageCid = await Message.getCid(message);
+    const subscription = await this.eventStream.subscribe(tenant, messageCid, listener);
+    return {
+      status: { code: 200, detail: 'OK' },
+      subscription
+    };
+  }
+
+  /**
+   * Subscribe to records as the owner of the DWN with no additional filtering.
+   */
+  private static async filterAsOwner(RecordsSubscribe: RecordsSubscribe): Promise<Filter[]> {
+    const { filter } = RecordsSubscribe.message.descriptor;
+
+    const subscribeFilter = {
+      ...Records.convertFilter(filter),
+      interface : DwnInterfaceName.Records,
+      method    : [ DwnMethodName.Write, DwnMethodName.Delete ], // we filter for both write and delete so that subscriber can update state.
+    };
+
+    return [ subscribeFilter ];
+  }
+
+  /**
+   * Creates filters in order to subscribe to records as a non-owner.
+   *
+   * Filters can support emitting messages for 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 subscription author (where `recipient` is the subscription author); and
+   *    3. unpublished records authorized by a protocol rule.
+   *
+   * B) PUBLISHED:
+   *    1. only published records;
+   *
+   * C) UNPUBLISHED:
+   *    1. unpublished records intended for the subscription author (where `recipient` is the subscription author); and
+   *    2. unpublished records authorized by a protocol rule.
+   */
+  private static async filterAsNonOwner(
+    recordsSubscribe: RecordsSubscribe
+  ): Promise<Filter[]> {
+    const filters:Filter[] = [];
+    const { filter } = recordsSubscribe.message.descriptor;
+    if (Records.filterIncludesPublishedRecords(filter)) {
+      filters.push(RecordsSubscribeHandler.buildPublishedRecordsFilter(recordsSubscribe));
+    }
+
+    if (Records.filterIncludesUnpublishedRecords(filter)) {
+      if (Records.shouldBuildUnpublishedAuthorFilter(filter, recordsSubscribe.author!)) {
+        filters.push(RecordsSubscribeHandler.buildUnpublishedRecordsBySubscribeAuthorFilter(recordsSubscribe));
+      }
+
+      if (Records.shouldProtocolAuthorize(recordsSubscribe.signaturePayload!)) {
+        filters.push(RecordsSubscribeHandler.buildUnpublishedProtocolAuthorizedRecordsFilter(recordsSubscribe));
+      }
+
+      if (Records.shouldBuildUnpublishedRecipientFilter(filter, recordsSubscribe.author!)) {
+        filters.push(RecordsSubscribeHandler.buildUnpublishedRecordsForSubscribeAuthorFilter(recordsSubscribe));
+      }
+    }
+    return filters;
+  }
+
+  /**
+   * Creates a filter for all published records matching the subscribe
+   */
+  private static buildPublishedRecordsFilter(recordsSubscribe: RecordsSubscribe): Filter {
+    return {
+      ...Records.convertFilter(recordsSubscribe.message.descriptor.filter),
+      interface : DwnInterfaceName.Records,
+      method    : [ DwnMethodName.Write, DwnMethodName.Delete ],
+      published : true,
+    };
+  }
+
+  /**
+   * Creates a filter for unpublished records that are intended for the subscribe author (where `recipient` is the author).
+   */
+  private static buildUnpublishedRecordsForSubscribeAuthorFilter(recordsSubscribe: RecordsSubscribe): Filter {
+    // include records where recipient is subscribe author
+    return {
+      ...Records.convertFilter(recordsSubscribe.message.descriptor.filter),
+      interface : DwnInterfaceName.Records,
+      method    : [ DwnMethodName.Write, DwnMethodName.Delete ],
+      recipient : recordsSubscribe.author!,
+      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(recordsSubscribe: RecordsSubscribe): Filter {
+    return {
+      ...Records.convertFilter(recordsSubscribe.message.descriptor.filter),
+      interface : DwnInterfaceName.Records,
+      method    : [ DwnMethodName.Write, DwnMethodName.Delete ],
+      published : false
+    };
+  }
+
+  /**
+   * Creates a filter for only unpublished records where the author is the same as the subscribe author.
+   */
+  private static buildUnpublishedRecordsBySubscribeAuthorFilter(recordsSubscribe: RecordsSubscribe): Filter {
+    // include records where author is the same as the subscribe author
+    return {
+      ...Records.convertFilter(recordsSubscribe.message.descriptor.filter),
+      author    : recordsSubscribe.author!,
+      interface : DwnInterfaceName.Records,
+      method    : [ DwnMethodName.Write, DwnMethodName.Delete ],
+      published : false
+    };
+  }
+
+  /**
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public static async authorizeRecordsSubscribe(
+    tenant: string,
+    recordsSubscribe: RecordsSubscribe,
+    messageStore: MessageStore
+  ): Promise<void> {
+
+    if (Message.isSignedByAuthorDelegate(recordsSubscribe.message)) {
+      await recordsSubscribe.authorizeDelegate(messageStore);
+    }
+
+    // NOTE: not all RecordsSubscribe 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(recordsSubscribe.signaturePayload!)) {
+      await ProtocolAuthorization.authorizeQueryOrSubscribe(tenant, recordsSubscribe, messageStore);
+    }
+  }
+}