@enbox/dwn-sdk-js 0.4.14 → 0.4.16

package/src/handlers/protocols-configure.ts

@@ -1,3 +1,4 @@
+import type { Filter } from '../types/query-types.js';
 import type { GenericMessageReply } from '../types/message-types.js';
 import type { ProgressToken } from '../types/subscriptions.js';
 import type { RecordsWriteMessage } from '../types/records-types.js';
@@ -6,12 +7,14 @@ import type { HandlerDependencies, MethodHandler } from '../types/method-handler
 import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureMessage } from '../types/protocols-types.js';
 
 import { authenticate } from '../core/auth.js';
+import { isEncryptionControlPath } from '../core/constants.js';
 import { Message } from '../core/message.js';
 import { messageReplyFromError } from '../core/message-reply.js';
 import { ProtocolAuthorization } from '../core/protocol-authorization.js';
 import { ProtocolsConfigure } from '../interfaces/protocols-configure.js';
 import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
+import { resolveProtocolTypesForPath } from '../core/protocol-authorization-validation.js';
 import { StorageController } from '../store/storage-controller.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
@@ -22,6 +25,7 @@ type StoredInitialWriteConfigValidity = 'valid' | 'invalid' | 'unknown';
 const STORED_INITIAL_WRITE_CONFIG_INVALID_CODES = new Set<string>([
   DwnErrorCode.EncryptionControlValidateAudienceRolePathInvalid,
   DwnErrorCode.EncryptionControlValidateAudienceSealKeyIdMismatch,
+  DwnErrorCode.ProtocolAuthorizationEncryptionNotAllowed,
   DwnErrorCode.ProtocolAuthorizationEncryptionRequired,
   DwnErrorCode.ProtocolAuthorizationIncorrectDataFormat,
   DwnErrorCode.ProtocolAuthorizationInitialWriteRevalidationNotInitial,
@@ -91,8 +95,20 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       }
     }
 
+    let newestMessage = await Message.getNewestMessage(existingMessages) as ProtocolsConfigureMessage | undefined;
+    let prefetchedRecordsWrites: RecordsWriteMessage[] | undefined;
+    try {
+      prefetchedRecordsWrites = await this.validateEncryptionPolicyIsImmutable(
+        tenant,
+        message.descriptor.definition,
+        message.descriptor.messageTimestamp,
+        newestMessage,
+      );
+    } catch (e) {
+      return messageReplyFromError(e, 400);
+    }
+
     // find newest message, and if the incoming message is the newest
-    let newestMessage = await Message.getNewestMessage(existingMessages);
     let incomingMessageIsNewest = false;
     if (newestMessage === undefined || await Message.isNewer(message, newestMessage)) {
       incomingMessageIsNewest = true;
@@ -135,7 +151,11 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       }
     }
 
-    await this.purgeRecordsInvalidatedByProtocolConfig(tenant, message.descriptor.definition.protocol);
+    await this.purgeRecordsInvalidatedByProtocolConfig(
+      tenant,
+      message.descriptor.definition.protocol,
+      prefetchedRecordsWrites,
+    );
 
     return messageReply;
   };
@@ -183,21 +203,230 @@ export class ProtocolsConfigureHandler implements MethodHandler {
     }
   }
 
-  private async purgeRecordsInvalidatedByProtocolConfig(tenant: string, protocol: string): Promise<void> {
+  /**
+   * Prevents a protocol URI from changing the at-rest representation of a path
+   * after records have been admitted under that path. A policy migration must use
+   * a new protocol URI so one store never contains both plaintext and ciphertext
+   * records governed by the same protocol version.
+   */
+  private async validateEncryptionPolicyIsImmutable(
+    tenant: string,
+    incomingDefinition: ProtocolDefinition,
+    incomingTimestamp: string,
+    previousConfiguration: ProtocolsConfigureMessage | undefined,
+  ): Promise<RecordsWriteMessage[] | undefined> {
+    if (previousConfiguration === undefined || !ProtocolsConfigureHandler.hasEncryptionPolicyChange(
+      previousConfiguration.descriptor.definition,
+      incomingDefinition,
+    )) {
+      return undefined;
+    }
+
+    const { messages } = await this.deps.messageStore.query(tenant, [{
+      interface : DwnInterfaceName.Records,
+      method    : DwnMethodName.Write,
+      protocol  : incomingDefinition.protocol,
+    }]);
+    const recordsWrites = messages as RecordsWriteMessage[];
+    const incomingPolicyByPath = new Map<string, boolean>();
+    for (const recordsWrite of recordsWrites) {
+      const { protocolPath } = recordsWrite.descriptor;
+      if (isEncryptionControlPath(protocolPath)) {
+        continue;
+      }
+
+      // Removing a path does not change its representation policy. Existing
+      // records remain governed by the configuration active at their timestamp.
+      if (getRuleSetAtPath(protocolPath, incomingDefinition.structure) === undefined) {
+        continue;
+      }
+
+      let incomingEncryptionRequired = incomingPolicyByPath.get(protocolPath);
+      if (incomingEncryptionRequired === undefined) {
+        const incomingTypes = await resolveProtocolTypesForPath(
+          tenant,
+          protocolPath,
+          incomingDefinition,
+          this.deps.validationStateReader,
+          incomingTimestamp,
+        );
+        incomingEncryptionRequired = incomingTypes[getTypeName(protocolPath)]?.encryptionRequired === true;
+        incomingPolicyByPath.set(protocolPath, incomingEncryptionRequired);
+      }
+
+      if ((recordsWrite.encryption !== undefined) === incomingEncryptionRequired) {
+        continue;
+      }
+
+      throw new DwnError(
+        DwnErrorCode.ProtocolsConfigureEncryptionPolicyImmutable,
+        `cannot change encryption policy for protocol path '${protocolPath}' after records exist; ` +
+        'install the changed definition under a new protocol URI.'
+      );
+    }
+
+    await this.validateComposedEncryptionPolicyIsImmutable(tenant, incomingDefinition);
+    return recordsWrites;
+  }
+
+  /** Prevents a referenced protocol from changing the representation of records stored by composing protocols. */
+  private async validateComposedEncryptionPolicyIsImmutable(
+    tenant: string,
+    incomingDefinition: ProtocolDefinition,
+  ): Promise<void> {
+    const { messages: configurationMessages } = await this.deps.messageStore.query(tenant, [{
+      interface         : DwnInterfaceName.Protocols,
+      isLatestBaseState : true,
+      method            : DwnMethodName.Configure,
+    }]);
+    const policiesByProtocol = ProtocolsConfigureHandler.getComposedPathPolicies(
+      configurationMessages as ProtocolsConfigureMessage[],
+      incomingDefinition,
+    );
+    if (policiesByProtocol.size === 0) {
+      return;
+    }
+
+    const { messages: dependentRecordsWrites } = await this.deps.messageStore.query(
+      tenant,
+      [...policiesByProtocol.keys()].map((protocol): Filter => ({
+        interface : DwnInterfaceName.Records,
+        method    : DwnMethodName.Write,
+        protocol,
+      })),
+    );
+    for (const message of dependentRecordsWrites) {
+      const recordsWrite = message as RecordsWriteMessage;
+      const { protocol, protocolPath } = recordsWrite.descriptor;
+      if (protocol === undefined) {
+        continue;
+      }
+
+      const encryptionRequired = policiesByProtocol.get(protocol)?.get(protocolPath);
+      if (encryptionRequired === undefined || (recordsWrite.encryption !== undefined) === encryptionRequired) {
+        continue;
+      }
+
+      throw new DwnError(
+        DwnErrorCode.ProtocolsConfigureEncryptionPolicyImmutable,
+        `cannot change encryption policy for protocol path '${protocolPath}' imported by protocol '${protocol}' ` +
+        `after records exist; install the changed definition under a new protocol URI.`
+      );
+    }
+  }
+
+  /** Maps each installed composing protocol to root `$ref` paths whose policy comes from the incoming definition. */
+  private static getComposedPathPolicies(
+    configurations: ProtocolsConfigureMessage[],
+    incomingDefinition: ProtocolDefinition,
+  ): Map<string, Map<string, boolean>> {
+    const policiesByProtocol = new Map<string, Map<string, boolean>>();
+    for (const configuration of configurations) {
+      const composingDefinition = configuration.descriptor.definition;
+      const pathPolicies = ProtocolsConfigureHandler.getImportedPathPolicies(
+        composingDefinition,
+        incomingDefinition,
+      );
+      if (pathPolicies.size > 0) {
+        policiesByProtocol.set(composingDefinition.protocol, pathPolicies);
+      }
+    }
+
+    return policiesByProtocol;
+  }
+
+  /** Resolves the effective policy for root `$ref` paths that import one definition. */
+  private static getImportedPathPolicies(
+    composingDefinition: ProtocolDefinition,
+    incomingDefinition: ProtocolDefinition,
+  ): Map<string, boolean> {
+    const pathPolicies = new Map<string, boolean>();
+    const importedAliases = new Set(
+      Object.entries(composingDefinition.uses ?? {})
+        .filter(([, protocol]): boolean => protocol === incomingDefinition.protocol)
+        .map(([alias]): string => alias),
+    );
+    if (importedAliases.size === 0) {
+      return pathPolicies;
+    }
+
+    for (const [protocolPath, ruleSet] of Object.entries(composingDefinition.structure)) {
+      const reference = ruleSet.$ref === undefined ? undefined : parseCrossProtocolRef(ruleSet.$ref);
+      if (reference === undefined || !importedAliases.has(reference.alias)) {
+        continue;
+      }
+
+      const typeName = getTypeName(protocolPath);
+      pathPolicies.set(protocolPath, incomingDefinition.types[typeName]?.encryptionRequired === true);
+    }
+
+    return pathPolicies;
+  }
+
+  /** Returns true when a configure can change a path's stored representation. */
+  private static hasEncryptionPolicyChange(
+    previousDefinition: ProtocolDefinition,
+    incomingDefinition: ProtocolDefinition,
+  ): boolean {
+    const typeNames = new Set([
+      ...Object.keys(previousDefinition.types),
+      ...Object.keys(incomingDefinition.types),
+    ]);
+    for (const typeName of typeNames) {
+      const previousRequired = previousDefinition.types[typeName]?.encryptionRequired === true;
+      const incomingRequired = incomingDefinition.types[typeName]?.encryptionRequired === true;
+      if (previousRequired !== incomingRequired) {
+        return true;
+      }
+    }
+
+    return ProtocolsConfigureHandler.getCompositionEncryptionPolicySignature(previousDefinition) !==
+      ProtocolsConfigureHandler.getCompositionEncryptionPolicySignature(incomingDefinition);
+  }
+
+  /** Captures only composition fields that can redirect a path to another type policy. */
+  private static getCompositionEncryptionPolicySignature(definition: ProtocolDefinition): string {
+    const references: string[] = [];
+    const visit = (ruleSet: ProtocolRuleSet, parentPath: string): void => {
+      for (const [typeName, value] of Object.entries(ruleSet)) {
+        if (typeName.startsWith('$')) {
+          continue;
+        }
+
+        const childRuleSet = value as ProtocolRuleSet;
+        const protocolPath = parentPath === '' ? typeName : `${parentPath}/${typeName}`;
+        if (childRuleSet.$ref !== undefined) {
+          references.push(`${protocolPath}=${childRuleSet.$ref}`);
+        }
+        visit(childRuleSet, protocolPath);
+      }
+    };
+    visit(definition.structure as ProtocolRuleSet, '');
+
+    const uses = Object.entries(definition.uses ?? {})
+      .sort(([left], [right]): number => left.localeCompare(right));
+    references.sort((left, right): number => left.localeCompare(right));
+    return JSON.stringify({ references, uses });
+  }
+
+  private async purgeRecordsInvalidatedByProtocolConfig(
+    tenant: string,
+    protocol: string,
+    prefetchedRecordsWrites?: RecordsWriteMessage[],
+  ): Promise<void> {
     const dataStore = this.deps.dataStore;
     if (dataStore === undefined) {
       return;
     }
 
-    const { messages } = await this.deps.messageStore.query(tenant, [{
+    const recordsWrites = prefetchedRecordsWrites ?? (await this.deps.messageStore.query(tenant, [{
       interface : DwnInterfaceName.Records,
       method    : DwnMethodName.Write,
       protocol,
-    }]);
+    }])).messages as RecordsWriteMessage[];
 
     const checkedRecordIds = new Set<string>();
-    for (const message of messages) {
-      const recordsWriteMessage = message as RecordsWriteMessage;
+    for (const recordsWriteMessage of recordsWrites) {
       if (checkedRecordIds.has(recordsWriteMessage.recordId)) {
         continue;
       }

package/src/index.ts

@@ -25,6 +25,8 @@ export {
   ENCRYPTION_CONTROL_PATHS,
   ENCRYPTION_CONTROL_ROOT_PATH,
   ENCRYPTION_PROTOCOL_URI,
+  ENCRYPTION_PROTOCOL_GRANT_KEY_PATH,
+  ENCRYPTION_PROTOCOL_WRAPPED_GRANT_KEY_PATH,
   PERMISSIONS_REVOCATION_PATH,
   isEncryptionControlPath,
 } from './core/constants.js';
@@ -98,6 +100,7 @@ export {
   getRoleAudienceContextId,
   getRoleContextPrefix,
   getRuleSetAtPath,
+  getTypeName,
   isCrossProtocolRef,
   parseCrossProtocolRef,
 } from './utils/protocols.js';

package/src/protocols/encryption.ts

@@ -10,12 +10,16 @@ import type { ContentEncryptionAlgorithm, X25519KeyEncryptionBase } from '../uti
 
 import { DwnConstant } from '../core/dwn-constant.js';
 import { Encoder } from '../utils/encoder.js';
-import { ENCRYPTION_PROTOCOL_URI } from '../core/constants.js';
 import { FilterUtility } from '../utils/filter.js';
 import { Message } from '../core/message.js';
 import { Records } from '../utils/records.js';
 import { validateJsonSchema } from '../schema-validator.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import {
+  ENCRYPTION_PROTOCOL_GRANT_KEY_PATH,
+  ENCRYPTION_PROTOCOL_URI,
+  ENCRYPTION_PROTOCOL_WRAPPED_GRANT_KEY_PATH,
+} from '../core/constants.js';
 import { grantKeyScopeCoversDeliveredScope, isGrantKeyEligibleRecordsScope, isGrantKeyRecordsScope } from '../utils/grant-key-coverage.js';
 
 export const WRAPPED_GRANT_KEY_FORMAT = 'enbox/wrapped-grant-key@1';
@@ -44,15 +48,21 @@ export function assertWrappedGrantKeyEnvelope(envelope: unknown): asserts envelo
 
 export class EncryptionProtocol implements CoreProtocol {
   public static readonly uri = ENCRYPTION_PROTOCOL_URI;
-  public static readonly grantKeyPath = 'grantKey';
+  public static readonly grantKeyPath = ENCRYPTION_PROTOCOL_GRANT_KEY_PATH;
+  public static readonly wrappedGrantKeyPath = ENCRYPTION_PROTOCOL_WRAPPED_GRANT_KEY_PATH;
 
   public static readonly definition: ProtocolDefinition = {
     published : true,
     protocol  : EncryptionProtocol.uri,
     types     : {
       grantKey: {
+        dataFormats        : ['application/json'],
+        encryptionRequired : true,
+        schema             : 'https://identity.foundation/dwn/json-schemas/encryption/grant-key.json',
+      },
+      wrappedGrantKey: {
         dataFormats : ['application/json'],
-        schema      : 'https://identity.foundation/dwn/json-schemas/encryption/grant-key.json',
+        schema      : 'https://identity.foundation/dwn/json-schemas/encryption/wrapped-grant-key-envelope.json',
       },
     },
     structure: {
@@ -71,6 +81,21 @@ export class EncryptionProtocol implements CoreProtocol {
           protocolPath        : { type: 'string' },
         },
       },
+      wrappedGrantKey: {
+        $actions: [
+          { can: ['create'], who: 'anyone' },
+          { can: ['read'], of: 'wrappedGrantKey', who: 'recipient' },
+        ],
+        $immutable : true,
+        $tags      : {
+          $allowUndefinedTags : false,
+          $requiredTags       : ['grantId', 'protocol', 'keyId'],
+          grantId             : { type: 'string' },
+          keyId               : { maxLength: 43, minLength: 43, pattern: '^[A-Za-z0-9_-]{43}$', type: 'string' },
+          protocol            : { type: 'string' },
+          protocolPath        : { type: 'string' },
+        },
+      },
     }
   };
 
@@ -87,13 +112,13 @@ export class EncryptionProtocol implements CoreProtocol {
     message: RecordsWriteMessage,
     validationStateReader: ValidationStateReader,
   ): Promise<void> {
-    if (message.descriptor.protocolPath === EncryptionProtocol.grantKeyPath) {
+    if (EncryptionProtocol.isGrantKeyPath(message.descriptor.protocolPath)) {
       await EncryptionProtocol.preProcessGrantKey(tenant, message, validationStateReader);
     }
   }
 
   public async validateRecord(message: RecordsWriteMessage, dataBytes: Uint8Array): Promise<void> {
-    if (message.descriptor.protocolPath === EncryptionProtocol.grantKeyPath) {
+    if (EncryptionProtocol.isGrantKeyPath(message.descriptor.protocolPath)) {
       EncryptionProtocol.verifyGrantKeyDelivery(message, dataBytes);
       return;
     }
@@ -109,7 +134,7 @@ export class EncryptionProtocol implements CoreProtocol {
     message: RecordsWriteMessage,
     validationStateReader: ValidationStateReader,
   ): Promise<void> {
-    EncryptionProtocol.verifyInlineWrappedGrantKeyDelivery(message);
+    EncryptionProtocol.verifyGrantKeyRepresentation(message);
 
     const grantId = EncryptionProtocol.getRequiredStringTag(message, 'grantId');
     const protocol = EncryptionProtocol.getRequiredStringTag(message, 'protocol');
@@ -130,21 +155,34 @@ export class EncryptionProtocol implements CoreProtocol {
     });
   }
 
-  private static verifyInlineWrappedGrantKeyDelivery(message: RecordsWriteMessage): void {
-    if (message.encryption !== undefined) {
+  private static verifyGrantKeyRepresentation(message: RecordsWriteMessage): void {
+    if (message.descriptor.protocolPath === EncryptionProtocol.grantKeyPath) {
+      if (message.encryption === undefined) {
+        throw new DwnError(
+          DwnErrorCode.EncryptionProtocolValidateEncryptedDeliveryMissingEncryption,
+          'grantKey records must be encrypted.'
+        );
+      }
       return;
     }
 
+    if (message.encryption !== undefined) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolAuthorizationEncryptionNotAllowed,
+        'wrappedGrantKey records must be plaintext at the DWN record level.'
+      );
+    }
+
     if (message.descriptor.dataSize > DwnConstant.maxDataSizeAllowedToBeEncoded) {
       throw new DwnError(
         DwnErrorCode.EncryptionProtocolValidateEncryptedDeliveryMissingEncryption,
-        'plaintext grantKey records must carry an inline wrapped grantKey envelope.'
+        'wrappedGrantKey records must carry an inline wrapped grantKey envelope.'
       );
     }
   }
 
   private static verifyGrantKeyDelivery(message: RecordsWriteMessage, dataBytes: Uint8Array): void {
-    if (message.encryption !== undefined) {
+    if (message.descriptor.protocolPath === EncryptionProtocol.grantKeyPath) {
       return;
     }
 
@@ -159,11 +197,16 @@ export class EncryptionProtocol implements CoreProtocol {
       const detail = error instanceof Error ? error.message : String(error);
       throw new DwnError(
         DwnErrorCode.EncryptionProtocolValidateEncryptedDeliveryMissingEncryption,
-        `${message.descriptor.protocolPath} records must be encrypted or carry a valid wrapped grantKey envelope: ${detail}`
+        `${message.descriptor.protocolPath} records must carry a valid wrapped grantKey envelope: ${detail}`
       );
     }
   }
 
+  private static isGrantKeyPath(protocolPath: string): boolean {
+    return protocolPath === EncryptionProtocol.grantKeyPath ||
+      protocolPath === EncryptionProtocol.wrappedGrantKeyPath;
+  }
+
   private static getRequiredStringTag(message: RecordsWriteMessage, tag: string): string {
     const value = message.descriptor.tags?.[tag];
     if (typeof value !== 'string') {

package/src/store/message-store-level.ts

@@ -731,8 +731,10 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     const startPosition = cursor === undefined ? 0n : BigInt(cursor.position);
 
     if (head === 0n) {
-      // Nothing to scan — caught up at the input position.
-      return { events: [], cursor, drained: true };
+      // Nothing to scan — caught up at the input position. A caller without a
+      // cursor still gets the position-zero anchor so an empty log yields a
+      // checkpointable token instead of forcing a rescan on every pass.
+      return { events: [], cursor: cursor ?? await this.buildToken(tenant, 0n), drained: true };
     }
 
     const maxResults = limit ?? Number.MAX_SAFE_INTEGER;

package/src/types/messages-types.ts

@@ -87,6 +87,20 @@ export type MessagesSubscribeMessage = {
 
 export type MessagesSubscribeReply = GenericMessageReply & {
   subscription?: MessageSubscription;
+  /**
+   * Feed fingerprint over the subscription's filter scopes, observed after the
+   * subscription became active. Present only when the filters map onto
+   * fingerprint domains and the message store exposes the replication feed.
+   */
+  fingerprint?: string;
+  /**
+   * High-water progress token of the tenant's replication log, observed after
+   * the subscription became active — the position-zero anchor when the log is
+   * empty. NOT a delivery cursor: adopting it as a checkpoint is sound only
+   * after verifying `fingerprint` against the local feed, since resuming from
+   * it skips every earlier log position.
+   */
+  head?: ProgressToken;
   /** Present when status.code is 410 — structured gap metadata. */
   error?: { code: 'ProgressGap' } & ProgressGapInfo;
 };

package/src/types/protocols-types.ts

@@ -53,7 +53,8 @@ export type ProtocolType = {
    * DID must have an X25519 keyAgreement key; protocol installation will
    * fail if it does not.
    *
-   * When `false` or omitted, encryption is not required for this type.
+   * When `false` or omitted, records of this type **must** be plaintext at the
+   * DWN record level. Applications cannot override this protocol policy per write.
    */
   encryptionRequired?: boolean,
 };

package/src/utils/messages.ts

@@ -6,6 +6,7 @@ import type { MessagesFilter } from '../types/messages-types.js';
 import { FilterUtility } from './filter.js';
 import { normalizeProtocolUrl } from './url.js';
 import { Records } from './records.js';
+import { Replication } from './replication.js';
 import { isEmptyObject, removeUndefinedProperties } from '@enbox/common';
 
 type StoredMessageWithEncodedData = GenericMessage & { encodedData?: string };
@@ -122,6 +123,50 @@ export class Messages {
     return metadataFilter;
   }
 
+  /**
+   * Maps a filter set onto the replication fingerprint domains it covers, or
+   * `undefined` when the filters do not correspond to fingerprint domains.
+   * An empty filter set covers the global domain; a set of protocol-only
+   * filters covers each protocol's domain plus its tagged core-protocol
+   * domains. Any other filter shape has no domain mapping.
+   */
+  public static computeFingerprintScopes(filters: MessagesFilter[]): string[] | undefined {
+    if (filters.length === 0) {
+      return [Replication.globalDomain];
+    }
+
+    const protocols = new Set<string>();
+    for (const filter of filters) {
+      const keys = Object.keys(filter);
+      if (keys.length !== 1 || typeof filter.protocol !== 'string') {
+        return undefined;
+      }
+
+      protocols.add(filter.protocol);
+    }
+
+    // Fail closed for filter sets naming a core protocol directly: the core
+    // protocols contribute no tagged domains for themselves, so the domain
+    // set would not span everything such filters enumerate — two feeds could
+    // fingerprint identically while differing in enumerable messages. No
+    // fingerprint beats one whose coverage is known-incomplete.
+    for (const protocol of protocols) {
+      if (Replication.isCoreProtocolUri(protocol)) {
+        return undefined;
+      }
+    }
+
+    const scopes: string[] = [];
+    for (const protocol of protocols) {
+      scopes.push(
+        Replication.protocolDomain(protocol),
+        ...Replication.taggedCoreProtocolDomains(protocol, protocols),
+      );
+    }
+
+    return scopes;
+  }
+
   /**
    * Returns a copy of a RecordsWrite message without inline encodedData, and the
    * detached encodedData value for wire surfaces that carry data beside the message.

package/src/utils/replication.ts

@@ -1,5 +1,6 @@
 import type { GenericMessage } from '../types/message-types.js';
 import type { KeyValues } from '../types/query-types.js';
+import type { ReplicationFeedReader } from '../types/subscriptions.js';
 
 import { EncryptionProtocol } from '../protocols/encryption.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
@@ -44,6 +45,22 @@ export class Replication {
     return domains;
   }
 
+  /**
+   * Narrows a message store to its replication feed surface when it implements
+   * one. Returns `undefined` for stores without replication feed support.
+   */
+  public static asFeedReader(candidate: unknown): ReplicationFeedReader | undefined {
+    const partial = candidate as Partial<ReplicationFeedReader>;
+    if (
+      typeof partial.logRead === 'function' &&
+      typeof partial.logBounds === 'function' &&
+      typeof partial.fingerprint === 'function' &&
+      typeof partial.epoch === 'function'
+    ) {
+      return partial as ReplicationFeedReader;
+    }
+  }
+
   public static async deriveStreamId(tenant: string): Promise<string> {
     const bytes = new TextEncoder().encode(tenant);
     const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
@@ -100,7 +117,8 @@ export class Replication {
     );
   }
 
-  private static isCoreProtocolUri(protocolUri: string): boolean {
+  /** Whether a protocol URI is one of the core protocols (permissions, encryption). */
+  public static isCoreProtocolUri(protocolUri: string): boolean {
     return protocolUri === PermissionsProtocol.uri || protocolUri === EncryptionProtocol.uri;
   }