@enbox/agent 0.5.16 → 0.6.1

package/dist/esm/dwn-api.js

@@ -7,10 +7,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { TtlCache } from '@enbox/common';
 import { Cid, ContentEncryptionAlgorithm, DataStoreLevel, DataStream, Dwn, DwnMethodName, EventEmitterEventLog, Jws, KeyDerivationScheme, Message, MessageStoreLevel, Protocols, Records, ResumableTaskStoreLevel, StateIndexLevel, } from '@enbox/dwn-sdk-js';
+import { Convert, TtlCache } from '@enbox/common';
 import { CryptoUtils, X25519 } from '@enbox/crypto';
 import { DidDht, DidJwk, DidResolverCacheLevel, UniversalResolver } from '@enbox/dids';
+import { AgentPermissionsApi } from './permissions-api.js';
 import { DwnDiscoveryFile } from './dwn-discovery-file.js';
 import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
 import { LocalDwnDiscovery } from './local-dwn.js';
@@ -53,6 +54,41 @@ export class AgentDwnApi {
         this._contextDerivedKeyCache = new TtlCache({
             ttl: 30 * 60 * 1000
         });
+        /**
+         * Delegate decryption key cache — stores scope-aware decryption keys
+         * delivered to delegates during the connect flow. These keys enable
+         * delegates to decrypt encrypted records without possessing the owner's
+         * root X25519 private key.
+         *
+         * Keyed by `ddk~${delegateDid}`. Each entry is an array covering all
+         * granted read scopes for that delegate session.
+         * TTL 24 hours (keys are re-populated on session restore).
+         */
+        this._delegateDecryptionKeyCache = new TtlCache({
+            ttl: 24 * 60 * 60 * 1000
+        });
+        /**
+         * Delegate context key cache — stores ProtocolContext decryption keys for
+         * multi-party encrypted protocols. Each key is scoped to one rootContextId.
+         * Keyed by `dctx~${delegateDid}~${protocol}~${rootContextId}`.
+         * TTL 24 hours (re-populated on session restore).
+         */
+        this._delegateContextKeyCache = new TtlCache({
+            ttl: 24 * 60 * 60 * 1000
+        });
+        /** Tracks which context key cache entries belong to which delegate DID. */
+        this._delegateContextKeyCacheIndex = new Map();
+        /**
+         * Explicit registry of which multi-party protocols each delegate has
+         * protocol-wide read-like access to. Populated at connect time (even
+         * when zero contexts exist) and used by postWriteKeyDelivery() to
+         * decide whether to deliver new context keys.
+         *
+         * Keyed by delegateDid. Each entry is a Set of protocol URIs.
+         * Unlike the context key cache, this registry is NOT time-limited —
+         * it persists for the lifetime of the session.
+         */
+        this._delegateMultiPartyProtocols = new Map();
         /**
          * Cache of locally-managed DIDs (agent DID + identities). Used to decide
          * whether a target DID should be routed through the local DWN server.
@@ -174,6 +210,16 @@ export class AgentDwnApi {
             return [...uniqueEndpoints];
         });
     }
+    /**
+     * Returns only the DWN service endpoints from the DID document (no local
+     * discovery endpoint). Use this when you need to confirm that a message
+     * reached the owner's actual remote DWN, not just the delegate's local server.
+     */
+    getRemoteDwnEndpointUrls(targetDid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return getDwnServiceEndpointUrls(targetDid, this.agent.did);
+        });
+    }
     /** Lazily retrieves the local DWN server endpoint via discovery. */
     getLocalDwnEndpoint() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -490,11 +536,17 @@ export class AgentDwnApi {
                     tenantDid: request.target,
                     authorDid: isExternallyAuthored ? authorDid : undefined,
                 });
-                if (newParticipants.size > 0) {
-                    // Derive the context key to deliver to participants
-                    const rootContextId = ((_a = recordsWriteMessage.contextId) === null || _a === void 0 ? void 0 : _a.split('/')[0])
-                        || recordsWriteMessage.contextId
-                        || recordsWriteMessage.recordId;
+                // Compute rootContextId for both participant and delegate delivery.
+                const rootContextId = ((_a = recordsWriteMessage.contextId) === null || _a === void 0 ? void 0 : _a.split('/')[0])
+                    || recordsWriteMessage.contextId
+                    || recordsWriteMessage.recordId;
+                // Determine if delegate delivery is needed: new multi-party root
+                // record created by the owner with active delegate sessions.
+                const needsDelegateDelivery = isMultiParty && isRootRecord
+                    && !isExternallyAuthored
+                    && this.hasEligibleDelegatesForProtocol(writeParams.protocol);
+                if (newParticipants.size > 0 || needsDelegateDelivery) {
+                    // Derive the context key once (shared for participant + delegate delivery).
                     const { keyId, keyUri } = yield getEncryptionKeyInfoFn(this.agent, request.target);
                     const contextDerivationPath = [
                         KeyDerivationScheme.ProtocolContext,
@@ -511,32 +563,66 @@ export class AgentDwnApi {
                         derivationPath: contextDerivationPath,
                         derivedPrivateKey: contextDerivedPrivateJwk,
                     };
-                    // Extract the author's key delivery public key from the record
-                    // so we can encrypt the contextKey directly to the external author.
-                    const authorKeyDeliveryPubKey = (_b = recordsWriteMessage.authorization) === null || _b === void 0 ? void 0 : _b.authorKeyDeliveryPublicKey;
-                    for (const participantDid of newParticipants) {
-                        try {
-                            // Use the author's key delivery public key when delivering
-                            // to the external author; for other participants (e.g.
-                            // recipient, role holders) fall back to owner-key encryption.
-                            const recipientKey = (participantDid === authorDid && authorKeyDeliveryPubKey)
-                                ? authorKeyDeliveryPubKey
-                                : undefined;
-                            yield this.writeContextKeyRecord({
-                                tenantDid: request.target,
-                                recipientDid: participantDid,
-                                contextKeyData: contextKeyPayload,
-                                sourceProtocol: writeParams.protocol,
-                                sourceContextId: rootContextId,
-                                recipientKeyDeliveryPublicKey: recipientKey,
-                            });
-                        }
-                        catch (keyDeliveryError) {
-                            console.warn(`AgentDwnApi: Key delivery to '${participantDid}' for context ` +
-                                `'${rootContextId}' failed: ${keyDeliveryError.message}. ` +
-                                `The participant may not be able to decrypt records in this context.`);
+                    // --- Participant key delivery (existing) ---
+                    if (newParticipants.size > 0) {
+                        // Extract the author's key delivery public key from the record
+                        // so we can encrypt the contextKey directly to the external author.
+                        const authorKeyDeliveryPubKey = (_b = recordsWriteMessage.authorization) === null || _b === void 0 ? void 0 : _b.authorKeyDeliveryPublicKey;
+                        for (const participantDid of newParticipants) {
+                            try {
+                                // Use the author's key delivery public key when delivering
+                                // to the external author; for other participants (e.g.
+                                // recipient, role holders) fall back to owner-key encryption.
+                                const recipientKey = (participantDid === authorDid && authorKeyDeliveryPubKey)
+                                    ? authorKeyDeliveryPubKey
+                                    : undefined;
+                                yield this.writeContextKeyRecord({
+                                    tenantDid: request.target,
+                                    recipientDid: participantDid,
+                                    contextKeyData: contextKeyPayload,
+                                    sourceProtocol: writeParams.protocol,
+                                    sourceContextId: rootContextId,
+                                    recipientKeyDeliveryPublicKey: recipientKey,
+                                });
+                            }
+                            catch (keyDeliveryError) {
+                                console.warn(`AgentDwnApi: Key delivery to '${participantDid}' for context ` +
+                                    `'${rootContextId}' failed: ${keyDeliveryError.message}. ` +
+                                    `The participant may not be able to decrypt records in this context.`);
+                            }
                         }
                     }
+                    // --- Post-connect delegate context key delivery (#824) ---
+                    // Same-process: direct cache injection (fast, no network).
+                    if (needsDelegateDelivery) {
+                        this.deliverContextKeyToDelegates(writeParams.protocol, rootContextId, contextKeyPayload);
+                    }
+                }
+                // --- Cross-device delegate context key delivery (#826) ---
+                // Query grants to find ALL eligible delegates (including those on
+                // other agents) and write contextKey records to the DWN.
+                // This is separate from same-process delivery: it discovers delegates
+                // from the owner's DWN grants, not just in-memory caches. It must
+                // run even when no same-process delegates or participants exist.
+                if (isMultiParty && isRootRecord && !isExternallyAuthored) {
+                    // Derive the context key if not already done above.
+                    const { keyId: xdKeyId, keyUri: xdKeyUri } = yield getEncryptionKeyInfoFn(this.agent, request.target);
+                    const xdContextDerivationPath = [
+                        KeyDerivationScheme.ProtocolContext,
+                        rootContextId,
+                    ];
+                    const xdContextDerivedPrivateKeyBytes = yield this.agent.keyManager.derivePrivateKeyBytes({
+                        keyUri: xdKeyUri,
+                        derivationPath: xdContextDerivationPath,
+                    });
+                    const xdContextDerivedPrivateJwk = yield X25519.bytesToPrivateKey({ privateKeyBytes: xdContextDerivedPrivateKeyBytes });
+                    const xdContextKeyPayload = {
+                        rootKeyId: xdKeyId,
+                        derivationScheme: KeyDerivationScheme.ProtocolContext,
+                        derivationPath: xdContextDerivationPath,
+                        derivedPrivateKey: xdContextDerivedPrivateJwk,
+                    };
+                    yield this.deliverContextKeyToDelegatesViaDwn(request.target, writeParams.protocol, rootContextId, xdContextKeyPayload);
                 }
             }
             catch (detectionError) {
@@ -596,6 +682,7 @@ export class AgentDwnApi {
     }
     constructDwnMessage(_a) {
         return __awaiter(this, arguments, void 0, function* ({ request }) {
+            var _b, _c, _d;
             // if the request has a granteeDid, ensure the messageParams include the proper grant parameters
             if (request.granteeDid && !this.hasGrantParams(request.messageParams)) {
                 throw new Error('AgentDwnApi: Requested to sign with a permission but no grant messageParams were provided in the request');
@@ -642,6 +729,19 @@ export class AgentDwnApi {
                 // Invalidate cache for this protocol
                 this._protocolDefinitionCache.delete(`${request.target}~${messageParams.definition.protocol}`);
             }
+            // When a ProtocolsConfigure is processed WITHOUT the encryption flag
+            // (e.g. a delegate installing the owner's protocol definition that
+            // already contains `$encryption` keys from the remote DWN), cache the
+            // definition so that subsequent RecordsWrite encryption can find it
+            // without re-querying the local DWN (which would fail for delegates
+            // because the query author doesn't match the unpublished protocol's
+            // tenant).
+            if (isDwnRequest(request, DwnInterface.ProtocolsConfigure) && !request.encryption && !rawMessage) {
+                const def = (_b = request.messageParams) === null || _b === void 0 ? void 0 : _b.definition;
+                if (def === null || def === void 0 ? void 0 : def.protocol) {
+                    this._protocolDefinitionCache.set(`${request.target}~${def.protocol}`, def);
+                }
+            }
             // Auto-encrypt data on RecordsWrite.
             //
             // Encryption scheme decision (unified key delivery):
@@ -680,7 +780,7 @@ export class AgentDwnApi {
                         protocolDefinition = yield this.fetchRemoteProtocolDefinition(request.target, messageParams.protocol);
                     }
                     else {
-                        protocolDefinition = yield this.getProtocolDefinition(request.target, messageParams.protocol);
+                        protocolDefinition = yield this.getProtocolDefinition(request.target, messageParams.protocol, request.granteeDid);
                     }
                     if (!protocolDefinition) {
                         throw new Error(`AgentDwnApi: Protocol '${messageParams.protocol}' is not installed ` +
@@ -832,7 +932,29 @@ export class AgentDwnApi {
                 const signer = request.granteeDid ?
                     yield this.getSigner(request.granteeDid) :
                     yield this.getSigner(request.author);
-                dwnMessage = yield dwnMessageConstructor.create(Object.assign(Object.assign({}, request.messageParams), { signer }));
+                // When signing as a delegate with a permissionGrantId, fetch the full
+                // grant message and pass it as `delegatedGrant` so the DWN SDK correctly
+                // sets `authorization.authorDelegatedGrant` and resolves the logical
+                // author to the grantor (owner) rather than the signer (delegate).
+                const params = Object.assign({}, request.messageParams);
+                if (request.granteeDid && params.permissionGrantId && !params.delegatedGrant
+                    && isDwnRequest(request, DwnInterface.RecordsWrite)) {
+                    // Read as the grantee (delegate), not the owner. The delegate is
+                    // the grant's recipient so the permissions protocol authorizes the
+                    // read. The owner's signing key may not be available on the
+                    // delegate agent in real wallet-connect flows.
+                    const { reply: grantReply } = yield this.processRequest({
+                        author: request.granteeDid,
+                        target: request.author,
+                        messageType: DwnInterface.RecordsRead,
+                        messageParams: { filter: { recordId: params.permissionGrantId } },
+                    });
+                    if (grantReply.status.code === 200 && ((_c = grantReply.entry) === null || _c === void 0 ? void 0 : _c.recordsWrite) && ((_d = grantReply.entry) === null || _d === void 0 ? void 0 : _d.data)) {
+                        const grantDataBytes = yield DataStream.toBytes(grantReply.entry.data);
+                        params.delegatedGrant = Object.assign(Object.assign({}, grantReply.entry.recordsWrite), { encodedData: Convert.uint8Array(grantDataBytes).toBase64Url() });
+                    }
+                }
+                dwnMessage = yield dwnMessageConstructor.create(Object.assign(Object.assign({}, params), { 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.
@@ -977,7 +1099,7 @@ export class AgentDwnApi {
      * @param protocolUri - The protocol URI to fetch
      * @returns The protocol definition, or undefined if not found
      */
-    getProtocolDefinition(tenantDid, protocolUri) {
+    getProtocolDefinition(tenantDid, protocolUri, granteeDid) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this._dwn) {
                 // Remote mode: query via RPC (same as fetchRemoteProtocolDefinition,
@@ -998,7 +1120,26 @@ export class AgentDwnApi {
                     throw error;
                 }
             }
-            return getProtocolDefinitionFn(tenantDid, protocolUri, this._dwn, this.getSigner.bind(this), this._protocolDefinitionCache);
+            // When operating as a delegate, resolve the ProtocolsQuery grant so
+            // the local DWN authorises the query for unpublished protocols.
+            let permissionGrantId;
+            if (granteeDid) {
+                try {
+                    const permissionsApi = new AgentPermissionsApi({ agent: this.agent });
+                    const { grant } = yield permissionsApi.getPermissionForRequest({
+                        connectedDid: tenantDid,
+                        delegateDid: granteeDid,
+                        protocol: protocolUri,
+                        cached: true,
+                        messageType: DwnInterface.ProtocolsQuery,
+                    });
+                    permissionGrantId = grant.id;
+                }
+                catch (_a) {
+                    // No grant found — try without (works for published protocols).
+                }
+            }
+            return getProtocolDefinitionFn(tenantDid, protocolUri, this._dwn, this.getSigner.bind(this), this._protocolDefinitionCache, granteeDid, permissionGrantId);
         });
     }
     /**
@@ -1033,7 +1174,7 @@ export class AgentDwnApi {
      */
     maybeDecryptReply(request, reply) {
         return __awaiter(this, void 0, void 0, function* () {
-            return maybeDecryptReplyFn(request, reply, this.agent, this._contextDerivedKeyCache, this.fetchContextKeyRecord.bind(this));
+            return maybeDecryptReplyFn(request, reply, this.agent, this._contextDerivedKeyCache, this.fetchContextKeyRecord.bind(this), this._delegateDecryptionKeyCache, this._delegateContextKeyCache);
         });
     }
     getDwnMessage(_a) {
@@ -1088,6 +1229,297 @@ export class AgentDwnApi {
             return ensureKeyDeliveryProtocolFn(this.agent, tenantDid, this.processRequest.bind(this), this.getProtocolDefinition.bind(this), this._keyDeliveryProtocolInstalledCache, this._protocolDefinitionCache);
         });
     }
+    /**
+     * Imports scope-aware decryption keys for delegate sessions.
+     *
+     * Called during the connect flow when the wallet delivers decryption keys
+     * for encrypted protocols. Keys are derived only for read-like scopes
+     * (Read/Query/Subscribe) — write-only delegates receive no keys.
+     *
+     * The keys are cached and used by `resolveKeyDecrypter()` to decrypt
+     * records when the delegate does not possess the owner's root X25519
+     * private key.
+     *
+     * @param delegateDid - The delegate DID for this session (unique per connect)
+     * @param keys - Array of scope-aware decryption key entries
+     */
+    /**
+     * Sets a callback invoked whenever post-connect context keys are
+     * delivered to a delegate. The auth layer uses this to persist
+     * updated context keys so they survive restart.
+     *
+     * @param callback - Called with the delegateDid that received new keys.
+     *                   Set to `undefined` to unregister.
+     */
+    set onDelegateContextKeysChanged(callback) {
+        this._onDelegateContextKeysChanged = callback;
+    }
+    importDelegateDecryptionKeys(delegateDid, keys) {
+        const cacheKey = `ddk~${delegateDid}`;
+        this._delegateDecryptionKeyCache.set(cacheKey, keys);
+    }
+    /**
+     * Imports ProtocolContext decryption keys for multi-party encrypted protocols.
+     * Each key is scoped to one rootContextId within one protocol.
+     *
+     * @param delegateDid - The delegate DID for this session
+     * @param keys - Array of `{ protocol, contextId, derivedPrivateKey }` entries
+     */
+    importDelegateContextKeys(delegateDid, keys, multiPartyProtocols) {
+        // Clear any previously indexed entries for this delegate first,
+        // so a re-import (e.g. session restore) doesn't leave stale entries.
+        const previousKeys = this._delegateContextKeyCacheIndex.get(delegateDid);
+        if (previousKeys) {
+            for (const ck of previousKeys) {
+                this._delegateContextKeyCache.delete(ck);
+            }
+        }
+        const cacheKeys = [];
+        for (const key of keys) {
+            const ck = `dctx~${delegateDid}~${key.protocol}~${key.contextId}`;
+            this._delegateContextKeyCache.set(ck, key.derivedPrivateKey);
+            cacheKeys.push(ck);
+        }
+        this._delegateContextKeyCacheIndex.set(delegateDid, cacheKeys);
+        // Populate the explicit multi-party protocol registry.
+        // Sources: explicit parameter (always wins) + protocols from delivered keys.
+        const protocols = new Set(multiPartyProtocols !== null && multiPartyProtocols !== void 0 ? multiPartyProtocols : []);
+        for (const key of keys) {
+            protocols.add(key.protocol);
+        }
+        if (protocols.size > 0) {
+            this._delegateMultiPartyProtocols.set(delegateDid, protocols);
+        }
+        else {
+            this._delegateMultiPartyProtocols.delete(delegateDid);
+        }
+    }
+    /**
+     * Clears all delegate decryption keys (both ProtocolPath and ProtocolContext)
+     * from the in-memory cache. Called on disconnect to prevent stale keys from
+     * persisting across sessions.
+     *
+     * @param delegateDid - If provided, clears keys for that delegate session only.
+     *                      If omitted, clears all delegate keys.
+     */
+    clearDelegateDecryptionKeys(delegateDid) {
+        if (delegateDid) {
+            this._delegateDecryptionKeyCache.delete(`ddk~${delegateDid}`);
+            // Delete only context keys belonging to this delegate.
+            const cacheKeys = this._delegateContextKeyCacheIndex.get(delegateDid);
+            if (cacheKeys) {
+                for (const ck of cacheKeys) {
+                    this._delegateContextKeyCache.delete(ck);
+                }
+                this._delegateContextKeyCacheIndex.delete(delegateDid);
+            }
+            this._delegateMultiPartyProtocols.delete(delegateDid);
+        }
+        else {
+            this._delegateDecryptionKeyCache.clear();
+            this._delegateContextKeyCache.clear();
+            this._delegateContextKeyCacheIndex.clear();
+            this._delegateMultiPartyProtocols.clear();
+        }
+    }
+    /**
+     * Exports the current set of delegate context keys for a specific delegate.
+     * Returns an array of `{ protocol, contextId, derivedPrivateKey }` entries
+     * suitable for serialization and persistence.
+     *
+     * Called by the auth layer to persist context keys (including keys delivered
+     * post-connect) so they survive agent restarts.
+     *
+     * @param delegateDid - The delegate DID whose context keys to export
+     * @returns Array of context key entries (may be empty)
+     */
+    exportDelegateContextKeys(delegateDid) {
+        const cacheKeys = this._delegateContextKeyCacheIndex.get(delegateDid);
+        if (!cacheKeys) {
+            return [];
+        }
+        const result = [];
+        const prefix = `dctx~${delegateDid}~`;
+        for (const ck of cacheKeys) {
+            const key = this._delegateContextKeyCache.get(ck);
+            if (!key || !ck.startsWith(prefix)) {
+                continue;
+            }
+            // Parse protocol and contextId from cache key:
+            // format is `dctx~<delegateDid>~<protocol>~<contextId>`
+            // contextId is always the last segment; protocol is everything between.
+            const rest = ck.slice(prefix.length);
+            const lastTilde = rest.lastIndexOf('~');
+            if (lastTilde === -1) {
+                continue;
+            }
+            result.push({
+                protocol: rest.slice(0, lastTilde),
+                contextId: rest.slice(lastTilde + 1),
+                derivedPrivateKey: key,
+            });
+        }
+        return result;
+    }
+    /**
+     * Exports the registered multi-party protocol URIs for a delegate.
+     * Used by the auth layer for persistence.
+     */
+    exportDelegateMultiPartyProtocols(delegateDid) {
+        const protocols = this._delegateMultiPartyProtocols.get(delegateDid);
+        return protocols ? [...protocols] : [];
+    }
+    /**
+     * Checks whether any active delegate session has context keys for the
+     * given protocol. Used by `postWriteKeyDelivery()` to determine if
+     * delegate delivery is needed.
+     */
+    hasEligibleDelegatesForProtocol(protocol) {
+        for (const [, protocols] of this._delegateMultiPartyProtocols) {
+            if (protocols.has(protocol)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Delivers a newly created multi-party context key to all active delegate
+     * sessions that have existing context keys for the given protocol.
+     *
+     * This is same-process delivery: the context key is injected directly
+     * into `_delegateContextKeyCache`. It works when the delegate cache is
+     * on the same agent instance that creates the root record.
+     *
+     * Cross-device DWN-based delivery (where the owner's agent and the
+     * delegate's agent are separate processes) is a documented follow-up.
+     *
+     * @param protocol - The protocol URI
+     * @param rootContextId - The root context ID of the new context
+     * @param contextKey - The derived context key (`DerivedPrivateJwk`)
+     */
+    deliverContextKeyToDelegates(protocol, rootContextId, contextKey) {
+        var _a, _b;
+        for (const [delegateDid, protocols] of this._delegateMultiPartyProtocols) {
+            if (!protocols.has(protocol)) {
+                continue;
+            }
+            // Skip if this delegate already has a key for this context (idempotent).
+            const newCacheKey = `dctx~${delegateDid}~${protocol}~${rootContextId}`;
+            if (this._delegateContextKeyCache.get(newCacheKey)) {
+                continue;
+            }
+            this._delegateContextKeyCache.set(newCacheKey, contextKey);
+            const indexKeys = (_a = this._delegateContextKeyCacheIndex.get(delegateDid)) !== null && _a !== void 0 ? _a : [];
+            indexKeys.push(newCacheKey);
+            this._delegateContextKeyCacheIndex.set(delegateDid, indexKeys);
+            // Notify the auth layer so it can persist the updated keys.
+            (_b = this._onDelegateContextKeysChanged) === null || _b === void 0 ? void 0 : _b.call(this, delegateDid);
+        }
+    }
+    /**
+     * Delivers a newly created multi-party context key to eligible delegates
+     * by writing `contextKey` records to the owner's DWN via the key-delivery
+     * protocol. This enables cross-device delivery: the delegate can later
+     * fetch the record from the owner's DWN and decrypt it.
+     *
+     * Eligible delegates are discovered by querying the owner's DWN for
+     * active permission grants with read-like scopes on the given protocol.
+     *
+     * The contextKey record is encrypted using the delegate's pre-derived
+     * key-delivery leaf public key, which is stored in the grant's tags
+     * during `submitConnectResponse()`.
+     *
+     * @param tenantDid - The owner's DID
+     * @param protocol - The protocol URI
+     * @param rootContextId - The root context ID of the new context
+     * @param contextKey - The derived context key (`DerivedPrivateJwk`)
+     */
+    deliverContextKeyToDelegatesViaDwn(tenantDid, protocol, rootContextId, contextKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const permissionsApi = new AgentPermissionsApi({ agent: this.agent });
+                const grants = yield permissionsApi.fetchGrants({
+                    author: tenantDid,
+                    target: tenantDid,
+                    grantor: tenantDid,
+                    protocol,
+                    checkRevoked: true,
+                });
+                const readMethods = new Set(['Read', 'Query', 'Subscribe']);
+                const nowMs = Date.now();
+                // Deduplicate: one contextKey per delegate, not per grant.
+                // Multiple grants (Read, Query, Subscribe) for the same delegate
+                // should produce exactly one contextKey record.
+                // IMPORTANT: dedup happens AFTER tag validation so that an older
+                // untagged grant doesn't shadow a valid tagged grant for the same delegate.
+                const deliveredDelegates = new Set();
+                for (const grant of grants) {
+                    // Only delegated grants are eligible. Non-delegated grants (direct
+                    // access without a delegate session) should not trigger cross-device
+                    // context key delivery.
+                    if (!grant.grant.delegated) {
+                        continue;
+                    }
+                    // Filter expired grants. fetchGrants checks revocation but does
+                    // NOT filter by dateExpires. Use numeric comparison for safety.
+                    if (new Date(grant.grant.dateExpires).getTime() <= nowMs) {
+                        continue;
+                    }
+                    const scope = grant.grant.scope;
+                    if (scope.interface !== 'Records' || !readMethods.has(scope.method)) {
+                        continue;
+                    }
+                    // Narrow scopes (protocolPath, contextId) are not supported for
+                    // multi-party delegate delivery — skip them silently.
+                    if (scope.protocolPath || scope.contextId) {
+                        continue;
+                    }
+                    const delegateDid = grant.grant.grantee;
+                    // Read the pre-derived key-delivery leaf public key from the
+                    // grant data payload. This was computed during submitConnectResponse()
+                    // and stored alongside the grant's standard fields.
+                    const keyDelivery = grant.grant.delegateKeyDelivery;
+                    if (!(keyDelivery === null || keyDelivery === void 0 ? void 0 : keyDelivery.rootKeyId) || !(keyDelivery === null || keyDelivery === void 0 ? void 0 : keyDelivery.publicKeyJwk)) {
+                        // Grant was created before key-delivery was supported, or
+                        // is not a read-like grant. Skip — do NOT dedup yet.
+                        continue;
+                    }
+                    // Dedup check — skip if already delivered via an earlier grant.
+                    if (deliveredDelegates.has(delegateDid)) {
+                        continue;
+                    }
+                    const leafPublicKeyJwk = keyDelivery.publicKeyJwk;
+                    try {
+                        yield this.writeContextKeyRecord({
+                            tenantDid,
+                            recipientDid: delegateDid,
+                            contextKeyData: contextKey,
+                            sourceProtocol: protocol,
+                            sourceContextId: rootContextId,
+                            recipientKeyDeliveryPublicKey: {
+                                rootKeyId: keyDelivery.rootKeyId,
+                                publicKeyJwk: leafPublicKeyJwk,
+                            },
+                        });
+                        // Mark as delivered ONLY after the write succeeds. If the write
+                        // fails, a later valid grant for the same delegate can still try.
+                        deliveredDelegates.add(delegateDid);
+                    }
+                    catch (delegateError) {
+                        console.warn(`AgentDwnApi: Cross-device key delivery to delegate ` +
+                            `'${delegateDid}' for context '${rootContextId}' failed: ` +
+                            `${delegateError.message}. The delegate may need to reconnect.`);
+                    }
+                }
+            }
+            catch (discoveryError) {
+                // Grant discovery failure is non-fatal — same-process delivery may
+                // still have succeeded, and sync will eventually deliver the record.
+                console.warn(`AgentDwnApi: Delegate grant discovery for protocol ` +
+                    `'${protocol}' failed: ${discoveryError.message}`);
+            }
+        });
+    }
     /**
      * Writes a `contextKey` record to the owner's DWN, delivering an encrypted
      * context key to a participant.
@@ -1118,7 +1550,7 @@ export class AgentDwnApi {
      */
     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), this.getDwnEndpointUrlsForTarget.bind(this));
+            return fetchContextKeyRecordFn(this.agent, params, this.processRequest.bind(this));
         });
     }
 }