@enbox/dwn-sdk-js 0.0.7 → 0.0.8

package/src/event-stream/event-emitter-event-log.ts

@@ -0,0 +1,283 @@
+import type { KeyValues } from '../types/query-types.js';
+import type {
+  EventLog,
+  EventLogEntry,
+  EventLogReadOptions,
+  EventLogReadResult,
+  EventLogSubscribeOptions,
+  EventSubscription,
+  MessageEvent,
+  SubscriptionListener,
+} from '../types/subscriptions.js';
+
+import mitt from 'mitt';
+
+import { FilterUtility } from '../utils/filter.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+const EVENTS_LISTENER_CHANNEL = 'events';
+
+/**
+ * Payload shape used internally by mitt. We bundle the three EventListener
+ * arguments into a single object because mitt emits one value per event.
+ */
+type EmitterPayload = { tenant: string; event: MessageEvent; indexes: KeyValues; seq: number };
+
+/**
+ * mitt event map — every channel name maps to an `EmitterPayload`.
+ * Using `Record<string, EmitterPayload>` lets us create channels dynamically.
+ */
+type EmitterEvents = Record<string, EmitterPayload>;
+
+/**
+ * Internal storage entry — the event plus its indexes.
+ */
+type StoredEntry = {
+  event : MessageEvent;
+  indexes : KeyValues;
+};
+
+export interface EventEmitterEventLogConfig {
+  /**
+   * Maximum number of events to retain per tenant.
+   * Oldest events are evicted when the limit is reached.
+   * Defaults to 10_000.
+   */
+  maxEventsPerTenant?: number;
+
+  /**
+   * An optional error handler in order to be able to react to any errors or warnings.
+   * By default we log errors with `console.error`.
+   */
+  errorHandler?: (error: any) => void;
+}
+
+/**
+ * In-memory implementation of {@link EventLog} backed by `mitt` for in-process
+ * pub/sub and a per-tenant `Map<number, StoredEntry>` for persistence with
+ * cursor-based reads.
+ *
+ * Suitable for single-process embedded DWN instances and tests.
+ * For multi-node deployments, use a distributed implementation (NATS, Redis, etc.).
+ */
+export class EventEmitterEventLog implements EventLog {
+  private emitter = mitt<EmitterEvents>();
+  private isOpen: boolean = false;
+  private errorHandler: (error: any) => void = (error): void => { console.error('event log error', error); };
+  private maxEventsPerTenant: number;
+
+  /**
+   * Per-tenant ordered event storage.
+   * Key: tenant DID → Map of seq → StoredEntry.
+   */
+  private tenantLogs: Map<string, Map<number, StoredEntry>> = new Map();
+
+  /**
+   * Per-tenant monotonic sequence counter.
+   */
+  private tenantSeqs: Map<string, number> = new Map();
+
+  constructor(config: EventEmitterEventLogConfig = {}) {
+    this.maxEventsPerTenant = config.maxEventsPerTenant ?? 10_000;
+
+    if (config.errorHandler) {
+      this.errorHandler = config.errorHandler;
+    }
+  }
+
+  public async open(): Promise<void> {
+    this.isOpen = true;
+  }
+
+  public async close(): Promise<void> {
+    this.isOpen = false;
+    this.emitter.all.clear();
+    this.tenantLogs.clear();
+    this.tenantSeqs.clear();
+  }
+
+  public async emit(tenant: string, event: MessageEvent, indexes: KeyValues): Promise<string> {
+    if (!this.isOpen) {
+      this.errorHandler(new DwnError(
+        DwnErrorCode.EventLogNotOpenError,
+        'a message emitted when EventLog is closed'
+      ));
+      return '';
+    }
+
+    // Assign a monotonic sequence number for this tenant.
+    const prevSeq = this.tenantSeqs.get(tenant) ?? 0;
+    const seq = prevSeq + 1;
+    this.tenantSeqs.set(tenant, seq);
+
+    // Persist the event.
+    let log = this.tenantLogs.get(tenant);
+    if (log === undefined) {
+      log = new Map();
+      this.tenantLogs.set(tenant, log);
+    }
+    log.set(seq, { event, indexes });
+
+    // Evict oldest entries if the log exceeds the retention limit.
+    if (log.size > this.maxEventsPerTenant) {
+      const evictCount = log.size - this.maxEventsPerTenant;
+      let evicted = 0;
+      for (const key of log.keys()) {
+        if (evicted >= evictCount) { break; }
+        log.delete(key);
+        evicted++;
+      }
+    }
+
+    // Notify in-process subscribers.
+    const channel = `${tenant}_${EVENTS_LISTENER_CHANNEL}`;
+    this.emitter.emit(channel, { tenant, event, indexes, seq });
+
+    return String(seq);
+  }
+
+  public async read(tenant: string, options: EventLogReadOptions = {}): Promise<EventLogReadResult> {
+    const { cursor, limit, filters } = options;
+    const cursorSeq = cursor !== undefined ? EventEmitterEventLog.parseCursor(cursor) : undefined;
+    const log = this.tenantLogs.get(tenant);
+
+    if (log === undefined || log.size === 0) {
+      return { events: [], cursor };
+    }
+
+    const results: EventLogEntry[] = [];
+    const maxResults = limit ?? Number.MAX_SAFE_INTEGER;
+
+    for (const [seq, entry] of log) {
+      // Skip entries at or before the cursor.
+      if (cursorSeq !== undefined && seq <= cursorSeq) { continue; }
+
+      // Apply filters if provided (OR semantics — match any filter).
+      if (filters !== undefined && filters.length > 0) {
+        if (!FilterUtility.matchAnyFilter(entry.indexes, filters)) { continue; }
+      }
+
+      results.push({
+        seq,
+        event   : entry.event,
+        indexes : entry.indexes,
+      });
+
+      if (results.length >= maxResults) { break; }
+    }
+
+    const lastSeq = results.length > 0 ? results[results.length - 1].seq : undefined;
+    return { events: results, cursor: lastSeq !== undefined ? String(lastSeq) : cursor };
+  }
+
+  /**
+   * Parse an opaque cursor string into an internal sequence number.
+   */
+  private static parseCursor(cursor: string): number {
+    const seq = Number(cursor);
+    if (Number.isNaN(seq) || seq < 0) {
+      throw new DwnError(DwnErrorCode.EventLogNotOpenError, `invalid cursor: '${cursor}'`);
+    }
+    return seq;
+  }
+
+  public async subscribe(
+    tenant: string,
+    id: string,
+    listener: SubscriptionListener,
+    options?: EventLogSubscribeOptions,
+  ): Promise<EventSubscription> {
+    const channel = `${tenant}_${EVENTS_LISTENER_CHANNEL}`;
+    const { cursor, filters } = options ?? {};
+
+    if (cursor !== undefined) {
+      // ---- Cursor mode: catch-up from stored events, then EOSE, then live ----
+      const cursorSeq = EventEmitterEventLog.parseCursor(cursor);
+
+      // Buffer live events that arrive during catch-up to avoid losing them.
+      type BufferedEvent = { event: MessageEvent; seq: number };
+      const pendingLiveEvents: BufferedEvent[] = [];
+      let catchUpComplete = false;
+
+      // Step 1: Register live listener FIRST so no events are missed during read.
+      const handler = (payload: EmitterPayload): void => {
+        if (filters !== undefined && filters.length > 0) {
+          if (!FilterUtility.matchAnyFilter(payload.indexes, filters)) { return; }
+        }
+        if (!catchUpComplete) {
+          pendingLiveEvents.push({ event: payload.event, seq: payload.seq });
+        } else {
+          listener({ type: 'event', cursor: String(payload.seq), event: payload.event });
+        }
+      };
+
+      this.emitter.on(channel, handler);
+
+      // Step 2: Read stored events from cursor and deliver them.
+      const readResult = await this.read(tenant, { cursor, filters });
+      // The read cursor is the last event's seq (string) or the input cursor if nothing new.
+      const eoseCursor = readResult.cursor ?? cursor;
+      const lastCatchUpSeq = readResult.cursor !== undefined ? Number(readResult.cursor) : cursorSeq;
+
+      for (const entry of readResult.events) {
+        listener({ type: 'event', cursor: String(entry.seq), event: entry.event });
+      }
+
+      // Step 3: Deliver any live events that arrived during catch-up (with seq > lastCatchUpSeq).
+      catchUpComplete = true;
+      for (const liveEvent of pendingLiveEvents) {
+        if (liveEvent.seq > lastCatchUpSeq) {
+          listener({ type: 'event', cursor: String(liveEvent.seq), event: liveEvent.event });
+        }
+      }
+
+      // Step 4: Send EOSE marker.
+      listener({ type: 'eose', cursor: eoseCursor });
+
+      return {
+        id,
+        close: async (): Promise<void> => { this.emitter.off(channel, handler); }
+      };
+    }
+
+    // ---- No cursor: live events only ----
+
+    const handler = (payload: EmitterPayload): void => {
+      if (filters !== undefined && filters.length > 0) {
+        if (!FilterUtility.matchAnyFilter(payload.indexes, filters)) { return; }
+      }
+      listener({ type: 'event', cursor: String(payload.seq), event: payload.event });
+    };
+
+    this.emitter.on(channel, handler);
+
+    return {
+      id,
+      close: async (): Promise<void> => { this.emitter.off(channel, handler); }
+    };
+  }
+
+  public async trim(tenant: string, olderThan: number | string): Promise<void> {
+    const log = this.tenantLogs.get(tenant);
+    if (log === undefined) { return; }
+
+    if (typeof olderThan === 'number') {
+      // Trim by sequence number: delete entries with seq < olderThan.
+      for (const seq of log.keys()) {
+        if (seq < olderThan) {
+          log.delete(seq);
+        } else {
+          break; // Map is ordered by insertion (ascending seq), safe to stop.
+        }
+      }
+    } else {
+      // Trim by ISO-8601 timestamp: delete entries whose message timestamp is before the given time.
+      for (const [seq, entry] of log) {
+        const messageTimestamp = (entry.indexes['messageTimestamp'] as string) ?? '';
+        if (messageTimestamp < olderThan) {
+          log.delete(seq);
+        }
+      }
+    }
+  }
+}

package/src/handlers/messages-read.ts

@@ -1,9 +1,7 @@
-import type { DataStore } from '../types/data-store.js';
-import type { DidResolver } from '@enbox/dids';
 import type { GenericMessage } from '../types/message-types.js';
 import type { MessageStore } from '../types/message-store.js';
-import type { MethodHandler } from '../types/method-handler.js';
 import type { RecordsQueryReplyEntry } from '../types/records-types.js';
+import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { MessagesReadMessage, MessagesReadReply, MessagesReadReplyEntry } from '../types/messages-types.js';
 
 import { authenticate } from '../core/auth.js';
@@ -19,7 +17,8 @@ import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 type HandleArgs = { tenant: string, message: MessagesReadMessage };
 
 export class MessagesReadHandler implements MethodHandler {
-  constructor(private didResolver: DidResolver, private messageStore: MessageStore, private dataStore: DataStore) {}
+
+  constructor(private deps: HandlerDependencies) {}
 
   public async handle({ tenant, message }: HandleArgs): Promise<MessagesReadReply> {
     let messagesRead: MessagesRead;
@@ -31,18 +30,18 @@ export class MessagesReadHandler implements MethodHandler {
     }
 
     try {
-      await authenticate(message.authorization, this.didResolver);
+      await authenticate(message.authorization, this.deps.didResolver);
     } catch (e) {
       return messageReplyFromError(e, 401);
     }
 
-    const messageResult = await this.messageStore.get(tenant, message.descriptor.messageCid);
+    const messageResult = await this.deps.messageStore.get(tenant, message.descriptor.messageCid);
     if (messageResult === undefined) {
       return { status: { code: 404, detail: 'Not Found' } };
     }
 
     try {
-      await MessagesReadHandler.authorizeMessagesRead(tenant, messagesRead, messageResult, this.messageStore);
+      await MessagesReadHandler.authorizeMessagesRead(tenant, messagesRead, messageResult, this.deps.messageStore);
     } catch (error) {
       return messageReplyFromError(error, 401);
     }
@@ -59,7 +58,7 @@ export class MessagesReadHandler implements MethodHandler {
         delete recordsWrite.encodedData;
       } else {
         // otherwise check the data store for the associated data
-        const result = await this.dataStore.get(tenant, recordsWrite.recordId, recordsWrite.descriptor.dataCid);
+        const result = await this.deps.dataStore!.get(tenant, recordsWrite.recordId, recordsWrite.descriptor.dataCid);
         if (result?.dataStream !== undefined) {
           entry.data = result.dataStream;
         }
@@ -100,4 +99,4 @@ export class MessagesReadHandler implements MethodHandler {
       throw new DwnError(DwnErrorCode.MessagesReadAuthorizationFailed, 'protocol message failed authorization');
     }
   }
-}
+}

package/src/handlers/messages-subscribe.ts

@@ -1,11 +1,9 @@
-import type { DidResolver } from '@enbox/dids';
 import type { MessageStore } from '../types/message-store.js';
-import type { MethodHandler } from '../types/method-handler.js';
-import type { EventListener, EventStream } from '../types/subscriptions.js';
-import type { MessagesSubscribeMessage, MessagesSubscribeReply, MessageSubscriptionHandler } from '../types/messages-types.js';
+import type { SubscriptionListener } from '../types/subscriptions.js';
+import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
+import type { MessagesSubscribeMessage, MessagesSubscribeReply } from '../types/messages-types.js';
 
 import { authenticate } from '../core/auth.js';
-import { FilterUtility } from '../utils/filter.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
 import { Messages } from '../utils/messages.js';
@@ -15,11 +13,8 @@ import { PermissionsProtocol } from '../protocols/permissions.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
 export class MessagesSubscribeHandler implements MethodHandler {
-  constructor(
-    private didResolver: DidResolver,
-    private messageStore: MessageStore,
-    private eventStream?: EventStream
-  ) {}
+
+  constructor(private deps: HandlerDependencies) {}
 
   public async handle({
     tenant,
@@ -28,11 +23,11 @@ export class MessagesSubscribeHandler implements MethodHandler {
   }: {
     tenant: string;
     message: MessagesSubscribeMessage;
-    subscriptionHandler: MessageSubscriptionHandler;
+    subscriptionHandler: SubscriptionListener;
   }): Promise<MessagesSubscribeReply> {
-    if (this.eventStream === undefined) {
+    if (this.deps.eventLog === undefined) {
       return messageReplyFromError(new DwnError(
-        DwnErrorCode.MessagesSubscribeEventStreamUnimplemented,
+        DwnErrorCode.MessagesSubscribeEventLogUnimplemented,
         'Subscriptions are not supported'
       ), 501);
     }
@@ -45,28 +40,29 @@ export class MessagesSubscribeHandler implements MethodHandler {
     }
 
     try {
-      await authenticate(message.authorization, this.didResolver);
-      await MessagesSubscribeHandler.authorizeMessagesSubscribe(tenant, messagesSubscribe, this.messageStore);
+      await authenticate(message.authorization, this.deps.didResolver);
+      await MessagesSubscribeHandler.authorizeMessagesSubscribe(tenant, messagesSubscribe, this.deps.messageStore);
     } catch (error) {
       return messageReplyFromError(error, 401);
     }
 
-    const { filters } = message.descriptor;
-    const messagesFilters = Messages.convertFilters(filters);
+    const { filters, cursor: eventLogCursor } = message.descriptor;
+    const messagesFilters = Messages.convertFilters(filters, this.deps.coreProtocols);
     const messageCid = await Message.getCid(message);
 
-    const listener: EventListener = (eventTenant, event, eventIndexes):void => {
-      if (tenant === eventTenant && FilterUtility.matchAnyFilter(eventIndexes, messagesFilters)) {
-        subscriptionHandler(event);
-      }
-    };
-
-    const subscription = await this.eventStream.subscribe(tenant, messageCid, listener);
+    try {
+      const subscription = await this.deps.eventLog.subscribe(tenant, messageCid, subscriptionHandler, {
+        cursor  : eventLogCursor,
+        filters : messagesFilters,
+      });
 
-    return {
-      status: { code: 200, detail: 'OK' },
-      subscription,
-    };
+      return {
+        status: { code: 200, detail: 'OK' },
+        subscription,
+      };
+    } catch (error) {
+      return messageReplyFromError(error, 500);
+    }
   }
 
   private static async authorizeMessagesSubscribe(tenant: string, messagesSubscribe: MessagesSubscribe, messageStore: MessageStore): Promise<void> {

package/src/handlers/messages-sync.ts

@@ -1,7 +1,5 @@
-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 { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { MessagesSyncMessage, MessagesSyncReply } from '../types/messages-types.js';
 
 import { authenticate } from '../core/auth.js';
@@ -15,11 +13,7 @@ import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
 export class MessagesSyncHandler implements MethodHandler {
 
-  constructor(
-    private didResolver: DidResolver,
-    private messageStore: MessageStore,
-    private stateIndex: StateIndex,
-  ) { }
+  constructor(private deps: HandlerDependencies) { }
 
   public async handle({
     tenant,
@@ -34,8 +28,8 @@ export class MessagesSyncHandler implements MethodHandler {
     }
 
     try {
-      await authenticate(message.authorization, this.didResolver);
-      await MessagesSyncHandler.authorizeMessagesSync(tenant, messagesSync, this.messageStore);
+      await authenticate(message.authorization, this.deps.didResolver);
+      await MessagesSyncHandler.authorizeMessagesSync(tenant, messagesSync, this.deps.messageStore);
     } catch (e) {
       return messageReplyFromError(e, 401);
     }
@@ -46,8 +40,8 @@ export class MessagesSyncHandler implements MethodHandler {
       switch (action) {
       case 'root': {
         const rootHash = protocol !== undefined
-          ? await this.stateIndex.getProtocolRoot(tenant, protocol)
-          : await this.stateIndex.getRoot(tenant);
+          ? await this.deps.stateIndex!.getProtocolRoot(tenant, protocol)
+          : await this.deps.stateIndex!.getRoot(tenant);
         return {
           status : { code: 200, detail: 'OK' },
           root   : hashToHex(rootHash),
@@ -57,8 +51,8 @@ export class MessagesSyncHandler implements MethodHandler {
       case 'subtree': {
         const bitPath = MessagesSyncHandler.parseBitPrefix(prefix!);
         const hash = protocol !== undefined
-          ? await this.stateIndex.getProtocolSubtreeHash(tenant, protocol, bitPath)
-          : await this.stateIndex.getSubtreeHash(tenant, bitPath);
+          ? await this.deps.stateIndex!.getProtocolSubtreeHash(tenant, protocol, bitPath)
+          : await this.deps.stateIndex!.getSubtreeHash(tenant, bitPath);
         return {
           status : { code: 200, detail: 'OK' },
           hash   : hashToHex(hash),
@@ -68,8 +62,8 @@ export class MessagesSyncHandler implements MethodHandler {
       case 'leaves': {
         const bitPath = MessagesSyncHandler.parseBitPrefix(prefix!);
         const leaves = protocol !== undefined
-          ? await this.stateIndex.getProtocolLeaves(tenant, protocol, bitPath)
-          : await this.stateIndex.getLeaves(tenant, bitPath);
+          ? await this.deps.stateIndex!.getProtocolLeaves(tenant, protocol, bitPath)
+          : await this.deps.stateIndex!.getLeaves(tenant, bitPath);
         return {
           status  : { code: 200, detail: 'OK' },
           entries : leaves,

package/src/handlers/protocols-configure.ts

@@ -1,9 +1,6 @@
-import type { DidResolver } from '@enbox/dids';
-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 { StateIndex } from '../types/state-index.js';
+import type { HandlerDependencies, MethodHandler } from '../types/method-handler.js';
 import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureMessage } from '../types/protocols-types.js';
 
 import { authenticate } from '../core/auth.js';
@@ -18,12 +15,7 @@ import { getRuleSetAtPath, parseCrossProtocolRef } from '../utils/protocols.js';
 
 export class ProtocolsConfigureHandler implements MethodHandler {
 
-  constructor(
-    private didResolver: DidResolver,
-    private messageStore: MessageStore,
-    private stateIndex: StateIndex,
-    private eventStream?: EventStream
-  ) { }
+  constructor(private deps: HandlerDependencies) { }
 
   public async handle({
     tenant,
@@ -38,8 +30,8 @@ export class ProtocolsConfigureHandler implements MethodHandler {
 
     // authentication & authorization
     try {
-      await authenticate(message.authorization, this.didResolver);
-      await ProtocolsConfigureHandler.authorizeProtocolsConfigure(tenant, protocolsConfigure, this.messageStore);
+      await authenticate(message.authorization, this.deps.didResolver);
+      await ProtocolsConfigureHandler.authorizeProtocolsConfigure(tenant, protocolsConfigure, this.deps.messageStore);
     } catch (e) {
       return messageReplyFromError(e, 401);
     }
@@ -48,7 +40,7 @@ export class ProtocolsConfigureHandler implements MethodHandler {
     // `$ref` paths must exist in the referenced protocols, and cross-protocol roles must exist.
     try {
       await ProtocolsConfigureHandler.validateCompositionDependencies(
-        tenant, message.descriptor.definition, this.messageStore
+        tenant, message.descriptor.definition, this.deps.messageStore
       );
     } catch (e) {
       return messageReplyFromError(e, 400);
@@ -60,7 +52,7 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       method    : DwnMethodName.Configure,
       protocol  : message.descriptor.definition.protocol
     };
-    const { messages: existingMessages } = await this.messageStore.query(tenant, [ query ]);
+    const { messages: existingMessages } = await this.deps.messageStore.query(tenant, [ query ]);
 
     // find newest message, and if the incoming message is the newest
     let newestMessage = await Message.getNewestMessage(existingMessages);
@@ -75,13 +67,13 @@ export class ProtocolsConfigureHandler implements MethodHandler {
     if (incomingMessageIsNewest) {
       const indexes = ProtocolsConfigureHandler.constructIndexes(protocolsConfigure, true);
 
-      await this.messageStore.put(tenant, message, indexes);
+      await this.deps.messageStore.put(tenant, message, indexes);
       const messageCid = await Message.getCid(message);
-      await this.stateIndex.insert(tenant, messageCid, indexes);
+      await this.deps.stateIndex!.insert(tenant, messageCid, indexes);
 
-      // only emit if the event stream is set
-      if (this.eventStream !== undefined) {
-        this.eventStream.emit(tenant, { message }, indexes);
+      // only emit if the event log is set
+      if (this.deps.eventLog !== undefined) {
+        await this.deps.eventLog.emit(tenant, { message }, indexes);
       }
 
       messageReply = {
@@ -91,9 +83,9 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       // 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);
+      await this.deps.messageStore.put(tenant, message, indexes);
       const messageCid = await Message.getCid(message);
-      await this.stateIndex.insert(tenant, messageCid, indexes);
+      await this.deps.stateIndex!.insert(tenant, messageCid, indexes);
 
       messageReply = {
         status: { code: 202, detail: 'Accepted' }
@@ -108,8 +100,8 @@ export class ProtocolsConfigureHandler implements MethodHandler {
         const updatedIndexes = ProtocolsConfigureHandler.constructIndexes(existingProtocolsConfigure, false);
         const existingCid = await Message.getCid(existingMessage);
 
-        await this.messageStore.delete(tenant, existingCid);
-        await this.messageStore.put(tenant, existingMessage, updatedIndexes);
+        await this.deps.messageStore.delete(tenant, existingCid);
+        await this.deps.messageStore.put(tenant, existingMessage, updatedIndexes);
       }
     }
 
@@ -230,7 +222,7 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       const childRuleSet = ruleSet[key] as ProtocolRuleSet;
       const childProtocolPath = protocolPath === '' ? key : `${protocolPath}/${key}`;
 
-      // Validate $ref path exists in the referenced protocol
+      // Validate $ref path exists in the referenced protocol and does not traverse through another $ref
       if (childRuleSet.$ref !== undefined) {
         const parsed = parseCrossProtocolRef(childRuleSet.$ref);
         if (parsed !== undefined) {
@@ -244,13 +236,36 @@ export class ProtocolsConfigureHandler implements MethodHandler {
             );
           }
 
-          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}'.`
-            );
+          // Walk the target path segment-by-segment and reject if any intermediate node has a $ref
+          const segments = parsed.protocolPath.split('/');
+          let currentLevel: { [key: string]: ProtocolRuleSet } = refDefinition.structure;
+
+          for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            const node = currentLevel[segment] as ProtocolRuleSet | undefined;
+
+            if (node === undefined) {
+              throw new DwnError(
+                DwnErrorCode.ProtocolsConfigureInvalidRefProtocolPath,
+                `'$ref' at protocol path '${childProtocolPath}' references type path '${parsed.protocolPath}' ` +
+                `which does not exist in protocol '${refDefinition.protocol}'.`
+              );
+            }
+
+            // If any node along the target path (including the final target) has a $ref,
+            // it means the composition chain passes through another protocol boundary.
+            // Multi-level composition is not supported — reject at install time.
+            if (node.$ref !== undefined) {
+              const traversedPath = segments.slice(0, i + 1).join('/');
+              throw new DwnError(
+                DwnErrorCode.ProtocolsConfigureInvalidRefTargetThroughRef,
+                `'$ref' at protocol path '${childProtocolPath}' references type path '${parsed.protocolPath}' ` +
+                `in protocol '${refDefinition.protocol}', but the node '${traversedPath}' is itself ` +
+                `a '$ref' composition point. multi-level composition (chaining through '$ref' nodes) is not supported.`
+              );
+            }
+
+            currentLevel = node as { [key: string]: ProtocolRuleSet };
           }
         }
       }
@@ -312,4 +327,4 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       ProtocolsConfigureHandler.validateRefsAndRolesRecursively(childRuleSet, childProtocolPath, referencedDefinitions);
     }
   }
-}
+}