@enbox/agent 0.1.5 → 0.1.6

package/dist/esm/dwn-api.js

@@ -8,32 +8,24 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { TtlCache } from '@enbox/common';
-import { Cid, ContentEncryptionAlgorithm, DataStoreLevel, DataStream, Dwn, DwnInterfaceName, DwnMethodName, Encoder, Encryption, EventEmitterStream, Jws, KeyDerivationScheme, Message, MessageStoreLevel, Protocols, Records, ResumableTaskStoreLevel, StateIndexLevel } from '@enbox/dwn-sdk-js';
+import { Cid, ContentEncryptionAlgorithm, DataStoreLevel, DataStream, Dwn, DwnMethodName, EventEmitterStream, Jws, KeyDerivationScheme, Message, MessageStoreLevel, Protocols, Records, ResumableTaskStoreLevel, StateIndexLevel, } from '@enbox/dwn-sdk-js';
 import { CryptoUtils, X25519 } from '@enbox/crypto';
 import { DidDht, DidJwk, DidResolverCacheLevel, UniversalResolver } from '@enbox/dids';
 import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
 import { DwnInterface, dwnMessageConstructors } from './types/dwn.js';
 import { getDwnServiceEndpointUrls, isRecordsWrite } from './utils.js';
-export function isDwnRequest(dwnRequest, messageType) {
-    return dwnRequest.messageType === messageType;
-}
-export function isDwnMessage(messageType, message) {
-    const incomingMessageInterfaceName = message.descriptor.interface + message.descriptor.method;
-    return incomingMessageInterfaceName === messageType;
-}
-export function isRecordsType(messageType) {
-    return messageType === DwnInterface.RecordsDelete ||
-        messageType === DwnInterface.RecordsQuery ||
-        messageType === DwnInterface.RecordsRead ||
-        messageType === DwnInterface.RecordsSubscribe ||
-        messageType === DwnInterface.RecordsWrite;
-}
-export function isRecordPermissionScope(scope) {
-    return scope.interface === DwnInterfaceName.Records;
-}
-export function isMessagesPermissionScope(scope) {
-    return scope.interface === DwnInterfaceName.Messages;
-}
+// Re-export type guards for backward compatibility
+export { isDwnMessage, isDwnRequest, isMessagesPermissionScope, isRecordPermissionScope, isRecordsType } from './dwn-type-guards.js';
+// Import type guards for internal use
+import { isDwnRequest } from './dwn-type-guards.js';
+// Import extracted encryption functions
+import { buildEncryptionInput as buildEncryptionInputFn, deriveContextEncryptionInput as deriveContextEncryptionInputFn, encryptAndComputeCid as encryptAndComputeCidFn, getEncryptionKeyDeriver as getEncryptionKeyDeriverFn, getEncryptionKeyInfo as getEncryptionKeyInfoFn, getKeyDecrypter as getKeyDecrypterFn, ivLength as ivLengthFn, maybeDecryptReply as maybeDecryptReplyFn, } from './dwn-encryption.js';
+// Import extracted protocol utilities
+import { detectNewParticipants as detectNewParticipantsFn, hasRelationalReadAccess as hasRelationalReadAccessFn, isMultiPartyContext as isMultiPartyContextFn, } from './protocol-utils.js';
+// Import extracted key delivery functions
+import { eagerSendContextKeyRecord as eagerSendContextKeyRecordFn, ensureKeyDeliveryProtocol as ensureKeyDeliveryProtocolFn, fetchContextKeyRecord as fetchContextKeyRecordFn, writeContextKeyRecord as writeContextKeyRecordFn, } from './dwn-key-delivery.js';
+// Import extracted record upgrade function
+import { upgradeExternalRootRecord as upgradeExternalRootRecordFn } from './dwn-record-upgrade.js';
 export class AgentDwnApi {
     constructor({ agent, dwn }) {
         /**
@@ -154,17 +146,17 @@ export class AgentDwnApi {
                             const isExternallyAuthored = authorDid !== request.target;
                             const isRootRecord = !writeParams.parentContextId;
                             const rootPathSegment = writeParams.protocolPath.split('/')[0];
-                            const isMultiParty = this.isMultiPartyContext(protocolDefinition, rootPathSegment);
+                            const isMultiParty = isMultiPartyContextFn(protocolDefinition, rootPathSegment);
                             if (isExternallyAuthored && isRootRecord && isMultiParty) {
                                 try {
-                                    yield this.upgradeExternalRootRecord(request.target, recordsWriteMessage);
+                                    yield upgradeExternalRootRecordFn(this.agent, request.target, recordsWriteMessage, this._dwn, this.getSigner.bind(this), this._contextKeyCache);
                                 }
                                 catch (upgradeError) {
                                     console.warn(`AgentDwnApi: Reactive root-record upgrade failed for ` +
                                         `'${recordsWriteMessage.recordId}': ${upgradeError.message}`);
                                 }
                             }
-                            const newParticipants = this.detectNewParticipants({
+                            const newParticipants = detectNewParticipantsFn({
                                 protocolDefinition,
                                 protocolPath: writeParams.protocolPath,
                                 recipient: writeParams.recipient,
@@ -176,7 +168,7 @@ export class AgentDwnApi {
                                 const rootContextId = ((_a = recordsWriteMessage.contextId) === null || _a === void 0 ? void 0 : _a.split('/')[0])
                                     || recordsWriteMessage.contextId
                                     || recordsWriteMessage.recordId;
-                                const { keyId, keyUri } = yield this.getEncryptionKeyInfo(request.target);
+                                const { keyId, keyUri } = yield getEncryptionKeyInfoFn(this.agent, request.target);
                                 const contextDerivationPath = [
                                     KeyDerivationScheme.ProtocolContext,
                                     rootContextId,
@@ -371,7 +363,7 @@ export class AgentDwnApi {
             // Auto-inject encryption keys into protocol definition (Component 5)
             if (isDwnRequest(request, DwnInterface.ProtocolsConfigure) && request.encryption && !rawMessage) {
                 const messageParams = request.messageParams;
-                const keyDeriver = yield this.getEncryptionKeyDeriver(request.author);
+                const keyDeriver = yield getEncryptionKeyDeriverFn(this.agent, request.author);
                 // SDK walks the protocol structure and calls our callback for each path.
                 // The KMS performs HKDF derivation + public key computation internally.
                 messageParams.definition = yield Protocols.deriveAndInjectPublicEncryptionKeys(messageParams.definition, keyDeriver);
@@ -445,7 +437,7 @@ export class AgentDwnApi {
                     const isKeyDeliveryProtocol = messageParams.protocol === KeyDeliveryProtocolDefinition.protocol;
                     const isMultiPartyContext = isKeyDeliveryProtocol
                         ? false
-                        : this.isMultiPartyContext(protocolDefinition, rootPathSegment);
+                        : isMultiPartyContextFn(protocolDefinition, rootPathSegment);
                     const isRootRecord = !messageParams.parentContextId;
                     // 4. Get plaintext bytes (normalize from all supported input types)
                     let plaintextBytes;
@@ -466,27 +458,21 @@ export class AgentDwnApi {
                     // 5. Generate random DEK and IV (IV size depends on content encryption algorithm)
                     const contentEncryptionAlgorithm = ContentEncryptionAlgorithm.A256GCM;
                     const dataEncryptionKey = crypto.getRandomValues(new Uint8Array(32));
-                    const dataEncryptionIV = crypto.getRandomValues(new Uint8Array(AgentDwnApi.ivLength(contentEncryptionAlgorithm)));
+                    const dataEncryptionIV = crypto.getRandomValues(new Uint8Array(ivLengthFn(contentEncryptionAlgorithm)));
                     // 6. Build partial EncryptionInput (authenticationTag added after AEAD encryption)
                     let encryptionInput;
-                    const buildProtocolPathInput = () => this.buildEncryptionInput(dataEncryptionKey, dataEncryptionIV, ruleSet.$encryption.rootKeyId, ruleSet.$encryption.publicKeyJwk, KeyDerivationScheme.ProtocolPath);
+                    const buildProtocolPathInput = () => buildEncryptionInputFn(dataEncryptionKey, dataEncryptionIV, ruleSet.$encryption.rootKeyId, ruleSet.$encryption.publicKeyJwk, KeyDerivationScheme.ProtocolPath);
                     if (isCrossDwn && isMultiPartyContext && isRootRecord) {
-                        // --- Cross-DWN root record in multi-party context → Target's ProtocolPath key ---
-                        // External authors cannot derive the target's context key (HKDF requires
-                        // the private key). Use the target's ProtocolPath public key from their
-                        // protocol definition. The target's agent will reactively upgrade the record
-                        // to include a ProtocolContext recipient entry.
+                        // --- Cross-DWN root record in multi-party context -> Target's ProtocolPath key ---
                         encryptionInput = buildProtocolPathInput();
                     }
                     else if (isCrossDwn && isMultiPartyContext && !isRootRecord) {
-                        // --- Cross-DWN non-root record in multi-party context → derivedPublicKey ---
-                        // Read an existing ProtocolContext-encrypted record from the target's DWN
-                        // and extract the derivedPublicKey (the context public key).
+                        // --- Cross-DWN non-root record in multi-party context -> derivedPublicKey ---
                         const rootContextId = messageParams.parentContextId.split('/')[0]
                             || messageParams.parentContextId;
                         const derivedPublicKeyInfo = yield this.extractDerivedPublicKey(request.target, messageParams.protocol, rootContextId, request.author);
                         if (derivedPublicKeyInfo) {
-                            encryptionInput = this.buildEncryptionInput(dataEncryptionKey, dataEncryptionIV, derivedPublicKeyInfo.rootKeyId, derivedPublicKeyInfo.derivedPublicKey, KeyDerivationScheme.ProtocolContext);
+                            encryptionInput = buildEncryptionInputFn(dataEncryptionKey, dataEncryptionIV, derivedPublicKeyInfo.rootKeyId, derivedPublicKeyInfo.derivedPublicKey, KeyDerivationScheme.ProtocolContext);
                         }
                         else {
                             // Fallback: no ProtocolContext-encrypted record exists yet (owner hasn't
@@ -495,16 +481,16 @@ export class AgentDwnApi {
                         }
                     }
                     else if (isCrossDwn) {
-                        // --- Cross-DWN single-party → Target's ProtocolPath key ---
+                        // --- Cross-DWN single-party -> Target's ProtocolPath key ---
                         encryptionInput = buildProtocolPathInput();
                     }
                     else if (isMultiPartyContext && !isRootRecord) {
-                        // --- Local non-root record in a multi-party context → Context key ---
+                        // --- Local non-root record in a multi-party context -> Context key ---
                         const rootContextId = messageParams.parentContextId.split('/')[0]
                             || messageParams.parentContextId;
                         let contextKeyInfo = this._contextKeyCache.get(rootContextId);
                         if (!contextKeyInfo) {
-                            const { keyId, keyUri } = yield this.getEncryptionKeyInfo(request.author);
+                            const { keyId, keyUri } = yield getEncryptionKeyInfoFn(this.agent, request.author);
                             const contextDerivationPath = Records.constructKeyDerivationPathUsingProtocolContextScheme(rootContextId);
                             contextKeyInfo = { keyId, keyUri, contextDerivationPath };
                             this._contextKeyCache.set(rootContextId, contextKeyInfo);
@@ -513,20 +499,20 @@ export class AgentDwnApi {
                             keyUri: contextKeyInfo.keyUri,
                             derivationPath: contextKeyInfo.contextDerivationPath,
                         });
-                        encryptionInput = this.buildEncryptionInput(dataEncryptionKey, dataEncryptionIV, contextKeyInfo.keyId, contextPublicKey, KeyDerivationScheme.ProtocolContext);
+                        encryptionInput = buildEncryptionInputFn(dataEncryptionKey, dataEncryptionIV, contextKeyInfo.keyId, contextPublicKey, KeyDerivationScheme.ProtocolContext);
                     }
                     else if (isMultiPartyContext && isRootRecord) {
-                        // --- Local root record in multi-party context → Deferred context encryption ---
+                        // --- Local root record in multi-party context -> Deferred context encryption ---
                         // contextId = recordId, which is only known after message creation.
                         // Skip encryptionInput here; apply it after create() below.
                         encryptionInput = undefined;
                     }
                     else {
-                        // --- Local single-party → ProtocolPath key (existing logic) ---
+                        // --- Local single-party -> ProtocolPath key (existing logic) ---
                         encryptionInput = buildProtocolPathInput();
                     }
                     // 7. Encrypt data with AEAD and compute CID
-                    const { encryptedBytes, dataCid, dataSize, authenticationTag } = yield this.encryptAndComputeCid(plaintextBytes, dataEncryptionKey, dataEncryptionIV, contentEncryptionAlgorithm);
+                    const { encryptedBytes, dataCid, dataSize, authenticationTag } = yield encryptAndComputeCidFn(plaintextBytes, dataEncryptionKey, dataEncryptionIV, contentEncryptionAlgorithm);
                     // 8. Replace plaintext with encrypted data
                     messageParams.dataCid = dataCid;
                     messageParams.dataSize = dataSize;
@@ -545,7 +531,7 @@ export class AgentDwnApi {
                     //    key-delivery ProtocolPath public key so the DWN owner can encrypt
                     //    context keys back to the author without querying the author's DWN.
                     if (isCrossDwn && isMultiPartyContext) {
-                        const { keyId: authorKeyId, keyUri: authorKeyUri } = yield this.getEncryptionKeyInfo(request.author);
+                        const { keyId: authorKeyId, keyUri: authorKeyUri } = yield getEncryptionKeyInfoFn(this.agent, request.author);
                         const keyDeliveryDerivationPath = [
                             KeyDerivationScheme.ProtocolPath,
                             KeyDeliveryProtocolDefinition.protocol,
@@ -574,11 +560,11 @@ export class AgentDwnApi {
                 dwnMessage = yield dwnMessageConstructor.create(Object.assign(Object.assign({}, request.messageParams), { signer }));
                 // Deferred context encryption for root multi-party records (Component 9).
                 // Now that the message exists, we know recordId = contextId.
-                // Following the SDK two-pass pattern: encryptSymmetricEncryptionKey → sign.
+                // Following the SDK two-pass pattern: encryptSymmetricEncryptionKey -> sign.
                 if (deferredContextEncryption && isDwnRequest(request, DwnInterface.RecordsWrite)) {
                     const recordsWriteInstance = dwnMessage;
                     const contextId = recordsWriteInstance.message.recordId;
-                    const { encryptionInput: contextEncryptionInput, keyId, keyUri, contextDerivationPath } = yield this.deriveContextEncryptionInput(request.author, contextId, deferredContextEncryption.dataEncryptionKey, deferredContextEncryption.dataEncryptionIV);
+                    const { encryptionInput: contextEncryptionInput, keyId, keyUri, contextDerivationPath } = yield deriveContextEncryptionInputFn(this.agent, request.author, contextId, deferredContextEncryption.dataEncryptionKey, deferredContextEncryption.dataEncryptionIV);
                     const fullContextInput = Object.assign(Object.assign({}, contextEncryptionInput), { authenticationTag: deferredContextEncryption.authenticationTag });
                     yield recordsWriteInstance.encryptSymmetricEncryptionKey(fullContextInput);
                     yield recordsWriteInstance.sign({ signer });
@@ -653,180 +639,69 @@ export class AgentDwnApi {
         });
     }
     /**
-     * Resolves the encryption key info for a given DID.
-     * Looks up the keyAgreement verification method in the DID document,
-     * then resolves the corresponding KMS key URI.
+     * Constructs an EncryptionKeyDeriver callback for the SDK.
+     * Delegates to the standalone function in `dwn-encryption.ts`.
      *
-     * @param didUri - The DID URI to resolve encryption key info for
-     * @returns keyId (fully qualified verification method ID), keyUri (KMS reference),
-     *          and publicKeyJwk. No private key material is returned.
-     * @throws If the DID has no keyAgreement verification method or it's not X25519.
+     * @param didUri - The DID URI to create the key deriver for
+     * @returns An EncryptionKeyDeriver callback object
      */
-    getEncryptionKeyInfo(didUri) {
+    getEncryptionKeyDeriver(didUri) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            // 1. Resolve the DID document
-            const { didDocument, didResolutionMetadata } = yield this.agent.did.resolve(didUri);
-            if (!didDocument) {
-                throw new Error(`AgentDwnApi: Failed to resolve DID '${didUri}': ` +
-                    `${JSON.stringify(didResolutionMetadata)}`);
-            }
-            // 2. Find the keyAgreement verification method
-            const keyAgreementRefs = didDocument.keyAgreement;
-            if (!keyAgreementRefs || keyAgreementRefs.length === 0) {
-                throw new Error(`AgentDwnApi: DID '${didUri}' does not have a keyAgreement ` +
-                    `verification method. Create the identity with an X25519 key ` +
-                    `with keyAgreement purpose to use protocol encryption.`);
-            }
-            // 3. Resolve the verification method (handle both inline and string refs)
-            const keyAgreementRef = keyAgreementRefs[0];
-            let verificationMethod;
-            if (typeof keyAgreementRef === 'string') {
-                const fragment = keyAgreementRef.includes('#')
-                    ? keyAgreementRef.split('#').pop()
-                    : keyAgreementRef;
-                verificationMethod = (_a = didDocument.verificationMethod) === null || _a === void 0 ? void 0 : _a.find(vm => vm.id.endsWith(`#${fragment}`));
-            }
-            else {
-                verificationMethod = keyAgreementRef;
-            }
-            if (!(verificationMethod === null || verificationMethod === void 0 ? void 0 : verificationMethod.publicKeyJwk)) {
-                throw new Error(`AgentDwnApi: keyAgreement verification method for '${didUri}' ` +
-                    `does not contain a public key in JWK format.`);
-            }
-            // 4. Verify it's an X25519 key
-            const publicKeyJwk = verificationMethod.publicKeyJwk;
-            if (publicKeyJwk.crv !== 'X25519') {
-                throw new Error(`AgentDwnApi: keyAgreement key for '${didUri}' uses curve ` +
-                    `'${publicKeyJwk.crv}', but DWN encryption requires 'X25519'.`);
-            }
-            // 5. Compute the KMS key URI (does NOT export the key)
-            const keyUri = yield this.agent.keyManager.getKeyUri({ key: publicKeyJwk });
-            return {
-                keyId: verificationMethod.id,
-                keyUri,
-                publicKeyJwk: publicKeyJwk,
-            };
+            return getEncryptionKeyDeriverFn(this.agent, didUri);
         });
     }
     /**
-     * Builds a partial EncryptionInput object for a single key-encryption entry.
-     * The `authenticationTag` is NOT set here — the caller must set it after
-     * AEAD encryption produces the tag.
-     */
-    /**
-     * Returns the correct nonce/IV byte length for the given content encryption algorithm.
-     * A256GCM uses 96-bit (12-byte) nonces; XC20P uses 192-bit (24-byte) nonces.
-     */
-    static ivLength(algorithm) {
-        return algorithm === ContentEncryptionAlgorithm.XC20P ? 24 : 12;
-    }
-    buildEncryptionInput(dek, iv, publicKeyId, publicKey, derivationScheme) {
-        return {
-            initializationVector: iv,
-            key: dek,
-            keyEncryptionInputs: [{
-                    publicKeyId,
-                    publicKey,
-                    derivationScheme,
-                }],
-        };
-    }
-    /**
-     * Encrypts plaintext bytes with AEAD and computes the CID of the resulting ciphertext.
-     * Returns everything needed to attach the encrypted data to a DWN message, including
-     * the authentication tag.
+     * Resolves the keyAgreement verification method for the given DID and returns
+     * the key ID, key URI, and public key JWK.
+     *
+     * @param didUri - The DID URI to look up
      */
-    encryptAndComputeCid(plaintextBytes_1, dek_1, iv_1) {
-        return __awaiter(this, arguments, void 0, function* (plaintextBytes, dek, iv, algorithm = ContentEncryptionAlgorithm.A256GCM) {
-            const { ciphertextStream, tag: authenticationTag } = yield Encryption.aeadEncryptStream(algorithm, dek, iv, DataStream.fromBytes(plaintextBytes));
-            const encryptedBytes = yield DataStream.toBytes(ciphertextStream);
-            const cidStream = DataStream.fromBytes(encryptedBytes);
-            const dataCid = yield Cid.computeDagPbCidFromStream(cidStream);
-            return { encryptedBytes, dataCid, dataSize: encryptedBytes.length, authenticationTag };
+    getEncryptionKeyInfo(didUri) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return getEncryptionKeyInfoFn(this.agent, didUri);
         });
     }
     /**
-     * Derives a ProtocolContext public key for a given DID and context ID,
-     * then returns a fully-formed EncryptionInput. Consolidates the repeated
-     * getEncryptionKeyInfo → constructKeyDerivationPath → derivePublicKey
-     * → build EncryptionInput sequence.
+     * Constructs a ProtocolPath KeyDecrypter for the given DID.
+     *
+     * @param didUri - The DID URI to build a decrypter for
      */
-    deriveContextEncryptionInput(didUri, contextId, dek, iv) {
+    getKeyDecrypter(didUri) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { keyId, keyUri } = yield this.getEncryptionKeyInfo(didUri);
-            const contextDerivationPath = Records.constructKeyDerivationPathUsingProtocolContextScheme(contextId);
-            const contextPublicKey = yield this.agent.keyManager.derivePublicKey({
-                keyUri,
-                derivationPath: contextDerivationPath,
-            });
-            const encryptionInput = this.buildEncryptionInput(dek, iv, keyId, contextPublicKey, KeyDerivationScheme.ProtocolContext);
-            return { encryptionInput, keyId, keyUri, contextDerivationPath };
+            return getKeyDecrypterFn(this.agent, didUri);
         });
     }
     /**
-     * Builds a KMS-backed JWE key unwrap callback. Used for both ProtocolPath
-     * and ProtocolContext decryption where the KMS holds the root private key.
+     * Checks if a protocol path represents a multi-party context.
+     *
+     * @param protocolDefinition - The full protocol definition
+     * @param rootProtocolPath - The root protocol path to check
      */
-    buildKmsDecryptCallback(keyId, keyUri, derivationScheme) {
-        const keyManager = this.agent.keyManager;
-        return {
-            rootKeyId: keyId,
-            derivationScheme,
-            decrypt: (fullDerivationPath, jwePayload) => __awaiter(this, void 0, void 0, function* () {
-                return keyManager.jweKeyUnwrap({
-                    keyUri,
-                    derivationPath: fullDerivationPath,
-                    encryptedKey: jwePayload.encryptedKey,
-                    ephemeralPublicKey: jwePayload.ephemeralPublicKey,
-                });
-            }),
-        };
+    isMultiPartyContext(protocolDefinition, rootProtocolPath) {
+        return isMultiPartyContextFn(protocolDefinition, rootProtocolPath);
     }
     /**
-     * Constructs an EncryptionKeyDeriver callback for the SDK.
-     * The SDK calls derivePublicKey(path), the KMS performs HKDF + public key
-     * computation internally. The private key never leaves the KMS.
-     *
-     * Analogous to getSigner() for signing operations.
+     * Checks if any `$actions` rule in the protocol grants read access
+     * via `who: '<actorType>'` and `of: '<path>'`.
      *
-     * @param didUri - The DID URI to create the key deriver for
-     * @returns An EncryptionKeyDeriver callback object
+     * @param actorType - The actor type to check ('author', 'recipient', or undefined for any)
+     * @param ofPath - The protocol path to check
+     * @param protocolDefinition - The protocol definition
      */
-    getEncryptionKeyDeriver(didUri) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const { keyId, keyUri } = yield this.getEncryptionKeyInfo(didUri);
-            const keyManager = this.agent.keyManager;
-            return {
-                rootKeyId: keyId,
-                derivationScheme: KeyDerivationScheme.ProtocolPath,
-                derivePublicKey: (fullDerivationPath) => __awaiter(this, void 0, void 0, function* () {
-                    return keyManager.derivePublicKey({
-                        keyUri,
-                        derivationPath: fullDerivationPath,
-                    });
-                }),
-            };
-        });
+    hasRelationalReadAccess(actorType, ofPath, protocolDefinition) {
+        return hasRelationalReadAccessFn(actorType, ofPath, protocolDefinition);
     }
     /**
-     * Constructs a KeyDecrypter callback for the SDK.
-     * The SDK calls decrypt(path, eciesParams), the KMS performs HKDF + ECIES
-     * decryption internally. The private key never leaves the KMS.
-     *
-     * Analogous to getSigner() for signing operations.
+     * Analyses a record write to determine which DIDs need context key delivery.
      *
-     * @param didUri - The DID URI to create the key decrypter for
-     * @returns A KeyDecrypter callback object
+     * @param params - Parameters for participant detection
+     * @returns Set of DIDs that need context key delivery
      */
-    getKeyDecrypter(didUri) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const { keyId, keyUri } = yield this.getEncryptionKeyInfo(didUri);
-            return this.buildKmsDecryptCallback(keyId, keyUri, KeyDerivationScheme.ProtocolPath);
-        });
+    detectNewParticipants(params) {
+        return detectNewParticipantsFn(params);
     }
     /**
-     * Fetches a protocol definition from the local DWN, with caching.
+      * Fetches a protocol definition from the local DWN, with caching.
      * Returns undefined if the protocol is not installed.
      *
      * @param tenantDid - The tenant DID to query
@@ -855,150 +730,6 @@ export class AgentDwnApi {
             return definition;
         });
     }
-    /**
-     * Checks if a protocol path represents a multi-party context. Returns true
-     * if the root path's subtree contains:
-     *   (a) any `$role: true` descendants, OR
-     *   (b) any relational `who`/`of` `$actions` rules that grant `read` access
-     *       (indicating external authors or recipients need context keys).
-     *
-     * This generalises the earlier `protocolPathHasRoles()` to cover protocols
-     * that use relational access without explicit role definitions.
-     */
-    isMultiPartyContext(protocolDefinition, rootProtocolPath) {
-        const segments = rootProtocolPath.split('/');
-        let ruleSet = protocolDefinition.structure;
-        for (const segment of segments) {
-            ruleSet = ruleSet[segment];
-            if (!ruleSet) {
-                return false;
-            }
-        }
-        // (a) Check for $role descendants in the subtree
-        function hasRoleRecursive(rs) {
-            for (const key in rs) {
-                if (!key.startsWith('$')) {
-                    const child = rs[key];
-                    if (child.$role === true) {
-                        return true;
-                    }
-                    if (hasRoleRecursive(child)) {
-                        return true;
-                    }
-                }
-            }
-            return false;
-        }
-        if (hasRoleRecursive(ruleSet)) {
-            return true;
-        }
-        // (b) Check for relational who/of read rules anywhere in the protocol
-        //     that reference a path within this subtree. A rule like
-        //     { who: 'recipient', of: 'email', can: ['read'] } on any record
-        //     type means the email recipient needs a context key.
-        return this.hasRelationalReadAccess(undefined, rootProtocolPath, protocolDefinition);
-    }
-    /**
-     * Checks whether any relational `who`/`of` rule in the protocol grants
-     * `read` access for a given actor type and ancestor path.
-     *
-     * Walks the *entire* protocol structure looking for any `$actions` rule that:
-     *   - Has `who` equal to `actorType` ('recipient' or 'author'), or any actor
-     *     type if `actorType` is `undefined`
-     *   - Has `of` equal to `ofPath`
-     *   - Has `can` including 'read'
-     *
-     * The search covers all record types in the protocol, since a relational
-     * rule can appear at any level (e.g. `{ who: 'recipient', of: 'thread',
-     * can: ['read'] }` might be defined on `thread/message`).
-     *
-     * @param actorType  - 'author' | 'recipient', or undefined for any
-     * @param ofPath     - The protocol path to check (e.g. 'thread', 'email')
-     * @param protocolDefinition - The full protocol definition
-     * @returns true if a matching relational read rule exists
-     */
-    hasRelationalReadAccess(actorType, ofPath, protocolDefinition) {
-        const structure = protocolDefinition.structure;
-        function walkRuleSet(rs) {
-            var _a;
-            // Check $actions on this node
-            if (rs.$actions) {
-                for (const rule of rs.$actions) {
-                    if (rule.who &&
-                        rule.who !== 'anyone' &&
-                        (actorType === undefined || rule.who === actorType) &&
-                        rule.of === ofPath &&
-                        ((_a = rule.can) === null || _a === void 0 ? void 0 : _a.includes('read'))) {
-                        return true;
-                    }
-                }
-            }
-            // Recurse into child record types
-            for (const key in rs) {
-                if (!key.startsWith('$')) {
-                    if (walkRuleSet(rs[key])) {
-                        return true;
-                    }
-                }
-            }
-            return false;
-        }
-        return walkRuleSet(structure);
-    }
-    /**
-     * Analyses a record write to determine which DIDs need context key delivery.
-     *
-     * Returns a set of participant DIDs that should receive `contextKey` records.
-     * The DWN owner (tenantDid) is always excluded — they have ProtocolPath access.
-     *
-     * Cases handled:
-     *   1. `$role` record with a recipient → recipient is a participant
-     *   2. Record has a recipient and a relational read rule grants access
-     *      via `{ who: 'recipient', of: '<path>', can: ['read'] }`
-     *   3. Record is authored by an external party → if `{ who: 'author', of:
-     *      '<path>', can: ['read'] }` rules grant read access, the author needs
-     *      a context key.
-     *
-     * @param params.protocolDefinition - The installed protocol definition
-     * @param params.protocolPath       - The written record's protocol path
-     * @param params.recipient          - Recipient DID from the record, if any
-     * @param params.tenantDid          - The DWN owner's DID (excluded from results)
-     * @param params.authorDid          - Author DID if externally authored, undefined otherwise
-     * @returns Set of DIDs that need context key delivery
-     */
-    detectNewParticipants({ protocolDefinition, protocolPath, recipient, tenantDid, authorDid }) {
-        const participants = new Set();
-        // Navigate to the rule set at the given protocol path
-        const pathSegments = protocolPath.split('/');
-        let ruleSet = protocolDefinition.structure;
-        for (const segment of pathSegments) {
-            ruleSet = ruleSet[segment];
-            if (!ruleSet) {
-                return participants;
-            }
-        }
-        // Case 1: $role record → recipient is a participant
-        if (ruleSet.$role === true && recipient) {
-            participants.add(recipient);
-        }
-        // Case 2: Record has a recipient → check if relational read rules exist
-        if (recipient && recipient !== tenantDid) {
-            if (this.hasRelationalReadAccess('recipient', protocolPath, protocolDefinition)) {
-                participants.add(recipient);
-            }
-        }
-        // Case 3: External author → check if author-based relational read rules exist.
-        // If `{ who: 'author', of: '<path>', can: ['read'] }` is defined anywhere
-        // in the protocol, the external author needs a context key to decrypt.
-        if (authorDid && authorDid !== tenantDid) {
-            if (this.hasRelationalReadAccess('author', protocolPath, protocolDefinition)) {
-                participants.add(authorDid);
-            }
-        }
-        // Remove the DWN owner — they always have ProtocolPath access
-        participants.delete(tenantDid);
-        return participants;
-    }
     /**
      * Fetches a protocol definition from a remote DWN.
      * Uses an unsigned ProtocolsQuery (public protocols can be queried anonymously).
@@ -1077,252 +808,15 @@ export class AgentDwnApi {
             return undefined;
         });
     }
-    /**
-     * Reactively upgrades an externally-authored root record that has only
-     * ProtocolPath encryption by appending a ProtocolContext recipient entry.
-     *
-     * After the upgrade, both the owner (ProtocolPath) and context key holders —
-     * including the external author (ProtocolContext) — can decrypt the record.
-     *
-     * Steps:
-     *   1. Decrypt the DEK using the owner's ProtocolPath-derived private key
-     *   2. Derive the context public key from the owner's #enc key
-     *   3. ECIES-encrypt the same DEK to the context public key
-     *   4. Append the ProtocolContext recipient entry (using PR 0b append mode)
-     *   5. Re-sign the record as owner
-     *
-     * The author's signature payload includes an `encryptionCid` that becomes
-     * stale after step 4. The SDK's `validateIntegrity()` skips the encryptionCid
-     * check on the author's signature when an ownerSignature is present (step 5),
-     * since the owner vouches for the updated encryption property.
-     *
-     * NOTE: An alternative design would deliver the DEK out-of-band via the
-     * key-delivery protocol (as a field on the contextKey record) instead of
-     * mutating the record's encryption property. That avoids the stale
-     * encryptionCid concern entirely but adds complexity to the read path and
-     * the contextKey schema. We chose the in-record approach because it keeps
-     * records self-contained and the read/decrypt path unchanged.
-     *
-     * @param tenantDid     - The DWN owner's DID
-     * @param recordsWrite  - The RecordsWrite message to upgrade
-     */
-    upgradeExternalRootRecord(tenantDid, recordsWrite) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const { encryption } = recordsWrite;
-            if (!encryption) {
-                return;
-            }
-            // Verify: has ProtocolPath but NOT ProtocolContext
-            const hasProtocolPath = encryption.recipients.some((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolPath);
-            const hasProtocolContext = encryption.recipients.some((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolContext);
-            if (!hasProtocolPath || hasProtocolContext) {
-                return;
-            }
-            // 1. Decrypt the DEK using the owner's ProtocolPath key
-            const keyDecrypter = yield this.getKeyDecrypter(tenantDid);
-            // Find the ProtocolPath recipient entry
-            const pathRecipient = encryption.recipients.find((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolPath);
-            const fullDerivationPath = Records.constructKeyDerivationPathUsingProtocolPathScheme(recordsWrite.descriptor);
-            const dataEncryptionKey = yield keyDecrypter.decrypt(fullDerivationPath, {
-                encryptedKey: Encoder.base64UrlToBytes(pathRecipient.encrypted_key),
-                ephemeralPublicKey: pathRecipient.header.epk,
-            });
-            // 2. Derive the context public key — contextId = recordId for root records
-            const contextId = recordsWrite.recordId;
-            const encryptionIV = Encoder.base64UrlToBytes(encryption.iv);
-            // 3 & 4. Append the ProtocolContext recipient entry using append mode.
-            // Append mode preserves the author's identity and authorization so that
-            // signAsOwner() can be called in step 5.
-            const { encryptionInput: contextEncryptionInput, keyId, keyUri, contextDerivationPath } = yield this.deriveContextEncryptionInput(tenantDid, contextId, dataEncryptionKey, encryptionIV);
-            // Set the authentication tag from the existing JWE encryption property
-            const fullContextInput = Object.assign(Object.assign({}, contextEncryptionInput), { authenticationTag: Encoder.base64UrlToBytes(encryption.tag) });
-            // Parse the message to get a RecordsWrite instance we can mutate
-            const recordsWriteInstance = yield dwnMessageConstructors[DwnInterface.RecordsWrite].parse(recordsWrite);
-            yield recordsWriteInstance.encryptSymmetricEncryptionKey(fullContextInput, { append: true });
-            // 5. Re-sign as owner — the author's signature is preserved but its
-            // encryptionCid is now stale; the owner's signature vouches for the
-            // updated encryption property.
-            const signer = yield this.getSigner(tenantDid);
-            yield recordsWriteInstance.signAsOwner(signer);
-            // Store the upgraded message directly via the message store, bypassing
-            // the handler's conflict resolution which doesn't support same-timestamp
-            // owner-augmented replacements. The data is unchanged — only the encryption
-            // metadata and authorization are updated.
-            //
-            // We must also update the state index and event stream to keep sync and
-            // real-time subscribers consistent — without this, the upgraded record
-            // would never propagate to remote DWNs or notify subscribers.
-            const { messageStore, stateIndex, eventStream } = this._dwn.storage;
-            // Validate the upgrade only changed encryption and authorization fields.
-            // The descriptor, recordId, contextId, and data must remain identical.
-            // Note: parse() may produce a new descriptor object, so we compare by value.
-            const upgradedMessage = recordsWriteInstance.message;
-            if (JSON.stringify(upgradedMessage.descriptor) !== JSON.stringify(recordsWrite.descriptor)) {
-                throw new Error('AgentDwnApi: upgradeExternalRootRecord() must not modify the descriptor.');
-            }
-            if (upgradedMessage.recordId !== recordsWrite.recordId) {
-                throw new Error('AgentDwnApi: upgradeExternalRootRecord() must not modify the recordId.');
-            }
-            // Fetch the stored original (which carries encodedData for small payloads)
-            const originalCid = yield Message.getCid(recordsWrite);
-            const storedOriginal = yield messageStore.get(tenantDid, originalCid);
-            // Build indexes for the upgraded message (mark as latest base state)
-            const isLatestBaseState = true;
-            const upgradedIndexes = yield recordsWriteInstance.constructIndexes(isLatestBaseState);
-            // Carry over the encoded data from the stored original (the handler
-            // base64url-encodes small payloads into encodedData during processMessage)
-            if (storedOriginal === null || storedOriginal === void 0 ? void 0 : storedOriginal.encodedData) {
-                upgradedMessage.encodedData = storedOriginal.encodedData;
-            }
-            // Use put-before-delete ordering: if a crash occurs after the put but
-            // before the delete, we end up with a duplicate (recoverable via the
-            // isLatestBaseState index) rather than data loss (unrecoverable).
-            const upgradedCid = yield Message.getCid(upgradedMessage);
-            yield messageStore.put(tenantDid, upgradedMessage, upgradedIndexes);
-            yield stateIndex.insert(tenantDid, upgradedCid, upgradedIndexes);
-            // Now remove the original message and its state index entry.
-            yield messageStore.delete(tenantDid, originalCid);
-            yield stateIndex.delete(tenantDid, [originalCid]);
-            // Notify real-time subscribers (mirrors handler behavior)
-            if (eventStream !== undefined) {
-                eventStream.emit(tenantDid, { message: upgradedMessage }, upgradedIndexes);
-            }
-            // Cache context key info for subsequent writes in this context
-            this._contextKeyCache.set(contextId, { keyId, keyUri, contextDerivationPath });
-        });
-    }
-    /**
-     * Resolves the appropriate KeyDecrypter for a record's encryption scheme.
-     * Handles both single-party (ProtocolPath) and multi-party (ProtocolContext).
-     *
-     * For ProtocolContext records:
-     *   - Context creator: derives key directly from KMS
-     *   - Participant: fetches contextKey via key-delivery protocol, caches it
-     */
-    resolveKeyDecrypter(authorDid, recordsWrite, targetDid) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const { encryption } = recordsWrite;
-            // Check if the record uses context-derived encryption
-            const hasContextKey = encryption === null || encryption === void 0 ? void 0 : encryption.recipients.some((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolContext);
-            if (!hasContextKey || !recordsWrite.contextId) {
-                // Single-party protocol-path encryption
-                return this.getKeyDecrypter(authorDid);
-            }
-            // --- Multi-party context encryption ---
-            const contextKeyEntry = encryption.recipients.find((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolContext);
-            const rootContextId = recordsWrite.contextId.split('/')[0];
-            // Case 1: I am the context creator — rootKeyId matches my encryption key
-            const { keyId, keyUri } = yield this.getEncryptionKeyInfo(authorDid);
-            if (contextKeyEntry.header.kid === keyId) {
-                return this.buildKmsDecryptCallback(keyId, keyUri, KeyDerivationScheme.ProtocolContext);
-            }
-            // Case 2: I am a participant — fetch my context key from the key-delivery protocol
-            const cacheKey = `ctx~${authorDid}~${rootContextId}`;
-            const cached = this._contextDerivedKeyCache.get(cacheKey);
-            if (cached) {
-                return this.buildContextKeyDecrypter(cached);
-            }
-            // Fetch context key via the key-delivery protocol — local first, then remote
-            const protocol = recordsWrite.descriptor.protocol;
-            // Try local: I may be the DWN owner with a contextKey addressed to myself
-            let contextDerivedPrivateKey = yield this.fetchContextKeyRecord({
-                ownerDid: authorDid,
-                requesterDid: authorDid,
-                sourceProtocol: protocol,
-                sourceContextId: rootContextId,
-            });
-            // Try remote: query the DWN owner's DWN for my contextKey record.
-            // For cross-DWN records, targetDid is the DWN owner (e.g., Alice) where the
-            // contextKey was written. For same-DWN records, fall back to the record's
-            // authorization signer.
-            if (!contextDerivedPrivateKey) {
-                const contextOwnerDid = targetDid !== null && targetDid !== void 0 ? targetDid : Jws.getSignerDid(recordsWrite.authorization.signature.signatures[0]);
-                contextDerivedPrivateKey = yield this.fetchContextKeyRecord({
-                    ownerDid: contextOwnerDid,
-                    requesterDid: authorDid,
-                    sourceProtocol: protocol,
-                    sourceContextId: rootContextId,
-                });
-            }
-            if (!contextDerivedPrivateKey) {
-                throw new Error(`AgentDwnApi: Failed to decrypt record '${recordsWrite.recordId}'. ` +
-                    `Record uses context-derived encryption but no contextKey record ` +
-                    `could be found via the key-delivery protocol.`);
-            }
-            this._contextDerivedKeyCache.set(cacheKey, contextDerivedPrivateKey);
-            return this.buildContextKeyDecrypter(contextDerivedPrivateKey);
-        });
-    }
-    /**
-     * Builds a KeyDecrypter from a context-derived private key.
-     * Uses the raw key directly (since it was shared with us via the key-delivery protocol).
-     */
-    buildContextKeyDecrypter(contextKey) {
-        return {
-            rootKeyId: contextKey.rootKeyId,
-            derivationScheme: contextKey.derivationScheme,
-            decrypt: (fullDerivationPath, jwePayload) => __awaiter(this, void 0, void 0, function* () {
-                const leafPrivateKeyBytes = yield Records.derivePrivateKey(contextKey, fullDerivationPath);
-                const leafPrivateKeyJwk = yield X25519.bytesToPrivateKey({ privateKeyBytes: leafPrivateKeyBytes });
-                return Encryption.ecdhEsUnwrapKey(leafPrivateKeyJwk, jwePayload.ephemeralPublicKey, jwePayload.encryptedKey);
-            }),
-        };
-    }
     /**
      * Post-processes a DWN reply, auto-decrypting data if encryption is enabled.
-     * Delegates to the SDK's Records.decrypt() with the appropriate KeyDecrypter —
-     * resolveKeyDecrypter() selects between ProtocolPath and ProtocolContext schemes.
+     * Delegates to the standalone function in `dwn-encryption.ts`.
      */
     maybeDecryptReply(request, reply) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
-            if (!('encryption' in request) || !request.encryption) {
-                return;
-            }
-            // Auto-decrypt RecordsRead replies
-            if (isDwnRequest(request, DwnInterface.RecordsRead)) {
-                const readReply = reply;
-                if (readReply.status.code === 200
-                    && ((_b = (_a = readReply.entry) === null || _a === void 0 ? void 0 : _a.recordsWrite) === null || _b === void 0 ? void 0 : _b.encryption)
-                    && ((_c = readReply.entry) === null || _c === void 0 ? void 0 : _c.data)) {
-                    const keyDecrypter = yield this.resolveKeyDecrypter(request.author, readReply.entry.recordsWrite, request.target);
-                    try {
-                        readReply.entry.data = yield Records.decrypt(readReply.entry.recordsWrite, keyDecrypter, readReply.entry.data);
-                    }
-                    catch (error) {
-                        throw new Error(`AgentDwnApi: Failed to decrypt record ` +
-                            `'${readReply.entry.recordsWrite.recordId}'. ` +
-                            `Original error: ${error.message}`);
-                    }
-                }
-            }
-            // Auto-decrypt RecordsQuery replies (small records inline as encodedData)
-            if (isDwnRequest(request, DwnInterface.RecordsQuery)) {
-                const queryReply = reply;
-                if (queryReply.status.code === 200 && queryReply.entries) {
-                    for (const entry of queryReply.entries) {
-                        if (entry.encryption && entry.encodedData) {
-                            const keyDecrypter = yield this.resolveKeyDecrypter(request.author, entry, request.target);
-                            try {
-                                const cipherBytes = Encoder.base64UrlToBytes(entry.encodedData);
-                                const cipherStream = DataStream.fromBytes(cipherBytes);
-                                const plainStream = yield Records.decrypt(entry, keyDecrypter, cipherStream);
-                                const plainBytes = yield DataStream.toBytes(plainStream);
-                                entry.encodedData = Encoder.bytesToBase64Url(plainBytes);
-                            }
-                            catch (error) {
-                                throw new Error(`AgentDwnApi: Failed to decrypt record ` +
-                                    `'${entry.recordId}'. Original error: ${error.message}`);
-                            }
-                        }
-                    }
-                }
-            }
+            return maybeDecryptReplyFn(request, reply, this.agent, this._contextDerivedKeyCache, this.fetchContextKeyRecord.bind(this));
         });
     }
-    /**
-     * FURTHER REFACTORING NEEDED BELOW THIS LINE
-     */
     getDwnMessage(_a) {
         return __awaiter(this, arguments, void 0, function* ({ author, messageCid }) {
             const signer = yield this.getSigner(author);
@@ -1348,119 +842,25 @@ export class AgentDwnApi {
     }
     /**
      * Ensures the key delivery protocol is installed on the given tenant's DWN,
-     * with `$encryption` keys injected. Uses the same lazy initialization pattern
-     * as `DwnDataStore.initialize()`.
+     * with `$encryption` keys injected.
      *
      * @param tenantDid - The DID of the DWN owner
      */
     ensureKeyDeliveryProtocol(tenantDid) {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this._keyDeliveryProtocolInstalledCache.get(tenantDid)) {
-                return;
-            }
-            const protocolUri = KeyDeliveryProtocolDefinition.protocol;
-            const existing = yield this.getProtocolDefinition(tenantDid, protocolUri);
-            if (!existing) {
-                // Derive and inject $encryption keys for each type path
-                const keyDeriver = yield this.getEncryptionKeyDeriver(tenantDid);
-                const definitionWithKeys = yield Protocols.deriveAndInjectPublicEncryptionKeys(KeyDeliveryProtocolDefinition, keyDeriver);
-                const { reply: { status } } = yield this.processRequest({
-                    author: tenantDid,
-                    target: tenantDid,
-                    messageType: DwnInterface.ProtocolsConfigure,
-                    messageParams: { definition: definitionWithKeys },
-                });
-                if (status.code !== 202) {
-                    throw new Error(`AgentDwnApi: Failed to install key delivery protocol: ${status.code} - ${status.detail}`);
-                }
-                // Invalidate protocol definition cache so subsequent reads pick up the new definition
-                this._protocolDefinitionCache.delete(`${tenantDid}~${protocolUri}`);
-            }
-            this._keyDeliveryProtocolInstalledCache.set(tenantDid, true);
+            return ensureKeyDeliveryProtocolFn(this.agent, tenantDid, this.processRequest.bind(this), this.getProtocolDefinition.bind(this), this._keyDeliveryProtocolInstalledCache, this._protocolDefinitionCache);
         });
     }
     /**
      * Writes a `contextKey` record to the owner's DWN, delivering an encrypted
      * context key to a participant.
      *
-     * The payload is encrypted to the **recipient's** ProtocolPath-derived public
-     * key on the key-delivery protocol, so only the recipient can decrypt it.
-     * The recipient's key is supplied via `recipientKeyDeliveryPublicKey` (which
-     * the external author attached as `authorKeyDeliveryPublicKey` on the
-     * original cross-DWN record).
-     *
-     * When `recipientKeyDeliveryPublicKey` is not provided (e.g. the owner is
-     * writing a contextKey for themselves), the record is encrypted to the
-     * owner's own ProtocolPath key using the generic `processRequest` path.
-     *
-     * @param params.tenantDid      - The DWN owner's DID (who is delivering the key)
-     * @param params.recipientDid   - The participant's DID (who will receive the key)
-     * @param params.contextKeyData - The `DerivedPrivateJwk` to deliver
-     * @param params.sourceProtocol - The URI of the source protocol (tag)
-     * @param params.sourceContextId - The root context ID (tag)
-     * @param params.recipientKeyDeliveryPublicKey - The recipient's ProtocolPath-
-     *        derived public key for `key-delivery/contextKey`. When provided,
-     *        the contextKey record is encrypted directly to this key.
+     * @param params - The write parameters
      * @returns The recordId of the written contextKey record
      */
-    writeContextKeyRecord(_a) {
-        return __awaiter(this, arguments, void 0, function* ({ tenantDid, recipientDid, contextKeyData, sourceProtocol, sourceContextId, recipientKeyDeliveryPublicKey }) {
-            // Ensure the key delivery protocol is installed on the owner's DWN
-            yield this.ensureKeyDeliveryProtocol(tenantDid);
-            const protocolUri = KeyDeliveryProtocolDefinition.protocol;
-            // Serialize the payload to JSON bytes
-            const plaintextBytes = new TextEncoder().encode(JSON.stringify(contextKeyData));
-            // Common contextKey record parameters
-            const contextKeyParams = {
-                protocol: protocolUri,
-                protocolPath: 'contextKey',
-                dataFormat: 'application/json',
-                recipient: recipientDid,
-                tags: { protocol: sourceProtocol, contextId: sourceContextId },
-            };
-            let message;
-            let status;
-            if (recipientKeyDeliveryPublicKey) {
-                // --- Encrypt to the recipient's ProtocolPath key (cross-DWN delivery) ---
-                // Manually build encryption input targeting the recipient's key so the
-                // record is decryptable only by the recipient.
-                const algorithm = ContentEncryptionAlgorithm.A256GCM;
-                const dataEncryptionKey = crypto.getRandomValues(new Uint8Array(32));
-                const dataEncryptionIV = crypto.getRandomValues(new Uint8Array(AgentDwnApi.ivLength(algorithm)));
-                const { encryptedBytes, dataCid, dataSize, authenticationTag } = yield this.encryptAndComputeCid(plaintextBytes, dataEncryptionKey, dataEncryptionIV, algorithm);
-                const encryptionInput = Object.assign(Object.assign({}, this.buildEncryptionInput(dataEncryptionKey, dataEncryptionIV, recipientKeyDeliveryPublicKey.rootKeyId, recipientKeyDeliveryPublicKey.publicKeyJwk, KeyDerivationScheme.ProtocolPath)), { authenticationTag });
-                ({ message, reply: { status } } = yield this.processRequest({
-                    author: tenantDid,
-                    target: tenantDid,
-                    messageType: DwnInterface.RecordsWrite,
-                    messageParams: Object.assign(Object.assign({}, contextKeyParams), { dataCid, dataSize, encryptionInput }),
-                    dataStream: new Blob([encryptedBytes]),
-                }));
-            }
-            else {
-                // --- Fallback: encrypt to the owner's key (local self-delivery) ---
-                // When no recipient key is provided, use the generic processRequest
-                // encryption path which encrypts to the DWN owner's ProtocolPath key.
-                ({ message, reply: { status } } = yield this.processRequest({
-                    author: tenantDid,
-                    target: tenantDid,
-                    messageType: DwnInterface.RecordsWrite,
-                    messageParams: contextKeyParams,
-                    dataStream: new Blob([plaintextBytes], { type: 'application/json' }),
-                    encryption: true,
-                }));
-            }
-            if (!(message && status.code === 202)) {
-                throw new Error(`AgentDwnApi: Failed to write contextKey record for ${recipientDid}: ${status.code} - ${status.detail}`);
-            }
-            // Eagerly send the contextKey record to the tenant's remote DWN so that
-            // participants can fetch it immediately without waiting for sync.
-            // This is fire-and-forget — sync will guarantee eventual consistency.
-            this.eagerSendContextKeyRecord(tenantDid, message).catch((err) => {
-                console.warn(`AgentDwnApi: Eager send of contextKey record '${message.recordId}' ` +
-                    `to remote DWN failed: ${err.message}. Sync will deliver it later.`);
-            });
-            return message.recordId;
+    writeContextKeyRecord(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return writeContextKeyRecordFn(this.agent, params, this.processRequest.bind(this), this.ensureKeyDeliveryProtocol.bind(this), this.eagerSendContextKeyRecord.bind(this));
         });
     }
     /**
@@ -1469,119 +869,19 @@ export class AgentDwnApi {
      */
     eagerSendContextKeyRecord(tenantDid, contextKeyMessage) {
         return __awaiter(this, void 0, void 0, function* () {
-            let dwnEndpointUrls;
-            try {
-                dwnEndpointUrls = yield getDwnServiceEndpointUrls(tenantDid, this.agent.did);
-            }
-            catch (_a) {
-                // DID resolution or endpoint lookup failed — not fatal, sync will handle it.
-                return;
-            }
-            if (dwnEndpointUrls.length === 0) {
-                return;
-            }
-            // Read the full message (including data blob) from the local DWN
-            const { data } = yield this.getDwnMessage({
-                author: tenantDid,
-                messageType: DwnInterface.RecordsWrite,
-                messageCid: yield Message.getCid(contextKeyMessage),
-            });
-            yield this.sendDwnRpcRequest({
-                targetDid: tenantDid,
-                dwnEndpointUrls,
-                message: contextKeyMessage,
-                data,
-            });
+            return eagerSendContextKeyRecordFn(this.agent, tenantDid, contextKeyMessage, this.getDwnMessage.bind(this), this.sendDwnRpcRequest.bind(this));
         });
     }
     /**
      * Fetches and decrypts a `contextKey` record from a DWN, returning the
      * `DerivedPrivateJwk` payload.
      *
-     * Supports both local reads (tenant queries own DWN) and remote reads
-     * (participant queries the context owner's DWN).
-     *
-     * @param params.ownerDid       - The DWN owner's DID (where contextKey records live)
-     * @param params.requesterDid   - The DID of the requester (used for signing and decryption)
-     * @param params.sourceProtocol - The URI of the source protocol (tag filter)
-     * @param params.sourceContextId - The root context ID (tag filter)
+     * @param params - The fetch parameters
      * @returns The decrypted `DerivedPrivateJwk`, or `undefined` if no matching record found
      */
-    fetchContextKeyRecord(_a) {
-        return __awaiter(this, arguments, void 0, function* ({ ownerDid, requesterDid, sourceProtocol, sourceContextId }) {
-            var _b, _c, _d, _e, _f;
-            const protocolUri = KeyDeliveryProtocolDefinition.protocol;
-            const isLocal = ownerDid === requesterDid;
-            // Shared query filter for both local and remote paths
-            const contextKeyFilter = {
-                protocol: protocolUri,
-                protocolPath: 'contextKey',
-                recipient: requesterDid,
-                tags: { protocol: sourceProtocol, contextId: sourceContextId },
-            };
-            /** Parse decrypted bytes into a DerivedPrivateJwk. */
-            const parsePayload = (bytes) => JSON.parse(new TextDecoder().decode(bytes));
-            if (isLocal) {
-                // Local query: owner queries their own DWN
-                const { reply } = yield this.processRequest({
-                    author: requesterDid,
-                    target: ownerDid,
-                    messageType: DwnInterface.RecordsQuery,
-                    messageParams: { filter: contextKeyFilter },
-                });
-                if (reply.status.code !== 200 || !((_b = reply.entries) === null || _b === void 0 ? void 0 : _b.length)) {
-                    return undefined;
-                }
-                // Read the full record to get the data (auto-decrypted by processRequest)
-                const recordId = reply.entries[0].recordId;
-                const { reply: readReply } = yield this.processRequest({
-                    author: requesterDid,
-                    target: ownerDid,
-                    messageType: DwnInterface.RecordsRead,
-                    messageParams: { filter: { recordId } },
-                    encryption: true,
-                });
-                const readResult = readReply;
-                if (!((_c = readResult.entry) === null || _c === void 0 ? void 0 : _c.data)) {
-                    return undefined;
-                }
-                return parsePayload(yield DataStream.toBytes(readResult.entry.data));
-            }
-            else {
-                // Remote query: participant queries the context owner's DWN
-                const signer = yield this.getSigner(requesterDid);
-                const dwnEndpointUrls = yield getDwnServiceEndpointUrls(ownerDid, this.agent.did);
-                const recordsQuery = yield dwnMessageConstructors[DwnInterface.RecordsQuery].create({
-                    signer,
-                    filter: contextKeyFilter,
-                });
-                const queryReply = yield this.sendDwnRpcRequest({
-                    targetDid: ownerDid,
-                    dwnEndpointUrls,
-                    message: recordsQuery.message,
-                });
-                if (queryReply.status.code !== 200 || !((_d = queryReply.entries) === null || _d === void 0 ? void 0 : _d.length)) {
-                    return undefined;
-                }
-                // Read the full record remotely
-                const recordId = queryReply.entries[0].recordId;
-                const recordsRead = yield dwnMessageConstructors[DwnInterface.RecordsRead].create({
-                    signer,
-                    filter: { recordId },
-                });
-                const readReply = yield this.sendDwnRpcRequest({
-                    targetDid: ownerDid,
-                    dwnEndpointUrls,
-                    message: recordsRead.message,
-                });
-                if (!((_e = readReply.entry) === null || _e === void 0 ? void 0 : _e.data) || !((_f = readReply.entry) === null || _f === void 0 ? void 0 : _f.recordsWrite)) {
-                    return undefined;
-                }
-                // Decrypt the contextKey payload using the requester's key-delivery protocol path key
-                const keyDecrypter = yield this.getKeyDecrypter(requesterDid);
-                const decryptedStream = yield Records.decrypt(readReply.entry.recordsWrite, keyDecrypter, readReply.entry.data);
-                return parsePayload(yield DataStream.toBytes(decryptedStream));
-            }
+    fetchContextKeyRecord(params) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return fetchContextKeyRecordFn(this.agent, params, this.processRequest.bind(this), this.getSigner.bind(this), this.sendDwnRpcRequest.bind(this));
         });
     }
 }