@enbox/dwn-sdk-js 0.3.3 → 0.3.5

package/src/smt/sparse-merkle-tree.ts

@@ -19,7 +19,7 @@ import type { Hash, SMTDiffResult, SMTInternalNode, SMTLeafNode, SMTNodeStore, S
 import { getBit, hashChildren, hashEquals, hashKey, hashLeaf, initDefaultHashes, SMT_DEPTH } from './smt-utils.js';
 
 export class SparseMerkleTree {
-  private store: SMTNodeStore;
+  private readonly store: SMTNodeStore;
   private defaultHashes!: Hash[];
 
   constructor(store: SMTNodeStore) {
@@ -142,13 +142,13 @@ export class SparseMerkleTree {
         // subtree hash would be if this leaf were pushed down to the prefix depth.
         // For simplicity, if we've hit a leaf, the subtree at this prefix
         // either contains this leaf or is empty.
-        if (node !== undefined && node.type === 'leaf') {
+        if (node?.type === 'leaf') {
           return this.computeSubtreeHashForLeaf(node, i, prefix);
         }
         return this.defaultHashes[prefix.length];
       }
 
-      const internalNode = node as SMTInternalNode;
+      const internalNode = node;
       if (prefix[i]) {
         currentHash = internalNode.rightHash;
       } else {
@@ -186,7 +186,7 @@ export class SparseMerkleTree {
         return [];
       }
 
-      const internalNode = node as SMTInternalNode;
+      const internalNode = node;
       if (prefix[i]) {
         currentHash = internalNode.rightHash;
       } else {
@@ -266,7 +266,7 @@ export class SparseMerkleTree {
     }
 
     // Internal node — recurse into the appropriate child
-    const internalNode = node as SMTInternalNode;
+    const internalNode = node;
     const goRight = getBit(keyHash, depth);
 
     let newLeftHash: Hash;
@@ -405,7 +405,7 @@ export class SparseMerkleTree {
     }
 
     // Internal node — recurse into the appropriate child
-    const internalNode = node as SMTInternalNode;
+    const internalNode = node;
     const goRight = getBit(keyHash, depth);
 
     let newLeftHash: Hash;
@@ -433,7 +433,7 @@ export class SparseMerkleTree {
     if (leftIsDefault || rightIsDefault) {
       const survivingHash = leftIsDefault ? newRightHash : newLeftHash;
       const survivingNode = await this.store.getNode(survivingHash);
-      if (survivingNode !== undefined && survivingNode.type === 'leaf') {
+      if (survivingNode?.type === 'leaf') {
         // Collapse: remove the internal node, return the leaf hash directly
         await this.store.deleteNode(currentHash);
         return survivingHash;
@@ -477,7 +477,7 @@ export class SparseMerkleTree {
       return hashEquals(node.keyHash, keyHash);
     }
 
-    const internalNode = node as SMTInternalNode;
+    const internalNode = node;
     const goRight = getBit(keyHash, depth);
 
     if (goRight) {
@@ -508,7 +508,7 @@ export class SparseMerkleTree {
       return { siblings: [], leafNode: node, depth };
     }
 
-    const internalNode = node as SMTInternalNode;
+    const internalNode = node;
     const goRight = getBit(keyHash, depth);
 
     let childHash: Hash;
@@ -578,7 +578,7 @@ export class SparseMerkleTree {
       return [node.valueCid];
     }
 
-    const internalNode = node as SMTInternalNode;
+    const internalNode = node;
     const leftLeaves = await this.collectLeaves(internalNode.leftHash, depth + 1);
     const rightLeaves = await this.collectLeaves(internalNode.rightHash, depth + 1);
 

package/src/state-index/state-index-level.ts

@@ -28,7 +28,7 @@ export type StateIndexLevelConfig = {
 };
 
 export class StateIndexLevel implements StateIndex {
-  private config: StateIndexLevelConfig;
+  private readonly config: StateIndexLevelConfig;
   private db!: LevelWrapper<string>;
 
   /**
@@ -36,13 +36,13 @@ export class StateIndexLevel implements StateIndex {
    * Stores promises to avoid race conditions when multiple concurrent operations
    * trigger lazy initialization of the same tenant's SMT.
    */
-  private globalTrees: Map<string, Promise<SparseMerkleTree>> = new Map();
+  private readonly globalTrees: Map<string, Promise<SparseMerkleTree>> = new Map();
 
   /**
    * Cache of per-tenant, per-protocol SMTs. Key format: `{tenant}\x00{protocol}`
    * Stores promises to avoid race conditions (same reason as globalTrees).
    */
-  private protocolTrees: Map<string, Promise<SparseMerkleTree>> = new Map();
+  private readonly protocolTrees: Map<string, Promise<SparseMerkleTree>> = new Map();
 
   constructor(config?: StateIndexLevelConfig) {
     this.config = {

package/src/store/index-level-compound.ts

@@ -203,28 +203,28 @@ export async function queryWithCompoundIndex(
   // determine the iterator bounds from the prefix
   const iteratorOptions: LevelWrapperIteratorOptions<string> = {};
 
-  if (cursor !== undefined) {
-    // build the full compound key for the cursor position
-    const cursorSortEncoded = encodeValue(cursor.value);
-    const cursorKey = prefix + cursorSortEncoded + delimiter + cursor.messageCid;
-
+  if (cursor === undefined) {
     if (sortDirection === SortDirection.Ascending) {
-      iteratorOptions.gt = cursorKey;
-      // upper bound: everything with this prefix (prefix + \xff is past all valid compound keys with this prefix)
+      iteratorOptions.gt = prefix;
       iteratorOptions.lt = prefix + '\xff';
     } else {
-      iteratorOptions.lt = cursorKey;
+      // for descending without cursor, start from the end of the prefix range
       iteratorOptions.gt = prefix;
+      iteratorOptions.lt = prefix + '\xff';
       iteratorOptions.reverse = true;
     }
   } else {
+    // build the full compound key for the cursor position
+    const cursorSortEncoded = encodeValue(cursor.value);
+    const cursorKey = prefix + cursorSortEncoded + delimiter + cursor.messageCid;
+
     if (sortDirection === SortDirection.Ascending) {
-      iteratorOptions.gt = prefix;
+      iteratorOptions.gt = cursorKey;
+      // upper bound: everything with this prefix (prefix + \xff is past all valid compound keys with this prefix)
       iteratorOptions.lt = prefix + '\xff';
     } else {
-      // for descending without cursor, start from the end of the prefix range
+      iteratorOptions.lt = cursorKey;
       iteratorOptions.gt = prefix;
-      iteratorOptions.lt = prefix + '\xff';
       iteratorOptions.reverse = true;
     }
   }

package/src/store/index-level.ts

@@ -53,7 +53,7 @@ export interface IndexLevelOptions {
 export class IndexLevel {
   db: LevelWrapper<string>;
   config: IndexLevelConfig;
-  private _compoundIndexes: CompoundIndexDefinition[];
+  private readonly _compoundIndexes: CompoundIndexDefinition[];
 
   constructor(config: IndexLevelConfig) {
     this.config = {
@@ -498,13 +498,13 @@ export class IndexLevel {
 
     const sortedValues = [...matches.values()].sort((a,b) => this.sortItems(a,b, sortProperty, sortDirection));
 
-    const start = cursorStartingKey !== undefined ? this.findCursorStartingIndex(sortedValues, sortDirection, sortProperty, cursorStartingKey) : 0;
+    const start = cursorStartingKey === undefined ? 0 : this.findCursorStartingIndex(sortedValues, sortDirection, sortProperty, cursorStartingKey);
     if (start < 0) {
       // if the provided cursor does not come before any of the results, we return no results
       return [];
     }
 
-    const end = limit !== undefined ? start + limit: undefined;
+    const end = limit === undefined ? undefined : start + limit;
     return sortedValues.slice(start, end);
   }
 
@@ -735,7 +735,7 @@ export class IndexLevel {
   /**
    * Joins the given values using the `\x00` (\u0000) character.
    */
-  private static delimiter = `\x00`;
+  private static readonly delimiter = `\x00`;
   private static keySegmentJoin(...values: string[]): string {
     return values.join(IndexLevel.delimiter);
   }

package/src/store/level-wrapper.ts

@@ -183,7 +183,7 @@ export class LevelWrapper<V> {
   }
 
   async isEmpty(options?: LevelWrapperOptions): Promise<boolean> {
-    for await (const _key of this.keys(options)) {
+    for await (const _key of this.keys(options)) { // NOSONAR — intentional single-iteration check
       return false;
     }
     return true;

package/src/store/storage-controller.ts

@@ -30,10 +30,10 @@ export type ResumableRecordsSquashData = {
  */
 export class StorageController {
 
-  private messageStore: MessageStore;
-  private dataStore: DataStore;
-  private stateIndex: StateIndex;
-  private eventLog?: EventLog;
+  private readonly messageStore: MessageStore;
+  private readonly dataStore: DataStore;
+  private readonly stateIndex: StateIndex;
+  private readonly eventLog?: EventLog;
 
   public constructor({ messageStore, dataStore, stateIndex, eventLog }: {
     messageStore : MessageStore,
@@ -79,8 +79,13 @@ export class StorageController {
     }
 
     if (message.descriptor.prune) {
-      // purge/hard-delete all descendent records
-      await StorageController.purgeRecordDescendants(tenant, message.descriptor.recordId, this.messageStore, this.dataStore, this.stateIndex);
+      // purge/hard-delete all descendant records. Cascade is intentionally protocol-agnostic:
+      // `parentContextId` is a structural link, and a prune removes the whole subtree regardless
+      // of which protocol a descendant lives in. Cross-protocol composing children (linked via
+      // `$ref`/`uses`) participate in the cascade. See issue #298 for the design discussion.
+      await StorageController.purgeRecordDescendants(
+        tenant, message.descriptor.recordId, this.messageStore, this.dataStore, this.stateIndex
+      );
     }
 
     // delete all existing messages that are not newest, except for the initial write
@@ -131,10 +136,10 @@ export class StorageController {
       }
 
       const existing = recordIdToMessages.get(recordId);
-      if (existing !== undefined) {
-        existing.push(msg);
-      } else {
+      if (existing === undefined) {
         recordIdToMessages.set(recordId, [msg]);
+      } else {
+        existing.push(msg);
       }
     }
 
@@ -191,7 +196,21 @@ export class StorageController {
   }
 
   /**
-   * Purges (permanent hard-delete) all descendant's data of the given `recordId`.
+   * Purges (permanent hard-delete) all descendants of the given `recordId`, recursively.
+   *
+   * The cascade is intentionally protocol-agnostic: `parentContextId` is a structural link,
+   * so pruning a parent removes every record hanging off it regardless of which protocol a
+   * descendant lives in. Cross-protocol composing children (records in a different protocol
+   * that reference the parent via `$ref` / `uses`) are included in the cascade.
+   *
+   * Rationale (closes #298 as working-as-intended):
+   * - A DWN is tenant-owned storage. The tenant's prune authority extends across the whole
+   *   subtree they rooted, regardless of which protocol a descendant declares itself under.
+   * - Preserving cross-protocol orphans creates a half-alive state (readable but not
+   *   updatable, since `validateReferentialIntegrity` requires the pruned parent) that is
+   *   worse for callers than simply cascading.
+   * - Same-protocol cascade is already protocol-agnostic at every hop via `parentId`,
+   *   so treating cross-protocol boundaries differently was inconsistent.
    */
   public static async purgeRecordDescendants(
     tenant: string,
@@ -200,16 +219,15 @@ export class StorageController {
     dataStore: DataStore,
     stateIndex: StateIndex
   ): Promise<void> {
-    const filter = {
+    const filter: Filter = {
       interface : DwnInterfaceName.Records,
-      parentId  : recordId
+      parentId  : recordId,
     };
     const { messages: childMessages } = await messageStore.query(tenant, [filter]);
 
     // group the child messages by `recordId`
     const recordIdToMessagesMap = new Map<string, GenericMessage[]>();
     for (const message of childMessages) {
-      // get the recordId
       let recordId;
       if (Records.isRecordsWrite(message)) {
         recordId = message.recordId;
@@ -225,13 +243,10 @@ export class StorageController {
       }
     }
 
-    // purge all child's descendants first
     for (const childRecordId of recordIdToMessagesMap.keys()) {
-      // purge the child's descendent messages first
       await StorageController.purgeRecordDescendants(tenant, childRecordId, messageStore, dataStore, stateIndex);
     }
 
-    // then purge the child messages themselves
     for (const childRecordId of recordIdToMessagesMap.keys()) {
       await StorageController.purgeRecordMessages(tenant, recordIdToMessagesMap.get(childRecordId)!, messageStore, dataStore, stateIndex);
     }

package/src/types/permission-types.ts

@@ -89,13 +89,12 @@ export type ProtocolPermissionScope = {
 /**
  * Permission scope for the Messages interface.
  *
- * A `Read` scope is a unified scope that authorizes `MessagesRead`, `MessagesSubscribe`, and `MessagesSync` operations.
- * The `Subscribe` and `Sync` method values are retained for backward compatibility with existing grants but are
- * functionally equivalent to `Read` — new grants SHOULD use `Read` exclusively.
+ * `Read` is the only valid method and acts as a unified scope that authorizes
+ * `MessagesRead`, `MessagesSubscribe`, and `MessagesSync` operations.
  */
 export type MessagesPermissionScope = {
   interface: DwnInterfaceName.Messages;
-  method: DwnMethodName.Read | DwnMethodName.Subscribe | DwnMethodName.Sync;
+  method: DwnMethodName.Read;
   protocol?: string;
 };
 

package/src/utils/memory-cache.ts

@@ -5,12 +5,12 @@ import { LRUCache } from 'lru-cache';
  * A cache using local memory.
  */
 export class MemoryCache implements Cache {
-  private cache: LRUCache<string, any>;
+  private readonly cache: LRUCache<string, any>;
 
   /**
    * @param timeToLiveInSeconds time-to-live for every key-value pair set in the cache
    */
-  public constructor (private timeToLiveInSeconds: number) {
+  public constructor (private readonly timeToLiveInSeconds: number) {
     this.cache = new LRUCache({
       max : 100_000,
       ttl : timeToLiveInSeconds * 1000

package/src/utils/messages.ts

@@ -21,7 +21,7 @@ export class Messages {
     // normalize each filter, and only add non-empty filters to the returned array
     for (const filter of filters) {
       // normalize the protocol URL if it exists
-      const protocol = filter.protocol !== undefined ? normalizeProtocolUrl(filter.protocol) : undefined;
+      const protocol = filter.protocol === undefined ? undefined : normalizeProtocolUrl(filter.protocol);
 
       const messagesFilter = {
         ...filter,
@@ -130,6 +130,6 @@ export class Messages {
       };
     }
 
-    return filterCopy as Filter;
+    return filterCopy;
   }
 }

package/src/utils/object.ts

@@ -6,11 +6,7 @@ export function isEmptyObject(obj: unknown): boolean {
     return false;
   }
 
-  for (const _ in obj) {
-    return false;
-  }
-
-  return true;
+  return Object.keys(obj as object).length === 0;
 }
 
 /**

package/src/utils/private-key-signer.ts

@@ -30,8 +30,8 @@ export type PrivateKeySignerOptions = {
 export class PrivateKeySigner implements MessageSigner {
   public keyId;
   public algorithm;
-  private privateJwk: PrivateKeyJwk;
-  private signatureAlgorithm;
+  private readonly privateJwk: PrivateKeyJwk;
+  private readonly signatureAlgorithm;
 
   public constructor(options: PrivateKeySignerOptions) {
     if (options.keyId === undefined && options.privateJwk.kid === undefined) {

package/src/utils/records.ts

@@ -375,7 +375,7 @@ export class Records {
       delete filterCopy.recipient;
     }
 
-    return filterCopy as Filter;
+    return filterCopy;
   }
 
   /**