@enbox/agent 0.3.1 → 0.5.0

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@enbox/agent",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
   "scripts": {
-    "clean": "rimraf dist",
-    "build:esm": "rimraf dist/esm dist/types && bun tsc -p tsconfig.json",
-    "build:browser": "rimraf dist/browser.mjs && bun ../../build/browser-bundle.js --node-shims",
+    "clean": "rm -rf dist",
+    "build:esm": "rm -rf dist/esm dist/types && bun tsc -p tsconfig.json",
+    "build:browser": "rm -rf dist/browser.mjs && bun ../../build/browser-bundle.js --node-shims",
     "build": "bun run clean && bun run build:esm && bun run build:browser",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",
@@ -71,32 +71,30 @@
   },
   "dependencies": {
     "@scure/bip39": "1.2.2",
-    "@enbox/dwn-clients": "0.1.0",
-    "@enbox/dwn-sdk-js": "0.1.2",
-    "@enbox/common": "0.0.7",
-    "@enbox/crypto": "0.0.8",
-    "@enbox/dids": "0.0.9",
+    "@enbox/dwn-clients": "0.2.0",
+    "@enbox/dwn-sdk-js": "0.2.0",
+    "@enbox/common": "0.1.0",
+    "@enbox/crypto": "0.1.0",
+    "@enbox/dids": "0.1.0",
     "abstract-level": "1.0.4",
     "ed25519-keygen": "0.4.11",
-    "level": "8.0.0",
+    "level": "8.0.1",
     "ms": "2.1.3",
     "ulidx": "2.1.0"
   },
   "devDependencies": {
     "@types/dns-packet": "5.6.4",
-    "@types/ms": "0.7.31",
-    "@types/node": "20.14.8",
+    "@types/ms": "0.7.34",
+    "@types/node": "22.19.15",
     "@types/sinon": "17.0.3",
     "@typescript-eslint/eslint-plugin": "8.32.1",
     "@typescript-eslint/parser": "8.32.1",
     "@vitest/browser-playwright": "4.0.18",
     "@vitest/coverage-istanbul": "4.0.18",
-    "abstract-level": "1.0.4",
-    "bun-types": "latest",
+    "bun-types": "1.3.10",
     "eslint": "9.7.0",
-    "rimraf": "4.4.0",
     "sinon": "18.0.0",
-    "typescript": "5.5.4",
+    "typescript": "5.9.3",
     "vitest": "4.0.18"
   }
 }

package/src/dwn-api.ts

@@ -86,8 +86,9 @@ import {
   writeContextKeyRecord as writeContextKeyRecordFn,
 } from './dwn-key-delivery.js';
 
-// Import extracted record upgrade function
-import { upgradeExternalRootRecord as upgradeExternalRootRecordFn } from './dwn-record-upgrade.js';
+// NOTE: upgradeExternalRootRecord is disabled — see TODO in postWriteKeyDelivery().
+// The module is kept for reference but no longer imported.
+// import { upgradeExternalRootRecord as upgradeExternalRootRecordFn } from './dwn-record-upgrade.js';
 
 // Import extracted protocol definition fetching functions
 import {
@@ -103,9 +104,11 @@ type DwnMessageWithBlob<T extends DwnInterface> = {
 
 type DwnApiParams = {
   agent?: EnboxPlatformAgent;
-  dwn: Dwn;
   localDwnStrategy?: LocalDwnStrategy;
-};
+} & (
+  | { dwn: Dwn; localDwnEndpoint?: never }
+  | { dwn?: never; localDwnEndpoint: string }
+);
 
 interface DwnApiCreateDwnParams extends Partial<DwnConfig> {
   dataPath?: string;
@@ -122,8 +125,17 @@ export class AgentDwnApi {
 
   /**
    * The DWN instance to use for this API.
+   * `undefined` in remote mode — all operations route through RPC to
+   * the local DWN server endpoint.
+   */
+  private _dwn?: Dwn;
+
+  /**
+   * The local DWN server endpoint for remote mode.
+   * When set, `_dwn` is `undefined` and `processRequest()` routes
+   * through `sendDwnRpcRequest()`.
    */
-  private _dwn: Dwn;
+  private _localDwnEndpoint?: string;
 
   /**
    * Protocol definition cache — TTL 30 minutes. Protocols rarely change.
@@ -166,12 +178,17 @@ export class AgentDwnApi {
   /** Lazy-initialized local DWN discovery instance. */
   private _localDwnDiscovery?: LocalDwnDiscovery;
 
-  constructor({ agent, dwn, localDwnStrategy = 'prefer' }: DwnApiParams) {
+  constructor(params: DwnApiParams) {
+    const { agent, localDwnStrategy = 'prefer' } = params;
+
     // 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 DWN instance (undefined in remote mode).
+    this._dwn = 'dwn' in params ? params.dwn : undefined;
+
+    // Set the remote endpoint (undefined in local mode).
+    this._localDwnEndpoint = 'localDwnEndpoint' in params ? params.localDwnEndpoint : undefined;
 
     // Set the local DWN discovery strategy.
     this._localDwnStrategy = localDwnStrategy;
@@ -186,6 +203,14 @@ export class AgentDwnApi {
     }
   }
 
+  /**
+   * Whether the API is operating in remote mode (no in-process DWN).
+   * In remote mode, all DWN operations are routed through RPC.
+   */
+  get isRemoteMode(): boolean {
+    return this._dwn === undefined;
+  }
+
   /**
    * Retrieves the `EnboxPlatformAgent` execution context.
    *
@@ -220,7 +245,7 @@ export class AgentDwnApi {
   }
 
   /**
-   * Inject a cached local DWN endpoint (e.g. from a `dwn://register`
+   * Inject a cached local DWN endpoint (e.g. from a `dwn://connect`
    * browser redirect or from persisted storage). The endpoint is validated
    * via `GET /info` before being accepted.
    *
@@ -257,8 +282,8 @@ export class AgentDwnApi {
     if (this._localDwnStrategy === 'only') {
       if (!localDwnEndpoint) {
         throw new Error(
-          `AgentDwnApi: Local DWN strategy is 'only' but no local server is available ` +
-          `on 127.0.0.1:{3000,55500-55509}`
+          `AgentDwnApi: Local DWN strategy is 'only' but no local DWN endpoint was discovered. ` +
+          `Ensure the local DWN server is running and discoverable via the discovery file (~/.enbox/dwn.json) or dwn://connect.`
         );
       }
 
@@ -288,6 +313,11 @@ export class AgentDwnApi {
 
   /** Lazily retrieves the local DWN server endpoint via discovery. */
   private async getLocalDwnEndpoint(): Promise<string | undefined> {
+    // In remote mode, the endpoint is always known.
+    if (this._localDwnEndpoint) {
+      return this._localDwnEndpoint;
+    }
+
     this._localDwnDiscovery ??= new LocalDwnDiscovery(
       this.agent.rpc,
       10_000,
@@ -364,6 +394,14 @@ export class AgentDwnApi {
    *   the DWN instance and not `agent.dwn.dwn`.
    */
   get node(): Dwn {
+    if (!this._dwn) {
+      throw new Error(
+        'AgentDwnApi: The in-process DWN instance is not available. ' +
+        'The agent is operating in remote mode (local DWN server at ' +
+        `'${this._localDwnEndpoint}'). Use processRequest() instead ` +
+        'of accessing the DWN node directly.'
+      );
+    }
     return this._dwn;
   }
 
@@ -407,10 +445,35 @@ export class AgentDwnApi {
     //   processing, passing along the target DID, the message, and any associated data stream.
     // - If `store` is set to false, it immediately returns a simulated 'accepted' status without
     //   storing the message/data in the DWN node.
-    const reply: DwnMessageReply[T] = (request.store !== false)
-      ? await this._dwn.processMessage(request.target, message, { dataStream: dataStream as any, subscriptionHandler })
-      : { status: { code: 202, detail: 'Accepted' } };
+    let reply: DwnMessageReply[T];
+
+    if (request.store === false) {
+      reply = { status: { code: 202, detail: 'Accepted' } };
+    } else if (this._dwn) {
+      // Local mode: process directly with the in-process DWN.
+      reply = await this._dwn.processMessage(
+        request.target, message,
+        { dataStream: dataStream as any, subscriptionHandler },
+      );
+    } else {
+      // Remote mode: route through RPC to the local DWN server.
+      // TODO(#713): This buffers the entire stream into memory before
+      // re-streaming it over HTTP. The RPC transport should accept a
+      // ReadableStream directly to avoid the extra copy.
+      let data: Blob | undefined;
+      if (dataStream) {
+        const bytes = await DataStream.toBytes(dataStream);
+        data = new Blob([bytes as BlobPart]);
+      }
 
+      reply = await this.sendDwnRpcRequest({
+        targetDid       : request.target,
+        dwnEndpointUrls : [this._localDwnEndpoint!],
+        message,
+        data,
+        subscriptionHandler,
+      });
+    }
 
     // Post-write key delivery: detect new participants and write contextKey records.
     await this.postWriteKeyDelivery(request, message, reply);
@@ -427,6 +490,46 @@ export class AgentDwnApi {
     };
   }
 
+  /**
+   * Process a pre-constructed DWN message against the local DWN (in-process
+   * or remote server). Used by the sync engine to store messages that were
+   * already fetched from a remote DWN.
+   *
+   * Unlike {@link processRequest}, this method does NOT construct a new
+   * message — it takes an already-signed `GenericMessage` and routes it
+   * to the appropriate backend.
+   *
+   * @param tenant - The DID of the DWN tenant (target).
+   * @param message - The pre-constructed DWN message.
+   * @param options - Optional data stream and subscription handler.
+   * @returns The reply from processing the message.
+   */
+  public async processRawMessage(
+    tenant: string,
+    message: GenericMessage,
+    options?: { dataStream?: ReadableStream<Uint8Array> },
+  ): Promise<{ status: { code: number; detail: string } }> {
+    if (this._dwn) {
+      return this._dwn.processMessage(tenant, message, { dataStream: options?.dataStream });
+    }
+
+    // TODO(#713): This buffers the entire stream into memory before
+    // re-streaming it over HTTP. The RPC transport should accept a
+    // ReadableStream directly to avoid the extra copy.
+    let data: Blob | undefined;
+    if (options?.dataStream) {
+      const bytes = await DataStream.toBytes(options.dataStream);
+      data = new Blob([bytes as BlobPart]);
+    }
+
+    return this.sendDwnRpcRequest({
+      targetDid       : tenant,
+      dwnEndpointUrls : [this._localDwnEndpoint!],
+      message         : message as DwnMessage[DwnInterface],
+      data,
+    });
+  }
+
   public async sendRequest<T extends DwnInterface>(
     request: SendDwnRequest<T>
   ): Promise<DwnResponse<T>> {
@@ -547,17 +650,31 @@ export class AgentDwnApi {
       const isMultiParty = isMultiPartyContextFn(protocolDefinition, rootPathSegment);
 
       if (isExternallyAuthored && isRootRecord && isMultiParty) {
-        try {
-          await upgradeExternalRootRecordFn(
-            this.agent, request.target, recordsWriteMessage,
-            this._dwn, this.getSigner.bind(this), this._contextKeyCache,
-          );
-        } catch (upgradeError: any) {
-          console.warn(
-            `AgentDwnApi: Reactive root-record upgrade failed for ` +
-            `'${recordsWriteMessage.recordId}': ${upgradeError.message}`
-          );
-        }
+        // TODO: Reactive root-record upgrade is disabled and needs redesign.
+        //
+        // The previous implementation (`upgradeExternalRootRecord` in
+        // `dwn-record-upgrade.ts`) bypassed DWN SDK conflict resolution by
+        // directly manipulating messageStore/stateIndex/eventLog internals.
+        // This is incompatible with remote DWN operation (local DWN server
+        // accessed via RPC) where the agent has no direct access to the
+        // server's storage layer.
+        //
+        // The correct approach is either:
+        //   (a) Perform the upgrade BEFORE the initial processMessage() call
+        //       (pre-store augmentation), so the message is stored in its
+        //       final form on the first pass — no replacement needed.
+        //   (b) Add DWN SDK support for same-timestamp owner-augmented
+        //       replacements in the RecordsWrite handler.
+        //
+        // Bumping messageTimestamp is NOT viable because the author's
+        // signature payload contains descriptorCid (which includes the
+        // timestamp). The owner does not have the external author's signing
+        // key and cannot re-sign.
+        //
+        // Until this is redesigned, externally-authored root records in
+        // multi-party encrypted contexts will only have ProtocolPath
+        // encryption. Context key holders will not be able to decrypt
+        // these records via ProtocolContext.
       }
 
       const newParticipants = detectNewParticipantsFn({
@@ -1160,6 +1277,17 @@ export class AgentDwnApi {
     tenantDid: string,
     protocolUri: string,
   ): Promise<ProtocolDefinition | undefined> {
+    if (!this._dwn) {
+      // Remote mode: query via RPC (same as fetchRemoteProtocolDefinition,
+      // but for locally-managed DIDs). The remote protocol definition
+      // cache uses a different key prefix, so we use a dedicated call.
+      try {
+        return await this.fetchRemoteProtocolDefinition(tenantDid, protocolUri);
+      } catch {
+        // Protocol not found — return undefined (consistent with local mode).
+        return undefined;
+      }
+    }
     return getProtocolDefinitionFn(
       tenantDid, protocolUri, this._dwn,
       this.getSigner.bind(this), this._protocolDefinitionCache,
@@ -1233,7 +1361,19 @@ export class AgentDwnApi {
       signer
     });
 
-    const result = await this._dwn.processMessage(author, messagesRead.message);
+    let result: any;
+
+    if (this._dwn) {
+      // Local mode: process directly with the in-process DWN.
+      result = await this._dwn.processMessage(author, messagesRead.message);
+    } else {
+      // Remote mode: route through RPC to the local DWN server.
+      result = await this.sendDwnRpcRequest({
+        targetDid       : author,
+        dwnEndpointUrls : [this._localDwnEndpoint!],
+        message         : messagesRead.message,
+      });
+    }
 
     if (result.status.code !== 200) {
       throw new Error(`AgentDwnApi: Failed to read message, response status: ${result.status.code} - ${result.status.detail}`);
@@ -1245,9 +1385,15 @@ export class AgentDwnApi {
     const dwnMessageWithBlob: DwnMessageWithBlob<T> = { message };
     // If the message is a RecordsWrite, data will be present in the form of a stream
 
-    if (isRecordsWrite(messageEntry) && messageEntry.data) {
-      const dataBytes = await DataStream.toBytes(messageEntry.data);
-      dwnMessageWithBlob.data = new Blob([ dataBytes ], { type: messageEntry.message.descriptor.dataFormat });
+    if (isRecordsWrite(messageEntry)) {
+      // The processMessage result includes a `data` ReadableStream for
+      // RecordsWrite entries, but the RecordsWrite type doesn't declare
+      // it. Access via index signature to avoid the type mismatch.
+      const entryData = (messageEntry as unknown as Record<string, unknown>)['data'] as ReadableStream<Uint8Array> | undefined;
+      if (entryData) {
+        const dataBytes = await DataStream.toBytes(entryData);
+        dwnMessageWithBlob.data = new Blob([ dataBytes as BlobPart ], { type: messageEntry.message.descriptor.dataFormat });
+      }
     }
 
     return dwnMessageWithBlob;

package/src/dwn-discovery-file.ts

@@ -139,7 +139,7 @@ export const DISCOVERY_FILENAME = 'dwn.json';
  * 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.
+ * It is complementary to the `dwn://connect` browser redirect flow.
  *
  * @example Reading the discovery file
  * ```ts

package/src/dwn-discovery-payload.ts

@@ -1,8 +1,8 @@
 /**
- * Shared types and utilities for the `dwn://register` discovery protocol.
+ * Shared types and utilities for the `dwn://connect` discovery protocol.
  *
  * The payload is the JSON data exchanged between the local DWN server
- * (electrobun-dwn) and the requesting app during the `dwn://register`
+ * (electrobun-dwn) and the requesting app during the `dwn://connect`
  * redirect flow. It is encoded as base64url and placed in the URL
  * fragment (`#`) of the callback URL.
  *
@@ -10,14 +10,13 @@
  * 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`
+ * The JSON payload delivered via the URL fragment in a `dwn://connect`
  * callback redirect.
  *
  * Intentionally minimal — everything beyond the endpoint (version,
@@ -29,9 +28,9 @@ export type DwnDiscoveryPayload = {
 };
 
 /**
- * Parsed result from a `dwn://register` URL.
+ * Parsed result from a `dwn://connect` URL.
  */
-export type DwnRegisterUrlParams = {
+export type DwnConnectUrlParams = {
   /** The callback URL to redirect to with the discovery payload. */
   callback: string;
 };
@@ -41,17 +40,17 @@ export type DwnRegisterUrlParams = {
 /** 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';
+/** The `dwn://connect` path that triggers the discovery handshake. */
+export const DWN_CONNECT_PATH = 'connect';
 
 // ─── Register URL construction ───────────────────────────────────
 
 /**
- * Build a `dwn://register?callback=<url>` URL that, when opened by the OS,
+ * Build a `dwn://connect?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.
+ * This is the **trigger** side of the `dwn://connect` 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.
@@ -59,17 +58,17 @@ export const DWN_REGISTER_PATH = 'register';
  * @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.
+ * @returns The `dwn://connect?callback=<encoded-url>` URL string.
  *
  * @example
  * ```ts
- * const registerUrl = buildDwnRegisterUrl('https://myapp.com/callback');
- * // => 'dwn://register?callback=https%3A%2F%2Fmyapp.com%2Fcallback'
+ * const registerUrl = buildDwnConnectUrl('https://myapp.com/callback');
+ * // => 'dwn://connect?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)}`;
+export function buildDwnConnectUrl(callbackUrl: string): string {
+  return `${DWN_PROTOCOL_SCHEME}://${DWN_CONNECT_PATH}?callback=${encodeURIComponent(callbackUrl)}`;
 }
 
 // ─── Payload encoding/decoding ───────────────────────────────────
@@ -110,15 +109,15 @@ export function decodeDwnDiscoveryPayload(encoded: string): DwnDiscoveryPayload
 // ─── URL parsing ─────────────────────────────────────────────────
 
 /**
- * Parse a `dwn://register?callback=<url>` URL into its components.
+ * Parse a `dwn://connect?callback=<url>` URL into its components.
  *
- * @param url - The full `dwn://register?callback=...` URL.
+ * @param url - The full `dwn://connect?callback=...` URL.
  * @returns The parsed parameters, or `undefined` if the URL is not a
- *   valid `dwn://register` URL or is missing the `callback` parameter.
+ *   valid `dwn://connect` URL or is missing the `callback` parameter.
  */
-export function parseDwnRegisterUrl(url: string): DwnRegisterUrlParams | undefined {
+export function parseDwnConnectUrl(url: string): DwnConnectUrlParams | undefined {
   try {
-    // dwn://register?callback=... is not a standard hierarchical URL, so
+    // dwn://connect?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)) {
@@ -134,7 +133,7 @@ export function parseDwnRegisterUrl(url: string): DwnRegisterUrlParams | undefin
     }
 
     const path = withoutScheme.slice(0, questionIndex);
-    if (path !== DWN_REGISTER_PATH) {
+    if (path !== DWN_CONNECT_PATH) {
       return undefined;
     }
 
@@ -156,7 +155,7 @@ export function parseDwnRegisterUrl(url: string): DwnRegisterUrlParams | undefin
  * 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 callbackUrl - The callback URL from the `dwn://connect` request.
  * @param payload - The discovery payload to encode in the fragment.
  * @returns The full redirect URL (e.g. `https://notes.sh/dwn#eyJ...`).
  */
@@ -202,7 +201,7 @@ export function readDwnDiscoveryPayloadFromUrl(url: string): DwnDiscoveryPayload
  * 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
+ * or `localhost`) because the `dwn://connect` payload is only intended
  * for local DWN discovery. Accepting arbitrary hostnames would allow a
  * malicious payload to redirect agent traffic to a remote server.
  *
@@ -231,7 +230,7 @@ function isValidPayload(value: unknown): value is DwnDiscoveryPayload {
  * 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
+ * This is a security boundary: the `dwn://connect` redirect flow MUST
  * NOT allow payloads that point to non-local servers.
  */
 function isLoopbackEndpoint(endpoint: string): boolean {

package/src/dwn-key-delivery.ts

@@ -174,7 +174,7 @@ export async function writeContextKeyRecord(
       target        : tenantDid,
       messageType   : DwnInterface.RecordsWrite,
       messageParams : { ...contextKeyParams, dataCid, dataSize, encryptionInput },
-      dataStream    : new Blob([encryptedBytes]),
+      dataStream    : new Blob([encryptedBytes as BlobPart]),
     }));
   } else {
     // --- Fallback: encrypt to the owner's key (local self-delivery) ---