@enbox/agent 0.6.7 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/agent",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
@@ -72,7 +72,7 @@
   },
   "dependencies": {
     "@scure/bip39": "1.2.2",
-    "@enbox/dwn-clients": "0.3.3",
+    "@enbox/dwn-clients": "0.4.0",
     "@enbox/dwn-sdk-js": "0.3.5",
     "@enbox/common": "0.1.0",
     "@enbox/crypto": "0.1.0",

package/src/enbox-connect-protocol.ts

@@ -115,12 +115,41 @@ import {
 import { DwnInterfaceName, DwnMethodName, HdKey, KeyDerivationScheme, PermissionsProtocol } from '@enbox/dwn-sdk-js';
 
 import { AgentPermissionsApi } from './permissions-api.js';
-import { concatenateUrl } from './utils.js';
 import { DwnInterface } from './types/dwn.js';
 import { getEncryptionKeyInfo } from './dwn-encryption.js';
 import { isMultiPartyContext } from './protocol-utils.js';
 import { isRecordPermissionScope } from './dwn-api.js';
 import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
+import { concatenateUrl, mapConcurrent, mapConcurrentSettled } from './utils.js';
+
+// ---------------------------------------------------------------------------
+// Tunables
+// ---------------------------------------------------------------------------
+
+/**
+ * Maximum number of in-flight DWN-endpoint sends issued by the connect flow
+ * (permission grants + revocation grants). Caps total concurrency across all
+ * `(grant, endpoint)` pairs so that a request with many permissions and/or a
+ * tenant with many DWN endpoints cannot stampede the network. Tuned to be
+ * generous enough to hide endpoint latency while staying well under typical
+ * per-host browser connection limits and server-side rate limits.
+ */
+const CONNECT_FANOUT_CONCURRENCY = 8;
+
+/**
+ * Per-request abort budget applied to every DWN-endpoint `sendDwnRequest`
+ * issued during the connect flow. The HttpDwnRpcClient's default per-attempt
+ * timeout is 30 s with 3 retries (~120 s worst-case per request) — that
+ * scales unacceptably when bounded fan-out has to wait for every settled
+ * task. With this budget, an unhealthy / cold endpoint short-circuits the
+ * retry loop within a few seconds (AbortError is non-retryable), keeping
+ * the user-visible "Authorizing…" wait bounded even when one of N DWN
+ * endpoints is misbehaving.
+ *
+ * Sync delivers any missed copies eventually, so aborting fast is safe:
+ * the connect-flow fan-outs are best-effort and tolerate per-task failure.
+ */
+const CONNECT_REQUEST_TIMEOUT_MS = 10_000;
 
 // ---------------------------------------------------------------------------
 // Types
@@ -690,45 +719,56 @@ async function createPermissionGrants(
   const dwnEndpointUrls = await agent.dwn.getDwnEndpointUrlsForTarget(selectedDid);
   logger.log(`Sending ${permissionGrants.length} permission grants to ${dwnEndpointUrls.length} DWN endpoint(s)...`);
 
-  const messagePromises = permissionGrants.map(async (grant) => {
+  // Flatten (grant, endpoint) tuples into a single list of sends so that one
+  // global concurrency cap governs total in-flight requests during the
+  // connect flow — important when either dimension grows large.
+  const sendTasks = permissionGrants.flatMap((grant, grantIndex) => {
     const { encodedData, ...rawMessage } = grant.message;
     const data = Convert.base64Url(encodedData).toUint8Array();
+    return dwnEndpointUrls.map((dwnUrl) => ({ grantIndex, dwnUrl, rawMessage, data }));
+  });
 
-    // The rawMessage is already signed by createGrant(), so we send it
-    // directly to each endpoint without re-constructing.
-    let atLeastOneSuccess = false;
-    for (const dwnUrl of dwnEndpointUrls) {
-      try {
-        const reply = await agent.rpc.sendDwnRequest({
-          dwnUrl,
-          targetDid : selectedDid,
-          message   : rawMessage,
-          data      : new Blob([data as BlobPart]),
-        });
+  const settled = await mapConcurrentSettled(
+    sendTasks,
+    CONNECT_FANOUT_CONCURRENCY,
+    async ({ grantIndex, dwnUrl, rawMessage, data }) => {
+      const reply = await agent.rpc.sendDwnRequest({
+        dwnUrl,
+        targetDid : selectedDid,
+        message   : rawMessage,
+        data      : new Blob([data as BlobPart]),
+        signal    : AbortSignal.timeout(CONNECT_REQUEST_TIMEOUT_MS),
+      });
+      return { grantIndex, dwnUrl, reply };
+    },
+  );
 
-        if (reply.status.code === 202 || reply.status.code === 409) {
-          atLeastOneSuccess = true;
-        } else {
-          logger.error(`Grant send to ${dwnUrl} returned ${reply.status.code}: ${reply.status.detail}`);
-        }
-      } catch (error: any) {
-        logger.error(`Grant send to ${dwnUrl} failed: ${error.message}`);
-      }
+  // Aggregate results back per grant: each grant must have at least one
+  // endpoint accept it (status 202 or 409 — already-stored is acceptable).
+  const successPerGrant = new Array<boolean>(permissionGrants.length).fill(false);
+  for (let i = 0; i < settled.length; i++) {
+    const result = settled[i];
+    if (result.status === 'rejected') {
+      const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      logger.error(`Grant send to ${sendTasks[i].dwnUrl} failed: ${reason}`);
+      continue;
+    }
+    const { grantIndex, dwnUrl, reply } = result.value;
+    if (reply.status.code === 202 || reply.status.code === 409) {
+      successPerGrant[grantIndex] = true;
+    } else {
+      logger.error(`Grant send to ${dwnUrl} returned ${reply.status.code}: ${reply.status.detail}`);
     }
+  }
 
-    if (!atLeastOneSuccess) {
+  for (let g = 0; g < permissionGrants.length; g++) {
+    if (!successPerGrant[g]) {
+      logger.error(`Error during batch-send of permission grants: grant ${g} reached no DWN endpoint.`);
       throw new Error('Could not send permission grant to any DWN endpoint.');
     }
-
-    return grant.message;
-  });
-
-  try {
-    return await Promise.all(messagePromises);
-  } catch (error) {
-    logger.error(`Error during batch-send of permission grants: ${error}`);
-    throw error;
   }
+
+  return permissionGrants.map((g) => g.message);
 }
 
 // ---------------------------------------------------------------------------
@@ -736,24 +776,31 @@ async function createPermissionGrants(
 // ---------------------------------------------------------------------------
 
 /**
- * Installs a DWN protocol on the provider's DWN if it doesn't already exist.
- * Ensures the protocol is available on both the local and remote DWN.
+ * Ensures the protocol is installed on the provider's local DWN so that the
+ * agent can sign and (when applicable) encrypt grants for it during
+ * `submitConnectResponse`.
  *
- * When the protocol definition contains types with `encryptionRequired: true`,
- * the protocol is installed with `encryption: true` so that the agent injects
- * `$encryption` keys (derived from the owner's X25519 root key) into the
- * protocol definition. This ensures the protocol is immediately usable for
- * encrypted record operations by both the owner and any delegates.
+ * Remote installation (push to every owner DWN endpoint) is the
+ * responsibility of the calling client (the wallet's own `prepareProtocol`
+ * runs *before* `submitConnectResponse` and fans out to every endpoint in
+ * parallel). When the protocol already exists locally — the common case —
+ * this function performs a single local `ProtocolsQuery` and returns: there
+ * is no remote send, so a slow/unhealthy DWN endpoint cannot block the
+ * "Authorizing…" hot path.
+ *
+ * When the protocol is *not* installed locally — a safety fallback for
+ * callers that did not pre-install — the protocol is configured locally
+ * (with `encryption: true` when any type declares `encryptionRequired: true`,
+ * so the agent injects `$encryption` keys derived from the owner's X25519
+ * root key) and then fanned out to every owner DWN endpoint with bounded
+ * concurrency and a short per-request budget. Endpoint failures are
+ * non-fatal — sync delivers any missing copies eventually.
  */
 async function prepareProtocol(
   selectedDid: string,
   agent: EnboxPlatformAgent,
   protocolDefinition: DwnProtocolDefinition
 ): Promise<void> {
-  // Detect whether any type in the protocol requires encryption.
-  const needsEncryption = Object.values(protocolDefinition.types ?? {})
-    .some((type: any) => type?.encryptionRequired === true);
-
   const queryMessage = await agent.processDwnRequest({
     author        : selectedDid,
     messageType   : DwnInterface.ProtocolsQuery,
@@ -763,42 +810,66 @@ async function prepareProtocol(
 
   if (queryMessage.reply.status.code !== 200) {
     throw new Error(`Could not fetch protocol: ${queryMessage.reply.status.detail}`);
-  } else if (queryMessage.reply.entries === undefined || queryMessage.reply.entries.length === 0) {
-    logger.log(`Protocol does not exist, creating: ${protocolDefinition.protocol}`);
-
-    const { reply: sendReply, message: configureMessage } = await agent.sendDwnRequest({
-      author        : selectedDid,
-      target        : selectedDid,
-      messageType   : DwnInterface.ProtocolsConfigure,
-      messageParams : { definition: protocolDefinition },
-      encryption    : needsEncryption || undefined,
-    });
+  }
 
-    if (sendReply.status.code !== 202 && sendReply.status.code !== 409) {
-      throw new Error(`Could not send protocol: ${sendReply.status.detail}`);
-    }
+  const isInstalledLocally = queryMessage.reply.entries !== undefined
+    && queryMessage.reply.entries.length > 0;
+
+  if (isInstalledLocally) {
+    // Already installed locally. The wallet's pre-call `prepareProtocol`
+    // is responsible for fanning the protocol out to every owner DWN
+    // endpoint; sync delivers any missing copies eventually. Skipping the
+    // remote send here turns this hot path into a single local DB read
+    // (~10 ms) instead of a sequential per-endpoint network round-trip
+    // with retries — the latter could take minutes if any endpoint was
+    // slow or unreachable.
+    logger.log(`Protocol already installed locally: ${protocolDefinition.protocol}`);
+    return;
+  }
 
-    await agent.processDwnRequest({
-      author      : selectedDid,
-      target      : selectedDid,
-      messageType : DwnInterface.ProtocolsConfigure,
-      rawMessage  : configureMessage
-    });
-  } else {
-    logger.log(`Protocol already exists: ${protocolDefinition.protocol}`);
-
-    const configureMessage = queryMessage.reply.entries![0];
-    const { reply: sendReply } = await agent.sendDwnRequest({
-      author      : selectedDid,
-      target      : selectedDid,
-      messageType : DwnInterface.ProtocolsConfigure,
-      rawMessage  : configureMessage,
-    });
+  // Safety fallback — protocol is missing locally, so the caller did not
+  // pre-install. Configure it locally (with encryption derivation if any
+  // type requires it) so the agent can sign/encrypt grants, then push to
+  // every owner DWN endpoint in parallel with a short per-request budget.
+  logger.log(`Protocol not installed, configuring locally: ${protocolDefinition.protocol}`);
+  const needsEncryption = Object.values(protocolDefinition.types ?? {})
+    .some((type: any) => type?.encryptionRequired === true);
 
-    if (sendReply.status.code !== 202 && sendReply.status.code !== 409) {
-      throw new Error(`Could not send protocol: ${sendReply.status.detail}`);
-    }
+  const { reply: configureReply, message: configureMessage } = await agent.processDwnRequest({
+    author        : selectedDid,
+    target        : selectedDid,
+    messageType   : DwnInterface.ProtocolsConfigure,
+    messageParams : { definition: protocolDefinition },
+    encryption    : needsEncryption || undefined,
+  });
+
+  if (configureReply.status.code !== 202 && configureReply.status.code !== 409) {
+    throw new Error(`Could not configure protocol locally: ${configureReply.status.detail}`);
   }
+
+  let dwnEndpointUrls: string[] = [];
+  try {
+    dwnEndpointUrls = await agent.dwn.getDwnEndpointUrlsForTarget(selectedDid);
+  } catch {
+    // Endpoint resolution failure — protocol stays local-only until sync.
+  }
+
+  if (dwnEndpointUrls.length === 0) {
+    return;
+  }
+
+  // Best-effort remote fan-out with bounded concurrency and a per-request
+  // abort signal. Failures are tolerated (sync delivers eventually).
+  await mapConcurrentSettled(
+    dwnEndpointUrls,
+    CONNECT_FANOUT_CONCURRENCY,
+    (dwnUrl) => agent.rpc.sendDwnRequest({
+      dwnUrl,
+      targetDid : selectedDid,
+      message   : configureMessage!,
+      signal    : AbortSignal.timeout(CONNECT_REQUEST_TIMEOUT_MS),
+    }),
+  );
 }
 
 /**
@@ -1243,46 +1314,62 @@ async function submitConnectResponse(
   // Snapshot the current length — revocation grants are appended to delegateGrants
   // below, but we must NOT iterate over them (they are meta-grants, not session grants).
   const sessionGrantCount = delegateGrants.length;
-  for (let i = 0; i < sessionGrantCount; i++) {
-    const grantMessage = delegateGrants[i];
-    const revGrant = await permissionsApi.createGrant({
-      delegated : true,
-      store     : true,
-      grantedTo : delegateBearerDid.uri,
-      scope     : {
-        interface : DwnInterfaceName.Records,
-        method    : DwnMethodName.Write,
-        protocol  : PermissionsProtocol.uri,
-        contextId : grantMessage.recordId,
-      },
-      dateExpires : '2040-06-25T16:09:16.693356Z',
-      author      : selectedDid,
-    });
+
+  // Phase 1: create all revocation grants locally with bounded concurrency.
+  // createGrant is local-only (storage + signing) so it's cheap, but we still
+  // cap parallelism to avoid head-of-line blocking when sessionGrantCount is
+  // large (e.g. dapp requesting many scopes at once).
+  const revGrantResults = await mapConcurrent(
+    delegateGrants.slice(0, sessionGrantCount),
+    CONNECT_FANOUT_CONCURRENCY,
+    (grantMessage) =>
+      permissionsApi.createGrant({
+        delegated : true,
+        store     : true,
+        grantedTo : delegateBearerDid.uri,
+        scope     : {
+          interface : DwnInterfaceName.Records,
+          method    : DwnMethodName.Write,
+          protocol  : PermissionsProtocol.uri,
+          contextId : grantMessage.recordId,
+        },
+        dateExpires : '2040-06-25T16:09:16.693356Z',
+        author      : selectedDid,
+      }).then((revGrant) => ({ grantMessage, revGrant })),
+  );
+
+  // Phase 2: fan out every revocation grant to every owner DWN endpoint with
+  // a single global concurrency cap so that (grants × endpoints) cannot blow
+  // up. This is best-effort (sync delivers eventually) so individual failures
+  // are tolerated by `mapConcurrentSettled`.
+  const revSendTasks = revGrantResults.flatMap(({ grantMessage, revGrant }) => {
     sessionRevocations.push({
       grantId           : grantMessage.recordId,
       revocationGrantId : revGrant.message.recordId,
     });
 
-    // Fan out the revocation grant to all owner DWN endpoints (same
-    // as session grants) so that immediate disconnect can send a
-    // delegated revocation to a remote DWN that recognises the grant.
     const { encodedData: revEncoded, ...revRawMessage } = revGrant.message;
     const revData = Convert.base64Url(revEncoded).toUint8Array();
-    for (const dwnUrl of revGrantEndpoints) {
-      try {
-        await agent.rpc.sendDwnRequest({
+
+    // Include the revocation grant in the delegate grants for distribution.
+    delegateGrants.push(revGrant.message);
+
+    return revGrantEndpoints.map((dwnUrl) => ({ revRawMessage, revData, dwnUrl }));
+  });
+
+  if (revSendTasks.length > 0) {
+    await mapConcurrentSettled(
+      revSendTasks,
+      CONNECT_FANOUT_CONCURRENCY,
+      ({ revRawMessage, revData, dwnUrl }) =>
+        agent.rpc.sendDwnRequest({
           dwnUrl,
           targetDid : selectedDid,
           message   : revRawMessage,
           data      : new Blob([revData as BlobPart]),
-        });
-      } catch {
-        // Best-effort — sync will deliver eventually.
-      }
-    }
-
-    // Include the revocation grant in the delegate grants for distribution
-    delegateGrants.push(revGrant.message);
+          signal    : AbortSignal.timeout(CONNECT_REQUEST_TIMEOUT_MS),
+        }),
+    );
   }
 
   logger.log('Building connect response...');

package/src/utils.ts

@@ -169,3 +169,72 @@ export function concatenateUrl(baseUrl: string, path: string): string {
 
   return `${baseUrl}/${path}`;
 }
+
+/**
+ * Map over an array with bounded concurrency, preserving input order in the
+ * output array. Uses a sliding-window pool of workers so the next item is
+ * picked up as soon as any in-flight task settles — strictly better than a
+ * fixed chunked-batch pattern (no stalling on the slowest item per batch).
+ *
+ * Semantics match `Promise.all`: the returned promise rejects on the first
+ * task rejection. Use {@link mapConcurrentSettled} when individual failures
+ * should not abort the whole batch (e.g. best-effort fan-out).
+ *
+ * @param items Input items to map over.
+ * @param concurrency Maximum number of in-flight tasks. Must be >= 1.
+ * @param fn Per-item async function. Receives the item and its index.
+ * @returns An array of results in the same order as `items`.
+ */
+export async function mapConcurrent<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new Error(`mapConcurrent: concurrency must be a positive integer, got ${concurrency}`);
+  }
+  if (items.length === 0) {
+    return [];
+  }
+
+  const results = new Array<R>(items.length);
+  let next = 0;
+
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) {
+        return;
+      }
+      results[i] = await fn(items[i], i);
+    }
+  };
+
+  const workerCount = Math.min(concurrency, items.length);
+  const workers: Promise<void>[] = [];
+  for (let w = 0; w < workerCount; w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Settled variant of {@link mapConcurrent}: never rejects — every task's
+ * outcome is captured as a `PromiseSettledResult`. Use this for best-effort
+ * fan-outs where partial success is acceptable.
+ */
+export async function mapConcurrentSettled<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<PromiseSettledResult<R>[]> {
+  return mapConcurrent(items, concurrency, async (item, index) => {
+    try {
+      const value = await fn(item, index);
+      return { status: 'fulfilled', value } as PromiseFulfilledResult<R>;
+    } catch (reason) {
+      return { status: 'rejected', reason } as PromiseRejectedResult;
+    }
+  });
+}