@enbox/dwn-sdk-js 0.4.9 → 0.4.11

package/src/store/storage-controller.ts

@@ -1,8 +1,8 @@
 import type { DataStore } from '../types/data-store.js';
-import type { Filter } from '../types/query-types.js';
 import type { GenericMessage } from '../types/message-types.js';
-import type { MessageStore } from '../types/message-store.js';
 import type { ProgressToken } from '../types/subscriptions.js';
+import type { Filter, KeyValues } from '../types/query-types.js';
+import type { MessageStore, MessageStorePutResult } from '../types/message-store.js';
 import type { RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
 
 import { DwnConstant } from '../core/dwn-constant.js';
@@ -80,7 +80,12 @@ export class StorageController {
     // tombstones carry no visibility facts in their descriptors, so the retained write is the
     // durable source of truth for later prune/replay/replication index reconstruction.
     const indexes = recordsDelete.constructIndexes(initialWrite, newestPreDeleteWrite);
-    const { position } = await this.messageStore.put(tenant, message, indexes);
+
+    // store the tombstone and displace every other message for this record in one atomic commit,
+    // retaining the writes needed for replay and future tombstone visibility
+    const { position } = await StorageController.commitLatestStateTransition(
+      tenant, existingMessages, { message, indexes }, [newestPreDeleteWrite], this.messageStore, this.dataStore
+    );
 
     if (message.descriptor.prune) {
       // purge/hard-delete all descendant records. Cascade is intentionally protocol-agnostic:
@@ -92,11 +97,6 @@ export class StorageController {
       );
     }
 
-    // displace every other message for this record, retaining the writes needed for replay and future tombstone visibility
-    await StorageController.deleteDisplacedMessagesAndRetainWrites(
-      tenant, existingMessages, message, this.messageStore, this.dataStore, [newestPreDeleteWrite]
-    );
-
     return { position };
   }
 
@@ -285,56 +285,70 @@ export class StorageController {
   }
 
   /**
-   * Deletes all messages in `existingMessages` that the `retainedMessage` displaces, while keeping
-   * the initial write and the caller-supplied writes as non-latest state for future replay and
-   * tombstone visibility reconstruction. Displacement is deliberately NOT a timestamp comparison:
-   * a RecordsDelete displaces even a newer RecordsWrite (delete-wins convergence), and on
-   * resumable-task replay the retained message itself is back in `existingMessages` and must
-   * survive — so membership is decided by CID.
+   * Stores the new latest message and displaces every other message in `existingMessages` as ONE
+   * atomic message-store commit: the initial write and the caller-supplied writes are retained as
+   * non-latest state for future replay and tombstone visibility reconstruction, and the remaining
+   * displaced messages are deleted. Readers can never observe an intermediate state where both the
+   * new message and a displaced message carry latest-state indexes.
+   *
+   * Displacement is deliberately NOT a timestamp comparison: a RecordsDelete displaces even a
+   * newer RecordsWrite (delete-wins convergence), and on resumable-task replay the new message
+   * itself is back in `existingMessages` and must survive — so membership is decided by CID.
+   *
+   * Displaced messages' unreferenced data is deleted from the data store only AFTER the commit:
+   * a crash in between leaves at most an orphaned data blob, never a live row whose data is gone.
    */
-  public static async deleteDisplacedMessagesAndRetainWrites(
+  public static async commitLatestStateTransition(
     tenant: string,
     existingMessages: GenericMessage[],
-    retainedMessage: GenericMessage,
+    newMessage: { message: GenericMessage, indexes: KeyValues },
+    additionalRetainedRecordsWrites: RecordsWriteMessage[],
     messageStore: MessageStore,
     dataStore: DataStore,
-    additionalRetainedRecordsWrites: RecordsWriteMessage[],
-  ): Promise<void> {
-    const retainedMessageCid = await Message.getCid(retainedMessage);
+  ): Promise<MessageStorePutResult> {
+    const newMessageCid = await Message.getCid(newMessage.message);
     const additionalRetainedRecordsWriteCids = new Set<string>();
     for (const retainedRecordsWrite of additionalRetainedRecordsWrites) {
       additionalRetainedRecordsWriteCids.add(await Message.getCid(retainedRecordsWrite));
     }
 
     // NOTE: under normal operation, there should only be at most two existing records per `recordId` (initial + a potential subsequent write/delete),
-    // but the DWN may crash before `delete()` is called below, so we use a loop as a tactic to clean up lingering data as needed
+    // but the plan-then-commit shape below heals any lingering rows a previous partial application left behind.
+    const retains: { messageCid: string, message: GenericMessage, indexes: KeyValues }[] = [];
+    const deletes: string[] = [];
+    const displacedMessages: GenericMessage[] = [];
     for (const message of existingMessages) {
       const messageCid = await Message.getCid(message);
-      const messageIsDisplaced = messageCid !== retainedMessageCid;
-      if (messageIsDisplaced) {
-        // the easiest implementation here is delete each old messages
-        // and re-create it with the right index (isLatestBaseState = 'false') if the message is a retained write,
-        // but there is room for better/more efficient implementation here
-
-        await StorageController.deleteFromDataStoreIfNeeded(dataStore, tenant, message, retainedMessage);
-
-        // Retained writes must stay in the message store and state index so future deletes and
-        // replicas can reconstruct tombstone visibility, but they must no longer be latest state.
-        const shouldKeepAsNonLatestWrite =
-          await RecordsWrite.isInitialWrite(message) ||
-          additionalRetainedRecordsWriteCids.has(messageCid);
-        if (shouldKeepAsNonLatestWrite) {
-          const retainedRecordsWriteMessage = StorageController.stripInlineData(message as RecordsWriteMessage);
-          const existingRecordsWrite = await RecordsWrite.parse(retainedRecordsWriteMessage);
-          const isLatestBaseState = false;
-          const indexes = await existingRecordsWrite.constructIndexes(isLatestBaseState);
-          await messageStore.updateMessageAndIndexes(tenant, messageCid, retainedRecordsWriteMessage, indexes);
-        } else {
-          // delete message from message store
-          await messageStore.delete(tenant, messageCid);
-        }
+      const messageIsDisplaced = messageCid !== newMessageCid;
+      if (!messageIsDisplaced) {
+        continue;
+      }
+
+      displacedMessages.push(message);
+
+      // Retained writes must stay in the message store and state index so future deletes and
+      // replicas can reconstruct tombstone visibility, but they must no longer be latest state.
+      const shouldKeepAsNonLatestWrite =
+        await RecordsWrite.isInitialWrite(message) ||
+        additionalRetainedRecordsWriteCids.has(messageCid);
+      if (shouldKeepAsNonLatestWrite) {
+        const retainedRecordsWriteMessage = StorageController.stripInlineData(message as RecordsWriteMessage);
+        const existingRecordsWrite = await RecordsWrite.parse(retainedRecordsWriteMessage);
+        const isLatestBaseState = false;
+        const indexes = await existingRecordsWrite.constructIndexes(isLatestBaseState);
+        retains.push({ messageCid, message: retainedRecordsWriteMessage, indexes });
+      } else {
+        deletes.push(messageCid);
       }
     }
+
+    const putResult = await messageStore.commitLatestState(tenant, { put: newMessage, retains, deletes });
+
+    for (const message of displacedMessages) {
+      await StorageController.deleteFromDataStoreIfNeeded(dataStore, tenant, message, newMessage.message);
+    }
+
+    return putResult;
   }
 
   private static stripInlineData(message: RecordsWriteMessage): RecordsWriteMessage {

package/src/types/message-store.ts

@@ -24,6 +24,28 @@ export type MessageStorePutResult = {
   position?: ProgressToken;
 };
 
+/**
+ * A latest-state transition applied by {@link MessageStore.commitLatestState}: the insert of a new
+ * message together with the displacement of the messages it supersedes.
+ */
+export type MessageStoreLatestStateTransition = {
+  /**
+   * The new message to insert, with its insert-time indexes.
+   */
+  put: { message: GenericMessage; indexes: KeyValues };
+
+  /**
+   * Displaced writes retained as non-latest state: same-CID in-place replacements
+   * (same row, same log sequence) applied with the insert.
+   */
+  retains?: { messageCid: string; message: GenericMessage; indexes: KeyValues }[];
+
+  /**
+   * Message CIDs of displaced messages that are not retained, deleted with the insert.
+   */
+  deletes?: string[];
+};
+
 export interface MessageStore {
   /**
    * opens a connection to the underlying store
@@ -46,6 +68,21 @@ export interface MessageStore {
     options?: MessageStoreOptions
   ): Promise<MessageStorePutResult>;
 
+  /**
+   * Atomically inserts a new message and displaces the messages it supersedes: retained writes are
+   * replaced in place with their demoted state, and the remaining displaced rows are deleted, all
+   * in one commit. Readers can never observe an intermediate state where both the new message and
+   * a displaced message carry latest-state indexes.
+   *
+   * When the new message already exists, returns `duplicate` and still applies the retains and
+   * deletes, so replaying a transition heals one that was only partially planned before a crash.
+   */
+  commitLatestState(
+    tenant: string,
+    transition: MessageStoreLatestStateTransition,
+    options?: MessageStoreOptions
+  ): Promise<MessageStorePutResult>;
+
   /**
    * Fetches a single message by `cid` from the underlying store.
    * Returns `undefined` no message was found.

package/src/utils/encryption.ts

@@ -107,13 +107,11 @@ export type KeyUnwrapPayload = {
 export type X25519KeyWrapInput = {
   cek: Uint8Array;
   keyInput: X25519KeyEncryptionInput;
-  ephemeralPrivateKey?: Jwk;
 };
 
 export type SealWrapInput = {
   privateKeyBytes: Uint8Array;
   keyInput: SealKeyWrapInput;
-  ephemeralPrivateKey?: Jwk;
 };
 
 export type SealUnwrapInput = {
@@ -180,17 +178,6 @@ export class Encryption {
     return Encryption.toStream(ciphertext);
   }
 
-  public static async decryptStream(
-    algorithm: ContentEncryptionAlgorithm,
-    keyBytes: Uint8Array,
-    initializationVector: Uint8Array,
-    ciphertextStream: ReadableStream<Uint8Array>,
-  ): Promise<ReadableStream<Uint8Array>> {
-    const ciphertext = await Encryption.readStream(ciphertextStream);
-    const plaintext = await Encryption.decrypt(algorithm, keyBytes, initializationVector, ciphertext);
-    return Encryption.toStream(plaintext);
-  }
-
   public static async wrapKey(input: X25519KeyWrapInput): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
     if (Encryption.isX25519KeyAgreementAlgorithm(input.keyInput.algorithm)) {
       return Encryption.wrapX25519Key(input);
@@ -206,7 +193,7 @@ export class Encryption {
 
     Encryption.validateContentEncryptionKey(input.privateKeyBytes);
 
-    const privateKey = input.ephemeralPrivateKey ?? await X25519.generateKey();
+    const privateKey = await X25519.generateKey();
     const publicKey = await X25519.getPublicKey({ key: privateKey }) as PublicKeyJwk;
     const sharedSecret = await X25519.sharedSecret({
       privateKeyA : privateKey,
@@ -231,7 +218,7 @@ export class Encryption {
   private static async wrapX25519Key(input: X25519KeyWrapInput): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
     Encryption.validateContentEncryptionKey(input.cek);
 
-    const privateKey = input.ephemeralPrivateKey ?? await X25519.generateKey();
+    const privateKey = await X25519.generateKey();
     const publicKey = await X25519.getPublicKey({ key: privateKey }) as PublicKeyJwk;
     const sharedSecret = await X25519.sharedSecret({
       privateKeyA : privateKey,

package/src/utils/hd-key.ts

@@ -1,7 +1,6 @@
-import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
+import type { PrivateKeyJwk } from '../types/jose-types.js';
 
 import { Encoder } from './encoder.js';
-import { X25519 } from '@enbox/crypto';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
 export enum KeyDerivationScheme {
@@ -20,36 +19,6 @@ export type DerivedPrivateJwk = {
  * Class containing hierarchical deterministic key related utility methods used by the DWN.
  */
 export class HdKey {
-  /**
-   * Derives a descendant private key.
-   * Uses X25519 keys for encryption key derivation.
-   */
-  public static async derivePrivateKey(ancestorKey: DerivedPrivateJwk, subDerivationPath: string[]): Promise<DerivedPrivateJwk> {
-    const ancestorPrivateKey = await X25519.privateKeyToBytes({ privateKey: ancestorKey.derivedPrivateKey });
-    const ancestorPrivateKeyDerivationPath = ancestorKey.derivationPath ?? [];
-    const derivedPrivateKeyBytes = await HdKey.derivePrivateKeyBytes(ancestorPrivateKey, subDerivationPath);
-    const derivedPrivateKeyJwk = await X25519.bytesToPrivateKey({ privateKeyBytes: derivedPrivateKeyBytes });
-    const derivedDescendantPrivateKey: DerivedPrivateJwk = {
-      rootKeyId         : ancestorKey.rootKeyId,
-      derivationScheme  : ancestorKey.derivationScheme,
-      derivationPath    : [...ancestorPrivateKeyDerivationPath, ...subDerivationPath],
-      derivedPrivateKey : derivedPrivateKeyJwk as PrivateKeyJwk
-    };
-
-    return derivedDescendantPrivateKey;
-  }
-
-  /**
-   * Derives a descendant public key from an ancestor private key.
-   * Uses X25519 keys for encryption key derivation.
-   */
-  public static async derivePublicKey(ancestorKey: DerivedPrivateJwk, subDerivationPath: string[]): Promise<PublicKeyJwk> {
-    const derivedDescendantPrivateKey = await HdKey.derivePrivateKey(ancestorKey, subDerivationPath);
-    const derivedDescendantPublicKey = await X25519.getPublicKey({ key: derivedDescendantPrivateKey.derivedPrivateKey });
-
-    return derivedDescendantPublicKey as PublicKeyJwk;
-  }
-
   /**
    * Derives a hardened hierarchical deterministic private key.
    */

package/src/utils/initial-write-attachment.ts

@@ -0,0 +1,64 @@
+import type { MessageStore } from '../types/message-store.js';
+import type { RecordsQueryReplyEntry } from '../types/records-types.js';
+
+import { DwnErrorCode } from '../core/dwn-error.js';
+import { Messages } from './messages.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+
+/**
+ * Attaches each returned update's retained initial write, resolved for the whole result page in
+ * one batched lookup by the stable identity `entryId === recordId` — unlike the mutable
+ * latest-state index, that identity holds at every point of the record's lifecycle.
+ *
+ * An update whose initial write is genuinely missing (store corruption) is omitted with a
+ * warning rather than failing the whole reply.
+ */
+export async function attachInitialWrites(input: {
+  messageStore: MessageStore;
+  tenant: string;
+  recordsWrites: RecordsQueryReplyEntry[];
+  operationName: 'RecordsQuery' | 'RecordsSubscribe';
+}): Promise<RecordsQueryReplyEntry[]> {
+  const updateRecordIds = new Set<string>();
+  const initialWriteState = new Map<RecordsQueryReplyEntry, boolean>();
+  for (const recordsWrite of input.recordsWrites) {
+    const isInitialWrite = await RecordsWrite.isInitialWrite(recordsWrite);
+    initialWriteState.set(recordsWrite, isInitialWrite);
+    if (!isInitialWrite) {
+      updateRecordIds.add(recordsWrite.recordId);
+    }
+  }
+
+  if (updateRecordIds.size === 0) {
+    return input.recordsWrites;
+  }
+
+  const initialWriteByRecordId = new Map<string, RecordsQueryReplyEntry>();
+  const { messages } = await input.messageStore.query(input.tenant, [{ entryId: [...updateRecordIds] }]);
+  for (const message of messages) {
+    const initialWrite = message as RecordsQueryReplyEntry;
+    initialWriteByRecordId.set(initialWrite.recordId, initialWrite);
+  }
+
+  const completeRecordsWrites: RecordsQueryReplyEntry[] = [];
+  for (const recordsWrite of input.recordsWrites) {
+    if (initialWriteState.get(recordsWrite) === true) {
+      completeRecordsWrites.push(recordsWrite);
+      continue;
+    }
+
+    const storedInitialWrite = initialWriteByRecordId.get(recordsWrite.recordId);
+    if (storedInitialWrite === undefined) {
+      console.warn(
+        `${DwnErrorCode.RecordsWriteGetInitialWriteNotFound}: ` +
+        `${input.operationName} skipped record ${recordsWrite.recordId}`,
+      );
+      continue;
+    }
+
+    const { message: initialWrite } = Messages.detachEncodedData(storedInitialWrite);
+    completeRecordsWrites.push({ ...recordsWrite, initialWrite: initialWrite as RecordsQueryReplyEntry });
+  }
+
+  return completeRecordsWrites;
+}

package/src/utils/protocols.ts

@@ -1,10 +1,7 @@
-import type { DerivedPrivateJwk } from '../utils/hd-key.js';
 import type { EncryptionKeyDeriver } from '../types/encryption-types.js';
-import type { PrivateKeyJwk, PublicKeyJwk } from '../types/jose-types.js';
 import type { ProtocolDefinition, ProtocolRuleSet } from '../types/protocols-types.js';
 
-import { X25519 } from '@enbox/crypto';
-import { HdKey, KeyDerivationScheme } from '../utils/hd-key.js';
+import { KeyDerivationScheme } from '../utils/hd-key.js';
 
 /**
  * Result of parsing a cross-protocol reference in `alias:path` format.
@@ -116,104 +113,44 @@ export class Protocols {
    * because their records belong to the referenced protocol, whose own encryption keys govern them.
    * Children of `$ref` nodes are still processed because they belong to the composing protocol.
    *
-   * Overload 1 (callback-based): Accepts an EncryptionKeyDeriver that performs
-   * key derivation internally. The private key never leaves the caller's boundary.
+   * Accepts an EncryptionKeyDeriver that performs key derivation internally.
+   * The private key never leaves the caller's boundary.
    */
   public static async deriveAndInjectPublicEncryptionKeys(
     protocolDefinition: ProtocolDefinition,
     keyDeriver: EncryptionKeyDeriver,
-  ): Promise<ProtocolDefinition>;
-
-  /**
-   * Overload 2 (raw-key): Takes rootKeyId and raw PrivateKeyJwk directly.
-   */
-  public static async deriveAndInjectPublicEncryptionKeys(
-    protocolDefinition: ProtocolDefinition,
-    rootKeyId: string,
-    privateJwk: PrivateKeyJwk,
-  ): Promise<ProtocolDefinition>;
-
-  // Implementation dispatches based on argument type.
-  public static async deriveAndInjectPublicEncryptionKeys(
-    protocolDefinition: ProtocolDefinition,
-    rootKeyIdOrKeyDeriver: string | EncryptionKeyDeriver,
-    privateJwk?: PrivateKeyJwk,
   ): Promise<ProtocolDefinition> {
     // clone before modify
     const clone = JSON.parse(JSON.stringify(protocolDefinition)) as ProtocolDefinition;
 
-    if (typeof rootKeyIdOrKeyDeriver !== 'string') {
-      // Callback-based path
-      const keyDeriver = rootKeyIdOrKeyDeriver;
-      const basePath = [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol];
-      clone.$keyAgreement = {
-        publicKeyJwk: await keyDeriver.derivePublicKey(basePath),
-      };
-
-      async function injectKeysViaCallback(
-        ruleSet: ProtocolRuleSet, parentPath: string[],
-      ): Promise<void> {
-        for (const key in ruleSet) {
-          if (!key.startsWith('$')) {
-            const currentPath = [...parentPath, key];
-            const childRuleSet = ruleSet[key] as ProtocolRuleSet;
-
-            // Skip $ref nodes — they are governed by the referenced protocol's encryption keys.
-            // Still recurse into children, which belong to the composing protocol.
-            if (childRuleSet.$ref !== undefined) {
-              await injectKeysViaCallback(childRuleSet, currentPath);
-              continue;
-            }
-
-            const publicKeyJwk = await keyDeriver.derivePublicKey(currentPath);
-            childRuleSet.$keyAgreement = { publicKeyJwk };
-            await injectKeysViaCallback(childRuleSet, currentPath);
-          }
-        }
-      }
-
-      await injectKeysViaCallback(clone.structure as ProtocolRuleSet, basePath);
-      return clone;
-    }
-
-    // Raw-key path
-    const rootKeyId = rootKeyIdOrKeyDeriver;
+    const basePath = [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol];
+    clone.$keyAgreement = {
+      publicKeyJwk: await keyDeriver.derivePublicKey(basePath),
+    };
 
-    // a function that recursively creates and adds `$keyAgreement` property to every rule set
-    async function addEncryptionProperty(ruleSet: ProtocolRuleSet, parentKey: DerivedPrivateJwk): Promise<void> {
+    async function injectKeys(
+      ruleSet: ProtocolRuleSet, parentPath: string[],
+    ): Promise<void> {
       for (const key in ruleSet) {
-        // if we encounter a nested rule set (a property name that doesn't begin with '$'), recursively inject the `$keyAgreement` property
         if (!key.startsWith('$')) {
-          const derivedPrivateKey = await HdKey.derivePrivateKey(parentKey, [key]);
+          const currentPath = [...parentPath, key];
           const childRuleSet = ruleSet[key] as ProtocolRuleSet;
 
           // Skip $ref nodes — they are governed by the referenced protocol's encryption keys.
           // Still recurse into children, which belong to the composing protocol.
           if (childRuleSet.$ref !== undefined) {
-            await addEncryptionProperty(childRuleSet, derivedPrivateKey);
+            await injectKeys(childRuleSet, currentPath);
             continue;
           }
 
-          const publicKeyJwk = await X25519.getPublicKey({ key: derivedPrivateKey.derivedPrivateKey }) as PublicKeyJwk;
-
+          const publicKeyJwk = await keyDeriver.derivePublicKey(currentPath);
           childRuleSet.$keyAgreement = { publicKeyJwk };
-          await addEncryptionProperty(childRuleSet, derivedPrivateKey);
+          await injectKeys(childRuleSet, currentPath);
         }
       }
     }
 
-    // inject encryption property starting from each root level record type
-    const rootKey: DerivedPrivateJwk = {
-      derivationScheme  : KeyDerivationScheme.ProtocolPath,
-      derivedPrivateKey : privateJwk!,
-      rootKeyId
-    };
-    const protocolLevelDerivedKey = await HdKey.derivePrivateKey(rootKey, [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol]);
-    clone.$keyAgreement = {
-      publicKeyJwk: await X25519.getPublicKey({ key: protocolLevelDerivedKey.derivedPrivateKey }) as PublicKeyJwk,
-    };
-    await addEncryptionProperty(clone.structure as ProtocolRuleSet, protocolLevelDerivedKey);
-
+    await injectKeys(clone.structure as ProtocolRuleSet, basePath);
     return clone;
   }
 }

package/src/utils/records.ts

@@ -1,7 +1,5 @@
 import type { DerivedPrivateJwk } from './hd-key.js';
-import type { Jwk } from '@enbox/crypto';
 import type { KeyDecrypter } from '../types/encryption-types.js';
-import type { PublicKeyJwk } from '../types/jose-types.js';
 import type { X25519KeyEncryption } from './encryption.js';
 import type { Filter, KeyValues, StartsWithFilter } from '../types/query-types.js';
 import type { GenericMessage, GenericSignaturePayload, MessageSort } from '../types/message-types.js';
@@ -63,31 +61,12 @@ export class Records {
 
   /**
    * Decrypts the encrypted data in a message reply.
-   *
-   * Overload 1 (callback-based): Accepts a KeyDecrypter that performs
-   * X25519-HKDF key agreement + AES Key Unwrap internally.
+   * Accepts a KeyDecrypter that performs X25519-HKDF key agreement + AES Key Unwrap internally.
    */
   public static async decrypt(
     recordsWrite: RecordsWriteMessage,
     keyDecrypter: KeyDecrypter,
     cipherStream: ReadableStream<Uint8Array>,
-  ): Promise<ReadableStream<Uint8Array>>;
-
-  /**
-   * Overload 2 (raw-key): Takes DerivedPrivateJwk directly.
-   * @param ancestorPrivateKey Any ancestor private key in the key derivation path.
-   */
-  public static async decrypt(
-    recordsWrite: RecordsWriteMessage,
-    ancestorPrivateKey: DerivedPrivateJwk,
-    cipherStream: ReadableStream<Uint8Array>,
-  ): Promise<ReadableStream<Uint8Array>>;
-
-  // Implementation dispatches based on argument type.
-  public static async decrypt(
-    recordsWrite: RecordsWriteMessage,
-    keyOrDecrypter: DerivedPrivateJwk | KeyDecrypter,
-    cipherStream: ReadableStream<Uint8Array>,
   ): Promise<ReadableStream<Uint8Array>> {
     const { encryption } = recordsWrite;
     if (encryption === undefined) {
@@ -101,27 +80,21 @@ export class Records {
     const actualDataCid = await Cid.computeDagPbCidFromBytes(ciphertext);
     Records.validateEncryptedDataIntegrity(recordsWrite, actualDataCid, ciphertext.byteLength);
 
-    const { fullDerivationPath, leafPrivateKey, matchingKeyEncryption } =
-      await Records.findMatchingKeyEncryption(recordsWrite, keyOrDecrypter);
+    const { fullDerivationPath, matchingKeyEncryption } =
+      await Records.findMatchingKeyEncryption(recordsWrite, keyDecrypter);
 
     if (matchingKeyEncryption === undefined) {
       throw new DwnError(
         DwnErrorCode.RecordsDecryptNoMatchingKeyEncryptedFound,
-        `Unable to find a matching key encryption entry for '${keyOrDecrypter.rootKeyId}' and '${keyOrDecrypter.derivationScheme}'.`
+        `Unable to find a matching key encryption entry for '${keyDecrypter.rootKeyId}' and '${keyDecrypter.derivationScheme}'.`
       );
     }
 
-    let cek: Uint8Array;
-
-    if ('decrypt' in keyOrDecrypter) {
-      cek = await keyOrDecrypter.decrypt(fullDerivationPath, {
-        encryptedKey       : Encoder.base64UrlToBytes(matchingKeyEncryption.encryptedKey),
-        ephemeralPublicKey : matchingKeyEncryption.ephemeralPublicKey,
-        keyEncryption      : matchingKeyEncryption,
-      });
-    } else {
-      cek = await Encryption.unwrapKey(leafPrivateKey!, matchingKeyEncryption);
-    }
+    const cek = await keyDecrypter.decrypt(fullDerivationPath, {
+      encryptedKey       : Encoder.base64UrlToBytes(matchingKeyEncryption.encryptedKey),
+      ephemeralPublicKey : matchingKeyEncryption.ephemeralPublicKey,
+      keyEncryption      : matchingKeyEncryption,
+    });
 
     const iv = Encoder.base64UrlToBytes(encryption.initializationVector);
     const plaintext = await Encryption.decrypt(encryption.algorithm, cek, iv, ciphertext);
@@ -132,33 +105,18 @@ export class Records {
 
   private static async findMatchingKeyEncryption(
     recordsWrite: RecordsWriteMessage,
-    keyOrDecrypter: DerivedPrivateJwk | KeyDecrypter,
-  ): Promise<{ fullDerivationPath: string[]; leafPrivateKey?: Jwk; matchingKeyEncryption?: X25519KeyEncryption }> {
+    keyDecrypter: KeyDecrypter,
+  ): Promise<{ fullDerivationPath: string[]; matchingKeyEncryption?: X25519KeyEncryption }> {
     const { encryption } = recordsWrite;
-    const fullDerivationPath = Records.constructKeyDerivationPath(keyOrDecrypter.derivationScheme, recordsWrite);
-
-    if ('decrypt' in keyOrDecrypter) {
-      const publicKey = await keyOrDecrypter.derivePublicKey(fullDerivationPath);
-      const keyId = await Encryption.getKeyId(publicKey);
-      return {
-        fullDerivationPath,
-        matchingKeyEncryption: encryption!.keyEncryption.find((entry): boolean =>
-          entry.derivationScheme === keyOrDecrypter.derivationScheme && entry.keyId === keyId
-        ),
-      };
-    }
-
-    const leafPrivateKeyBytes = await Records.derivePrivateKey(keyOrDecrypter, fullDerivationPath);
-    const leafPrivateKey = await X25519.bytesToPrivateKey({ privateKeyBytes: leafPrivateKeyBytes });
+    const fullDerivationPath = Records.constructKeyDerivationPath(keyDecrypter.derivationScheme, recordsWrite);
 
-    const publicKey = await X25519.getPublicKey({ key: leafPrivateKey });
-    const keyId = keyOrDecrypter.keyId ?? await Encryption.getKeyId(publicKey as PublicKeyJwk);
+    const publicKey = await keyDecrypter.derivePublicKey(fullDerivationPath);
+    const keyId = await Encryption.getKeyId(publicKey);
 
     return {
       fullDerivationPath,
-      leafPrivateKey,
       matchingKeyEncryption: encryption!.keyEncryption.find((entry): boolean =>
-        entry.derivationScheme === keyOrDecrypter.derivationScheme && entry.keyId === keyId
+        entry.derivationScheme === keyDecrypter.derivationScheme && entry.keyId === keyId
       ),
     };
   }

package/dist/esm/tests/validation/json-schemas/encryption/delivery.spec.js

@@ -1,47 +0,0 @@
-import { validateJsonSchema } from '../../../../src/schema-validator.js';
-import { describe, expect, it } from 'bun:test';
-const delivery = {
-    contextId: 'thread-1',
-    keyId: 'abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG',
-    keyMaterial: {
-        algorithm: 'X25519-HKDF-SHA256+A256KW',
-        derivationScheme: 'roleAudience',
-        keyId: 'abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG',
-        privateKeyJwk: {
-            crv: 'X25519',
-            d: 'private-key',
-            kty: 'OKP',
-            x: 'public-key',
-        },
-        publicKeyJwk: {
-            crv: 'X25519',
-            kty: 'OKP',
-            x: 'public-key',
-        },
-    },
-    protocol: 'https://example.com/protocol',
-    rolePath: 'thread/participant',
-};
-describe('Delivery Schema', () => {
-    it('should accept a roleAudience key delivery payload', () => {
-        expect(() => validateJsonSchema('Delivery', delivery)).not.toThrow();
-    });
-    it('should reject legacy epoch fields', () => {
-        const invalidDelivery = {
-            ...structuredClone(delivery),
-            epoch: 1,
-        };
-        expect(() => validateJsonSchema('Delivery', invalidDelivery)).toThrow();
-    });
-    it('should reject non-roleAudience key material', () => {
-        const invalidDelivery = structuredClone(delivery);
-        invalidDelivery.keyMaterial.derivationScheme = 'protocolPath';
-        expect(() => validateJsonSchema('Delivery', invalidDelivery)).toThrow();
-    });
-    it('should reject key IDs that are not base64url thumbprints', () => {
-        const invalidDelivery = structuredClone(delivery);
-        invalidDelivery.keyMaterial.keyId = 'abcdefghijklmnopqrstuvwxyz0123456789ABCDEF!';
-        expect(() => validateJsonSchema('Delivery', invalidDelivery)).toThrow();
-    });
-});
-//# sourceMappingURL=delivery.spec.js.map

package/dist/esm/tests/validation/json-schemas/encryption/delivery.spec.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"delivery.spec.js","sourceRoot":"","sources":["../../../../../../tests/validation/json-schemas/encryption/delivery.spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEhD,MAAM,QAAQ,GAAG;IACf,SAAS,EAAK,UAAU;IACxB,KAAK,EAAS,6CAA6C;IAC3D,WAAW,EAAG;QACZ,SAAS,EAAU,2BAA2B;QAC9C,gBAAgB,EAAG,cAAc;QACjC,KAAK,EAAc,6CAA6C;QAChE,aAAa,EAAM;YACjB,GAAG,EAAG,QAAQ;YACd,CAAC,EAAK,aAAa;YACnB,GAAG,EAAG,KAAK;YACX,CAAC,EAAK,YAAY;SACnB;QACD,YAAY,EAAE;YACZ,GAAG,EAAG,QAAQ;YACd,GAAG,EAAG,KAAK;YACX,CAAC,EAAK,YAAY;SACnB;KACF;IACD,QAAQ,EAAG,8BAA8B;IACzC,QAAQ,EAAG,oBAAoB;CAChC,CAAC;AAEF,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,CACJ,GAAG,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAC/C,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,eAAe,GAAG;YACtB,GAAG,eAAe,CAAC,QAAQ,CAAC;YAC5B,KAAK,EAAE,CAAC;SACT,CAAC;QAEF,MAAM,CACJ,GAAG,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,eAAe,CAAC,CACtD,CAAC,OAAO,EAAE,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,eAAe,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QAClD,eAAe,CAAC,WAAW,CAAC,gBAAgB,GAAG,cAAc,CAAC;QAE9D,MAAM,CACJ,GAAG,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,eAAe,CAAC,CACtD,CAAC,OAAO,EAAE,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,eAAe,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;QAClD,eAAe,CAAC,WAAW,CAAC,KAAK,GAAG,6CAA6C,CAAC;QAElF,MAAM,CACJ,GAAG,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,eAAe,CAAC,CACtD,CAAC,OAAO,EAAE,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}