@enbox/agent 0.2.2 → 0.3.1

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
@@ -68,21 +68,16 @@ async function initClient({
     encryptionKey,
   });
 
-  // Convert the encrypted Request Object to URLSearchParams for form encoding.
-  const formEncodedRequest = new URLSearchParams({
-    request: requestObjectJwe,
-  });
-
   const pushedAuthorizationRequestEndpoint = Oidc.buildOidcUrl({
     baseURL  : connectServerUrl,
     endpoint : 'pushedAuthorizationRequest',
   });
 
   const parResponse = await fetch(pushedAuthorizationRequestEndpoint, {
-    body    : formEncodedRequest,
+    body    : JSON.stringify({ request: requestObjectJwe }),
     method  : 'POST',
     headers : {
-      'Content-Type': 'application/x-www-form-urlencoded',
+      'Content-Type': 'application/json',
     },
     signal: AbortSignal.timeout(30_000),
   });
@@ -93,8 +88,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 +107,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 +118,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 +154,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,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;
+}
+
+