@enbox/agent 0.2.1 → 0.3.0

package/dist/types/utils-internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils-internal.d.ts","sourceRoot":"","sources":["../../src/utils-internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAElH,OAAO,EAAiC,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,qBAAa,yBAA0B,SAAQ,eAAe;IAC5D,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,aAAa,CAAkC;;IAQ1C,iBAAiB,CAAC,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,GAAG,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBzE,SAAS,CAAC,EAAE,MAAM,EAAE,EAC/B,kBAAkB,GACjB,OAAO,CAAC,GAAG,CAAC;IAYF,WAAW,CAAC,OAAO,EAAE;QAChC,SAAS,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAA;KAC5D,GAAG,OAAO,CAAC,aAAa,CAAC;IAYb,YAAY,CAAC,EAAE,MAAM,EAAE,EAChC,qBAAqB,GACtB,OAAO,CAAC,GAAG,CAAC;IAeF,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAChC,aAAa,GACZ,OAAO,CAAC,UAAU,CAAC;CAcvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;IAClE,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBlB"}
+{"version":3,"file":"utils-internal.d.ts","sourceRoot":"","sources":["../../src/utils-internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAElH,OAAO,EAAiC,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,qBAAa,yBAA0B,SAAQ,eAAe;IAC5D,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,aAAa,CAAkC;;IAQ1C,iBAAiB,CAAC,EAAE,WAAW,EAAE,EAAE;QAAE,WAAW,EAAE,GAAG,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBzE,SAAS,CAAC,EAAE,MAAM,EAAE,EAC/B,kBAAkB,GACjB,OAAO,CAAC,GAAG,CAAC;IAYF,WAAW,CAAC,OAAO,EAAE;QAChC,SAAS,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAA;KAC5D,GAAG,OAAO,CAAC,aAAa,CAAC;IAYb,YAAY,CAAC,EAAE,MAAM,EAAE,EAChC,qBAAqB,GACtB,OAAO,CAAC,GAAG,CAAC;IAeF,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAChC,aAAa,GACZ,OAAO,CAAC,UAAU,CAAC;CAcvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;IAClE,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/agent",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
@@ -71,11 +71,11 @@
   },
   "dependencies": {
     "@scure/bip39": "1.2.2",
-    "@enbox/dwn-clients": "0.0.8",
-    "@enbox/dwn-sdk-js": "0.1.1",
-    "@enbox/common": "0.0.6",
-    "@enbox/crypto": "0.0.7",
-    "@enbox/dids": "0.0.8",
+    "@enbox/dwn-clients": "0.1.0",
+    "@enbox/dwn-sdk-js": "0.1.2",
+    "@enbox/common": "0.0.7",
+    "@enbox/crypto": "0.0.8",
+    "@enbox/dids": "0.0.9",
     "abstract-level": "1.0.4",
     "ed25519-keygen": "0.4.11",
     "level": "8.0.0",

package/src/agent-did-resolver-cache.ts

@@ -1,6 +1,6 @@
 import type { DidResolutionResult, DidResolverCache, DidResolverCacheLevelParams } from '@enbox/dids';
 
-import type { Web5PlatformAgent } from './types/agent.js';
+import type { EnboxPlatformAgent } from './types/agent.js';
 
 import { DidResolverCacheLevel } from '@enbox/dids';
 import { logger } from '@enbox/common';
@@ -13,29 +13,29 @@ import { logger } from '@enbox/common';
 export class AgentDidResolverCache extends DidResolverCacheLevel implements DidResolverCache {
 
   /**
-   * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
-   * the `AgentDidApi`. This agent is used to interact with other Web5 agent components. It's vital
-   * to ensure this instance is set to correctly contextualize operations within the broader Web5
+   * Holds the instance of a `EnboxPlatformAgent` that represents the current execution context for
+   * the `AgentDidApi`. This agent is used to interact with other Enbox agent components. It's vital
+   * to ensure this instance is set to correctly contextualize operations within the broader Enbox
    * Agent framework.
    */
-  private _agent?: Web5PlatformAgent;
+  private _agent?: EnboxPlatformAgent;
 
   /** A map of DIDs that are currently in-flight. This helps avoid going into an infinite loop */
   private _resolving: Map<string, boolean> = new Map();
 
-  constructor({ agent, db, location, ttl }: DidResolverCacheLevelParams & { agent?: Web5PlatformAgent }) {
+  constructor({ agent, db, location, ttl }: DidResolverCacheLevelParams & { agent?: EnboxPlatformAgent }) {
     super ({ db, location, ttl });
     this._agent = agent;
   }
 
-  get agent(): Web5PlatformAgent {
+  get agent(): EnboxPlatformAgent {
     if (!this._agent) {
       throw new Error('Agent not initialized');
     }
     return this._agent;
   }
 
-  set agent(agent: Web5PlatformAgent) {
+  set agent(agent: EnboxPlatformAgent) {
     this._agent = agent;
   }
 

package/src/anonymous-dwn-api.ts

@@ -13,7 +13,7 @@ import type {
   RecordsSubscribeReply,
   SubscriptionListener,
 } from '@enbox/dwn-sdk-js';
-import type { DwnRpcRequest, Web5Rpc } from '@enbox/dwn-clients';
+import type { DwnRpcRequest, EnboxRpc } from '@enbox/dwn-clients';
 
 import { ProtocolsQuery, RecordsCount, RecordsQuery, RecordsRead, RecordsSubscribe } from '@enbox/dwn-sdk-js';
 
@@ -26,7 +26,7 @@ export type AnonymousDwnApiParams = {
   /** A DID URL dereferencer for resolving target DID service endpoints. */
   didResolver: DidUrlDereferencer;
   /** An RPC client for sending messages to remote DWNs. */
-  rpcClient: Web5Rpc;
+  rpcClient: EnboxRpc;
 };
 
 /**
@@ -89,7 +89,7 @@ export type AnonymousProtocolsQueryParams = {
  * @example
  * ```ts
  * const resolver = new UniversalResolver({ didResolvers: [DidDht, DidJwk] });
- * const rpcClient = new Web5RpcClient();
+ * const rpcClient = new EnboxRpcClient();
  * const anonymousDwn = new AnonymousDwnApi({ didResolver: resolver, rpcClient });
  *
  * const reply = await anonymousDwn.recordsQuery('did:dht:alice...', {
@@ -99,7 +99,7 @@ export type AnonymousProtocolsQueryParams = {
  */
 export class AnonymousDwnApi {
   private _didResolver: DidUrlDereferencer;
-  private _rpcClient: Web5Rpc;
+  private _rpcClient: EnboxRpc;
 
   constructor({ didResolver, rpcClient }: AnonymousDwnApiParams) {
     this._didResolver = didResolver;

package/src/bearer-identity.ts

@@ -2,7 +2,7 @@ import type { BearerDid } from '@enbox/dids';
 import type { IdentityMetadata, PortableIdentity } from './types/identity.js';
 
 /**
- * Represents a Web5 Identity with its DID and metadata.
+ * Represents an Enbox Identity with its DID and metadata.
  */
 export class BearerIdentity {
   /** {@inheritDoc BearerDid} */

package/src/connect.ts

@@ -1,6 +1,6 @@
 
 import type { PushedAuthResponse } from './oidc.js';
-import type { DwnPermissionScope, DwnProtocolDefinition, Web5ConnectAuthResponse } from './index.js';
+import type { DwnPermissionScope, DwnProtocolDefinition, EnboxConnectAuthResponse } from './index.js';
 
 import { CryptoUtils } from '@enbox/crypto';
 import { DidJwk } from '@enbox/dids';
@@ -21,8 +21,8 @@ async function initClient({
   onWalletUriReady,
   validatePin,
 }: WalletConnectOptions): Promise<{
-  delegateGrants: Web5ConnectAuthResponse['delegateGrants'];
-  delegatePortableDid: Web5ConnectAuthResponse['delegatePortableDid'];
+  delegateGrants: EnboxConnectAuthResponse['delegateGrants'];
+  delegatePortableDid: EnboxConnectAuthResponse['delegatePortableDid'];
   connectedDid: string;
 } | undefined> {
   // ephemeral client did for ECDH, signing, verification
@@ -93,8 +93,8 @@ async function initClient({
 
   const parData: PushedAuthResponse = await parResponse.json();
 
-  // a deeplink to a web5 compatible wallet. if the wallet scans this link it should receive
-  // a route to its web5 connect provider flow and the params of where to fetch the auth request.
+  // a deeplink to a compatible wallet. if the wallet scans this link it should receive
+  // a route to its Connect provider flow and the params of where to fetch the auth request.
   logger.log(`Wallet URI: ${walletUri}`);
   const generatedWalletUri = new URL(walletUri);
   generatedWalletUri.searchParams.set('request_uri', parData.request_uri);
@@ -112,7 +112,7 @@ async function initClient({
     tokenParam : request.state,
   });
 
-  // subscribe to receiving a response from the wallet with default TTL. receive ciphertext of {@link Web5ConnectAuthResponse}
+  // subscribe to receiving a response from the wallet with default TTL. receive ciphertext of {@link EnboxConnectAuthResponse}
   const authResponse = await pollWithTtl(() => fetch(tokenUrl, { signal: AbortSignal.timeout(30_000) }));
 
   if (authResponse) {
@@ -123,7 +123,7 @@ async function initClient({
     const jwt = await Oidc.decryptAuthResponse(clientDid, jwe, pin);
     const verifiedAuthResponse = (await Oidc.verifyJwt({
       jwt,
-    })) as Web5ConnectAuthResponse;
+    })) as EnboxConnectAuthResponse;
 
     return {
       delegateGrants      : verifiedAuthResponse.delegateGrants,
@@ -159,20 +159,20 @@ export type WalletConnectOptions = {
   permissionRequests: ConnectPermissionRequest[];
 
   /**
-   * The Web5 API provides a URI to the wallet based on the `walletUri` plus a query params payload valid for 5 minutes.
+   * The Connect API provides a URI to the wallet based on the `walletUri` plus a query params payload valid for 5 minutes.
    * The link can either be used as a deep link on the same device or a QR code for cross device or both.
    * The query params are `{ request_uri: string; encryption_key: string; }`
    * The wallet will use the `request_uri to contact the intermediary server's `authorize` endpoint
-   * and pull down the {@link Web5ConnectAuthRequest} and use the `encryption_key` to decrypt it.
+   * and pull down the {@link EnboxConnectAuthRequest} and use the `encryption_key` to decrypt it.
    *
-   * @param uri - The URI returned by the web5 connect API to be passed to a provider.
+   * @param uri - The URI returned by the Connect API to be passed to a provider.
    */
   onWalletUriReady: (uri: string) => void;
 
   /**
    * Function that must be provided to submit the pin entered by the user on the client.
-   * The pin is used to decrypt the {@link Web5ConnectAuthResponse} that was retrieved from the
-   * token endpoint by the client inside of web5 connect.
+   * The pin is used to decrypt the {@link EnboxConnectAuthResponse} that was retrieved from the
+   * token endpoint by the client inside of Connect.
    *
    * @returns A promise that resolves to the PIN as a string.
    */

package/src/did-api.ts

@@ -8,6 +8,7 @@ import type {
   DidResolutionResult,
   DidResolverCache,
   DidVerificationMethod,
+  DidWebCreateOptions,
   PortableDid,
 } from '@enbox/dids';
 
@@ -15,7 +16,7 @@ import { BearerDid, Did, DidDht, UniversalResolver } from '@enbox/dids';
 
 import type { AgentDataStore } from './store-data.js';
 import type { AgentKeyManager } from './types/key-manager.js';
-import type { ResponseStatus, Web5PlatformAgent } from './types/agent.js';
+import type { EnboxPlatformAgent, ResponseStatus } from './types/agent.js';
 
 import { AgentDidResolverCache } from './agent-did-resolver-cache.js';
 import { canonicalize } from '@enbox/crypto';
@@ -77,12 +78,13 @@ export interface DidCreateParams<
 export interface DidMethodCreateOptions<TKeyManager> {
   dht: DidDhtCreateOptions<TKeyManager>;
   jwk: DidJwkCreateOptions<TKeyManager>;
+  web: DidWebCreateOptions<TKeyManager>;
 }
 
 export interface DidApiParams {
   didMethods: DidMethodApi[];
 
-  agent?: Web5PlatformAgent;
+  agent?: EnboxPlatformAgent;
 
   /**
    * An optional `DidResolverCache` instance used for caching resolved DID documents.
@@ -105,19 +107,19 @@ export function isDidRequest<T extends DidInterface>(
 }
 
 /**
- * This API is used to manage and interact with DIDs within the Web5 Agent framework.
+ * This API is used to manage and interact with DIDs within the Enbox Agent framework.
  *
  * If a DWN Data Store is used, the DID information is stored under DID's own tenant by default.
  * If a tenant property is passed, that tenant will be used to store the DID information.
  */
 export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager> extends UniversalResolver {
   /**
-   * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
-   * the `AgentDidApi`. This agent is used to interact with other Web5 agent components. It's vital
-   * to ensure this instance is set to correctly contextualize operations within the broader Web5
+   * Holds the instance of a `EnboxPlatformAgent` that represents the current execution context for
+   * the `AgentDidApi`. This agent is used to interact with other Enbox agent components. It's vital
+   * to ensure this instance is set to correctly contextualize operations within the broader Enbox
    * Agent framework.
    */
-  private _agent?: Web5PlatformAgent;
+  private _agent?: EnboxPlatformAgent;
 
   private _didMethods: Map<string, DidMethodApi> = new Map();
 
@@ -146,12 +148,12 @@ export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager>
   }
 
   /**
-   * Retrieves the `Web5PlatformAgent` execution context.
+   * Retrieves the `EnboxPlatformAgent` execution context.
    *
-   * @returns The `Web5PlatformAgent` instance that represents the current execution context.
+   * @returns The `EnboxPlatformAgent` instance that represents the current execution context.
    * @throws Will throw an error if the `agent` instance property is undefined.
    */
-  get agent(): Web5PlatformAgent {
+  get agent(): EnboxPlatformAgent {
     if (this._agent === undefined) {
       throw new Error('AgentDidApi: Unable to determine agent execution context.');
     }
@@ -159,7 +161,7 @@ export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager>
     return this._agent;
   }
 
-  set agent(agent: Web5PlatformAgent) {
+  set agent(agent: EnboxPlatformAgent) {
     this._agent = agent;
 
     // AgentDidResolverCache should set the agent if it is the type of cache being used

package/src/dwn-api.ts

@@ -33,7 +33,8 @@ import {
 import { CryptoUtils, X25519 } from '@enbox/crypto';
 import { DidDht, DidJwk, DidResolverCacheLevel, UniversalResolver } from '@enbox/dids';
 
-import type { Web5PlatformAgent } from './types/agent.js';
+import type { EnboxPlatformAgent } from './types/agent.js';
+import type { LocalDwnStrategy } from './local-dwn.js';
 import type {
   DwnMessage,
   DwnMessageInstance,
@@ -47,7 +48,9 @@ import type {
   SendDwnRequest,
 } from './types/dwn.js';
 
+import { DwnDiscoveryFile } from './dwn-discovery-file.js';
 import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
+import { LocalDwnDiscovery } from './local-dwn.js';
 import { DwnInterface, dwnMessageConstructors } from './types/dwn.js';
 import { getDwnServiceEndpointUrls, isRecordsWrite } from './utils.js';
 
@@ -99,8 +102,9 @@ type DwnMessageWithBlob<T extends DwnInterface> = {
 };
 
 type DwnApiParams = {
-  agent?: Web5PlatformAgent;
+  agent?: EnboxPlatformAgent;
   dwn: Dwn;
+  localDwnStrategy?: LocalDwnStrategy;
 };
 
 interface DwnApiCreateDwnParams extends Partial<DwnConfig> {
@@ -109,12 +113,12 @@ interface DwnApiCreateDwnParams extends Partial<DwnConfig> {
 
 export class AgentDwnApi {
   /**
-   * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
-   * the `AgentDwnApi`. This agent is used to interact with other Web5 agent components. It's vital
-   * to ensure this instance is set to correctly contextualize operations within the broader Web5
+   * Holds the instance of a `EnboxPlatformAgent` that represents the current execution context for
+   * the `AgentDwnApi`. This agent is used to interact with other Enbox agent components. It's vital
+   * to ensure this instance is set to correctly contextualize operations within the broader Enbox
    * Agent framework.
    */
-  private _agent?: Web5PlatformAgent;
+  private _agent?: EnboxPlatformAgent;
 
   /**
    * The DWN instance to use for this API.
@@ -148,21 +152,47 @@ export class AgentDwnApi {
     ttl: 30 * 60 * 1000
   });
 
-  constructor({ agent, dwn }: DwnApiParams) {
+  /**
+   * Cache of locally-managed DIDs (agent DID + identities). Used to decide
+   * whether a target DID should be routed through the local DWN server.
+   */
+  private _localManagedDidCache = new TtlCache<string, boolean>({
+    ttl: 30 * 60 * 1000
+  });
+
+  /** Controls local DWN discovery behavior ('prefer' | 'only' | 'off'). */
+  private _localDwnStrategy: LocalDwnStrategy;
+
+  /** Lazy-initialized local DWN discovery instance. */
+  private _localDwnDiscovery?: LocalDwnDiscovery;
+
+  constructor({ agent, dwn, localDwnStrategy = 'prefer' }: DwnApiParams) {
     // If an agent is provided, set it as the execution context for this API.
     this._agent = agent;
 
     // Set the DWN instance for this API.
     this._dwn = dwn;
+
+    // Set the local DWN discovery strategy.
+    this._localDwnStrategy = localDwnStrategy;
+
+    // If agent is already available, eagerly initialize the discovery instance.
+    if (agent) {
+      this._localDwnDiscovery = new LocalDwnDiscovery(
+        agent.rpc,
+        10_000,
+        AgentDwnApi._tryCreateDiscoveryFile(),
+      );
+    }
   }
 
   /**
-   * Retrieves the `Web5PlatformAgent` execution context.
+   * Retrieves the `EnboxPlatformAgent` execution context.
    *
-   * @returns The `Web5PlatformAgent` instance that represents the current execution context.
+   * @returns The `EnboxPlatformAgent` instance that represents the current execution context.
    * @throws Will throw an error if the `agent` instance property is undefined.
    */
-  get agent(): Web5PlatformAgent {
+  get agent(): EnboxPlatformAgent {
     if (this._agent === undefined) {
       throw new Error('AgentDwnApi: Unable to determine agent execution context.');
     }
@@ -170,8 +200,156 @@ export class AgentDwnApi {
     return this._agent;
   }
 
-  set agent(agent: Web5PlatformAgent) {
+  set agent(agent: EnboxPlatformAgent) {
     this._agent = agent;
+    // Re-initialize local DWN discovery with the new agent's RPC client.
+    this._localDwnDiscovery = new LocalDwnDiscovery(
+      agent.rpc,
+      10_000,
+      AgentDwnApi._tryCreateDiscoveryFile(),
+    );
+    this._localManagedDidCache.clear();
+  }
+
+  get localDwnStrategy(): LocalDwnStrategy {
+    return this._localDwnStrategy;
+  }
+
+  public setLocalDwnStrategy(strategy: LocalDwnStrategy): void {
+    this._localDwnStrategy = strategy;
+  }
+
+  /**
+   * Inject a cached local DWN endpoint (e.g. from a `dwn://register`
+   * browser redirect or from persisted storage). The endpoint is validated
+   * via `GET /info` before being accepted.
+   *
+   * @param endpoint - The local DWN server base URL.
+   * @returns `true` if the endpoint was validated and cached, `false` otherwise.
+   * @see https://github.com/enboxorg/enbox/issues/589
+   */
+  public async setCachedLocalDwnEndpoint(endpoint: string): Promise<boolean> {
+    this._localDwnDiscovery ??= new LocalDwnDiscovery(
+      this.agent.rpc,
+      10_000,
+      AgentDwnApi._tryCreateDiscoveryFile(),
+    );
+    return this._localDwnDiscovery.setCachedEndpoint(endpoint);
+  }
+
+  /**
+   * Resolves the DWN service endpoint URLs for the given target DID, optionally
+   * prepending a local DWN server endpoint when local discovery is enabled and
+   * the target is a locally-managed DID.
+   *
+   * @param targetDid - The DID whose DWN endpoints should be resolved.
+   * @returns An array of endpoint URLs.
+   * @throws When strategy is `'only'` and no local server is available.
+   */
+  public async getDwnEndpointUrlsForTarget(targetDid: string): Promise<string[]> {
+    const shouldUseLocalDwn = await this.shouldUseLocalDwnForTarget(targetDid);
+
+    if (!shouldUseLocalDwn) {
+      return getDwnServiceEndpointUrls(targetDid, this.agent.did);
+    }
+
+    const localDwnEndpoint = await this.getLocalDwnEndpoint();
+    if (this._localDwnStrategy === 'only') {
+      if (!localDwnEndpoint) {
+        throw new Error(
+          `AgentDwnApi: Local DWN strategy is 'only' but no local server is available ` +
+          `on 127.0.0.1:{3000,55500-55509}`
+        );
+      }
+
+      return [localDwnEndpoint];
+    }
+
+    let dwnEndpointUrls: string[] = [];
+    try {
+      dwnEndpointUrls = await getDwnServiceEndpointUrls(targetDid, this.agent.did);
+    } catch (error) {
+      if (!localDwnEndpoint) {
+        throw error;
+      }
+    }
+
+    if (!localDwnEndpoint) {
+      return dwnEndpointUrls;
+    }
+
+    const uniqueEndpoints = new Set<string>([
+      localDwnEndpoint,
+      ...dwnEndpointUrls,
+    ]);
+
+    return [...uniqueEndpoints];
+  }
+
+  /** Lazily retrieves the local DWN server endpoint via discovery. */
+  private async getLocalDwnEndpoint(): Promise<string | undefined> {
+    this._localDwnDiscovery ??= new LocalDwnDiscovery(
+      this.agent.rpc,
+      10_000,
+      AgentDwnApi._tryCreateDiscoveryFile(),
+    );
+    return this._localDwnDiscovery.getEndpoint();
+  }
+
+  /**
+   * Attempt to create a {@link DwnDiscoveryFile} for file-based local DWN
+   * discovery. Returns `undefined` in environments where the filesystem
+   * is not available (e.g. browsers).
+   */
+  private static _tryCreateDiscoveryFile(): DwnDiscoveryFile | undefined {
+    try {
+      return new DwnDiscoveryFile();
+    } catch {
+      // Browser environment — node:fs/promises not available.
+      return undefined;
+    }
+  }
+
+  /**
+   * Determines whether the given target DID should be routed through the
+   * local DWN server. Returns `true` if the DID is the agent DID or one
+   * of the locally-managed identity DIDs.
+   */
+  private async shouldUseLocalDwnForTarget(targetDid: string): Promise<boolean> {
+    if (this._localDwnStrategy === 'off') {
+      return false;
+    }
+
+    const cached = this._localManagedDidCache.get(targetDid);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    if (targetDid === this.agent.agentDid.uri) {
+      this._localManagedDidCache.set(targetDid, true);
+      return true;
+    }
+
+    const identities = await this.agent.identity.list();
+    const localManagedDids = new Set<string>();
+
+    for (const identity of identities) {
+      localManagedDids.add(identity.did.uri);
+      if (identity.metadata.connectedDid) {
+        localManagedDids.add(identity.metadata.connectedDid);
+      }
+    }
+
+    for (const localDid of localManagedDids) {
+      this._localManagedDidCache.set(localDid, true);
+    }
+
+    const isLocalManaged = localManagedDids.has(targetDid);
+    if (!isLocalManaged) {
+      this._localManagedDidCache.set(targetDid, false);
+    }
+
+    return isLocalManaged;
   }
 
   /**
@@ -182,7 +360,7 @@ export class AgentDwnApi {
    *   However, it is recommended to use the `processRequest` method to interact with the DWN
    *   instance to ensure that the DWN message is constructed correctly.
    * - The getter is named `node` to avoid confusion with the `dwn` property of the
-   *   `Web5PlatformAgent`. In other words, so that a developer can call `agent.dwn.node` to access
+   *   `EnboxPlatformAgent`. In other words, so that a developer can call `agent.dwn.node` to access
    *   the DWN instance and not `agent.dwn.dwn`.
    */
   get node(): Dwn {
@@ -252,8 +430,8 @@ export class AgentDwnApi {
   public async sendRequest<T extends DwnInterface>(
     request: SendDwnRequest<T>
   ): Promise<DwnResponse<T>> {
-    // First, confirm the target DID can be dereferenced and extract the DWN service endpoint URLs.
-    const dwnEndpointUrls = await getDwnServiceEndpointUrls(request.target, this.agent.did);
+    // Resolve DWN service endpoint URLs, with local DWN discovery if enabled.
+    const dwnEndpointUrls = await this.getDwnEndpointUrlsForTarget(request.target);
     if (dwnEndpointUrls.length === 0) {
       throw new Error(`AgentDwnApi: DID Service is missing or malformed: ${request.target}#dwn`);
     }
@@ -997,7 +1175,7 @@ export class AgentDwnApi {
     protocolUri: string,
   ): Promise<ProtocolDefinition> {
     return fetchRemoteProtocolDefinitionFn(
-      targetDid, protocolUri, this.agent.did,
+      targetDid, protocolUri, this.getDwnEndpointUrlsForTarget.bind(this),
       this.sendDwnRpcRequest.bind(this), this._protocolDefinitionCache,
     );
   }
@@ -1022,7 +1200,7 @@ export class AgentDwnApi {
   ): Promise<{ rootKeyId: string; derivedPublicKey: PublicKeyJwk } | undefined> {
     return extractDerivedPublicKeyFn(
       targetDid, protocolUri, rootContextId, requesterDid,
-      this.agent.did, this.getSigner.bind(this),
+      this.getDwnEndpointUrlsForTarget.bind(this), this.getSigner.bind(this),
       this.sendDwnRpcRequest.bind(this),
     );
   }
@@ -1139,6 +1317,7 @@ export class AgentDwnApi {
       this.agent, tenantDid, contextKeyMessage,
       this.getDwnMessage.bind(this),
       this.sendDwnRpcRequest.bind(this),
+      this.getDwnEndpointUrlsForTarget.bind(this),
     );
   }
 
@@ -1160,6 +1339,7 @@ export class AgentDwnApi {
       this.processRequest.bind(this),
       this.getSigner.bind(this),
       this.sendDwnRpcRequest.bind(this),
+      this.getDwnEndpointUrlsForTarget.bind(this),
     );
   }
 }