@enbox/agent 0.2.1 → 0.3.0

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;
+}
+
+

package/src/dwn-discovery-payload.ts

@@ -0,0 +1,308 @@
+/**
+ * Shared types and utilities for the `dwn://register` discovery protocol.
+ *
+ * The payload is the JSON data exchanged between the local DWN server
+ * (electrobun-dwn) and the requesting app during the `dwn://register`
+ * redirect flow. It is encoded as base64url and placed in the URL
+ * fragment (`#`) of the callback URL.
+ *
+ * This module intentionally avoids external dependencies so it can be
+ * consumed from any environment (Bun, browser, Electrobun) without
+ * triggering transitive dependency resolution issues.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/586
+ * @module
+ */
+
+// ─── Types ────────────────────────────────────────────────────────
+
+/**
+ * The JSON payload delivered via the URL fragment in a `dwn://register`
+ * callback redirect.
+ *
+ * Intentionally minimal — everything beyond the endpoint (version,
+ * WebSocket support, etc.) is obtained from `GET {endpoint}/info`.
+ */
+export type DwnDiscoveryPayload = {
+  /** Base URL of the running DWN server (e.g. `"http://127.0.0.1:55557"`). */
+  endpoint: string;
+};
+
+/**
+ * Parsed result from a `dwn://register` URL.
+ */
+export type DwnRegisterUrlParams = {
+  /** The callback URL to redirect to with the discovery payload. */
+  callback: string;
+};
+
+// ─── Constants ────────────────────────────────────────────────────
+
+/** The URL scheme for DWN discovery protocol handlers. */
+export const DWN_PROTOCOL_SCHEME = 'dwn';
+
+/** The `dwn://register` path that triggers the discovery handshake. */
+export const DWN_REGISTER_PATH = 'register';
+
+// ─── Register URL construction ───────────────────────────────────
+
+/**
+ * Build a `dwn://register?callback=<url>` URL that, when opened by the OS,
+ * triggers electrobun-dwn (or another `dwn://` scheme handler) to redirect
+ * back to `callbackUrl` with the local DWN endpoint in the URL fragment.
+ *
+ * This is the **trigger** side of the `dwn://register` browser flow.
+ * The web app opens this URL (e.g. via `window.open()` or `location.href`),
+ * the OS routes it to the registered handler, and the handler redirects
+ * back with the discovery payload.
+ *
+ * @param callbackUrl - The URL to redirect back to after discovery.
+ *   This should be the current page (or a dedicated callback page) that
+ *   will read the payload from `window.location.hash`.
+ * @returns The `dwn://register?callback=<encoded-url>` URL string.
+ *
+ * @example
+ * ```ts
+ * const registerUrl = buildDwnRegisterUrl('https://myapp.com/callback');
+ * // => 'dwn://register?callback=https%3A%2F%2Fmyapp.com%2Fcallback'
+ * window.open(registerUrl);
+ * ```
+ */
+export function buildDwnRegisterUrl(callbackUrl: string): string {
+  return `${DWN_PROTOCOL_SCHEME}://${DWN_REGISTER_PATH}?callback=${encodeURIComponent(callbackUrl)}`;
+}
+
+// ─── Payload encoding/decoding ───────────────────────────────────
+
+/**
+ * Encode a {@link DwnDiscoveryPayload} as a base64url string suitable
+ * for use in a URL fragment.
+ *
+ * @param payload - The discovery payload to encode.
+ * @returns A base64url-encoded string (no padding).
+ */
+export function encodeDwnDiscoveryPayload(payload: DwnDiscoveryPayload): string {
+  const json = JSON.stringify(payload);
+  return stringToBase64Url(json);
+}
+
+/**
+ * Decode a base64url-encoded string back into a {@link DwnDiscoveryPayload}.
+ *
+ * @param encoded - The base64url string from the URL fragment.
+ * @returns The parsed payload, or `undefined` if decoding or parsing fails.
+ */
+export function decodeDwnDiscoveryPayload(encoded: string): DwnDiscoveryPayload | undefined {
+  try {
+    const json = base64UrlToString(encoded);
+    const parsed: unknown = JSON.parse(json);
+
+    if (!isValidPayload(parsed)) {
+      return undefined;
+    }
+
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+// ─── URL parsing ─────────────────────────────────────────────────
+
+/**
+ * Parse a `dwn://register?callback=<url>` URL into its components.
+ *
+ * @param url - The full `dwn://register?callback=...` URL.
+ * @returns The parsed parameters, or `undefined` if the URL is not a
+ *   valid `dwn://register` URL or is missing the `callback` parameter.
+ */
+export function parseDwnRegisterUrl(url: string): DwnRegisterUrlParams | undefined {
+  try {
+    // dwn://register?callback=... is not a standard hierarchical URL, so
+    // we parse it manually to avoid URL constructor quirks with custom schemes.
+    const schemePrefix = `${DWN_PROTOCOL_SCHEME}://`;
+    if (!url.startsWith(schemePrefix)) {
+      return undefined;
+    }
+
+    const withoutScheme = url.slice(schemePrefix.length);
+
+    // Split on '?' to separate the path from query parameters.
+    const questionIndex = withoutScheme.indexOf('?');
+    if (questionIndex === -1) {
+      return undefined;
+    }
+
+    const path = withoutScheme.slice(0, questionIndex);
+    if (path !== DWN_REGISTER_PATH) {
+      return undefined;
+    }
+
+    const queryString = withoutScheme.slice(questionIndex + 1);
+    const params = new URLSearchParams(queryString);
+    const callback = params.get('callback');
+
+    if (!callback || callback.length === 0) {
+      return undefined;
+    }
+
+    return { callback };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build the full callback redirect URL with the discovery payload
+ * encoded in the URL fragment.
+ *
+ * @param callbackUrl - The callback URL from the `dwn://register` request.
+ * @param payload - The discovery payload to encode in the fragment.
+ * @returns The full redirect URL (e.g. `https://notes.sh/dwn#eyJ...`).
+ */
+export function buildDwnDiscoveryRedirectUrl(
+  callbackUrl: string,
+  payload: DwnDiscoveryPayload,
+): string {
+  const encoded = encodeDwnDiscoveryPayload(payload);
+  // Strip any existing fragment from the callback URL before appending ours.
+  const base = callbackUrl.split('#')[0];
+  return `${base}#${encoded}`;
+}
+
+/**
+ * Read a {@link DwnDiscoveryPayload} from a URL's fragment (hash).
+ *
+ * Intended for use in the browser callback page that receives the
+ * redirect from electrobun-dwn.
+ *
+ * @param url - The full URL including the `#` fragment, or just the
+ *   fragment string (with or without the leading `#`).
+ * @returns The parsed payload, or `undefined` if the fragment is missing
+ *   or contains an invalid payload.
+ */
+export function readDwnDiscoveryPayloadFromUrl(url: string): DwnDiscoveryPayload | undefined {
+  const hashIndex = url.indexOf('#');
+  if (hashIndex === -1) {
+    // Maybe it's just the fragment without the leading #.
+    return decodeDwnDiscoveryPayload(url);
+  }
+
+  const fragment = url.slice(hashIndex + 1);
+  if (fragment.length === 0) {
+    return undefined;
+  }
+
+  return decodeDwnDiscoveryPayload(fragment);
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────
+
+/**
+ * Type guard for a valid {@link DwnDiscoveryPayload}.
+ *
+ * The endpoint MUST point to a loopback address (`127.0.0.1`, `[::1]`,
+ * or `localhost`) because the `dwn://register` payload is only intended
+ * for local DWN discovery. Accepting arbitrary hostnames would allow a
+ * malicious payload to redirect agent traffic to a remote server.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/633
+ */
+function isValidPayload(value: unknown): value is DwnDiscoveryPayload {
+  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 (!isLoopbackEndpoint(record.endpoint)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Returns `true` if the endpoint URL's hostname resolves to a loopback
+ * address.  Accepts `127.0.0.1`, `::1` (with or without brackets), and
+ * `localhost` (bare or with any subdomain suffix, per RFC 6761 §6.3).
+ *
+ * This is a security boundary: the `dwn://register` redirect flow MUST
+ * NOT allow payloads that point to non-local servers.
+ */
+function isLoopbackEndpoint(endpoint: string): boolean {
+  try {
+    const url = new URL(endpoint);
+    const hostname = url.hostname.toLowerCase();
+
+    // IPv4 loopback: 127.0.0.1
+    if (hostname === '127.0.0.1') {
+      return true;
+    }
+
+    // IPv6 loopback: [::1] — URL.hostname strips the brackets.
+    if (hostname === '::1' || hostname === '[::1]') {
+      return true;
+    }
+
+    // `localhost` or any subdomain (e.g. `foo.localhost`).
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Encode a UTF-8 string as unpadded base64url (RFC 4648 §5).
+ *
+ * Uses `TextEncoder` to correctly handle all Unicode code points
+ * (including those above U+00FF that `btoa` cannot represent).
+ *
+ * This module MUST remain dependency-free — no imports from
+ * `@enbox/common` or any other package.
+ */
+function stringToBase64Url(input: string): string {
+  const bytes = new TextEncoder().encode(input);
+  // Build a binary string from the UTF-8 byte array so `btoa` can
+  // consume it (btoa only accepts Latin-1 / code points ≤ U+00FF).
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * Decode an unpadded base64url string back to a UTF-8 string.
+ *
+ * Re-adds padding and swaps base64url characters back to standard
+ * base64 before calling `atob`, then feeds the resulting bytes through
+ * `TextDecoder` for correct UTF-8 handling.
+ */
+function base64UrlToString(input: string): string {
+  // Restore standard base64 alphabet and padding.
+  let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+  const remainder = base64.length % 4;
+  if (remainder === 2) {
+    base64 += '==';
+  } else if (remainder === 3) {
+    base64 += '=';
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new TextDecoder().decode(bytes);
+}

package/src/dwn-encryption.ts

@@ -9,7 +9,7 @@ import type {
 } from '@enbox/dwn-sdk-js';
 import type { KeyIdentifier, PublicKeyJwk } from '@enbox/crypto';
 
-import type { Web5PlatformAgent } from './types/agent.js';
+import type { EnboxPlatformAgent } from './types/agent.js';
 import type {
   DwnMessageReply,
   ProcessDwnRequest,
@@ -93,7 +93,7 @@ export async function encryptAndComputeCid(
  * @throws If the DID has no keyAgreement verification method or it's not X25519.
  */
 export async function getEncryptionKeyInfo(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   didUri: string,
 ): Promise<{
   keyId: string;
@@ -172,7 +172,7 @@ export async function getEncryptionKeyInfo(
  * @param iv - Initialization vector
  */
 export async function deriveContextEncryptionInput(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   didUri: string,
   contextId: string,
   dek: Uint8Array,
@@ -208,7 +208,7 @@ export async function deriveContextEncryptionInput(
  * @param derivationScheme - The key derivation scheme
  */
 export function buildKmsDecryptCallback(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   keyId: string,
   keyUri: KeyIdentifier,
   derivationScheme: typeof KeyDerivationScheme.ProtocolPath | typeof KeyDerivationScheme.ProtocolContext,
@@ -240,7 +240,7 @@ export function buildKmsDecryptCallback(
  * @returns An EncryptionKeyDeriver callback object
  */
 export async function getEncryptionKeyDeriver(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   didUri: string,
 ): Promise<EncryptionKeyDeriver> {
   const { keyId, keyUri } = await getEncryptionKeyInfo(agent, didUri);
@@ -266,7 +266,7 @@ export async function getEncryptionKeyDeriver(
  * @returns A KeyDecrypter callback object
  */
 export async function getKeyDecrypter(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   didUri: string,
 ): Promise<KeyDecrypter> {
   const { keyId, keyUri } = await getEncryptionKeyInfo(agent, didUri);
@@ -311,7 +311,7 @@ export function buildContextKeyDecrypter(
  * @param fetchContextKeyRecordFn - Function to fetch context key records from key-delivery protocol
  */
 export async function resolveKeyDecrypter(
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   authorDid: string,
   recordsWrite: RecordsWriteMessage,
   targetDid: string | undefined,
@@ -409,7 +409,7 @@ export async function resolveKeyDecrypter(
 export async function maybeDecryptReply<T extends DwnInterface>(
   request: ProcessDwnRequest<T> | SendDwnRequest<T>,
   reply: DwnMessageReply[T],
-  agent: Web5PlatformAgent,
+  agent: EnboxPlatformAgent,
   contextDerivedKeyCache: { get(key: string): DerivedPrivateJwk | undefined; set(key: string, value: DerivedPrivateJwk): void },
   fetchContextKeyRecordFn: (params: {
     ownerDid: string;