@enbox/dwn-sdk-js 0.0.1

package/src/dwn.ts

@@ -0,0 +1,264 @@
+
+import type { DataStore } from './types/data-store.js';
+import type { DidResolver } from '@enbox/dids';
+import type { EventLog } from './types/event-log.js';
+import type { EventStream } from './types/subscriptions.js';
+import type { MessageStore } from './types/message-store.js';
+import type { MethodHandler } from './types/method-handler.js';
+import type { Readable } from 'readable-stream';
+import type { ResumableTaskStore } from './types/resumable-task-store.js';
+import type { TenantGate } from './core/tenant-gate.js';
+import type { UnionMessageReply } from './core/message-reply.js';
+import type { GenericMessage, GenericMessageReply } from './types/message-types.js';
+import type { MessagesQueryMessage, MessagesQueryReply, MessagesReadMessage, MessagesReadReply, MessagesSubscribeMessage, MessagesSubscribeMessageOptions, MessagesSubscribeReply, MessageSubscriptionHandler } from './types/messages-types.js';
+import type { ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply } from './types/protocols-types.js';
+import type { RecordsDeleteMessage, RecordsQueryMessage, RecordsQueryReply, RecordsReadMessage, RecordsReadReply, RecordsSubscribeMessage, RecordsSubscribeMessageOptions, RecordsSubscribeReply, RecordSubscriptionHandler, RecordsWriteMessage, RecordsWriteMessageOptions } from './types/records-types.js';
+
+import { AllowAllTenantGate } from './core/tenant-gate.js';
+import { Message } from './core/message.js';
+import { messageReplyFromError } from './core/message-reply.js';
+import { MessagesQueryHandler } from './handlers/messages-query.js';
+import { MessagesReadHandler } from './handlers/messages-read.js';
+import { MessagesSubscribeHandler } from './handlers/messages-subscribe.js';
+import { ProtocolsConfigureHandler } from './handlers/protocols-configure.js';
+import { ProtocolsQueryHandler } from './handlers/protocols-query.js';
+import { RecordsDeleteHandler } from './handlers/records-delete.js';
+import { RecordsQueryHandler } from './handlers/records-query.js';
+import { RecordsReadHandler } from './handlers/records-read.js';
+import { RecordsSubscribeHandler } from './handlers/records-subscribe.js';
+import { RecordsWriteHandler } from './handlers/records-write.js';
+import { ResumableTaskManager } from './core/resumable-task-manager.js';
+import { StorageController } from './store/storage-controller.js';
+import { DidDht, DidJwk, DidKey, DidResolverCacheLevel, DidWeb, UniversalResolver } from '@enbox/dids';
+import { DwnInterfaceName, DwnMethodName } from './enums/dwn-interface-method.js';
+
+export class Dwn {
+  private methodHandlers: { [key:string]: MethodHandler };
+  private didResolver: DidResolver;
+  private messageStore: MessageStore;
+  private dataStore: DataStore;
+  private resumableTaskStore: ResumableTaskStore;
+  private eventLog: EventLog;
+  private tenantGate: TenantGate;
+  private eventStream?: EventStream;
+  private storageController: StorageController;
+  private resumableTaskManager: ResumableTaskManager;
+
+  private constructor(config: DwnConfig) {
+    this.didResolver = config.didResolver!;
+    this.tenantGate = config.tenantGate!;
+    this.eventStream = config.eventStream!;
+    this.messageStore = config.messageStore;
+    this.dataStore = config.dataStore;
+    this.resumableTaskStore = config.resumableTaskStore;
+    this.eventLog = config.eventLog;
+    this.eventStream = config.eventStream;
+    this.storageController = new StorageController({
+      messageStore : this.messageStore,
+      dataStore    : this.dataStore,
+      eventLog     : this.eventLog,
+      eventStream  : this.eventStream
+    });
+    this.resumableTaskManager = new ResumableTaskManager(
+      config.resumableTaskStore,
+      this.storageController
+    );
+
+    this.methodHandlers = {
+      [DwnInterfaceName.Messages + DwnMethodName.Query]: new MessagesQueryHandler(
+        this.didResolver,
+        this.messageStore,
+        this.eventLog,
+      ),
+      [DwnInterfaceName.Messages + DwnMethodName.Read]: new MessagesReadHandler(
+        this.didResolver,
+        this.messageStore,
+        this.dataStore,
+      ),
+      [DwnInterfaceName.Messages + DwnMethodName.Subscribe]: new MessagesSubscribeHandler(
+        this.didResolver,
+        this.messageStore,
+        this.eventStream,
+      ),
+      [DwnInterfaceName.Protocols + DwnMethodName.Configure]: new ProtocolsConfigureHandler(
+        this.didResolver,
+        this.messageStore,
+        this.eventLog,
+        this.eventStream
+      ),
+      [DwnInterfaceName.Protocols + DwnMethodName.Query]: new ProtocolsQueryHandler(
+        this.didResolver,
+        this.messageStore,
+        this.dataStore
+      ),
+      [DwnInterfaceName.Records + DwnMethodName.Delete]: new RecordsDeleteHandler(
+        this.didResolver,
+        this.messageStore,
+        this.resumableTaskManager
+      ),
+      [DwnInterfaceName.Records + DwnMethodName.Query]: new RecordsQueryHandler(
+        this.didResolver,
+        this.messageStore,
+        this.dataStore
+      ),
+      [DwnInterfaceName.Records + DwnMethodName.Read]: new RecordsReadHandler(
+        this.didResolver,
+        this.messageStore,
+        this.dataStore
+      ),
+      [DwnInterfaceName.Records + DwnMethodName.Subscribe]: new RecordsSubscribeHandler(
+        this.didResolver,
+        this.messageStore,
+        this.eventStream
+      ),
+      [DwnInterfaceName.Records + DwnMethodName.Write]: new RecordsWriteHandler(
+        this.didResolver,
+        this.messageStore,
+        this.dataStore,
+        this.eventLog,
+        this.eventStream
+      )
+    };
+  }
+
+  /**
+   * Creates an instance of the DWN.
+   */
+  public static async create(config: DwnConfig): Promise<Dwn> {
+    config.didResolver ??= new UniversalResolver({
+      didResolvers : [ DidDht, DidJwk, DidKey, DidWeb ],
+      cache        : new DidResolverCacheLevel({ location: 'RESOLVERCACHE' }),
+    });
+    config.tenantGate ??= new AllowAllTenantGate();
+
+    const dwn = new Dwn(config);
+    await dwn.open();
+    return dwn;
+  }
+
+  /**
+   * Initializes the DWN instance and opens the connection to it.
+   */
+  public async open(): Promise<void> {
+    await this.messageStore.open();
+    await this.dataStore.open();
+    await this.resumableTaskStore.open();
+    await this.eventLog.open();
+    await this.eventStream?.open();
+
+    await this.resumableTaskManager.resumeTasksAndWaitForCompletion();
+  }
+
+  public async close(): Promise<void> {
+    await this.eventStream?.close();
+    await this.messageStore.close();
+    await this.dataStore.close();
+    await this.resumableTaskStore.close();
+    await this.eventLog.close();
+  }
+
+  /**
+   * Processes the given DWN message and returns with a reply.
+   * @param tenant The tenant DID to route the given message to.
+   */
+  public async processMessage(tenant: string, rawMessage: MessagesQueryMessage): Promise<MessagesQueryReply>;
+  public async processMessage(
+    tenant: string, rawMessage: MessagesSubscribeMessage, options?: MessagesSubscribeMessageOptions): Promise<MessagesSubscribeReply>;
+  public async processMessage(tenant: string, rawMessage: MessagesReadMessage): Promise<MessagesReadReply>;
+  public async processMessage(tenant: string, rawMessage: ProtocolsConfigureMessage): Promise<GenericMessageReply>;
+  public async processMessage(tenant: string, rawMessage: ProtocolsQueryMessage): Promise<ProtocolsQueryReply>;
+  public async processMessage(tenant: string, rawMessage: RecordsDeleteMessage): Promise<GenericMessageReply>;
+  public async processMessage(tenant: string, rawMessage: RecordsQueryMessage): Promise<RecordsQueryReply>;
+  public async processMessage(
+    tenant: string, rawMessage: RecordsSubscribeMessage, options: RecordsSubscribeMessageOptions): Promise<RecordsSubscribeReply>;
+  public async processMessage(tenant: string, rawMessage: RecordsReadMessage): Promise<RecordsReadReply>;
+  public async processMessage(tenant: string, rawMessage: RecordsWriteMessage, options?: RecordsWriteMessageOptions): Promise<GenericMessageReply>;
+  public async processMessage(tenant: string, rawMessage: unknown, options?: MessageOptions): Promise<UnionMessageReply>;
+  public async processMessage(tenant: string, rawMessage: GenericMessage, options: MessageOptions = {}): Promise<UnionMessageReply> {
+    const errorMessageReply = await this.validateTenant(tenant) ?? await this.validateMessageIntegrity(rawMessage);
+    if (errorMessageReply !== undefined) {
+      return errorMessageReply;
+    }
+
+    const { dataStream, subscriptionHandler } = options;
+
+    const handlerKey = rawMessage.descriptor.interface + rawMessage.descriptor.method;
+    const methodHandlerReply = await this.methodHandlers[handlerKey].handle({
+      tenant,
+      message: rawMessage as GenericMessage,
+      dataStream,
+      subscriptionHandler
+    });
+
+    return methodHandlerReply;
+  }
+
+  /**
+   * Checks tenant gate to see if tenant is allowed.
+   * @param tenant The tenant DID to route the given message to.
+   * @returns GenericMessageReply if the message has an integrity error, otherwise undefined.
+   */
+  public async validateTenant(tenant: string): Promise<GenericMessageReply | undefined> {
+    const result = await this.tenantGate.isActiveTenant(tenant);
+    if (!result.isActiveTenant) {
+      const detail = result.detail ?? `DID ${tenant} is not an active tenant.`;
+      return {
+        status: { code: 401, detail }
+      };
+    }
+  }
+
+  /**
+   * Validates structure of DWN message
+   * @param tenant The tenant DID to route the given message to.
+   * @param dwnMessageInterface The interface of DWN message.
+   * @param dwnMessageMethod The interface of DWN message.
+
+   * @returns GenericMessageReply if the message has an integrity error, otherwise undefined.
+   */
+  public async validateMessageIntegrity(
+    rawMessage: any,
+  ): Promise<GenericMessageReply | undefined> {
+    // Verify interface and method
+    const dwnInterface = rawMessage?.descriptor?.interface;
+    const dwnMethod = rawMessage?.descriptor?.method;
+
+    if (dwnInterface === undefined || dwnMethod === undefined) {
+      return {
+        status: { code: 400, detail: `Both interface and method must be present, interface: ${dwnInterface}, method: ${dwnMethod}` }
+      };
+    }
+
+    // validate message structure
+    try {
+      // consider to push this down to individual handlers
+      Message.validateJsonSchema(rawMessage);
+    } catch (error) {
+      return messageReplyFromError(error, 400);
+    }
+  }
+};
+
+/**
+ *  MessageOptions that are used when processing a message.
+ */
+export interface MessageOptions {
+  dataStream?: Readable;
+  subscriptionHandler?: MessageSubscriptionHandler | RecordSubscriptionHandler;
+};
+
+/**
+ * DWN configuration.
+ */
+export type DwnConfig = {
+  didResolver?: DidResolver;
+  tenantGate?: TenantGate;
+
+  // event stream is optional if a DWN does not wish to provide subscription services.
+  eventStream?: EventStream;
+
+  messageStore: MessageStore;
+  dataStore: DataStore;
+  eventLog: EventLog;
+  resumableTaskStore: ResumableTaskStore;
+};

package/src/enums/dwn-interface-method.ts

@@ -0,0 +1,14 @@
+export enum DwnInterfaceName {
+  Messages = 'Messages',
+  Protocols = 'Protocols',
+  Records = 'Records'
+}
+
+export enum DwnMethodName {
+  Configure = 'Configure',
+  Query = 'Query',
+  Read = 'Read',
+  Write = 'Write',
+  Delete = 'Delete',
+  Subscribe = 'Subscribe'
+}

package/src/event-log/event-emitter-stream.ts

@@ -0,0 +1,69 @@
+import type { KeyValues } from '../types/query-types.js';
+import type { EventListener, EventStream, EventSubscription, MessageEvent } from '../types/subscriptions.js';
+
+import { EventEmitter } from 'events';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+const EVENTS_LISTENER_CHANNEL = 'events';
+
+export interface EventEmitterStreamConfig {
+  /**
+   * An optional error handler in order to be able to react to any errors or warnings triggers by `EventEmitter`.
+   * By default we log errors with `console.error`.
+   */
+  errorHandler?: (error: any) => void;
+};
+
+export class EventEmitterStream implements EventStream {
+  private eventEmitter: EventEmitter;
+  private isOpen: boolean = false;
+
+  constructor(config: EventEmitterStreamConfig = {}) {
+    // we capture the rejections and currently just log the errors that are produced
+    this.eventEmitter = new EventEmitter({ captureRejections: true });
+
+    // number of listeners per particular eventName before a warning is emitted
+    // we set to 0 which represents infinity.
+    // https://nodejs.org/api/events.html#emittersetmaxlistenersn
+    this.eventEmitter.setMaxListeners(0);
+
+    if (config.errorHandler) {
+      this.errorHandler = config.errorHandler;
+    }
+
+    this.eventEmitter.on('error', this.errorHandler);
+  }
+
+  /**
+   * we subscribe to the `EventEmitter` error handler with a provided handler or set one which logs the errors.
+   */
+  private errorHandler: (error:any) => void = (error) => { console.error('event emitter error', error); };
+
+  async subscribe(tenant: string, id: string, listener: EventListener): Promise<EventSubscription> {
+    this.eventEmitter.on(`${tenant}_${EVENTS_LISTENER_CHANNEL}`, listener);
+    return {
+      id,
+      close: async (): Promise<void> => { this.eventEmitter.off(`${tenant}_${EVENTS_LISTENER_CHANNEL}`, listener); }
+    };
+  }
+
+  async open(): Promise<void> {
+    this.isOpen = true;
+  }
+
+  async close(): Promise<void> {
+    this.isOpen = false;
+    this.eventEmitter.removeAllListeners();
+  }
+
+  emit(tenant: string, event: MessageEvent, indexes: KeyValues): void {
+    if (!this.isOpen) {
+      this.errorHandler(new DwnError(
+        DwnErrorCode.EventEmitterStreamNotOpenError,
+        'a message emitted when EventEmitterStream is closed'
+      ));
+      return;
+    }
+    this.eventEmitter.emit(`${tenant}_${EVENTS_LISTENER_CHANNEL}`, tenant, event, indexes);
+  }
+}

package/src/event-log/event-log-level.ts

@@ -0,0 +1,72 @@
+import type { EventLog } from '../types/event-log.js';
+import type { EventStream } from '../types/subscriptions.js';
+import type { ULIDFactory } from 'ulidx';
+import type { Filter, KeyValues, PaginationCursor } from '../types/query-types.js';
+
+import { createLevelDatabase } from '../store/level-wrapper.js';
+import { IndexLevel } from '../store/index-level.js';
+import { monotonicFactory } from 'ulidx';
+
+export type EventLogLevelConfig = {
+ /**
+   * must be a directory path (relative or absolute) where
+   *  LevelDB will store its files, or in browsers, the name of the
+   * {@link https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase IDBDatabase} to be opened.
+  */
+  location?: string,
+  createLevelDatabase?: typeof createLevelDatabase,
+  eventStream?: EventStream,
+};
+
+export class EventLogLevel implements EventLog {
+  ulidFactory: ULIDFactory;
+  index: IndexLevel;
+
+  constructor(config?: EventLogLevelConfig) {
+    this.index = new IndexLevel({
+      location: 'EVENTLOG',
+      createLevelDatabase,
+      ...config,
+    });
+
+    this.ulidFactory = monotonicFactory();
+  }
+
+  async open(): Promise<void> {
+    return this.index.open();
+  }
+
+  async close(): Promise<void> {
+    return this.index.close();
+  }
+
+  async clear(): Promise<void> {
+    return this.index.clear();
+  }
+
+  async append(tenant: string, messageCid: string, indexes: KeyValues): Promise<void> {
+    const watermark = this.ulidFactory();
+    await this.index.put(tenant, messageCid, { ...indexes, watermark });
+  }
+
+  async queryEvents(tenant: string, filters: Filter[], cursor?: PaginationCursor): Promise<{ events: string[], cursor?: PaginationCursor }> {
+    const results = await this.index.query(tenant, filters, { sortProperty: 'watermark', cursor });
+    return {
+      events : results.map(({ messageCid }) => messageCid),
+      cursor : IndexLevel.createCursorFromLastArrayItem(results, 'watermark'),
+    };
+  }
+
+  async getEvents(tenant: string, cursor?: PaginationCursor): Promise<{ events: string[], cursor?: PaginationCursor }> {
+    return this.queryEvents(tenant, [], cursor);
+  }
+
+  async deleteEventsByCid(tenant: string, messageCids: Array<string>): Promise<void> {
+    const indexDeletePromises: Promise<void>[] = [];
+    for (const messageCid of messageCids) {
+      indexDeletePromises.push(this.index.delete(tenant, messageCid));
+    }
+
+    await Promise.all(indexDeletePromises);
+  }
+}

package/src/handlers/messages-query.ts

@@ -0,0 +1,67 @@
+import type { DidResolver } from '@enbox/dids';
+import type { EventLog } from '../types/event-log.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { MessagesQueryMessage, MessagesQueryReply } from '../types/messages-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { messageReplyFromError } from '../core/message-reply.js';
+import { Messages } from '../utils/messages.js';
+import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
+import { MessagesQuery } from '../interfaces/messages-query.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+
+export class MessagesQueryHandler implements MethodHandler {
+
+  constructor(private didResolver: DidResolver, private messageStore: MessageStore, private eventLog: EventLog) { }
+
+  public async handle({
+    tenant,
+    message
+  }: {tenant: string, message: MessagesQueryMessage}): Promise<MessagesQueryReply> {
+    let messagesQuery: MessagesQuery;
+
+    try {
+      messagesQuery = await MessagesQuery.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    try {
+      await authenticate(message.authorization, this.didResolver);
+      await MessagesQueryHandler.authorizeMessagesQuery(tenant, messagesQuery, this.messageStore);
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    // an empty array of filters means no filtering and all events are returned
+    const eventFilters = Messages.convertFilters(message.descriptor.filters);
+    const { events, cursor } = await this.eventLog.queryEvents(tenant, eventFilters, message.descriptor.cursor);
+
+    return {
+      status  : { code: 200, detail: 'OK' },
+      entries : events,
+      cursor
+    };
+  }
+
+  private static async authorizeMessagesQuery(tenant: string, messagesQuery: MessagesQuery, messageStore: MessageStore): Promise<void> {
+    // if `MessagesQuery` author is the same as the target tenant, we can directly grant access
+    if (messagesQuery.author === tenant) {
+      return;
+    } else if (messagesQuery.author !== undefined && messagesQuery.signaturePayload!.permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, messagesQuery.signaturePayload!.permissionGrantId);
+      await MessagesGrantAuthorization.authorizeQueryOrSubscribe({
+        incomingMessage : messagesQuery.message,
+        expectedGrantor : tenant,
+        expectedGrantee : messagesQuery.author,
+        permissionGrant,
+        messageStore
+      });
+    } else {
+      throw new DwnError(DwnErrorCode.MessagesQueryAuthorizationFailed, 'message failed authorization');
+    }
+  }
+}

package/src/handlers/messages-read.ts

@@ -0,0 +1,103 @@
+import type { DataStore } from '../types/data-store.js';
+import type { DidResolver } from '@enbox/dids';
+import type { GenericMessage } from '../types/message-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { RecordsQueryReplyEntry } from '../types/records-types.js';
+import type { MessagesReadMessage, MessagesReadReply, MessagesReadReplyEntry } from '../types/messages-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { DataStream } from '../utils/data-stream.js';
+import { Encoder } from '../utils/encoder.js';
+import { messageReplyFromError } from '../core/message-reply.js';
+import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
+import { MessagesRead } from '../interfaces/messages-read.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { Records } from '../utils/records.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+type HandleArgs = { tenant: string, message: MessagesReadMessage };
+
+export class MessagesReadHandler implements MethodHandler {
+  constructor(private didResolver: DidResolver, private messageStore: MessageStore, private dataStore: DataStore) {}
+
+  public async handle({ tenant, message }: HandleArgs): Promise<MessagesReadReply> {
+    let messagesRead: MessagesRead;
+
+    try {
+      messagesRead = await MessagesRead.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    try {
+      await authenticate(message.authorization, this.didResolver);
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    const messageResult = await this.messageStore.get(tenant, message.descriptor.messageCid);
+    if (messageResult === undefined) {
+      return { status: { code: 404, detail: 'Not Found' } };
+    }
+
+    try {
+      await MessagesReadHandler.authorizeMessagesRead(tenant, messagesRead, messageResult, this.messageStore);
+    } catch (error) {
+      return messageReplyFromError(error, 401);
+    }
+
+    // If the message is a RecordsWrite, we include the data in the response if it is available
+    const entry: MessagesReadReplyEntry = { message: messageResult, messageCid: message.descriptor.messageCid };
+    if (Records.isRecordsWrite(messageResult)) {
+      const recordsWrite = entry.message as RecordsQueryReplyEntry;
+      // RecordsWrite specific handling, if MessageStore has embedded `encodedData` return it with the entry.
+      // we store `encodedData` along with the message if the data is below a certain threshold.
+      if (recordsWrite.encodedData !== undefined) {
+        const dataBytes = Encoder.base64UrlToBytes(recordsWrite.encodedData);
+        entry.data = DataStream.fromBytes(dataBytes);
+        delete recordsWrite.encodedData;
+      } else {
+        // otherwise check the data store for the associated data
+        const result = await this.dataStore.get(tenant, recordsWrite.recordId, recordsWrite.descriptor.dataCid);
+        if (result?.dataStream !== undefined) {
+          entry.data = result.dataStream;
+        }
+      }
+    }
+
+    return {
+      status: { code: 200, detail: 'OK' },
+      entry
+    };
+  }
+
+  /**
+   * @param messageStore Used to fetch related permission grant, permission revocation, and/or RecordsWrites for permission scope validation.
+   */
+  private static async authorizeMessagesRead(
+    tenant: string,
+    messagesRead: MessagesRead,
+    matchedMessage: GenericMessage,
+    messageStore: MessageStore
+  ): Promise<void> {
+
+    if (messagesRead.author === tenant) {
+      // If the author is the tenant, no further authorization is needed
+      return;
+    } else if (messagesRead.author !== undefined && messagesRead.signaturePayload!.permissionGrantId !== undefined) {
+      // if the author is not the tenant and the message has a permissionGrantId, we need to authorize the grant
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, messagesRead.signaturePayload!.permissionGrantId);
+      await MessagesGrantAuthorization.authorizeMessagesRead({
+        messagesReadMessage : messagesRead.message,
+        messageToRead       : matchedMessage,
+        expectedGrantor     : tenant,
+        expectedGrantee     : messagesRead.author,
+        permissionGrant,
+        messageStore
+      });
+    } else {
+      throw new DwnError(DwnErrorCode.MessagesReadAuthorizationFailed, 'protocol message failed authorization');
+    }
+  }
+}

package/src/handlers/messages-subscribe.ts

@@ -0,0 +1,89 @@
+import type { DidResolver } from '@enbox/dids';
+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 { MessagesSubscribeMessage, MessagesSubscribeReply, MessageSubscriptionHandler } from '../types/messages-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 { Messages } from '../utils/messages.js';
+import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
+import { MessagesSubscribe } from '../interfaces/messages-subscribe.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+export class MessagesSubscribeHandler implements MethodHandler {
+  constructor(
+    private didResolver: DidResolver,
+    private messageStore: MessageStore,
+    private eventStream?: EventStream
+  ) {}
+
+  public async handle({
+    tenant,
+    message,
+    subscriptionHandler
+  }: {
+    tenant: string;
+    message: MessagesSubscribeMessage;
+    subscriptionHandler: MessageSubscriptionHandler;
+  }): Promise<MessagesSubscribeReply> {
+    if (this.eventStream === undefined) {
+      return messageReplyFromError(new DwnError(
+        DwnErrorCode.MessagesSubscribeEventStreamUnimplemented,
+        'Subscriptions are not supported'
+      ), 501);
+    }
+
+    let messagesSubscribe: MessagesSubscribe;
+    try {
+      messagesSubscribe = await MessagesSubscribe.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    try {
+      await authenticate(message.authorization, this.didResolver);
+      await MessagesSubscribeHandler.authorizeMessagesSubscribe(tenant, messagesSubscribe, this.messageStore);
+    } catch (error) {
+      return messageReplyFromError(error, 401);
+    }
+
+    const { filters } = message.descriptor;
+    const messagesFilters = Messages.convertFilters(filters);
+    const messageCid = await Message.getCid(message);
+
+    const listener: EventListener = (eventTenant, event, eventIndexes):void => {
+      if (tenant === eventTenant && FilterUtility.matchAnyFilter(eventIndexes, messagesFilters)) {
+        subscriptionHandler(event);
+      }
+    };
+
+    const subscription = await this.eventStream.subscribe(tenant, messageCid, listener);
+
+    return {
+      status: { code: 200, detail: 'OK' },
+      subscription,
+    };
+  }
+
+  private static async authorizeMessagesSubscribe(tenant: string, messagesSubscribe: MessagesSubscribe, messageStore: MessageStore): Promise<void> {
+    // if `MessagesSubscribe` author is the same as the target tenant, we can directly grant access
+    if (messagesSubscribe.author === tenant) {
+      return;
+    } else if (messagesSubscribe.author !== undefined && messagesSubscribe.signaturePayload!.permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, messagesSubscribe.signaturePayload!.permissionGrantId);
+      await MessagesGrantAuthorization.authorizeQueryOrSubscribe({
+        incomingMessage : messagesSubscribe.message,
+        expectedGrantor : tenant,
+        expectedGrantee : messagesSubscribe.author,
+        permissionGrant,
+        messageStore
+      });
+    } else {
+      throw new DwnError(DwnErrorCode.MessagesSubscribeAuthorizationFailed, 'message failed authorization');
+    }
+  }
+}