@enbox/agent 0.6.8 → 0.7.1

package/src/enbox-connect-protocol.ts

@@ -18,7 +18,7 @@ import type { EnboxPlatformAgent } from './types/agent.js';
 import type { PrivateKeyJwk } from '@enbox/crypto';
 import type { RequireOnly } from '@enbox/common';
 import type { DidDocument, PortableDid } from '@enbox/dids';
-import type { DwnDataEncodedRecordsWriteMessage, DwnPermissionScope, DwnProtocolDefinition } from './types/dwn.js';
+import type { DwnDataEncodedRecordsWriteMessage, DwnPermissionScope, DwnProtocolDefinition, DwnRecordsPermissionScope } from './types/dwn.js';
 
 /**
  * The protocols of permissions requested, along with the definition and permission scopes for each protocol.
@@ -103,7 +103,7 @@ import type {
   Jwk } from '@enbox/crypto';
 
 import { type BearerDid, DidJwk } from '@enbox/dids';
-import { Convert, logger } from '@enbox/common';
+import { concatenateUrl, Convert, logger, nowMs, timed } from '@enbox/common';
 import {
   CryptoUtils,
   Ed25519,
@@ -120,7 +120,7 @@ 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';
+import { mapConcurrent, mapConcurrentSettled } from './utils.js';
 
 // ---------------------------------------------------------------------------
 // Tunables
@@ -136,6 +136,24 @@ import { concatenateUrl, mapConcurrent, mapConcurrentSettled } from './utils.js'
  */
 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;
+
+/** Log namespace used for wallet-side connect critical-path timings. */
+const CONNECT_PERF_LOG_PREFIX = '[connect.perf]';
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -318,13 +336,20 @@ function buildConnectUrl({
 // JWT signing and verification
 // ---------------------------------------------------------------------------
 
-/** Signs an object as a JWT using an Ed25519 DID key. */
+/**
+ * Signs an object as a JWT using an Ed25519 DID key.
+ *
+ * `data` is constrained to `object` so callers don't have to widen
+ * typed payload shapes (e.g. `EnboxConnectResponse`) to
+ * `Record<string, unknown>` at the call site. `Convert.object(data)`
+ * stringifies whatever JSON-serializable shape is passed.
+ */
 async function signJwt({
   did,
   data,
 }: {
   did: BearerDid;
-  data: Record<string, unknown>;
+  data: object;
 }): Promise<string> {
   const header = Convert.object({
     alg : 'EdDSA',
@@ -343,7 +368,17 @@ async function signJwt({
   return `${header}.${payload}.${signatureBase64Url}`;
 }
 
-/** Verifies a JWT signature using the DID in the `kid` header. Returns the parsed payload. */
+/**
+ * Verifies a JWT signature using the DID in the `kid` header. Returns the
+ * parsed payload as an untyped object.
+ *
+ * The return type is intentionally `Record<string, unknown>` rather than a
+ * caller-supplied generic — a JWT payload is bytes from a remote party, and
+ * we can't soundly assert its shape without runtime validation. Callers must
+ * apply one of the {@link assertConnectRequest} / {@link assertConnectResponse}
+ * assertion helpers (or their own type guard) to narrow the payload before
+ * accessing fields.
+ */
 async function verifyJwt({ jwt }: { jwt: string }): Promise<Record<string, unknown>> {
   const [headerB64U, payloadB64U, signatureB64U] = jwt.split('.');
 
@@ -379,7 +414,129 @@ async function verifyJwt({ jwt }: { jwt: string }): Promise<Record<string, unkno
     throw new Error('Connect: JWT verification failed — invalid signature.');
   }
 
-  return Convert.base64Url(payloadB64U).toObject() as Record<string, unknown>;
+  const decoded: unknown = Convert.base64Url(payloadB64U).toObject();
+  if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) {
+    throw new Error('Connect: JWT verification failed — payload must be a JSON object.');
+  }
+  return decoded as Record<string, unknown>;
+}
+
+// ─── Field-level validation helpers ─────────────────────────────────────
+//
+// The connect-request / connect-response assertions below describe their
+// expected shape declaratively in terms of these primitive checks. Each
+// helper throws a consistent `Connect: <context> — \`<field>\` <reason>`
+// message on mismatch, so per-field error formatting is centralized here
+// rather than duplicated at every call site.
+
+/**
+ * Throws a shape-validation error during connect JWT assertion.
+ *
+ * Deliberately throws plain `Error` rather than `TypeError` even though
+ * the failures are runtime type-shape mismatches. The reason is layered
+ * error handling: boundary-validation failures need to propagate through
+ * the same `try/catch` paths as every other connect-flow error — vault
+ * lock failure, JWT signature failure, DWN request failure, etc. —
+ * without `catch` blocks having to special-case a `TypeError` subclass.
+ *
+ * SonarCloud's `typescript:S7786` flags this as "too unspecific for a
+ * type check" and prefers `TypeError`. We suppress it at the file level
+ * (see `sonar-project.properties`) because every `require*` helper goes
+ * through this single throw site.
+ */
+function fail(context: string, field: string, reason: string): never {
+  throw new Error(`Connect: ${context} — \`${field}\` ${reason}.`);
+}
+
+function requireString(payload: Record<string, unknown>, field: string, context: string): void {
+  if (typeof payload[field] !== 'string') { fail(context, field, 'must be a string'); }
+}
+
+function requireNumber(payload: Record<string, unknown>, field: string, context: string): void {
+  if (typeof payload[field] !== 'number') { fail(context, field, 'must be a number'); }
+}
+
+function requireArray(payload: Record<string, unknown>, field: string, context: string): void {
+  if (!Array.isArray(payload[field])) { fail(context, field, 'must be an array'); }
+}
+
+function requireObject(payload: Record<string, unknown>, field: string, context: string): void {
+  const value = payload[field];
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    fail(context, field, 'must be an object');
+  }
+}
+
+function requireLiteral<L extends string | number | boolean>(
+  payload: Record<string, unknown>, field: string, expected: L, context: string,
+): void {
+  if (payload[field] !== expected) { fail(context, field, `must be ${JSON.stringify(expected)}`); }
+}
+
+function requireStringArray(payload: Record<string, unknown>, field: string, context: string): void {
+  const value = payload[field];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+    fail(context, field, 'must be a string[]');
+  }
+}
+
+function requireOptionalString(payload: Record<string, unknown>, field: string, context: string): void {
+  if (payload[field] !== undefined && typeof payload[field] !== 'string') {
+    fail(context, field, 'must be a string when present');
+  }
+}
+
+function requireOptionalArray(payload: Record<string, unknown>, field: string, context: string): void {
+  if (payload[field] !== undefined && !Array.isArray(payload[field])) {
+    fail(context, field, 'must be an array when present');
+  }
+}
+
+// ─── Boundary assertions ────────────────────────────────────────────────
+//
+// Each `assertConnect*` describes the shape of its target type as a list
+// of per-field requirements. The structural existence/primitive checks
+// are the only validation done at the JWT-payload boundary; deeper
+// validation of nested arrays/objects (permission scopes, grants,
+// portable DID structure) happens downstream in DWN-aware validators
+// where the richer logic already lives.
+
+/**
+ * Runtime assertion that a verified JWT payload has the shape of an
+ * {@link EnboxConnectRequest}. Use immediately after `verifyJwt()` to narrow
+ * a `Record<string, unknown>` payload before accessing fields.
+ */
+function assertConnectRequest(payload: Record<string, unknown>): asserts payload is EnboxConnectRequest {
+  const ctx = 'invalid connect request';
+  requireString(payload, 'clientDid', ctx);
+  requireString(payload, 'appName', ctx);
+  requireArray(payload, 'permissionRequests', ctx);
+  requireString(payload, 'nonce', ctx);
+  requireString(payload, 'state', ctx);
+  requireString(payload, 'callbackUrl', ctx);
+  requireLiteral(payload, 'responseMode', 'direct_post', ctx);
+  requireStringArray(payload, 'supportedDidMethods', ctx);
+}
+
+/**
+ * Runtime assertion that a verified JWT payload has the shape of an
+ * {@link EnboxConnectResponse}. Use immediately after `verifyJwt()` to narrow
+ * a `Record<string, unknown>` payload before accessing fields.
+ */
+function assertConnectResponse(payload: Record<string, unknown>): asserts payload is EnboxConnectResponse {
+  const ctx = 'invalid connect response';
+  requireString(payload, 'providerDid', ctx);
+  requireString(payload, 'delegateDid', ctx);
+  requireString(payload, 'aud', ctx);
+  requireNumber(payload, 'iat', ctx);
+  requireNumber(payload, 'exp', ctx);
+  requireOptionalString(payload, 'nonce', ctx);
+  requireArray(payload, 'delegateGrants', ctx);
+  requireObject(payload, 'delegatePortableDid', ctx);
+  requireOptionalArray(payload, 'delegateDecryptionKeys', ctx);
+  requireOptionalArray(payload, 'delegateContextKeys', ctx);
+  requireOptionalArray(payload, 'delegateMultiPartyProtocols', ctx);
+  requireOptionalArray(payload, 'sessionRevocations', ctx);
 }
 
 // ---------------------------------------------------------------------------
@@ -622,7 +779,9 @@ async function getConnectRequest(requestUri: string, encryptionKey: string): Pro
   const response = await fetch(requestUri, { signal: AbortSignal.timeout(30_000) });
   const jwe = await response.text();
   const jwt = await decryptRequest({ jwe, encryptionKey });
-  return (await verifyJwt({ jwt })) as unknown as EnboxConnectRequest;
+  const payload = await verifyJwt({ jwt });
+  assertConnectRequest(payload);
+  return payload;
 }
 
 // ---------------------------------------------------------------------------
@@ -722,6 +881,7 @@ async function createPermissionGrants(
         targetDid : selectedDid,
         message   : rawMessage,
         data      : new Blob([data as BlobPart]),
+        signal    : AbortSignal.timeout(CONNECT_REQUEST_TIMEOUT_MS),
       });
       return { grantIndex, dwnUrl, reply };
     },
@@ -760,24 +920,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`.
+ *
+ * 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 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.
+ * 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,
@@ -787,42 +954,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),
+    }),
+  );
 }
 
 /**
@@ -856,10 +1047,12 @@ async function deriveScopedDecryptionKeys(
     DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe,
   ]);
 
-  // Collect read-like scopes only.
+  // Collect read-like scopes only. `isRecordPermissionScope` narrows to
+  // `DwnRecordsPermissionScope`, which declares `protocolPath?: string`
+  // and `contextId?: string` — no `as any` needed for those reads below.
   const readScopes = scopes.filter(
-    (s): s is DwnPermissionScope & { method: string } =>
-      isRecordPermissionScope(s) && readMethods.has(s.method as DwnMethodName),
+    (s): s is DwnRecordsPermissionScope =>
+      isRecordPermissionScope(s) && readMethods.has(s.method),
   );
 
   if (readScopes.length === 0) {
@@ -868,7 +1061,7 @@ async function deriveScopedDecryptionKeys(
 
   // Fail closed: reject contextId-scoped encrypted reads.
   for (const scope of readScopes) {
-    if ('contextId' in scope && (scope as any).contextId) {
+    if (scope.contextId) {
       throw new Error(
         `Encrypted delegate access scoped by contextId is not supported ` +
         `yet; use protocol-wide permissions for protocol '${protocolUri}'.`,
@@ -889,9 +1082,7 @@ async function deriveScopedDecryptionKeys(
   }
 
   // Check if any scope is protocol-wide (no protocolPath).
-  const hasProtocolWideRead = readScopes.some(
-    (s) => !('protocolPath' in s) || !(s as any).protocolPath,
-  );
+  const hasProtocolWideRead = readScopes.some((s) => !s.protocolPath);
 
   const { keyId, keyUri } = await getEncryptionKeyInfo(agent, ownerDid);
 
@@ -920,8 +1111,7 @@ async function deriveScopedDecryptionKeys(
   // Emit one exact-path key per unique protocolPath.
   const uniquePaths = new Set<string>();
   for (const scope of readScopes) {
-    const pp = (scope as any).protocolPath as string | undefined;
-    if (pp) { uniquePaths.add(pp); }
+    if (scope.protocolPath) { uniquePaths.add(scope.protocolPath); }
   }
 
   const keys: DelegateDecryptionKey[] = [];
@@ -1011,9 +1201,12 @@ async function deriveContextKeysForDelegate(
     DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe,
   ]);
 
+  // `isRecordPermissionScope` narrows to `DwnRecordsPermissionScope`,
+  // which declares `protocolPath?: string` and `contextId?: string` —
+  // no `as any` needed for the field reads below.
   const readScopes = scopes.filter(
-    (s): s is DwnPermissionScope & { method: string } =>
-      isRecordPermissionScope(s) && readMethods.has(s.method as DwnMethodName),
+    (s): s is DwnRecordsPermissionScope =>
+      isRecordPermissionScope(s) && readMethods.has(s.method),
   );
 
   if (readScopes.length === 0) {
@@ -1022,7 +1215,7 @@ async function deriveContextKeysForDelegate(
 
   // Fail closed: reject contextId-scoped reads.
   for (const scope of readScopes) {
-    if ('contextId' in scope && (scope as any).contextId) {
+    if (scope.contextId) {
       throw new Error(
         `Encrypted delegate access scoped by contextId is not supported ` +
         `yet; use protocol-wide permissions for protocol ` +
@@ -1033,7 +1226,7 @@ async function deriveContextKeysForDelegate(
 
   // Fail closed: reject protocolPath-scoped reads on multi-party protocols.
   for (const scope of readScopes) {
-    if ('protocolPath' in scope && (scope as any).protocolPath) {
+    if (scope.protocolPath) {
       throw new Error(
         `Encrypted delegate access scoped by protocolPath on multi-party ` +
         `protocols is not supported yet; use protocol-wide permissions for ` +
@@ -1066,8 +1259,7 @@ async function deriveContextKeysForDelegate(
     });
 
     for (const entry of reply.entries ?? []) {
-      const rootContextId = (entry as any).contextId?.split('/')[0]
-        || (entry as any).recordId;
+      const rootContextId = entry.contextId?.split('/')[0] ?? entry.recordId;
 
       if (!rootContextId || seenContextIds.has(rootContextId)) { continue; }
       seenContextIds.add(rootContextId);
@@ -1119,260 +1311,324 @@ async function submitConnectResponse(
   pin: string | undefined,
   agent: EnboxPlatformAgent
 ): Promise<void> {
-  const delegateBearerDid = await DidJwk.create();
-  const delegatePortableDid = await delegateBearerDid.export();
-
-  // Add X25519 key derived from the delegate's Ed25519 key.
-  // did:jwk only supports one verification method, but DWN encryption
-  // requires X25519 for key agreement. Including the derived X25519
-  // private key in the PortableDid ensures the delegate agent's KMS
-  // has both keys after import. The Ed25519→X25519 conversion is a
-  // standard cryptographic operation (RFC 8032 / libsodium).
-  const delegateEdPrivateKey = delegatePortableDid.privateKeys![0];
-  const delegateX25519PrivateKey = await Ed25519.convertPrivateKeyToX25519({
-    privateKey: delegateEdPrivateKey,
-  });
-  delegatePortableDid.privateKeys!.push(delegateX25519PrivateKey);
-
-  // Derive the delegate's key-delivery ProtocolPath leaf public key.
-  // This is the pre-derived key that the owner will use later when writing
-  // contextKey records addressed to this delegate. The owner cannot derive
-  // this from the delegate's root public key alone (HKDF needs the private
-  // key), so we compute it now while we have temporary access to the
-  // delegate's private key material.
-  const delegateX25519PrivateKeyBytes = await X25519.privateKeyToBytes({
-    privateKey: delegateX25519PrivateKey,
-  });
-  const keyDeliveryDerivationPath = [
-    KeyDerivationScheme.ProtocolPath,
-    KeyDeliveryProtocolDefinition.protocol,
-    'contextKey',
-  ];
-  const delegateLeafPrivateKeyBytes = await HdKey.derivePrivateKeyBytes(
-    delegateX25519PrivateKeyBytes, keyDeliveryDerivationPath,
+  const submitStart = nowMs();
+  const numProtocols = connectRequest.permissionRequests.length;
+  const numScopes = connectRequest.permissionRequests.reduce(
+    (sum, req) => sum + req.permissionScopes.length,
+    0,
+  );
+  // Tracked across the try/finally so the aggregate `submitConnectResponse.total`
+  // log emits on both success and failure paths — operators bisecting wall-time
+  // from wallet debug logs need the total even when a phase throws.
+  let sessionGrantCount = 0;
+  let outcome: 'ok' | 'fail' = 'ok';
+  logger.log(
+    `${CONNECT_PERF_LOG_PREFIX} submitConnectResponse.start `
+    + `(protocols=${numProtocols}, scopes=${numScopes})`,
   );
-  const delegateLeafPrivateKeyJwk = await X25519.bytesToPrivateKey({
-    privateKeyBytes: delegateLeafPrivateKeyBytes,
-  });
-  const delegateKeyDeliveryLeafPublicKey = await X25519.getPublicKey({
-    key: delegateLeafPrivateKeyJwk,
-  });
 
-  // The rootKeyId is the delegate's keyAgreement VM id (e.g. `did:jwk:...#0`).
-  // For did:jwk this is the Ed25519 VM, but getEncryptionKeyInfo() also returns
-  // this same id after Ed25519→X25519 conversion. The DWN SDK matches the JWE
-  // `kid` header against the KeyDecrypter's `rootKeyId`, so both sides must use
-  // the same id — which they do because both derive from verificationMethod.id
-  // of the keyAgreement relationship.
-  const delegateKeyAgreementVmId = delegateBearerDid.document.verificationMethod![0].id;
-  const delegateKeyDeliveryData = {
-    rootKeyId    : delegateKeyAgreementVmId,
-    publicKeyJwk : delegateKeyDeliveryLeafPublicKey,
-  };
+  try {
+    const delegateBearerDid = await timed(`${CONNECT_PERF_LOG_PREFIX} delegateDid.create`, () => DidJwk.create());
+    const delegatePortableDid = await delegateBearerDid.export();
+
+    // Add X25519 key derived from the delegate's Ed25519 key.
+    // did:jwk only supports one verification method, but DWN encryption
+    // requires X25519 for key agreement. Including the derived X25519
+    // private key in the PortableDid ensures the delegate agent's KMS
+    // has both keys after import. The Ed25519→X25519 conversion is a
+    // standard cryptographic operation (RFC 8032 / libsodium).
+    const delegateEdPrivateKey = delegatePortableDid.privateKeys![0];
+    const delegateX25519PrivateKey = await Ed25519.convertPrivateKeyToX25519({
+      privateKey: delegateEdPrivateKey,
+    });
+    delegatePortableDid.privateKeys!.push(delegateX25519PrivateKey);
+
+    // Derive the delegate's key-delivery ProtocolPath leaf public key.
+    // This is the pre-derived key that the owner will use later when writing
+    // contextKey records addressed to this delegate. The owner cannot derive
+    // this from the delegate's root public key alone (HKDF needs the private
+    // key), so we compute it now while we have temporary access to the
+    // delegate's private key material.
+    const delegateX25519PrivateKeyBytes = await X25519.privateKeyToBytes({
+      privateKey: delegateX25519PrivateKey,
+    });
+    const keyDeliveryDerivationPath = [
+      KeyDerivationScheme.ProtocolPath,
+      KeyDeliveryProtocolDefinition.protocol,
+      'contextKey',
+    ];
+    const delegateLeafPrivateKeyBytes = await HdKey.derivePrivateKeyBytes(
+      delegateX25519PrivateKeyBytes, keyDeliveryDerivationPath,
+    );
+    const delegateLeafPrivateKeyJwk = await X25519.bytesToPrivateKey({
+      privateKeyBytes: delegateLeafPrivateKeyBytes,
+    });
+    const delegateKeyDeliveryLeafPublicKey = await X25519.getPublicKey({
+      key: delegateLeafPrivateKeyJwk,
+    });
 
-  // Derive scope-aware decryption keys for encrypted protocols.
-  // Single-party: ProtocolPath keys (protocol-wide or exact-path).
-  // Multi-party: ProtocolContext keys (per rootContextId).
-  // Write-only delegates receive no decryption capability.
-  const delegateDecryptionKeys: DelegateDecryptionKey[] = [];
-  const delegateContextKeys: DelegateContextKey[] = [];
-  const delegateMultiPartyProtocols: string[] = [];
+    // The rootKeyId is the delegate's keyAgreement VM id (e.g. `did:jwk:...#0`).
+    // For did:jwk this is the Ed25519 VM, but getEncryptionKeyInfo() also returns
+    // this same id after Ed25519→X25519 conversion. The DWN SDK matches the JWE
+    // `kid` header against the KeyDecrypter's `rootKeyId`, so both sides must use
+    // the same id — which they do because both derive from verificationMethod.id
+    // of the keyAgreement relationship.
+    const delegateKeyAgreementVmId = delegateBearerDid.document.verificationMethod![0].id;
+    const delegateKeyDeliveryData = {
+      rootKeyId    : delegateKeyAgreementVmId,
+      publicKeyJwk : delegateKeyDeliveryLeafPublicKey,
+    };
+
+    // Derive scope-aware decryption keys for encrypted protocols.
+    // Single-party: ProtocolPath keys (protocol-wide or exact-path).
+    // Multi-party: ProtocolContext keys (per rootContextId).
+    // Write-only delegates receive no decryption capability.
+    const delegateDecryptionKeys: DelegateDecryptionKey[] = [];
+    const delegateContextKeys: DelegateContextKey[] = [];
+    const delegateMultiPartyProtocols: string[] = [];
+
+    const delegateGrants = await timed(
+      `${CONNECT_PERF_LOG_PREFIX} permissionGrants.fanout (protocols=${numProtocols})`,
+      async () => {
+        const delegateGrantPromises = connectRequest.permissionRequests.map(
+          async (permissionRequest) => {
+            const { protocolDefinition, permissionScopes } = permissionRequest;
+
+            const grantsMatchProtocolUri = permissionScopes.every(
+              scope => 'protocol' in scope && scope.protocol === protocolDefinition.protocol
+            );
+            if (!grantsMatchProtocolUri) {
+              throw new Error('All permission scopes must match the protocol URI they are provided with.');
+            }
+
+            await prepareProtocol(selectedDid, agent, protocolDefinition);
+
+            const hasEncryptedTypes = Object.values(protocolDefinition.types ?? {})
+              .some((type: any) => type?.encryptionRequired === true);
+
+            if (hasEncryptedTypes) {
+              const { multiParty, singleParty } = classifyProtocolRoots(protocolDefinition);
+
+              if (multiParty.length > 0 && singleParty.length > 0) {
+                // Mixed protocol: some roots are multi-party, others single-party.
+                // We cannot safely model this with either key type alone.
+                throw new Error(
+                  `Encrypted delegate access for protocols with mixed single-party ` +
+                  `and multi-party roots is not supported yet. ` +
+                  `Protocol '${protocolDefinition.protocol}' has multi-party roots ` +
+                  `[${multiParty.join(', ')}] and single-party roots ` +
+                  `[${singleParty.join(', ')}].`,
+                );
+              }
+
+              if (multiParty.length > 0) {
+                // Pure multi-party: derive per-context keys for existing contexts.
+                // Unsupported scope shapes (protocolPath, contextId) throw.
+                const ctxKeys = await deriveContextKeysForDelegate(
+                  agent, selectedDid, protocolDefinition, permissionScopes,
+                );
+                delegateContextKeys.push(...ctxKeys);
+
+                // Only register the protocol for post-connect delivery if the
+                // delegate has at least one read-like scope. Write-only delegates
+                // must NOT receive context keys — they have no decryption need.
+                const readMethods = new Set([
+                  DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe,
+                ]);
+                const hasReadLikeScope = permissionScopes.some(
+                  (s): boolean => isRecordPermissionScope(s) && readMethods.has(s.method as DwnMethodName),
+                );
+                if (hasReadLikeScope) {
+                  delegateMultiPartyProtocols.push(protocolDefinition.protocol);
+                }
+              } else {
+                // Pure single-party: derive ProtocolPath keys.
+                // Unsupported scope shapes (contextId) throw.
+                const keys = await deriveScopedDecryptionKeys(
+                  agent, selectedDid, protocolDefinition.protocol,
+                  permissionScopes, protocolDefinition,
+                );
+                delegateDecryptionKeys.push(...keys);
+              }
+            }
+
+            return EnboxConnectProtocol.createPermissionGrants(
+              selectedDid,
+              delegateBearerDid,
+              agent,
+              permissionScopes,
+              delegateKeyDeliveryData,
+            );
+          }
+        );
 
-  const delegateGrantPromises = connectRequest.permissionRequests.map(
-    async (permissionRequest) => {
-      const { protocolDefinition, permissionScopes } = permissionRequest;
+        return (await Promise.all(delegateGrantPromises)).flat();
+      },
+    );
 
-      const grantsMatchProtocolUri = permissionScopes.every(
-        scope => 'protocol' in scope && scope.protocol === protocolDefinition.protocol
-      );
-      if (!grantsMatchProtocolUri) {
-        throw new Error('All permission scopes must match the protocol URI they are provided with.');
-      }
+    // Create per-grant contextId-scoped revocation grants.
+    // Each revocation grant authorizes the delegate to write a revocation
+    // ONLY for the specific session grant it corresponds to.
+    const permissionsApi = new AgentPermissionsApi({ agent });
+    const sessionRevocations: { grantId: string; revocationGrantId: string }[] = [];
+    let revGrantEndpoints: string[] = [];
+    try {
+      revGrantEndpoints = await agent.dwn.getDwnEndpointUrlsForTarget(selectedDid);
+    } catch {
+      // Endpoint resolution failure — revocation grants will be local-only until sync.
+    }
 
-      await prepareProtocol(selectedDid, agent, protocolDefinition);
+    // 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).
+    sessionGrantCount = delegateGrants.length;
+
+    // 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 timed(
+      `${CONNECT_PERF_LOG_PREFIX} revocationGrants.create (n=${sessionGrantCount})`,
+      () => 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 })),
+      ),
+    );
 
-      const hasEncryptedTypes = Object.values(protocolDefinition.types ?? {})
-        .some((type: any) => type?.encryptionRequired === true);
+    // 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,
+      });
 
-      if (hasEncryptedTypes) {
-        const { multiParty, singleParty } = classifyProtocolRoots(protocolDefinition);
+      const { encodedData: revEncoded, ...revRawMessage } = revGrant.message;
+      const revData = Uint8Array.from(Convert.base64Url(revEncoded).toUint8Array());
 
-        if (multiParty.length > 0 && singleParty.length > 0) {
-          // Mixed protocol: some roots are multi-party, others single-party.
-          // We cannot safely model this with either key type alone.
-          throw new Error(
-            `Encrypted delegate access for protocols with mixed single-party ` +
-            `and multi-party roots is not supported yet. ` +
-            `Protocol '${protocolDefinition.protocol}' has multi-party roots ` +
-            `[${multiParty.join(', ')}] and single-party roots ` +
-            `[${singleParty.join(', ')}].`,
-          );
-        }
+      // Include the revocation grant in the delegate grants for distribution.
+      delegateGrants.push(revGrant.message);
 
-        if (multiParty.length > 0) {
-          // Pure multi-party: derive per-context keys for existing contexts.
-          // Unsupported scope shapes (protocolPath, contextId) throw.
-          const ctxKeys = await deriveContextKeysForDelegate(
-            agent, selectedDid, protocolDefinition, permissionScopes,
-          );
-          delegateContextKeys.push(...ctxKeys);
-
-          // Only register the protocol for post-connect delivery if the
-          // delegate has at least one read-like scope. Write-only delegates
-          // must NOT receive context keys — they have no decryption need.
-          const readMethods = new Set([
-            DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe,
-          ]);
-          const hasReadLikeScope = permissionScopes.some(
-            (s): boolean => isRecordPermissionScope(s) && readMethods.has(s.method as DwnMethodName),
-          );
-          if (hasReadLikeScope) {
-            delegateMultiPartyProtocols.push(protocolDefinition.protocol);
-          }
-        } else {
-          // Pure single-party: derive ProtocolPath keys.
-          // Unsupported scope shapes (contextId) throw.
-          const keys = await deriveScopedDecryptionKeys(
-            agent, selectedDid, protocolDefinition.protocol,
-            permissionScopes, protocolDefinition,
-          );
-          delegateDecryptionKeys.push(...keys);
-        }
-      }
+      return revGrantEndpoints.map((dwnUrl) => ({ revRawMessage, revData, dwnUrl }));
+    });
 
-      return EnboxConnectProtocol.createPermissionGrants(
-        selectedDid,
-        delegateBearerDid,
-        agent,
-        permissionScopes,
-        delegateKeyDeliveryData,
+    if (revSendTasks.length > 0) {
+      await timed(
+        `${CONNECT_PERF_LOG_PREFIX} revocationGrants.fanout (sends=${revSendTasks.length}, endpoints=${revGrantEndpoints.length})`,
+        () => mapConcurrentSettled(
+          revSendTasks,
+          CONNECT_FANOUT_CONCURRENCY,
+          ({ revRawMessage, revData, dwnUrl }) =>
+            agent.rpc.sendDwnRequest({
+              dwnUrl,
+              targetDid : selectedDid,
+              message   : revRawMessage,
+              data      : new Blob([revData]),
+              signal    : AbortSignal.timeout(CONNECT_REQUEST_TIMEOUT_MS),
+            }),
+        ),
       );
     }
-  );
 
-  const delegateGrants = (await Promise.all(delegateGrantPromises)).flat();
-
-  // Create per-grant contextId-scoped revocation grants.
-  // Each revocation grant authorizes the delegate to write a revocation
-  // ONLY for the specific session grant it corresponds to.
-  const permissionsApi = new AgentPermissionsApi({ agent });
-  const sessionRevocations: { grantId: string; revocationGrantId: string }[] = [];
-  let revGrantEndpoints: string[] = [];
-  try {
-    revGrantEndpoints = await agent.dwn.getDwnEndpointUrlsForTarget(selectedDid);
-  } catch {
-    // Endpoint resolution failure — revocation grants will be local-only until sync.
-  }
-
-  // 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;
+    const responseObject = await timed(
+      `${CONNECT_PERF_LOG_PREFIX} response.build`,
+      () => EnboxConnectProtocol.createConnectResponse({
+        providerDid                 : selectedDid,
+        delegateDid                 : delegateBearerDid.uri,
+        aud                         : connectRequest.clientDid,
+        nonce                       : connectRequest.nonce,
+        delegateGrants,
+        delegatePortableDid,
+        delegateDecryptionKeys      : delegateDecryptionKeys.length > 0 ? delegateDecryptionKeys : undefined,
+        delegateContextKeys         : delegateContextKeys.length > 0 ? delegateContextKeys : undefined,
+        delegateMultiPartyProtocols : delegateMultiPartyProtocols.length > 0 ? delegateMultiPartyProtocols : undefined,
+        sessionRevocations          : sessionRevocations.length > 0 ? sessionRevocations : undefined,
+      }),
+    );
 
-  // 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 })),
-  );
+    const responseObjectJwt = await timed(
+      `${CONNECT_PERF_LOG_PREFIX} response.sign`,
+      () => EnboxConnectProtocol.signJwt({
+        did  : delegateBearerDid,
+        data : responseObject,
+      }),
+    );
 
-  // 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,
-    });
+    const clientDid = await timed(
+      `${CONNECT_PERF_LOG_PREFIX} clientDid.resolve`,
+      () => DidJwk.resolve(connectRequest.clientDid),
+    );
 
-    const { encodedData: revEncoded, ...revRawMessage } = revGrant.message;
-    const revData = Convert.base64Url(revEncoded).toUint8Array();
+    const sharedKey = await timed(
+      `${CONNECT_PERF_LOG_PREFIX} response.deriveSharedKey`,
+      () => EnboxConnectProtocol.deriveSharedKey(
+        delegateBearerDid,
+        clientDid?.didDocument!,
+      ),
+    );
 
-    // Include the revocation grant in the delegate grants for distribution.
-    delegateGrants.push(revGrant.message);
+    const encryptedResponse = await timed(
+      `${CONNECT_PERF_LOG_PREFIX} response.encrypt`,
+      () => EnboxConnectProtocol.encryptResponse({
+        jwt                  : responseObjectJwt,
+        encryptionKey        : sharedKey,
+        delegatePublicKeyJwk : delegateBearerDid.document.verificationMethod![0].publicKeyJwk!,
+        pin,
+      }),
+    );
 
-    return revGrantEndpoints.map((dwnUrl) => ({ revRawMessage, revData, dwnUrl }));
-  });
+    const formEncodedRequest = new URLSearchParams({
+      id_token : encryptedResponse,
+      state    : connectRequest.state,
+    }).toString();
+
+    await timed(
+      `${CONNECT_PERF_LOG_PREFIX} response.callbackPost`,
+      async () => {
+        const response = await fetch(connectRequest.callbackUrl, {
+          body    : formEncodedRequest,
+          method  : 'POST',
+          headers : {
+            'Content-Type': 'application/x-www-form-urlencoded',
+          },
+          signal: AbortSignal.timeout(30_000),
+        });
+
+        if (!response.ok) {
+          // NOTE: delegate grants have already been written/fanned out by this
+          // point, so callers may observe partial owner-side state when the
+          // callback server rejects the final response delivery.
+          throw new Error(`Connect: callback POST failed with HTTP ${response.status}.`);
+        }
 
-  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]),
-        }),
+        return response;
+      },
+    );
+  } catch (err) {
+    outcome = 'fail';
+    throw err;
+  } finally {
+    const totalElapsed = nowMs() - submitStart;
+    logger.log(
+      `${CONNECT_PERF_LOG_PREFIX} submitConnectResponse.total ${outcome} in ${totalElapsed.toFixed(1)}ms `
+      + `(protocols=${numProtocols}, scopes=${numScopes}, sessionGrants=${sessionGrantCount})`,
     );
   }
-
-  logger.log('Building connect response...');
-  const responseObject = await EnboxConnectProtocol.createConnectResponse({
-    providerDid                 : selectedDid,
-    delegateDid                 : delegateBearerDid.uri,
-    aud                         : connectRequest.clientDid,
-    nonce                       : connectRequest.nonce,
-    delegateGrants,
-    delegatePortableDid,
-    delegateDecryptionKeys      : delegateDecryptionKeys.length > 0 ? delegateDecryptionKeys : undefined,
-    delegateContextKeys         : delegateContextKeys.length > 0 ? delegateContextKeys : undefined,
-    delegateMultiPartyProtocols : delegateMultiPartyProtocols.length > 0 ? delegateMultiPartyProtocols : undefined,
-    sessionRevocations          : sessionRevocations.length > 0 ? sessionRevocations : undefined,
-  });
-
-  logger.log('Signing connect response...');
-  const responseObjectJwt = await EnboxConnectProtocol.signJwt({
-    did  : delegateBearerDid,
-    data : responseObject as unknown as Record<string, unknown>,
-  });
-
-  const clientDid = await DidJwk.resolve(connectRequest.clientDid);
-
-  const sharedKey = await EnboxConnectProtocol.deriveSharedKey(
-    delegateBearerDid,
-    clientDid?.didDocument!
-  );
-
-  logger.log('Encrypting connect response...');
-  const encryptedResponse = await EnboxConnectProtocol.encryptResponse({
-    jwt                  : responseObjectJwt,
-    encryptionKey        : sharedKey,
-    delegatePublicKeyJwk : delegateBearerDid.document.verificationMethod![0].publicKeyJwk!,
-    pin,
-  });
-
-  const formEncodedRequest = new URLSearchParams({
-    id_token : encryptedResponse,
-    state    : connectRequest.state,
-  }).toString();
-
-  logger.log(`Sending connect response to: ${connectRequest.callbackUrl}`);
-  await fetch(connectRequest.callbackUrl, {
-    body    : formEncodedRequest,
-    method  : 'POST',
-    headers : {
-      'Content-Type': 'application/x-www-form-urlencoded',
-    },
-    signal: AbortSignal.timeout(30_000),
-  });
 }
 
 // ---------------------------------------------------------------------------
@@ -1383,6 +1639,8 @@ export const EnboxConnectProtocol = {
   buildConnectUrl,
   signJwt,
   verifyJwt,
+  assertConnectRequest,
+  assertConnectResponse,
   encryptRequest,
   decryptRequest,
   encryptResponse,