@enbox/agent 0.3.1 → 0.4.0

package/dist/types/local-dwn.d.ts

@@ -7,37 +7,20 @@
  * 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.
+ * 3. **Injected endpoint** — in browsers, the `dwn://connect` redirect
+ *    flow delivers the endpoint, which is injected via
+ *    {@link LocalDwnDiscovery.setCachedEndpoint | setCachedEndpoint()}.
  *
- * @see https://github.com/enboxorg/enbox/issues/585
+ * @see https://github.com/enboxorg/enbox/issues/677
  * @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 declare const localDwnPortCandidates: readonly [3000, 55500, 55501, 55502, 55503, 55504, 55505, 55506, 55507, 55508, 55509];
-/**
- * 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 declare const localDwnHostCandidates: readonly ["127.0.0.1"];
 /**
  * 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.
+ * - `'prefer'` — try local DWN first; fall back to DID-document endpoints.
  * - `'only'`   — require a local server; throw if none is found.
  */
 export type LocalDwnStrategy = 'prefer' | 'only' | 'off';
@@ -51,7 +34,7 @@ export declare function normalizeBaseUrl(url: string): string;
  * 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
+ * @example Discovery with file-based channel (CLI / native)
  * ```ts
  * import { DwnDiscoveryFile } from './dwn-discovery-file.js';
  *
@@ -60,7 +43,7 @@ export declare function normalizeBaseUrl(url: string): string;
  * const endpoint = await discovery.getEndpoint();
  * ```
  *
- * @example Browser: inject cached endpoint from `dwn://register` redirect
+ * @example Browser: inject cached endpoint from `dwn://connect` redirect
  * ```ts
  * const discovery = new LocalDwnDiscovery(rpcClient);
  * discovery.setCachedEndpoint('http://127.0.0.1:55557');
@@ -82,11 +65,18 @@ export declare class LocalDwnDiscovery {
      * 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).
+     *
+     * If neither channel finds an endpoint, the result (`undefined`) is
+     * cached to avoid repeated discovery file reads on hot paths.
+     *
+     * In browser environments (where no discovery file is available), the
+     * endpoint must be injected externally via
+     * {@link setCachedEndpoint | setCachedEndpoint()} — typically after a
+     * `dwn://connect` redirect delivers the endpoint in the URL fragment.
      */
     getEndpoint(): Promise<string | undefined>;
     /**
-     * Inject a cached endpoint (e.g. from a `dwn://register` browser redirect
+     * Inject a cached endpoint (e.g. from a `dwn://connect` browser redirect
      * or from `localStorage`). The endpoint is validated via `GET /info` before
      * caching.
      *
@@ -104,12 +94,6 @@ export declare class LocalDwnDiscovery {
      * validation. Returns `undefined` otherwise.
      */
     private _tryDiscoveryFile;
-    /**
-     * 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 _probePortCandidates;
     /**
      * Call `GET /info` on the endpoint and check that
      * `serverInfo.server === '@enbox/dwn-server'`.

package/dist/types/local-dwn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-dwn.d.ts","sourceRoot":"","sources":["../../src/local-dwn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,uFAAwF,CAAC;AAE5H;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,wBAAyB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEzD,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAiB;IAK1B,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,cAAc,CAAC;IANzB,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,YAAY,CAAK;gBAGf,UAAU,EAAE,QAAQ,EACpB,WAAW,SAAS,EACpB,cAAc,CAAC,EAAE,gBAAgB,YAAA;IAG3C;;;;;;;;;;OAUG;IACU,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAoBvD;;;;;;OAMG;IACU,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlE;;;OAGG;IACI,UAAU,IAAI,IAAI;IAOzB;;;;OAIG;YACW,iBAAiB;IAmB/B;;;;OAIG;YACW,oBAAoB;IAalC;;;OAGG;YACW,iBAAiB;IAS/B,wCAAwC;IACxC,OAAO,CAAC,cAAc;CAIvB"}
+{"version":3,"file":"local-dwn.d.ts","sourceRoot":"","sources":["../../src/local-dwn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEzD,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAiB;IAK1B,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,cAAc,CAAC;IANzB,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,YAAY,CAAK;gBAGf,UAAU,EAAE,QAAQ,EACpB,WAAW,SAAS,EACpB,cAAc,CAAC,EAAE,gBAAgB,YAAA;IAG3C;;;;;;;;;;;;;;;;;OAiBG;IACU,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAmBvD;;;;;;OAMG;IACU,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASlE;;;OAGG;IACI,UAAU,IAAI,IAAI;IAOzB;;;;OAIG;YACW,iBAAiB;IAmB/B;;;OAGG;YACW,iBAAiB;IAS/B,wCAAwC;IACxC,OAAO,CAAC,cAAc;CAIvB"}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@enbox/agent",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -78,25 +78,23 @@
     "@enbox/dids": "0.0.9",
     "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/connect.ts

@@ -1,10 +1,10 @@
 
-import type { PushedAuthResponse } from './oidc.js';
-import type { DwnPermissionScope, DwnProtocolDefinition, EnboxConnectAuthResponse } from './index.js';
+import type { ConnectPushedResponse, EnboxConnectResponse } from './enbox-connect-protocol.js';
+import type { DwnPermissionScope, DwnProtocolDefinition } from './index.js';
 
 import { CryptoUtils } from '@enbox/crypto';
 import { DidJwk } from '@enbox/dids';
-import { Oidc } from './oidc.js';
+import { EnboxConnectProtocol } from './enbox-connect-protocol.js';
 import { pollWithTtl } from './utils.js';
 import { Convert, logger } from '@enbox/common';
 import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
@@ -21,8 +21,8 @@ async function initClient({
   onWalletUriReady,
   validatePin,
 }: WalletConnectOptions): Promise<{
-  delegateGrants: EnboxConnectAuthResponse['delegateGrants'];
-  delegatePortableDid: EnboxConnectAuthResponse['delegatePortableDid'];
+  delegateGrants: EnboxConnectResponse['delegateGrants'];
+  delegatePortableDid: EnboxConnectResponse['delegatePortableDid'];
   connectedDid: string;
 } | undefined> {
   // ephemeral client did for ECDH, signing, verification
@@ -35,40 +35,36 @@ async function initClient({
   //   await Oidc.generateCodeChallenge();
   const encryptionKey = CryptoUtils.randomBytes(32);
 
-  // build callback URL to pass into the auth request
-  const callbackEndpoint = Oidc.buildOidcUrl({
+  // Build callback URL for the connect request.
+  const callbackEndpoint = EnboxConnectProtocol.buildConnectUrl({
     baseURL  : connectServerUrl,
     endpoint : 'callback',
   });
 
-  // build the PAR request
-  const request = await Oidc.createAuthRequest({
-    client_id          : clientDid.uri,
-    scope              : 'openid did:jwk',
-    redirect_uri       : callbackEndpoint,
-    // custom properties:
-    // code_challenge        : codeChallengeBase64Url,
-    // code_challenge_method : 'S256',
+  // Build the connect request.
+  const request = await EnboxConnectProtocol.createConnectRequest({
+    clientDid          : clientDid.uri,
+    callbackUrl        : callbackEndpoint,
     permissionRequests : permissionRequests,
-    displayName,
+    appName            : displayName,
   });
 
-  // Sign the Request Object using the Client DID's signing key.
-  const requestJwt = await Oidc.signJwt({
+  // Sign the request as a JWT.
+  const requestJwt = await EnboxConnectProtocol.signJwt({
     did  : clientDid,
-    data : request,
+    data : request as unknown as Record<string, unknown>,
   });
 
   if (!requestJwt) {
     throw new Error('Unable to sign requestObject');
   }
-  // Encrypt the Request Object JWT using the code challenge.
-  const requestObjectJwe = await Oidc.encryptAuthRequest({
+  // Encrypt the request JWT with the symmetric key.
+  const requestObjectJwe = await EnboxConnectProtocol.encryptRequest({
     jwt: requestJwt,
     encryptionKey,
   });
 
-  const pushedAuthorizationRequestEndpoint = Oidc.buildOidcUrl({
+  const pushedAuthorizationRequestEndpoint = EnboxConnectProtocol.buildConnectUrl({
     baseURL  : connectServerUrl,
     endpoint : 'pushedAuthorizationRequest',
   });
@@ -86,7 +82,7 @@ async function initClient({
     throw new Error(`${parResponse.status}: ${parResponse.statusText}`);
   }
 
-  const parData: PushedAuthResponse = await parResponse.json();
+  const parData: ConnectPushedResponse = await parResponse.json();
 
   // 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.
@@ -101,7 +97,7 @@ async function initClient({
   // call user's callback so they can send the URI to the wallet as they see fit
   onWalletUriReady(generatedWalletUri.toString());
 
-  const tokenUrl = Oidc.buildOidcUrl({
+  const tokenUrl = EnboxConnectProtocol.buildConnectUrl({
     baseURL    : connectServerUrl,
     endpoint   : 'token',
     tokenParam : request.state,
@@ -113,36 +109,35 @@ async function initClient({
   if (authResponse) {
     const jwe = await authResponse?.text();
 
-    // get the pin from the user and use it as AAD to decrypt
+    // Get the PIN from the user and use it as AAD to decrypt.
     const pin = await validatePin();
-    const jwt = await Oidc.decryptAuthResponse(clientDid, jwe, pin);
-    const verifiedAuthResponse = (await Oidc.verifyJwt({
+    const jwt = await EnboxConnectProtocol.decryptResponse(clientDid, jwe, pin);
+    const verifiedResponse = (await EnboxConnectProtocol.verifyJwt({
       jwt,
-    })) as EnboxConnectAuthResponse;
+    })) as unknown as EnboxConnectResponse;
 
     return {
-      delegateGrants      : verifiedAuthResponse.delegateGrants,
-      delegatePortableDid : verifiedAuthResponse.delegatePortableDid,
-      connectedDid        : verifiedAuthResponse.iss,
+      delegateGrants      : verifiedResponse.delegateGrants,
+      delegatePortableDid : verifiedResponse.delegatePortableDid,
+      connectedDid        : verifiedResponse.providerDid,
     };
   }
 }
 
 /**
- * Initiates the wallet connect process. Used when a client wants to obtain
- * a did from a provider.
+ * Options for initiating a wallet connect flow (remote, relay-mediated).
  */
 export type WalletConnectOptions = {
-  /** The user friendly name of the client/app to be displayed when prompting end-user with permission requests. */
+  /** The user-friendly name of the app, displayed in the wallet consent UI. */
   displayName: string;
 
-  /** The URL of the intermediary server which relays messages between the client and provider. */
+  /** The URL of the connect server which relays messages between the app and wallet. */
   connectServerUrl: string;
 
   /**
-   * The URI of the Provider (wallet).The `onWalletUriReady` will take this wallet
-   * uri and add a payload to it which will be used to obtain and decrypt from the `request_uri`.
-   * @example `web5://` or `http://localhost:3000/`.
+   * The URI of the wallet app. Query params (`request_uri`, `encryption_key`)
+   * are appended and passed to `onWalletUriReady`.
+   * @example `enbox://connect` or `http://localhost:3000/`
    */
   walletUri: string;
 
@@ -154,20 +149,16 @@ export type WalletConnectOptions = {
   permissionRequests: ConnectPermissionRequest[];
 
   /**
-   * 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 EnboxConnectAuthRequest} and use the `encryption_key` to decrypt it.
+   * Called with the wallet URI including query params (`request_uri`, `encryption_key`).
+   * The app should render this as a QR code or use it as a deep link.
    *
-   * @param uri - The URI returned by the Connect API to be passed to a provider.
+   * @param uri - The wallet URI with connect payload.
    */
   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 EnboxConnectAuthResponse} that was retrieved from the
-   * token endpoint by the client inside of Connect.
+   * Called to collect the PIN from the user. The PIN is used as AAD
+   * when decrypting the connect response from the relay.
    *
    * @returns A promise that resolves to the PIN as a string.
    */

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