@enbox/agent 0.2.1 → 0.2.2

package/src/dwn-api.ts

@@ -33,6 +33,7 @@ import {
 import { CryptoUtils, X25519 } from '@enbox/crypto';
 import { DidDht, DidJwk, DidResolverCacheLevel, UniversalResolver } from '@enbox/dids';
 
+import type { LocalDwnStrategy } from './local-dwn.js';
 import type { Web5PlatformAgent } from './types/agent.js';
 import type {
   DwnMessage,
@@ -48,6 +49,7 @@ import type {
 } from './types/dwn.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';
 
@@ -101,6 +103,7 @@ type DwnMessageWithBlob<T extends DwnInterface> = {
 type DwnApiParams = {
   agent?: Web5PlatformAgent;
   dwn: Dwn;
+  localDwnStrategy?: LocalDwnStrategy;
 };
 
 interface DwnApiCreateDwnParams extends Partial<DwnConfig> {
@@ -148,12 +151,34 @@ 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);
+    }
   }
 
   /**
@@ -172,6 +197,114 @@ export class AgentDwnApi {
 
   set agent(agent: Web5PlatformAgent) {
     this._agent = agent;
+    // Re-initialize local DWN discovery with the new agent's RPC client.
+    this._localDwnDiscovery = new LocalDwnDiscovery(agent.rpc);
+    this._localManagedDidCache.clear();
+  }
+
+  get localDwnStrategy(): LocalDwnStrategy {
+    return this._localDwnStrategy;
+  }
+
+  public setLocalDwnStrategy(strategy: LocalDwnStrategy): void {
+    this._localDwnStrategy = strategy;
+  }
+
+  /**
+   * 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 localhost/127.0.0.1:{3000,55555-55559}`
+        );
+      }
+
+      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 probing. */
+  private async getLocalDwnEndpoint(): Promise<string | undefined> {
+    this._localDwnDiscovery ??= new LocalDwnDiscovery(this.agent.rpc);
+    return this._localDwnDiscovery.getEndpoint();
+  }
+
+  /**
+   * 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;
   }
 
   /**
@@ -252,8 +385,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 +1130,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 +1155,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 +1272,7 @@ export class AgentDwnApi {
       this.agent, tenantDid, contextKeyMessage,
       this.getDwnMessage.bind(this),
       this.sendDwnRpcRequest.bind(this),
+      this.getDwnEndpointUrlsForTarget.bind(this),
     );
   }
 
@@ -1160,6 +1294,7 @@ export class AgentDwnApi {
       this.processRequest.bind(this),
       this.getSigner.bind(this),
       this.sendDwnRpcRequest.bind(this),
+      this.getDwnEndpointUrlsForTarget.bind(this),
     );
   }
 }

package/src/dwn-key-delivery.ts

@@ -22,7 +22,6 @@ import {
   Records,
 } from '@enbox/dwn-sdk-js';
 
-import { getDwnServiceEndpointUrls } from './utils.js';
 import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
 import { buildEncryptionInput, encryptAndComputeCid, getEncryptionKeyDeriver, getKeyDecrypter, ivLength } from './dwn-encryption.js';
 import { DwnInterface, dwnMessageConstructors } from './types/dwn.js';
@@ -219,6 +218,7 @@ export async function writeContextKeyRecord(
  * @param contextKeyMessage - The context key message to send
  * @param getDwnMessage - Function to read a full message from local DWN
  * @param sendDwnRpcRequest - Function to send a DWN RPC request
+ * @param getDwnEndpointUrlsForTarget - Function to resolve DWN endpoint URLs (with local discovery)
  */
 export async function eagerSendContextKeyRecord(
   agent: Web5PlatformAgent,
@@ -226,10 +226,11 @@ export async function eagerSendContextKeyRecord(
   contextKeyMessage: DwnMessage[DwnInterface.RecordsWrite],
   getDwnMessage: (params: { author: string; messageType: DwnInterface; messageCid: string }) => Promise<{ message: any; data?: Blob }>,
   sendDwnRpcRequest: (params: { targetDid: string; dwnEndpointUrls: string[]; message: any; data?: Blob }) => Promise<any>,
+  getDwnEndpointUrlsForTarget: (targetDid: string) => Promise<string[]>,
 ): Promise<void> {
   let dwnEndpointUrls: string[];
   try {
-    dwnEndpointUrls = await getDwnServiceEndpointUrls(tenantDid, agent.did);
+    dwnEndpointUrls = await getDwnEndpointUrlsForTarget(tenantDid);
   } catch {
     // DID resolution or endpoint lookup failed — not fatal, sync will handle it.
     return;
@@ -266,6 +267,7 @@ export async function eagerSendContextKeyRecord(
  * @param processRequest - The agent's processRequest method (bound)
  * @param getSigner - Function to get a signer for a DID
  * @param sendDwnRpcRequest - Function to send a DWN RPC request
+ * @param getDwnEndpointUrlsForTarget - Function to resolve DWN endpoint URLs (with local discovery)
  * @returns The decrypted `DerivedPrivateJwk`, or `undefined` if no matching record found
  */
 export async function fetchContextKeyRecord(
@@ -274,6 +276,7 @@ export async function fetchContextKeyRecord(
   processRequest: ProcessRequestFn,
   getSigner: (author: string) => Promise<any>,
   sendDwnRpcRequest: (params: { targetDid: string; dwnEndpointUrls: string[]; message: any; data?: Blob }) => Promise<any>,
+  getDwnEndpointUrlsForTarget: (targetDid: string) => Promise<string[]>,
 ): Promise<DerivedPrivateJwk | undefined> {
   const { ownerDid, requesterDid, sourceProtocol, sourceContextId } = params;
   const protocolUri = KeyDeliveryProtocolDefinition.protocol;
@@ -323,7 +326,7 @@ export async function fetchContextKeyRecord(
   } else {
     // Remote query: participant queries the context owner's DWN
     const signer = await getSigner(requesterDid);
-    const dwnEndpointUrls = await getDwnServiceEndpointUrls(ownerDid, agent.did);
+    const dwnEndpointUrls = await getDwnEndpointUrlsForTarget(ownerDid);
 
     const recordsQuery = await dwnMessageConstructors[DwnInterface.RecordsQuery].create({
       signer,

package/src/dwn-protocol-cache.ts

@@ -7,7 +7,6 @@
  * @module
  */
 
-import type { DidUrlDereferencer } from '@enbox/dids';
 import type { PublicKeyJwk } from '@enbox/crypto';
 import type { TtlCache } from '@enbox/common';
 import type {
@@ -26,13 +25,15 @@ import type {
 
 import { KeyDerivationScheme } from '@enbox/dwn-sdk-js';
 
-import { getDwnServiceEndpointUrls } from './utils.js';
 import { DwnInterface as DwnInterfaceEnum, dwnMessageConstructors } from './types/dwn.js';
 
 // ---------------------------------------------------------------------------
 // Dependency signatures — keep the extracted code free of `this` references.
 // ---------------------------------------------------------------------------
 
+/** Callback to resolve DWN endpoint URLs for a target DID (with local discovery). */
+type GetDwnEndpointUrlsFn = (targetDid: string) => Promise<string[]>;
+
 /** Callback to obtain a DWN signer for a given DID. */
 type GetSignerFn = (author: string) => Promise<DwnSigner>;
 
@@ -106,7 +107,7 @@ export async function getProtocolDefinition(
  *
  * @param targetDid - The remote DWN owner
  * @param protocolUri - The protocol URI to look up
- * @param didDereferencer - A DID URL dereferencer for resolving service endpoints
+ * @param getDwnEndpointUrls - Callback to resolve DWN endpoint URLs (with local discovery)
  * @param sendDwnRpcRequest - Callback to send the RPC query
  * @param cache - The shared protocol definition cache
  * @returns The protocol definition
@@ -115,7 +116,7 @@ export async function getProtocolDefinition(
 export async function fetchRemoteProtocolDefinition(
   targetDid: string,
   protocolUri: string,
-  didDereferencer: DidUrlDereferencer,
+  getDwnEndpointUrls: GetDwnEndpointUrlsFn,
   sendDwnRpcRequest: SendDwnRpcRequestFn,
   cache: TtlCache<string, ProtocolDefinition>,
 ): Promise<ProtocolDefinition> {
@@ -131,7 +132,7 @@ export async function fetchRemoteProtocolDefinition(
 
   const reply = await sendDwnRpcRequest({
     targetDid,
-    dwnEndpointUrls : await getDwnServiceEndpointUrls(targetDid, didDereferencer),
+    dwnEndpointUrls : await getDwnEndpointUrls(targetDid),
     message         : protocolsQuery.message,
   }) as ProtocolsQueryReply;
 
@@ -158,7 +159,7 @@ export async function fetchRemoteProtocolDefinition(
  * @param protocolUri    - The protocol URI to search
  * @param rootContextId  - The root context ID
  * @param requesterDid   - The DID of the requester (used for signing the query)
- * @param didDereferencer - A DID URL dereferencer for resolving service endpoints
+ * @param getDwnEndpointUrls - Callback to resolve DWN endpoint URLs (with local discovery)
  * @param getSigner      - Callback to obtain the signer for `requesterDid`
  * @param sendDwnRpcRequest - Callback to send the RPC query
  * @returns The rootKeyId and derivedPublicKey, or `undefined` if no
@@ -169,7 +170,7 @@ export async function extractDerivedPublicKey(
   protocolUri: string,
   rootContextId: string,
   requesterDid: string,
-  didDereferencer: DidUrlDereferencer,
+  getDwnEndpointUrls: GetDwnEndpointUrlsFn,
   getSigner: GetSignerFn,
   sendDwnRpcRequest: SendDwnRpcRequestFn,
 ): Promise<{ rootKeyId: string; derivedPublicKey: PublicKeyJwk } | undefined> {
@@ -184,7 +185,7 @@ export async function extractDerivedPublicKey(
     },
   });
 
-  const dwnEndpointUrls = await getDwnServiceEndpointUrls(targetDid, didDereferencer);
+  const dwnEndpointUrls = await getDwnEndpointUrls(targetDid);
   const queryReply = await sendDwnRpcRequest<DwnInterfaceEnum.RecordsQuery>({
     targetDid,
     dwnEndpointUrls,

package/src/identity-api.ts

@@ -9,7 +9,6 @@ import type { IdentityMetadata, PortableIdentity } from './types/identity.js';
 import { isPortableDid } from '@enbox/dids';
 
 import { BearerIdentity } from './bearer-identity.js';
-import { getDwnServiceEndpointUrls } from './utils.js';
 import { InMemoryIdentityStore } from './store-identity.js';
 
 export interface IdentityApiParams<TKeyManager extends AgentKeyManager> {
@@ -226,7 +225,7 @@ export class AgentIdentityApi<TKeyManager extends AgentKeyManager = AgentKeyMana
    * @throws An error if the DID is not found, or no DWN service exists.
    */
   public getDwnEndpoints({ didUri }: { didUri: string; }): Promise<string[]> {
-    return getDwnServiceEndpointUrls(didUri, this.agent.did);
+    return this.agent.dwn.getDwnEndpointUrlsForTarget(didUri);
   }
 
   /**

package/src/index.ts

@@ -20,6 +20,7 @@ export * from './dwn-type-guards.js';
 export * from './protocol-utils.js';
 export * from './hd-identity-vault.js';
 export * from './identity-api.js';
+export * from './local-dwn.js';
 export * from './local-key-manager.js';
 export * from './permissions-api.js';
 export * from './store-data.js';

package/src/local-dwn.ts

@@ -0,0 +1,81 @@
+/**
+ * Local DWN discovery — probes well-known localhost ports for a running
+ * `@enbox/dwn-server` instance so the agent can route traffic to it.
+ *
+ * @module
+ */
+
+import type { Web5Rpc } from '@enbox/dwn-clients';
+
+/** Well-known ports the local DWN desktop app may bind to. */
+export const localDwnPortCandidates = [3000, 55555, 55556, 55557, 55558, 55559] as const;
+
+/** Hosts probed when discovering a local DWN server. */
+export const localDwnHostCandidates = ['127.0.0.1', 'localhost'] as const;
+
+/**
+ * Controls how the agent discovers and routes to a local DWN server.
+ *
+ * - `'prefer'` — probe localhost first; fall back to DID-document endpoints.
+ * - `'only'`   — require a local server; throw if none is found.
+ * - `'off'`    — skip local discovery entirely.
+ */
+export type LocalDwnStrategy = 'prefer' | 'only' | 'off';
+
+/** The `server` field returned by `GET /info` on `@enbox/dwn-server`. */
+export const localDwnServerName = '@enbox/dwn-server';
+
+/** Strips a trailing slash from a URL so endpoint comparisons are consistent. */
+function normalizeBaseUrl(url: string): string {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+
+/**
+ * Probes well-known localhost ports for a running `@enbox/dwn-server` instance.
+ *
+ * Results are cached for {@link _cacheTtlMs} milliseconds (default 10 s) to
+ * avoid repeated HTTP round-trips on hot paths such as sync.
+ *
+ * TODO: Replace sequential port probing with an `enbox://` protocol-handler
+ *       handshake (https://github.com/enboxorg/enbox/issues/287).
+ */
+export class LocalDwnDiscovery {
+  private _cachedEndpoint?: string;
+  private _cacheExpiry = 0;
+
+  constructor(
+    private _rpcClient: Web5Rpc,
+    private _cacheTtlMs = 10_000
+  ) {}
+
+  /**
+   * Returns the base URL of a local DWN server, or `undefined` if none is
+   * reachable on the well-known port candidates.
+   */
+  public async getEndpoint(): Promise<string | undefined> {
+    const now = Date.now();
+    if (now < this._cacheExpiry) {
+      return this._cachedEndpoint;
+    }
+
+    for (const port of localDwnPortCandidates) {
+      for (const host of localDwnHostCandidates) {
+        const endpoint = `http://${host}:${port}`;
+        try {
+          const serverInfo = await this._rpcClient.getServerInfo(endpoint);
+          if (serverInfo.server === localDwnServerName) {
+            this._cachedEndpoint = normalizeBaseUrl(endpoint);
+            this._cacheExpiry = now + this._cacheTtlMs;
+            return this._cachedEndpoint;
+          }
+        } catch {
+          // keep probing candidate endpoints
+        }
+      }
+    }
+
+    this._cachedEndpoint = undefined;
+    this._cacheExpiry = now + this._cacheTtlMs;
+    return undefined;
+  }
+}

package/src/sync-engine-level.ts

@@ -12,7 +12,6 @@ import type { Web5Agent, Web5PlatformAgent } from './types/agent.js';
 
 import { AgentPermissionsApi } from './permissions-api.js';
 import { DwnInterface } from './types/dwn.js';
-import { getDwnServiceEndpointUrls } from './utils.js';
 import { isRecordsWrite } from './utils.js';
 import { topologicalSort } from './sync-topological-sort.js';
 import { pullMessages, pushMessages } from './sync-messages.js';
@@ -1063,7 +1062,7 @@ export class SyncEngineLevel implements SyncEngine {
       }
       const { protocols, delegateDid } = parsed;
 
-      const dwnEndpointUrls = await getDwnServiceEndpointUrls(did, this.agent.did);
+      const dwnEndpointUrls = await this.agent.dwn.getDwnEndpointUrlsForTarget(did);
       if (dwnEndpointUrls.length === 0) {
         continue;
       }

package/src/test-harness.ts

@@ -277,7 +277,8 @@ export class PlatformAgentTestHarness {
     });
 
     // Instantiate Agent's DWN API using the custom DWN instance.
-    const dwnApi = new AgentDwnApi({ dwn });
+    // Disable local DWN discovery so tests don't accidentally probe localhost.
+    const dwnApi = new AgentDwnApi({ dwn, localDwnStrategy: 'off' });
 
     // Instantiate Agent's Sync API using a custom LevelDB-backed store.
     const syncStore = new Level(testDataPath('SYNC_STORE'));

package/src/web5-user-agent.ts

@@ -1,5 +1,6 @@
 import type { AgentKeyManager } from './types/key-manager.js';
 import type { BearerDid } from '@enbox/dids';
+import type { LocalDwnStrategy } from './local-dwn.js';
 import type { Web5PlatformAgent } from './types/agent.js';
 import type { Web5Rpc } from '@enbox/dwn-clients';
 import type { DidInterface, DidRequest, DidResponse } from './did-api.js';
@@ -87,6 +88,10 @@ export type AgentParams<TKeyManager extends AgentKeyManager = LocalKeyManager> =
   syncApi: AgentSyncApi;
 };
 
+export type CreateUserAgentParams = Partial<AgentParams> & {
+  localDwnStrategy?: LocalDwnStrategy;
+};
+
 export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager> implements Web5PlatformAgent<TKeyManager> {
   public crypto: AgentCryptoApi;
   public did: AgentDidApi<TKeyManager>;
@@ -140,8 +145,9 @@ export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager
    */
   public static async create({
     dataPath = 'DATA/AGENT',
+    localDwnStrategy,
     agentDid, agentVault, cryptoApi, didApi, dwnApi, identityApi, keyManager, permissionsApi, rpcClient, syncApi
-  }: Partial<AgentParams> = {}
+  }: CreateUserAgentParams = {}
   ): Promise<Web5UserAgent> {
 
     agentVault ??= new HdIdentityVault({
@@ -158,8 +164,12 @@ export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager
     });
 
     dwnApi ??= new AgentDwnApi({
-      dwn: await AgentDwnApi.createDwn({ dataPath, didResolver: didApi })
+      dwn              : await AgentDwnApi.createDwn({ dataPath, didResolver: didApi }),
+      localDwnStrategy : localDwnStrategy ?? 'prefer',
     });
+    if (localDwnStrategy) {
+      dwnApi.setLocalDwnStrategy(localDwnStrategy);
+    }
 
     identityApi ??= new AgentIdentityApi({ store: new DwnIdentityStore() });
 
@@ -250,4 +260,4 @@ export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager
     // Set the Agent's DID.
     this.agentDid = await this.vault.getDid();
   }
-}
+}