@enbox/dwn-sdk-js 0.0.1 → 0.0.3

package/src/core/records-grant-authorization.ts

@@ -1,7 +1,7 @@
 import type { MessageStore } from '../types/message-store.js';
 import type { PermissionGrant } from '../protocols/permission-grant.js';
 import type { PermissionConditions, RecordsPermissionScope } from '../types/permission-types.js';
-import type { RecordsDeleteMessage, RecordsQueryMessage, RecordsReadMessage, RecordsSubscribeMessage, RecordsWriteMessage } from '../types/records-types.js';
+import type { RecordsCountMessage, RecordsDeleteMessage, RecordsQueryMessage, RecordsReadMessage, RecordsSubscribeMessage, RecordsWriteMessage } from '../types/records-types.js';
 
 import { GrantAuthorization } from './grant-authorization.js';
 import { PermissionConditionPublication } from '../types/permission-types.js';
@@ -69,7 +69,7 @@ export class RecordsGrantAuthorization {
    * @param messageStore Used to check if the grant has been revoked.
    */
   public static async authorizeQueryOrSubscribe(input: {
-    incomingMessage: RecordsQueryMessage | RecordsSubscribeMessage,
+    incomingMessage: RecordsCountMessage | RecordsQueryMessage | RecordsSubscribeMessage,
     expectedGrantor: string,
     expectedGrantee: string,
     permissionGrant: PermissionGrant,

package/src/core/resumable-task-manager.ts

@@ -90,6 +90,7 @@ export class ResumableTaskManager {
 
   /**
    * Repeatedly retry the given tasks until all are completed successfully.
+   * Tasks are processed sequentially to avoid concurrent database write contention (e.g. SQLite's single-writer lock).
    */
   private async retryTasksUntilCompletion(resumableTasks: ManagedResumableTask[]): Promise<void> {
 
@@ -98,17 +99,15 @@ export class ResumableTaskManager {
       const managedTasksCopy = managedTasks;
       managedTasks = [];
 
-      const allTaskPromises = managedTasksCopy.map(async (managedTask) => {
+      for (const managedTask of managedTasksCopy) {
         try {
           await this.runWithAutomaticTimeoutExtension(managedTask);
         } catch (error) {
           console.error('Error while running resumable task:', error);
-          console.error('Resumable task:', resumableTasks);
+          console.error('Resumable task:', managedTask);
           managedTasks.push(managedTask);
         }
-      });
-
-      await Promise.all(allTaskPromises);
+      }
     }
   }
 }

package/src/dwn.ts

@@ -1,27 +1,27 @@
 
 import type { DataStore } from './types/data-store.js';
 import type { DidResolver } from '@enbox/dids';
-import type { EventLog } from './types/event-log.js';
 import type { EventStream } from './types/subscriptions.js';
 import type { MessageStore } from './types/message-store.js';
 import type { MethodHandler } from './types/method-handler.js';
-import type { Readable } from 'readable-stream';
 import type { ResumableTaskStore } from './types/resumable-task-store.js';
+import type { StateIndex } from './types/state-index.js';
 import type { TenantGate } from './core/tenant-gate.js';
 import type { UnionMessageReply } from './core/message-reply.js';
 import type { GenericMessage, GenericMessageReply } from './types/message-types.js';
-import type { MessagesQueryMessage, MessagesQueryReply, MessagesReadMessage, MessagesReadReply, MessagesSubscribeMessage, MessagesSubscribeMessageOptions, MessagesSubscribeReply, MessageSubscriptionHandler } from './types/messages-types.js';
+import type { MessagesReadMessage, MessagesReadReply, MessagesSubscribeMessage, MessagesSubscribeMessageOptions, MessagesSubscribeReply, MessagesSyncMessage, MessagesSyncReply, MessageSubscriptionHandler } from './types/messages-types.js';
 import type { ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply } from './types/protocols-types.js';
-import type { RecordsDeleteMessage, RecordsQueryMessage, RecordsQueryReply, RecordsReadMessage, RecordsReadReply, RecordsSubscribeMessage, RecordsSubscribeMessageOptions, RecordsSubscribeReply, RecordSubscriptionHandler, RecordsWriteMessage, RecordsWriteMessageOptions } from './types/records-types.js';
+import type { RecordsCountMessage, RecordsCountReply, RecordsDeleteMessage, RecordsQueryMessage, RecordsQueryReply, RecordsReadMessage, RecordsReadReply, RecordsSubscribeMessage, RecordsSubscribeMessageOptions, RecordsSubscribeReply, RecordSubscriptionHandler, RecordsWriteMessage, RecordsWriteMessageOptions } from './types/records-types.js';
 
 import { AllowAllTenantGate } from './core/tenant-gate.js';
 import { Message } from './core/message.js';
 import { messageReplyFromError } from './core/message-reply.js';
-import { MessagesQueryHandler } from './handlers/messages-query.js';
 import { MessagesReadHandler } from './handlers/messages-read.js';
 import { MessagesSubscribeHandler } from './handlers/messages-subscribe.js';
+import { MessagesSyncHandler } from './handlers/messages-sync.js';
 import { ProtocolsConfigureHandler } from './handlers/protocols-configure.js';
 import { ProtocolsQueryHandler } from './handlers/protocols-query.js';
+import { RecordsCountHandler } from './handlers/records-count.js';
 import { RecordsDeleteHandler } from './handlers/records-delete.js';
 import { RecordsQueryHandler } from './handlers/records-query.js';
 import { RecordsReadHandler } from './handlers/records-read.js';
@@ -38,7 +38,7 @@ export class Dwn {
   private messageStore: MessageStore;
   private dataStore: DataStore;
   private resumableTaskStore: ResumableTaskStore;
-  private eventLog: EventLog;
+  private stateIndex: StateIndex;
   private tenantGate: TenantGate;
   private eventStream?: EventStream;
   private storageController: StorageController;
@@ -51,12 +51,12 @@ export class Dwn {
     this.messageStore = config.messageStore;
     this.dataStore = config.dataStore;
     this.resumableTaskStore = config.resumableTaskStore;
-    this.eventLog = config.eventLog;
+    this.stateIndex = config.stateIndex;
     this.eventStream = config.eventStream;
     this.storageController = new StorageController({
       messageStore : this.messageStore,
       dataStore    : this.dataStore,
-      eventLog     : this.eventLog,
+      stateIndex   : this.stateIndex,
       eventStream  : this.eventStream
     });
     this.resumableTaskManager = new ResumableTaskManager(
@@ -65,11 +65,6 @@ export class Dwn {
     );
 
     this.methodHandlers = {
-      [DwnInterfaceName.Messages + DwnMethodName.Query]: new MessagesQueryHandler(
-        this.didResolver,
-        this.messageStore,
-        this.eventLog,
-      ),
       [DwnInterfaceName.Messages + DwnMethodName.Read]: new MessagesReadHandler(
         this.didResolver,
         this.messageStore,
@@ -80,10 +75,15 @@ export class Dwn {
         this.messageStore,
         this.eventStream,
       ),
+      [DwnInterfaceName.Messages + DwnMethodName.Sync]: new MessagesSyncHandler(
+        this.didResolver,
+        this.messageStore,
+        this.stateIndex,
+      ),
       [DwnInterfaceName.Protocols + DwnMethodName.Configure]: new ProtocolsConfigureHandler(
         this.didResolver,
         this.messageStore,
-        this.eventLog,
+        this.stateIndex,
         this.eventStream
       ),
       [DwnInterfaceName.Protocols + DwnMethodName.Query]: new ProtocolsQueryHandler(
@@ -91,6 +91,10 @@ export class Dwn {
         this.messageStore,
         this.dataStore
       ),
+      [DwnInterfaceName.Records + DwnMethodName.Count]: new RecordsCountHandler(
+        this.didResolver,
+        this.messageStore,
+      ),
       [DwnInterfaceName.Records + DwnMethodName.Delete]: new RecordsDeleteHandler(
         this.didResolver,
         this.messageStore,
@@ -115,7 +119,7 @@ export class Dwn {
         this.didResolver,
         this.messageStore,
         this.dataStore,
-        this.eventLog,
+        this.stateIndex,
         this.eventStream
       )
     };
@@ -143,7 +147,7 @@ export class Dwn {
     await this.messageStore.open();
     await this.dataStore.open();
     await this.resumableTaskStore.open();
-    await this.eventLog.open();
+    await this.stateIndex.open();
     await this.eventStream?.open();
 
     await this.resumableTaskManager.resumeTasksAndWaitForCompletion();
@@ -154,19 +158,20 @@ export class Dwn {
     await this.messageStore.close();
     await this.dataStore.close();
     await this.resumableTaskStore.close();
-    await this.eventLog.close();
+    await this.stateIndex.close();
   }
 
   /**
    * Processes the given DWN message and returns with a reply.
    * @param tenant The tenant DID to route the given message to.
    */
-  public async processMessage(tenant: string, rawMessage: MessagesQueryMessage): Promise<MessagesQueryReply>;
   public async processMessage(
     tenant: string, rawMessage: MessagesSubscribeMessage, options?: MessagesSubscribeMessageOptions): Promise<MessagesSubscribeReply>;
   public async processMessage(tenant: string, rawMessage: MessagesReadMessage): Promise<MessagesReadReply>;
+  public async processMessage(tenant: string, rawMessage: MessagesSyncMessage): Promise<MessagesSyncReply>;
   public async processMessage(tenant: string, rawMessage: ProtocolsConfigureMessage): Promise<GenericMessageReply>;
   public async processMessage(tenant: string, rawMessage: ProtocolsQueryMessage): Promise<ProtocolsQueryReply>;
+  public async processMessage(tenant: string, rawMessage: RecordsCountMessage): Promise<RecordsCountReply>;
   public async processMessage(tenant: string, rawMessage: RecordsDeleteMessage): Promise<GenericMessageReply>;
   public async processMessage(tenant: string, rawMessage: RecordsQueryMessage): Promise<RecordsQueryReply>;
   public async processMessage(
@@ -243,7 +248,7 @@ export class Dwn {
  *  MessageOptions that are used when processing a message.
  */
 export interface MessageOptions {
-  dataStream?: Readable;
+  dataStream?: ReadableStream<Uint8Array>;
   subscriptionHandler?: MessageSubscriptionHandler | RecordSubscriptionHandler;
 };
 
@@ -259,6 +264,6 @@ export type DwnConfig = {
 
   messageStore: MessageStore;
   dataStore: DataStore;
-  eventLog: EventLog;
+  stateIndex: StateIndex;
   resumableTaskStore: ResumableTaskStore;
 };

package/src/enums/dwn-interface-method.ts

@@ -6,9 +6,11 @@ export enum DwnInterfaceName {
 
 export enum DwnMethodName {
   Configure = 'Configure',
+  Count = 'Count',
+  Delete = 'Delete',
   Query = 'Query',
   Read = 'Read',
-  Write = 'Write',
-  Delete = 'Delete',
-  Subscribe = 'Subscribe'
+  Subscribe = 'Subscribe',
+  Sync = 'Sync',
+  Write = 'Write'
 }

package/src/handlers/messages-subscribe.ts

@@ -75,7 +75,7 @@ export class MessagesSubscribeHandler implements MethodHandler {
       return;
     } else if (messagesSubscribe.author !== undefined && messagesSubscribe.signaturePayload!.permissionGrantId !== undefined) {
       const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, messagesSubscribe.signaturePayload!.permissionGrantId);
-      await MessagesGrantAuthorization.authorizeQueryOrSubscribe({
+      await MessagesGrantAuthorization.authorizeSubscribeOrSync({
         incomingMessage : messagesSubscribe.message,
         expectedGrantor : tenant,
         expectedGrantee : messagesSubscribe.author,

package/src/handlers/messages-sync.ts

@@ -0,0 +1,129 @@
+import type { DidResolver } from '@enbox/dids';
+import type { MessageStore } from '../types/message-store.js';
+import type { MethodHandler } from '../types/method-handler.js';
+import type { StateIndex } from '../types/state-index.js';
+import type { MessagesSyncMessage, MessagesSyncReply } from '../types/messages-types.js';
+
+import { authenticate } from '../core/auth.js';
+import { hashToHex } from '../smt/smt-utils.js';
+import { messageReplyFromError } from '../core/message-reply.js';
+import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
+import { MessagesSync } from '../interfaces/messages-sync.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+
+export class MessagesSyncHandler implements MethodHandler {
+
+  constructor(
+    private didResolver: DidResolver,
+    private messageStore: MessageStore,
+    private stateIndex: StateIndex,
+  ) { }
+
+  public async handle({
+    tenant,
+    message
+  }: { tenant: string, message: MessagesSyncMessage }): Promise<MessagesSyncReply> {
+    let messagesSync: MessagesSync;
+
+    try {
+      messagesSync = await MessagesSync.parse(message);
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
+    try {
+      await authenticate(message.authorization, this.didResolver);
+      await MessagesSyncHandler.authorizeMessagesSync(tenant, messagesSync, this.messageStore);
+    } catch (e) {
+      return messageReplyFromError(e, 401);
+    }
+
+    const { action, protocol, prefix } = message.descriptor;
+
+    try {
+      switch (action) {
+      case 'root': {
+        const rootHash = protocol !== undefined
+          ? await this.stateIndex.getProtocolRoot(tenant, protocol)
+          : await this.stateIndex.getRoot(tenant);
+        return {
+          status : { code: 200, detail: 'OK' },
+          root   : hashToHex(rootHash),
+        };
+      }
+
+      case 'subtree': {
+        const bitPath = MessagesSyncHandler.parseBitPrefix(prefix!);
+        const hash = protocol !== undefined
+          ? await this.stateIndex.getProtocolSubtreeHash(tenant, protocol, bitPath)
+          : await this.stateIndex.getSubtreeHash(tenant, bitPath);
+        return {
+          status : { code: 200, detail: 'OK' },
+          hash   : hashToHex(hash),
+        };
+      }
+
+      case 'leaves': {
+        const bitPath = MessagesSyncHandler.parseBitPrefix(prefix!);
+        const leaves = protocol !== undefined
+          ? await this.stateIndex.getProtocolLeaves(tenant, protocol, bitPath)
+          : await this.stateIndex.getLeaves(tenant, bitPath);
+        return {
+          status  : { code: 200, detail: 'OK' },
+          entries : leaves,
+        };
+      }
+
+      default: {
+        return {
+          status: { code: 400, detail: `Unknown action: ${action as string}` },
+        };
+      }
+      }
+    } catch (e) {
+      return messageReplyFromError(e, 500);
+    }
+  }
+
+  /**
+   * Parse a bit prefix string (e.g. "0110101") into a boolean array.
+   */
+  private static parseBitPrefix(prefix: string): boolean[] {
+    if (!/^[01]*$/.test(prefix)) {
+      throw new DwnError(
+        DwnErrorCode.MessagesSyncInvalidPrefix,
+        `Invalid prefix: must contain only '0' and '1' characters, got: ${prefix}`
+      );
+    }
+    if (prefix.length > 256) {
+      throw new DwnError(
+        DwnErrorCode.MessagesSyncInvalidPrefix,
+        `Invalid prefix: length must be <= 256, got: ${prefix.length}`
+      );
+    }
+    return Array.from(prefix, (ch): boolean => ch === '1');
+  }
+
+  private static async authorizeMessagesSync(
+    tenant: string,
+    messagesSync: MessagesSync,
+    messageStore: MessageStore
+  ): Promise<void> {
+    if (messagesSync.author === tenant) {
+      return;
+    } else if (messagesSync.author !== undefined && messagesSync.signaturePayload!.permissionGrantId !== undefined) {
+      const permissionGrant = await PermissionsProtocol.fetchGrant(tenant, messageStore, messagesSync.signaturePayload!.permissionGrantId);
+      await MessagesGrantAuthorization.authorizeSubscribeOrSync({
+        incomingMessage : messagesSync.message,
+        expectedGrantor : tenant,
+        expectedGrantee : messagesSync.author,
+        permissionGrant,
+        messageStore
+      });
+    } else {
+      throw new DwnError(DwnErrorCode.MessagesSyncAuthorizationFailed, 'message failed authorization');
+    }
+  }
+}

package/src/handlers/protocols-configure.ts

@@ -1,10 +1,10 @@
 import type { DidResolver } from '@enbox/dids';
-import type { EventLog } from '../types/event-log.js';
 import type { EventStream } from '../types/subscriptions.js';
 import type { GenericMessageReply } from '../types/message-types.js';
 import type { MessageStore } from '../types//message-store.js';
 import type { MethodHandler } from '../types/method-handler.js';
-import type { ProtocolsConfigureMessage } from '../types/protocols-types.js';
+import type { StateIndex } from '../types/state-index.js';
+import type { ProtocolDefinition, ProtocolsConfigureMessage } from '../types/protocols-types.js';
 
 import { authenticate } from '../core/auth.js';
 import { Message } from '../core/message.js';
@@ -14,13 +14,14 @@ import { ProtocolsConfigure } from '../interfaces/protocols-configure.js';
 import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { getRuleSetAtPath, parseCrossProtocolRef } from '../utils/protocols.js';
 
 export class ProtocolsConfigureHandler implements MethodHandler {
 
   constructor(
     private didResolver: DidResolver,
     private messageStore: MessageStore,
-    private eventLog: EventLog,
+    private stateIndex: StateIndex,
     private eventStream?: EventStream
   ) { }
 
@@ -43,6 +44,16 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       return messageReplyFromError(e, 401);
     }
 
+    // validate composition dependencies: all `uses` protocols must already be installed,
+    // `$ref` paths must exist in the referenced protocols, and cross-protocol roles must exist.
+    try {
+      await ProtocolsConfigureHandler.validateCompositionDependencies(
+        tenant, message.descriptor.definition, this.messageStore
+      );
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
     // attempt to get existing protocol
     const query = {
       interface : DwnInterfaceName.Protocols,
@@ -62,11 +73,11 @@ export class ProtocolsConfigureHandler implements MethodHandler {
     // write the incoming message to DB if incoming message is newest
     let messageReply: GenericMessageReply;
     if (incomingMessageIsNewest) {
-      const indexes = ProtocolsConfigureHandler.constructIndexes(protocolsConfigure);
+      const indexes = ProtocolsConfigureHandler.constructIndexes(protocolsConfigure, true);
 
       await this.messageStore.put(tenant, message, indexes);
       const messageCid = await Message.getCid(message);
-      await this.eventLog.append(tenant, messageCid, indexes);
+      await this.stateIndex.insert(tenant, messageCid, indexes);
 
       // only emit if the event stream is set
       if (this.eventStream !== undefined) {
@@ -77,28 +88,35 @@ export class ProtocolsConfigureHandler implements MethodHandler {
         status: { code: 202, detail: 'Accepted' }
       };
     } else {
+      // incoming message is older — still store it as a historical version (not the latest)
+      const indexes = ProtocolsConfigureHandler.constructIndexes(protocolsConfigure, false);
+
+      await this.messageStore.put(tenant, message, indexes);
+      const messageCid = await Message.getCid(message);
+      await this.stateIndex.insert(tenant, messageCid, indexes);
+
       messageReply = {
-        status: { code: 409, detail: 'Conflict' }
+        status: { code: 202, detail: 'Accepted' }
       };
     }
 
-    // delete all existing records that are smaller
-    const deletedMessageCids: string[] = [];
-    for (const message of existingMessages) {
-      if (await Message.isNewer(newestMessage, message)) {
-        const messageCid = await Message.getCid(message);
-        deletedMessageCids.push(messageCid);
+    // re-index previously-latest messages as no longer the latest base state.
+    // We must delete and re-put (not just put) to properly replace old index entries.
+    for (const existingMessage of existingMessages) {
+      if (existingMessage !== newestMessage) {
+        const existingProtocolsConfigure = await ProtocolsConfigure.parse(existingMessage as ProtocolsConfigureMessage);
+        const updatedIndexes = ProtocolsConfigureHandler.constructIndexes(existingProtocolsConfigure, false);
+        const existingCid = await Message.getCid(existingMessage);
 
-        await this.messageStore.delete(tenant, messageCid);
+        await this.messageStore.delete(tenant, existingCid);
+        await this.messageStore.put(tenant, existingMessage, updatedIndexes);
       }
     }
 
-    await this.eventLog.deleteEventsByCid(tenant, deletedMessageCids);
-
     return messageReply;
   };
 
-  static constructIndexes(protocolsConfigure: ProtocolsConfigure): { [key: string]: string | boolean } {
+  static constructIndexes(protocolsConfigure: ProtocolsConfigure, isLatestBaseState: boolean): { [key: string]: string | boolean } {
     // strip out `definition` as it is not indexable
     const { definition, ...propertiesToIndex } = protocolsConfigure.message.descriptor;
     const { author } = protocolsConfigure;
@@ -107,7 +125,8 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       ...propertiesToIndex,
       author    : author!,
       protocol  : definition.protocol, // retain protocol url from `definition`,
-      published : definition.published // retain published state from definition
+      published : definition.published, // retain published state from definition
+      isLatestBaseState,
     };
 
     return indexes;
@@ -134,4 +153,163 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       throw new DwnError(DwnErrorCode.ProtocolsConfigureAuthorizationFailed, 'message failed authorization');
     }
   }
+
+  /**
+   * Validates composition dependencies at install time:
+   * 1. All `uses` protocols must already be installed for the tenant.
+   * 2. Each `$ref` path must exist in the referenced protocol's structure.
+   * 3. Cross-protocol role references must point to valid role paths in the referenced protocol.
+   *
+   * This is a no-op if the protocol definition has no `uses` map.
+   */
+  private static async validateCompositionDependencies(
+    tenant: string, definition: ProtocolDefinition, messageStore: MessageStore
+  ): Promise<void> {
+    const { uses } = definition;
+    if (uses === undefined) {
+      return;
+    }
+
+    // Fetch all referenced protocol definitions
+    const referencedDefinitions = new Map<string, ProtocolDefinition>();
+    for (const alias in uses) {
+      const protocolUri = uses[alias];
+      const refDefinition = await ProtocolsConfigureHandler.fetchInstalledProtocolDefinition(tenant, protocolUri, messageStore);
+
+      if (refDefinition === undefined) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureComposedProtocolNotInstalled,
+          `composed protocol '${protocolUri}' (alias '${alias}') is not installed for tenant '${tenant}'.`
+        );
+      }
+
+      referencedDefinitions.set(alias, refDefinition);
+    }
+
+    // Walk the structure and validate all $ref paths and cross-protocol role references
+    ProtocolsConfigureHandler.validateRefsAndRolesRecursively(definition.structure, '', referencedDefinitions);
+  }
+
+  /**
+   * Fetches the latest installed protocol definition for the given protocol URI.
+   * @returns The protocol definition, or `undefined` if not installed.
+   */
+  private static async fetchInstalledProtocolDefinition(
+    tenant: string, protocolUri: string, messageStore: MessageStore
+  ): Promise<ProtocolDefinition | undefined> {
+    const query = {
+      interface         : DwnInterfaceName.Protocols,
+      method            : DwnMethodName.Configure,
+      protocol          : protocolUri,
+      isLatestBaseState : true
+    };
+    const { messages } = await messageStore.query(tenant, [query]);
+
+    if (messages.length === 0) {
+      return undefined;
+    }
+
+    return (messages[0] as ProtocolsConfigureMessage).descriptor.definition;
+  }
+
+  /**
+   * Recursively walks the structure tree to validate:
+   * - `$ref` type paths exist in the referenced protocol's structure
+   * - Cross-protocol `role` references point to valid `$role: true` paths in the referenced protocol
+   */
+  private static validateRefsAndRolesRecursively(
+    ruleSet: { [key: string]: any },
+    protocolPath: string,
+    referencedDefinitions: Map<string, ProtocolDefinition>
+  ): void {
+    for (const key in ruleSet) {
+      if (key.startsWith('$')) {
+        continue;
+      }
+
+      const childRuleSet = ruleSet[key];
+      const childProtocolPath = protocolPath === '' ? key : `${protocolPath}/${key}`;
+
+      // Validate $ref path exists in the referenced protocol
+      if (childRuleSet.$ref !== undefined) {
+        const parsed = parseCrossProtocolRef(childRuleSet.$ref);
+        if (parsed !== undefined) {
+          const refDefinition = referencedDefinitions.get(parsed.alias);
+          if (refDefinition === undefined) {
+            // Defensive: alias was validated by validateRefNode() and definition was fetched by validateCompositionDependencies()
+            throw new DwnError(
+              DwnErrorCode.ProtocolsConfigureInvalidRefAlias,
+              `'$ref' alias '${parsed.alias}' at protocol path '${childProtocolPath}' ` +
+              `was not found in the referenced definitions map.`
+            );
+          }
+
+          const targetRuleSet = getRuleSetAtPath(parsed.protocolPath, refDefinition.structure);
+          if (targetRuleSet === undefined) {
+            throw new DwnError(
+              DwnErrorCode.ProtocolsConfigureInvalidRefProtocolPath,
+              `'$ref' at protocol path '${childProtocolPath}' references type path '${parsed.protocolPath}' ` +
+              `which does not exist in protocol '${refDefinition.protocol}'.`
+            );
+          }
+        }
+      }
+
+      // Validate cross-protocol references in $actions (roles and `of` paths)
+      const actionRules = childRuleSet.$actions ?? [];
+      for (const actionRule of actionRules) {
+        // Validate cross-protocol role references
+        if (actionRule.role !== undefined) {
+          const parsed = parseCrossProtocolRef(actionRule.role);
+          if (parsed !== undefined) {
+            const refDefinition = referencedDefinitions.get(parsed.alias);
+            if (refDefinition === undefined) {
+              throw new DwnError(
+                DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolRole,
+                `cross-protocol role alias '${parsed.alias}' in '${actionRule.role}' at protocol path '${childProtocolPath}' ` +
+                `was not found in the referenced definitions map.`
+              );
+            }
+
+            // Check that the role path exists and is marked $role: true in the referenced protocol
+            const roleRuleSet = getRuleSetAtPath(parsed.protocolPath, refDefinition.structure);
+            if (roleRuleSet === undefined || !roleRuleSet.$role) {
+              throw new DwnError(
+                DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolRole,
+                `cross-protocol role '${actionRule.role}' at protocol path '${childProtocolPath}' ` +
+                `does not point to a valid role ($role: true) in protocol '${refDefinition.protocol}'.`
+              );
+            }
+          }
+        }
+
+        // Validate cross-protocol `of` references: the path must exist in the referenced protocol's structure
+        if (actionRule.of !== undefined) {
+          const parsed = parseCrossProtocolRef(actionRule.of);
+          if (parsed !== undefined) {
+            const refDefinition = referencedDefinitions.get(parsed.alias);
+            if (refDefinition === undefined) {
+              throw new DwnError(
+                DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolOf,
+                `cross-protocol 'of' alias '${parsed.alias}' in '${actionRule.of}' at protocol path '${childProtocolPath}' ` +
+                `was not found in the referenced definitions map.`
+              );
+            }
+
+            const ofRuleSet = getRuleSetAtPath(parsed.protocolPath, refDefinition.structure);
+            if (ofRuleSet === undefined) {
+              throw new DwnError(
+                DwnErrorCode.ProtocolsConfigureInvalidCrossProtocolOf,
+                `cross-protocol 'of' reference '${actionRule.of}' at protocol path '${childProtocolPath}' ` +
+                `does not point to a valid type path in protocol '${refDefinition.protocol}'.`
+              );
+            }
+          }
+        }
+      }
+
+      // Recurse into children
+      ProtocolsConfigureHandler.validateRefsAndRolesRecursively(childRuleSet, childProtocolPath, referencedDefinitions);
+    }
+  }
 }

package/src/handlers/protocols-query.ts

@@ -52,8 +52,9 @@ export class ProtocolsQueryHandler implements MethodHandler {
 
     const query = {
       ...message.descriptor.filter,
-      interface : DwnInterfaceName.Protocols,
-      method    : DwnMethodName.Configure
+      interface         : DwnInterfaceName.Protocols,
+      method            : DwnMethodName.Configure,
+      isLatestBaseState : true,
     };
     removeUndefinedProperties(query);
 
@@ -72,9 +73,10 @@ export class ProtocolsQueryHandler implements MethodHandler {
     // fetch all published `ProtocolConfigure` matching the query
     const filter = {
       ...protocolsQuery.message.descriptor.filter,
-      interface : DwnInterfaceName.Protocols,
-      method    : DwnMethodName.Configure,
-      published : true
+      interface         : DwnInterfaceName.Protocols,
+      method            : DwnMethodName.Configure,
+      published         : true,
+      isLatestBaseState : true,
     };
     const { messages: publishedProtocolsConfigure } = await this.messageStore.query(tenant, [ filter ]);
     return publishedProtocolsConfigure as ProtocolsConfigureMessage[];