@abaxxtech/id 0.0.0

package/src/handlers/records-query.ts

@@ -0,0 +1,253 @@
+import type { DataStore } from '../types/data-store.js';
+import type { DidResolver } from '../did/did-resolver.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { Filter, GenericMessage, MessageSort } from '../types/message-types.js';
+import type { RecordsQueryMessage, RecordsQueryReply, RecordsWriteMessageWithOptionalEncodedData } from '../types/records-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { DateSort } from '../types/records-types.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 { SortOrder } from '../types/message-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: RecordsWriteMessageWithOptionalEncodedData[];
+    let cursor: string|undefined;
+    // if this is an anonymous query and the filter supports published records, query only published records
+    if (RecordsQueryHandler.filterIncludesPublishedRecords(recordsQuery) && recordsQuery.author === undefined) {
+      const results = await this.fetchPublishedRecords(tenant, recordsQuery);
+      recordsWrites = results.messages as RecordsWriteMessageWithOptionalEncodedData[];
+      cursor = results.cursor;
+    } else {
+      // authentication and authorization
+      try {
+        await authenticate(message.authorization!, this.didResolver);
+
+        // Only run protocol authz if message deliberately invokes it
+        if (RecordsQueryHandler.shouldProtocolAuthorizeQuery(recordsQuery)) {
+          await ProtocolAuthorization.authorizeQuery(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 RecordsWriteMessageWithOptionalEncodedData[];
+        cursor = results.cursor;
+      } else {
+        const results = await this.fetchRecordsAsNonOwner(tenant, recordsQuery);
+        recordsWrites = results.messages as RecordsWriteMessageWithOptionalEncodedData[];
+        cursor = results.cursor;
+      }
+    }
+
+    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: SortOrder.Ascending };
+    case DateSort.CreatedDescending:
+      return { dateCreated: SortOrder.Descending };
+    case DateSort.PublishedAscending:
+      return { datePublished: SortOrder.Ascending };
+    case DateSort.PublishedDescending:
+      return { datePublished: SortOrder.Descending };
+    default:
+      return { dateCreated: SortOrder.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?: string }> {
+    const { dateSort, filter, pagination } = recordsQuery.message.descriptor;
+
+    // fetch all published records matching the query
+    const queryFilter = {
+      ...Records.convertFilter(filter),
+      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?: string }> {
+    const { dateSort, pagination } = recordsQuery.message.descriptor;
+    const filters: any[] = [];
+
+    if (RecordsQueryHandler.filterIncludesPublishedRecords(recordsQuery)) {
+      filters.push(RecordsQueryHandler.buildPublishedRecordsFilter(recordsQuery));
+    }
+
+    if (RecordsQueryHandler.filterIncludesUnpublishedRecords(recordsQuery)) {
+      filters.push(RecordsQueryHandler.buildUnpublishedRecordsByQueryAuthorFilter(recordsQuery));
+
+      const recipientFilter = recordsQuery.message.descriptor.filter.recipient;
+      if (recipientFilter === undefined || recipientFilter === recordsQuery.author) {
+        filters.push(RecordsQueryHandler.buildUnpublishedRecordsForQueryAuthorFilter(recordsQuery));
+      }
+
+      if (RecordsQueryHandler.shouldProtocolAuthorizeQuery(recordsQuery)) {
+        filters.push(RecordsQueryHandler.buildUnpublishedProtocolAuthorizedRecordsFilter(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?: string }> {
+    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 {
+    // fetch all published records matching the query
+    return {
+      ...Records.convertFilter(recordsQuery.message.descriptor.filter),
+      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 {
+    // include records where recipient is query author
+    return {
+      ...Records.convertFilter(recordsQuery.message.descriptor.filter),
+      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 {
+    return {
+      ...Records.convertFilter(recordsQuery.message.descriptor.filter),
+      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 {
+    // include records where author is the same as the query author
+    return {
+      ...Records.convertFilter(recordsQuery.message.descriptor.filter),
+      author            : recordsQuery.author!,
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      isLatestBaseState : true,
+      published         : false
+    };
+  }
+
+  /**
+   * Determines if ProtocolAuthorization.authorizeQuery should be run and if the corresponding filter should be used.
+   */
+  private static shouldProtocolAuthorizeQuery(recordsQuery: RecordsQuery): boolean {
+    return recordsQuery.signaturePayload!.protocolRole !== undefined;
+  }
+
+  /**
+   * Checks if the recordQuery filter supports returning published records.
+   */
+  private static filterIncludesPublishedRecords(recordsQuery: RecordsQuery): boolean {
+    const { filter } = recordsQuery.message.descriptor;
+    // When `published` and `datePublished` range are both undefined, published records can be returned.
+    return filter.datePublished !== undefined || filter.published !== false;
+  }
+
+  /**
+   * Checks if the recordQuery filter supports returning unpublished records.
+   */
+  private static filterIncludesUnpublishedRecords(recordsQuery: RecordsQuery): boolean {
+    const { filter } = recordsQuery.message.descriptor;
+    // When `published` and `datePublished` range are both undefined, unpublished records can be returned.
+    if (filter.datePublished === undefined && filter.published === undefined) {
+      return true;
+    }
+    return filter.published === false;
+  }
+}

package/src/handlers/records-read.ts

@@ -0,0 +1,127 @@
+import type { DataStore } from '../types/data-store.js';
+import type { DidResolver } from '../did/did-resolver.js';
+import type { Filter } from '../types/message-types.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { RecordsReadMessage, RecordsReadReply, RecordsWriteMessageWithOptionalEncodedData } from '../types/records-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { DataStream } from '../utils/data-stream.js';
+import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
+import { Encoder } from '../utils/encoder.js';
+import { GrantAuthorization } from '../core/grant-authorization.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 { 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';
+
+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
+    // only RecordsWrite messages will be returned due to 'isLatestBaseState' being set to true.
+    const query: Filter = {
+      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 newestRecordsWrite = existingMessages[0] as RecordsWriteMessageWithOptionalEncodedData;
+    try {
+      await RecordsReadHandler.authorizeRecordsRead(tenant, recordsRead, await RecordsWrite.parse(newestRecordsWrite), this.messageStore);
+    } catch (error) {
+      return messageReplyFromError(error, 401);
+    }
+
+    let data;
+    if (newestRecordsWrite.encodedData !== undefined) {
+      const dataBytes = Encoder.base64UrlToBytes(newestRecordsWrite.encodedData);
+      data = DataStream.fromBytes(dataBytes);
+      delete newestRecordsWrite.encodedData;
+    } else {
+      const messageCid = await Message.getCid(newestRecordsWrite);
+      const result = await this.dataStore.get(tenant, messageCid, newestRecordsWrite.descriptor.dataCid);
+      if (result?.dataStream === undefined) {
+        return {
+          status: { code: 404, detail: 'Not Found' }
+        };
+      }
+      data = result.dataStream;
+    }
+
+    const messageReply: RecordsReadReply = {
+      status : { code: 200, detail: 'OK' },
+      record : {
+        ...newestRecordsWrite,
+        data,
+      }
+    };
+    return messageReply;
+  };
+
+  private static async authorizeRecordsRead(
+    tenant: string,
+    recordsRead: RecordsRead,
+    newestRecordsWrite: RecordsWrite,
+    messageStore: MessageStore
+  ): Promise<void> {
+    const { descriptor } = newestRecordsWrite.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) {
+      // The recipient of a message may always read it
+      return;
+    } else if (recordsRead.author !== undefined && recordsRead.signaturePayload!.permissionsGrantId !== undefined) {
+      const permissionsGrantMessage = await GrantAuthorization.fetchGrant(tenant, messageStore, recordsRead.signaturePayload!.permissionsGrantId);
+      await RecordsGrantAuthorization.authorizeRead(
+        tenant, recordsRead, newestRecordsWrite.message, recordsRead.author, permissionsGrantMessage, messageStore
+      );
+    } else if (descriptor.protocol !== undefined) {
+      await ProtocolAuthorization.authorizeRead(tenant, recordsRead, newestRecordsWrite, messageStore);
+    } else {
+      throw new DwnError(DwnErrorCode.RecordsReadAuthorizationFailed, 'message failed authorization');
+    }
+  }
+}

package/src/handlers/records-write.ts

@@ -0,0 +1,296 @@
+import type { DataStore } from '../types/data-store.js';
+import type { DidResolver } from '../did/did-resolver.js';
+import type { EventLog } from '../types/event-log.js';
+import type { GenericMessageReply } from '../core/message-reply.js';
+import type { MessageStore } from '../types//message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { RecordsDeleteMessage, RecordsWriteMessage, RecordsWriteMessageWithOptionalEncodedData } 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 { GrantAuthorization } from '../core/grant-authorization.js';
+import { Message } from '../core/message.js';
+import { messageReplyFromError } from '../core/message-reply.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';
+
+export type RecordsWriteHandlerOptions = {
+  skipDataStorage?: boolean; // used for DWN sync
+};
+
+type HandlerArgs = { tenant: string, message: RecordsWriteMessage, options?: RecordsWriteHandlerOptions, dataStream?: _Readable.Readable};
+
+export class RecordsWriteHandler implements MethodHandler {
+
+  constructor(private didResolver: DidResolver, private messageStore: MessageStore, private dataStore: DataStore, private eventLog: EventLog) { }
+
+  public async handle({
+    tenant,
+    message,
+    options,
+    dataStream
+  }: HandlerArgs): Promise<GenericMessageReply> {
+    let recordsWrite: RecordsWrite;
+    try {
+      recordsWrite = await RecordsWrite.parse(message);
+
+      // Protocol 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 this exact message already exists, treat as idempotent no-op.
+    // This makes sync convergent: receiving the same message twice is always safe.
+    const incomingMessageCid = await Message.getCid(message);
+    for (const existingMessage of existingMessages) {
+      const existingCid = await Message.getCid(existingMessage);
+      if (existingCid === incomingMessageCid) {
+        return { status: { code: 202, detail: 'Accepted' } };
+      }
+    }
+
+
+    // 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();
+    if (!newMessageIsInitialWrite) {
+      try {
+        const 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' }
+      };
+    }
+
+    const isLatestBaseState = true;
+    const indexes = await recordsWrite.constructRecordsWriteIndexes(isLatestBaseState);
+
+    // if data is below a certain threshold, we embed the data directly into the message for storage in MessageStore.
+    let messageWithOptionalEncodedData: RecordsWriteMessageWithOptionalEncodedData = message;
+
+    // try to store data, unless options explicitly say to skip storage
+    if (options === undefined || !options.skipDataStorage) {
+      if (dataStream === undefined && newestExistingMessage?.descriptor.method === DwnMethodName.Delete) {
+        return messageReplyFromError(new DwnError(DwnErrorCode.RecordsWriteMissingDataStream, 'No data stream was provided with the previous message being a delete'), 400);
+      }
+
+      try {
+        // if data is below the threshold, we store it within MessageStore
+        if (message.descriptor.dataSize <= DwnConstant.maxDataSizeAllowedToBeEncoded) {
+          // processes and sets `encodedData` with appropriate data.
+          messageWithOptionalEncodedData = await this.processEncodedData(
+            message,
+            dataStream,
+            newestExistingMessage as (RecordsWriteMessage|RecordsDeleteMessage) | undefined
+          );
+        } else {
+          await this.putData(tenant, message, dataStream);
+        }
+      } catch (error) {
+        const e = error as any;
+        if (e.code === DwnErrorCode.RecordsWriteMissingDataInPrevious ||
+            e.code === DwnErrorCode.RecordsWriteMissingDataAssociation ||
+            e.code === DwnErrorCode.RecordsWriteDataCidMismatch ||
+            e.code === DwnErrorCode.RecordsWriteDataSizeMismatch) {
+          return messageReplyFromError(error, 400);
+        }
+
+        // else throw
+        throw error;
+      }
+    }
+
+    await this.messageStore.put(tenant, messageWithOptionalEncodedData, indexes);
+    await this.eventLog.append(tenant, await Message.getCid(message));
+
+    const messageReply = {
+      status: { code: 202, detail: 'Accepted' }
+    };
+
+    // delete all existing messages that are not newest, except for the initial write
+    await StorageController.deleteAllOlderMessagesButKeepInitialWrite(
+      tenant, existingMessages, newestMessage, this.messageStore, this.dataStore, this.eventLog
+    );
+
+    return messageReply;
+  };
+
+  /**
+   * Embeds the record's data into the `encodedData` property.
+   * If dataStream is present, it uses the dataStream. Otherwise, uses the `encodedData` from the most recent RecordsWrite.
+   *
+   * @returns {RecordsWriteMessageWithOptionalEncodedData} `encodedData` embedded.
+   *
+   * @throws {DwnError} with `DwnErrorCode.RecordsWriteMissingDataInPrevious`
+   *                    if `dataStream` is absent AND `encodedData` of previous message is missing
+   * @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
+   */
+  public async processEncodedData(
+    message: RecordsWriteMessage,
+    dataStream?: _Readable.Readable,
+    newestExistingMessage?: RecordsWriteMessage | RecordsDeleteMessage
+  ): Promise<RecordsWriteMessageWithOptionalEncodedData> {
+    let dataBytes;
+    if (dataStream === undefined) {
+      const newestWithData = newestExistingMessage as RecordsWriteMessageWithOptionalEncodedData | undefined;
+      if (newestWithData?.encodedData === undefined) {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteMissingDataInPrevious,
+          `No dataStream was provided and unable to get data from previous message`
+        );
+      } else {
+        dataBytes = Encoder.base64UrlToBytes(newestWithData.encodedData);
+      }
+    } else {
+      dataBytes = await DataStream.toBytes(dataStream);
+    }
+
+    const dataCid = await Cid.computeDagPbCidFromBytes(dataBytes);
+    RecordsWriteHandler.validateDataIntegrity(message.descriptor.dataCid, message.descriptor.dataSize, dataCid, dataBytes.length);
+
+    const recordsWrite: RecordsWriteMessageWithOptionalEncodedData = { ...message };
+    recordsWrite.encodedData = Encoder.bytesToBase64Url(dataBytes);
+    return recordsWrite;
+  }
+
+  /**
+   * Puts the given data in storage unless tenant already has that data for the given recordId
+   *
+   * @throws {DwnError} with `DwnErrorCode.RecordsWriteMissingDataAssociation`
+   *                    if `dataStream` is absent AND unable to associate data given `dataCid`
+   * @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
+   */
+  public async putData(
+    tenant: string,
+    message: RecordsWriteMessage,
+    dataStream?: _Readable.Readable,
+  ): Promise<void> {
+    let result: { dataCid: string, dataSize: number };
+    const messageCid = await Message.getCid(message);
+
+    if (dataStream === undefined) {
+      const associateResult = await this.dataStore.associate(tenant, messageCid, message.descriptor.dataCid);
+      if (associateResult === undefined) {
+        throw new DwnError(DwnErrorCode.RecordsWriteMissingDataAssociation, `Unable to associate dataCid ${message.descriptor.dataCid} ` +
+          `to messageCid ${messageCid} because dataStream was not provided and data was not found in dataStore`);
+      }
+      result = associateResult;
+    } else {
+      result = await this.dataStore.put(tenant, messageCid, message.descriptor.dataCid, dataStream);
+    }
+
+    try {
+      RecordsWriteHandler.validateDataIntegrity(message.descriptor.dataCid, message.descriptor.dataSize, result.dataCid, result.dataSize);
+    } catch (error) {
+      // delete data and throw error to caller
+      await this.dataStore.delete(tenant, messageCid, message.descriptor.dataCid);
+      throw error;
+    }
+  }
+
+  /**
+   * 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
+   */
+  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 DID is specified, 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.isSignedByDelegatee) {
+      await recordsWrite.authorizeDelegatee(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!.permissionsGrantId !== undefined) {
+      const permissionsGrantMessage = await GrantAuthorization.fetchGrant(tenant, messageStore, recordsWrite.signaturePayload!.permissionsGrantId);
+      await RecordsGrantAuthorization.authorizeWrite(tenant, recordsWrite.message, recordsWrite.author, permissionsGrantMessage, messageStore);
+    } else if (recordsWrite.message.descriptor.protocol !== undefined) {
+      await ProtocolAuthorization.authorizeWrite(tenant, recordsWrite, messageStore);
+    } else {
+      throw new DwnError(DwnErrorCode.RecordsWriteAuthorizationFailed, 'message failed authorization');
+    }
+  }
+
+}