@enbox/dwn-sdk-js 0.3.7 → 0.3.9

package/src/sync/records-projection.ts

@@ -0,0 +1,328 @@
+import type { Filter } from '../types/query-types.js';
+import type { Hash } from '../types/smt-types.js';
+import type { MessageStore, MessageStoreOptions } from '../types/message-store.js';
+
+import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
+import { FilterUtility } from '../utils/filter.js';
+import { hashToHex } from '../smt/smt-utils.js';
+import { isRecordsPrimaryProjectionExcludedProtocol } from '../core/constants.js';
+import { lexicographicalCompare } from '../utils/string.js';
+import { Message } from '../core/message.js';
+import { SMTStoreMemory } from '../smt/smt-store-memory.js';
+import { SparseMerkleTree } from '../smt/sparse-merkle-tree.js';
+
+/**
+ * Projection-root algorithm for record-primary scoped subsets.
+ *
+ * This version builds an on-demand SMT over latest Records primary message CIDs
+ * selected by protocol plus optional exact protocolPath or context subtree.
+ * Dependency records, protocol configs, and record data payloads are not part
+ * of this root.
+ */
+export const RECORDS_PROJECTION_ROOT_VERSION = 'records-primary-scope-root-v1';
+
+/**
+ * A Records primary projection scope.
+ *
+ * `protocolPath` is an exact type-path match. `contextId` is a boundary-aware
+ * subtree match: the candidate context must equal the scoped context or start
+ * with `${contextId}/`. `protocolPath` and `contextId` are mutually exclusive.
+ */
+export type RecordsProjectionScope = {
+  protocol: string;
+  protocolPath?: string;
+  contextId?: string;
+};
+
+export type RecordsProjectionInput = {
+  tenant: string;
+  messageStore: MessageStore;
+  scopes: readonly [RecordsProjectionScope, ...RecordsProjectionScope[]];
+  options?: MessageStoreOptions;
+};
+
+export type RecordsProjectionTreeInput = RecordsProjectionInput & {
+  prefix: boolean[];
+};
+
+export type RecordsProjectionSnapshot = {
+  getRoot(): Promise<Hash>;
+  getRootHex(): Promise<string>;
+  getSubtreeHash(prefix: boolean[]): Promise<Hash>;
+  getLeaves(prefix: boolean[]): Promise<string[]>;
+  close(): Promise<void>;
+};
+
+export type NormalizedRecordsProjectionScope = {
+  protocol: string;
+} | {
+  protocol: string;
+  protocolPath: string;
+} | {
+  protocol: string;
+  contextId: string;
+};
+
+/**
+ * Computes deterministic on-demand roots for Records projections.
+ *
+ * The snapshot API performs one store enumeration and serves tree operations
+ * from that in-memory view. A future store-level snapshot/high-watermark can be
+ * threaded through the `options` input without changing the projection shape.
+ */
+export class RecordsProjection {
+
+  /**
+   * Returns the sorted latest Records primary message CIDs covered by a scope union.
+   */
+  public static async getPrimaryMessageCids({
+    tenant,
+    messageStore,
+    scopes,
+    options,
+  }: RecordsProjectionInput): Promise<string[]> {
+    const filters = RecordsProjection.normalizeScopes(scopes)
+      .filter(scope => !isRecordsPrimaryProjectionExcludedProtocol(scope.protocol))
+      .flatMap(scope => RecordsProjection.constructFilters(scope));
+    if (filters.length === 0) {
+      return [];
+    }
+
+    const { messages } = await messageStore.query(tenant, filters, undefined, undefined, options);
+    const messageCids = await Promise.all(messages.map(message => Message.getCid(message)));
+
+    return [...new Set(messageCids)].sort(lexicographicalCompare); // NOSONAR — projection IDs require locale-independent bytewise ordering.
+  }
+
+  /**
+   * Returns the projection root hash.
+   */
+  public static async getRoot(input: RecordsProjectionInput): Promise<Hash> {
+    return RecordsProjection.withTree(input, tree => tree.getRoot());
+  }
+
+  /**
+   * Returns the projection root hash encoded as lowercase hex.
+   */
+  public static async getRootHex(input: RecordsProjectionInput): Promise<string> {
+    return hashToHex(await RecordsProjection.getRoot(input));
+  }
+
+  /**
+   * Returns the subtree hash for a bit prefix within this projection.
+   */
+  public static async getSubtreeHash(input: RecordsProjectionTreeInput): Promise<Hash> {
+    return RecordsProjection.withTree(input, tree => tree.getSubtreeHash(input.prefix));
+  }
+
+  /**
+   * Returns the message CIDs under a bit prefix within this projection.
+   */
+  public static async getLeaves(input: RecordsProjectionTreeInput): Promise<string[]> {
+    return RecordsProjection.withTree(input, tree => tree.getLeaves(input.prefix));
+  }
+
+  /**
+   * Builds an in-memory projection tree from one primary-CID enumeration.
+   */
+  public static async createSnapshot(input: RecordsProjectionInput): Promise<RecordsProjectionSnapshot> {
+    const tree = await RecordsProjection.createTree(input);
+    return {
+      close          : () => tree.close(),
+      getLeaves      : (prefix: boolean[]) => tree.getLeaves(prefix),
+      getRoot        : () => tree.getRoot(),
+      getRootHex     : async () => hashToHex(await tree.getRoot()),
+      getSubtreeHash : (prefix: boolean[]) => tree.getSubtreeHash(prefix),
+    };
+  }
+
+  /**
+   * Normalizes a scope union into sorted, duplicate-free, subsumption-reduced entries.
+   */
+  public static normalizeScopes(
+    scopes: readonly [RecordsProjectionScope, ...RecordsProjectionScope[]],
+  ): [NormalizedRecordsProjectionScope, ...NormalizedRecordsProjectionScope[]] {
+    if (scopes.length === 0) {
+      throw new Error('RecordsProjection: scopes must contain at least one scope.');
+    }
+
+    const normalized = scopes.map(scope => RecordsProjection.normalizeScope(scope));
+    const deduped = new Map<string, NormalizedRecordsProjectionScope>();
+    for (const scope of normalized) {
+      deduped.set(RecordsProjection.scopeKey(scope), scope);
+    }
+
+    const uniqueScopes = [...deduped.values()];
+    const protocolWide = new Set(
+      uniqueScopes
+        .filter(scope => RecordsProjection.isProtocolWideScope(scope))
+        .map(scope => scope.protocol)
+    );
+
+    const reduced = uniqueScopes.filter(scope => {
+      if (protocolWide.has(scope.protocol)) {
+        return RecordsProjection.isProtocolWideScope(scope);
+      }
+
+      if (RecordsProjection.isContextScope(scope)) {
+        return !uniqueScopes.some(candidate =>
+          candidate !== scope &&
+          RecordsProjection.isContextScope(candidate) &&
+          candidate.protocol === scope.protocol &&
+          RecordsProjection.contextIdSubsumes(candidate.contextId, scope.contextId)
+        );
+      }
+
+      return true;
+    });
+
+    const result = reduced.sort(RecordsProjection.compareScopes);
+    return result as [NormalizedRecordsProjectionScope, ...NormalizedRecordsProjectionScope[]];
+  }
+
+  private static async withTree<T>(
+    input: RecordsProjectionInput,
+    fn: (tree: SparseMerkleTree) => Promise<T>,
+  ): Promise<T> {
+    const tree = await RecordsProjection.createTree(input);
+
+    try {
+      return await fn(tree);
+    } finally {
+      await tree.close();
+    }
+  }
+
+  private static async createTree(input: RecordsProjectionInput): Promise<SparseMerkleTree> {
+    const tree = new SparseMerkleTree(new SMTStoreMemory());
+    await tree.initialize();
+
+    try {
+      const messageCids = await RecordsProjection.getPrimaryMessageCids(input);
+      for (const messageCid of messageCids) {
+        await tree.insert(messageCid);
+      }
+
+      return tree;
+    } catch (error) {
+      await tree.close();
+      throw error;
+    }
+  }
+
+  private static normalizeScope(scope: RecordsProjectionScope): NormalizedRecordsProjectionScope {
+    const protocol = RecordsProjection.requireNonEmptyString(scope.protocol, 'protocol');
+
+    if (scope.protocolPath !== undefined && scope.contextId !== undefined) {
+      throw new Error('RecordsProjection: protocolPath and contextId scopes are mutually exclusive.');
+    }
+
+    if (scope.protocolPath !== undefined) {
+      return {
+        protocol,
+        protocolPath: RecordsProjection.requireNonEmptyString(scope.protocolPath, 'protocolPath'),
+      };
+    }
+
+    if (scope.contextId !== undefined) {
+      return {
+        protocol,
+        contextId: RecordsProjection.requireNonEmptyString(scope.contextId, 'contextId'),
+      };
+    }
+
+    return { protocol };
+  }
+
+  private static constructFilters(scope: NormalizedRecordsProjectionScope): Filter[] {
+    const baseFilter: Filter = {
+      interface         : DwnInterfaceName.Records,
+      isLatestBaseState : true,
+      protocol          : scope.protocol,
+    };
+
+    if ('protocolPath' in scope) {
+      return [{ ...baseFilter, protocolPath: scope.protocolPath }];
+    }
+
+    if ('contextId' in scope) {
+      const childContextPrefix = `${scope.contextId}/`;
+      return [
+        { ...baseFilter, contextId: scope.contextId },
+        {
+          ...baseFilter,
+          contextId: FilterUtility.constructPrefixFilterAsRangeFilter(childContextPrefix),
+        },
+      ];
+    }
+
+    return [baseFilter];
+  }
+
+  private static requireNonEmptyString(value: string, field: string): string {
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error(`RecordsProjection: ${field} must be a non-empty string.`);
+    }
+
+    return value;
+  }
+
+  private static scopeKey(scope: NormalizedRecordsProjectionScope): string {
+    if ('protocolPath' in scope) {
+      return `${scope.protocol}\u001fprotocolPath\u001f${scope.protocolPath}`;
+    }
+
+    if ('contextId' in scope) {
+      return `${scope.protocol}\u001fcontextId\u001f${scope.contextId}`;
+    }
+
+    return `${scope.protocol}\u001fprotocol`;
+  }
+
+  private static isProtocolWideScope(
+    scope: NormalizedRecordsProjectionScope,
+  ): scope is { protocol: string } {
+    return !('protocolPath' in scope) && !('contextId' in scope);
+  }
+
+  private static isContextScope(
+    scope: NormalizedRecordsProjectionScope,
+  ): scope is { protocol: string; contextId: string } {
+    return 'contextId' in scope;
+  }
+
+  private static contextIdSubsumes(parentContextId: string, childContextId: string): boolean {
+    return childContextId === parentContextId ||
+      childContextId.startsWith(`${parentContextId}/`);
+  }
+
+  private static compareScopes(
+    a: NormalizedRecordsProjectionScope,
+    b: NormalizedRecordsProjectionScope,
+  ): number {
+    const protocolCompare = lexicographicalCompare(a.protocol, b.protocol);
+    if (protocolCompare !== 0) {
+      return protocolCompare;
+    }
+
+    const aRank = RecordsProjection.scopeRank(a);
+    const bRank = RecordsProjection.scopeRank(b);
+    if (aRank !== bRank) {
+      return aRank - bRank;
+    }
+
+    return lexicographicalCompare(RecordsProjection.scopeValue(a), RecordsProjection.scopeValue(b));
+  }
+
+  private static scopeRank(scope: NormalizedRecordsProjectionScope): number {
+    if ('protocolPath' in scope) { return 1; }
+    if ('contextId' in scope) { return 2; }
+    return 0;
+  }
+
+  private static scopeValue(scope: NormalizedRecordsProjectionScope): string {
+    if ('protocolPath' in scope) { return scope.protocolPath; }
+    if ('contextId' in scope) { return scope.contextId; }
+    return '';
+  }
+}

package/src/types/message-types.ts

@@ -92,6 +92,7 @@ export type DelegatedGrantRecordsWriteMessage = {
 export type GenericSignaturePayload = {
   descriptorCid: string;
   permissionGrantId?: string;
+  permissionGrantIds?: string[];
 
   /**
    * Record ID of a permission grant DWN `RecordsWrite` with `delegated` set to `true`.

package/src/types/messages-types.ts

@@ -24,7 +24,7 @@ export type MessagesReadDescriptor = {
   method: DwnMethodName.Read;
   messageCid: string;
   messageTimestamp: string;
-  permissionGrantId?: string;
+  permissionGrantIds?: string[];
 };
 
 export type MessagesReadMessage = GenericMessage & {
@@ -50,8 +50,14 @@ export type MessagesSyncDescriptor = {
   messageTimestamp : string;
   action : MessagesSyncAction;
   protocol? : string; // optional protocol scope
+  projectionRootVersion?: string;
+  projectionScopes?: {
+    protocol: string;
+    protocolPath?: string;
+    contextId?: string;
+  }[];
   prefix? : string; // bit path for subtree/leaves (e.g. "0110101...")
-  permissionGrantId? : string;
+  permissionGrantIds? : string[];
   /**
    * For `action: 'diff'`: a map of `{ bitPrefix: hexHash }` representing the client's
    * subtree hashes at `depth`. The server compares each hash against its own tree
@@ -85,6 +91,18 @@ export type MessagesSyncDiffEntry = {
   encodedData? : string;
 };
 
+export type MessagesSyncDependencyClass = 'protocolsConfigure' | 'recordsInitialWrite';
+
+/**
+ * Advisory dependency hint returned with projected diff responses. Dependency
+ * entries are not part of the projected root; clients must rederive that the
+ * dependency is required by the referenced primary before applying it.
+ */
+export type MessagesSyncDependencyEntry = MessagesSyncDiffEntry & {
+  dependencyClass: MessagesSyncDependencyClass;
+  rootMessageCid: string;
+};
+
 export type MessagesSyncReply = GenericMessageReply & {
   root? : string; // hex-encoded root hash (for 'root' action)
   hash? : string; // hex-encoded subtree hash (for 'subtree' action)
@@ -93,6 +111,8 @@ export type MessagesSyncReply = GenericMessageReply & {
   onlyRemote? : MessagesSyncDiffEntry[];
   /** For 'diff' action: bit prefixes where the client has entries the server doesn't. */
   onlyLocal? : string[];
+  /** Advisory dependency messages needed to apply projected `onlyRemote` primary entries. */
+  dependencies? : MessagesSyncDependencyEntry[];
 };
 
 export type MessagesSubscribeMessageOptions = {
@@ -115,7 +135,7 @@ export type MessagesSubscribeDescriptor = {
   method: DwnMethodName.Subscribe;
   messageTimestamp: string;
   filters: MessagesFilter[];
-  permissionGrantId?: string;
+  permissionGrantIds?: string[];
   /**
    * Progress token to resume from. When provided, the handler replays events
    * from the EventLog starting after this position instead of returning no

package/src/types/permission-types.ts

@@ -96,6 +96,10 @@ export type MessagesPermissionScope = {
   interface: DwnInterfaceName.Messages;
   method: DwnMethodName.Read;
   protocol?: string;
+  /** May only be present when `protocol` is defined and `protocolPath` is undefined */
+  contextId?: string;
+  /** May only be present when `protocol` is defined and `contextId` is undefined */
+  protocolPath?: string;
 };
 
 /**
@@ -123,4 +127,4 @@ export type PermissionConditions = {
    * If `undefined`, it is optional to make the message public.
    */
   publication?: PermissionConditionPublication;
-};
+};

package/src/types/records-types.ts

@@ -105,6 +105,7 @@ export type RecordsCountDescriptor = {
   method: DwnMethodName.Count;
   messageTimestamp: string;
   filter: RecordsFilter;
+  permissionGrantId?: string;
 };
 
 export type RecordsCountMessage = GenericMessage & {
@@ -120,6 +121,7 @@ export type RecordsQueryDescriptor = {
   method: DwnMethodName.Query;
   messageTimestamp: string;
   filter: RecordsFilter;
+  permissionGrantId?: string;
   dateSort?: DateSort;
   pagination?: Pagination;
 };
@@ -129,6 +131,7 @@ export type RecordsSubscribeDescriptor = {
   method: DwnMethodName.Subscribe;
   messageTimestamp: string;
   filter: RecordsFilter;
+  permissionGrantId?: string;
   dateSort?: DateSort;
   pagination?: Pagination;
   /**
@@ -267,9 +270,10 @@ export type RecordsDeleteDescriptor = {
   method: DwnMethodName.Delete;
   messageTimestamp: string;
   recordId: string;
+  permissionGrantId?: string;
 
   /**
    * Denotes if all the descendent records should be purged.
    */
   prune: boolean
-};
+};

package/src/types/subscriptions.ts

@@ -110,15 +110,31 @@ export type SubscriptionEose = {
   cursor : ProgressToken;
 };
 
+/**
+ * Subscription-level error emitted after a subscription is already open.
+ *
+ * This is used for conditions that invalidate future delivery, such as a
+ * delegated subscription grant being revoked after the subscription was
+ * authorized. The cursor identifies the event that caused delivery to stop.
+ */
+export type SubscriptionError = {
+  type : 'error';
+  cursor : ProgressToken;
+  error : {
+    code : string;
+    detail : string;
+  };
+};
+
 /**
  * Discriminated union of subscription event types delivered to
  * {@link SubscriptionListener} callbacks.
  */
-export type SubscriptionMessage = SubscriptionEvent | SubscriptionEose;
+export type SubscriptionMessage = SubscriptionEvent | SubscriptionEose | SubscriptionError;
 
 /**
- * Callback for {@link EventLog.subscribe}. Receives either a regular event
- * (with cursor) or an EOSE marker indicating catch-up replay is complete.
+ * Callback for {@link EventLog.subscribe}. Receives events, catch-up EOSE
+ * markers, or subscription-level errors that stop delivery.
  */
 export type SubscriptionListener = (message: SubscriptionMessage) => void;
 

package/src/utils/permission-scope.ts

@@ -0,0 +1,55 @@
+/**
+ * Minimal protocol-bound scope shape used by permission grant authorization.
+ *
+ * Permission grants and candidate records/filters are projected down to these
+ * fields before matching so grant selection and server enforcement use the
+ * same rules.
+ */
+export type ProtocolScope = {
+  protocol?: string;
+  protocolPath?: string;
+  contextId?: string;
+};
+
+/**
+ * Shared matching rules for protocol-scoped permission grants.
+ *
+ * Matching fails closed for invalid combinations: `protocolPath` and
+ * `contextId` are mutually exclusive, and either field requires `protocol`.
+ * `protocol` and `protocolPath` match by exact equality. `contextId` scopes
+ * match a context subtree: the target context must equal the scoped context or
+ * begin with the scoped context followed by `/`.
+ */
+export class PermissionScopeMatcher {
+  /**
+   * Determines whether a candidate target is within a grant scope.
+   */
+  public static matches(scope: ProtocolScope, target: ProtocolScope): boolean {
+    if (scope.protocolPath !== undefined && scope.contextId !== undefined) {
+      return false;
+    }
+
+    if ((scope.protocolPath !== undefined || scope.contextId !== undefined) && scope.protocol === undefined) {
+      return false;
+    }
+
+    if (scope.protocol !== undefined && scope.protocol !== target.protocol) {
+      return false;
+    }
+
+    if (scope.protocolPath !== undefined) {
+      return scope.protocolPath === target.protocolPath;
+    }
+
+    if (scope.contextId !== undefined) {
+      return PermissionScopeMatcher.matchesContextId(scope.contextId, target.contextId);
+    }
+
+    return true;
+  }
+
+  private static matchesContextId(scopeContextId: string, candidateContextId: unknown): boolean {
+    return typeof candidateContextId === 'string' &&
+      (candidateContextId === scopeContextId || candidateContextId.startsWith(scopeContextId + '/'));
+  }
+}