@enbox/dwn-sdk-js 0.4.4 → 0.4.6

package/src/utils/permission-scope.ts

@@ -16,9 +16,9 @@ export type ProtocolScope = {
  *
  * Matching fails closed for invalid combinations: `protocolPath` and
  * `contextId` are mutually exclusive, and either field requires `protocol`.
- * `protocol` and `protocolPath` match by exact equality. `contextId` scopes
- * match a context subtree: the target context must equal the scoped context or
- * begin with the scoped context followed by `/`.
+ * `protocol` matches by exact equality. `protocolPath` and `contextId` scopes
+ * match subtrees: the target value must equal the scoped value or begin with the
+ * scoped value followed by `/`.
  */
 export class PermissionScopeMatcher {
   /**
@@ -38,7 +38,7 @@ export class PermissionScopeMatcher {
     }
 
     if (scope.protocolPath !== undefined) {
-      return scope.protocolPath === target.protocolPath;
+      return PermissionScopeMatcher.matchesSubtree(scope.protocolPath, target.protocolPath);
     }
 
     if (scope.contextId !== undefined) {
@@ -49,7 +49,11 @@ export class PermissionScopeMatcher {
   }
 
   private static matchesContextId(scopeContextId: string, candidateContextId: unknown): boolean {
-    return typeof candidateContextId === 'string' &&
-      (candidateContextId === scopeContextId || candidateContextId.startsWith(scopeContextId + '/'));
+    return PermissionScopeMatcher.matchesSubtree(scopeContextId, candidateContextId);
+  }
+
+  private static matchesSubtree(scopeValue: string, candidateValue: unknown): boolean {
+    return typeof candidateValue === 'string' &&
+      (candidateValue === scopeValue || candidateValue.startsWith(scopeValue + '/'));
   }
 }

package/src/utils/protocols.ts

@@ -77,11 +77,10 @@ export function getRuleSetAtPath(protocolPath: string, structure: { [key: string
  */
 export class Protocols {
   /**
-   * Derives public encryptions keys and inject it in the `$encryption` property for each protocol path segment of the given Protocol definition,
-   * then returns the final encryption-enabled protocol definition.
+   * Derives public encryption keys and injects them in `$keyAgreement`.
    * NOTE: The original definition passed in is unmodified.
    *
-   * `$ref` nodes (cross-protocol attachment points) are skipped during `$encryption` injection
+   * `$ref` nodes (cross-protocol attachment points) are skipped during `$keyAgreement` injection
    * because their records belong to the referenced protocol, whose own encryption keys govern them.
    * Children of `$ref` nodes are still processed because they belong to the composing protocol.
    *
@@ -94,8 +93,7 @@ export class Protocols {
   ): Promise<ProtocolDefinition>;
 
   /**
-   * Overload 2 (raw-key, existing): Takes rootKeyId and raw PrivateKeyJwk directly.
-   * Preserved for backward compatibility with tests and non-KMS callers.
+   * Overload 2 (raw-key): Takes rootKeyId and raw PrivateKeyJwk directly.
    */
   public static async deriveAndInjectPublicEncryptionKeys(
     protocolDefinition: ProtocolDefinition,
@@ -103,7 +101,7 @@ export class Protocols {
     privateJwk: PrivateKeyJwk,
   ): Promise<ProtocolDefinition>;
 
-  // Implementation dispatches based on argument type
+  // Implementation dispatches based on argument type.
   public static async deriveAndInjectPublicEncryptionKeys(
     protocolDefinition: ProtocolDefinition,
     rootKeyIdOrKeyDeriver: string | EncryptionKeyDeriver,
@@ -116,6 +114,9 @@ export class Protocols {
       // Callback-based path
       const keyDeriver = rootKeyIdOrKeyDeriver;
       const basePath = [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol];
+      clone.$keyAgreement = {
+        publicKeyJwk: await keyDeriver.derivePublicKey(basePath),
+      };
 
       async function injectKeysViaCallback(
         ruleSet: ProtocolRuleSet, parentPath: string[],
@@ -133,10 +134,7 @@ export class Protocols {
             }
 
             const publicKeyJwk = await keyDeriver.derivePublicKey(currentPath);
-            childRuleSet.$encryption = {
-              rootKeyId: keyDeriver.rootKeyId,
-              publicKeyJwk,
-            };
+            childRuleSet.$keyAgreement = { publicKeyJwk };
             await injectKeysViaCallback(childRuleSet, currentPath);
           }
         }
@@ -146,13 +144,13 @@ export class Protocols {
       return clone;
     }
 
-    // Raw-key path (existing logic, unchanged)
+    // Raw-key path
     const rootKeyId = rootKeyIdOrKeyDeriver;
 
-    // a function that recursively creates and adds `$encryption` property to every rule set
+    // a function that recursively creates and adds `$keyAgreement` property to every rule set
     async function addEncryptionProperty(ruleSet: ProtocolRuleSet, parentKey: DerivedPrivateJwk): Promise<void> {
       for (const key in ruleSet) {
-        // if we encounter a nested rule set (a property name that doesn't begin with '$'), recursively inject the `$encryption` property
+        // if we encounter a nested rule set (a property name that doesn't begin with '$'), recursively inject the `$keyAgreement` property
         if (!key.startsWith('$')) {
           const derivedPrivateKey = await HdKey.derivePrivateKey(parentKey, [key]);
           const childRuleSet = ruleSet[key] as ProtocolRuleSet;
@@ -166,7 +164,7 @@ export class Protocols {
 
           const publicKeyJwk = await X25519.getPublicKey({ key: derivedPrivateKey.derivedPrivateKey }) as PublicKeyJwk;
 
-          childRuleSet.$encryption = { rootKeyId, publicKeyJwk };
+          childRuleSet.$keyAgreement = { publicKeyJwk };
           await addEncryptionProperty(childRuleSet, derivedPrivateKey);
         }
       }
@@ -179,8 +177,11 @@ export class Protocols {
       rootKeyId
     };
     const protocolLevelDerivedKey = await HdKey.derivePrivateKey(rootKey, [KeyDerivationScheme.ProtocolPath, protocolDefinition.protocol]);
+    clone.$keyAgreement = {
+      publicKeyJwk: await X25519.getPublicKey({ key: protocolLevelDerivedKey.derivedPrivateKey }) as PublicKeyJwk,
+    };
     await addEncryptionProperty(clone.structure as ProtocolRuleSet, protocolLevelDerivedKey);
 
     return clone;
   }
-}
+}

package/src/utils/records.ts

@@ -1,13 +1,16 @@
 import type { DerivedPrivateJwk } from './hd-key.js';
 import type { Jwk } from '@enbox/crypto';
 import type { KeyDecrypter } from '../types/encryption-types.js';
+import type { KeyEncryption } from './encryption.js';
+import type { PublicKeyJwk } from '../types/jose-types.js';
 import type { Filter, KeyValues, StartsWithFilter } from '../types/query-types.js';
 import type { GenericMessage, GenericSignaturePayload, MessageSort } from '../types/message-types.js';
 import type { RecordsCountMessage, RecordsDeleteMessage, RecordsFilter, RecordsQueryMessage, RecordsReadMessage, RecordsSubscribeMessage, RecordsWriteDescriptor, RecordsWriteMessage, RecordsWriteTags, RecordsWriteTagsFilter } from '../types/records-types.js';
 
+import { Cid } from './cid.js';
+import { DataStream } from './data-stream.js';
 import { DateSort } from '../types/records-types.js';
 import { Encoder } from './encoder.js';
-import { Encryption } from './encryption.js';
 import { FilterUtility } from './filter.js';
 import { Jws } from './jws.js';
 import { Message } from '../core/message.js';
@@ -17,6 +20,7 @@ import { SortDirection } from '../types/query-types.js';
 import { X25519 } from '@enbox/crypto';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { Encryption, ROLE_AUDIENCE_DERIVATION_SCHEME } from './encryption.js';
 import { HdKey, KeyDerivationScheme } from './hd-key.js';
 import { normalizeProtocolUrl, normalizeSchemaUrl } from './url.js';
 
@@ -60,7 +64,7 @@ export class Records {
    * Decrypts the encrypted data in a message reply.
    *
    * Overload 1 (callback-based): Accepts a KeyDecrypter that performs
-   * HKDF derivation + ECDH-ES key agreement + AES Key Unwrap internally.
+   * X25519-HKDF key agreement + AES Key Unwrap internally.
    */
   public static async decrypt(
     recordsWrite: RecordsWriteMessage,
@@ -78,7 +82,7 @@ export class Records {
     cipherStream: ReadableStream<Uint8Array>,
   ): Promise<ReadableStream<Uint8Array>>;
 
-  // Implementation dispatches based on argument type
+  // Implementation dispatches based on argument type.
   public static async decrypt(
     recordsWrite: RecordsWriteMessage,
     keyOrDecrypter: DerivedPrivateJwk | KeyDecrypter,
@@ -92,81 +96,114 @@ export class Records {
       );
     }
 
-    const isCallback = 'decrypt' in keyOrDecrypter;
+    const ciphertext = await DataStream.toBytes(cipherStream);
+    const actualDataCid = await Cid.computeDagPbCidFromBytes(ciphertext);
+    Records.validateEncryptedDataIntegrity(recordsWrite, actualDataCid, ciphertext.byteLength);
 
-    // Parse the JWE protected header to determine the content encryption algorithm
-    const protectedHeader = Encryption.parseProtectedHeader(encryption.protected);
-    const enc = protectedHeader.enc;
+    const { fullDerivationPath, leafPrivateKey, matchingKeyEncryption } =
+      await Records.findMatchingKeyEncryption(recordsWrite, keyOrDecrypter);
 
-    // Find matching recipient entry by rootKeyId and derivationScheme
-    const matchingRecipient = encryption.recipients.find(r =>
-      r.header.kid === keyOrDecrypter.rootKeyId &&
-      r.header.derivationScheme === keyOrDecrypter.derivationScheme
-    );
-    if (matchingRecipient === undefined) {
+    if (matchingKeyEncryption === undefined) {
       throw new DwnError(
         DwnErrorCode.RecordsDecryptNoMatchingKeyEncryptedFound,
-        `Unable to find a JWE recipient matching key \
-        with ID '${keyOrDecrypter.rootKeyId}' and '${keyOrDecrypter.derivationScheme}' derivation scheme.`
+        `Unable to find a matching key encryption entry for '${keyOrDecrypter.rootKeyId}' and '${keyOrDecrypter.derivationScheme}'.`
       );
     }
 
-    // Construct the full derivation path
-    const fullDerivationPath = Records.constructKeyDerivationPath(
-      matchingRecipient.header.derivationScheme, recordsWrite,
-    );
-
     let cek: Uint8Array;
 
-    if (isCallback) {
-      // Callback-based: delegate HKDF + ECDH-ES + AES Key Unwrap to the KeyDecrypter
-      const encryptedKeyBytes = Encoder.base64UrlToBytes(matchingRecipient.encrypted_key);
-
+    if ('decrypt' in keyOrDecrypter) {
       cek = await keyOrDecrypter.decrypt(fullDerivationPath, {
-        encryptedKey       : encryptedKeyBytes,
-        ephemeralPublicKey : matchingRecipient.header.epk,
+        encryptedKey       : Encoder.base64UrlToBytes(matchingKeyEncryption.encryptedKey),
+        ephemeralPublicKey : matchingKeyEncryption.ephemeralPublicKey,
+        keyEncryption      : matchingKeyEncryption,
       });
     } else {
-      // Raw-key path: derive the leaf private key, then ECDH-ES + AES Key Unwrap
-      const leafPrivateKeyBytes = await Records.derivePrivateKey(keyOrDecrypter, fullDerivationPath);
-      const leafPrivateKeyJwk = await X25519.bytesToPrivateKey({ privateKeyBytes: leafPrivateKeyBytes });
-      const wrappedKeyBytes = Encoder.base64UrlToBytes(matchingRecipient.encrypted_key);
-
-      cek = await Encryption.ecdhEsUnwrapKey(
-        leafPrivateKeyJwk,
-        matchingRecipient.header.epk as Jwk,
-        wrappedKeyBytes,
-      );
+      cek = await Encryption.unwrapKey(leafPrivateKey!, matchingKeyEncryption);
     }
 
-    // AEAD decrypt data using the CEK
-    const iv = Encoder.base64UrlToBytes(encryption.iv);
-    const tag = Encoder.base64UrlToBytes(encryption.tag);
-    const plaintextStream = await Encryption.aeadDecryptStream(enc, cek, iv, cipherStream, tag);
+    const iv = Encoder.base64UrlToBytes(encryption.initializationVector);
+    const plaintext = await Encryption.decrypt(encryption.algorithm, cek, iv, ciphertext);
+    const plaintextStream = DataStream.fromBytes(plaintext);
 
     return plaintextStream;
   }
 
+  private static async findMatchingKeyEncryption(
+    recordsWrite: RecordsWriteMessage,
+    keyOrDecrypter: DerivedPrivateJwk | KeyDecrypter,
+  ): Promise<{ fullDerivationPath: string[]; leafPrivateKey?: Jwk; matchingKeyEncryption?: KeyEncryption }> {
+    const { encryption } = recordsWrite;
+    const fullDerivationPath = Records.constructKeyDerivationPath(keyOrDecrypter.derivationScheme, recordsWrite);
+
+    if ('decrypt' in keyOrDecrypter) {
+      const publicKey = await keyOrDecrypter.derivePublicKey(fullDerivationPath);
+      const keyId = await Encryption.getKeyId(publicKey);
+      return {
+        fullDerivationPath,
+        matchingKeyEncryption: encryption!.keyEncryption.find((entry): boolean =>
+          entry.derivationScheme === keyOrDecrypter.derivationScheme && entry.keyId === keyId
+        ),
+      };
+    }
+
+    const leafPrivateKeyBytes = await Records.derivePrivateKey(keyOrDecrypter, fullDerivationPath);
+    const leafPrivateKey = await X25519.bytesToPrivateKey({ privateKeyBytes: leafPrivateKeyBytes });
+
+    const publicKey = await X25519.getPublicKey({ key: leafPrivateKey });
+    const keyId = keyOrDecrypter.keyId ?? await Encryption.getKeyId(publicKey as PublicKeyJwk);
+
+    return {
+      fullDerivationPath,
+      leafPrivateKey,
+      matchingKeyEncryption: encryption!.keyEncryption.find((entry): boolean =>
+        entry.derivationScheme === keyOrDecrypter.derivationScheme && entry.keyId === keyId
+      ),
+    };
+  }
+
+  private static validateEncryptedDataIntegrity(
+    recordsWrite: RecordsWriteMessage,
+    actualDataCid: string,
+    actualDataSize: number,
+  ): void {
+    const { dataCid, dataSize } = recordsWrite.descriptor;
+    if (dataCid !== actualDataCid) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteDataCidMismatch,
+        `actual data CID ${actualDataCid} does not match dataCid in descriptor: ${dataCid}`
+      );
+    }
+
+    if (dataSize !== actualDataSize) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteDataSizeMismatch,
+        `actual data size ${actualDataSize} bytes does not match dataSize in descriptor: ${dataSize}`
+      );
+    }
+  }
+
   /**
    * Constructs full key derivation path using the specified scheme.
    */
   public static constructKeyDerivationPath(
-    keyDerivationScheme: KeyDerivationScheme,
+    keyDerivationScheme: KeyDerivationScheme | typeof ROLE_AUDIENCE_DERIVATION_SCHEME,
     recordsWriteMessage: RecordsWriteMessage
   ): string[] {
 
     const descriptor = recordsWriteMessage.descriptor;
-    const contextId = recordsWriteMessage.contextId;
-
-    let fullDerivationPath;
     if (keyDerivationScheme === KeyDerivationScheme.ProtocolPath) {
-      fullDerivationPath = Records.constructKeyDerivationPathUsingProtocolPathScheme(descriptor);
-    } else {
-      // `protocolContext` scheme
-      fullDerivationPath = Records.constructKeyDerivationPathUsingProtocolContextScheme(contextId);
+      return Records.constructKeyDerivationPathUsingProtocolPathScheme(descriptor);
     }
 
-    return fullDerivationPath;
+    if (keyDerivationScheme === ROLE_AUDIENCE_DERIVATION_SCHEME) {
+      return [ROLE_AUDIENCE_DERIVATION_SCHEME];
+    }
+
+    throw new DwnError(
+      DwnErrorCode.RecordsDecryptUnsupportedKeyDerivationScheme,
+      `Unsupported key derivation scheme '${keyDerivationScheme as string}'.`
+    );
   }
 
   /**
@@ -188,28 +225,6 @@ export class Records {
     return fullDerivationPath;
   }
 
-  /**
-   * Constructs the full key derivation path using `protocolContext` scheme.
-   *
-   * NOTE on protocol composition: When a context tree spans two protocols via `$ref` composition,
-   * the root `contextId` segment (the `$ref` parent record's ID) is shared across both protocols.
-   * This means ProtocolContext-encrypted records from the composing protocol and the referenced
-   * protocol derive the same context key. This is by design — it enables multi-party access within
-   * a shared context (e.g., thread participants can decrypt messages from both the threads protocol
-   * and composing protocols that attach to those threads).
-   */
-  public static constructKeyDerivationPathUsingProtocolContextScheme(contextId: string): string[] {
-    // TODO: Extend key derivation support to include the full contextId (https://github.com/enboxorg/enbox/issues/99)
-    const firstContextSegment = contextId.split('/')[0];
-
-    const fullDerivationPath = [
-      KeyDerivationScheme.ProtocolContext,
-      firstContextSegment
-    ];
-
-    return fullDerivationPath;
-  }
-
   /**
    * Derives a descendant private key given an ancestor private key and the full absolute derivation path.
    * Uses X25519 keys for encryption key derivation.

package/src/utils/replication.ts

@@ -1,6 +1,7 @@
 import type { GenericMessage } from '../types/message-types.js';
 import type { KeyValues } from '../types/query-types.js';
 
+import { EncryptionProtocol } from '../protocols/encryption.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
@@ -24,6 +25,25 @@ export class Replication {
     return `perm:${protocolUri}`;
   }
 
+  public static encryptionDomain(protocolUri: string): string {
+    return `enc:${protocolUri}`;
+  }
+
+  public static taggedCoreProtocolDomains(protocolUri: string, protocolsInScope: ReadonlySet<string> = new Set()): string[] {
+    if (Replication.isCoreProtocolUri(protocolUri)) {
+      return [];
+    }
+
+    const domains: string[] = [];
+    if (!protocolsInScope.has(PermissionsProtocol.uri)) {
+      domains.push(Replication.permissionDomain(protocolUri));
+    }
+    if (!protocolsInScope.has(EncryptionProtocol.uri)) {
+      domains.push(Replication.encryptionDomain(protocolUri));
+    }
+    return domains;
+  }
+
   public static async deriveStreamId(tenant: string): Promise<string> {
     const bytes = new TextEncoder().encode(tenant);
     const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
@@ -39,11 +59,13 @@ export class Replication {
     if (typeof protocol === 'string') {
       scopes.push(Replication.protocolDomain(protocol));
 
-      if (protocol === PermissionsProtocol.uri) {
-        const indexedTaggedProtocol = indexes['tag.protocol'];
-        const taggedProtocol = indexedTaggedProtocol ?? descriptor.tags?.protocol;
-        if (typeof taggedProtocol === 'string') {
+      const indexedTaggedProtocol = indexes['tag.protocol'];
+      const taggedProtocol = indexedTaggedProtocol ?? descriptor.tags?.protocol;
+      if (typeof taggedProtocol === 'string') {
+        if (protocol === PermissionsProtocol.uri) {
           scopes.push(Replication.permissionDomain(taggedProtocol));
+        } else if (protocol === EncryptionProtocol.uri) {
+          scopes.push(Replication.encryptionDomain(taggedProtocol));
         }
       }
     }
@@ -78,6 +100,10 @@ export class Replication {
     );
   }
 
+  private static isCoreProtocolUri(protocolUri: string): boolean {
+    return protocolUri === PermissionsProtocol.uri || protocolUri === EncryptionProtocol.uri;
+  }
+
   public static async hashMessageCid(messageCid: string): Promise<Uint8Array> {
     const bytes = new TextEncoder().encode(messageCid);
     const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);

package/dist/esm/tests/vectors/protocol-definitions/chat.json

@@ -1,70 +0,0 @@
-{
-    "protocol": "http://chat-protocol.xyz",
-    "published": true,
-    "types": {
-        "thread": {
-            "schema": "thread",
-            "dataFormats": [
-                "application/json"
-            ]
-        },
-        "message": {
-            "schema": "message",
-            "dataFormats": [
-                "application/json"
-            ]
-        }
-    },
-    "structure": {
-        "thread": {
-            "$actions": [
-                {
-                    "who": "anyone",
-                    "can": [
-                        "create",
-                        "update"
-                    ]
-                },
-                {
-                    "who": "author",
-                    "of": "thread",
-                    "can": [
-                        "read"
-                    ]
-                },
-                {
-                    "who": "recipient",
-                    "of": "thread",
-                    "can": [
-                        "read"
-                    ]
-                }
-            ],
-            "message": {
-                "$actions": [
-                    {
-                        "who": "anyone",
-                        "can": [
-                            "create",
-                            "update"
-                        ]
-                    },
-                    {
-                        "who": "author",
-                        "of": "thread/message",
-                        "can": [
-                            "read"
-                        ]
-                    },
-                    {
-                        "who": "recipient",
-                        "of": "thread/message",
-                        "can": [
-                            "read"
-                        ]
-                    }
-                ]
-            }
-        }
-    }
-}