@enbox/agent 0.5.16 → 0.6.0

package/src/dwn-encryption.ts

@@ -7,7 +7,7 @@ import type {
   RecordsReadReply,
   RecordsWriteMessage,
 } from '@enbox/dwn-sdk-js';
-import type { KeyIdentifier, PublicKeyJwk } from '@enbox/crypto';
+import type { Jwk, KeyIdentifier, PublicKeyJwk } from '@enbox/crypto';
 
 import type { EnboxPlatformAgent } from './types/agent.js';
 import type {
@@ -16,7 +16,6 @@ import type {
   SendDwnRequest,
 } from './types/dwn.js';
 
-import { X25519 } from '@enbox/crypto';
 import {
   Cid,
   ContentEncryptionAlgorithm,
@@ -26,6 +25,7 @@ import {
   KeyDerivationScheme,
   Records,
 } from '@enbox/dwn-sdk-js';
+import { Ed25519, X25519 } from '@enbox/crypto';
 
 import { DwnInterface } from './types/dwn.js';
 import { isDwnRequest } from './dwn-type-guards.js';
@@ -140,22 +140,33 @@ export async function getEncryptionKeyInfo(
     );
   }
 
-  // 4. Verify it's an X25519 key
-  const publicKeyJwk = verificationMethod.publicKeyJwk;
-  if (publicKeyJwk.crv !== 'X25519') {
+  // 4. Resolve or derive the X25519 key for encryption.
+  // Standard case: the keyAgreement VM already has an X25519 key.
+  // Delegate case: did:jwk with Ed25519 only — convert to X25519.
+  // The Ed25519→X25519 conversion is a standard cryptographic operation
+  // (RFC 8032 / libsodium). The converted X25519 key must already be
+  // present in the agent's KMS (imported via the delegate PortableDid).
+  let resolvedPublicKeyJwk = verificationMethod.publicKeyJwk;
+
+  if (resolvedPublicKeyJwk.crv === 'Ed25519') {
+    resolvedPublicKeyJwk = await Ed25519.convertPublicKeyToX25519({
+      publicKey: resolvedPublicKeyJwk,
+    });
+  } else if (resolvedPublicKeyJwk.crv !== 'X25519') {
     throw new Error(
       `AgentDwnApi: keyAgreement key for '${didUri}' uses curve ` +
-      `'${publicKeyJwk.crv}', but DWN encryption requires 'X25519'.`
+      `'${resolvedPublicKeyJwk.crv}', but DWN encryption requires ` +
+      `'X25519' (or 'Ed25519' which is auto-converted).`
     );
   }
 
   // 5. Compute the KMS key URI (does NOT export the key)
-  const keyUri = await agent.keyManager.getKeyUri({ key: publicKeyJwk });
+  const keyUri = await agent.keyManager.getKeyUri({ key: resolvedPublicKeyJwk });
 
   return {
     keyId        : verificationMethod.id,
     keyUri,
-    publicKeyJwk : publicKeyJwk as PublicKeyJwk,
+    publicKeyJwk : resolvedPublicKeyJwk as PublicKeyJwk,
   };
 }
 
@@ -295,11 +306,55 @@ export function buildContextKeyDecrypter(
   };
 }
 
+/** Cache entry shape for scope-aware delegate decryption keys. */
+export type DelegateDecryptionKeyEntry = {
+  protocol: string;
+  scope: { kind: 'protocol' } | { kind: 'protocolPath'; protocolPath: string; match: 'exact' };
+  derivedPrivateKey: DerivedPrivateJwk;
+};
+
+/**
+ * Builds a KeyDecrypter for an exact-path delegate key that enforces the
+ * record's full derivation path matches the key's path exactly — siblings
+ * and descendants are NOT accessible.
+ */
+export function buildExactProtocolPathDecrypter(
+  key: DerivedPrivateJwk,
+): KeyDecrypter {
+  return {
+    rootKeyId        : key.rootKeyId,
+    derivationScheme : key.derivationScheme,
+    decrypt          : async (
+      fullDerivationPath: string[],
+      jwePayload: { ephemeralPublicKey: Jwk; encryptedKey: Uint8Array },
+    ): Promise<Uint8Array> => {
+      const keyPath = key.derivationPath ?? [];
+      if (keyPath.length !== fullDerivationPath.length ||
+          !keyPath.every((seg: string, i: number) => seg === fullDerivationPath[i])) {
+        throw new Error(
+          'Delegate decryption key is out of scope for this protocol path. ' +
+          `Key path: [${keyPath.join(', ')}], ` +
+          `record path: [${fullDerivationPath.join(', ')}].`
+        );
+      }
+      const leafPrivateKeyBytes = await Records.derivePrivateKey(key, fullDerivationPath);
+      const leafPrivateKeyJwk = await X25519.bytesToPrivateKey({ privateKeyBytes: leafPrivateKeyBytes });
+      return Encryption.ecdhEsUnwrapKey(leafPrivateKeyJwk, jwePayload.ephemeralPublicKey, jwePayload.encryptedKey);
+    },
+  };
+}
+
 /**
  * Resolves the appropriate KeyDecrypter for a record's encryption scheme.
  * Handles both single-party (ProtocolPath) and multi-party (ProtocolContext).
  *
+ * For ProtocolPath records:
+ *   - Owner: derives key directly from KMS
+ *   - Delegate with protocol-wide key: uses ancestor-prefix derivation
+ *   - Delegate with exact-path key: enforces exact path match
+ *
  * For ProtocolContext records:
+ *   - Delegate: uses delivered context key from the connect flow
  *   - Context creator: derives key directly from KMS
  *   - Participant: fetches contextKey via key-delivery protocol, caches it
  *
@@ -309,6 +364,8 @@ export function buildContextKeyDecrypter(
  * @param targetDid - The target DID (DWN owner), if known
  * @param contextDerivedKeyCache - Cache for context-derived private keys
  * @param fetchContextKeyRecordFn - Function to fetch context key records from key-delivery protocol
+ * @param delegateDecryptionKeyCache - Cache for scope-aware delegate decryption keys
+ * @param granteeDid - The delegate DID (if this is a delegated request)
  */
 export async function resolveKeyDecrypter(
   agent: EnboxPlatformAgent,
@@ -322,6 +379,9 @@ export async function resolveKeyDecrypter(
     sourceProtocol: string;
     sourceContextId: string;
   }) => Promise<DerivedPrivateJwk | undefined>,
+  delegateDecryptionKeyCache?: { get(key: string): DelegateDecryptionKeyEntry[] | undefined },
+  granteeDid?: string,
+  delegateContextKeyCache?: { get(key: string): DerivedPrivateJwk | undefined; set(key: string, value: DerivedPrivateJwk): void },
 ): Promise<KeyDecrypter> {
   const { encryption } = recordsWrite;
 
@@ -331,7 +391,37 @@ export async function resolveKeyDecrypter(
   );
 
   if (!hasContextKey || !recordsWrite.contextId) {
-    // Single-party protocol-path encryption
+    // Single-party protocol-path encryption.
+    // Check for scope-aware delegate decryption keys first — this enables
+    // delegates to decrypt without the owner's root X25519 private key.
+    if (delegateDecryptionKeyCache && granteeDid) {
+      const protocol = recordsWrite.descriptor.protocol;
+      const protocolPath = recordsWrite.descriptor.protocolPath;
+      if (protocol) {
+        const cacheKey = `ddk~${granteeDid}`;
+        const allKeys = delegateDecryptionKeyCache.get(cacheKey);
+        if (allKeys) {
+          const keysForProtocol = allKeys.filter((k) => k.protocol === protocol);
+
+          // Priority 1: exact-path key matching this record's protocolPath.
+          if (protocolPath) {
+            const exactKey = keysForProtocol.find(
+              (k) => k.scope.kind === 'protocolPath' && k.scope.protocolPath === protocolPath
+            );
+            if (exactKey) {
+              return buildExactProtocolPathDecrypter(exactKey.derivedPrivateKey);
+            }
+          }
+
+          // Priority 2: protocol-wide key (ancestor-prefix derivation).
+          const wideKey = keysForProtocol.find((k) => k.scope.kind === 'protocol');
+          if (wideKey) {
+            return buildContextKeyDecrypter(wideKey.derivedPrivateKey);
+          }
+        }
+      }
+    }
+
     return getKeyDecrypter(agent, authorDid);
   }
 
@@ -342,6 +432,60 @@ export async function resolveKeyDecrypter(
 
   const rootContextId = recordsWrite.contextId.split('/')[0];
 
+  // Case 0: Delegate with a delivered context key for this rootContextId.
+  // First check the in-memory cache (same-process delivery).
+  // On cache miss, try to fetch a contextKey record from the owner's DWN
+  // (cross-device delivery via the key-delivery protocol).
+  //
+  // IMPORTANT: If this is a delegated request (granteeDid is set), we must
+  // NOT fall through to Cases 1/2 which use authorDid (the owner). Delegates
+  // must decrypt via their own delivered context key — never via the owner's
+  // KMS. This is fail-closed by design.
+  if (delegateContextKeyCache && granteeDid) {
+    const protocol = recordsWrite.descriptor.protocol;
+    if (protocol) {
+      const ctxCacheKey = `dctx~${granteeDid}~${protocol}~${rootContextId}`;
+      const delegateCtxKey = delegateContextKeyCache.get(ctxCacheKey);
+      if (delegateCtxKey) {
+        return buildContextKeyDecrypter(delegateCtxKey);
+      }
+
+      // Cache miss — try fetching a delivered contextKey record.
+      // The owner may have written one addressed to this delegate
+      // after the initial connect (cross-device delivery).
+      //
+      // For cross-device (ownerDid !== requesterDid), fetchContextKeyRecord
+      // queries the owner's tenant on the delegate's local DWN via
+      // processRequest. The delegate identity's connectedDid metadata
+      // registers ownerDid as locally-managed, so the query routes locally
+      // (in-process node or local-server RPC) — not to the owner's remote
+      // endpoint. Sync must have brought the contextKey record locally.
+      try {
+        const fetchedKey = await fetchContextKeyRecordFn({
+          ownerDid        : authorDid,
+          requesterDid    : granteeDid,
+          sourceProtocol  : protocol,
+          sourceContextId : rootContextId,
+        });
+        if (fetchedKey) {
+          delegateContextKeyCache.set(ctxCacheKey, fetchedKey);
+          return buildContextKeyDecrypter(fetchedKey);
+        }
+      } catch {
+        // Delegate fetch failed — fail closed below.
+      }
+    }
+
+    // Delegate path exhausted: no cached key, no delivered record.
+    // Fail closed — do NOT fall through to the owner KMS path.
+    throw new Error(
+      `AgentDwnApi: Delegate '${granteeDid}' does not have a context key ` +
+      `for context '${rootContextId}'. No delivered contextKey record was ` +
+      `found via the key-delivery protocol. The delegate may need to ` +
+      `reconnect or wait for sync.`
+    );
+  }
+
   // Case 1: I am the context creator — rootKeyId matches my encryption key
   const { keyId, keyUri } = await getEncryptionKeyInfo(agent, authorDid);
   if (contextKeyEntry.header.kid === keyId) {
@@ -405,6 +549,7 @@ export async function resolveKeyDecrypter(
  * @param agent - The platform agent
  * @param contextDerivedKeyCache - Cache for context-derived private keys
  * @param fetchContextKeyRecordFn - Function to fetch context key records
+ * @param delegateDecryptionKeyCache - Cache for scope-aware delegate decryption keys
  */
 export async function maybeDecryptReply<T extends DwnInterface>(
   request: ProcessDwnRequest<T> | SendDwnRequest<T>,
@@ -417,6 +562,8 @@ export async function maybeDecryptReply<T extends DwnInterface>(
     sourceProtocol: string;
     sourceContextId: string;
   }) => Promise<DerivedPrivateJwk | undefined>,
+  delegateDecryptionKeyCache?: { get(key: string): DelegateDecryptionKeyEntry[] | undefined },
+  delegateContextKeyCache?: { get(key: string): DerivedPrivateJwk | undefined; set(key: string, value: DerivedPrivateJwk): void },
 ): Promise<void> {
   if (!('encryption' in request) || !request.encryption) {
     return;
@@ -430,7 +577,8 @@ export async function maybeDecryptReply<T extends DwnInterface>(
         && readReply.entry?.data) {
       const keyDecrypter = await resolveKeyDecrypter(
         agent, request.author, readReply.entry.recordsWrite, request.target,
-        contextDerivedKeyCache, fetchContextKeyRecordFn,
+        contextDerivedKeyCache, fetchContextKeyRecordFn, delegateDecryptionKeyCache,
+        (request as any).granteeDid, delegateContextKeyCache,
       );
 
       try {
@@ -457,7 +605,8 @@ export async function maybeDecryptReply<T extends DwnInterface>(
         if (entry.encryption && entry.encodedData) {
           const keyDecrypter = await resolveKeyDecrypter(
             agent, request.author, entry as RecordsWriteMessage, request.target,
-            contextDerivedKeyCache, fetchContextKeyRecordFn,
+            contextDerivedKeyCache, fetchContextKeyRecordFn, delegateDecryptionKeyCache,
+            (request as any).granteeDid, delegateContextKeyCache,
           );
 
           try {

package/src/dwn-key-delivery.ts

@@ -2,7 +2,6 @@ import type { PublicKeyJwk } from '@enbox/crypto';
 import type {
   DerivedPrivateJwk,
   EncryptionInput,
-  RecordsQueryReply,
   RecordsReadReply,
 } from '@enbox/dwn-sdk-js';
 
@@ -19,12 +18,12 @@ import {
   KeyDerivationScheme,
   Message,
   Protocols,
-  Records,
 } from '@enbox/dwn-sdk-js';
 
+import { DwnInterface } from './types/dwn.js';
 import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
-import { buildEncryptionInput, encryptAndComputeCid, getEncryptionKeyDeriver, getKeyDecrypter, ivLength } from './dwn-encryption.js';
-import { DwnInterface, dwnMessageConstructors } from './types/dwn.js';
+
+import { buildEncryptionInput, encryptAndComputeCid, getEncryptionKeyDeriver, ivLength } from './dwn-encryption.js';
 
 /**
  * Parameters for writeContextKeyRecord.
@@ -255,6 +254,59 @@ export async function eagerSendContextKeyRecord(
   });
 }
 
+/**
+ * Fetches a contextKey record from the owner's tenant via `processRequest`.
+ *
+ * This works in both agent modes:
+ * - In-process DWN node: `processRequest` routes locally via the DWN instance
+ * - Remote/local-server mode: `processRequest` routes via RPC to the local DWN server
+ *
+ * The delegate identity's `connectedDid` metadata registers `ownerDid` as a
+ * locally-managed DID, so `processRequest` routes to the local DWN (not the
+ * owner's remote endpoint).
+ *
+ * Requires sync to have brought the contextKey record to the owner's tenant
+ * on the delegate's DWN before this is called.
+ */
+async function fetchCrossDeviceContextKey(
+  processRequest: ProcessRequestFn,
+  requesterDid: string,
+  ownerDid: string,
+  contextKeyFilter: Record<string, any>,
+  parsePayload: (bytes: Uint8Array) => DerivedPrivateJwk,
+): Promise<DerivedPrivateJwk | undefined> {
+  try {
+    const { reply } = await processRequest({
+      author        : requesterDid,
+      target        : ownerDid,
+      messageType   : DwnInterface.RecordsQuery,
+      messageParams : { filter: contextKeyFilter },
+    });
+
+    if (reply.status.code !== 200 || !reply.entries?.length) {
+      return undefined;
+    }
+
+    const recordId = reply.entries[0].recordId;
+    const { reply: readReply } = await processRequest({
+      author        : requesterDid,
+      target        : ownerDid,
+      messageType   : DwnInterface.RecordsRead,
+      messageParams : { filter: { recordId } },
+      encryption    : true,
+    });
+
+    const readResult = readReply as RecordsReadReply;
+    if (!readResult.entry?.data) {
+      return undefined;
+    }
+
+    return parsePayload(await DataStream.toBytes(readResult.entry.data));
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Fetches and decrypts a `contextKey` record from a DWN, returning the
  * `DerivedPrivateJwk` payload.
@@ -265,18 +317,12 @@ export async function eagerSendContextKeyRecord(
  * @param agent - The platform agent
  * @param params - The fetch parameters
  * @param processRequest - The agent's processRequest method (bound)
- * @param getSigner - Function to get a signer for a DID
- * @param sendDwnRpcRequest - Function to send a DWN RPC request
- * @param getDwnEndpointUrlsForTarget - Function to resolve DWN endpoint URLs (with local discovery)
  * @returns The decrypted `DerivedPrivateJwk`, or `undefined` if no matching record found
  */
 export async function fetchContextKeyRecord(
-  agent: EnboxPlatformAgent,
+  _agent: EnboxPlatformAgent,
   params: FetchContextKeyParams,
   processRequest: ProcessRequestFn,
-  getSigner: (author: string) => Promise<any>,
-  sendDwnRpcRequest: (params: { targetDid: string; dwnEndpointUrls: string[]; message: any; data?: Blob }) => Promise<any>,
-  getDwnEndpointUrlsForTarget: (targetDid: string) => Promise<string[]>,
 ): Promise<DerivedPrivateJwk | undefined> {
   const { ownerDid, requesterDid, sourceProtocol, sourceContextId } = params;
   const protocolUri = KeyDeliveryProtocolDefinition.protocol;
@@ -295,7 +341,7 @@ export async function fetchContextKeyRecord(
     JSON.parse(new TextDecoder().decode(bytes)) as DerivedPrivateJwk;
 
   if (isLocal) {
-    // Local query: owner queries their own DWN
+    // Local query via processRequest: owner queries their own DWN.
     const { reply } = await processRequest({
       author        : requesterDid,
       target        : ownerDid,
@@ -307,13 +353,12 @@ export async function fetchContextKeyRecord(
       return undefined;
     }
 
-    // Read the full record to get the data (auto-decrypted by processRequest)
-    const recordId = reply.entries[0].recordId;
+    const localRecordId = reply.entries[0].recordId;
     const { reply: readReply } = await processRequest({
       author        : requesterDid,
       target        : ownerDid,
       messageType   : DwnInterface.RecordsRead,
-      messageParams : { filter: { recordId } },
+      messageParams : { filter: { recordId: localRecordId } },
       encryption    : true,
     });
 
@@ -323,51 +368,18 @@ export async function fetchContextKeyRecord(
     }
 
     return parsePayload(await DataStream.toBytes(readResult.entry.data));
-  } else {
-    // Remote query: participant queries the context owner's DWN
-    const signer = await getSigner(requesterDid);
-    const dwnEndpointUrls = await getDwnEndpointUrlsForTarget(ownerDid);
-
-    const recordsQuery = await dwnMessageConstructors[DwnInterface.RecordsQuery].create({
-      signer,
-      filter: contextKeyFilter,
-    });
-
-    const queryReply = await sendDwnRpcRequest({
-      targetDid : ownerDid,
-      dwnEndpointUrls,
-      message   : recordsQuery.message,
-    }) as RecordsQueryReply;
-
-    if (queryReply.status.code !== 200 || !queryReply.entries?.length) {
-      return undefined;
-    }
-
-    // Read the full record remotely
-    const recordId = queryReply.entries[0].recordId;
-    const recordsRead = await dwnMessageConstructors[DwnInterface.RecordsRead].create({
-      signer,
-      filter: { recordId },
-    });
-
-    const readReply = await sendDwnRpcRequest({
-      targetDid : ownerDid,
-      dwnEndpointUrls,
-      message   : recordsRead.message,
-    }) as RecordsReadReply;
-
-    if (!readReply.entry?.data || !readReply.entry?.recordsWrite) {
-      return undefined;
-    }
-
-    // Decrypt the contextKey payload using the requester's key-delivery protocol path key
-    const keyDecrypter = await getKeyDecrypter(agent, requesterDid);
-    const decryptedStream = await Records.decrypt(
-      readReply.entry.recordsWrite,
-      keyDecrypter,
-      readReply.entry.data as ReadableStream<Uint8Array>,
-    );
-
-    return parsePayload(await DataStream.toBytes(decryptedStream));
   }
+
+  // Cross-device path: the requester is NOT the owner.
+  // Query the owner's tenant on the delegate's DWN via processRequest.
+  // The delegate identity's connectedDid metadata registers ownerDid as
+  // locally-managed, so processRequest routes locally (in-process or
+  // local-server RPC) rather than to the owner's remote DWN endpoint.
+  //
+  // Sync must have brought the contextKey record to the owner's tenant
+  // on the delegate's DWN before this is called.
+  // If fetch fails, the caller's fail-closed guard will fire.
+  return fetchCrossDeviceContextKey(
+    processRequest, requesterDid, ownerDid, contextKeyFilter, parsePayload,
+  );
 }