Quality-of-life improvements for devs using the SDK for encryption

1. When using root private key, derivation path of `[]` is no longer required to be specified
2. Encryption input used to create an encrypted message now only accepts the root public key

Author: thehenrytsai

README.md

@@ -3,7 +3,7 @@
 # Decentralized Web Node (DWN) SDK
 
 Code Coverage
-![Statements](https://img.shields.io/badge/statements-94.07%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-93.58%25-brightgreen.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-91.8%25-brightgreen.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-94.07%25-brightgreen.svg?style=flat)
+![Statements](https://img.shields.io/badge/statements-94.07%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-93.6%25-brightgreen.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-91.8%25-brightgreen.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-94.07%25-brightgreen.svg?style=flat)
 
 ## Introduction
 

src/index.ts

@@ -16,7 +16,7 @@ export { DataStore } from './store/data-store.js';
 export { DataStoreLevel } from './store/data-store-level.js';
 export { DateSort } from './interfaces/records/messages/records-query.js';
 export { DataStream } from './utils/data-stream.js';
-export { DerivedPrivateJwk, DerivedPublicJwk, HdKey, KeyDerivationScheme } from './utils/hd-key.js';
+export { DerivedPrivateJwk, HdKey, KeyDerivationScheme } from './utils/hd-key.js';
 export { DidKeyResolver } from './did/did-key-resolver.js';
 export { DidIonResolver } from './did/did-ion-resolver.js';
 export { DidResolver, DidMethodResolver } from './did/did-resolver.js';

src/interfaces/records/messages/records-write.ts

@@ -1,6 +1,7 @@
 import type { BaseMessage } from '../../../core/types.js';
-import type { DerivedPublicJwk } from '../../../utils/hd-key.js';
+import type { KeyDerivationScheme } from '../../../index.js';
 import type { MessageStore } from '../../../store/message-store.js';
+import type { PublicJwk } from '../../../jose/types.js';
 import type {
   EncryptedKey,
   EncryptionProperty,
@@ -81,9 +82,14 @@ export type EncryptionInput = {
  */
 export type KeyEncryptionInput = {
   /**
-   * Public key used to encrypt the symmetric key.
+   * Key derivation scheme to derive the descendant public key to encrypt the symmetric key.
    */
-  publicKey: DerivedPublicJwk;
+  derivationScheme: KeyDerivationScheme;
+
+  /**
+   * Root public key used derive the descendant public key to encrypt the symmetric key.
+   */
+  publicKey: PublicJwk;
 
   /**
    * Algorithm used for encrypting the symmetric key. Uses {EncryptionAlgorithm.EciesSecp256k1} if not given.
@@ -468,7 +474,7 @@ export class RecordsWrite extends Message<RecordsWriteMessage> {
     const keyEncryption: EncryptedKey[] = [];
     for (const keyEncryptionInput of encryptionInput.keyEncryptionInputs) {
 
-      const fullDerivationPath = Records.constructKeyDerivationPath(keyEncryptionInput.publicKey.derivationScheme, recordId, contextId, descriptor);
+      const fullDerivationPath = Records.constructKeyDerivationPath(keyEncryptionInput.derivationScheme, recordId, contextId, descriptor);
 
       // NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
       // so we will assume that's the algorithm without additional switch/if statements
@@ -481,7 +487,7 @@ export class RecordsWrite extends Message<RecordsWriteMessage> {
       const messageAuthenticationCode = Encoder.bytesToBase64Url(keyEncryptionOutput.messageAuthenticationCode);
       const encryptedKeyData: EncryptedKey = {
         algorithm            : keyEncryptionInput.algorithm ?? EncryptionAlgorithm.EciesSecp256k1,
-        derivationScheme     : keyEncryptionInput.publicKey.derivationScheme,
+        derivationScheme     : keyEncryptionInput.derivationScheme,
         encryptedKey,
         ephemeralPublicKey,
         initializationVector : keyEncryptionInitializationVector,

src/utils/hd-key.ts

@@ -1,20 +1,14 @@
-import type { PrivateJwk, PublicJwk } from '../jose/types.js';
+import type { PrivateJwk } from '../jose/types.js';
 
 import { Secp256k1 } from './secp256k1.js';
 
 export enum KeyDerivationScheme {
   Protocols = 'protocols'
 }
 
-export type DerivedPublicJwk = {
-  derivationScheme: KeyDerivationScheme;
-  derivationPath: string[];
-  derivedPublicKey: PublicJwk,
-};
-
 export type DerivedPrivateJwk = {
   derivationScheme: KeyDerivationScheme;
-  derivationPath: string[];
+  derivationPath?: string[];
   derivedPrivateKey: PrivateJwk,
 };
 
@@ -28,10 +22,11 @@ export class HdKey {
    */
   public static async derivePrivateKey(ancestorKey: DerivedPrivateJwk, subDerivationPath: string[]): Promise<DerivedPrivateJwk> {
     const ancestorPrivateKey = Secp256k1.privateJwkToBytes(ancestorKey.derivedPrivateKey);
+    const ancestorPrivateKeyDerivationPath = ancestorKey.derivationPath ?? [];
     const derivedPrivateKeyBytes = await Secp256k1.derivePrivateKey(ancestorPrivateKey, subDerivationPath);
     const derivedPrivateJwk = await Secp256k1.privateKeyToJwk(derivedPrivateKeyBytes);
     const derivedDescendantPrivateKey: DerivedPrivateJwk = {
-      derivationPath    : [...ancestorKey.derivationPath, ...subDerivationPath],
+      derivationPath    : [...ancestorPrivateKeyDerivationPath, ...subDerivationPath],
       derivationScheme  : ancestorKey.derivationScheme,
       derivedPrivateKey : derivedPrivateJwk
     };

src/utils/records.ts

@@ -1,5 +1,6 @@
+import type { DerivedPrivateJwk } from './hd-key.js';
+import type { PublicJwk } from '../jose/types.js';
 import type { Readable } from 'readable-stream';
-import type { DerivedPrivateJwk, DerivedPublicJwk } from './hd-key.js';
 import type { RecordsWriteDescriptor, UnsignedRecordsWriteMessage } from '../interfaces/records/types.js';
 
 import { Encoder } from './encoder.js';
@@ -14,6 +15,7 @@ import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 export class Records {
   /**
    * Decrypts the encrypted data in a message reply using the given ancestor private key.
+   * @param ancestorPrivateKey Any ancestor private key in the key derivation path.
    */
   public static async decrypt(
     recordsWrite: UnsignedRecordsWriteMessage,
@@ -106,19 +108,16 @@ export class Records {
    * NOTE: right now only `ECIES-ES256K` algorithm is supported for asymmetric encryption,
    *       so we will assume that's the algorithm without additional switch/if statements
    */
-  public static async deriveLeafPublicKey(ancestorPublicKey: DerivedPublicJwk, fullDescendantDerivationPath: string[]): Promise<Uint8Array> {
-    if (ancestorPublicKey.derivedPublicKey.crv !== 'secp256k1') {
+  public static async deriveLeafPublicKey(rootPublicKey: PublicJwk, fullDescendantDerivationPath: string[]): Promise<Uint8Array> {
+    if (rootPublicKey.crv !== 'secp256k1') {
       throw new DwnError(
         DwnErrorCode.RecordsDeriveLeafPublicKeyUnSupportedCurve,
-        `Curve ${ancestorPublicKey.derivedPublicKey.crv} is not supported.`
+        `Curve ${rootPublicKey.crv} is not supported.`
       );
     }
 
-    Records.validateAncestorKeyAndDescentKeyDerivationPathsMatch(ancestorPublicKey.derivationPath, fullDescendantDerivationPath);
-
-    const subDerivationPath = fullDescendantDerivationPath.slice(ancestorPublicKey.derivationPath.length);
-    const ancestorPublicKeyBytes = Secp256k1.publicJwkToBytes(ancestorPublicKey.derivedPublicKey);
-    const leafPublicKey = await Secp256k1.derivePublicKey(ancestorPublicKeyBytes, subDerivationPath);
+    const ancestorPublicKeyBytes = Secp256k1.publicJwkToBytes(rootPublicKey);
+    const leafPublicKey = await Secp256k1.derivePublicKey(ancestorPublicKeyBytes, fullDescendantDerivationPath);
 
     return leafPublicKey;
   }
@@ -136,9 +135,11 @@ export class Records {
       );
     }
 
-    Records.validateAncestorKeyAndDescentKeyDerivationPathsMatch(ancestorPrivateKey.derivationPath, fullDescendantDerivationPath);
+    const ancestorPrivateKeyDerivationPath = ancestorPrivateKey.derivationPath ?? [];
+
+    Records.validateAncestorKeyAndDescentKeyDerivationPathsMatch(ancestorPrivateKeyDerivationPath, fullDescendantDerivationPath);
 
-    const subDerivationPath = fullDescendantDerivationPath.slice(ancestorPrivateKey.derivationPath.length);
+    const subDerivationPath = fullDescendantDerivationPath.slice(ancestorPrivateKeyDerivationPath.length);
     const ancestorPrivateKeyBytes = Secp256k1.privateJwkToBytes(ancestorPrivateKey.derivedPrivateKey);
     const leafPrivateKey = await Secp256k1.derivePrivateKey(ancestorPrivateKeyBytes, subDerivationPath);
 

tests/interfaces/records/handlers/records-query.spec.ts

@@ -1,7 +1,6 @@
 import type { RecordsQueryReplyEntry } from '../../../../src/interfaces/records/types.js';
 import type { DerivedPrivateJwk, EncryptionInput, ProtocolDefinition, RecordsWriteMessage } from '../../../../src/index.js';
 
-
 import chaiAsPromised from 'chai-as-promised';
 import emailProtocolDefinition from '../../../vectors/protocol-definitions/email.json' assert { type: 'json' };
 import sinon from 'sinon';
@@ -618,7 +617,7 @@ describe('RecordsQueryHandler.handle()', () => {
     });
 
     describe('encryption scenarios', () => {
-      it('should only be able to decrypt record with a correct derived private key', async () => {
+      it('should only be able to decrypt record with a correct derived private key - protocols derivation scheme', async () => {
         // scenario, Bob writes into Alice's DWN an encrypted "email", alice is able to decrypt it
 
         // creating Alice and Bob persona and setting up a stub DID resolver
@@ -651,11 +650,8 @@ describe('RecordsQueryHandler.handle()', () => {
           initializationVector : dataEncryptionInitializationVector,
           key                  : dataEncryptionKey,
           keyEncryptionInputs  : [{
-            publicKey: {
-              derivationScheme : KeyDerivationScheme.Protocols,
-              derivationPath   : [],
-              derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
-            }
+            derivationScheme : KeyDerivationScheme.Protocols,
+            publicKey        : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
           }]
         };
 
@@ -683,25 +679,39 @@ describe('RecordsQueryHandler.handle()', () => {
 
         const unsignedRecordsWrite = queryReply.entries![0] as RecordsQueryReplyEntry;
 
-        // test able to decrypt the message using a derived key
+
+        // test able to decrypt the message using the root key
         const rootPrivateKey: DerivedPrivateJwk = {
           derivationScheme  : KeyDerivationScheme.Protocols,
-          derivationPath    : [],
           derivedPrivateKey : alice.keyPair.privateJwk
         };
-        const relativeDescendantDerivationPath = Records.constructKeyDerivationPath(
-          KeyDerivationScheme.Protocols,
-          message.recordId,
-          message.contextId,
-          message.descriptor
-        );
-        const descendantPrivateKey: DerivedPrivateJwk = await HdKey.derivePrivateKey(rootPrivateKey, relativeDescendantDerivationPath);
-
         const cipherStream = DataStream.fromBytes(Encoder.base64UrlToBytes(unsignedRecordsWrite.encodedData!));
 
-        const plaintextDataStream = await Records.decrypt(unsignedRecordsWrite, descendantPrivateKey, cipherStream);
+        const plaintextDataStream = await Records.decrypt(unsignedRecordsWrite, rootPrivateKey, cipherStream);
         const plaintextBytes = await DataStream.toBytes(plaintextDataStream);
         expect(Comparer.byteArraysEqual(plaintextBytes, bobMessageBytes)).to.be.true;
+
+
+        // test able to decrypt the message using a derived key
+        const derivationPath = [KeyDerivationScheme.Protocols]; // the first path segment of `protocol` derivation scheme
+        const derivedPrivateKey: DerivedPrivateJwk = await HdKey.derivePrivateKey(rootPrivateKey, derivationPath);
+
+        const cipherStream2 = DataStream.fromBytes(Encoder.base64UrlToBytes(unsignedRecordsWrite.encodedData!));
+
+        const plaintextDataStream2 = await Records.decrypt(unsignedRecordsWrite, derivedPrivateKey, cipherStream2);
+        const plaintextBytes2 = await DataStream.toBytes(plaintextDataStream2);
+        expect(Comparer.byteArraysEqual(plaintextBytes2, bobMessageBytes)).to.be.true;
+
+
+        // test able to decrypt the message using a key derived from a derived key
+        const protocolsUriDerivationPathSegment = [message.descriptor.protocol!]; // the 2nd path segment of `protocol` derivation scheme
+        const derivedPrivateKey2: DerivedPrivateJwk = await HdKey.derivePrivateKey(derivedPrivateKey, protocolsUriDerivationPathSegment);
+
+        const cipherStream3 = DataStream.fromBytes(Encoder.base64UrlToBytes(unsignedRecordsWrite.encodedData!));
+
+        const plaintextDataStream3 = await Records.decrypt(unsignedRecordsWrite, derivedPrivateKey2, cipherStream3);
+        const plaintextBytes3 = await DataStream.toBytes(plaintextDataStream3);
+        expect(Comparer.byteArraysEqual(plaintextBytes3, bobMessageBytes)).to.be.true;
       });
     });
   });

tests/interfaces/records/handlers/records-read.spec.ts

@@ -400,11 +400,8 @@ describe('RecordsReadHandler.handle()', () => {
           initializationVector : dataEncryptionInitializationVector,
           key                  : dataEncryptionKey,
           keyEncryptionInputs  : [{
-            publicKey: {
-              derivationScheme : KeyDerivationScheme.Protocols,
-              derivationPath   : [],
-              derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
-            }
+            derivationScheme : KeyDerivationScheme.Protocols,
+            publicKey        : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
           }]
         };
 
@@ -432,7 +429,6 @@ describe('RecordsReadHandler.handle()', () => {
         // test able to decrypt the message using a derived key
         const rootPrivateKey: DerivedPrivateJwk = {
           derivationScheme  : KeyDerivationScheme.Protocols,
-          derivationPath    : [],
           derivedPrivateKey : alice.keyPair.privateJwk
         };
         const relativeDescendantDerivationPath = Records.constructKeyDerivationPath(
@@ -460,7 +456,6 @@ describe('RecordsReadHandler.handle()', () => {
         // test unable to decrypt the message if there no derivation scheme(s) used by the message matches the scheme used by the given private key
         const privateKeyWithMismatchingDerivationScheme: DerivedPrivateJwk = {
           derivationScheme  : 'scheme-that-is-not-protocol-context' as any,
-          derivationPath    : [],
           derivedPrivateKey : alice.keyPair.privateJwk
         };
         await expect(Records.decrypt(unsignedRecordsWrite, privateKeyWithMismatchingDerivationScheme, cipherStream)).to.be.rejectedWith(

tests/interfaces/records/handlers/records-write.spec.ts

@@ -1437,12 +1437,9 @@ describe('RecordsWriteHandler.handle()', () => {
           initializationVector : dataEncryptionInitializationVector,
           key                  : dataEncryptionKey,
           keyEncryptionInputs  : [{
-            algorithm : EncryptionAlgorithm.EciesSecp256k1,
-            publicKey : {
-              derivationScheme : KeyDerivationScheme.Protocols,
-              derivationPath   : [],
-              derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
-            }
+            algorithm        : EncryptionAlgorithm.EciesSecp256k1,
+            derivationScheme : KeyDerivationScheme.Protocols,
+            publicKey        : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
           }]
         };
         const { message, dataStream } = await TestDataGenerator.generateRecordsWrite({

tests/interfaces/records/messages/records-write.spec.ts

@@ -186,11 +186,8 @@ describe('RecordsWrite', () => {
         initializationVector : dataEncryptionInitializationVector,
         key                  : dataEncryptionKey,
         keyEncryptionInputs  : [{
-          publicKey: {
-            derivationScheme : KeyDerivationScheme.Protocols,
-            derivationPath   : [],
-            derivedPublicKey : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
-          }
+          derivationScheme : KeyDerivationScheme.Protocols,
+          publicKey        : alice.keyPair.publicJwk // reusing signing key for encryption purely as a convenience
         }]
       };
 

tests/utils/records.spec.ts

@@ -1,4 +1,4 @@
-import type { DerivedPrivateJwk, DerivedPublicJwk } from '../../src/index.js';
+import type { DerivedPrivateJwk } from '../../src/index.js';
 
 import { DwnErrorCode } from '../../src/core/dwn-error.js';
 import { ed25519 } from '../../src/jose/algorithms/signing/ed25519.js';
@@ -8,19 +8,14 @@ import { KeyDerivationScheme, Records } from '../../src/index.js';
 describe('Records', () => {
   describe('deriveLeafPublicKey()', () => {
     it('should throw if given public key is not supported', async () => {
-      const derivedKey: DerivedPublicJwk = {
-        derivationPath   : [],
-        derivationScheme : KeyDerivationScheme.Protocols,
-        derivedPublicKey : (await ed25519.generateKeyPair()).publicJwk
-      };
-      await expect(Records.deriveLeafPublicKey(derivedKey, ['a'])).to.be.rejectedWith(DwnErrorCode.RecordsDeriveLeafPublicKeyUnSupportedCurve);
+      const rootPublicKey = (await ed25519.generateKeyPair()).publicJwk;
+      await expect(Records.deriveLeafPublicKey(rootPublicKey, ['a'])).to.be.rejectedWith(DwnErrorCode.RecordsDeriveLeafPublicKeyUnSupportedCurve);
     });
   });
 
   describe('deriveLeafPrivateKey()', () => {
     it('should throw if given private key is not supported', async () => {
       const derivedKey: DerivedPrivateJwk = {
-        derivationPath    : [],
         derivationScheme  : KeyDerivationScheme.Protocols,
         derivedPrivateKey : (await ed25519.generateKeyPair()).privateJwk
       };