@enbox/agent 0.2.1 → 0.3.0

package/src/dwn-key-delivery.ts

@@ -6,7 +6,7 @@ import type {
   RecordsReadReply,
 } from '@enbox/dwn-sdk-js';
 
-import type { Web5PlatformAgent } from './types/agent.js';
+import type { EnboxPlatformAgent } from './types/agent.js';
 import type {
   DwnMessage,
   DwnMessageReply,
@@ -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';
@@ -66,7 +65,7 @@ type ProcessRequestFn = <T extends DwnInterface>(
  * @param installedCache - Cache for installation status
  */
 export async function ensureKeyDeliveryProtocol(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   tenantDid: string,
   processRequest: ProcessRequestFn,
   getProtocolDefinition: (tenantDid: string, protocolUri: string) => Promise<any>,
@@ -121,7 +120,7 @@ export async function ensureKeyDeliveryProtocol(
  * @returns The recordId of the written contextKey record
  */
 export async function writeContextKeyRecord(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   params: WriteContextKeyParams,
   processRequest: ProcessRequestFn,
   ensureProtocol: (tenantDid: string) => Promise<void>,
@@ -219,17 +218,19 @@ 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,
+  agent: EnboxPlatformAgent,
   tenantDid: string,
   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,14 +267,16 @@ 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(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   params: FetchContextKeyParams,
   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/dwn-record-upgrade.ts

@@ -8,7 +8,7 @@ import type {
 } from '@enbox/dwn-sdk-js';
 
 import type { DwnSigner } from './types/dwn.js';
-import type { Web5PlatformAgent } from './types/agent.js';
+import type { EnboxPlatformAgent } from './types/agent.js';
 
 import {
   Encoder,
@@ -42,7 +42,7 @@ import { DwnInterface, dwnMessageConstructors } from './types/dwn.js';
  * @param contextKeyCache - Cache for context key info
  */
 export async function upgradeExternalRootRecord(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   tenantDid: string,
   recordsWrite: RecordsWriteMessage,
   dwn: Dwn,

package/src/{web5-user-agent.ts → enbox-user-agent.ts}

@@ -1,7 +1,8 @@
 import type { AgentKeyManager } from './types/key-manager.js';
 import type { BearerDid } from '@enbox/dids';
-import type { Web5PlatformAgent } from './types/agent.js';
-import type { Web5Rpc } from '@enbox/dwn-clients';
+import type { EnboxPlatformAgent } from './types/agent.js';
+import type { EnboxRpc } from '@enbox/dwn-clients';
+import type { LocalDwnStrategy } from './local-dwn.js';
 import type { DidInterface, DidRequest, DidResponse } from './did-api.js';
 import type { DwnInterface, DwnResponse, ProcessDwnRequest, SendDwnRequest } from './types/dwn.js';
 import type { ProcessVcRequest, SendVcRequest, VcResponse } from './types/vc.js';
@@ -16,15 +17,15 @@ import { AgentSyncApi } from './sync-api.js';
 import { DwnDidStore } from './store-did.js';
 import { DwnIdentityStore } from './store-identity.js';
 import { DwnKeyStore } from './store-key.js';
+import { EnboxRpcClient } from '@enbox/dwn-clients';
 import { HdIdentityVault } from './hd-identity-vault.js';
 import { LevelStore } from '@enbox/common';
 import { LocalKeyManager } from './local-key-manager.js';
 import { SyncEngineLevel } from './sync-engine-level.js';
-import { Web5RpcClient } from '@enbox/dwn-clients';
 import { DidDht, DidJwk } from '@enbox/dids';
 
 /**
- * Initialization parameters for {@link Web5UserAgent}, including an optional recovery phrase that
+ * Initialization parameters for {@link EnboxUserAgent}, including an optional recovery phrase that
  * can be used to derive keys to encrypt the vault and generate a DID.
  */
 export type AgentInitializeParams = {
@@ -45,10 +46,10 @@ export type AgentInitializeParams = {
    recoveryPhrase?: string;
 
   /**
-   * Optional dwnEndpoints to register didService endpoints during Web5UserAgent initialization
+   * Optional dwnEndpoints to register didService endpoints during EnboxUserAgent initialization
    *
    * The dwnEndpoints are used to register DWN endpoints against the agent DID created during
-   * Web5UserAgent.initialize() =>  DidDht.create(). This allows the
+   * EnboxUserAgent.initialize() =>  DidDht.create(). This allows the
    * agent to properly recover connectedDids from DWN. Also, this pattern can be used on the server
    * side in place of the agentDid-->connectedDids pattern.
    */
@@ -63,7 +64,7 @@ export type AgentStartParams = {
  };
 
 export type AgentParams<TKeyManager extends AgentKeyManager = LocalKeyManager> = {
-  /** Optional. The Decentralized Identifier (DID) representing this Web5 User Agent. */
+  /** Optional. The Decentralized Identifier (DID) representing this Enbox User Agent. */
   agentDid?: BearerDid;
   /** Encrypted vault used for managing the Agent's DID and associated keys. */
   agentVault: HdIdentityVault;
@@ -81,20 +82,24 @@ export type AgentParams<TKeyManager extends AgentKeyManager = LocalKeyManager> =
   keyManager: TKeyManager;
   /** Facilitates fetching, requesting, creating, revoking and validating revocation status of permissions */
   permissionsApi: AgentPermissionsApi;
-  /** Remote procedure call (RPC) client used to communicate with other Web5 services. */
-  rpcClient: Web5Rpc;
+  /** Remote procedure call (RPC) client used to communicate with other Enbox services. */
+  rpcClient: EnboxRpc;
   /** Facilitates data synchronization of DWN records between nodes. */
   syncApi: AgentSyncApi;
 };
 
-export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager> implements Web5PlatformAgent<TKeyManager> {
+export type CreateUserAgentParams = Partial<AgentParams> & {
+  localDwnStrategy?: LocalDwnStrategy;
+};
+
+export class EnboxUserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager> implements EnboxPlatformAgent<TKeyManager> {
   public crypto: AgentCryptoApi;
   public did: AgentDidApi<TKeyManager>;
   public dwn: AgentDwnApi;
   public identity: AgentIdentityApi<TKeyManager>;
   public keyManager: TKeyManager;
   public permissions: AgentPermissionsApi;
-  public rpc: Web5Rpc;
+  public rpc: EnboxRpc;
   public sync: AgentSyncApi;
   public vault: HdIdentityVault;
 
@@ -124,7 +129,7 @@ export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager
   get agentDid(): BearerDid {
     if (this._agentDid === undefined) {
       throw new Error(
-        'Web5UserAgent: The "agentDid" property is not set. Ensure the agent is properly ' +
+        'EnboxUserAgent: The "agentDid" property is not set. Ensure the agent is properly ' +
         'initialized and a DID is assigned.'
       );
     }
@@ -140,9 +145,10 @@ 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> = {}
-  ): Promise<Web5UserAgent> {
+  }: CreateUserAgentParams = {}
+  ): Promise<EnboxUserAgent> {
 
     agentVault ??= new HdIdentityVault({
       keyDerivationWorkFactor : 210_000,
@@ -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() });
 
@@ -167,12 +177,12 @@ export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager
 
     permissionsApi ??= new AgentPermissionsApi();
 
-    rpcClient ??= new Web5RpcClient();
+    rpcClient ??= new EnboxRpcClient();
 
     syncApi ??= new AgentSyncApi({ syncEngine: new SyncEngineLevel({ dataPath }) });
 
     // Instantiate the Agent using the provided or default components.
-    return new Web5UserAgent({
+    return new EnboxUserAgent({
       agentDid,
       agentVault,
       cryptoApi,
@@ -196,7 +206,7 @@ export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager
    *
    * This method is typically called once, the first time the Agent is launched, and is responsible
    * for setting up the agent's operational environment, cryptographic key material, and readiness
-   * for processing Web5 requests.
+   * for processing requests.
    *
    * The password is used to secure the Agent vault, and the recovery phrase is used to derive the
    * cryptographic keys for the vault. If a recovery phrase is not provided, a new recovery phrase
@@ -250,4 +260,14 @@ export class Web5UserAgent<TKeyManager extends AgentKeyManager = LocalKeyManager
     // Set the Agent's DID.
     this.agentDid = await this.vault.getDid();
   }
-}
+}
+
+// ---------------------------------------------------------------------------
+// Deprecated aliases — migration aid
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use {@link EnboxUserAgent} instead. Will be removed in a future version. */
+export const Web5UserAgent = EnboxUserAgent;
+
+/** @deprecated Use {@link EnboxUserAgent} instead. Will be removed in a future version. */
+export type Web5UserAgent = EnboxUserAgent;

package/src/identity-api.ts

@@ -3,17 +3,16 @@ import type { RequireOnly } from '@enbox/common';
 import type { AgentDataStore } from './store-data.js';
 import type { AgentKeyManager } from './types/key-manager.js';
 import type { DidMethodCreateOptions } from './did-api.js';
-import type { Web5PlatformAgent } from './types/agent.js';
+import type { EnboxPlatformAgent } from './types/agent.js';
 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> {
-  agent?: Web5PlatformAgent<TKeyManager>;
+  agent?: EnboxPlatformAgent<TKeyManager>;
 
   store?: AgentDataStore<IdentityMetadata>;
 }
@@ -37,7 +36,7 @@ export function isPortableIdentity(obj: unknown): obj is PortableIdentity {
 }
 
 /**
- * This API is used to manage and interact with Identities within the Web5 Agent framework.
+ * This API is used to manage and interact with Identities within the Enbox Agent framework.
  * An Identity is a DID that is associated with metadata that describes the Identity.
  * Metadata includes A name(label), and whether or not the Identity is connected (delegated to act on the behalf of another DID).
  *
@@ -48,12 +47,12 @@ export function isPortableIdentity(obj: unknown): obj is PortableIdentity {
  */
 export class AgentIdentityApi<TKeyManager extends AgentKeyManager = AgentKeyManager> {
   /**
-   * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
-   * the `AgentIdentityApi`. This agent is used to interact with other Web5 agent components. It's
+   * Holds the instance of a `EnboxPlatformAgent` that represents the current execution context for
+   * the `AgentIdentityApi`. 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
-   * Web5 Agent framework.
+   * Enbox Agent framework.
    */
-  private _agent?: Web5PlatformAgent<TKeyManager>;
+  private _agent?: EnboxPlatformAgent<TKeyManager>;
 
   private _store: AgentDataStore<IdentityMetadata>;
 
@@ -65,12 +64,12 @@ export class AgentIdentityApi<TKeyManager extends AgentKeyManager = AgentKeyMana
   }
 
   /**
-   * 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<TKeyManager> {
+  get agent(): EnboxPlatformAgent<TKeyManager> {
     if (this._agent === undefined) {
       throw new Error('AgentIdentityApi: Unable to determine agent execution context.');
     }
@@ -78,7 +77,7 @@ export class AgentIdentityApi<TKeyManager extends AgentKeyManager = AgentKeyMana
     return this._agent;
   }
 
-  set agent(agent: Web5PlatformAgent<TKeyManager>) {
+  set agent(agent: EnboxPlatformAgent<TKeyManager>) {
     this._agent = agent;
   }
 
@@ -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

@@ -13,6 +13,8 @@ export * from './bearer-identity.js';
 export * from './crypto-api.js';
 export * from './did-api.js';
 export * from './dwn-api.js';
+export * from './dwn-discovery-file.js';
+export * from './dwn-discovery-payload.js';
 export * from './dwn-encryption.js';
 export * from './dwn-key-delivery.js';
 export * from './dwn-record-upgrade.js';
@@ -20,6 +22,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';
@@ -32,4 +35,4 @@ export * from './test-harness.js';
 export * from './utils.js';
 export * from './connect.js';
 export * from './oidc.js';
-export * from './web5-user-agent.js';
+export * from './enbox-user-agent.js';

package/src/local-dwn.ts

@@ -0,0 +1,207 @@
+/**
+ * Local DWN discovery — discovers a running `@enbox/dwn-server` instance
+ * so the agent can route traffic to it.
+ *
+ * Discovery channels (tried in order):
+ * 1. **In-memory cache** — serves a recent positive or negative result.
+ * 2. **Discovery file** (`~/.enbox/dwn.json`) — written by `electrobun-dwn`
+ *    on startup. Fast filesystem read, no network. Available for CLI and
+ *    native apps; skipped in browsers.
+ * 3. **Port probing** (fallback) — sequential HTTP `GET /info` on well-known
+ *    localhost ports. Works everywhere but is slower.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/585
+ * @module
+ */
+
+import type { EnboxRpc } from '@enbox/dwn-clients';
+
+import type { DwnDiscoveryFile } from './dwn-discovery-file.js';
+
+/**
+ * Well-known ports the local DWN desktop app may bind to.
+ *
+ * Per the DWN Transport Spec, clients probe ports `55500` through `55509`
+ * (inclusive). Port `3000` is included as a development convenience.
+ *
+ * @see https://identity.foundation/dwn-transport/#port-probing
+ */
+export const localDwnPortCandidates = [3000, 55500, 55501, 55502, 55503, 55504, 55505, 55506, 55507, 55508, 55509] as const;
+
+/**
+ * Hosts probed when discovering a local DWN server.
+ *
+ * Per the DWN Transport Spec, clients MUST use `127.0.0.1` rather than
+ * `localhost` to avoid DNS resolution ambiguity.
+ *
+ * @see https://identity.foundation/dwn-transport/#port-probing
+ */
+export const localDwnHostCandidates = ['127.0.0.1'] as const;
+
+/**
+ * Controls how the agent discovers and routes to a local DWN server.
+ *
+ * - `'off'`    — (default) skip local discovery entirely.
+ * - `'prefer'` — probe localhost first; fall back to DID-document endpoints.
+ * - `'only'`   — require a local server; throw if none is found.
+ */
+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. */
+export function normalizeBaseUrl(url: string): string {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+
+/**
+ * Discovers a running local DWN server.
+ *
+ * Results are cached for {@link _cacheTtlMs} milliseconds (default 10 s) to
+ * avoid repeated I/O on hot paths such as sync.
+ *
+ * @example Discovery with file-based channel
+ * ```ts
+ * import { DwnDiscoveryFile } from './dwn-discovery-file.js';
+ *
+ * const discoveryFile = new DwnDiscoveryFile();
+ * const discovery = new LocalDwnDiscovery(rpcClient, 10_000, discoveryFile);
+ * const endpoint = await discovery.getEndpoint();
+ * ```
+ *
+ * @example Browser: inject cached endpoint from `dwn://register` redirect
+ * ```ts
+ * const discovery = new LocalDwnDiscovery(rpcClient);
+ * discovery.setCachedEndpoint('http://127.0.0.1:55557');
+ * ```
+ */
+export class LocalDwnDiscovery {
+  private _cachedEndpoint?: string;
+  private _cacheExpiry = 0;
+
+  constructor(
+    private _rpcClient: EnboxRpc,
+    private _cacheTtlMs = 10_000,
+    private _discoveryFile?: DwnDiscoveryFile,
+  ) {}
+
+  /**
+   * Returns the base URL of a local DWN server, or `undefined` if none
+   * is discoverable.
+   *
+   * The discovery order is:
+   * 1. In-memory cache (if not expired).
+   * 2. `~/.enbox/dwn.json` discovery file (if a {@link DwnDiscoveryFile}
+   *    was provided). The endpoint from the file is validated via
+   *    `GET /info` to ensure the server is still running.
+   * 3. Sequential port probing on well-known localhost ports (fallback).
+   */
+  public async getEndpoint(): Promise<string | undefined> {
+    const now = Date.now();
+    if (now < this._cacheExpiry) {
+      return this._cachedEndpoint;
+    }
+
+    // Channel 1: file-based discovery.
+    const fileEndpoint = await this._tryDiscoveryFile();
+    if (fileEndpoint !== undefined) {
+      this._setCacheEntry(fileEndpoint, now);
+      return fileEndpoint;
+    }
+
+    // Channel 2: sequential port probing (fallback).
+    const probeEndpoint = await this._probePortCandidates();
+    // Cache both positive and negative results.
+    this._setCacheEntry(probeEndpoint, now);
+    return probeEndpoint;
+  }
+
+  /**
+   * Inject a cached endpoint (e.g. from a `dwn://register` browser redirect
+   * or from `localStorage`). The endpoint is validated via `GET /info` before
+   * caching.
+   *
+   * @returns `true` if the endpoint was validated and cached, `false` otherwise.
+   */
+  public async setCachedEndpoint(endpoint: string): Promise<boolean> {
+    const normalized = normalizeBaseUrl(endpoint);
+    const valid = await this._validateEndpoint(normalized);
+    if (valid) {
+      this._setCacheEntry(normalized, Date.now());
+    }
+    return valid;
+  }
+
+  /**
+   * Clear the in-memory cache, forcing the next {@link getEndpoint} call
+   * to perform a fresh discovery.
+   */
+  public clearCache(): void {
+    this._cachedEndpoint = undefined;
+    this._cacheExpiry = 0;
+  }
+
+  // ─── Private discovery channels ────────────────────────────────
+
+  /**
+   * Try the `~/.enbox/dwn.json` discovery file. Returns the endpoint if
+   * the file exists, is valid, and the endpoint passes `GET /info`
+   * validation. Returns `undefined` otherwise.
+   */
+  private async _tryDiscoveryFile(): Promise<string | undefined> {
+    if (!this._discoveryFile) {
+      return undefined;
+    }
+
+    try {
+      const record = await this._discoveryFile.read();
+      if (!record) {
+        return undefined;
+      }
+
+      // Validate that the server is actually alive and is ours.
+      const valid = await this._validateEndpoint(record.endpoint);
+      return valid ? record.endpoint : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Sequential HTTP probe on well-known localhost port candidates.
+   * Returns the first endpoint whose `GET /info` response identifies
+   * as `@enbox/dwn-server`, or `undefined` if none is found.
+   */
+  private async _probePortCandidates(): Promise<string | undefined> {
+    for (const port of localDwnPortCandidates) {
+      for (const host of localDwnHostCandidates) {
+        const endpoint = `http://${host}:${port}`;
+        const valid = await this._validateEndpoint(endpoint);
+        if (valid) {
+          return normalizeBaseUrl(endpoint);
+        }
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Call `GET /info` on the endpoint and check that
+   * `serverInfo.server === '@enbox/dwn-server'`.
+   */
+  private async _validateEndpoint(endpoint: string): Promise<boolean> {
+    try {
+      const serverInfo = await this._rpcClient.getServerInfo(endpoint);
+      return serverInfo.server === localDwnServerName;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Update the in-memory cache entry. */
+  private _setCacheEntry(endpoint: string | undefined, now: number): void {
+    this._cachedEndpoint = endpoint;
+    this._cacheExpiry = now + this._cacheTtlMs;
+  }
+}