@enbox/dwn-sdk-js 0.0.1

package/src/handlers/records-write.ts

@@ -0,0 +1,404 @@
+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 { GenericMessageReply } from '../types/message-types.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { RecordsQueryReplyEntry, RecordsWriteMessage } from '../types/records-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { Cid } from '../utils/cid.js';
+import { DataStream } from '../utils/data-stream.js';
+import { DwnConstant } from '../core/dwn-constant.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 { RecordsGrantAuthorization } from '../core/records-grant-authorization.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { StorageController } from '../store/storage-controller.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+type HandlerArgs = { tenant: string, message: RecordsWriteMessage, dataStream?: _Readable.Readable};
+
+export class RecordsWriteHandler implements MethodHandler {
+
+  constructor(
+    private didResolver: DidResolver,
+    private messageStore: MessageStore,
+    private dataStore: DataStore,
+    private eventLog: EventLog,
+    private eventStream?: EventStream
+  ) { }
+
+  public async handle({
+    tenant,
+    message,
+    dataStream
+  }: HandlerArgs): Promise<GenericMessageReply> {
+    let recordsWrite: RecordsWrite;
+    try {
+      recordsWrite = await RecordsWrite.parse(message);
+
+      // Protocol-authorized record specific validation
+      if (message.descriptor.protocol !== undefined) {
+        await ProtocolAuthorization.validateReferentialIntegrity(tenant, recordsWrite, this.messageStore);
+      }
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    // authentication & authorization
+    try {
+      await authenticate(message.authorization, this.didResolver);
+      await RecordsWriteHandler.authorizeRecordsWrite(tenant, recordsWrite, this.messageStore);
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    // get existing messages matching the `recordId`
+    const query = {
+      interface : DwnInterfaceName.Records,
+      recordId  : message.recordId
+    };
+    const { messages: existingMessages } = await this.messageStore.query(tenant, [ query ]);
+
+    // if the incoming write is not the initial write, then it must not modify any immutable properties defined by the initial write
+    const newMessageIsInitialWrite = await recordsWrite.isInitialWrite();
+    let initialWrite: RecordsWriteMessage | undefined;
+    if (!newMessageIsInitialWrite) {
+      try {
+        initialWrite = await RecordsWrite.getInitialWrite(existingMessages);
+        RecordsWrite.verifyEqualityOfImmutableProperties(initialWrite, message);
+      } catch (e) {
+        return messageReplyFromError(e, 400);
+      }
+    }
+
+    const newestExistingMessage = await Message.getNewestMessage(existingMessages);
+
+    let incomingMessageIsNewest = false;
+    let newestMessage; // keep reference of newest message for pruning later
+    if (newestExistingMessage === undefined || await Message.isNewer(message, newestExistingMessage)) {
+      incomingMessageIsNewest = true;
+      newestMessage = message;
+    } else { // existing message is the same age or newer than the incoming message
+      newestMessage = newestExistingMessage;
+    }
+
+    if (!incomingMessageIsNewest) {
+      return {
+        status: { code: 409, detail: 'Conflict' }
+      };
+    }
+
+    try {
+      if (newestExistingMessage?.descriptor.method === DwnMethodName.Delete) {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteNotAllowedAfterDelete,
+          'RecordsWrite is not allowed after a RecordsDelete.'
+        );
+      }
+
+      // NOTE: We want to perform additional validation before storing the RecordsWrite.
+      // This is necessary for core DWN RecordsWrite that needs additional processing and allows us to fail before the storing and post processing.
+      //
+      // Example: Ensures that the protocol tag of a permission revocation RecordsWrite and the parent grant's scoped protocol match.
+      await this.preProcessingForCoreRecordsWrite(tenant, message);
+
+      // NOTE: We allow isLatestBaseState to be true ONLY if the incoming message comes with data, or if the incoming message is NOT an initial write
+      // This would allow an initial write to be written to the DB without data, but having it not queryable,
+      // because query implementation filters on `isLatestBaseState` being `true`
+      // thus preventing a user's attempt to gain authorized access to data by referencing the dataCid of a private data in their initial writes,
+      // See: https://github.com/TBD54566975/dwn-sdk-js/issues/359 for more info
+      let isLatestBaseState = false;
+      let messageWithOptionalEncodedData = message as RecordsQueryReplyEntry;
+
+      if (dataStream !== undefined) {
+        messageWithOptionalEncodedData = await this.processMessageWithDataStream(tenant, message, dataStream);
+        isLatestBaseState = true;
+      } else {
+        // else data stream is NOT provided
+
+        // if the incoming message is not an initial write, and no dataStream is provided, we would allow it provided it passes validation
+        // processMessageWithoutDataStream() abstracts that logic
+        if (!newMessageIsInitialWrite) {
+          const newestExistingWrite = newestExistingMessage as RecordsQueryReplyEntry;
+          messageWithOptionalEncodedData = await this.processMessageWithoutDataStream(tenant, message, newestExistingWrite );
+          isLatestBaseState = true;
+        }
+      }
+
+      const indexes = await recordsWrite.constructIndexes(isLatestBaseState);
+      await this.messageStore.put(tenant, messageWithOptionalEncodedData, indexes);
+      await this.eventLog.append(tenant, await Message.getCid(message), indexes);
+
+      // NOTE: We only emit a `RecordsWrite` when the message is the latest base state.
+      // Because we allow a `RecordsWrite` which is not the latest state to be written, but not queried, we shouldn't emit it either.
+      // It will be emitted as a part of a subsequent next write, if it is the latest base state.
+      if (this.eventStream !== undefined && isLatestBaseState) {
+        this.eventStream.emit(tenant, { message, initialWrite }, indexes);
+      }
+    } catch (error) {
+      const e = error as any;
+      if (e.code !== undefined) {
+        if (e.code === DwnErrorCode.RecordsWriteMissingEncodedDataInPrevious ||
+          e.code === DwnErrorCode.RecordsWriteMissingDataInPrevious ||
+          e.code === DwnErrorCode.RecordsWriteNotAllowedAfterDelete ||
+          e.code === DwnErrorCode.RecordsWriteDataCidMismatch ||
+          e.code === DwnErrorCode.RecordsWriteDataSizeMismatch ||
+          e.code.startsWith('PermissionsProtocolValidate') ||
+          e.code.startsWith('SchemaValidator')) {
+          return messageReplyFromError(error, 400);
+        }
+      }
+
+      // else throw
+      throw error;
+    }
+
+    const messageReply = {
+      // In order to discern between something that was accepted as a queryable write and something that was accepted
+      // as an initial state we use separate response codes. See https://github.com/TBD54566975/dwn-sdk-js/issues/695
+      // for more details.
+      status: (newMessageIsInitialWrite && dataStream === undefined) ?
+        { code: 204, detail: 'No Content' } :
+        { code: 202, detail: 'Accepted' }
+    };
+
+    // delete all existing messages of the same record that are not newest, except for the initial write
+    await StorageController.deleteAllOlderMessagesButKeepInitialWrite(
+      tenant, existingMessages, newestMessage, this.messageStore, this.dataStore, this.eventLog
+    );
+
+    await this.postProcessingForCoreRecordsWrite(tenant, recordsWrite);
+
+    return messageReply;
+  };
+
+  /**
+   * Performs additional necessary validation before storing the RecordsWrite if it is a core DWN RecordsWrite that needs additional processing.
+   * For instance: a Permission revocation RecordsWrite.
+   */
+  private async preProcessingForCoreRecordsWrite(tenant: string, recordsWriteMessage: RecordsWriteMessage): Promise<void> {
+
+    // we validate the protocol tag of the revocation message against the grant's scoped protocol
+    // to do this we will fetch the grant, and compare the the scoped protocol value to the protocol tag of the revocation message
+    if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri &&
+      recordsWriteMessage.descriptor.protocolPath === PermissionsProtocol.revocationPath) {
+
+      // get the parentId of the revocation message, which is the permissionGrantId
+      // fetch the grant in order to get the grant's protocol
+      const permissionGrantId = recordsWriteMessage.descriptor.parentId!;
+      const grant = await PermissionsProtocol.fetchGrant(tenant, this.messageStore, permissionGrantId);
+
+      // get the protocol values of the revocation message from the protocol tag and the protocol from the grant scope if they are defined
+      // compare the two values ensuring they must match
+      const revokeTagProtocol = recordsWriteMessage.descriptor.tags?.protocol;
+      const grantProtocol = 'protocol' in grant.scope ? grant.scope.protocol : undefined;
+      if (grantProtocol !== revokeTagProtocol) {
+        throw new DwnError(
+          DwnErrorCode.PermissionsProtocolValidateRevocationProtocolTagMismatch,
+          `Revocation protocol ${revokeTagProtocol} does not match grant protocol ${grantProtocol}`
+        );
+      }
+    }
+  }
+
+  private static validateSchemaForCoreRecordsWrite(recordsWriteMessage: RecordsWriteMessage, dataBytes: Uint8Array): void {
+    if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri) {
+      PermissionsProtocol.validateSchema(recordsWriteMessage, dataBytes);
+    }
+  }
+
+  /**
+   * Performs additional necessary tasks if the RecordsWrite handled is a core DWN RecordsWrite that need additional processing.
+   * For instance: a Permission revocation RecordsWrite.
+   */
+  private async postProcessingForCoreRecordsWrite(tenant: string, recordsWrite: RecordsWrite): Promise<void> {
+    // If this message is a Permission revocation, we need to delete all grant-authorized messages with timestamp after revocation
+    // TODO: https://github.com/TBD54566975/dwn-sdk-js/issues/716
+    // This code is a direct copy and paste from the original PermissionsRevokeHandler (no longer exists),
+    // but it appears that there was no test for it and it does not look like the code worked:
+    // - not seeing `permissionGrantId` being an index
+    // - not seeing `this.dataStore` being called to delete actual data
+    // - test coverage is missing for the main delete logic
+    if (recordsWrite.message.descriptor.protocol === PermissionsProtocol.uri &&
+      recordsWrite.message.descriptor.protocolPath === PermissionsProtocol.revocationPath) {
+      const permissionGrantId = recordsWrite.message.descriptor.parentId!;
+      const grantAuthorizedMessagesQuery = {
+        permissionGrantId,
+        dateCreated: { gte: recordsWrite.message.descriptor.messageTimestamp },
+      };
+      const { messages: grantAuthorizedMessagesAfterRevoke } = await this.messageStore.query(tenant, [ grantAuthorizedMessagesQuery ]);
+      const grantAuthorizedMessageCidsAfterRevoke: string[] = [];
+      for (const grantAuthorizedMessage of grantAuthorizedMessagesAfterRevoke) {
+        const messageCid = await Message.getCid(grantAuthorizedMessage);
+        await this.messageStore.delete(tenant, messageCid);
+      }
+      this.eventLog.deleteEventsByCid(tenant, grantAuthorizedMessageCidsAfterRevoke);
+    }
+  }
+
+  /**
+   * Returns a `RecordsQueryReplyEntry` with a copy of the incoming message and the incoming data encoded to `Base64URL`.
+   */
+  public async cloneAndAddEncodedData(message: RecordsWriteMessage, dataBytes: Uint8Array):Promise<RecordsQueryReplyEntry> {
+    const recordsWrite: RecordsQueryReplyEntry = { ...message };
+    recordsWrite.encodedData = Encoder.bytesToBase64Url(dataBytes);
+    return recordsWrite;
+  }
+
+  private async processMessageWithDataStream(
+    tenant: string,
+    message: RecordsWriteMessage,
+    dataStream: _Readable.Readable,
+  ):Promise<RecordsQueryReplyEntry> {
+    let messageWithOptionalEncodedData: RecordsQueryReplyEntry = message;
+
+    // if data is below the threshold, we store it within MessageStore
+    if (message.descriptor.dataSize <= DwnConstant.maxDataSizeAllowedToBeEncoded) {
+      // validate data integrity before setting.
+      const dataBytes = await DataStream.toBytes(dataStream!);
+      const dataCid = await Cid.computeDagPbCidFromBytes(dataBytes);
+      RecordsWriteHandler.validateDataIntegrity(message.descriptor.dataCid, message.descriptor.dataSize, dataCid, dataBytes.length);
+
+      RecordsWriteHandler.validateSchemaForCoreRecordsWrite(message, dataBytes);
+
+      messageWithOptionalEncodedData = await this.cloneAndAddEncodedData(message, dataBytes);
+    } else {
+      // split the dataStream into two: one for CID computation and one for storage
+      const [dataStreamCopy1, dataStreamCopy2] = DataStream.duplicateDataStream(dataStream, 2);
+
+      try {
+        // perform storage and CID computation in parallel
+        const [dataCid, DataStorePutResult] = await Promise.all([
+          Cid.computeDagPbCidFromStream(dataStreamCopy1),
+          this.dataStore.put(tenant, message.recordId, message.descriptor.dataCid, dataStreamCopy2)
+        ]);
+
+        RecordsWriteHandler.validateDataIntegrity(message.descriptor.dataCid, message.descriptor.dataSize, dataCid, DataStorePutResult.dataSize);
+      } catch (error) {
+        // unwind/delete data if we have issue with storage or the data failed integrity validation
+        await this.dataStore.delete(tenant, message.recordId, message.descriptor.dataCid);
+
+        throw error;
+      }
+    }
+
+    return messageWithOptionalEncodedData;
+  }
+
+  private async processMessageWithoutDataStream(
+    tenant: string,
+    message: RecordsWriteMessage,
+    newestExistingWrite: RecordsQueryReplyEntry,
+  ):Promise<RecordsQueryReplyEntry> {
+    const messageWithOptionalEncodedData: RecordsQueryReplyEntry = { ...message }; // clone
+    const { dataCid, dataSize } = message.descriptor;
+
+    // Since incoming message is not an initial write, and no dataStream is provided, we first check integrity against newest existing write.
+    // we preform the dataCid check in case a user attempts to gain access to data by referencing a different known dataCid,
+    // so we insure that the data is already associated with the existing newest message
+    // See: https://github.com/TBD54566975/dwn-sdk-js/issues/359 for more info
+    RecordsWriteHandler.validateDataIntegrity(dataCid, dataSize, newestExistingWrite.descriptor.dataCid, newestExistingWrite.descriptor.dataSize);
+
+    if (dataSize <= DwnConstant.maxDataSizeAllowedToBeEncoded) {
+      // we encode the data from the original write if it is smaller than the data-store threshold
+      if (newestExistingWrite.encodedData !== undefined) {
+        messageWithOptionalEncodedData.encodedData = newestExistingWrite.encodedData;
+      } else {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteMissingEncodedDataInPrevious,
+          `No dataStream was provided and unable to get data from previous message`
+        );
+      }
+    } else {
+      // else just make sure the data is in the data store
+
+      // attempt to retrieve the data from the previous message
+      const DataStoreGetResult = await this.dataStore.get(tenant, newestExistingWrite.recordId, message.descriptor.dataCid);
+
+      if (DataStoreGetResult === undefined) {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteMissingDataInPrevious,
+          `No dataStream was provided and unable to get data from previous message`
+        );
+      }
+    }
+
+    return messageWithOptionalEncodedData;
+  }
+
+  /**
+   * Validates the expected `dataCid` and `dataSize` in the descriptor vs the received data.
+   *
+   * @throws {DwnError} with `DwnErrorCode.RecordsWriteDataCidMismatch`
+   *                    if the data stream resulted in a data CID that mismatches with `dataCid` in the given message
+   * @throws {DwnError} with `DwnErrorCode.RecordsWriteDataSizeMismatch`
+   *                    if `dataSize` in `descriptor` given mismatches the actual data size
+   */
+  private static validateDataIntegrity(
+    expectedDataCid: string,
+    expectedDataSize: number,
+    actualDataCid: string,
+    actualDataSize: number
+  ): void {
+    if (expectedDataCid !== actualDataCid) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteDataCidMismatch,
+        `actual data CID ${actualDataCid} does not match dataCid in descriptor: ${expectedDataCid}`
+      );
+    }
+
+    if (expectedDataSize !== actualDataSize) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteDataSizeMismatch,
+        `actual data size ${actualDataSize} bytes does not match dataSize in descriptor: ${expectedDataSize}`
+      );
+    }
+  }
+
+  private static async authorizeRecordsWrite(tenant: string, recordsWrite: RecordsWrite, messageStore: MessageStore): Promise<void> {
+    // if owner signature is given (`owner` is not `undefined`), it must be the same as the tenant DID
+    if (recordsWrite.owner !== undefined && recordsWrite.owner !== tenant) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteOwnerAndTenantMismatch,
+        `Owner ${recordsWrite.owner} must be the same as tenant ${tenant} when specified.`
+      );
+    }
+
+    if (recordsWrite.isSignedByAuthorDelegate) {
+      await recordsWrite.authorizeAuthorDelegate(messageStore);
+    }
+
+    if (recordsWrite.isSignedByOwnerDelegate) {
+      await recordsWrite.authorizeOwnerDelegate(messageStore);
+    }
+
+    if (recordsWrite.owner !== undefined) {
+      // if incoming message is a write retained by this tenant, we by-design always allow
+      // NOTE: the "owner === tenant" check is already done earlier in this method
+      return;
+    } else if (recordsWrite.author === tenant) {
+      // if author is the same as the target tenant, we can directly grant access
+      return;
+    } else if (recordsWrite.author !== undefined && recordsWrite.signaturePayload!.permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, recordsWrite.signaturePayload!.permissionGrantId);
+      await RecordsGrantAuthorization.authorizeWrite({
+        recordsWriteMessage : recordsWrite.message,
+        expectedGrantor     : tenant,
+        expectedGrantee     : recordsWrite.author,
+        permissionGrant,
+        messageStore
+      });
+    } else if (recordsWrite.message.descriptor.protocol !== undefined) {
+      await ProtocolAuthorization.authorizeWrite(tenant, recordsWrite, messageStore);
+    } else {
+      throw new DwnError(DwnErrorCode.RecordsWriteAuthorizationFailed, 'message failed authorization');
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+// export everything that we want to be consumable
+export type { DwnConfig } from './dwn.js';
+export type { EventLog } from './types/event-log.js';
+export type { EventListener, EventStream, EventSubscription, MessageEvent, SubscriptionReply } from './types/subscriptions.js';
+export type { AuthorizationModel, Descriptor, DelegatedGrantRecordsWriteMessage, GenericMessage, GenericMessageReply, GenericSignaturePayload, MessageSort, MessageSubscription, Pagination, QueryResultEntry, Status } from './types/message-types.js';
+export type { MessagesFilter, MessagesReadMessage as MessagesReadMessage, MessagesReadReply as MessagesReadReply, MessagesReadReplyEntry as MessagesReadReplyEntry, MessagesReadDescriptor, MessagesQueryDescriptor, MessagesQueryMessage, MessagesQueryReply, MessagesSubscribeDescriptor, MessagesSubscribeMessage, MessagesSubscribeReply, MessageSubscriptionHandler, MessagesSubscribeMessageOptions } from './types/messages-types.js';
+export type { GT, LT, Filter, FilterValue, KeyValues, EqualFilter, OneOfFilter, RangeFilter, RangeCriterion, PaginationCursor, QueryOptions, RangeValue, StartsWithFilter } from './types/query-types.js';
+export type { ProtocolsConfigureDescriptor, ProtocolDefinition, ProtocolTypes, ProtocolRuleSet, ProtocolsQueryFilter, ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply, ProtocolActionRule, ProtocolPathEncryption, ProtocolsQueryDescriptor, ProtocolType } from './types/protocols-types.js';
+export type { DataEncodedRecordsWriteMessage, EncryptedKey, EncryptionProperty, RecordsDeleteMessage, RecordsFilter, RecordsQueryMessage, RecordsQueryReply, RecordsQueryReplyEntry, RecordsReadMessage, RecordsReadReply, RecordsSubscribeDescriptor, RecordsSubscribeMessage, RecordsSubscribeReply, RecordSubscriptionHandler, RecordsWriteDescriptor, RecordsWriteTags, RecordsWriteTagValue, RecordsWriteMessage, RecordsWriteSignaturePayload, RecordsDeleteDescriptor, RecordsQueryDescriptor, RecordsReadDescriptor, RecordsSubscribeMessageOptions, RecordsWriteMessageOptions, InternalRecordsWriteMessage, RecordEvent, RecordsWriteTagsFilter } from './types/records-types.js';
+export type { GeneralJws, SignatureEntry } from './types/jws-types.js';
+export { authenticate } from './core/auth.js';
+export { ActiveTenantCheckResult, AllowAllTenantGate, TenantGate } from './core/tenant-gate.js';
+export { Cid } from './utils/cid.js';
+export { RecordsQuery, RecordsQueryOptions } from './interfaces/records-query.js';
+export { DataStore, DataStorePutResult, DataStoreGetResult } from './types/data-store.js';
+export { ResumableTaskStore, ManagedResumableTask } from './types/resumable-task-store.js';
+export { DataStream } from './utils/data-stream.js';
+export { DerivedPrivateJwk, HdKey, KeyDerivationScheme } from './utils/hd-key.js';
+export { Dwn, MessageOptions } from './dwn.js';
+export { DwnConstant } from './core/dwn-constant.js';
+export { DwnError, DwnErrorCode } from './core/dwn-error.js';
+export { DwnInterfaceName, DwnMethodName } from './enums/dwn-interface-method.js';
+export { Encoder } from './utils/encoder.js';
+export { MessagesSubscribe as MessagesSubscribe, MessagesSubscribeOptions as MessagesSubscribeOptions } from './interfaces/messages-subscribe.js';
+export { Encryption, EncryptionAlgorithm, EciesEncryptionOutput, EciesEncryptionInput } from './utils/encryption.js';
+export { EncryptionInput, KeyEncryptionInput, RecordsWrite, RecordsWriteOptions, CreateFromOptions } from './interfaces/records-write.js';
+export { executeUnlessAborted } from './utils/abort.js';
+export { Jws } from './utils/jws.js';
+export { KeyMaterial, PrivateJwk, PublicJwk, Jwk } from './types/jose-types.js';
+export { Message } from './core/message.js';
+export { MessagesRead as MessagesRead, MessagesReadOptions as MessagesReadOptions } from './interfaces/messages-read.js';
+export { MessagesQuery, MessagesQueryOptions } from './interfaces/messages-query.js';
+export { UnionMessageReply } from './core/message-reply.js';
+export { MessageStore, MessageStoreOptions } from './types/message-store.js';
+export { MessageInterface } from './types/message-interface.js';
+export { PermissionGrant } from './protocols/permission-grant.js';
+export { PermissionRequest } from './protocols/permission-request.js';
+export { PermissionsProtocol, PermissionGrantCreateOptions, PermissionRequestCreateOptions, PermissionRevocationCreateOptions } from './protocols/permissions.js';
+export { PrivateKeySigner, PrivateKeySignerOptions } from './utils/private-key-signer.js';
+export { Protocols } from './utils/protocols.js';
+export { ProtocolsConfigure, ProtocolsConfigureOptions } from './interfaces/protocols-configure.js';
+export { ProtocolsQuery, ProtocolsQueryOptions } from './interfaces/protocols-query.js';
+export { Records } from './utils/records.js';
+export { RecordsDelete, RecordsDeleteOptions } from './interfaces/records-delete.js';
+export { RecordsRead, RecordsReadOptions } from './interfaces/records-read.js';
+export { RecordsSubscribe, RecordsSubscribeOptions } from './interfaces/records-subscribe.js';
+export { Secp256k1 } from './utils/secp256k1.js';
+export { Secp256r1 } from './utils/secp256r1.js';
+export { Signer } from './types/signer.js';
+export { SortDirection } from './types/query-types.js';
+export { Time } from './utils/time.js';
+export * from './types/permission-types.js';
+export * from './types/records-types.js';
+
+// concrete implementations of stores and event stream
+export { BlockstoreLevel, BlockstoreLevelConfig } from './store/blockstore-level.js';
+export { DataStoreLevel, DataStoreLevelConfig } from './store/data-store-level.js';
+export { EventLogLevel, EventLogLevelConfig } from './event-log/event-log-level.js';
+export { IndexLevel, IndexLevelConfig, IndexedItem, IndexLevelOptions } from './store/index-level.js';
+export { createLevelDatabase, CreateLevelDatabaseOptions, LevelDatabase, LevelWrapper, LevelWrapperConfig, LevelWrapperBatchOperation, LevelWrapperOptions, LevelWrapperIteratorOptions } from './store/level-wrapper.js';
+export { MessageStoreLevel, MessageStoreLevelConfig } from './store/message-store-level.js';
+export { ResumableTaskStoreLevel, ResumableTaskStoreLevelConfig } from './store/resumable-task-store-level.js';
+export { EventEmitterStream, EventEmitterStreamConfig } from './event-log/event-emitter-stream.js';
+
+// test library exports
+export { GenerateFromRecordsWriteOut, GenerateGrantCreateOutput, GenerateMessagesQueryOutput, GenerateMessagesReadOutput, GenerateMessagesSubscribeOutput, GenerateProtocolsConfigureOutput, GenerateProtocolsQueryOutput, GenerateRecordsDeleteOutput, GenerateRecordsQueryOutput, GenerateRecordsSubscribeOutput, GenerateRecordsWriteOutput, Persona, TestDataGenerator, GenerateFromRecordsWriteInput, GenerateGrantCreateInput, GenerateMessagesQueryInput, GenerateMessagesReadInput, GenerateMessagesSubscribeInput, GenerateProtocolsConfigureInput, GenerateProtocolsQueryInput, GenerateRecordsDeleteInput, GenerateRecordsQueryInput, GenerateRecordsSubscribeInput, GenerateRecordsWriteInput } from '../tests/utils/test-data-generator.js';
+export { Poller } from '../tests/utils/poller.js';

package/src/interfaces/messages-query.ts

@@ -0,0 +1,60 @@
+import type { PaginationCursor } from '../types/query-types.js';
+import type { Signer } from '../types/signer.js';
+import type { MessagesFilter, MessagesQueryDescriptor, MessagesQueryMessage } from '../types/messages-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { Message } from '../core/message.js';
+import { Messages } from '../utils/messages.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+import { Time } from '../utils/time.js';
+import { validateProtocolUrlNormalized } from '../utils/url.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export type MessagesQueryOptions = {
+  signer: Signer;
+  filters?: MessagesFilter[];
+  cursor?: PaginationCursor;
+  messageTimestamp?: string;
+  permissionGrantId?: string;
+};
+
+export class MessagesQuery extends AbstractMessage<MessagesQueryMessage>{
+
+  public static async parse(message: MessagesQueryMessage): Promise<MessagesQuery> {
+    Message.validateJsonSchema(message);
+    await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
+
+    for (const filter of message.descriptor.filters) {
+      if ('protocol' in filter && filter.protocol !== undefined) {
+        validateProtocolUrlNormalized(filter.protocol);
+      }
+    }
+
+    return new MessagesQuery(message);
+  }
+
+  public static async create(options: MessagesQueryOptions): Promise<MessagesQuery> {
+    const descriptor: MessagesQueryDescriptor = {
+      interface        : DwnInterfaceName.Messages,
+      method           : DwnMethodName.Query,
+      filters          : options.filters ? Messages.normalizeFilters(options.filters) : [],
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      cursor           : options.cursor,
+    };
+
+    removeUndefinedProperties(descriptor);
+
+    const { permissionGrantId, signer } = options;
+    const authorization = await Message.createAuthorization({
+      descriptor,
+      signer,
+      permissionGrantId
+    });
+
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+
+    return new MessagesQuery(message);
+  }
+}

package/src/interfaces/messages-read.ts

@@ -0,0 +1,63 @@
+import type { Signer } from '../types/signer.js';
+import type { MessagesReadDescriptor, MessagesReadMessage } from '../types/messages-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { Cid } from '../utils/cid.js';
+import { Message } from '../core/message.js';
+import { Time } from '../utils/time.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export type MessagesReadOptions = {
+  messageCid: string;
+  signer: Signer;
+  messageTimestamp?: string;
+  permissionGrantId?: string;
+};
+
+export class MessagesRead extends AbstractMessage<MessagesReadMessage> {
+  public static async parse(message: MessagesReadMessage): Promise<MessagesRead> {
+    Message.validateJsonSchema(message);
+    this.validateMessageCid(message.descriptor.messageCid);
+
+    await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new MessagesRead(message);
+  }
+
+  public static async create(options: MessagesReadOptions): Promise<MessagesRead> {
+    const descriptor: MessagesReadDescriptor = {
+      interface        : DwnInterfaceName.Messages,
+      method           : DwnMethodName.Read,
+      messageCid       : options.messageCid,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+    };
+
+    const { signer, permissionGrantId } = options;
+    const authorization = await Message.createAuthorization({
+      descriptor,
+      signer,
+      permissionGrantId,
+    });
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+    MessagesRead.validateMessageCid(options.messageCid);
+
+    return new MessagesRead(message);
+  }
+
+  /**
+   * validates the provided cid
+   * @param messageCid - the cid in question
+   * @throws {DwnError} if an invalid cid is found.
+   */
+  private static validateMessageCid(messageCid: string): void {
+    try {
+      Cid.parseCid(messageCid);
+    } catch (_) {
+      throw new DwnError(DwnErrorCode.MessagesReadInvalidCid, `${messageCid} is not a valid CID`);
+    }
+  }
+}

package/src/interfaces/messages-subscribe.ts

@@ -0,0 +1,64 @@
+import type { MessagesFilter } from '../types/messages-types.js';
+import type { Signer } from '../types/signer.js';
+import type { MessagesSubscribeDescriptor, MessagesSubscribeMessage } from '../types/messages-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { Message } from '../core/message.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+import { Time } from '../utils/time.js';
+import { validateProtocolUrlNormalized } from '../utils/url.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+
+export type MessagesSubscribeOptions = {
+  signer: Signer;
+  messageTimestamp?: string;
+  filters?: MessagesFilter[]
+  permissionGrantId?: string;
+};
+
+export class MessagesSubscribe extends AbstractMessage<MessagesSubscribeMessage> {
+  public static async parse(message: MessagesSubscribeMessage): Promise<MessagesSubscribe> {
+    Message.validateJsonSchema(message);
+    await Message.validateSignatureStructure(message.authorization.signature, message.descriptor);
+
+    for (const filter of message.descriptor.filters) {
+      if ('protocol' in filter && filter.protocol !== undefined) {
+        validateProtocolUrlNormalized(filter.protocol);
+      }
+    }
+
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+    return new MessagesSubscribe(message);
+  }
+
+  /**
+   * Creates a MessagesSubscribe message.
+   *
+   * @throws {DwnError} if json schema validation fails.
+   */
+  public static async create(
+    options: MessagesSubscribeOptions
+  ): Promise<MessagesSubscribe> {
+    const currentTime = Time.getCurrentTimestamp();
+
+    const descriptor: MessagesSubscribeDescriptor = {
+      interface        : DwnInterfaceName.Messages,
+      method           : DwnMethodName.Subscribe,
+      filters          : options.filters ?? [],
+      messageTimestamp : options.messageTimestamp ?? currentTime,
+    };
+
+    removeUndefinedProperties(descriptor);
+    const { permissionGrantId, signer } = options;
+    const authorization = await Message.createAuthorization({
+      descriptor,
+      signer,
+      permissionGrantId
+    });
+
+    const message: MessagesSubscribeMessage = { descriptor, authorization };
+    Message.validateJsonSchema(message);
+    return new MessagesSubscribe(message);
+  }
+}