@abaxxtech/id 0.0.0

package/src/index.ts

@@ -0,0 +1,81 @@
+/* eslint-disable max-len */
+
+/**
+ * ID++ Protocol Exports
+ */
+
+// import { webcrypto } from 'node:crypto';
+//@ts-ignore
+// if (!globalThis.crypto) { globalThis.crypto = webcrypto; }
+
+export type { DwnConfig } from './dwn.js';
+export type { DidMethodResolver, DwnServiceEndpoint, ServiceEndpoint, DidDocument, DidResolutionResult, DidResolutionMetadata, DidDocumentMetadata, VerificationMethod } from './types/did-types.js';
+export type { EventLog, Event, GetEventsOptions } from './types/event-log.js';
+export type { EventsGetMessage, EventsGetReply } from './types/event-types.js';
+export type { Filter, GenericMessage, MessageSort, Pagination } from './types/message-types.js';
+export type { MessagesGetMessage, MessagesGetReply } from './types/messages-types.js';
+export type { PermissionConditions, PermissionScope, PermissionsGrantDescriptor } from './types/permissions-grant-descriptor.js';
+export type { PermissionsGrantMessage, PermissionsRequestDescriptor, PermissionsRequestMessage, PermissionsRevokeDescriptor, PermissionsRevokeMessage } from './types/permissions-types.js';
+export type { ProtocolsConfigureDescriptor, ProtocolDefinition, ProtocolTypes, ProtocolRuleSet, ProtocolsQueryFilter, ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply } from './types/protocols-types.js';
+export type { EncryptionProperty, RecordsDeleteMessage, RecordsQueryMessage, RecordsQueryReply, RecordsQueryReplyEntry, RecordsReadReply, RecordsWriteDescriptor, RecordsWriteMessage } from './types/records-types.js';
+
+export { AllowAllTenantGate } from './core/tenant-gate.js';
+export type { TenantGate } from './core/tenant-gate.js';
+export { Cid } from './utils/cid.js';
+export { RecordsQuery } from './interfaces/records-query.js';
+export type { RecordsQueryOptions } from './interfaces/records-query.js';
+export type { DataStore, PutResult, GetResult, AssociateResult } from './types/data-store.js';
+export { DataStream } from './utils/data-stream.js';
+export { DateSort } from './types/records-types.js';
+export type { DerivedPrivateJwk } from './utils/hd-key.js';
+export { HdKey, KeyDerivationScheme } from './utils/hd-key.js';
+export { DidKeyResolver } from './did/did-key-resolver.js';
+export { DidIonResolver } from './did/did-ion-resolver.js';
+export { DidDhtResolver } from './did/did-dht-resolver.js';
+export { DidResolver } from './did/did-resolver.js';
+export { Dwn } 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 { EventsGet } from './interfaces/events-get.js';
+export type { EventsGetOptions } from './interfaces/events-get.js';
+export { Encryption, EncryptionAlgorithm } from './utils/encryption.js';
+export type { EncryptionInput, KeyEncryptionInput, RecordsWriteOptions, CreateFromOptions } from './interfaces/records-write.js';
+export { RecordsWrite } from './interfaces/records-write.js';
+export { executeUnlessAborted } from './utils/abort.js';
+export { Jws } from './utils/jws.js';
+export type { KeyMaterial, PrivateJwk, PublicJwk } from './types/jose-types.js';
+export { Message } from './core/message.js';
+export { MessagesGet } from './interfaces/messages-get.js';
+export type { MessagesGetOptions } from './interfaces/messages-get.js';
+export type { UnionMessageReply } from './core/message-reply.js';
+export type { MessageStore, MessageStoreOptions } from './types/message-store.js';
+export { PermissionsGrant } from './interfaces/permissions-grant.js';
+export type { PermissionsGrantOptions } from './interfaces/permissions-grant.js';
+export { PermissionsRequest } from './interfaces/permissions-request.js';
+export type { PermissionsRequestOptions } from './interfaces/permissions-request.js';
+export { PermissionsRevoke } from './interfaces/permissions-revoke.js';
+export type { PermissionsRevokeOptions } from './interfaces/permissions-revoke.js';
+export { PrivateKeySigner } from './utils/private-key-signer.js';
+export { Protocols } from './utils/protocols.js';
+export { ProtocolsConfigure } from './interfaces/protocols-configure.js';
+export type { ProtocolsConfigureOptions } from './interfaces/protocols-configure.js';
+export { ProtocolsQuery } from './interfaces/protocols-query.js';
+export type { ProtocolsQueryOptions } from './interfaces/protocols-query.js';
+export { Records } from './utils/records.js';
+export { RecordsDelete } from './interfaces/records-delete.js';
+export type { RecordsDeleteOptions } from './interfaces/records-delete.js';
+export { RecordsRead } from './interfaces/records-read.js';
+export type { RecordsReadOptions } from './interfaces/records-read.js';
+export { Secp256k1 } from './utils/secp256k1.js';
+export type { Signer } from './types/signer.js';
+export { DataStoreLevel } from './store/data-store-level.js';
+export { EventLogLevel } from './event-log/event-log-level.js';
+export { MessageStoreLevel } from './store/message-store-level.js';
+export { SortOrder } from './types/message-types.js';
+export { Time } from './utils/time.js';
+
+// custom
+export { Authenticate } from './core/auth.js';
+export { GeneralJwsSigner } from './jose/jws/general/signer.js';

package/src/interfaces/events-get.ts

@@ -0,0 +1,43 @@
+import type { Signer } from '../types/signer.js';
+import type { EventsGetDescriptor, EventsGetMessage } from '../types/event-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { Message } from '../core/message.js';
+import { Time } from '../utils/time.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export type EventsGetOptions = {
+  watermark?: string;
+  signer: Signer;
+  messageTimestamp?: string;
+};
+
+export class EventsGet extends AbstractMessage<EventsGetMessage> {
+
+  public static async parse(message: EventsGetMessage): Promise<EventsGet> {
+    Message.validateJsonSchema(message);
+    await Message.validateMessageSignatureIntegrity(message.authorization.signature, message.descriptor);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new EventsGet(message);
+  }
+
+  public static async create(options: EventsGetOptions): Promise<EventsGet> {
+    const descriptor: EventsGetDescriptor = {
+      interface        : DwnInterfaceName.Events,
+      method           : DwnMethodName.Get,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+    };
+
+    if (options.watermark) {
+      descriptor.watermark = options.watermark;
+    }
+
+    const authorization = await Message.createAuthorization({ descriptor, signer: options.signer });
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+
+    return new EventsGet(message);
+  }
+}

package/src/interfaces/messages-get.ts

@@ -0,0 +1,59 @@
+import type { Signer } from '../types/signer.js';
+import type { MessagesGetDescriptor, MessagesGetMessage } 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 MessagesGetOptions = {
+  messageCids: string[];
+  signer: Signer;
+  messageTimestamp?: string;
+};
+
+export class MessagesGet extends AbstractMessage<MessagesGetMessage> {
+  public static async parse(message: MessagesGetMessage): Promise<MessagesGet> {
+    Message.validateJsonSchema(message);
+    this.validateMessageCids(message.descriptor.messageCids);
+
+    await Message.validateMessageSignatureIntegrity(message.authorization.signature, message.descriptor);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new MessagesGet(message);
+  }
+
+  public static async create(options: MessagesGetOptions): Promise<MessagesGet> {
+    const descriptor: MessagesGetDescriptor = {
+      interface        : DwnInterfaceName.Messages,
+      method           : DwnMethodName.Get,
+      messageCids      : options.messageCids,
+      messageTimestamp : options?.messageTimestamp ?? Time.getCurrentTimestamp(),
+    };
+
+    const authorization = await Message.createAuthorization({ descriptor, signer: options.signer });
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+    MessagesGet.validateMessageCids(options.messageCids);
+
+    return new MessagesGet(message);
+  }
+
+  /**
+   * validates the provided cids
+   * @param messageCids - the cids in question
+   * @throws {DwnError} if an invalid cid is found.
+   */
+  private static validateMessageCids(messageCids: string[]): void {
+    for (const cid of messageCids) {
+      try {
+        Cid.parseCid(cid);
+      } catch (_) {
+        throw new DwnError(DwnErrorCode.MessageGetInvalidCid, `${cid} is not a valid CID`);
+      }
+    }
+  }
+}

package/src/interfaces/permissions-grant.ts

@@ -0,0 +1,175 @@
+import type { DelegatedGrantMessage } from '../types/delegated-grant-message.js';
+import type { PermissionsGrantMessage } from '../types/permissions-types.js';
+import type { PermissionsRequest } from './permissions-request.js';
+import type { Signer } from '../types/signer.js';
+import type { PermissionConditions, PermissionScope, PermissionsGrantDescriptor, RecordsPermissionScope } from '../types/permissions-grant-descriptor.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 { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { normalizeProtocolUrl, normalizeSchemaUrl } from '../utils/url.js';
+
+export type PermissionsGrantOptions = {
+  messageTimestamp?: string;
+  dateExpires: string;
+  description?: string;
+  grantedTo: string;
+  grantedBy: string;
+  grantedFor: string;
+  delegated?: boolean;
+  permissionsRequestId?: string;
+  scope: PermissionScope;
+  conditions?: PermissionConditions;
+  signer: Signer;
+};
+
+export type CreateFromPermissionsRequestOverrides = {
+  dateExpires: string;
+  description?: string;
+  grantedTo?: string;
+  grantedBy?: string;
+  grantedFor?: string;
+  scope?: PermissionScope;
+  conditions?: PermissionConditions;
+};
+
+export class PermissionsGrant extends AbstractMessage<PermissionsGrantMessage> {
+
+  public static async parse(message: PermissionsGrantMessage): Promise<PermissionsGrant> {
+    await Message.validateMessageSignatureIntegrity(message.authorization.signature, message.descriptor);
+    PermissionsGrant.validateScope(message);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+    Time.validateTimestamp(message.descriptor.dateExpires);
+
+    return new PermissionsGrant(message);
+  }
+
+  static async create(options: PermissionsGrantOptions): Promise<PermissionsGrant> {
+    const scope = { ...options.scope } as RecordsPermissionScope;
+    scope.protocol = scope.protocol !== undefined ? normalizeProtocolUrl(scope.protocol) : undefined;
+    scope.schema = scope.schema !== undefined ? normalizeSchemaUrl(scope.schema) : undefined;
+
+    const descriptor: PermissionsGrantDescriptor = {
+      interface            : DwnInterfaceName.Permissions,
+      method               : DwnMethodName.Grant,
+      messageTimestamp     : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      dateExpires          : options.dateExpires,
+      description          : options.description,
+      grantedTo            : options.grantedTo,
+      grantedBy            : options.grantedBy,
+      grantedFor           : options.grantedFor,
+      delegated            : options.delegated,
+      permissionsRequestId : options.permissionsRequestId,
+      scope                : scope,
+      conditions           : options.conditions,
+    };
+
+    // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:
+    // Error: `undefined` is not supported by the IPLD Data Model and cannot be encoded
+    removeUndefinedProperties(descriptor);
+
+    const authorization = await Message.createAuthorization({ descriptor, signer: options.signer });
+    const message: PermissionsGrantMessage = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+    PermissionsGrant.validateScope(message);
+
+    return new PermissionsGrant(message);
+  }
+
+  /**
+   * A convenience method for casting a PermissionsGrantMessage to a DelegatedGrantMessage if the `delegated` property is `true`.
+   * @throws {DwnError} if the `delegated` property is not `true`.
+   */
+  public asDelegatedGrant(): DelegatedGrantMessage {
+    return PermissionsGrant.asDelegatedGrant(this.message);
+  }
+
+  /**
+   * A convenience method for casting a PermissionsGrantMessage to a DelegatedGrantMessage if the `delegated` property is `true`.
+   * @throws {DwnError} if the `delegated` property is not `true`.
+   */
+  public static asDelegatedGrant(message: PermissionsGrantMessage): DelegatedGrantMessage {
+    if (!message.descriptor.delegated) {
+      throw new DwnError(
+        DwnErrorCode.PermissionsGrantNotADelegatedGrant,
+        `PermissionsGrant given is not a delegated grant. Descriptor: ${message.descriptor}`
+      );
+    }
+
+    return message as DelegatedGrantMessage;
+  }
+
+
+  /**
+   * generates a PermissionsGrant using the provided PermissionsRequest
+   * @param permissionsRequest
+   * @param signer - the private key and additional signature material of the grantor
+   * @param overrides - overrides that will be used instead of the properties in `permissionsRequest`
+   */
+  public static async createFromPermissionsRequest(
+    permissionsRequest: PermissionsRequest,
+    signer: Signer,
+    overrides: CreateFromPermissionsRequestOverrides,
+  ): Promise<PermissionsGrant> {
+    const descriptor = permissionsRequest.message.descriptor;
+    return PermissionsGrant.create({
+      dateExpires          : overrides.dateExpires,
+      description          : overrides.description ?? descriptor.description,
+      grantedBy            : overrides.grantedBy ?? descriptor.grantedBy,
+      grantedTo            : overrides.grantedTo ?? descriptor.grantedTo,
+      grantedFor           : overrides.grantedFor ?? descriptor.grantedFor,
+      permissionsRequestId : await Message.getCid(permissionsRequest.message),
+      scope                : overrides.scope ?? descriptor.scope,
+      conditions           : overrides.conditions ?? descriptor.conditions,
+      signer,
+    });
+  }
+
+  /**
+   * Current implementation only allows the DWN owner to store grants they created.
+   */
+  public authorize(): void {
+    const { grantedBy, grantedFor } = this.message.descriptor;
+    if (this.author !== grantedBy) {
+      throw new DwnError(DwnErrorCode.PermissionsGrantGrantedByMismatch, 'Message author must match grantedBy property');
+    } else if (grantedBy !== grantedFor) {
+      // Without delegation, only the DWN owner may grant access to their own DWN.
+      throw new DwnError(
+        DwnErrorCode.PermissionsGrantUnauthorizedGrant,
+        `${grantedBy} is not authorized to give access to the DWN belonging to ${grantedFor}`
+      );
+    }
+  }
+
+  /**
+   * Validates scope structure for properties beyond `interface` and `method`.
+   * Currently only grants for RecordsRead and RecordsWrite have such properties and need validation beyond JSON Schema.
+   */
+  public static validateScope(permissionsGrantMessage: PermissionsGrantMessage): void {
+    const recordsScope = permissionsGrantMessage.descriptor.scope as RecordsPermissionScope;
+
+    // `schema` scopes may not have protocol-related fields
+    if (recordsScope.schema !== undefined) {
+      if (recordsScope.protocol !== undefined || recordsScope.contextId !== undefined || recordsScope.protocolPath) {
+        throw new DwnError(
+          DwnErrorCode.PermissionsGrantScopeSchemaProhibitedFields,
+          'PermissionsGrants for RecordsRead and RecordsWrite that have `schema` present may not also have protocol-related properties present'
+        );
+      }
+    }
+
+    if (recordsScope.protocol !== undefined) {
+      // `contextId` and `protocolPath` are mutually exclusive
+      if (recordsScope.contextId !== undefined && recordsScope.protocolPath !== undefined) {
+        throw new DwnError(
+          DwnErrorCode.PermissionsGrantScopeContextIdAndProtocolPath,
+          'PermissionsGrants for RecordsRead and RecordsWrite may not have both `contextId` and `protocolPath` present'
+        );
+      }
+    }
+  }
+}

package/src/interfaces/permissions-request.ts

@@ -0,0 +1,55 @@
+import type { Signer } from '../types/signer.js';
+import type { PermissionConditions, PermissionScope } from '../types/permissions-grant-descriptor.js';
+import type { PermissionsRequestDescriptor, PermissionsRequestMessage } from '../types/permissions-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 { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export type PermissionsRequestOptions = {
+  messageTimestamp?: string;
+  description?: string;
+  grantedTo: string;
+  grantedBy: string;
+  grantedFor: string;
+  scope: PermissionScope;
+  conditions?: PermissionConditions;
+  signer: Signer;
+};
+
+export class PermissionsRequest extends AbstractMessage<PermissionsRequestMessage> {
+
+  public static async parse(message: PermissionsRequestMessage): Promise<PermissionsRequest> {
+    await Message.validateMessageSignatureIntegrity(message.authorization.signature, message.descriptor);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new PermissionsRequest(message);
+  }
+
+  public static async create(options: PermissionsRequestOptions): Promise<PermissionsRequest> {
+    const descriptor: PermissionsRequestDescriptor = {
+      interface        : DwnInterfaceName.Permissions,
+      method           : DwnMethodName.Request,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      description      : options.description,
+      grantedTo        : options.grantedTo,
+      grantedBy        : options.grantedBy,
+      grantedFor       : options.grantedFor,
+      scope            : options.scope,
+      conditions       : options.conditions,
+    };
+
+    // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:
+    // Error: `undefined` is not supported by the IPLD Data Model and cannot be encoded
+    removeUndefinedProperties(descriptor);
+
+    const auth = await Message.createAuthorization({ descriptor, signer: options.signer });
+    const message: PermissionsRequestMessage = { descriptor, authorization: auth };
+
+    Message.validateJsonSchema(message);
+
+    return new PermissionsRequest(message);
+  }
+}

package/src/interfaces/permissions-revoke.ts

@@ -0,0 +1,46 @@
+import type { Signer } from '../types/signer.js';
+import type { PermissionsGrantMessage, PermissionsRevokeDescriptor, PermissionsRevokeMessage } from '../types/permissions-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.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 PermissionsRevokeOptions = {
+  messageTimestamp?: string;
+  permissionsGrantId: string;
+  signer: Signer;
+};
+
+export class PermissionsRevoke extends AbstractMessage<PermissionsRevokeMessage> {
+  public static async parse(message: PermissionsRevokeMessage): Promise<PermissionsRevoke> {
+    await Message.validateMessageSignatureIntegrity(message.authorization.signature, message.descriptor);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new PermissionsRevoke(message);
+  }
+
+  public static async create(options: PermissionsRevokeOptions): Promise<PermissionsRevoke> {
+    const descriptor: PermissionsRevokeDescriptor = {
+      interface          : DwnInterfaceName.Permissions,
+      method             : DwnMethodName.Revoke,
+      messageTimestamp   : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      permissionsGrantId : options.permissionsGrantId,
+    };
+
+    const authorization = await Message.createAuthorization({ descriptor, signer: options.signer });
+    const message: PermissionsRevokeMessage = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+
+    return new PermissionsRevoke(message);
+  }
+
+  public async authorize(permissionsGrantMessage: PermissionsGrantMessage): Promise<void> {
+    if (this.author !== permissionsGrantMessage.descriptor.grantedFor) {
+      // Until delegation is implemented, only the DWN owner may grant or revoke access to their DWN
+      throw new DwnError(DwnErrorCode.PermissionsRevokeUnauthorizedRevoke, 'Only the DWN owner may revoke a grant');
+    }
+  }
+}

package/src/interfaces/protocols-configure.ts

@@ -0,0 +1,188 @@
+import type { Signer } from '../types/signer.js';
+import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureDescriptor, ProtocolsConfigureMessage } from '../types/protocols-types.js';
+
+import { AbstractMessage } from '../core/abstract-message.js';
+import { Message } from '../core/message.js';
+import { ProtocolActor } from '../types/protocols-types.js';
+import { Time } from '../utils/time.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { normalizeProtocolUrl, normalizeSchemaUrl, validateProtocolUrlNormalized, validateSchemaUrlNormalized } from '../utils/url.js';
+
+export type ProtocolsConfigureOptions = {
+  messageTimestamp?: string;
+  definition: ProtocolDefinition;
+  signer: Signer;
+  permissionsGrantId?: string;
+};
+
+export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessage> {
+  public static async parse(message: ProtocolsConfigureMessage): Promise<ProtocolsConfigure> {
+    Message.validateJsonSchema(message);
+    ProtocolsConfigure.validateProtocolDefinition(message.descriptor.definition);
+    await Message.validateMessageSignatureIntegrity(message.authorization.signature, message.descriptor);
+    Time.validateTimestamp(message.descriptor.messageTimestamp);
+
+    return new ProtocolsConfigure(message);
+  }
+
+  public static async create(options: ProtocolsConfigureOptions): Promise<ProtocolsConfigure> {
+    const descriptor: ProtocolsConfigureDescriptor = {
+      interface        : DwnInterfaceName.Protocols,
+      method           : DwnMethodName.Configure,
+      messageTimestamp : options.messageTimestamp ?? Time.getCurrentTimestamp(),
+      definition       : ProtocolsConfigure.normalizeDefinition(options.definition)
+    };
+
+    const authorization = await Message.createAuthorization({
+      descriptor,
+      signer             : options.signer,
+      permissionsGrantId : options.permissionsGrantId
+    });
+    const message = { descriptor, authorization };
+
+    Message.validateJsonSchema(message);
+    ProtocolsConfigure.validateProtocolDefinition(message.descriptor.definition);
+
+    const protocolsConfigure = new ProtocolsConfigure(message);
+    return protocolsConfigure;
+  }
+
+  private static validateProtocolDefinition(definition: ProtocolDefinition): void {
+    const { protocol, types } = definition;
+
+    // validate protocol url
+    validateProtocolUrlNormalized(protocol);
+
+    // validate schema url normalized
+    for (const typeName in types) {
+      const schema = types[typeName].schema;
+      if (schema !== undefined) {
+        validateSchemaUrlNormalized(schema);
+      }
+    }
+
+    // validate `structure
+    ProtocolsConfigure.validateStructure(definition);
+  }
+
+  private static validateStructure(definition: ProtocolDefinition): void {
+    // gather $globalRoles
+    const globalRoles: string[] = [];
+    for (const rootRecordPath in definition.structure) {
+      const rootRuleSet = definition.structure[rootRecordPath];
+      if (rootRuleSet.$globalRole) {
+        globalRoles.push(rootRecordPath);
+      }
+    }
+
+    // Traverse nested rule sets
+    for (const rootRecordPath in definition.structure) {
+      const rootRuleSet = definition.structure[rootRecordPath];
+
+      // gather $contextRoles
+      const contextRoles: string[] = [];
+      for (const childRecordType in rootRuleSet) {
+        if (childRecordType.startsWith('$')) {
+          continue;
+        }
+        const childRuleSet: ProtocolRuleSet = rootRuleSet[childRecordType];
+        if (childRuleSet.$contextRole) {
+          contextRoles.push(`${rootRecordPath}/${childRecordType}`);
+        }
+      }
+
+      ProtocolsConfigure.validateRuleSet(rootRuleSet, rootRecordPath, [...globalRoles, ...contextRoles]);
+    }
+  }
+
+  /**
+   * Validates the given rule set structure then recursively validates its nested child rule sets.
+   */
+  private static validateRuleSet(ruleSet: ProtocolRuleSet, protocolPath: string, roles: string[]): void {
+    const depth = protocolPath.split('/').length;
+    if (ruleSet.$globalRole && depth !== 1) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsConfigureGlobalRoleAtProhibitedProtocolPath,
+        `$globalRole is not allowed at protocol path (${protocolPath}). Only root records may set $globalRole true.`
+      );
+    } else if (ruleSet.$contextRole && depth !== 2) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsConfigureContextRoleAtProhibitedProtocolPath,
+        `$contextRole is not allowed at protocol path (${protocolPath}). Only second-level records may set $contextRole true.`
+      );
+    }
+
+    // Validate $actions in the ruleset
+    const actions = ruleSet.$actions ?? [];
+    for (const action of actions) {
+      // Validate that all `role` properties contain protocol paths $globalRole or $contextRole records
+      if (action.role !== undefined && !roles.includes(action.role)) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidRole,
+          `Invalid role '${action.role}' found at protocol path '${protocolPath}'`
+        );
+      }
+
+      // Validate that if `who` is set to `anyone` then `of` is not set
+      if (action.who === 'anyone' && action.of) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidActionOfNotAllowed,
+          `'of' is not allowed at protocol path (${protocolPath})`
+        );
+      }
+
+      // Validate that if `who === recipient` and `of === undefined`, then `can` is either `delete` or `update`
+      // We will not use direct recipient for `read`, `write`, or `query` because:
+      // - Recipients are always allowed to `read`.
+      // - `write` entails ability to create and update, whereas `update` only allows for updates.
+      //    There is no 'recipient' until the record has been created, so it makes no sense to allow recipient to write.
+      // - At this time, `query` is only authorized using roles, so allowing direct recipients to query is outside the scope of this PR.
+      if (action.who === ProtocolActor.Recipient &&
+          action.of === undefined &&
+          !['update', 'delete'].includes(action.can)
+      ) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidRecipientOfAction,
+          'Rules for `recipient` without `of` property must have `can` === `delete` or `update`'
+        );
+      }
+
+      // Validate that if `who` is set to `author` then `of` is set
+      if (action.who === ProtocolActor.Author && !action.of) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidActionMissingOf,
+          `'of' is required when 'author' is specified as 'who'`
+        );
+      }
+    }
+
+    // Validate nested rule sets
+    for (const recordType in ruleSet) {
+      if (recordType.startsWith('$')) {
+        continue;
+      }
+      const rootRuleSet = ruleSet[recordType];
+      const nextProtocolPath = `${protocolPath}/${recordType}`;
+      ProtocolsConfigure.validateRuleSet(rootRuleSet, nextProtocolPath, roles);
+    }
+  }
+
+  private static normalizeDefinition(definition: ProtocolDefinition): ProtocolDefinition {
+    const typesCopy = { ...definition.types };
+
+    // Normalize schema url
+    for (const typeName in typesCopy) {
+      const schema = typesCopy[typeName].schema;
+      if (schema !== undefined) {
+        typesCopy[typeName].schema = normalizeSchemaUrl(schema);
+      }
+    }
+
+    return {
+      ...definition,
+      protocol : normalizeProtocolUrl(definition.protocol),
+      types    : typesCopy,
+    };
+  }
+}