@enbox/agent 0.5.15 → 0.6.0

package/src/enbox-connect-protocol.ts

@@ -13,7 +13,9 @@
  * and ECDH (Ed25519 → X25519 + HKDF) for key agreement.
  */
 
+import type { DerivedPrivateJwk } from '@enbox/dwn-sdk-js';
 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';
@@ -31,6 +33,71 @@ export type ConnectPermissionRequest = {
   /** The scope of the permissions being requested for the given protocol */
   permissionScopes: DwnPermissionScope[];
 };
+
+/**
+ * A scope-aware decryption key delivered to delegates during the connect flow.
+ *
+ * Two scope kinds:
+ *
+ * - **`protocol`** — protocol-wide key at depth `[ProtocolPath, protocolUri]`.
+ *   Can derive leaf keys for any type path within the protocol.
+ *   Issued when the grant covers the entire protocol (no `protocolPath`).
+ *
+ * - **`protocolPath`** — exact-path key at depth
+ *   `[ProtocolPath, protocolUri, ...pathSegments]`.
+ *   Can only decrypt records at that exact path — not siblings or descendants.
+ *   Issued when the grant is narrowed to a specific `protocolPath`.
+ *
+ * Common conditions (both kinds):
+ * 1. The protocol has `encryptionRequired: true` types (single-party only)
+ * 2. The delegate has at least one read-like scope (Read/Query/Subscribe)
+ * 3. The protocol does NOT use multi-party / role-based access patterns
+ *
+ * Out of scope (fail closed):
+ * - `contextId`-scoped encrypted delegate reads
+ * - multi-party / ProtocolContext encrypted delegate reads
+ */
+export type DelegateDecryptionKey =
+  | {
+    /** The protocol URI this key is scoped to. */
+    protocol: string;
+    /** Protocol-wide decryption scope. */
+    scope: { kind: 'protocol' };
+    /** The derived private key material for ProtocolPath decryption. */
+    derivedPrivateKey: DerivedPrivateJwk;
+  }
+  | {
+    /** The protocol URI this key is scoped to. */
+    protocol: string;
+    /** Exact-path decryption scope — siblings and descendants are NOT accessible. */
+    scope: { kind: 'protocolPath'; protocolPath: string; match: 'exact' };
+    /** The derived private key material for ProtocolPath decryption. */
+    derivedPrivateKey: DerivedPrivateJwk;
+  };
+
+/**
+ * A context-scoped decryption key for a multi-party encrypted protocol.
+ *
+ * Delivered to delegates during the connect flow so they can decrypt
+ * ProtocolContext-encrypted records without the owner's root X25519 key.
+ *
+ * Each key is scoped to one rootContextId — it unlocks all records within
+ * that context domain but cannot access other contexts in the protocol.
+ *
+ * Delivered only when:
+ * 1. The protocol has multi-party access patterns (detected by `isMultiPartyContext`)
+ * 2. The delegate has a protocol-wide read-like scope (no protocolPath/contextId)
+ * 3. The protocol has `encryptionRequired: true` types
+ */
+export type DelegateContextKey = {
+  /** The protocol URI this key belongs to. */
+  protocol: string;
+  /** The root context ID this key unlocks. */
+  contextId: string;
+  /** The derived private key at `[ProtocolContext, rootContextId]`. */
+  derivedPrivateKey: DerivedPrivateJwk;
+};
+
 import type {
   JoseHeaderParams,
   Jwk } from '@enbox/crypto';
@@ -45,12 +112,15 @@ import {
   X25519,
   XChaCha20Poly1305,
 } from '@enbox/crypto';
-import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
+import { DwnInterfaceName, DwnMethodName, HdKey, KeyDerivationScheme, PermissionsProtocol } from '@enbox/dwn-sdk-js';
 
 import { AgentPermissionsApi } from './permissions-api.js';
 import { concatenateUrl } from './utils.js';
 import { DwnInterface } from './types/dwn.js';
+import { getEncryptionKeyInfo } from './dwn-encryption.js';
+import { isMultiPartyContext } from './protocol-utils.js';
 import { isRecordPermissionScope } from './dwn-api.js';
+import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -143,6 +213,41 @@ export type EnboxConnectResponse = {
 
   /** The delegate DID's full portable form, including private keys. */
   delegatePortableDid: PortableDid;
+
+  /**
+   * Scope-aware decryption keys for encrypted protocols.
+   *
+   * Derived only for read-like permission scopes (Read/Query/Subscribe) on
+   * protocols with `encryptionRequired: true` types. Write-only delegates
+   * receive no decryption keys.
+   */
+  delegateDecryptionKeys?: DelegateDecryptionKey[];
+
+  /**
+   * Context-scoped decryption keys for multi-party encrypted protocols.
+   *
+   * Derived at connect time for each existing rootContextId in multi-party
+   * protocols where the delegate has a protocol-wide read-like scope.
+   * Each key is scoped to `[ProtocolContext, rootContextId]` and can decrypt
+   * all records within that context domain.
+   *
+   * Contexts created after connect are delivered automatically by
+   * `postWriteKeyDelivery()` when the owner creates a new multi-party root
+   * record on the same agent instance (same-process delivery).
+   * Cross-device delivery is a documented follow-up.
+   */
+  delegateContextKeys?: DelegateContextKey[];
+
+  /**
+   * Protocol URIs that have multi-party encrypted access patterns.
+   *
+   * Delivered even when no contexts exist yet (cold-start), so the
+   * delegate's agent can register for future context key delivery.
+   */
+  delegateMultiPartyProtocols?: string[];
+
+  /** Per-grant revocation mappings for session-bound self-revocation on disconnect. */
+  sessionRevocations?: { grantId: string; revocationGrantId: string }[];
 };
 
 /** The connect server endpoint types. */
@@ -530,6 +635,7 @@ async function createPermissionGrants(
   delegateBearerDid: BearerDid,
   agent: EnboxPlatformAgent,
   scopes: DwnPermissionScope[],
+  delegateKeyDeliveryData?: { rootKeyId: string; publicKeyJwk: Record<string, any> },
 ): Promise<DwnDataEncodedRecordsWriteMessage[]> {
   const permissionsApi = new AgentPermissionsApi({ agent });
 
@@ -537,6 +643,16 @@ async function createPermissionGrants(
   const permissionGrants = await Promise.all(
     scopes.map((scope) => {
       const delegated = shouldUseDelegatePermission(scope);
+
+      // Attach delegate key-delivery tags to read-like grants so the
+      // owner can encrypt future contextKey records to the delegate.
+      const readMethods = new Set([
+        DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe,
+      ]);
+      const isReadLike = isRecordPermissionScope(scope)
+        && readMethods.has(scope.method as DwnMethodName);
+      const delegateKeyDelivery = (isReadLike && delegateKeyDeliveryData) ? delegateKeyDeliveryData : undefined;
+
       return permissionsApi.createGrant({
         delegated,
         store       : true,
@@ -544,6 +660,7 @@ async function createPermissionGrants(
         scope,
         dateExpires : '2040-06-25T16:09:16.693356Z', // TODO: make dateExpires configurable
         author      : selectedDid,
+        delegateKeyDelivery,
       });
     })
   );
@@ -604,12 +721,22 @@ 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.
+ *
+ * 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.
  */
 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,
@@ -627,6 +754,7 @@ async function prepareProtocol(
       target        : selectedDid,
       messageType   : DwnInterface.ProtocolsConfigure,
       messageParams : { definition: protocolDefinition },
+      encryption    : needsEncryption || undefined,
     });
 
     if (sendReply.status.code !== 202 && sendReply.status.code !== 409) {
@@ -656,6 +784,277 @@ async function prepareProtocol(
   }
 }
 
+/**
+ * Derives the minimal set of decryption keys implied by read-like permission
+ * scopes for a single-party encrypted protocol.
+ *
+ * Rules:
+ *   - Only Records.Read / Records.Query / Records.Subscribe scopes contribute.
+ *   - Write / Delete / Count scopes produce no decryption keys.
+ *   - If any unrestricted (no `protocolPath`) read scope exists, one
+ *     protocol-wide key is emitted and narrower keys are dropped.
+ *   - Otherwise one exact-path key is emitted per unique `protocolPath`.
+ *   - Scopes with `contextId` cause a fail-closed error.
+ *   - Multi-party protocols cause a fail-closed error.
+ *
+ * @param agent - The platform agent (must hold the owner's KMS keys)
+ * @param ownerDid - The DID of the protocol owner
+ * @param protocolUri - The protocol URI
+ * @param scopes - The permission scopes for this protocol
+ * @param protocolDefinition - The protocol definition (for multi-party detection)
+ * @returns An array of `DelegateDecryptionKey` (may be empty)
+ */
+async function deriveScopedDecryptionKeys(
+  agent: EnboxPlatformAgent,
+  ownerDid: string,
+  protocolUri: string,
+  scopes: DwnPermissionScope[],
+  protocolDefinition: DwnProtocolDefinition,
+): Promise<DelegateDecryptionKey[]> {
+  const readMethods = new Set([
+    DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe,
+  ]);
+
+  // Collect read-like scopes only.
+  const readScopes = scopes.filter(
+    (s): s is DwnPermissionScope & { method: string } =>
+      isRecordPermissionScope(s) && readMethods.has(s.method as DwnMethodName),
+  );
+
+  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 as any).contextId) {
+      throw new Error(
+        `Encrypted delegate access scoped by contextId is not supported ` +
+        `yet; use protocol-wide permissions for protocol '${protocolUri}'.`,
+      );
+    }
+  }
+
+  // Defense-in-depth: reject if any root is multi-party.
+  // The caller should have already routed multi-party protocols to
+  // deriveContextKeysForDelegate instead.
+  const { multiParty } = classifyProtocolRoots(protocolDefinition);
+  if (multiParty.length > 0) {
+    throw new Error(
+      `deriveScopedDecryptionKeys called for protocol with multi-party ` +
+      `roots [${multiParty.join(', ')}]. Use deriveContextKeysForDelegate ` +
+      `for multi-party protocols.`,
+    );
+  }
+
+  // Check if any scope is protocol-wide (no protocolPath).
+  const hasProtocolWideRead = readScopes.some(
+    (s) => !('protocolPath' in s) || !(s as any).protocolPath,
+  );
+
+  const { keyId, keyUri } = await getEncryptionKeyInfo(agent, ownerDid);
+
+  // If any unrestricted read scope exists, emit one protocol-wide key
+  // and skip narrower keys (the protocol-wide key subsumes them).
+  if (hasProtocolWideRead) {
+    const derivationPath = [KeyDerivationScheme.ProtocolPath, protocolUri];
+    const derivedBytes = await agent.keyManager.derivePrivateKeyBytes({
+      keyUri, derivationPath,
+    });
+    const derivedJwk = await X25519.bytesToPrivateKey({ privateKeyBytes: derivedBytes });
+
+    return [{
+      protocol          : protocolUri,
+      scope             : { kind: 'protocol' },
+      derivedPrivateKey : {
+        rootKeyId         : keyId,
+        derivationScheme  : KeyDerivationScheme.ProtocolPath,
+        derivationPath,
+        derivedPrivateKey : derivedJwk as PrivateKeyJwk,
+      },
+    }];
+  }
+
+  // All read scopes are protocolPath-scoped.
+  // 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); }
+  }
+
+  const keys: DelegateDecryptionKey[] = [];
+  for (const protocolPath of uniquePaths) {
+    const pathSegments = protocolPath.split('/');
+    const derivationPath = [KeyDerivationScheme.ProtocolPath, protocolUri, ...pathSegments];
+    const derivedBytes = await agent.keyManager.derivePrivateKeyBytes({
+      keyUri, derivationPath,
+    });
+    const derivedJwk = await X25519.bytesToPrivateKey({ privateKeyBytes: derivedBytes });
+
+    keys.push({
+      protocol          : protocolUri,
+      scope             : { kind: 'protocolPath', protocolPath, match: 'exact' },
+      derivedPrivateKey : {
+        rootKeyId         : keyId,
+        derivationScheme  : KeyDerivationScheme.ProtocolPath,
+        derivationPath,
+        derivedPrivateKey : derivedJwk as PrivateKeyJwk,
+      },
+    });
+  }
+
+  return keys;
+}
+
+/**
+ * Detects whether a protocol definition has any root-level type whose subtree
+ * triggers multi-party semantics. Delegates to the canonical
+ * `isMultiPartyContext()` from `protocol-utils.ts` which checks:
+ *
+ *   - `$role: true` descendants in the subtree
+ *   - Relational `who`/`of` `$actions` rules that grant `read` access
+ *
+ * These patterns cause the DWN agent to use ProtocolContext encryption at
+ * write time, which is not supported in delegate sessions yet.
+ */
+/**
+ * Classifies root-level types in a protocol definition into multi-party
+ * and single-party buckets. Used to detect mixed protocols that cannot
+ * be safely modeled with a single key type.
+ */
+function classifyProtocolRoots(
+  definition: DwnProtocolDefinition,
+): { multiParty: string[]; singleParty: string[] } {
+  const structure = definition.structure;
+  if (!structure) { return { multiParty: [], singleParty: [] }; }
+
+  const multiParty: string[] = [];
+  const singleParty: string[] = [];
+
+  for (const rootTypeName of Object.keys(structure)) {
+    if (rootTypeName.startsWith('$')) { continue; }
+    if (isMultiPartyContext(definition, rootTypeName)) {
+      multiParty.push(rootTypeName);
+    } else {
+      singleParty.push(rootTypeName);
+    }
+  }
+
+  return { multiParty, singleParty };
+}
+
+/**
+ * Derives per-context decryption keys for a delegate's access to a multi-party
+ * encrypted protocol. Queries the owner's DWN for all root-level records
+ * (thread roots, etc.) and derives a `[ProtocolContext, rootContextId]` key
+ * for each.
+ *
+ * Validates scopes first — only protocol-wide read-like scopes are accepted.
+ * `protocolPath`-scoped and `contextId`-scoped reads throw (not yet supported).
+ * Write-only scopes return empty (no decryption keys needed).
+ *
+ * @param agent - The platform agent (must hold the owner's KMS keys)
+ * @param ownerDid - The DID of the protocol owner
+ * @param protocolDefinition - The protocol definition
+ * @param scopes - The permission scopes for this protocol
+ * @returns An array of `DelegateContextKey` (may be empty)
+ */
+async function deriveContextKeysForDelegate(
+  agent: EnboxPlatformAgent,
+  ownerDid: string,
+  protocolDefinition: DwnProtocolDefinition,
+  scopes: DwnPermissionScope[],
+): Promise<DelegateContextKey[]> {
+  const readMethods = new Set([
+    DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe,
+  ]);
+
+  const readScopes = scopes.filter(
+    (s): s is DwnPermissionScope & { method: string } =>
+      isRecordPermissionScope(s) && readMethods.has(s.method as DwnMethodName),
+  );
+
+  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 as any).contextId) {
+      throw new Error(
+        `Encrypted delegate access scoped by contextId is not supported ` +
+        `yet; use protocol-wide permissions for protocol ` +
+        `'${protocolDefinition.protocol}'.`,
+      );
+    }
+  }
+
+  // Fail closed: reject protocolPath-scoped reads on multi-party protocols.
+  for (const scope of readScopes) {
+    if ('protocolPath' in scope && (scope as any).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}'.`,
+      );
+    }
+  }
+
+  // All read scopes are protocol-wide. Derive context keys for each
+  // existing root-level context in the protocol.
+  const { keyId, keyUri } = await getEncryptionKeyInfo(agent, ownerDid);
+  const protocolUri = protocolDefinition.protocol;
+
+  // Find root-level types (non-$ keys in structure).
+  const rootTypes = Object.keys(protocolDefinition.structure ?? {})
+    .filter((k) => !k.startsWith('$'));
+
+  const contextKeys: DelegateContextKey[] = [];
+  const seenContextIds = new Set<string>();
+
+  for (const rootType of rootTypes) {
+    // Query all root records for this type.
+    const { reply } = await agent.processDwnRequest({
+      author        : ownerDid,
+      target        : ownerDid,
+      messageType   : DwnInterface.RecordsQuery,
+      messageParams : {
+        filter: { protocol: protocolUri, protocolPath: rootType },
+      },
+    });
+
+    for (const entry of reply.entries ?? []) {
+      const rootContextId = (entry as any).contextId?.split('/')[0]
+        || (entry as any).recordId;
+
+      if (!rootContextId || seenContextIds.has(rootContextId)) { continue; }
+      seenContextIds.add(rootContextId);
+
+      const derivationPath = [KeyDerivationScheme.ProtocolContext, rootContextId];
+      const derivedBytes = await agent.keyManager.derivePrivateKeyBytes({
+        keyUri, derivationPath,
+      });
+      const derivedJwk = await X25519.bytesToPrivateKey({
+        privateKeyBytes: derivedBytes,
+      });
+
+      contextKeys.push({
+        protocol          : protocolUri,
+        contextId         : rootContextId,
+        derivedPrivateKey : {
+          rootKeyId         : keyId,
+          derivationScheme  : KeyDerivationScheme.ProtocolContext,
+          derivationPath,
+          derivedPrivateKey : derivedJwk as PrivateKeyJwk,
+        },
+      });
+    }
+  }
+
+  return contextKeys;
+}
+
 // ---------------------------------------------------------------------------
 // Full wallet-side flow (provider submits response)
 // ---------------------------------------------------------------------------
@@ -682,6 +1081,62 @@ async function submitConnectResponse(
   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 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,
+  };
+
+  // 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 delegateGrantPromises = connectRequest.permissionRequests.map(
     async (permissionRequest) => {
       const { protocolDefinition, permissionScopes } = permissionRequest;
@@ -695,25 +1150,136 @@ async function submitConnectResponse(
 
       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
+        permissionScopes,
+        delegateKeyDeliveryData,
       );
     }
   );
 
   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;
+  for (let i = 0; i < sessionGrantCount; i++) {
+    const grantMessage = delegateGrants[i];
+    const revGrant = await permissionsApi.createGrant({
+      delegated : true,
+      store     : true,
+      grantedTo : delegateBearerDid.uri,
+      scope     : {
+        interface : DwnInterfaceName.Records,
+        method    : DwnMethodName.Write,
+        protocol  : PermissionsProtocol.uri,
+        contextId : grantMessage.recordId,
+      },
+      dateExpires : '2040-06-25T16:09:16.693356Z',
+      author      : selectedDid,
+    });
+    sessionRevocations.push({
+      grantId           : grantMessage.recordId,
+      revocationGrantId : revGrant.message.recordId,
+    });
+
+    // Fan out the revocation grant to all owner DWN endpoints (same
+    // as session grants) so that immediate disconnect can send a
+    // delegated revocation to a remote DWN that recognises the grant.
+    const { encodedData: revEncoded, ...revRawMessage } = revGrant.message;
+    const revData = Convert.base64Url(revEncoded).toUint8Array();
+    for (const dwnUrl of revGrantEndpoints) {
+      try {
+        await agent.rpc.sendDwnRequest({
+          dwnUrl,
+          targetDid : selectedDid,
+          message   : revRawMessage,
+          data      : new Blob([revData as BlobPart]),
+        });
+      } catch {
+        // Best-effort — sync will deliver eventually.
+      }
+    }
+
+    // Include the revocation grant in the delegate grants for distribution
+    delegateGrants.push(revGrant.message);
+  }
+
   logger.log('Building connect response...');
   const responseObject = await EnboxConnectProtocol.createConnectResponse({
-    providerDid : selectedDid,
-    delegateDid : delegateBearerDid.uri,
-    aud         : connectRequest.clientDid,
-    nonce       : connectRequest.nonce,
+    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...');
@@ -771,4 +1337,7 @@ export const EnboxConnectProtocol = {
   createConnectResponse,
   createPermissionGrants,
   submitConnectResponse,
+  deriveScopedDecryptionKeys,
+  deriveContextKeysForDelegate,
+  classifyProtocolRoots,
 };