@enbox/dwn-sdk-js 0.0.1

package/package.json

@@ -0,0 +1,167 @@
+{
+  "name": "@enbox/dwn-sdk-js",
+  "version": "0.0.1",
+  "description": "A reference implementation of https://identity.foundation/decentralized-web-node/spec/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/enboxorg/enbox.git",
+    "directory": "packages/dwn-sdk-js"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/enboxorg/enbox/tree/main/packages/dwn-sdk-js#readme",
+  "bugs": {
+    "url": "https://github.com/enboxorg/enbox/issues"
+  },
+  "contributors": [
+    {
+      "name": "Daniel Buchner",
+      "url": "https://github.com/csuwildcat"
+    },
+    {
+      "name": "Diane Huxley",
+      "url": "https://github.com/diehuxx"
+    },
+    {
+      "name": "Henry Tsai",
+      "url": "https://github.com/thehenrytsai"
+    },
+    {
+      "name": "Moe Jangda",
+      "url": "https://github.com/mistermoe"
+    },
+    {
+      "name": "Liran Cohen",
+      "url": "https://github.com/LiranCohen"
+    }
+  ],
+  "type": "module",
+  "@comment files": [
+    "the files property informs npm about which files we want to include in our published package.",
+    "dist will include all transpiled js. There's no point in including .ts files"
+  ],
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">= 18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/src/index.js",
+  "types": "./dist/types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/src/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/src/index.d.ts"
+    },
+    "./tests": {
+      "import": "./dist/esm/tests/test-suite.js",
+      "types": "./dist/types/tests/test-suite.d.ts"
+    }
+  },
+  "react-native": "./dist/esm/src/index.js",
+  "dependencies": {
+    "@ipld/dag-cbor": "9.0.3",
+    "@js-temporal/polyfill": "0.4.4",
+    "@noble/ciphers": "0.5.3",
+    "@noble/curves": "1.4.2",
+    "@noble/ed25519": "2.0.0",
+    "@noble/secp256k1": "2.0.0",
+    "@enbox/dids": "workspace:*",
+    "abstract-level": "1.0.3",
+    "ajv": "8.12.0",
+    "blockstore-core": "4.2.0",
+    "cross-fetch": "4.0.0",
+    "eciesjs": "0.4.5",
+    "interface-blockstore": "5.2.3",
+    "interface-store": "5.1.2",
+    "ipfs-unixfs-exporter": "13.1.5",
+    "ipfs-unixfs-importer": "15.1.5",
+    "level": "8.0.0",
+    "lodash": "4.17.21",
+    "lru-cache": "9.1.2",
+    "ms": "2.1.3",
+    "multiformats": "11.0.2",
+    "randombytes": "2.1.0",
+    "readable-stream": "4.5.2",
+    "uint8arrays": "5.1.0",
+    "ulidx": "2.1.0",
+    "uuid": "8.3.2",
+    "varint": "6.0.0"
+  },
+  "devDependencies": {
+    "@types/chai": "4.3.0",
+    "@types/chai-as-promised": "7.1.5",
+    "@types/flat": "^5.0.2",
+    "@types/karma": "^6.3.3",
+    "@types/lodash": "4.14.179",
+    "@types/mocha": "^9.1.0",
+    "@types/ms": "0.7.31",
+    "@types/node": "^18.13.0",
+    "@types/randombytes": "2.0.0",
+    "@types/readable-stream": "4.0.10",
+    "@types/secp256k1": "4.0.3",
+    "@types/sinon": "^17.0.3",
+    "@types/uuid": "^9.0.1",
+    "@types/varint": "6.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.9.0",
+    "@typescript-eslint/parser": "^7.9.0",
+    "c8": "^10.1.2",
+    "chai": "4.3.6",
+    "chai-as-promised": "7.1.1",
+    "cross-env": "7.0.3",
+    "dependency-cruiser": "^16.3.7",
+    "esbuild": "0.16.17",
+    "eslint": "^9.2.0",
+    "eslint-plugin-todo-plz": "1.3.0",
+    "events": "3.3.0",
+    "istanbul-badges-readme": "1.8.1",
+    "karma": "^6.4.4",
+    "karma-chai": "0.1.0",
+    "karma-chrome-launcher": "3.1.1",
+    "karma-esbuild": "2.2.5",
+    "karma-firefox-launcher": "2.1.2",
+    "karma-mocha": "2.0.1",
+    "karma-mocha-reporter": "2.2.5",
+    "karma-webkit-launcher": "2.1.0",
+    "license-report": "6.3.0",
+    "mkdirp": "1.0.4",
+    "mocha": "10.1.0",
+    "mockdate": "3.0.5",
+    "ms": "2.1.3",
+    "node-stdlib-browser": "1.2.0",
+    "playwright": "^1.44.0",
+    "rimraf": "^3.0.2",
+    "search-index": "3.4.0",
+    "sinon": "18.0.1",
+    "typescript": "^5.1.6",
+    "util": "0.12.4"
+  },
+  "overrides": {
+    "cookie": "^0.7.1",
+    "@typescript-eslint/eslint-plugin": {
+      "eslint": "^9.2.0"
+    }
+  },
+  "scripts": {
+    "build:esm": "tsc",
+    "build:cjs": "npm run build:esm && node build/create-cjs-bundle.cjs && echo '{\"type\": \"commonjs\"}' > ./dist/cjs/package.json",
+    "build": "npm run clean && npm run compile-validators && npm run build:esm && npm run build:cjs && npm run bundle",
+    "bundle": "node ./build/create-browser-bundle.cjs",
+    "clean": "rimraf dist && rimraf generated/*",
+    "compile-validators": "node ./build/compile-validators.js",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "circular-dependency-check": "depcruise src",
+    "test:node": "npm run compile-validators && tsc && c8 npx mocha \"dist/esm/tests/**/*.spec.js\"",
+    "test:node-grep": "npm run compile-validators && tsc && c8 npx mocha \"dist/esm/tests/**/*.spec.js\" -- --grep $npm_config_grep",
+    "test:browser": "npm run compile-validators && cross-env karma start karma.conf.cjs",
+    "test:browser-debug": "npm run compile-validators && cross-env karma start karma.conf.debug.cjs",
+    "license-check": "license-report --only=prod > license-report.json && node ./build/license-check.cjs",
+    "publish:unstable": "./build/publish-unstable.sh"
+  }
+}

package/src/core/abstract-message.ts

@@ -0,0 +1,62 @@
+import type { MessageInterface } from '../types/message-interface.js';
+import type { GenericMessage, GenericSignaturePayload } from '../types/message-types.js';
+
+import { Jws } from '../utils/jws.js';
+import { Message } from './message.js';
+
+/**
+ * An abstract implementation of the `MessageInterface` interface.
+ */
+export abstract class AbstractMessage<M extends GenericMessage> implements MessageInterface<M> {
+  private _message: M;
+  public get message(): M {
+    return this._message as M;
+  }
+
+  private _signer: string | undefined;
+  public get signer(): string | undefined {
+    return this._signer;
+  }
+
+  private _author: string | undefined;
+  public get author(): string | undefined {
+    return this._author;
+  }
+
+  private _signaturePayload: GenericSignaturePayload | undefined;
+  public get signaturePayload(): GenericSignaturePayload | undefined {
+    return this._signaturePayload;
+  }
+
+  /**
+   * If this message is signed by an author-delegate.
+   */
+  public get isSignedByAuthorDelegate(): boolean {
+    return Message.isSignedByAuthorDelegate(this._message);
+  }
+
+  protected constructor(message: M) {
+    this._message = message;
+
+    if (message.authorization !== undefined) {
+      this._signer = Message.getSigner(message);
+
+      // if the message authorization contains author delegated grant, the author would be the grantor of the grant
+      // else the author would be the signer of the message
+      if (message.authorization.authorDelegatedGrant !== undefined) {
+        this._author = Message.getSigner(message.authorization.authorDelegatedGrant);
+      } else {
+        this._author = this._signer;
+      }
+
+      this._signaturePayload = Jws.decodePlainObjectPayload(message.authorization.signature);
+    }
+  }
+
+  /**
+   * Called by `JSON.stringify(...)` automatically.
+   */
+  toJSON(): GenericMessage {
+    return this.message;
+  }
+}

package/src/core/auth.ts

@@ -0,0 +1,36 @@
+import type { AuthorizationModel } from '../types/message-types.js';
+import type { DidResolver } from '@enbox/dids';
+
+import { GeneralJwsVerifier } from '../jose/jws/general/verifier.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+/**
+ * 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 author-delegated grant
+    const authorDelegatedGrant = await RecordsWrite.parse(authorizationModel.authorDelegatedGrant);
+    await GeneralJwsVerifier.verifySignatures(authorDelegatedGrant.message.authorization.signature, didResolver);
+  }
+
+  if (authorizationModel.ownerDelegatedGrant !== undefined) {
+    // verify the signature of the grantor of the owner-delegated grant
+    const ownerDelegatedGrant = await RecordsWrite.parse(authorizationModel.ownerDelegatedGrant);
+    await GeneralJwsVerifier.verifySignatures(ownerDelegatedGrant.message.authorization.signature, didResolver);
+  }
+}

package/src/core/dwn-constant.ts

@@ -0,0 +1,9 @@
+export class DwnConstant {
+  /**
+   * The maximum size of raw data that will be returned as `encodedData`.
+   *
+   * We chose 30k, as after encoding it would give plenty of headroom up to the 65k limit in most SQL variants.
+   * We currently encode using base64url which is a 33% increase in size.
+   */
+  public static readonly maxDataSizeAllowedToBeEncoded = 30_000;
+}

package/src/core/dwn-error.ts

@@ -0,0 +1,167 @@
+/**
+ * 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',
+  AuthorizationNotGrantedToAuthor = 'AuthorizationNotGrantedToAuthor',
+  ComputeCidCodecNotSupported = 'ComputeCidCodecNotSupported',
+  ComputeCidMultihashNotSupported = 'ComputeCidMultihashNotSupported',
+  Ed25519InvalidJwk = 'Ed25519InvalidJwk',
+  EventEmitterStreamNotOpenError = 'EventEmitterStreamNotOpenError',
+  MessagesGrantAuthorizationMismatchedProtocol = 'EventsGrantAuthorizationMismatchedProtocol',
+  MessagesSubscribeAuthorizationFailed = 'MessagesSubscribeAuthorizationFailed',
+  MessagesSubscribeEventStreamUnimplemented = 'MessagesSubscribeEventStreamUnimplemented',
+  GeneralJwsVerifierGetPublicKeyNotFound = 'GeneralJwsVerifierGetPublicKeyNotFound',
+  GeneralJwsVerifierInvalidSignature = 'GeneralJwsVerifierInvalidSignature',
+  GrantAuthorizationGrantExpired = 'GrantAuthorizationGrantExpired',
+  GrantAuthorizationGrantMissing = 'GrantAuthorizationGrantMissing',
+  GrantAuthorizationGrantRevoked = 'GrantAuthorizationGrantRevoked',
+  GrantAuthorizationInterfaceMismatch = 'GrantAuthorizationInterfaceMismatch',
+  GrantAuthorizationMethodMismatch = 'GrantAuthorizationMethodMismatch',
+  GrantAuthorizationNotGrantedForTenant = 'GrantAuthorizationNotGrantedForTenant',
+  GrantAuthorizationNotGrantedToAuthor = 'GrantAuthorizationNotGrantedToAuthor',
+  GrantAuthorizationGrantNotYetActive = 'GrantAuthorizationGrantNotYetActive',
+  HdKeyDerivationPathInvalid = 'HdKeyDerivationPathInvalid',
+  JwsVerifySignatureUnsupportedCrv = 'JwsVerifySignatureUnsupportedCrv',
+  IndexInvalidCursorValueType = 'IndexInvalidCursorValueType',
+  IndexInvalidCursorSortProperty = 'IndexInvalidCursorSortProperty',
+  IndexInvalidSortPropertyInMemory = 'IndexInvalidSortPropertyInMemory',
+  IndexMissingIndexableProperty = 'IndexMissingIndexableProperty',
+  JwsDecodePlainObjectPayloadInvalid = 'JwsDecodePlainObjectPayloadInvalid',
+  MessagesReadInvalidCid = 'MessagesReadInvalidCid',
+  MessagesReadAuthorizationFailed = 'MessagesReadAuthorizationFailed',
+  MessageGetInvalidCid = 'MessageGetInvalidCid',
+  MessagesQueryAuthorizationFailed = 'MessagesQueryAuthorizationFailed',
+  MessagesReadVerifyScopeFailed = 'MessagesReadVerifyScopeFailed',
+  ParseCidCodecNotSupported = 'ParseCidCodecNotSupported',
+  ParseCidMultihashNotSupported = 'ParseCidMultihashNotSupported',
+  PermissionsProtocolCreateGrantRecordsScopeMissingProtocol = 'PermissionsProtocolCreateGrantRecordsScopeMissingProtocol',
+  PermissionsProtocolCreateRequestRecordsScopeMissingProtocol = 'PermissionsProtocolCreateRequestRecordsScopeMissingProtocol',
+  PermissionsProtocolGetScopeInvalidProtocol = 'PermissionsProtocolGetScopeInvalidProtocol',
+  PermissionsProtocolValidateSchemaUnexpectedRecord = 'PermissionsProtocolValidateSchemaUnexpectedRecord',
+  PermissionsProtocolValidateScopeContextIdProhibitedProperties = 'PermissionsProtocolValidateScopeContextIdProhibitedProperties',
+  PermissionsProtocolValidateScopeProtocolMismatch = 'PermissionsProtocolValidateScopeProtocolMismatch',
+  PermissionsProtocolValidateScopeMissingProtocolTag = 'PermissionsProtocolValidateScopeMissingProtocolTag',
+  PermissionsProtocolValidateRevocationProtocolTagMismatch = 'PermissionsProtocolValidateRevocationProtocolTagMismatch',
+  PrivateKeySignerUnableToDeduceAlgorithm = 'PrivateKeySignerUnableToDeduceAlgorithm',
+  PrivateKeySignerUnableToDeduceKeyId = 'PrivateKeySignerUnableToDeduceKeyId',
+  PrivateKeySignerUnsupportedCurve = 'PrivateKeySignerUnsupportedCurve',
+  ProtocolAuthorizationActionNotAllowed = 'ProtocolAuthorizationActionNotAllowed',
+  ProtocolAuthorizationActionRulesNotFound = 'ProtocolAuthorizationActionRulesNotFound',
+  ProtocolAuthorizationIncorrectDataFormat = 'ProtocolAuthorizationIncorrectDataFormat',
+  ProtocolAuthorizationIncorrectContextId = 'ProtocolAuthorizationIncorrectContextId',
+  ProtocolAuthorizationIncorrectProtocolPath = 'ProtocolAuthorizationIncorrectProtocolPath',
+  ProtocolAuthorizationDuplicateRoleRecipient = 'ProtocolAuthorizationDuplicateRoleRecipient',
+  ProtocolAuthorizationInvalidSchema = 'ProtocolAuthorizationInvalidSchema',
+  ProtocolAuthorizationInvalidType = 'ProtocolAuthorizationInvalidType',
+  ProtocolAuthorizationMatchingRoleRecordNotFound = 'ProtocolAuthorizationMatchingRoleRecordNotFound',
+  ProtocolAuthorizationMaxSizeInvalid = 'ProtocolAuthorizationMaxSizeInvalid',
+  ProtocolAuthorizationMinSizeInvalid = 'ProtocolAuthorizationMinSizeInvalid',
+  ProtocolAuthorizationMissingContextId = 'ProtocolAuthorizationMissingContextId',
+  ProtocolAuthorizationMissingRuleSet = 'ProtocolAuthorizationMissingRuleSet',
+  ProtocolAuthorizationParentlessIncorrectProtocolPath = 'ProtocolAuthorizationParentlessIncorrectProtocolPath',
+  ProtocolAuthorizationNotARole = 'ProtocolAuthorizationNotARole',
+  ProtocolAuthorizationParentNotFoundConstructingRecordChain = 'ProtocolAuthorizationParentNotFoundConstructingRecordChain',
+  ProtocolAuthorizationProtocolNotFound = 'ProtocolAuthorizationProtocolNotFound',
+  ProtocolAuthorizationRoleMissingRecipient = 'ProtocolAuthorizationRoleMissingRecipient',
+  ProtocolAuthorizationTagsInvalidSchema = 'ProtocolAuthorizationTagsInvalidSchema',
+  ProtocolsConfigureAuthorizationFailed = 'ProtocolsConfigureAuthorizationFailed',
+  ProtocolsConfigureDuplicateActorInRuleSet = 'ProtocolsConfigureDuplicateActorInRuleSet',
+  ProtocolsConfigureDuplicateRoleInRuleSet = 'ProtocolsConfigureDuplicateRoleInRuleSet',
+  ProtocolsConfigureInvalidSize = 'ProtocolsConfigureInvalidSize',
+  ProtocolsConfigureInvalidActionMissingOf = 'ProtocolsConfigureInvalidActionMissingOf',
+  ProtocolsConfigureInvalidActionOfNotAllowed = 'ProtocolsConfigureInvalidActionOfNotAllowed',
+  ProtocolsConfigureInvalidActionDeleteWithoutCreate = 'ProtocolsConfigureInvalidActionDeleteWithoutCreate',
+  ProtocolsConfigureInvalidActionUpdateWithoutCreate = 'ProtocolsConfigureInvalidActionUpdateWithoutCreate',
+  ProtocolsConfigureInvalidRecipientOfAction = 'ProtocolsConfigureInvalidRecipientOfAction',
+  ProtocolsConfigureInvalidRuleSetRecordType = 'ProtocolsConfigureInvalidRuleSetRecordType',
+  ProtocolsConfigureInvalidTagSchema = 'ProtocolsConfigureInvalidTagSchema',
+  ProtocolsConfigureRecordNestingDepthExceeded = 'ProtocolsConfigureRecordNestingDepthExceeded',
+  ProtocolsConfigureRoleDoesNotExistAtGivenPath = 'ProtocolsConfigureRoleDoesNotExistAtGivenPath',
+  ProtocolsConfigureRoleReadActionMissing = 'ProtocolsConfigureRoleReadActionMissing',
+  ProtocolsGrantAuthorizationQueryProtocolScopeMismatch = 'ProtocolsGrantAuthorizationQueryProtocolScopeMismatch',
+  ProtocolsGrantAuthorizationScopeProtocolMismatch = 'ProtocolsGrantAuthorizationScopeProtocolMismatch',
+  ProtocolsQueryUnauthorized = 'ProtocolsQueryUnauthorized',
+  RecordsAuthorDelegatedGrantAndIdExistenceMismatch = 'RecordsAuthorDelegatedGrantAndIdExistenceMismatch',
+  RecordsAuthorDelegatedGrantCidMismatch = 'RecordsAuthorDelegatedGrantCidMismatch',
+  RecordsAuthorDelegatedGrantGrantedToAndOwnerSignatureMismatch = 'RecordsAuthorDelegatedGrantGrantedToAndOwnerSignatureMismatch',
+  RecordsAuthorDelegatedGrantNotADelegatedGrant = 'RecordsAuthorDelegatedGrantNotADelegatedGrant',
+  RecordsDecryptNoMatchingKeyEncryptedFound = 'RecordsDecryptNoMatchingKeyEncryptedFound',
+  RecordsDeleteAuthorizationFailed = 'RecordsDeleteAuthorizationFailed',
+  RecordsQueryCreateFilterPublishedSortInvalid = 'RecordsQueryCreateFilterPublishedSortInvalid',
+  RecordsQueryParseFilterPublishedSortInvalid = 'RecordsQueryParseFilterPublishedSortInvalid',
+  RecordsGrantAuthorizationConditionPublicationProhibited = 'RecordsGrantAuthorizationConditionPublicationProhibited',
+  RecordsGrantAuthorizationConditionPublicationRequired = 'RecordsGrantAuthorizationConditionPublicationRequired',
+  RecordsGrantAuthorizationDeleteProtocolScopeMismatch = 'RecordsGrantAuthorizationDeleteProtocolScopeMismatch',
+  RecordsGrantAuthorizationQueryOrSubscribeProtocolScopeMismatch = 'RecordsGrantAuthorizationQueryOrSubscribeProtocolScopeMismatch',
+  RecordsGrantAuthorizationScopeContextIdMismatch = 'RecordsGrantAuthorizationScopeContextIdMismatch',
+  RecordsGrantAuthorizationScopeProtocolMismatch = 'RecordsGrantAuthorizationScopeProtocolMismatch',
+  RecordsGrantAuthorizationScopeProtocolPathMismatch = 'RecordsGrantAuthorizationScopeProtocolPathMismatch',
+  RecordsDerivePrivateKeyUnSupportedCurve = 'RecordsDerivePrivateKeyUnSupportedCurve',
+  RecordsInvalidAncestorKeyDerivationSegment = 'RecordsInvalidAncestorKeyDerivationSegment',
+  RecordsOwnerDelegatedGrantAndIdExistenceMismatch = 'RecordsOwnerDelegatedGrantAndIdExistenceMismatch',
+  RecordsOwnerDelegatedGrantCidMismatch = 'RecordsOwnerDelegatedGrantCidMismatch',
+  RecordsOwnerDelegatedGrantGrantedToAndOwnerSignatureMismatch = 'RecordsOwnerDelegatedGrantGrantedToAndOwnerSignatureMismatch',
+  RecordsOwnerDelegatedGrantNotADelegatedGrant = 'RecordsOwnerDelegatedGrantNotADelegatedGrant',
+  RecordsProtocolContextDerivationSchemeMissingContextId = 'RecordsProtocolContextDerivationSchemeMissingContextId',
+  RecordsProtocolPathDerivationSchemeMissingProtocol = 'RecordsProtocolPathDerivationSchemeMissingProtocol',
+  RecordsQueryFilterMissingRequiredProperties = 'RecordsQueryFilterMissingRequiredProperties',
+  RecordsReadReturnedMultiple = 'RecordsReadReturnedMultiple',
+  RecordsReadAuthorizationFailed = 'RecordsReadAuthorizationFailed',
+  RecordsSubscribeEventStreamUnimplemented = 'RecordsSubscribeEventStreamUnimplemented',
+  RecordsSubscribeFilterMissingRequiredProperties = 'RecordsSubscribeFilterMissingRequiredProperties',
+  RecordsSchemasDerivationSchemeMissingSchema = 'RecordsSchemasDerivationSchemeMissingSchema',
+  RecordsWriteAttestationIntegrityMoreThanOneSignature = 'RecordsWriteAttestationIntegrityMoreThanOneSignature',
+  RecordsWriteAttestationIntegrityDescriptorCidMismatch = 'RecordsWriteAttestationIntegrityDescriptorCidMismatch',
+  RecordsWriteAttestationIntegrityInvalidPayloadProperty = 'RecordsWriteAttestationIntegrityInvalidPayloadProperty',
+  RecordsWriteAuthorizationFailed = 'RecordsWriteAuthorizationFailed',
+  RecordsWriteCreateMissingSigner = 'RecordsWriteCreateMissingSigner',
+  RecordsWriteCreateDataAndDataCidMutuallyExclusive = 'RecordsWriteCreateDataAndDataCidMutuallyExclusive',
+  RecordsWriteCreateDataCidAndDataSizeMutuallyInclusive = 'RecordsWriteCreateDataCidAndDataSizeMutuallyInclusive',
+  RecordsWriteCreateProtocolAndProtocolPathMutuallyInclusive = 'RecordsWriteCreateProtocolAndProtocolPathMutuallyInclusive',
+  RecordsWriteDataCidMismatch = 'RecordsWriteDataCidMismatch',
+  RecordsWriteDataSizeMismatch = 'RecordsWriteDataSizeMismatch',
+  RecordsWriteGetEntryIdUndefinedAuthor = 'RecordsWriteGetEntryIdUndefinedAuthor',
+  RecordsWriteGetNewestWriteRecordNotFound = 'RecordsWriteGetNewestWriteRecordNotFound',
+  RecordsWriteGetInitialWriteNotFound = 'RecordsWriteGetInitialWriteNotFound',
+  RecordsWriteImmutablePropertyChanged = 'RecordsWriteImmutablePropertyChanged',
+  RecordsWriteMissingSigner = 'RecordsWriteMissingSigner',
+  RecordsWriteMissingDataInPrevious = 'RecordsWriteMissingDataInPrevious',
+  RecordsWriteMissingEncodedDataInPrevious = 'RecordsWriteMissingEncodedDataInPrevious',
+  RecordsWriteMissingProtocol = 'RecordsWriteMissingProtocol',
+  RecordsWriteMissingSchema = 'RecordsWriteMissingSchema',
+  RecordsWriteNotAllowedAfterDelete = 'RecordsWriteNotAllowedAfterDelete',
+  RecordsWriteOwnerAndTenantMismatch = 'RecordsWriteOwnerAndTenantMismatch',
+  RecordsWriteSignAsOwnerDelegateUnknownAuthor = 'RecordsWriteSignAsOwnerDelegateUnknownAuthor',
+  RecordsWriteSignAsOwnerUnknownAuthor = 'RecordsWriteSignAsOwnerUnknownAuthor',
+  RecordsWriteValidateIntegrityAttestationMismatch = 'RecordsWriteValidateIntegrityAttestationMismatch',
+  RecordsWriteValidateIntegrityContextIdMismatch = 'RecordsWriteValidateIntegrityContextIdMismatch',
+  RecordsWriteValidateIntegrityContextIdNotInSignerSignaturePayload = 'RecordsWriteValidateIntegrityContextIdNotInSignerSignaturePayload',
+  RecordsWriteValidateIntegrityDateCreatedMismatch = 'RecordsWriteValidateIntegrityDateCreatedMismatch',
+  RecordsWriteValidateIntegrityEncryptionCidMismatch = 'RecordsWriteValidateIntegrityEncryptionCidMismatch',
+  RecordsWriteValidateIntegrityRecordIdUnauthorized = 'RecordsWriteValidateIntegrityRecordIdUnauthorized',
+  SchemaValidatorAdditionalPropertyNotAllowed = 'SchemaValidatorAdditionalPropertyNotAllowed',
+  SchemaValidatorFailure = 'SchemaValidatorFailure',
+  SchemaValidatorSchemaNotFound = 'SchemaValidatorSchemaNotFound',
+  SchemaValidatorUnevaluatedPropertyNotAllowed = 'SchemaValidatorUnevaluatedPropertyNotAllowed',
+  Secp256k1KeyNotValid = 'Secp256k1KeyNotValid',
+  Secp256r1KeyNotValid = 'Secp256r1KeyNotValid',
+  TimestampInvalid = 'TimestampInvalid',
+  UrlProtocolNotNormalized = 'UrlProtocolNotNormalized',
+  UrlProtocolNotNormalizable = 'UrlProtocolNotNormalizable',
+  UrlSchemaNotNormalized = 'UrlSchemaNotNormalized',
+  RecordsReadInitialWriteNotFound = 'RecordsReadInitialWriteNotFound',
+};

package/src/core/grant-authorization.ts

@@ -0,0 +1,148 @@
+import type { GenericMessage } from '../types/message-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { PermissionGrant } from '../protocols/permission-grant.js';
+
+import { Message } from './message.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+export class GrantAuthorization {
+
+  /**
+   * Performs base permissions-grant-based authorization against the given message:
+   * 1. Validates the `expectedGrantor` and `expectedGrantee` values against the actual values in given permission grant.
+   * 2. Verifies that the incoming message is within the allowed time frame of the grant, and the grant has not been revoked.
+   * 3. Verifies that the `interface` and `method` grant scopes match the incoming message.
+   *
+   * NOTE: Does not validate grant `conditions` or `scope` beyond `interface` and `method`
+   *
+   * @param messageStore Used to check if the grant has been revoked.
+   * @throws {DwnError} if validation fails
+   */
+  public static async performBaseValidation(input: {
+    incomingMessage: GenericMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+    }): Promise<void> {
+    const { incomingMessage, expectedGrantor, expectedGrantee, permissionGrant, messageStore } = input;
+
+    const incomingMessageDescriptor = incomingMessage.descriptor;
+
+    GrantAuthorization.verifyExpectedGrantorAndGrantee(expectedGrantor, expectedGrantee, permissionGrant);
+
+    // verify that grant is active during incomingMessage's timestamp
+    const grantedFor = expectedGrantor; // renaming for better readability now that we have verified the grantor above
+    await GrantAuthorization.verifyGrantActive(
+      grantedFor,
+      incomingMessageDescriptor.messageTimestamp,
+      permissionGrant,
+      messageStore
+    );
+
+    // Check grant scope for interface and method
+    await GrantAuthorization.verifyGrantScopeInterfaceAndMethod(
+      incomingMessageDescriptor.interface,
+      incomingMessageDescriptor.method,
+      permissionGrant,
+    );
+  }
+
+  /**
+   * Verifies the given `expectedGrantor` and `expectedGrantee` values against
+   * the actual signer and recipient in given permission grant.
+   * @throws {DwnError} if `expectedGrantor` or `expectedGrantee` do not match the actual values in the grant.
+   */
+  private static verifyExpectedGrantorAndGrantee(
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant
+  ): void {
+
+    const actualGrantee = permissionGrant.grantee;
+    if (expectedGrantee !== actualGrantee) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationNotGrantedToAuthor,
+        `Permission grant is granted to ${actualGrantee}, but need to be granted to ${expectedGrantee}`
+      );
+    }
+
+    const actualGrantor = permissionGrant.grantor;
+    if (expectedGrantor !== actualGrantor) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationNotGrantedForTenant,
+        `Permission grant is granted by ${actualGrantor}, but need to be granted by ${expectedGrantor}`
+      );
+    }
+  }
+
+  /**
+   * Verify that the incoming message is within the allowed time frame of the grant,
+   * and the grant has not been revoked.
+   * @param messageStore Used to check if the grant has been revoked.
+   * @throws {DwnError} if incomingMessage has timestamp for a time in which the grant is not active.
+   */
+  private static async verifyGrantActive(
+    grantedFor: string,
+    incomingMessageTimestamp: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  ): Promise<void> {
+    // Check that incomingMessage is within the grant's time frame
+    if (incomingMessageTimestamp < permissionGrant.dateGranted) {
+      // grant is not yet active
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationGrantNotYetActive,
+        `The message has a timestamp before the associated permission grant becomes active`,
+      );
+    }
+
+    if (incomingMessageTimestamp >= permissionGrant.dateExpires) {
+      // grant has expired
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationGrantExpired,
+        `The message has timestamp after the expiry of the associated permission grant`,
+      );
+    }
+
+    // Check if grant has been revoked
+    const query = {
+      parentId          : permissionGrant.id,
+      protocolPath      : `grant/revocation`, // NOTE: this is optional, not referencing PermissionsProtocol.revocationPath due to circular dependency
+      isLatestBaseState : true
+    };
+    const { messages: revokes } = await messageStore.query(grantedFor, [query]);
+    const oldestExistingRevoke = await Message.getOldestMessage(revokes);
+
+    if (oldestExistingRevoke !== undefined && oldestExistingRevoke.descriptor.messageTimestamp <= incomingMessageTimestamp) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationGrantRevoked,
+        `Permission grant with CID ${permissionGrant.id} has been revoked`,
+      );
+    }
+  }
+
+  /**
+   * Verify that the `interface` and `method` grant scopes match the incoming message
+   * @param permissionGrantId Purely being passed for logging purposes.
+   * @throws {DwnError} if the `interface` and `method` of the incoming message do not match the scope of the permission grant.
+   */
+  private static async verifyGrantScopeInterfaceAndMethod(
+    dwnInterface: string,
+    dwnMethod: string,
+    permissionGrant: PermissionGrant,
+  ): Promise<void> {
+
+    if (dwnInterface !== permissionGrant.scope.interface) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationInterfaceMismatch,
+        `DWN Interface of incoming message is outside the scope of permission grant with ID ${permissionGrant.id}`
+      );
+    } else if (dwnMethod !== permissionGrant.scope.method) {
+      throw new DwnError(
+        DwnErrorCode.GrantAuthorizationMethodMismatch,
+        `DWN Method of incoming message is outside the scope of permission grant with ID ${permissionGrant.id}`
+      );
+    }
+  }
+}

package/src/core/message-reply.ts

@@ -0,0 +1,41 @@
+import type { MessagesReadReplyEntry } from '../types/messages-types.js';
+import type { PaginationCursor } from '../types/query-types.js';
+import type { ProtocolsConfigureMessage } from '../types/protocols-types.js';
+import type { RecordsReadReplyEntry } from '../types/records-types.js';
+import type { GenericMessageReply, MessageSubscription, QueryResultEntry } from '../types/message-types.js';
+
+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 & {
+  /**
+   * A container for the data returned from a `RecordsRead` or `MessagesRead`.
+   * Mutually exclusive with (`entries` + `cursor`) and `subscription`.
+   */
+  entry?: MessagesReadReplyEntry & RecordsReadReplyEntry;
+
+  /**
+   * Resulting message entries or events returned from the invocation of the corresponding message.
+   * e.g. the resulting messages from a RecordsQuery, or array of messageCid strings for MessagesQuery
+   * Mutually exclusive with `record`.
+   */
+  entries?: QueryResultEntry[] | ProtocolsConfigureMessage[] | string[];
+
+  /**
+   * A cursor for pagination if applicable (e.g. RecordsQuery).
+   * Mutually exclusive with `record`.
+   */
+  cursor?: PaginationCursor;
+
+  /**
+   * A subscription object if a subscription was requested.
+   */
+  subscription?: MessageSubscription;
+};