@abaxxtech/id 0.0.0

package/src/core/auth.ts

@@ -0,0 +1,108 @@
+import type { DidResolver } from '../did/did-resolver.js';
+import type { GeneralJws } from '../types/jws-types.js';
+import type { AuthorizationModel, Descriptor, GenericSignaturePayload } from '../types/message-types.js';
+
+import { Cid } from '../utils/cid.js';
+import { GeneralJwsVerifier } from '../jose/jws/general/verifier.js';
+import { Jws } from '../utils/jws.js';
+import { PermissionsGrant } from '../interfaces/permissions-grant.js';
+import { validateJsonSchema } from '../schema-validator.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+export class Authenticate {
+
+  /**
+   * Verifies all the signature(s) within the authorization property.
+   * @throws {Error} if fails authentication
+   */
+  public static async authenticate(authorizationModel: AuthorizationModel | undefined, didResolver: DidResolver): Promise<void> {
+
+    if (authorizationModel === undefined) {
+      throw new DwnError(DwnErrorCode.AuthenticateJwsMissing, 'Missing JWS.');
+    }
+
+    await GeneralJwsVerifier.verifySignatures(authorizationModel.signature, didResolver);
+
+    if (authorizationModel.ownerSignature !== undefined) {
+      await GeneralJwsVerifier.verifySignatures(authorizationModel.ownerSignature, didResolver);
+    }
+
+    if (authorizationModel.authorDelegatedGrant !== undefined) {
+      // verify the signature of the grantor of the delegated grant
+      const authorDelegatedGrant = await PermissionsGrant.parse(authorizationModel.authorDelegatedGrant);
+      await GeneralJwsVerifier.verifySignatures(authorDelegatedGrant.message.authorization.signature, didResolver);
+    }
+
+  }
+};
+
+/**
+ * Validates the structural integrity of the message signature given.
+ * NOTE: signature is not verified.
+ * @param payloadJsonSchemaKey The key to look up the JSON schema referenced in `compile-validators.js` and perform payload schema validation on.
+ * @returns the parsed JSON payload object if validation succeeds.
+ */
+export async function validateMessageSignatureIntegrity(
+  messageSignature: GeneralJws,
+  messageDescriptor: Descriptor,
+  payloadJsonSchemaKey: string = 'GenericSignaturePayload',
+): Promise<GenericSignaturePayload> {
+
+  if (messageSignature.signatures.length !== 1) {
+    throw new DwnError(DwnErrorCode.AuthenticationMoreThanOneSignatureNotSupported, 'expected no more than 1 signature for authorization purpose');
+  }
+
+  // validate payload integrity
+  const payloadJson = Jws.decodePlainObjectPayload(messageSignature);
+
+  validateJsonSchema(payloadJsonSchemaKey, payloadJson);
+
+  // `descriptorCid` validation - ensure that the provided descriptorCid matches the CID of the actual message
+  const { descriptorCid } = payloadJson;
+  const expectedDescriptorCid = await Cid.computeCid(messageDescriptor);
+  if (descriptorCid !== expectedDescriptorCid) {
+    throw new DwnError(
+      DwnErrorCode.AuthenticateDescriptorCidMismatch,
+      `provided descriptorCid ${descriptorCid} does not match expected CID ${expectedDescriptorCid}`
+    );
+  }
+
+  return payloadJson;
+}
+
+/**
+ * Verifies all the signature(s) within the authorization property.
+ * @throws {Error} if fails authentication
+ */
+export async function authenticate(authorizationModel: AuthorizationModel | undefined, didResolver: DidResolver): Promise<void> {
+
+  if (authorizationModel === undefined) {
+    throw new DwnError(DwnErrorCode.AuthenticateJwsMissing, 'Missing JWS.');
+  }
+
+  await GeneralJwsVerifier.verifySignatures(authorizationModel.signature, didResolver);
+
+  if (authorizationModel.ownerSignature !== undefined) {
+    await GeneralJwsVerifier.verifySignatures(authorizationModel.ownerSignature, didResolver);
+  }
+
+  if (authorizationModel.authorDelegatedGrant !== undefined) {
+    // verify the signature of the grantor of the delegated grant
+    const authorDelegatedGrant = await PermissionsGrant.parse(authorizationModel.authorDelegatedGrant);
+    await GeneralJwsVerifier.verifySignatures(authorDelegatedGrant.message.authorization.signature, didResolver);
+  }
+
+}
+
+/**
+ * Authorizes the incoming message.
+ * @throws {Error} if fails authentication
+ */
+export async function authorize(tenant: string, incomingMessage: { author: string | undefined }): Promise<void> {
+  // if author is the same as the target tenant, we can directly grant access
+  if (incomingMessage.author === tenant) {
+    return;
+  } else {
+    throw new DwnError(DwnErrorCode.AuthorizationUnknownAuthor, 'message failed authorization, permission grant check not yet implemented');
+  }
+}

package/src/core/dwn-constant.ts

@@ -0,0 +1,7 @@
+export class DwnConstant {
+  /**
+   * The maximum size in bytes of raw data that will be returned as `encodedData`.
+   * this is also the maximum size that we will store within MessageStore.
+   */
+  public static readonly maxDataSizeAllowedToBeEncoded = 50_000;
+}

package/src/core/dwn-error.ts

@@ -0,0 +1,136 @@
+/**
+ * A class that represents a DWN error.
+ */
+export class DwnError extends Error {
+  constructor (public code: string, message: string) {
+    super(`${code}: ${message}`);
+
+    this.name = 'DwnError';
+  }
+}
+
+/**
+ * DWN SDK error codes.
+ */
+export enum DwnErrorCode {
+  AuthenticateJwsMissing = 'AuthenticateJwsMissing',
+  AuthenticateDescriptorCidMismatch = 'AuthenticateDescriptorCidMismatch',
+  AuthenticationMoreThanOneSignatureNotSupported = 'AuthenticationMoreThanOneSignatureNotSupported',
+  AuthorizationUnknownAuthor = 'AuthorizationUnknownAuthor',
+  AuthorizationNotGrantedToAuthor = 'AuthorizationNotGrantedToAuthor',
+  ComputeCidCodecNotSupported = 'ComputeCidCodecNotSupported',
+  ComputeCidMultihashNotSupported = 'ComputeCidMultihashNotSupported',
+  DidMethodNotSupported = 'DidMethodNotSupported',
+  DidNotString = 'DidNotString',
+  DidNotValid = 'DidNotValid',
+  DidResolutionFailed = 'DidResolutionFailed',
+  Ed25519InvalidJwk = 'Ed25519InvalidJwk',
+  GeneralJwsVerifierGetPublicKeyNotFound = 'GeneralJwsVerifierGetPublicKeyNotFound',
+  GeneralJwsVerifierInvalidSignature = 'GeneralJwsVerifierInvalidSignature',
+  GrantAuthorizationGrantExpired = 'GrantAuthorizationGrantExpired',
+  GrantAuthorizationGrantMissing = 'GrantAuthorizationGrantMissing',
+  GrantAuthorizationGrantRevoked = 'GrantAuthorizationGrantRevoked',
+  GrantAuthorizationInterfaceMismatch = 'GrantAuthorizationInterfaceMismatch',
+  GrantAuthorizationMethodMismatch = 'GrantAuthorizationMethodMismatch',
+  GrantAuthorizationNotGrantedForTenant = 'GrantAuthorizationNotGrantedForTenant',
+  GrantAuthorizationNotGrantedToAuthor = 'GrantAuthorizationNotGrantedToAuthor',
+  GrantAuthorizationGrantNotYetActive = 'GrantAuthorizationGrantNotYetActive',
+  HdKeyDerivationPathInvalid = 'HdKeyDerivationPathInvalid',
+  JwsVerifySignatureUnsupportedCrv = 'JwsVerifySignatureUnsupportedCrv',
+  JwsDecodePlainObjectPayloadInvalid = 'JwsDecodePlainObjectPayloadInvalid',
+  MessageGetInvalidCid = 'MessageGetInvalidCid',
+  ParseCidCodecNotSupported = 'ParseCidCodecNotSupported',
+  ParseCidMultihashNotSupported = 'ParseCidMultihashNotSupported',
+  PermissionsGrantGrantedByMismatch = 'PermissionsGrantGrantedByMismatch',
+  PermissionsGrantNotADelegatedGrant = 'PermissionsGrantNotADelegatedGrant',
+  PermissionsGrantScopeContextIdAndProtocolPath = 'PermissionsGrantScopeContextIdAndProtocolPath',
+  PermissionsGrantScopeSchemaProhibitedFields = 'PermissionsGrantScopeSchemaProhibitedFields',
+  PermissionsGrantUnauthorizedGrant = 'PermissionsGrantUnauthorizedGrant',
+  PermissionsRevokeMissingPermissionsGrant = 'PermissionsRevokeMissingPermissionsGrant',
+  PermissionsRevokeUnauthorizedRevoke = 'PermissionsRevokeUnauthorizedRevoke',
+  PrivateKeySignerUnableToDeduceAlgorithm = 'PrivateKeySignerUnableToDeduceAlgorithm',
+  PrivateKeySignerUnableToDeduceKeyId = 'PrivateKeySignerUnableToDeduceKeyId',
+  PrivateKeySignerUnsupportedCurve = 'PrivateKeySignerUnsupportedCurve',
+  ProtocolAuthorizationActionNotAllowed = 'ProtocolAuthorizationActionNotAllowed',
+  ProtocolAuthorizationActionRulesNotFound = 'ProtocolAuthorizationActionRulesNotFound',
+  ProtocolAuthorizationDuplicateContextRoleRecipient = 'ProtocolAuthorizationDuplicateContextRoleRecipient',
+  ProtocolAuthorizationDuplicateGlobalRoleRecipient = 'ProtocolAuthorizationDuplicateGlobalRoleRecipient',
+  ProtocolAuthorizationIncorrectDataFormat = 'ProtocolAuthorizationIncorrectDataFormat',
+  ProtocolAuthorizationIncorrectProtocolPath = 'ProtocolAuthorizationIncorrectProtocolPath',
+  ProtocolAuthorizationInvalidSchema = 'ProtocolAuthorizationInvalidSchema',
+  ProtocolAuthorizationInvalidType = 'ProtocolAuthorizationInvalidType',
+  ProtocolAuthorizationMissingContextId = 'ProtocolAuthorizationMissingContextId',
+  ProtocolAuthorizationMissingRole = 'ProtocolAuthorizationMissingRole',
+  ProtocolAuthorizationMissingRuleSet = 'ProtocolAuthorizationMissingRuleSet',
+  ProtocolAuthorizationParentlessIncorrectProtocolPath = 'ProtocolAuthorizationParentlessIncorrectProtocolPath',
+  ProtocolAuthorizationNotARole = 'ProtocolAuthorizationNotARole',
+  ProtocolAuthorizationParentNotFound = 'ProtocolAuthorizationParentNotFound',
+  ProtocolAuthorizationProtocolNotFound = 'ProtocolAuthorizationProtocolNotFound',
+  ProtocolAuthorizationQueryWithoutRole = 'ProtocolAuthorizationQueryWithoutRole',
+  ProtocolAuthorizationRoleMissingRecipient = 'ProtocolAuthorizationRoleMissingRecipient',
+  ProtocolsConfigureContextRoleAtProhibitedProtocolPath = 'ProtocolsConfigureContextRoleAtProhibitedProtocolPath',
+  ProtocolsConfigureGlobalRoleAtProhibitedProtocolPath = 'ProtocolsConfigureGlobalRoleAtProhibitedProtocolPath',
+  ProtocolsConfigureInvalidRole = 'ProtocolsConfigureInvalidRole',
+  ProtocolsConfigureInvalidActionMissingOf = 'ProtocolsConfigureInvalidActionMissingOf',
+  ProtocolsConfigureInvalidActionOfNotAllowed = 'ProtocolsConfigureInvalidActionOfNotAllowed',
+  ProtocolsConfigureInvalidRecipientOfAction = 'ProtocolsConfigureInvalidRecipientOfAction',
+  ProtocolsConfigureQueryNotAllowed = 'ProtocolsConfigureQueryNotAllowed',
+  ProtocolsConfigureUnauthorized = 'ProtocolsConfigureUnauthorized',
+  ProtocolsQueryUnauthorized = 'ProtocolsQueryUnauthorized',
+  RecordsDecryptNoMatchingKeyEncryptedFound = 'RecordsDecryptNoMatchingKeyEncryptedFound',
+  RecordsDeleteAuthorizationFailed = 'RecordsDeleteAuthorizationFailed',
+  RecordsGrantAuthorizationConditionPublicationProhibited = 'RecordsGrantAuthorizationConditionPublicationProhibited',
+  RecordsGrantAuthorizationConditionPublicationRequired = 'RecordsGrantAuthorizationConditionPublicationRequired',
+  RecordsGrantAuthorizationScopeContextIdMismatch = 'RecordsGrantAuthorizationScopeContextIdMismatch',
+  RecordsGrantAuthorizationScopeNotProtocol = 'RecordsGrantAuthorizationScopeNotProtocol',
+  RecordsGrantAuthorizationScopeProtocolMismatch = 'RecordsGrantAuthorizationScopeProtocolMismatch',
+  RecordsGrantAuthorizationScopeProtocolPathMismatch = 'RecordsGrantAuthorizationScopeProtocolPathMismatch',
+  RecordsGrantAuthorizationScopeSchema = 'RecordsGrantAuthorizationScopeSchema',
+  RecordsDerivePrivateKeyUnSupportedCurve = 'RecordsDerivePrivateKeyUnSupportedCurve',
+  RecordsInvalidAncestorKeyDerivationSegment = 'RecordsInvalidAncestorKeyDerivationSegment',
+  RecordsProtocolContextDerivationSchemeMissingContextId = 'RecordsProtocolContextDerivationSchemeMissingContextId',
+  RecordsProtocolPathDerivationSchemeMissingProtocol = 'RecordsProtocolPathDerivationSchemeMissingProtocol',
+  RecordsQueryFilterMissingRequiredProperties = 'RecordsQueryFilterMissingRequiredProperties',
+  RecordsReadReturnedMultiple = 'RecordsReadReturnedMultiple',
+  RecordsReadAuthorizationFailed = 'RecordsReadAuthorizationFailed',
+  RecordsSchemasDerivationSchemeMissingSchema = 'RecordsSchemasDerivationSchemeMissingSchema',
+  RecordsValidateIntegrityDelegatedGrantAndIdExistenceMismatch = 'RecordsValidateIntegrityDelegatedGrantAndIdExistenceMismatch',
+  RecordsValidateIntegrityGrantedToAndSignerMismatch = 'RecordsValidateIntegrityGrantedToAndSignerMismatch',
+  RecordsWriteAttestationIntegrityMoreThanOneSignature = 'RecordsWriteAttestationIntegrityMoreThanOneSignature',
+  RecordsWriteAttestationIntegrityDescriptorCidMismatch = 'RecordsWriteAttestationIntegrityDescriptorCidMismatch',
+  RecordsWriteAttestationIntegrityInvalidPayloadProperty = 'RecordsWriteAttestationIntegrityInvalidPayloadProperty',
+  RecordsWriteAuthorizationFailed = 'RecordsWriteAuthorizationFailed',
+  RecordsWriteCreateMissingSigner = 'RecordsWriteCreateMissingSigner',
+  RecordsWriteCreateContextIdAndParentIdMutuallyInclusive = 'RecordsWriteCreateContextIdAndParentIdMutuallyInclusive',
+  RecordsWriteCreateDataAndDataCidMutuallyExclusive = 'RecordsWriteCreateDataAndDataCidMutuallyExclusive',
+  RecordsWriteCreateDataCidAndDataSizeMutuallyInclusive = 'RecordsWriteCreateDataCidAndDataSizeMutuallyInclusive',
+  RecordsWriteCreateProtocolAndProtocolPathMutuallyInclusive = 'RecordsWriteCreateProtocolAndProtocolPathMutuallyInclusive',
+  RecordsWriteDataCidMismatch = 'RecordsWriteDataCidMismatch',
+  RecordsWriteDataSizeMismatch = 'RecordsWriteDataSizeMismatch',
+  RecordsWriteGetEntryIdUndefinedAuthor = 'RecordsWriteGetEntryIdUndefinedAuthor',
+  RecordsWriteGetInitialWriteNotFound = 'RecordsWriteGetInitialWriteNotFound',
+  RecordsWriteImmutablePropertyChanged = 'RecordsWriteImmutablePropertyChanged',
+  RecordsWriteMissingAuthorizationSigner = 'RecordsWriteMissingAuthorizationSigner',
+  RecordsWriteMissingSigner = 'RecordsWriteMissingSigner',
+  RecordsWriteMissingDataInPrevious = 'RecordsWriteMissingDataInPrevious',
+  RecordsWriteMissingDataAssociation = 'RecordsWriteMissingDataAssociation',
+  RecordsWriteMissingDataStream = 'RecordsWriteMissingDataStream',
+  RecordsWriteMissingProtocol = 'RecordsWriteMissingProtocol',
+  RecordsWriteMissingSchema = 'RecordsWriteMissingSchema',
+  RecordsWriteOwnerAndTenantMismatch = 'RecordsWriteOwnerAndTenantMismatch',
+  RecordsWriteSignAsOwnerUnknownAuthor = 'RecordsWriteSignAsOwnerUnknownAuthor',
+  RecordsWriteValidateIntegrityAttestationMismatch = 'RecordsWriteValidateIntegrityAttestationMismatch',
+  RecordsWriteValidateIntegrityContextIdMismatch = 'RecordsWriteValidateIntegrityContextIdMismatch',
+  RecordsWriteValidateIntegrityContextIdNotInSignerSignaturePayload = 'RecordsWriteValidateIntegrityContextIdNotInSignerSignaturePayload',
+  RecordsWriteValidateIntegrityDateCreatedMismatch = 'RecordsWriteValidateIntegrityDateCreatedMismatch',
+  RecordsWriteValidateIntegrityEncryptionCidMismatch = 'RecordsWriteValidateIntegrityEncryptionCidMismatch',
+  RecordsWriteValidateIntegrityRecordIdUnauthorized = 'RecordsWriteValidateIntegrityRecordIdUnauthorized',
+  SchemaValidatorSchemaNotFound = 'SchemaValidatorSchemaNotFound',
+  SchemaValidationFailure = 'SchemaValidationFailure',
+  Secp256k1KeyNotValid = 'Secp256k1KeyNotValid',
+  TimestampInvalid = 'TimestampInvalid',
+  UrlProtocolNotNormalized = 'UrlProtocolNotNormalized',
+  UrlProtocolNotNormalizable = 'UrlProtocolNotNormalizable',
+  UrlSchemaNotNormalized = 'UrlSchemaNotNormalized',
+  UrlSchemaNotNormalizable = 'UrlSchemaNotNormalizable',
+};

package/src/core/grant-authorization.ts

@@ -0,0 +1,163 @@
+import type { GenericMessage } from '../types/message-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { PermissionsGrantMessage } from '../types/permissions-types.js';
+
+import { Message } from './message.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export class GrantAuthorization {
+
+  /**
+   * Performs PermissionsGrant-based authorization against the given message
+   * Does not validate grant `conditions` or `scope` beyond `interface` and `method`
+   * @throws {DwnError} if authorization fails
+   */
+  public static async authorizeGenericMessage(
+    tenant: string,
+    incomingMessage: GenericMessage,
+    author: string,
+    permissionsGrantMessage: PermissionsGrantMessage,
+    messageStore: MessageStore,
+  ): Promise<void> {
+
+    const incomingMessageDescriptor = incomingMessage.descriptor;
+    const permissionsGrantId = await Message.getCid(permissionsGrantMessage);
+
+    GrantAuthorization.verifyGrantedToAndGrantedFor(author, tenant, permissionsGrantMessage);
+
+    // verify that grant is active during incomingMessage's timestamp
+    await GrantAuthorization.verifyGrantActive(
+      tenant,
+      incomingMessageDescriptor.messageTimestamp,
+      permissionsGrantMessage,
+      permissionsGrantId,
+      messageStore
+    );
+
+    // Check grant scope for interface and method
+    await GrantAuthorization.verifyGrantScopeInterfaceAndMethod(
+      incomingMessageDescriptor.interface,
+      incomingMessageDescriptor.method,
+      permissionsGrantMessage,
+      permissionsGrantId
+    );
+  }
+
+  /**
+   * Fetches PermissionsGrantMessage with CID `permissionsGrantId`.
+   * @returns the PermissionsGrantMessage with CID `permissionsGrantId` if message exists
+   * @throws {Error} if PermissionsGrantMessage with CID `permissionsGrantId` does not exist
+   */
+  public static async fetchGrant(
+    tenant: string,
+    messageStore: MessageStore,
+    permissionsGrantId: string,
+  ): Promise<PermissionsGrantMessage> {
+    const possibleGrantMessage: GenericMessage | undefined = await messageStore.get(tenant, permissionsGrantId);
+
+    const dwnInterface = possibleGrantMessage?.descriptor.interface;
+    const dwnMethod = possibleGrantMessage?.descriptor.method;
+    if (possibleGrantMessage === undefined || dwnInterface !== DwnInterfaceName.Permissions || dwnMethod !== DwnMethodName.Grant) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationGrantMissing,
+        `Could not find PermissionsGrant with CID ${permissionsGrantId}`
+      );
+    }
+
+    const permissionsGrantMessage = possibleGrantMessage as PermissionsGrantMessage;
+    return permissionsGrantMessage;
+  }
+
+  /**
+   * Verifies the given `grantedTo` and `grantedFor` values against the given permissions grant and throws error if there is a mismatch.
+   */
+  private static verifyGrantedToAndGrantedFor(grantedTo: string, grantedFor: string, permissionsGrantMessage: PermissionsGrantMessage): void {
+    // Validate `grantedTo`
+    const expectedGrantedTo = permissionsGrantMessage.descriptor.grantedTo;
+    if (expectedGrantedTo !== grantedTo) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationNotGrantedToAuthor,
+        `PermissionsGrant has grantedTo ${expectedGrantedTo}, but given ${grantedTo}`
+      );
+    }
+
+    // Validate `grantedFor`
+    const expectedGrantedFor = permissionsGrantMessage.descriptor.grantedFor;
+    if (expectedGrantedFor !== grantedFor) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationNotGrantedForTenant,
+        `PermissionsGrant has grantedFor ${expectedGrantedFor}, but given ${grantedFor}`
+      );
+    }
+  }
+
+  /**
+   * Verify that the incoming message is within the allowed time frame of the grant,
+   * and the grant has not been revoked.
+   * @param permissionsGrantId Purely being passed as an optimization. Technically can be computed from `permissionsGrantMessage`.
+   * @throws {DwnError} if incomingMessage has timestamp for a time in which the grant is not active.
+   */
+  private static async verifyGrantActive(
+    tenant: string,
+    incomingMessageTimestamp: string,
+    permissionsGrantMessage: PermissionsGrantMessage,
+    permissionsGrantId: string,
+    messageStore: MessageStore,
+  ): Promise<void> {
+    // Check that incomingMessage is within the grant's time frame
+    if (incomingMessageTimestamp < permissionsGrantMessage.descriptor.messageTimestamp) {
+      // grant is not yet active
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationGrantNotYetActive,
+        `The message has a timestamp before the associated PermissionsGrant becomes active`,
+      );
+    } else if (incomingMessageTimestamp >= permissionsGrantMessage.descriptor.dateExpires) {
+      // grant has expired
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationGrantExpired,
+        `The message has timestamp after the expiry of the associated PermissionsGrant`,
+      );
+    }
+
+    // Check if grant has been revoked
+    const query = {
+      interface : DwnInterfaceName.Permissions,
+      method    : DwnMethodName.Revoke,
+      permissionsGrantId,
+    };
+    const { messages: revokes } = await messageStore.query(tenant, [query]);
+    const oldestExistingRevoke = await Message.getOldestMessage(revokes);
+
+    if (oldestExistingRevoke !== undefined && oldestExistingRevoke.descriptor.messageTimestamp <= incomingMessageTimestamp) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationGrantRevoked,
+        `PermissionsGrant with CID ${permissionsGrantId} has been revoked`,
+      );
+    }
+  }
+
+  /**
+   * Verify that the `interface` and `method` grant scopes match the incoming message
+   * @param permissionsGrantId Purely being passed for logging purposes.
+   * @throws {DwnError} if the `interface` and `method` of the incoming message do not match the scope of the PermissionsGrant
+   */
+  private static async verifyGrantScopeInterfaceAndMethod(
+    dwnInterface: string,
+    dwnMethod: string,
+    permissionsGrantMessage: PermissionsGrantMessage,
+    permissionsGrantId: string
+  ): Promise<void> {
+    if (dwnInterface !== permissionsGrantMessage.descriptor.scope.interface) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationInterfaceMismatch,
+        `DWN Interface of incoming message is outside the scope of PermissionsGrant with CID ${permissionsGrantId}`
+      );
+    } else if (dwnMethod !== permissionsGrantMessage.descriptor.scope.method) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationMethodMismatch,
+        `DWN Method of incoming message is outside the scope of PermissionsGrant with CID ${permissionsGrantId}`
+      );
+    }
+  }
+}

package/src/core/message-reply.ts

@@ -0,0 +1,42 @@
+import type { QueryResultEntry } from '../types/message-types.js';
+import type { Readable } from 'readable-stream';
+
+type Status = {
+  code: number
+  detail: string
+};
+
+export type GenericMessageReply = {
+  status: Status;
+};
+
+export function messageReplyFromError(e: unknown, code: number): GenericMessageReply {
+
+  const detail = e instanceof Error ? e.message : 'Error';
+
+  return { status: { code, detail } };
+}
+
+/**
+ * Catch-all message reply type. It is recommended to use GenericMessageReply or a message-specific reply type wherever possible.
+ */
+export type UnionMessageReply = GenericMessageReply & {
+  /**
+   * Resulting message entries or events returned from the invocation of the corresponding message.
+   * e.g. the resulting messages from a RecordsQuery
+   * Mutually exclusive with `data`.
+   */
+  entries?: QueryResultEntry[];
+
+  /**
+   * Data corresponding to the message received if applicable (e.g. RecordsRead).
+   * Mutually exclusive with `entries` and `cursor`.
+   */
+  data?: Readable;
+
+  /**
+   * A cursor for pagination if applicable (e.g. RecordsQuery).
+   * Mutually exclusive with `data`.
+   */
+  cursor?: string;
+};