@enbox/dwn-sdk-js 0.4.12 → 0.4.14

package/src/store/index-level.ts

@@ -23,6 +23,9 @@ export type IndexLevelConfig = {
 
 export type IndexedItem = { messageCid: string, indexes: KeyValues };
 
+/** A value that can be encoded into a lexicographically sortable index key. */
+type IndexableValue = string | number | boolean;
+
 /**
  * Defines a compound index that covers multiple filter properties and a sort property.
  *
@@ -218,7 +221,7 @@ export class IndexLevel {
     tenant: string,
     item: IndexedItem,
     indexName: string,
-    indexValue: string | number | boolean
+    indexValue: IndexableValue
   ): Promise<LevelWrapperBatchOperation<string>> {
     const { messageCid } = item;
 
@@ -786,10 +789,9 @@ export class IndexLevel {
    * NOTE: we currently only use this for strings, numbers and booleans.
    */
   static encodeValue(value: string | number | boolean): string {
-    switch (typeof value) {
-    case 'number':
+    if (typeof value === 'number') {
       return this.encodeNumberValue(value);
-    default:
+    } else {
       return JSON.stringify(value);
     }
   }

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

@@ -325,8 +325,8 @@ export class MessageStoreLevel implements MessageStore, ReplicationFeedReader {
     }
 
     const messages: GenericMessage[] = [];
-    for (let i = 0; i < results.length; i++) {
-      const { messageCid } = results[i];
+    for (const result of results) {
+      const { messageCid } = result;
       const message = await this.get(tenant, messageCid, options);
       if (message) { messages.push(message); }
     }

package/src/store/storage-controller.ts

@@ -132,22 +132,7 @@ export class StorageController {
 
     // Group messages by recordId — RecordsWrite messages use `message.recordId`,
     // RecordsDelete messages use `message.descriptor.recordId`.
-    const recordIdToMessages = new Map<string, GenericMessage[]>();
-    for (const msg of siblingMessages) {
-      let recordId: string;
-      if (Records.isRecordsWrite(msg)) {
-        recordId = msg.recordId;
-      } else {
-        recordId = (msg as RecordsDeleteMessage).descriptor.recordId;
-      }
-
-      const existing = recordIdToMessages.get(recordId);
-      if (existing === undefined) {
-        recordIdToMessages.set(recordId, [msg]);
-      } else {
-        existing.push(msg);
-      }
-    }
+    const recordIdToMessages = StorageController.groupSquashSiblingsByRecordId(siblingMessages);
 
     // Delete all records whose newest message timestamp is strictly older than the squash timestamp.
     // Skip the squash record itself.
@@ -170,6 +155,32 @@ export class StorageController {
     }
   }
 
+  /**
+   * Groups the given messages by `recordId` — RecordsWrite messages use `message.recordId`,
+   * RecordsDelete messages use `message.descriptor.recordId`. Used by `performRecordsSquash()`
+   * to identify sibling records at the squash record's protocol path and parent context.
+   */
+  private static groupSquashSiblingsByRecordId(messages: GenericMessage[]): Map<string, GenericMessage[]> {
+    const recordIdToMessages = new Map<string, GenericMessage[]>();
+    for (const msg of messages) {
+      let recordId: string;
+      if (Records.isRecordsWrite(msg)) {
+        recordId = msg.recordId;
+      } else {
+        recordId = (msg as RecordsDeleteMessage).descriptor.recordId;
+      }
+
+      const existing = recordIdToMessages.get(recordId);
+      if (existing === undefined) {
+        recordIdToMessages.set(recordId, [msg]);
+      } else {
+        existing.push(msg);
+      }
+    }
+
+    return recordIdToMessages;
+  }
+
   /**
    * Deletes the data referenced by the given message if needed.
    * @param message The message to check if the data it references should be deleted.

package/src/types/jose-types.ts

@@ -1,6 +1,7 @@
-import type { Jwk, PrivateKeyJwk, PublicKeyJwk } from '@enbox/crypto';
+import type { PrivateKeyJwk, PublicKeyJwk } from '@enbox/crypto';
 
-export type { Jwk, PrivateKeyJwk, PublicKeyJwk };
+export type { Jwk } from '@enbox/crypto';
+export type { PrivateKeyJwk, PublicKeyJwk };
 
 /**
  * Contains a public-private key pair and the associated key ID.

package/src/types/message-types.ts

@@ -1,3 +1,4 @@
+import type { DwnErrorInfo } from '../core/dwn-error.js';
 import type { GeneralJws } from './jws-types.js';
 import type { ProgressToken } from './subscriptions.js';
 import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
@@ -127,8 +128,23 @@ export type Pagination = {
 };
 
 export type Status = {
+  /** Numeric status code representing the outcome of the operation, aligned with HTTP status codes. */
   code: number
+
+  /** Human-readable detail about the status or error. Prose only — load-bearing values belong in `info`. */
   detail: string
+
+  /**
+   * The `DwnErrorCode` of the `DwnError` that produced this status.
+   * Only present when the failure originated from a `DwnError`; synthesized statuses (e.g. tenant gate rejections) omit it.
+   */
+  errorCode?: string
+
+  /**
+   * Structured, machine-readable error data (e.g. the squash floor timestamp for a squash backstop rejection).
+   * Only present when the originating `DwnError` carries an info bag; values mirror `DwnErrorInfo`.
+   */
+  info?: DwnErrorInfo
 };
 
 export type GenericMessageReply = {

package/src/types/subscriptions.ts

@@ -141,8 +141,13 @@ export type SubscriptionMessage = SubscriptionEvent | SubscriptionEose | Subscri
 /**
  * Callback for {@link EventLog.subscribe}. Receives events, catch-up EOSE
  * markers, or subscription-level errors that stop delivery.
+ *
+ * A listener may return a promise to signal when the message has been fully
+ * processed; transports that support backpressure (e.g. the WebSocket client)
+ * gate their acknowledgements on it. Emitters that cannot exert backpressure
+ * simply ignore the returned value.
  */
-export type SubscriptionListener = (message: SubscriptionMessage) => void;
+export type SubscriptionListener = (message: SubscriptionMessage) => void | Promise<void>;
 
 /**
  * Options for {@link EventLog.subscribe}.

package/src/utils/filter.ts

@@ -84,18 +84,14 @@ export class FilterUtility {
         if (this.matchOneOf(filterValue, indexValue)) {
           return true;
         }
-      } else {
+      } else if (this.matchRange(filterValue, indexValue as RangeValue)) {
         // `filterValue` is a `RangeFilter`
         // range filters cannot range over booleans
-        if (this.matchRange(filterValue, indexValue as RangeValue)) {
-          return true;
-        }
-      }
-    } else {
-      // filterValue is an EqualFilter, meaning it is a non-object primitive type
-      if (indexValue === filterValue) {
         return true;
       }
+    } else if (indexValue === filterValue) {
+      // filterValue is an EqualFilter, meaning it is a non-object primitive type
+      return true;
     }
 
     return false;

package/src/utils/messages.ts

@@ -59,39 +59,13 @@ export class Messages {
 
     for (const filter of filters) {
       // Ask each core protocol whether it needs an additional shadow filter for this query.
-      // For example, the Permissions protocol injects a filter for grants/requests/revocations
-      // tagged with the target protocol so they appear alongside that protocol's own records.
-      if (coreProtocols !== undefined) {
-        for (const coreProtocol of coreProtocols.all()) {
-          const additionalFilter = coreProtocol.constructAdditionalMessageFilter?.(filter);
-          if (additionalFilter !== undefined) {
-            messagesQueryFilters.push(additionalFilter);
-          }
-        }
-      }
+      messagesQueryFilters.push(...this.constructCoreProtocolFilters(filter, coreProtocols));
 
       messagesQueryFilters.push(this.convertFilter(filter));
 
-      // When protocolPathPrefix is used with a protocol, inject a shadow filter
-      // for ProtocolsConfigure events. Without this, protocol metadata updates
-      // would be excluded (ProtocolsConfigure indexes have no protocolPath).
-      // This mirrors the existing core-protocol additional-filter pattern above.
-      // The messageTimestamp constraint is carried over so time-bounded queries
-      // (including cursor-based subscriptions) also apply to the shadow filter.
-      if ((filter.protocolPathPrefix !== undefined || filter.contextIdPrefix !== undefined) && filter.protocol !== undefined) {
-        const metadataFilter: Filter = {
-          interface : 'Protocols',
-          method    : 'Configure',
-          protocol  : filter.protocol,
-        };
-
-        if (filter.messageTimestamp !== undefined) {
-          const timestampFilter = FilterUtility.convertRangeCriterion(filter.messageTimestamp);
-          if (timestampFilter) {
-            metadataFilter.messageTimestamp = timestampFilter;
-          }
-        }
-
+      // When protocolPathPrefix is used with a protocol, inject a shadow filter for ProtocolsConfigure events.
+      const metadataFilter = this.constructProtocolConfigureShadowFilter(filter);
+      if (metadataFilter !== undefined) {
         messagesQueryFilters.push(metadataFilter);
       }
     }
@@ -99,6 +73,55 @@ export class Messages {
     return messagesQueryFilters;
   }
 
+  /**
+   * Asks each core protocol whether it needs an additional shadow filter for the given query filter.
+   * For example, the Permissions protocol injects a filter for grants/requests/revocations
+   * tagged with the target protocol so they appear alongside that protocol's own records.
+   */
+  private static constructCoreProtocolFilters(filter: MessagesFilter, coreProtocols?: CoreProtocolRegistry): Filter[] {
+    if (coreProtocols === undefined) {
+      return [];
+    }
+
+    const additionalFilters: Filter[] = [];
+    for (const coreProtocol of coreProtocols.all()) {
+      const additionalFilter = coreProtocol.constructAdditionalMessageFilter?.(filter);
+      if (additionalFilter !== undefined) {
+        additionalFilters.push(additionalFilter);
+      }
+    }
+
+    return additionalFilters;
+  }
+
+  /**
+   * When protocolPathPrefix or contextIdPrefix is used with a protocol, constructs a shadow filter
+   * for ProtocolsConfigure events. Without this, protocol metadata updates would be excluded
+   * (ProtocolsConfigure indexes have no protocolPath). This mirrors the core-protocol additional-filter
+   * pattern above. The messageTimestamp constraint is carried over so time-bounded queries
+   * (including cursor-based subscriptions) also apply to the shadow filter.
+   */
+  private static constructProtocolConfigureShadowFilter(filter: MessagesFilter): Filter | undefined {
+    if ((filter.protocolPathPrefix === undefined && filter.contextIdPrefix === undefined) || filter.protocol === undefined) {
+      return undefined;
+    }
+
+    const metadataFilter: Filter = {
+      interface : 'Protocols',
+      method    : 'Configure',
+      protocol  : filter.protocol,
+    };
+
+    if (filter.messageTimestamp !== undefined) {
+      const timestampFilter = FilterUtility.convertRangeCriterion(filter.messageTimestamp);
+      if (timestampFilter) {
+        metadataFilter.messageTimestamp = timestampFilter;
+      }
+    }
+
+    return metadataFilter;
+  }
+
   /**
    * 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/protocols.ts

@@ -46,7 +46,7 @@ export function isCrossProtocolRef(ref: string): boolean {
  * e.g. `'thread/comment'` → `'comment'`, `'note'` → `'note'`.
  */
 export function getTypeName(protocolPath: string): string {
-  return protocolPath.split('/').slice(-1)[0];
+  return protocolPath.split('/').at(-1)!;
 }
 
 /**
@@ -121,7 +121,7 @@ export class Protocols {
     keyDeriver: EncryptionKeyDeriver,
   ): Promise<ProtocolDefinition> {
     // clone before modify
-    const clone = JSON.parse(JSON.stringify(protocolDefinition)) as ProtocolDefinition;
+    const clone = structuredClone(protocolDefinition);
 
     const basePath = [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol];
     clone.$keyAgreement = {

package/src/utils/records.ts

@@ -445,6 +445,20 @@ export class Records {
     message: RecordsCountMessage | RecordsReadMessage | RecordsQueryMessage | RecordsWriteMessage | RecordsDeleteMessage | RecordsSubscribeMessage,
     authorSignaturePayload: GenericSignaturePayload | undefined,
     ownerSignaturePayload?: GenericSignaturePayload | undefined
+  ): Promise<void> {
+    await Records.validateAuthorDelegatedGrantReferentialIntegrity(message, authorSignaturePayload);
+
+    // repeat the same checks for the owner signature below
+    await Records.validateOwnerDelegatedGrantReferentialIntegrity(message, ownerSignaturePayload);
+  }
+
+  /**
+   * Validates the referential integrity of the author-delegated grant, if any.
+   * Extracted from `validateDelegatedGrantReferentialIntegrity()` to keep its cognitive complexity low.
+   */
+  private static async validateAuthorDelegatedGrantReferentialIntegrity(
+    message: RecordsCountMessage | RecordsReadMessage | RecordsQueryMessage | RecordsWriteMessage | RecordsDeleteMessage | RecordsSubscribeMessage,
+    authorSignaturePayload: GenericSignaturePayload | undefined,
   ): Promise<void> {
     // `deletedGrantId` in the payload of the message signature and `authorDelegatedGrant` in `authorization` must both exist or be both undefined
     const authorDelegatedGrantIdDefined = authorSignaturePayload?.delegatedGrantId !== undefined;
@@ -458,38 +472,47 @@ export class Records {
       );
     }
 
-    if (authorDelegatedGrantDefined) {
-      const delegatedGrant = message.authorization!.authorDelegatedGrant!;
+    if (!authorDelegatedGrantDefined) {
+      return;
+    }
 
-      const permissionGrant = PermissionGrant.parse(delegatedGrant);
-      if (permissionGrant.delegated !== true) {
-        throw new DwnError(
-          DwnErrorCode.RecordsAuthorDelegatedGrantNotADelegatedGrant,
-          `The owner delegated grant given is not a delegated grant.`
-        );
-      }
+    const delegatedGrant = message.authorization!.authorDelegatedGrant!;
 
-      const grantedTo = delegatedGrant.descriptor.recipient;
-      const signer = Message.getSigner(message);
-      if (grantedTo !== signer) {
-        throw new DwnError(
-          DwnErrorCode.RecordsAuthorDelegatedGrantGrantedToAndOwnerSignatureMismatch,
-          `grantedTo ${grantedTo} in author delegated grant must be the same as the signer ${signer} of the message signature.`
-        );
-      }
+    const permissionGrant = PermissionGrant.parse(delegatedGrant);
+    if (permissionGrant.delegated !== true) {
+      throw new DwnError(
+        DwnErrorCode.RecordsAuthorDelegatedGrantNotADelegatedGrant,
+        `The owner delegated grant given is not a delegated grant.`
+      );
+    }
 
-      const delegateGrantCid = await Message.getCid(delegatedGrant);
-      if (delegateGrantCid !== authorSignaturePayload!.delegatedGrantId) {
-        throw new DwnError(
-          DwnErrorCode.RecordsAuthorDelegatedGrantCidMismatch,
-          `CID of the author delegated grant ${delegateGrantCid} must be the same as \
-          the delegatedGrantId ${authorSignaturePayload!.delegatedGrantId} in the message signature.`
-        );
-      }
+    const grantedTo = delegatedGrant.descriptor.recipient;
+    const signer = Message.getSigner(message);
+    if (grantedTo !== signer) {
+      throw new DwnError(
+        DwnErrorCode.RecordsAuthorDelegatedGrantGrantedToAndOwnerSignatureMismatch,
+        `grantedTo ${grantedTo} in author delegated grant must be the same as the signer ${signer} of the message signature.`
+      );
     }
 
-    // repeat the same checks for the owner signature below
+    const delegateGrantCid = await Message.getCid(delegatedGrant);
+    if (delegateGrantCid !== authorSignaturePayload!.delegatedGrantId) {
+      throw new DwnError(
+        DwnErrorCode.RecordsAuthorDelegatedGrantCidMismatch,
+        `CID of the author delegated grant ${delegateGrantCid} must be the same as \
+        the delegatedGrantId ${authorSignaturePayload!.delegatedGrantId} in the message signature.`
+      );
+    }
+  }
 
+  /**
+   * Validates the referential integrity of the owner-delegated grant, if any.
+   * Extracted from `validateDelegatedGrantReferentialIntegrity()` to keep its cognitive complexity low.
+   */
+  private static async validateOwnerDelegatedGrantReferentialIntegrity(
+    message: RecordsCountMessage | RecordsReadMessage | RecordsQueryMessage | RecordsWriteMessage | RecordsDeleteMessage | RecordsSubscribeMessage,
+    ownerSignaturePayload: GenericSignaturePayload | undefined,
+  ): Promise<void> {
     // `deletedGrantId` in the payload of the owner signature and `ownerDelegatedGrant` in `authorization` must both exist or be both undefined
     const ownerDelegatedGrantIdDefined = ownerSignaturePayload?.delegatedGrantId !== undefined;
     const ownerDelegatedGrantDefined = message.authorization?.ownerDelegatedGrant !== undefined;
@@ -502,34 +525,36 @@ export class Records {
       );
     }
 
-    if (ownerDelegatedGrantDefined) {
-      const delegatedGrant = message.authorization!.ownerDelegatedGrant!;
-      const permissionGrant = PermissionGrant.parse(delegatedGrant);
+    if (!ownerDelegatedGrantDefined) {
+      return;
+    }
 
-      if (permissionGrant.delegated !== true) {
-        throw new DwnError(
-          DwnErrorCode.RecordsOwnerDelegatedGrantNotADelegatedGrant,
-          `The owner delegated grant given is not a delegated grant.`
-        );
-      }
+    const delegatedGrant = message.authorization!.ownerDelegatedGrant!;
+    const permissionGrant = PermissionGrant.parse(delegatedGrant);
 
-      const grantedTo = delegatedGrant.descriptor.recipient;
-      const signer = Jws.getSignerDid(message.authorization!.ownerSignature!.signatures[0]);
-      if (grantedTo !== signer) {
-        throw new DwnError(
-          DwnErrorCode.RecordsOwnerDelegatedGrantGrantedToAndOwnerSignatureMismatch,
-          `grantedTo ${grantedTo} in owner delegated grant must be the same as the signer ${signer} of the owner signature.`
-        );
-      }
+    if (permissionGrant.delegated !== true) {
+      throw new DwnError(
+        DwnErrorCode.RecordsOwnerDelegatedGrantNotADelegatedGrant,
+        `The owner delegated grant given is not a delegated grant.`
+      );
+    }
 
-      const delegateGrantCid = await Message.getCid(delegatedGrant);
-      if (delegateGrantCid !== ownerSignaturePayload!.delegatedGrantId) {
-        throw new DwnError(
-          DwnErrorCode.RecordsOwnerDelegatedGrantCidMismatch,
-          `CID of the owner delegated grant ${delegateGrantCid} must be the same as \
-          the delegatedGrantId ${ownerSignaturePayload!.delegatedGrantId} in the owner signature.`
-        );
-      }
+    const grantedTo = delegatedGrant.descriptor.recipient;
+    const signer = Jws.getSignerDid(message.authorization!.ownerSignature!.signatures[0]);
+    if (grantedTo !== signer) {
+      throw new DwnError(
+        DwnErrorCode.RecordsOwnerDelegatedGrantGrantedToAndOwnerSignatureMismatch,
+        `grantedTo ${grantedTo} in owner delegated grant must be the same as the signer ${signer} of the owner signature.`
+      );
+    }
+
+    const delegateGrantCid = await Message.getCid(delegatedGrant);
+    if (delegateGrantCid !== ownerSignaturePayload!.delegatedGrantId) {
+      throw new DwnError(
+        DwnErrorCode.RecordsOwnerDelegatedGrantCidMismatch,
+        `CID of the owner delegated grant ${delegateGrantCid} must be the same as \
+        the delegatedGrantId ${ownerSignaturePayload!.delegatedGrantId} in the owner signature.`
+      );
     }
   }
 

package/src/utils/secp256r1.ts

@@ -85,7 +85,7 @@ export class Secp256r1 {
     const hashedContent = await sha256.encode(content);
     const privateKeyBytes = Secp256r1.privateJwkToBytes(privateJwk);
 
-    return Promise.resolve(p256.sign(hashedContent, privateKeyBytes, { prehash: false }));
+    return p256.sign(hashedContent, privateKeyBytes, { prehash: false });
   }
 
   /**

package/src/utils/url.ts

@@ -40,7 +40,7 @@ export function normalizeSchemaUrl(url: string): string {
 
 function normalizeUrl(url: string): string {
   let fullUrl: string;
-  if (/^[^:]+:(\/{2})?[^\/].*/.test(url)) {
+  if (/^[^:]+:(\/{2})?[^/].*/.test(url)) {
     fullUrl = url;
   } else {
     fullUrl = `http://${url}`;