@enbox/agent 0.6.8 → 0.7.1

package/dist/esm/enbox-connect-protocol.js

@@ -33,7 +33,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 import { DidJwk } from '@enbox/dids';
-import { Convert, logger } from '@enbox/common';
+import { concatenateUrl, Convert, logger, nowMs, timed } from '@enbox/common';
 import { CryptoUtils, Ed25519, EdDsaAlgorithm, Hkdf, X25519, XChaCha20Poly1305, } from '@enbox/crypto';
 import { DwnInterfaceName, DwnMethodName, HdKey, KeyDerivationScheme, PermissionsProtocol } from '@enbox/dwn-sdk-js';
 import { AgentPermissionsApi } from './permissions-api.js';
@@ -42,7 +42,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
 // ---------------------------------------------------------------------------
@@ -55,6 +55,22 @@ import { concatenateUrl, mapConcurrent, mapConcurrentSettled } from './utils.js'
  * 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 = 10000;
+/** Log namespace used for wallet-side connect critical-path timings. */
+const CONNECT_PERF_LOG_PREFIX = '[connect.perf]';
 // ---------------------------------------------------------------------------
 // URL building
 // ---------------------------------------------------------------------------
@@ -89,7 +105,14 @@ function buildConnectUrl({ baseURL, endpoint, authParam, tokenParam, }) {
 // ---------------------------------------------------------------------------
 // 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.
+ */
 function signJwt(_a) {
     return __awaiter(this, arguments, void 0, function* ({ did, data, }) {
         const header = Convert.object({
@@ -106,7 +129,17 @@ function signJwt(_a) {
         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.
+ */
 function verifyJwt(_a) {
     return __awaiter(this, arguments, void 0, function* ({ jwt }) {
         var _b, _c;
@@ -134,9 +167,124 @@ function verifyJwt(_a) {
         if (!isValid) {
             throw new Error('Connect: JWT verification failed — invalid signature.');
         }
-        return Convert.base64Url(payloadB64U).toObject();
+        const decoded = 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;
     });
 }
+// ─── 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, field, reason) {
+    throw new Error(`Connect: ${context} — \`${field}\` ${reason}.`);
+}
+function requireString(payload, field, context) {
+    if (typeof payload[field] !== 'string') {
+        fail(context, field, 'must be a string');
+    }
+}
+function requireNumber(payload, field, context) {
+    if (typeof payload[field] !== 'number') {
+        fail(context, field, 'must be a number');
+    }
+}
+function requireArray(payload, field, context) {
+    if (!Array.isArray(payload[field])) {
+        fail(context, field, 'must be an array');
+    }
+}
+function requireObject(payload, field, context) {
+    const value = payload[field];
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        fail(context, field, 'must be an object');
+    }
+}
+function requireLiteral(payload, field, expected, context) {
+    if (payload[field] !== expected) {
+        fail(context, field, `must be ${JSON.stringify(expected)}`);
+    }
+}
+function requireStringArray(payload, field, context) {
+    const value = payload[field];
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        fail(context, field, 'must be a string[]');
+    }
+}
+function requireOptionalString(payload, field, context) {
+    if (payload[field] !== undefined && typeof payload[field] !== 'string') {
+        fail(context, field, 'must be a string when present');
+    }
+}
+function requireOptionalArray(payload, field, context) {
+    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) {
+    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) {
+    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);
+}
 // ---------------------------------------------------------------------------
 // Encryption: request (symmetric key via QR/deep link)
 // ---------------------------------------------------------------------------
@@ -309,7 +457,9 @@ function getConnectRequest(requestUri, encryptionKey) {
         const response = yield fetch(requestUri, { signal: AbortSignal.timeout(30000) });
         const jwe = yield response.text();
         const jwt = yield decryptRequest({ jwe, encryptionKey });
-        return (yield verifyJwt({ jwt }));
+        const payload = yield verifyJwt({ jwt });
+        assertConnectRequest(payload);
+        return payload;
     });
 }
 // ---------------------------------------------------------------------------
@@ -382,6 +532,7 @@ function createPermissionGrants(selectedDid, delegateBearerDid, agent, scopes, d
                 targetDid: selectedDid,
                 message: rawMessage,
                 data: new Blob([data]),
+                signal: AbortSignal.timeout(CONNECT_REQUEST_TIMEOUT_MS),
             });
             return { grantIndex, dwnUrl, reply };
         }));
@@ -416,21 +567,29 @@ function createPermissionGrants(selectedDid, delegateBearerDid, agent, scopes, d
 // Protocol installation
 // ---------------------------------------------------------------------------
 /**
- * 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.
  */
 function prepareProtocol(selectedDid, agent, protocolDefinition) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
-        // Detect whether any type in the protocol requires encryption.
-        const needsEncryption = Object.values((_a = protocolDefinition.types) !== null && _a !== void 0 ? _a : {})
-            .some((type) => (type === null || type === void 0 ? void 0 : type.encryptionRequired) === true);
         const queryMessage = yield agent.processDwnRequest({
             author: selectedDid,
             messageType: DwnInterface.ProtocolsQuery,
@@ -440,38 +599,54 @@ function prepareProtocol(selectedDid, agent, protocolDefinition) {
         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 } = yield 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}`);
-            }
-            yield agent.processDwnRequest({
-                author: selectedDid,
-                target: selectedDid,
-                messageType: DwnInterface.ProtocolsConfigure,
-                rawMessage: configureMessage
-            });
+        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;
         }
-        else {
-            logger.log(`Protocol already exists: ${protocolDefinition.protocol}`);
-            const configureMessage = queryMessage.reply.entries[0];
-            const { reply: sendReply } = yield agent.sendDwnRequest({
-                author: selectedDid,
-                target: selectedDid,
-                messageType: DwnInterface.ProtocolsConfigure,
-                rawMessage: configureMessage,
-            });
-            if (sendReply.status.code !== 202 && sendReply.status.code !== 409) {
-                throw new Error(`Could not send protocol: ${sendReply.status.detail}`);
-            }
+        // 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((_a = protocolDefinition.types) !== null && _a !== void 0 ? _a : {})
+            .some((type) => (type === null || type === void 0 ? void 0 : type.encryptionRequired) === true);
+        const { reply: configureReply, message: configureMessage } = yield 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 = [];
+        try {
+            dwnEndpointUrls = yield agent.dwn.getDwnEndpointUrlsForTarget(selectedDid);
         }
+        catch (_b) {
+            // 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).
+        yield mapConcurrentSettled(dwnEndpointUrls, CONNECT_FANOUT_CONCURRENCY, (dwnUrl) => agent.rpc.sendDwnRequest({
+            dwnUrl,
+            targetDid: selectedDid,
+            message: configureMessage,
+            signal: AbortSignal.timeout(CONNECT_REQUEST_TIMEOUT_MS),
+        }));
     });
 }
 /**
@@ -499,14 +674,16 @@ function deriveScopedDecryptionKeys(agent, ownerDid, protocolUri, scopes, protoc
         const readMethods = new Set([
             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) => isRecordPermissionScope(s) && readMethods.has(s.method));
         if (readScopes.length === 0) {
             return []; // write/delete only → no decryption keys
         }
         // Fail closed: reject contextId-scoped encrypted reads.
         for (const scope of readScopes) {
-            if ('contextId' in scope && scope.contextId) {
+            if (scope.contextId) {
                 throw new Error(`Encrypted delegate access scoped by contextId is not supported ` +
                     `yet; use protocol-wide permissions for protocol '${protocolUri}'.`);
             }
@@ -521,7 +698,7 @@ function deriveScopedDecryptionKeys(agent, ownerDid, protocolUri, scopes, protoc
                 `for multi-party protocols.`);
         }
         // Check if any scope is protocol-wide (no protocolPath).
-        const hasProtocolWideRead = readScopes.some((s) => !('protocolPath' in s) || !s.protocolPath);
+        const hasProtocolWideRead = readScopes.some((s) => !s.protocolPath);
         const { keyId, keyUri } = yield getEncryptionKeyInfo(agent, ownerDid);
         // If any unrestricted read scope exists, emit one protocol-wide key
         // and skip narrower keys (the protocol-wide key subsumes them).
@@ -546,9 +723,8 @@ function deriveScopedDecryptionKeys(agent, ownerDid, protocolUri, scopes, protoc
         // Emit one exact-path key per unique protocolPath.
         const uniquePaths = new Set();
         for (const scope of readScopes) {
-            const pp = scope.protocolPath;
-            if (pp) {
-                uniquePaths.add(pp);
+            if (scope.protocolPath) {
+                uniquePaths.add(scope.protocolPath);
             }
         }
         const keys = [];
@@ -627,17 +803,20 @@ function classifyProtocolRoots(definition) {
  */
 function deriveContextKeysForDelegate(agent, ownerDid, protocolDefinition, scopes) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const readMethods = new Set([
             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) => isRecordPermissionScope(s) && readMethods.has(s.method));
         if (readScopes.length === 0) {
             return []; // write-only → no context keys
         }
         // Fail closed: reject contextId-scoped reads.
         for (const scope of readScopes) {
-            if ('contextId' in scope && scope.contextId) {
+            if (scope.contextId) {
                 throw new Error(`Encrypted delegate access scoped by contextId is not supported ` +
                     `yet; use protocol-wide permissions for protocol ` +
                     `'${protocolDefinition.protocol}'.`);
@@ -645,7 +824,7 @@ function deriveContextKeysForDelegate(agent, ownerDid, protocolDefinition, scope
         }
         // Fail closed: reject protocolPath-scoped reads on multi-party protocols.
         for (const scope of readScopes) {
-            if ('protocolPath' in scope && scope.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 ` +
                     `protocol '${protocolDefinition.protocol}'.`);
@@ -671,8 +850,7 @@ function deriveContextKeysForDelegate(agent, ownerDid, protocolDefinition, scope
                 },
             });
             for (const entry of (_b = reply.entries) !== null && _b !== void 0 ? _b : []) {
-                const rootContextId = ((_c = entry.contextId) === null || _c === void 0 ? void 0 : _c.split('/')[0])
-                    || entry.recordId;
+                const rootContextId = (_d = (_c = entry.contextId) === null || _c === void 0 ? void 0 : _c.split('/')[0]) !== null && _d !== void 0 ? _d : entry.recordId;
                 if (!rootContextId || seenContextIds.has(rootContextId)) {
                     continue;
                 }
@@ -717,200 +895,229 @@ function deriveContextKeysForDelegate(agent, ownerDid, protocolDefinition, scope
  */
 function submitConnectResponse(selectedDid, connectRequest, pin, agent) {
     return __awaiter(this, void 0, void 0, function* () {
-        const delegateBearerDid = yield DidJwk.create();
-        const delegatePortableDid = yield 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 = yield 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 = yield X25519.privateKeyToBytes({
-            privateKey: delegateX25519PrivateKey,
-        });
-        const keyDeliveryDerivationPath = [
-            KeyDerivationScheme.ProtocolPath,
-            KeyDeliveryProtocolDefinition.protocol,
-            'contextKey',
-        ];
-        const delegateLeafPrivateKeyBytes = yield HdKey.derivePrivateKeyBytes(delegateX25519PrivateKeyBytes, keyDeliveryDerivationPath);
-        const delegateLeafPrivateKeyJwk = yield X25519.bytesToPrivateKey({
-            privateKeyBytes: delegateLeafPrivateKeyBytes,
-        });
-        const delegateKeyDeliveryLeafPublicKey = yield 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,
-        };
-        // 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 = [];
-        const delegateContextKeys = [];
-        const delegateMultiPartyProtocols = [];
-        const delegateGrantPromises = connectRequest.permissionRequests.map((permissionRequest) => __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            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.');
-            }
-            yield prepareProtocol(selectedDid, agent, protocolDefinition);
-            const hasEncryptedTypes = Object.values((_a = protocolDefinition.types) !== null && _a !== void 0 ? _a : {})
-                .some((type) => (type === null || type === void 0 ? void 0 : 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 = yield 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) => isRecordPermissionScope(s) && readMethods.has(s.method));
-                    if (hasReadLikeScope) {
-                        delegateMultiPartyProtocols.push(protocolDefinition.protocol);
+        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';
+        logger.log(`${CONNECT_PERF_LOG_PREFIX} submitConnectResponse.start `
+            + `(protocols=${numProtocols}, scopes=${numScopes})`);
+        try {
+            const delegateBearerDid = yield timed(`${CONNECT_PERF_LOG_PREFIX} delegateDid.create`, () => DidJwk.create());
+            const delegatePortableDid = yield 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 = yield 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 = yield X25519.privateKeyToBytes({
+                privateKey: delegateX25519PrivateKey,
+            });
+            const keyDeliveryDerivationPath = [
+                KeyDerivationScheme.ProtocolPath,
+                KeyDeliveryProtocolDefinition.protocol,
+                'contextKey',
+            ];
+            const delegateLeafPrivateKeyBytes = yield HdKey.derivePrivateKeyBytes(delegateX25519PrivateKeyBytes, keyDeliveryDerivationPath);
+            const delegateLeafPrivateKeyJwk = yield X25519.bytesToPrivateKey({
+                privateKeyBytes: delegateLeafPrivateKeyBytes,
+            });
+            const delegateKeyDeliveryLeafPublicKey = yield 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,
+            };
+            // 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 = [];
+            const delegateContextKeys = [];
+            const delegateMultiPartyProtocols = [];
+            const delegateGrants = yield timed(`${CONNECT_PERF_LOG_PREFIX} permissionGrants.fanout (protocols=${numProtocols})`, () => __awaiter(this, void 0, void 0, function* () {
+                const delegateGrantPromises = connectRequest.permissionRequests.map((permissionRequest) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    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.');
                     }
-                }
-                else {
-                    // Pure single-party: derive ProtocolPath keys.
-                    // Unsupported scope shapes (contextId) throw.
-                    const keys = yield deriveScopedDecryptionKeys(agent, selectedDid, protocolDefinition.protocol, permissionScopes, protocolDefinition);
-                    delegateDecryptionKeys.push(...keys);
-                }
+                    yield prepareProtocol(selectedDid, agent, protocolDefinition);
+                    const hasEncryptedTypes = Object.values((_a = protocolDefinition.types) !== null && _a !== void 0 ? _a : {})
+                        .some((type) => (type === null || type === void 0 ? void 0 : 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 = yield 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) => isRecordPermissionScope(s) && readMethods.has(s.method));
+                            if (hasReadLikeScope) {
+                                delegateMultiPartyProtocols.push(protocolDefinition.protocol);
+                            }
+                        }
+                        else {
+                            // Pure single-party: derive ProtocolPath keys.
+                            // Unsupported scope shapes (contextId) throw.
+                            const keys = yield deriveScopedDecryptionKeys(agent, selectedDid, protocolDefinition.protocol, permissionScopes, protocolDefinition);
+                            delegateDecryptionKeys.push(...keys);
+                        }
+                    }
+                    return EnboxConnectProtocol.createPermissionGrants(selectedDid, delegateBearerDid, agent, permissionScopes, delegateKeyDeliveryData);
+                }));
+                return (yield 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 = [];
+            let revGrantEndpoints = [];
+            try {
+                revGrantEndpoints = yield agent.dwn.getDwnEndpointUrlsForTarget(selectedDid);
             }
-            return EnboxConnectProtocol.createPermissionGrants(selectedDid, delegateBearerDid, agent, permissionScopes, delegateKeyDeliveryData);
-        }));
-        const delegateGrants = (yield 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 = [];
-        let revGrantEndpoints = [];
-        try {
-            revGrantEndpoints = yield agent.dwn.getDwnEndpointUrlsForTarget(selectedDid);
-        }
-        catch (_a) {
-            // 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;
-        // 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 = yield 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,
+            catch (_a) {
+                // 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).
+            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 = yield 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 }))));
+            // 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 _a = revGrant.message, { encodedData: revEncoded } = _a, revRawMessage = __rest(_a, ["encodedData"]);
+                const revData = Uint8Array.from(Convert.base64Url(revEncoded).toUint8Array());
+                // Include the revocation grant in the delegate grants for distribution.
+                delegateGrants.push(revGrant.message);
+                return revGrantEndpoints.map((dwnUrl) => ({ revRawMessage, revData, dwnUrl }));
             });
-            const _a = revGrant.message, { encodedData: revEncoded } = _a, revRawMessage = __rest(_a, ["encodedData"]);
-            const revData = Convert.base64Url(revEncoded).toUint8Array();
-            // 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) {
-            yield mapConcurrentSettled(revSendTasks, CONNECT_FANOUT_CONCURRENCY, ({ revRawMessage, revData, dwnUrl }) => agent.rpc.sendDwnRequest({
-                dwnUrl,
-                targetDid: selectedDid,
-                message: revRawMessage,
-                data: new Blob([revData]),
+            if (revSendTasks.length > 0) {
+                yield 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 responseObject = yield 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,
+            }));
+            const responseObjectJwt = yield timed(`${CONNECT_PERF_LOG_PREFIX} response.sign`, () => EnboxConnectProtocol.signJwt({
+                did: delegateBearerDid,
+                data: responseObject,
+            }));
+            const clientDid = yield timed(`${CONNECT_PERF_LOG_PREFIX} clientDid.resolve`, () => DidJwk.resolve(connectRequest.clientDid));
+            const sharedKey = yield timed(`${CONNECT_PERF_LOG_PREFIX} response.deriveSharedKey`, () => EnboxConnectProtocol.deriveSharedKey(delegateBearerDid, clientDid === null || clientDid === void 0 ? void 0 : clientDid.didDocument));
+            const encryptedResponse = yield timed(`${CONNECT_PERF_LOG_PREFIX} response.encrypt`, () => EnboxConnectProtocol.encryptResponse({
+                jwt: responseObjectJwt,
+                encryptionKey: sharedKey,
+                delegatePublicKeyJwk: delegateBearerDid.document.verificationMethod[0].publicKeyJwk,
+                pin,
+            }));
+            const formEncodedRequest = new URLSearchParams({
+                id_token: encryptedResponse,
+                state: connectRequest.state,
+            }).toString();
+            yield timed(`${CONNECT_PERF_LOG_PREFIX} response.callbackPost`, () => __awaiter(this, void 0, void 0, function* () {
+                const response = yield fetch(connectRequest.callbackUrl, {
+                    body: formEncodedRequest,
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/x-www-form-urlencoded',
+                    },
+                    signal: AbortSignal.timeout(30000),
+                });
+                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}.`);
+                }
+                return response;
             }));
         }
-        logger.log('Building connect response...');
-        const responseObject = yield 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 = yield EnboxConnectProtocol.signJwt({
-            did: delegateBearerDid,
-            data: responseObject,
-        });
-        const clientDid = yield DidJwk.resolve(connectRequest.clientDid);
-        const sharedKey = yield EnboxConnectProtocol.deriveSharedKey(delegateBearerDid, clientDid === null || clientDid === void 0 ? void 0 : clientDid.didDocument);
-        logger.log('Encrypting connect response...');
-        const encryptedResponse = yield 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}`);
-        yield fetch(connectRequest.callbackUrl, {
-            body: formEncodedRequest,
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/x-www-form-urlencoded',
-            },
-            signal: AbortSignal.timeout(30000),
-        });
+        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})`);
+        }
     });
 }
 // ---------------------------------------------------------------------------
@@ -920,6 +1127,8 @@ export const EnboxConnectProtocol = {
     buildConnectUrl,
     signJwt,
     verifyJwt,
+    assertConnectRequest,
+    assertConnectResponse,
     encryptRequest,
     decryptRequest,
     encryptResponse,