@enbox/agent 0.5.16 → 0.6.1

package/src/dwn-api.ts

@@ -13,7 +13,6 @@ import type {
 import type { DwnSubscriptionHandler, ResubscribeFactory } from '@enbox/dwn-clients';
 import type { KeyIdentifier, PrivateKeyJwk, PublicKeyJwk } from '@enbox/crypto';
 
-import { TtlCache } from '@enbox/common';
 import {
   Cid,
   ContentEncryptionAlgorithm,
@@ -31,6 +30,7 @@ import {
   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';
 
@@ -49,6 +49,7 @@ import type {
   SendDwnRequest,
 } from './types/dwn.js';
 
+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';
@@ -165,6 +166,55 @@ export class AgentDwnApi {
     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).
+   */
+  private _delegateDecryptionKeyCache = new TtlCache<string, {
+    protocol: string;
+    scope: { kind: 'protocol' } | { kind: 'protocolPath'; protocolPath: string; match: 'exact' };
+    derivedPrivateKey: DerivedPrivateJwk;
+  }[]>({
+    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).
+   */
+  private _delegateContextKeyCache = new TtlCache<string, DerivedPrivateJwk>({
+    ttl: 24 * 60 * 60 * 1000
+  });
+
+  /** Tracks which context key cache entries belong to which delegate DID. */
+  private _delegateContextKeyCacheIndex = new Map<string, string[]>();
+
+  /**
+   * 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.
+   */
+  private _delegateMultiPartyProtocols = new Map<string, Set<string>>();
+
+  /**
+   * Optional callback invoked when post-connect context keys are delivered
+   * to a delegate. The auth layer sets this to persist updated keys.
+   */
+  private _onDelegateContextKeysChanged?: (delegateDid: string) => void;
+
   /**
    * Cache of locally-managed DIDs (agent DID + identities). Used to decide
    * whether a target DID should be routed through the local DWN server.
@@ -312,6 +362,15 @@ 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.
+   */
+  public async getRemoteDwnEndpointUrls(targetDid: string): Promise<string[]> {
+    return getDwnServiceEndpointUrls(targetDid, this.agent.did);
+  }
+
   /** Lazily retrieves the local DWN server endpoint via discovery. */
   private async getLocalDwnEndpoint(): Promise<string | undefined> {
     // In remote mode, the endpoint is always known.
@@ -686,12 +745,19 @@ export class AgentDwnApi {
         authorDid    : isExternallyAuthored ? authorDid : undefined,
       });
 
-      if (newParticipants.size > 0) {
-        // Derive the context key to deliver to participants
-        const rootContextId = recordsWriteMessage.contextId?.split('/')[0]
-          || recordsWriteMessage.contextId
-          || recordsWriteMessage.recordId;
+      // Compute rootContextId for both participant and delegate delivery.
+      const rootContextId = recordsWriteMessage.contextId?.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 } = await getEncryptionKeyInfoFn(this.agent, request.target);
         const contextDerivationPath = [
           KeyDerivationScheme.ProtocolContext,
@@ -711,36 +777,79 @@ export class AgentDwnApi {
           derivedPrivateKey : contextDerivedPrivateJwk as PrivateKeyJwk,
         };
 
-        // Extract the author's key delivery public key from the record
-        // so we can encrypt the contextKey directly to the external author.
-        const authorKeyDeliveryPubKey =
-          recordsWriteMessage.authorization?.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;
-
-            await this.writeContextKeyRecord({
-              tenantDid                     : request.target,
-              recipientDid                  : participantDid,
-              contextKeyData                : contextKeyPayload,
-              sourceProtocol                : writeParams.protocol,
-              sourceContextId               : rootContextId,
-              recipientKeyDeliveryPublicKey : recipientKey,
-            });
-          } catch (keyDeliveryError: any) {
-            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 =
+            recordsWriteMessage.authorization?.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;
+
+              await this.writeContextKeyRecord({
+                tenantDid                     : request.target,
+                recipientDid                  : participantDid,
+                contextKeyData                : contextKeyPayload,
+                sourceProtocol                : writeParams.protocol,
+                sourceContextId               : rootContextId,
+                recipientKeyDeliveryPublicKey : recipientKey,
+              });
+            } catch (keyDeliveryError: any) {
+              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 } = await getEncryptionKeyInfoFn(this.agent, request.target);
+        const xdContextDerivationPath = [
+          KeyDerivationScheme.ProtocolContext,
+          rootContextId,
+        ];
+        const xdContextDerivedPrivateKeyBytes =
+          await this.agent.keyManager.derivePrivateKeyBytes({
+            keyUri         : xdKeyUri,
+            derivationPath : xdContextDerivationPath,
+          });
+        const xdContextDerivedPrivateJwk =
+          await X25519.bytesToPrivateKey({ privateKeyBytes: xdContextDerivedPrivateKeyBytes });
+        const xdContextKeyPayload: DerivedPrivateJwk = {
+          rootKeyId         : xdKeyId,
+          derivationScheme  : KeyDerivationScheme.ProtocolContext,
+          derivationPath    : xdContextDerivationPath,
+          derivedPrivateKey : xdContextDerivedPrivateJwk as PrivateKeyJwk,
+        };
+
+        await this.deliverContextKeyToDelegatesViaDwn(
+          request.target, writeParams.protocol, rootContextId, xdContextKeyPayload,
+        );
       }
     } catch (detectionError: any) {
       // Participant detection failure is non-fatal — the record is still stored.
@@ -875,6 +984,20 @@ export class AgentDwnApi {
       );
     }
 
+    // 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 = request.messageParams?.definition;
+      if (def?.protocol) {
+        this._protocolDefinitionCache.set(`${request.target}~${def.protocol}`, def);
+      }
+    }
+
     // Auto-encrypt data on RecordsWrite.
     //
     // Encryption scheme decision (unified key delivery):
@@ -923,7 +1046,7 @@ export class AgentDwnApi {
           );
         } else {
           protocolDefinition = await this.getProtocolDefinition(
-            request.target, messageParams.protocol,
+            request.target, messageParams.protocol, request.granteeDid,
           );
         }
 
@@ -1115,8 +1238,34 @@ export class AgentDwnApi {
         await this.getSigner(request.granteeDid) :
         await this.getSigner(request.author);
 
+      // 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 = { ...request.messageParams } as any;
+      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 } = await this.processRequest({
+          author        : request.granteeDid,
+          target        : request.author,
+          messageType   : DwnInterface.RecordsRead,
+          messageParams : { filter: { recordId: params.permissionGrantId } },
+        });
+        if (grantReply.status.code === 200 && grantReply.entry?.recordsWrite && grantReply.entry?.data) {
+          const grantDataBytes = await DataStream.toBytes(grantReply.entry.data);
+          params.delegatedGrant = {
+            ...grantReply.entry.recordsWrite,
+            encodedData: Convert.uint8Array(grantDataBytes).toBase64Url(),
+          };
+        }
+      }
+
       dwnMessage = await dwnMessageConstructor.create({
-        ...request.messageParams,
+        ...params,
         signer
       });
 
@@ -1293,6 +1442,7 @@ export class AgentDwnApi {
   private async getProtocolDefinition(
     tenantDid: string,
     protocolUri: string,
+    granteeDid?: string,
   ): Promise<ProtocolDefinition | undefined> {
     if (!this._dwn) {
       // Remote mode: query via RPC (same as fetchRemoteProtocolDefinition,
@@ -1312,9 +1462,29 @@ export class AgentDwnApi {
         throw error;
       }
     }
+    // When operating as a delegate, resolve the ProtocolsQuery grant so
+    // the local DWN authorises the query for unpublished protocols.
+    let permissionGrantId: string | undefined;
+    if (granteeDid) {
+      try {
+        const permissionsApi = new AgentPermissionsApi({ agent: this.agent });
+        const { grant } = await permissionsApi.getPermissionForRequest({
+          connectedDid : tenantDid,
+          delegateDid  : granteeDid,
+          protocol     : protocolUri,
+          cached       : true,
+          messageType  : DwnInterface.ProtocolsQuery,
+        });
+        permissionGrantId = grant.id;
+      } catch {
+        // No grant found — try without (works for published protocols).
+      }
+    }
+
     return getProtocolDefinitionFn(
       tenantDid, protocolUri, this._dwn,
       this.getSigner.bind(this), this._protocolDefinitionCache,
+      granteeDid, permissionGrantId,
     );
   }
 
@@ -1369,6 +1539,8 @@ export class AgentDwnApi {
       request, reply, this.agent,
       this._contextDerivedKeyCache,
       this.fetchContextKeyRecord.bind(this),
+      this._delegateDecryptionKeyCache,
+      this._delegateContextKeyCache,
     );
   }
 
@@ -1452,6 +1624,328 @@ export class AgentDwnApi {
     );
   }
 
+  /**
+   * 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.
+   */
+  public set onDelegateContextKeysChanged(
+    callback: ((delegateDid: string) => void) | undefined,
+  ) {
+    this._onDelegateContextKeysChanged = callback;
+  }
+
+  public importDelegateDecryptionKeys(
+    delegateDid: string,
+    keys: {
+      protocol: string;
+      scope: { kind: 'protocol' } | { kind: 'protocolPath'; protocolPath: string; match: 'exact' };
+      derivedPrivateKey: DerivedPrivateJwk;
+    }[],
+  ): void {
+    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
+   */
+  public importDelegateContextKeys(
+    delegateDid: string,
+    keys: {
+      protocol: string;
+      contextId: string;
+      derivedPrivateKey: DerivedPrivateJwk;
+    }[],
+    multiPartyProtocols?: string[],
+  ): void {
+    // 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: string[] = [];
+    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<string>(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.
+   */
+  public clearDelegateDecryptionKeys(delegateDid?: string): void {
+    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)
+   */
+  public exportDelegateContextKeys(
+    delegateDid: string,
+  ): { protocol: string; contextId: string; derivedPrivateKey: DerivedPrivateJwk }[] {
+    const cacheKeys = this._delegateContextKeyCacheIndex.get(delegateDid);
+    if (!cacheKeys) { return []; }
+
+    const result: { protocol: string; contextId: string; derivedPrivateKey: DerivedPrivateJwk }[] = [];
+    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.
+   */
+  public exportDelegateMultiPartyProtocols(delegateDid: string): string[] {
+    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.
+   */
+  private hasEligibleDelegatesForProtocol(protocol: string): boolean {
+    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`)
+   */
+  private deliverContextKeyToDelegates(
+    protocol: string,
+    rootContextId: string,
+    contextKey: DerivedPrivateJwk,
+  ): void {
+    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 = this._delegateContextKeyCacheIndex.get(delegateDid) ?? [];
+      indexKeys.push(newCacheKey);
+      this._delegateContextKeyCacheIndex.set(delegateDid, indexKeys);
+
+      // Notify the auth layer so it can persist the updated keys.
+      this._onDelegateContextKeysChanged?.(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`)
+   */
+  private async deliverContextKeyToDelegatesViaDwn(
+    tenantDid: string,
+    protocol: string,
+    rootContextId: string,
+    contextKey: DerivedPrivateJwk,
+  ): Promise<void> {
+    try {
+      const permissionsApi = new AgentPermissionsApi({ agent: this.agent });
+      const grants = await 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<string>();
+
+      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 as any;
+        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?.rootKeyId || !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 as PublicKeyJwk;
+
+        try {
+          await 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: any) {
+          console.warn(
+            `AgentDwnApi: Cross-device key delivery to delegate ` +
+            `'${delegateDid}' for context '${rootContextId}' failed: ` +
+            `${delegateError.message}. The delegate may need to reconnect.`
+          );
+        }
+      }
+    } catch (discoveryError: any) {
+      // 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.
@@ -1507,9 +2001,6 @@ export class AgentDwnApi {
     return fetchContextKeyRecordFn(
       this.agent, params,
       this.processRequest.bind(this),
-      this.getSigner.bind(this),
-      this.sendDwnRpcRequest.bind(this),
-      this.getDwnEndpointUrlsForTarget.bind(this),
     );
   }
 }