@enbox/dwn-sdk-js 0.4.5 → 0.4.7

package/src/utils/encryption.ts

@@ -1,7 +1,6 @@
 import type { Jwk } from '@enbox/crypto';
 import type { PublicKeyJwk } from '../types/jose-types.js';
 
-import { concatBytes } from '@noble/ciphers/utils';
 import { AesCtr, AesKw, computeJwkThumbprint, Hkdf, X25519 } from '@enbox/crypto';
 
 import { Encoder } from './encoder.js';
@@ -17,69 +16,128 @@ export enum KeyAgreementAlgorithm {
 }
 
 export const ROLE_AUDIENCE_DERIVATION_SCHEME = 'roleAudience';
+export const SEAL_DERIVATION_SCHEME = 'seal';
 
 const AES_256_KEY_LENGTH_BYTES = 32;
 const AES_CTR_COUNTER_LENGTH_BYTES = 16;
 const AES_CTR_COUNTER_LENGTH_BITS = 128;
 const KEK_INFO_PREFIX = KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
 
-export type ProtocolPathKeyEncryption = {
+function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+  const byteLength = arrays.reduce((total, array): number => total + array.byteLength, 0);
+  const result = new Uint8Array(byteLength);
+  let offset = 0;
+
+  for (const array of arrays) {
+    result.set(array, offset);
+    offset += array.byteLength;
+  }
+
+  return result;
+}
+
+export type X25519KeyEncryptionBase = {
   algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
   keyId: string;
-  derivationScheme: KeyDerivationScheme.ProtocolPath;
   ephemeralPublicKey: PublicKeyJwk;
   encryptedKey: string;
 };
 
-export type RoleAudienceKeyEncryption = {
-  algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
-  keyId: string;
+export type ProtocolPathKeyEncryption = X25519KeyEncryptionBase & {
+  derivationScheme: KeyDerivationScheme.ProtocolPath;
+};
+
+export type SourceRoleAudienceKeyEncryption = X25519KeyEncryptionBase & {
   derivationScheme: typeof ROLE_AUDIENCE_DERIVATION_SCHEME;
   protocol: string;
-  role: string;
-  epoch: number;
-  ephemeralPublicKey: PublicKeyJwk;
-  encryptedKey: string;
+  rolePath: string;
 };
 
-export type KeyEncryption = ProtocolPathKeyEncryption | RoleAudienceKeyEncryption;
+export type X25519KeyEncryption = ProtocolPathKeyEncryption | SourceRoleAudienceKeyEncryption;
+
+export type SealKeyWrap = X25519KeyEncryptionBase & {
+  derivationScheme: typeof SEAL_DERIVATION_SCHEME;
+};
 
 export type DwnEncryption = {
   algorithm: ContentEncryptionAlgorithm.A256CTR;
   initializationVector: string;
-  keyEncryption: KeyEncryption[];
+  keyEncryption: X25519KeyEncryption[];
 };
 
-export type ProtocolPathKeyEncryptionInput = {
+export type X25519KeyEncryptionInputBase = {
+  algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
   keyId: string;
   publicKey: PublicKeyJwk;
+};
+
+export type ProtocolPathKeyEncryptionInput = X25519KeyEncryptionInputBase & {
   derivationScheme: KeyDerivationScheme.ProtocolPath;
 };
 
-export type RoleAudienceKeyEncryptionInput = {
-  keyId: string;
-  publicKey: PublicKeyJwk;
+export type SourceRoleAudienceKeyEncryptionInput = X25519KeyEncryptionInputBase & {
   derivationScheme: typeof ROLE_AUDIENCE_DERIVATION_SCHEME;
   protocol: string;
-  role: string;
-  epoch: number;
+  rolePath: string;
 };
 
-export type KeyEncryptionInput = ProtocolPathKeyEncryptionInput | RoleAudienceKeyEncryptionInput;
+export type X25519KeyEncryptionInput = ProtocolPathKeyEncryptionInput | SourceRoleAudienceKeyEncryptionInput;
+
+export type SealKeyWrapInput = X25519KeyEncryptionInputBase & {
+  derivationScheme: typeof SEAL_DERIVATION_SCHEME;
+  protocol: string;
+  rolePath: string;
+  contextId: string;
+  audienceKeyId: string;
+};
 
 export type EncryptionInput = {
   algorithm?: ContentEncryptionAlgorithm;
   key: Uint8Array;
   initializationVector: Uint8Array;
-  keyEncryptionInputs: KeyEncryptionInput[];
+  keyEncryptionInputs: X25519KeyEncryptionInput[];
 };
 
 export type KeyUnwrapPayload = {
   encryptedKey: Uint8Array;
   ephemeralPublicKey: PublicKeyJwk;
-  keyEncryption: KeyEncryption;
+  keyEncryption: X25519KeyEncryption;
+};
+
+export type X25519KeyWrapInput = {
+  cek: Uint8Array;
+  keyInput: X25519KeyEncryptionInput;
+  ephemeralPrivateKey?: Jwk;
 };
 
+export type SealWrapInput = {
+  privateKeyBytes: Uint8Array;
+  keyInput: SealKeyWrapInput;
+  ephemeralPrivateKey?: Jwk;
+};
+
+export type SealUnwrapInput = {
+  seal: SealKeyWrap;
+  recipientPrivateKey: Jwk;
+  protocol: string;
+  rolePath: string;
+  contextId: string;
+  audienceKeyId: string;
+};
+
+type SealKeyUnwrapInfo = SealKeyWrap & {
+  protocol: string;
+  rolePath: string;
+  contextId: string;
+  audienceKeyId: string;
+};
+
+type X25519KekDerivationInput =
+  | X25519KeyEncryptionInput
+  | X25519KeyEncryption
+  | SealKeyWrapInput
+  | SealKeyUnwrapInfo;
+
 export class Encryption {
   public static async encrypt(
     algorithm: ContentEncryptionAlgorithm,
@@ -133,22 +191,54 @@ export class Encryption {
     return Encryption.toStream(plaintext);
   }
 
-  public static async wrapKey(
-    recipientPublicKey: PublicKeyJwk,
-    cek: Uint8Array,
-    keyInput: KeyEncryptionInput,
-    ephemeralPrivateKey?: Jwk,
-  ): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
-    Encryption.validateContentEncryptionKey(cek);
+  public static async wrapKey(input: X25519KeyWrapInput): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
+    if (Encryption.isX25519KeyAgreementAlgorithm(input.keyInput.algorithm)) {
+      return Encryption.wrapX25519Key(input);
+    }
+
+    throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(input.keyInput.algorithm));
+  }
+
+  public static async wrapSeal(input: SealWrapInput): Promise<SealKeyWrap> {
+    if (!Encryption.isX25519KeyAgreementAlgorithm(input.keyInput.algorithm)) {
+      throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(input.keyInput.algorithm));
+    }
+
+    Encryption.validateContentEncryptionKey(input.privateKeyBytes);
+
+    const privateKey = input.ephemeralPrivateKey ?? await X25519.generateKey();
+    const publicKey = await X25519.getPublicKey({ key: privateKey }) as PublicKeyJwk;
+    const sharedSecret = await X25519.sharedSecret({
+      privateKeyA : privateKey,
+      publicKeyB  : input.keyInput.publicKey as Jwk,
+    });
+    const kek = await Encryption.deriveKek(sharedSecret, input.keyInput);
+    const unwrappedKey = await AesKw.bytesToPrivateKey({ privateKeyBytes: input.privateKeyBytes });
+    const encryptedKey = await AesKw.wrapKey({
+      encryptionKey: Encryption.toA256KwJwk(kek),
+      unwrappedKey,
+    });
+
+    return {
+      algorithm          : input.keyInput.algorithm,
+      derivationScheme   : SEAL_DERIVATION_SCHEME,
+      encryptedKey       : Encoder.bytesToBase64Url(encryptedKey),
+      ephemeralPublicKey : publicKey,
+      keyId              : input.keyInput.keyId,
+    };
+  }
+
+  private static async wrapX25519Key(input: X25519KeyWrapInput): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
+    Encryption.validateContentEncryptionKey(input.cek);
 
-    const privateKey = ephemeralPrivateKey ?? await X25519.generateKey();
+    const privateKey = input.ephemeralPrivateKey ?? await X25519.generateKey();
     const publicKey = await X25519.getPublicKey({ key: privateKey }) as PublicKeyJwk;
     const sharedSecret = await X25519.sharedSecret({
       privateKeyA : privateKey,
-      publicKeyB  : recipientPublicKey as Jwk,
+      publicKeyB  : input.keyInput.publicKey as Jwk,
     });
-    const kek = await Encryption.deriveKek(sharedSecret, keyInput);
-    const cekJwk = Encryption.toA256CtrJwk(cek);
+    const kek = await Encryption.deriveKek(sharedSecret, input.keyInput);
+    const cekJwk = Encryption.toA256CtrJwk(input.cek);
     const kekJwk: Jwk = { alg: 'A256KW', k: Encoder.bytesToBase64Url(kek), kty: 'oct' };
     const encryptedKey = await AesKw.wrapKey({ encryptionKey: kekJwk, unwrappedKey: cekJwk });
 
@@ -157,7 +247,44 @@ export class Encryption {
 
   public static async unwrapKey(
     recipientPrivateKey: Jwk,
-    keyEncryption: KeyEncryption,
+    keyEncryption: X25519KeyEncryption,
+  ): Promise<Uint8Array> {
+    if (Encryption.isX25519KeyAgreementAlgorithm(keyEncryption.algorithm)) {
+      return Encryption.unwrapX25519Key(recipientPrivateKey, keyEncryption);
+    }
+
+    throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(keyEncryption.algorithm));
+  }
+
+  public static async unwrapSeal(input: SealUnwrapInput): Promise<Uint8Array> {
+    if (!Encryption.isX25519KeyAgreementAlgorithm(input.seal.algorithm)) {
+      throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(input.seal.algorithm));
+    }
+
+    const keyEncryption: SealKeyUnwrapInfo = {
+      ...input.seal,
+      audienceKeyId : input.audienceKeyId,
+      contextId     : input.contextId,
+      protocol      : input.protocol,
+      rolePath      : input.rolePath,
+    };
+    const sharedSecret = await X25519.sharedSecret({
+      privateKeyA : input.recipientPrivateKey,
+      publicKeyB  : input.seal.ephemeralPublicKey as Jwk,
+    });
+    const kek = await Encryption.deriveKek(sharedSecret, keyEncryption);
+    const unwrappedKey = await AesKw.unwrapKey({
+      decryptionKey       : Encryption.toA256KwJwk(kek),
+      wrappedKeyAlgorithm : 'A256KW',
+      wrappedKeyBytes     : Encoder.base64UrlToBytes(input.seal.encryptedKey),
+    });
+
+    return AesKw.privateKeyToBytes({ privateKey: unwrappedKey });
+  }
+
+  private static async unwrapX25519Key(
+    recipientPrivateKey: Jwk,
+    keyEncryption: X25519KeyEncryption,
   ): Promise<Uint8Array> {
     const sharedSecret = await X25519.sharedSecret({
       privateKeyA : recipientPrivateKey,
@@ -180,33 +307,9 @@ export class Encryption {
     const algorithm = encryptionInput.algorithm ?? ContentEncryptionAlgorithm.A256CTR;
     Encryption.validateContentEncryptionParameters(algorithm, encryptionInput.key, encryptionInput.initializationVector);
 
-    const keyEncryption: KeyEncryption[] = [];
+    const keyEncryption: X25519KeyEncryption[] = [];
     for (const keyInput of encryptionInput.keyEncryptionInputs) {
-      const { encryptedKey, ephemeralPublicKey } = await Encryption.wrapKey(
-        keyInput.publicKey,
-        encryptionInput.key,
-        keyInput,
-      );
-      const common = {
-        algorithm    : KeyAgreementAlgorithm.X25519HkdfSha256A256Kw,
-        encryptedKey : Encoder.bytesToBase64Url(encryptedKey),
-        ephemeralPublicKey,
-        keyId        : keyInput.keyId,
-      };
-      if (keyInput.derivationScheme === KeyDerivationScheme.ProtocolPath) {
-        keyEncryption.push({
-          ...common,
-          derivationScheme: KeyDerivationScheme.ProtocolPath,
-        });
-      } else {
-        keyEncryption.push({
-          ...common,
-          derivationScheme : ROLE_AUDIENCE_DERIVATION_SCHEME,
-          epoch            : keyInput.epoch,
-          protocol         : keyInput.protocol,
-          role             : keyInput.role,
-        });
-      }
+      keyEncryption.push(await Encryption.buildKeyEncryptionEntry(encryptionInput.key, keyInput));
     }
 
     return {
@@ -230,18 +333,64 @@ export class Encryption {
     }
 
     for (const entry of encryption.keyEncryption) {
-      if (entry.ephemeralPublicKey.kty !== 'OKP' || entry.ephemeralPublicKey.crv !== 'X25519') {
-        throw new DwnError(
-          DwnErrorCode.RecordsWriteValidateIntegrityEncryptionEphemeralPublicKeyInvalid,
-          'ephemeralPublicKey must be an OKP X25519 public key.'
-        );
-      }
+      Encryption.validateKeyEncryptionEntry(entry);
+    }
+  }
+
+  private static async buildKeyEncryptionEntry(
+    cek: Uint8Array,
+    keyInput: X25519KeyEncryptionInput,
+  ): Promise<X25519KeyEncryption> {
+    const { encryptedKey, ephemeralPublicKey } = await Encryption.wrapKey({
+      cek,
+      keyInput,
+    });
+    const common = {
+      algorithm    : keyInput.algorithm,
+      encryptedKey : Encoder.bytesToBase64Url(encryptedKey),
+      ephemeralPublicKey,
+      keyId        : keyInput.keyId,
+    };
+
+    if (keyInput.derivationScheme === KeyDerivationScheme.ProtocolPath) {
+      return {
+        ...common,
+        derivationScheme: KeyDerivationScheme.ProtocolPath,
+      };
+    }
+
+    return {
+      ...common,
+      derivationScheme : ROLE_AUDIENCE_DERIVATION_SCHEME,
+      protocol         : keyInput.protocol,
+      rolePath         : keyInput.rolePath,
+    };
+  }
+
+  private static validateKeyEncryptionEntry(entry: X25519KeyEncryption): void {
+    if (Encryption.isX25519KeyAgreementAlgorithm(entry.algorithm)) {
+      Encryption.validateX25519KeyEncryptionEntry(entry);
+      return;
+    }
+
+    throw new DwnError(
+      DwnErrorCode.RecordsWriteValidateIntegrityEncryptionEphemeralPublicKeyInvalid,
+      Encryption.unsupportedKeyAgreementAlgorithmMessage(entry.algorithm)
+    );
+  }
+
+  private static validateX25519KeyEncryptionEntry(entry: X25519KeyEncryption): void {
+    if (entry.ephemeralPublicKey.kty !== 'OKP' || entry.ephemeralPublicKey.crv !== 'X25519') {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteValidateIntegrityEncryptionEphemeralPublicKeyInvalid,
+        'ephemeralPublicKey must be an OKP X25519 public key.'
+      );
     }
   }
 
   private static async deriveKek(
     sharedSecret: Uint8Array,
-    keyEncryption: KeyEncryptionInput | KeyEncryption,
+    keyEncryption: X25519KekDerivationInput,
   ): Promise<Uint8Array> {
     Encryption.validateSharedSecret(sharedSecret);
     const info = Encryption.getKekInfo(keyEncryption);
@@ -254,12 +403,29 @@ export class Encryption {
     });
   }
 
-  private static getKekInfo(keyEncryption: KeyEncryptionInput | KeyEncryption): string {
+  private static getKekInfo(keyEncryption: X25519KekDerivationInput): string {
+    if (keyEncryption.derivationScheme === SEAL_DERIVATION_SCHEME) {
+      return JSON.stringify([
+        KEK_INFO_PREFIX,
+        SEAL_DERIVATION_SCHEME,
+        keyEncryption.protocol,
+        keyEncryption.rolePath,
+        keyEncryption.contextId,
+        keyEncryption.audienceKeyId,
+      ]);
+    }
+
     if (keyEncryption.derivationScheme === ROLE_AUDIENCE_DERIVATION_SCHEME) {
-      return `${KEK_INFO_PREFIX}|roleAudience|${keyEncryption.protocol}|${keyEncryption.role}|${keyEncryption.epoch}|${keyEncryption.keyId}`;
+      return JSON.stringify([
+        KEK_INFO_PREFIX,
+        ROLE_AUDIENCE_DERIVATION_SCHEME,
+        keyEncryption.protocol,
+        keyEncryption.rolePath,
+        keyEncryption.keyId,
+      ]);
     }
 
-    return `${KEK_INFO_PREFIX}|protocolPath|${keyEncryption.keyId}`;
+    return JSON.stringify([KEK_INFO_PREFIX, KeyDerivationScheme.ProtocolPath, keyEncryption.keyId]);
   }
 
   private static validateContentEncryptionParameters(
@@ -290,10 +456,22 @@ export class Encryption {
     }
   }
 
+  private static isX25519KeyAgreementAlgorithm(algorithm: unknown): algorithm is KeyAgreementAlgorithm.X25519HkdfSha256A256Kw {
+    return algorithm === KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
+  }
+
+  private static unsupportedKeyAgreementAlgorithmMessage(algorithm: unknown): string {
+    return `Unsupported key agreement algorithm: ${String(algorithm)}`;
+  }
+
   private static toA256CtrJwk(keyBytes: Uint8Array): Jwk {
     return { alg: ContentEncryptionAlgorithm.A256CTR, k: Encoder.bytesToBase64Url(keyBytes), kty: 'oct' };
   }
 
+  private static toA256KwJwk(keyBytes: Uint8Array): Jwk {
+    return { alg: 'A256KW', k: Encoder.bytesToBase64Url(keyBytes), kty: 'oct' };
+  }
+
   private static async readStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
     const reader = stream.getReader();
     const chunks: Uint8Array[] = [];