@enbox/agent 0.2.2 → 0.3.0

package/src/dwn-api.ts

@@ -33,8 +33,8 @@ import {
 import { CryptoUtils, X25519 } from '@enbox/crypto';
 import { DidDht, DidJwk, DidResolverCacheLevel, UniversalResolver } from '@enbox/dids';
 
+import type { EnboxPlatformAgent } from './types/agent.js';
 import type { LocalDwnStrategy } from './local-dwn.js';
-import type { Web5PlatformAgent } from './types/agent.js';
 import type {
   DwnMessage,
   DwnMessageInstance,
@@ -48,6 +48,7 @@ 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';
@@ -101,7 +102,7 @@ type DwnMessageWithBlob<T extends DwnInterface> = {
 };
 
 type DwnApiParams = {
-  agent?: Web5PlatformAgent;
+  agent?: EnboxPlatformAgent;
   dwn: Dwn;
   localDwnStrategy?: LocalDwnStrategy;
 };
@@ -112,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.
@@ -177,17 +178,21 @@ export class AgentDwnApi {
 
     // If agent is already available, eagerly initialize the discovery instance.
     if (agent) {
-      this._localDwnDiscovery = new LocalDwnDiscovery(agent.rpc);
+      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.');
     }
@@ -195,10 +200,14 @@ 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);
+    this._localDwnDiscovery = new LocalDwnDiscovery(
+      agent.rpc,
+      10_000,
+      AgentDwnApi._tryCreateDiscoveryFile(),
+    );
     this._localManagedDidCache.clear();
   }
 
@@ -210,6 +219,24 @@ export class AgentDwnApi {
     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
@@ -231,7 +258,7 @@ export class AgentDwnApi {
       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}`
+          `on 127.0.0.1:{3000,55500-55509}`
         );
       }
 
@@ -259,12 +286,30 @@ export class AgentDwnApi {
     return [...uniqueEndpoints];
   }
 
-  /** Lazily retrieves the local DWN server endpoint via discovery probing. */
+  /** Lazily retrieves the local DWN server endpoint via discovery. */
   private async getLocalDwnEndpoint(): Promise<string | undefined> {
-    this._localDwnDiscovery ??= new LocalDwnDiscovery(this.agent.rpc);
+    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
@@ -315,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 {

package/src/dwn-discovery-file.ts

@@ -0,0 +1,305 @@
+/**
+ * File-based local DWN discovery for CLI and native apps.
+ *
+ * When `electrobun-dwn` (or any local DWN server) starts, it writes a
+ * well-known file (`~/.enbox/dwn.json`) containing the DWN endpoint URL
+ * and the server PID. CLI tools and native apps read this file to discover
+ * the local DWN without port probing.
+ *
+ * The filesystem operations are abstracted behind {@link DiscoveryFileFs}
+ * so the module can be tested without touching the real filesystem, and
+ * adapted to runtimes that provide different I/O primitives.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/587
+ * @module
+ */
+
+import { normalizeBaseUrl } from './local-dwn.js';
+
+// ─── Types ────────────────────────────────────────────────────────
+
+/**
+ * The JSON shape persisted in the discovery file.
+ *
+ * @see https://identity.foundation/dwn-transport/#discovery-file
+ */
+export interface DwnDiscoveryRecord {
+  /** Base URL of the running DWN server (e.g. `"http://127.0.0.1:55500"`). */
+  endpoint: string;
+  /** OS process ID of the DWN server. Used for liveness checking. */
+  pid: number;
+  /**
+   * Transport capabilities advertised by the server (e.g. `["http", "ws"]`).
+   * Optional per the DWN Transport Spec.
+   */
+  capabilities?: string[];
+}
+
+/**
+ * Minimal filesystem interface required by {@link DwnDiscoveryFile}.
+ *
+ * Consumers can provide a custom implementation for testing or for
+ * runtimes that do not expose Node-compatible `fs` and `os` modules.
+ */
+export interface DiscoveryFileFs {
+  /** Read the file at `path` and return its UTF-8 contents, or `null` if not found. */
+  readFile(path: string): Promise<string | null>;
+  /** Write `contents` to the file at `path`, creating parent directories as needed. */
+  writeFile(path: string, contents: string): Promise<void>;
+  /** Delete the file at `path`. Must not throw if the file does not exist. */
+  removeFile(path: string): Promise<void>;
+  /** Return `true` if the process with the given PID is alive. */
+  isProcessAlive(pid: number): boolean;
+  /** Return the user's home directory (e.g. `/home/alice`). */
+  homedir(): string;
+}
+
+// ─── Default Node/Bun filesystem implementation ──────────────────
+
+/**
+ * Creates a {@link DiscoveryFileFs} backed by Node.js / Bun built-in
+ * modules. Returns `undefined` in environments where `node:fs/promises`
+ * or `node:os` are not available (e.g. browsers).
+ */
+export function createNodeDiscoveryFileFs(): DiscoveryFileFs | undefined {
+  try {
+    // Dynamic require avoids hard dependency on Node built-ins so bundlers
+    // can tree-shake this path away in browser builds.
+    const nodeRequire = require;
+    const fs = nodeRequire('node:fs/promises') as {
+      readFile(path: string, encoding: string): Promise<string>;
+      writeFile(path: string, data: string, options: { encoding: string; mode?: number }): Promise<void>;
+      mkdir(path: string, options: { recursive: boolean }): Promise<string | undefined>;
+      unlink(path: string): Promise<void>;
+    };
+    const path = nodeRequire('node:path') as {
+      join(...segments: string[]): string;
+      dirname(path: string): string;
+    };
+    const os = nodeRequire('node:os') as {
+      homedir(): string;
+    };
+
+    return {
+      async readFile(filePath: string): Promise<string | null> {
+        try {
+          return await fs.readFile(filePath, 'utf-8');
+        } catch {
+          return null;
+        }
+      },
+
+      async writeFile(filePath: string, contents: string): Promise<void> {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        // mode 0o600: owner read/write only — the file contains the PID
+        // and endpoint of a local DWN server.
+        await fs.writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
+      },
+
+      async removeFile(filePath: string): Promise<void> {
+        try {
+          await fs.unlink(filePath);
+        } catch {
+          // Ignore ENOENT — the file was already gone.
+        }
+      },
+
+      isProcessAlive(pid: number): boolean {
+        try {
+          process.kill(pid, 0);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+
+      homedir(): string {
+        return os.homedir();
+      },
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+// ─── Constants ────────────────────────────────────────────────────
+
+/**
+ * Directory under the user's home where the discovery file lives.
+ * Shared with the `electrobun-dwn` app and other Enbox tooling.
+ */
+export const DISCOVERY_DIR = '.enbox';
+
+/** Filename of the discovery file. */
+export const DISCOVERY_FILENAME = 'dwn.json';
+
+// ─── DwnDiscoveryFile ────────────────────────────────────────────
+
+/**
+ * Reads, writes, and validates the `~/.enbox/dwn.json` discovery file.
+ *
+ * This is the **file-based discovery channel** for CLI and native apps.
+ * It is complementary to the `dwn://register` browser redirect flow.
+ *
+ * @example Reading the discovery file
+ * ```ts
+ * const discoveryFile = new DwnDiscoveryFile();
+ * const record = await discoveryFile.read();
+ *
+ * if (record) {
+ *   console.log(`Local DWN at ${record.endpoint}`);
+ * }
+ * ```
+ *
+ * @example Writing the discovery file (from electrobun-dwn)
+ * ```ts
+ * const discoveryFile = new DwnDiscoveryFile();
+ * await discoveryFile.write({
+ *   endpoint : 'http://127.0.0.1:55557',
+ *   pid      : process.pid,
+ * });
+ * ```
+ */
+export class DwnDiscoveryFile {
+  private readonly _fs: DiscoveryFileFs;
+  private readonly _filePath: string;
+
+  /**
+   * @param fs - Filesystem adapter. Defaults to Node/Bun built-ins.
+   * @param filePath - Override the discovery file path (mainly for testing).
+   * @throws If no filesystem adapter is available (e.g. in a browser).
+   */
+  constructor(fs?: DiscoveryFileFs, filePath?: string) {
+    const resolvedFs = fs ?? createNodeDiscoveryFileFs();
+    if (!resolvedFs) {
+      throw new Error(
+        'DwnDiscoveryFile: No filesystem adapter available. ' +
+        'Provide a DiscoveryFileFs implementation or run in Node.js / Bun.'
+      );
+    }
+    this._fs = resolvedFs;
+
+    if (filePath) {
+      this._filePath = filePath;
+    } else {
+      // Dynamic require so we can resolve the path at construction time.
+      const nodeRequire = require;
+      const path = nodeRequire('node:path') as { join(...segments: string[]): string };
+      this._filePath = path.join(resolvedFs.homedir(), DISCOVERY_DIR, DISCOVERY_FILENAME);
+    }
+  }
+
+  /** The absolute path of the discovery file. */
+  public get path(): string {
+    return this._filePath;
+  }
+
+  /**
+   * Read and validate the discovery file.
+   *
+   * Returns the parsed {@link DwnDiscoveryRecord} if:
+   * 1. The file exists and contains valid JSON.
+   * 2. The `endpoint` is a non-empty string.
+   * 3. The `pid` is a positive integer whose process is still alive.
+   *
+   * Returns `undefined` in all other cases (missing file, parse error,
+   * stale PID). Stale files are automatically removed.
+   */
+  public async read(): Promise<DwnDiscoveryRecord | undefined> {
+    const raw = await this._fs.readFile(this._filePath);
+    if (raw === null) {
+      return undefined;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // Corrupted file — remove it.
+      await this._fs.removeFile(this._filePath);
+      return undefined;
+    }
+
+    if (!isValidRecord(parsed)) {
+      await this._fs.removeFile(this._filePath);
+      return undefined;
+    }
+
+    // Check that the server process is still alive.
+    if (!this._fs.isProcessAlive(parsed.pid)) {
+      await this._fs.removeFile(this._filePath);
+      return undefined;
+    }
+
+    const result: DwnDiscoveryRecord = {
+      endpoint : normalizeBaseUrl(parsed.endpoint),
+      pid      : parsed.pid,
+    };
+
+    if (parsed.capabilities !== undefined) {
+      result.capabilities = parsed.capabilities;
+    }
+
+    return result;
+  }
+
+  /**
+   * Write the discovery file. Creates the `~/.enbox/` directory if needed.
+   *
+   * @param record - The endpoint and PID to persist.
+   */
+  public async write(record: DwnDiscoveryRecord): Promise<void> {
+    const serialized: Record<string, unknown> = {
+      endpoint : normalizeBaseUrl(record.endpoint),
+      pid      : record.pid,
+    };
+
+    if (record.capabilities !== undefined && record.capabilities.length > 0) {
+      serialized.capabilities = record.capabilities;
+    }
+
+    const json = JSON.stringify(serialized, null, 2);
+    await this._fs.writeFile(this._filePath, json);
+  }
+
+  /**
+   * Remove the discovery file. Does not throw if the file is already gone.
+   */
+  public async remove(): Promise<void> {
+    await this._fs.removeFile(this._filePath);
+  }
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────
+
+/** Type guard for a valid {@link DwnDiscoveryRecord}. */
+function isValidRecord(value: unknown): value is DwnDiscoveryRecord {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  if (typeof record.endpoint !== 'string' || record.endpoint.length === 0) {
+    return false;
+  }
+
+  if (typeof record.pid !== 'number' || !Number.isInteger(record.pid) || record.pid <= 0) {
+    return false;
+  }
+
+  // `capabilities` is optional, but when present must be a string array.
+  if (record.capabilities !== undefined) {
+    if (!Array.isArray(record.capabilities)) {
+      return false;
+    }
+
+    if (!record.capabilities.every((item: unknown) => typeof item === 'string')) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+