@enbox/agent 0.0.1

package/src/prototyping/crypto/jose/jwe.ts

@@ -0,0 +1,653 @@
+import type { JoseHeaderParams, Jwk, KeyIdentifier } from '@enbox/crypto';
+
+import { Convert } from '@enbox/common';
+
+import type { CryptoApi } from '../types/crypto-api.js';
+import type { KeyManager } from '../types/key-manager.js';
+
+import { CryptoError, CryptoErrorCode } from '../crypto-error.js';
+
+/**
+ * Specifies options for decrypting a JWE, allowing the caller to define constraints on the JWE
+ * decryption process, particularly regarding the algorithms used.
+ *
+ * These options ensure that only expected and permitted algorithms are utilized during the
+ * decryption, enhancing security by preventing unexpected algorithm usage.
+ */
+export interface JweDecryptOptions {
+  /**
+   * The allowed "alg" (Algorithm) Header Parameter values.
+   *
+   * These values specify the cryptographic algorithms that are permissible for decrypting
+   * the Content Encryption Key (CEK) or for key agreement to determine the CEK.
+   *
+   * Note: If not specified, all algorithm values are considered allowed, which might not be
+   * desirable in all contexts.
+   */
+  allowedAlgValues?: string[];
+
+  /**
+   * The allowed "enc" (Encryption) Header Parameter values.
+   *
+   * These values determine the cryptographic algorithms that can be used for decrypting the
+   * ciphertext and protecting the integrity of the plaintext and Additional Authenticated Data.
+   *
+   * Note: If left unspecified, it implies that all encryption algorithms are acceptable, which may
+   * not be secure in every scenario.
+   *
+   */
+  allowedEncValues?: string[];
+}
+
+/**
+ * Placeholder for specifying options during the JWE encryption process. Currently, this interface
+ * does not define any specific options but can be extended in the future to include parameters
+ * that control various aspects of the JWE encryption workflow.
+ */
+export interface JweEncryptOptions {}
+
+/**
+ * JSON Web Encryption (JWE) Header Parameters
+ *
+ * The Header Parameter names for use in JWEs are registered in the IANA "JSON Web Signature and
+ * Encryption Header Parameters" registry.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1 | RFC 7516, Section 4.1}
+ */
+export interface JweHeaderParams extends JoseHeaderParams {
+  /**
+   * Algorithm Header Parameter
+   *
+   * Identifies the cryptographic algorithm used to encrypt or determine the value of the Content
+   * Encryption Key (CEK). The encrypted content is not usable if the "alg" value does not represent
+   * a supported algorithm, or if the recipient does not have a key that can be used with that
+   * algorithm.
+   *
+   * "alg" values should either be registered in the IANA "JSON Web Signature and Encryption
+   * Algorithms" registry or be a value that contains a Collision-Resistant Name. The "alg" value is
+   * a case-sensitive ASCII string.  This Header Parameter MUST be present and MUST be understood
+   * and processed by implementations.
+   *
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.1 | RFC 7516, Section 4.1.1}
+   */
+  alg:
+    // AES Key Wrap with default initial value using 128-bit key
+    | 'A128KW'
+    // AES Key Wrap with default initial value using 192-bit key
+    | 'A192KW'
+    // AES Key Wrap with default initial value using 256-bit key
+    | 'A256KW'
+    // Direct use of a shared symmetric key as the CEK
+    | 'dir'
+    // Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF
+    | 'ECDH-ES'
+    // ECDH-ES using Concat KDF and CEK wrapped with "A128KW"
+    | 'ECDH-ES+A128KW'
+    // ECDH-ES using Concat KDF and CEK wrapped with "A192KW"
+    | 'ECDH-ES+A192KW'
+    // ECDH-ES using Concat KDF and CEK wrapped with "A256KW"
+    | 'ECDH-ES+A256KW'
+    // Key wrapping with AES GCM using 128-bit key
+    | 'A128GCMKW'
+    // Key wrapping with AES GCM using 192-bit key
+    | 'A192GCMKW'
+    // Key wrapping with AES GCM using 256-bit key
+    | 'A256GCMKW'
+    // PBES2 with HMAC SHA-256 and "A128KW" wrapping
+    | 'PBES2-HS256+A128KW'
+    // PBES2 with HMAC SHA-384 and "A192KW" wrapping
+    | 'PBES2-HS384+A192KW'
+    // PBES2 with HMAC SHA-512 and "A256KW" wrapping
+    | 'PBES2-HS512+A256KW'
+    // PBES2 with HMAC SHA-512 and "XC20PKW" wrapping
+    | 'PBES2-HS512+XC20PKW'
+    // an unregistered, case-sensitive, collision-resistant string
+    | string;
+
+  /**
+   * Agreement PartyUInfo Header Parameter
+   *
+   * The "apu" (agreement PartyUInfo) value is a base64url-encoded octet sequence containing
+   * information about the producer of the JWE.  This information is used by the recipient to
+   * determine the key agreement algorithm and key encryption algorithm to use to decrypt the JWE.
+   *
+   * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+   * that uses public key cryptography.
+   */
+  apu?: string;
+
+  /**
+   * Agreement PartyVInfo Header Parameter
+   *
+   * The "apv" (agreement PartyVInfo) value is a base64url-encoded octet sequence containing
+   * information about the recipient of the JWE.  This information is used by the recipient to
+   * determine the key agreement algorithm and key encryption algorithm to use to decrypt the JWE.
+   *
+   * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+   * that uses public key cryptography.
+   */
+  apv?: string;
+
+  /**
+   * Critical Header Parameter
+   *
+   * Indicates that extensions to JOSE RFCs are being used that MUST be understood and processed.
+   */
+  crit?: string[];
+
+  /**
+   * Encryption Algorithm Header Parameter
+   *
+   * Identifies the content encryption algorithm used to encrypt and integrity-protect (also
+   * known as "authenticated encryption") the plaintext and to integrity-protect the Additional
+   * Authenticated Data (AAD), if any.  This algorithm MUST be an AEAD algorithm with a specified
+   * key length.
+   *
+   * The encrypted content is not usable if the "enc" value does not represent a supported
+   * algorithm.  "enc" values should either be registered in the IANA "JSON Web Signature and
+   * Encryption Algorithms" registry or be a value that contains a Collision-Resistant Name. The
+   * "enc" value is a case-sensitive ASCII string containing a StringOrURI value. This Header
+   * Parameter MUST be present and MUST be understood and processed by implementations.
+   *
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.2 | RFC 7516, Section 4.1.2}
+   */
+  enc:
+    // AES_128_CBC_HMAC_SHA_256 authenticated encryption algorithm,
+    // as defined in RFC 7518, Section 5.2.3
+    | 'A128CBC-HS256'
+    // AES_192_CBC_HMAC_SHA_384 authenticated encryption algorithm,
+    // as defined in RFC 7518, Section 5.2.4
+    | 'A192CBC-HS384'
+    // AES_256_CBC_HMAC_SHA_512 authenticated encryption algorithm,
+    // as defined in RFC 7518, Section 5.2.5
+    | 'A256CBC-HS512'
+    // AES GCM using 128-bit key
+    | 'A128GCM'
+    // AES GCM using 192-bit key
+    | 'A192GCM'
+    // AES GCM using 256-bit key
+    | 'A256GCM'
+    // XChaCha20-Poly1305 authenticated encryption algorithm
+    | 'XC20P'
+    // an unregistered, case-sensitive, collision-resistant string
+    | string;
+
+  /**
+   * Ephemeral Public Key Header Parameter
+   *
+   * The "epk" (ephemeral public key) value created by the originator for the use in key agreement
+   * algorithms.  It is the ephemeral public key that corresponds to the key used to encrypt the
+   * JWE.  This value is represented as a JSON Web Key (JWK).
+   *
+   * Note: This parameter is intended only for use when the recipient is a key agreement algorithm
+   * that uses public key cryptography.
+   */
+  epk?: Jwk;
+
+  /**
+   * Initialization Vector Header Parameter
+   *
+   * The "iv" (initialization vector) value is a base64url-encoded octet sequence used by the
+   * specified "enc" algorithm.  The length of this Initialization Vector value MUST be exactly
+   * equal to the value that would be produced by the "enc" algorithm.
+   *
+   * Note: With symmetric encryption algorithms such as AES GCM, this Header Parameter MUST
+   * be present and MUST be understood and processed by implementations.
+   */
+  iv?: string;
+
+  /**
+   * PBES2 Count Header Parameter
+   *
+   * The "p2c" (PBES2 count) value is an integer indicating the number of iterations of the PBKDF2
+   * algorithm performed during key derivation.
+   *
+   * Note: The iteration count adds computational expense, ideally compounded by the possible range
+   * of keys introduced by the salt.  A minimum iteration count of 1000 is RECOMMENDED.
+   */
+  p2c?: number;
+
+  /**
+   * PBES2 Salt Input Header Parameter
+   *
+   * The "p2s" (PBES2 salt) value is a base64url-encoded octet sequence used as the salt value
+   * input to the PBKDF2 algorithm during key derivation.
+   *
+   * The salt value used is (UTF8(Alg) || 0x00 || Salt Input), where Alg is the "alg" (algorithm)
+   * Header Parameter value.
+   *
+   * Note: The salt value is used to ensure that each key derived from the master key is
+   * independent of every other key. A suitable source of salt value is a sequence of
+   * cryptographically random bytes containing 8 or more octets.
+   */
+  p2s?: string;
+
+  /**
+   * Authentication Tag Header Parameter
+   *
+   * The "tag" value is a base64url-encoded octet sequence containing the value of the
+   * Authentication Tag output by the specified "enc" algorithm.  The length of this
+   * Authentication Tag value MUST be exactly equal to the value that would be produced by the
+   * "enc" algorithm.
+   *
+   * Note: With authenticated encryption algorithms such as AES GCM, this Header Parameter MUST
+   * be present and MUST be understood and processed by implementations.
+   */
+  tag?: string;
+
+  /**
+   * Additional Public or Private Header Parameter names.
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Represents the result of the JWE key management encryption process, encapsulating the Content
+ * Encryption Key (CEK) and optionally the encrypted CEK.
+ */
+export interface JweKeyManagementEncryptResult {
+  /**
+   * The Content Encryption Key (CEK) used for encrypting the JWE payload. It can be a Key
+   * Identifier such as a KMS URI or a JSON Web Key (JWK).
+   */
+  cek: KeyIdentifier | Jwk;
+
+  /**
+   * The encrypted version of the CEK, provided as a byte array. The encrypted version of the CEK
+   * is returned for all key management modes other than "dir" (Direct Encryption Mode).
+   */
+  encryptedKey?: Uint8Array;
+}
+
+/**
+ * Defines the parameters required to decrypt a JWE encrypted key, including the key management
+ * details.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface JweKeyManagementDecryptParams<TKeyManager, TCrypto> {
+  /**
+   * The decryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+   * or raw key material represented as a byte array.
+   */
+  key: KeyIdentifier | Jwk | Uint8Array;
+
+  /**
+   * The encrypted key extracted from the JWE, represented as a byte array. This parameter is
+   * optional and is used when the key is wrapped.
+   */
+  encryptedKey?: Uint8Array;
+
+  /**
+   * The JWE header parameters that define the characteristics of the decryption process, specifying
+   * the algorithm and encryption method among other settings.
+   */
+  joseHeader: JweHeaderParams;
+
+  /** Key Manager instanceß responsible for managing cryptographic keys. */
+  keyManager: TKeyManager;
+
+  /** Crypto API instance that provides the necessary cryptographic operations. */
+  crypto: TCrypto;
+}
+
+/**
+ * Defines the parameters required for encrypting a JWE CEK, including the key management details.
+ *
+ * @typeParam TKeyManager - The Key Manager used to manage cryptographic keys.
+ * @typeParam TCrypto - The Crypto API used to perform cryptographic operations.
+ */
+export interface JweKeyManagementEncryptParams<TKeyManager, TCrypto> {
+  /**
+   * The encryption key which can be a Key Identifier such as a KMS key URI, a JSON Web Key (JWK),
+   * or raw key material represented as a byte array.
+   */
+  key: KeyIdentifier | Jwk | Uint8Array;
+
+  /**
+   * The JWE header parameters that define the characteristics of the encryption process, specifying
+   * the algorithm and encryption method among other settings.
+   */
+  joseHeader: JweHeaderParams;
+
+  /** Key Manager instanceß responsible for managing cryptographic keys. */
+  keyManager: TKeyManager;
+
+  /** Crypto API instance that provides the necessary cryptographic operations. */
+  crypto: TCrypto;
+}
+
+/**
+ * Checks if the provided object is a valid JWE (JSON Web Encryption) header.
+ *
+ * This function evaluates whether the given object adheres to the structure expected for
+ * a JWE header, specifically looking for the presence and proper format of the "alg" (algorithm)
+ * and "enc" (encryption algorithm) properties, which are essential for defining the JWE's
+ * cryptographic operations.
+ *
+ * @example
+ * ```ts
+ * const header = {
+ *   alg: 'dir',
+ *   enc: 'A256GCM'
+ * };
+ *
+ * if (isValidJweHeader(header)) {
+ *   console.log('The object is a valid JWE header.');
+ * } else {
+ *   console.log('The object is not a valid JWE header.');
+ * }
+ * ```
+ *
+ * @param obj - The object to be validated as a JWE header.
+ * @returns Returns `true` if the object is a valid JWE header, otherwise `false`.
+ */
+export function isValidJweHeader(obj: unknown): obj is JweHeaderParams {
+  return typeof obj === 'object' && obj !== null
+    && 'alg' in obj && obj.alg !== undefined
+    && 'enc' in obj && obj.enc !== undefined;
+}
+
+/**
+ * The `JweKeyManagement` class implements the key management aspects of JSON Web Encryption (JWE)
+ * as specified in {@link https://datatracker.ietf.org/doc/html/rfc7516 | RFC 7516}.
+ *
+ * It supports algorithms for encrypting and decrypting keys, thereby enabling the secure
+ * transmission of information where the payload is encrypted, and the encryption key is also
+ * encrypted or agreed upon using key agreement techniques.
+ *
+ * The choice of algorithm is determined by the "alg" parameter in the JWE
+ * header, and the class is designed to handle the intricacies associated with each algorithm,
+ * ensuring the secure handling of the encryption keys.
+ *
+ * Supported algorithms include:
+ * - `"dir"`: Direct Encryption Mode
+ * - `"PBES2-HS256+A128KW"`, `"PBES2-HS384+A192KW"`, `"PBES2-HS512+A256KW"`: Password-Based
+ *   Encryption Mode with Key Wrapping (PBES2) using HMAC-SHA and AES Key Wrap algorithms for key
+ *   wrapping and encryption.
+ *
+ * @example
+ * // To encrypt a key:
+ * const keyEncryptionKey = Convert.string(passphrase).toUint8Array()
+ * const { cek, encryptedKey: encryptedCek } = await JweKeyManagement.encrypt({
+ *   key: keyEncryptionKey,
+ *   joseHeader: {
+ *     alg: 'PBES2-HS512+A256KW',
+ *     enc: 'A256GCM',
+ *     p2c : 210_000,
+       p2s : Convert.uint8Array(saltInput).toBase64Url()
+ *   },
+ *   crypto: new AgentCryptoApi(),
+ * });
+ *
+ * // To decrypt a key:
+ * const cek = await JweKeyManagement.decrypt({
+ *   key: keyEncryptionKey,
+ *   encryptedKey: encryptedCek,
+ *   joseHeader: {
+ *     alg: 'PBES2-HS512+A256KW',
+ *     enc: 'A256GCM',
+ *     p2c : 210_000,
+       p2s : Convert.uint8Array(saltInput).toBase64Url()
+ *   },
+ *   crypto: new AgentCryptoApi(),
+ * });
+ */
+export class JweKeyManagement {
+  /**
+   * Decrypts the encrypted key (JWE Encrypted Key) using the specified key encryption algorithm
+   * defined in the JWE Header's "alg" parameter.
+   *
+   * This method supports multiple key management algorithms, including Direct Encryption (dir) and
+   * PBES2 schemes with key wrapping.
+   *
+   * The method takes a key, which can be a Key Identifier, JWK, or raw byte array, and the
+   * encrypted key along with the JWE header. It returns the decrypted Content Encryption Key (CEK)
+   * which can then be used to decrypt the JWE ciphertext.
+   *
+   * @example
+   * ```ts
+   * // Decrypting the CEK with the PBES2-HS512+A256KW algorithm
+   * const cek = await JweKeyManagement.decrypt({
+   *   key: Convert.string(passphrase).toUint8Array(),
+   *   encryptedKey: encryptedCek,
+   *   joseHeader: {
+   *     alg: 'PBES2-HS512+A256KW',
+   *     enc: 'A256GCM',
+   *     p2c: 210_000,
+   *     p2s: Convert.uint8Array(saltInput).toBase64Url(),
+   *   },
+   *   crypto: new AgentCryptoApi()
+   * });
+   * ```
+   *
+   * @param params - The decryption parameters.
+   * @throws Throws an error if the key management algorithm is not supported or if required
+   *         parameters are missing or invalid.
+   */
+  public static async decrypt<TKeyManager extends KeyManager, TCrypto extends CryptoApi>({
+    key, encryptedKey, joseHeader, crypto
+  }: JweKeyManagementDecryptParams<TKeyManager, TCrypto>
+  ): Promise<KeyIdentifier | Jwk> {
+    // Determine the Key Management Mode employed by the algorithm specified by the "alg"
+    // (algorithm) Header Parameter.
+    switch (joseHeader.alg) {
+      case 'dir': {
+        // In Direct Encryption mode, a JWE "Encrypted Key" is not provided. Instead, the
+        // provided key management `key` is directly used as the Content Encryption Key (CEK) to
+        // decrypt the JWE payload.
+
+        // Verify that the JWE Encrypted Key value is empty.
+        if (encryptedKey !== undefined) {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JWE "encrypted_key" is not allowed when using "dir" (Direct Encryption Mode).');
+        }
+
+        // Verify the key management `key` is a Key Identifier or JWK.
+        if (key instanceof Uint8Array) {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'Key management "key" must be a Key URI or JWK when using "dir" (Direct Encryption Mode).');
+        }
+
+        // return the key management `key` as the CEK.
+        return key;
+      }
+
+      case 'PBES2-HS256+A128KW':
+      case 'PBES2-HS384+A192KW':
+      case 'PBES2-HS512+A256KW': {
+        // In Key Encryption mode (PBES2) with key wrapping (A128KW, A192KW, A256KW), the given
+        // passphrase, salt (p2s), and iteration count (p2c) are used with the PBKDF2 key derivation
+        // function to derive the Key Encryption Key (KEK).  The KEK is then used to decrypt the JWE
+        // Encrypted Key to obtain the Content Encryption Key (CEK).
+
+        if (typeof joseHeader.p2c !== 'number') {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JOSE Header "p2c" (PBES2 Count) is missing or not a number.');
+        }
+
+        if (typeof joseHeader.p2s !== 'string') {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JOSE Header "p2s" (PBES2 salt) is missing or not a string.');
+        }
+
+        // Throw an error if the key management `key` is not a byte array. For PBES2, the key is
+        // expected to be a low-entropy passphrase as a byte array.
+        if (!(key instanceof Uint8Array)) {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'Key management "key" must be a Uint8Array when using "PBES2" (Key Encryption Mode).');
+        }
+
+        // Verify that the JWE Encrypted Key value is present.
+        if (encryptedKey === undefined) {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JWE "encrypted_key" is required when using "PBES2" (Key Encryption Mode).');
+        }
+
+        // Per {@link https://www.rfc-editor.org/rfc/rfc7518.html#section-4.8.1.1 | RFC 7518, Section 4.8.1.1},
+        // the salt value used with PBES2 should be of the format (UTF8(Alg) || 0x00 || Salt Input),
+        // where Alg is the "alg" (algorithm) Header Parameter value. This reduces the potential for
+        // a precomputed dictionary attack (also known as a rainbow table attack).
+        let salt: Uint8Array;
+        try {
+          salt = new Uint8Array([
+            ...Convert.string(joseHeader.alg).toUint8Array(),
+            0x00,
+            ...Convert.base64Url(joseHeader.p2s).toUint8Array()
+          ]);
+        } catch {
+          throw new CryptoError(CryptoErrorCode.EncodingError, 'Failed to decode the JOSE Header "p2s" (PBES2 salt) value.');
+        }
+
+        // Derive the Key Encryption Key (KEK) from the given passphrase, salt, and iteration count.
+        const kek = await crypto.deriveKey({
+          algorithm    : joseHeader.alg,
+          baseKeyBytes : key,
+          iterations   : joseHeader.p2c,
+          salt
+        });
+
+        if (!(kek.alg && ['A128KW', 'A192KW', 'A256KW'].includes(kek.alg))) {
+          throw new CryptoError(CryptoErrorCode.AlgorithmNotSupported, `Unsupported Key Encryption Algorithm (alg) value: ${kek.alg}`);
+        }
+
+        // Decrypt the Content Encryption Key (CEK) with the derived KEK.
+        return await crypto.unwrapKey({
+          decryptionKey       : kek,
+          wrappedKeyBytes     : encryptedKey,
+          wrappedKeyAlgorithm : joseHeader.enc
+        });
+      }
+
+      default: {
+        throw new CryptoError(
+          CryptoErrorCode.AlgorithmNotSupported,
+          `Unsupported "alg" (Algorithm) Header Parameter value: ${joseHeader.alg}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Encrypts a Content Encryption Key (CEK) using the key management algorithm specified in the
+   * JWE Header's "alg" parameter.
+   *
+   * This method supports various key management algorithms, including Direct Encryption (dir) and
+   * PBES2 with key wrapping.
+   *
+   * It generates a random CEK for the specified encryption algorithm in the JWE header, which
+   * can then be used to encrypt the actual payload. For algorithms that require an encrypted key,
+   * it returns the CEK along with the encrypted key.
+   *
+   * @example
+   * ```ts
+   * // Encrypting the CEK with the PBES2-HS512+A256KW algorithm
+   * const { cek, encryptedKey } = await JweKeyManagement.encrypt({
+   *   key: Convert.string(passphrase).toUint8Array(),
+   *   joseHeader: {
+   *     alg: 'PBES2-HS512+A256KW',
+   *     enc: 'A256GCM',
+   *     p2c: 210_000,
+   *     p2s: Convert.uint8Array(saltInput).toBase64Url(),
+   *   },
+   *   crypto: crypto: new AgentCryptoApi()
+   * });
+   * ```
+   *
+   * @param params - The encryption parameters.
+   * @returns The encrypted key result containing the CEK and optionally the encrypted CEK
+   *          (JWE Encrypted Key).
+   * @throws Throws an error if the key management algorithm is not supported or if required
+   *         parameters are missing or invalid.
+   */
+  public static async encrypt<TKeyManager extends KeyManager, TCrypto extends CryptoApi>({
+    key, joseHeader, crypto
+  }: JweKeyManagementEncryptParams<TKeyManager, TCrypto>
+  ): Promise<JweKeyManagementEncryptResult> {
+    let cek: KeyIdentifier | Jwk;
+    let encryptedKey: Uint8Array | undefined;
+
+    // Determine the Key Management Mode employed by the algorithm specified by the "alg"
+    // (algorithm) Header Parameter.
+    switch (joseHeader.alg) {
+      case 'dir': {
+        // In Direct Encryption mode (dir), a JWE "Encrypted Key" is not provided. Instead, the
+        // provided key management `key` is directly used as the Content Encryption Key (CEK) to
+        // decrypt the JWE payload.
+
+        // Verify that the JWE Encrypted Key value is empty.
+        if (encryptedKey !== undefined) {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JWE "encrypted_key" is not allowed when using "dir" (Direct Encryption Mode).');
+        }
+
+        // Verify the key management `key` is a Key Identifier or JWK.
+        if (key instanceof Uint8Array) {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'Key management "key" must be a Key URI or JWK when using "dir" (Direct Encryption Mode).');
+        }
+
+        // Set the CEK to the key management `key`.
+        cek = key;
+
+        break;
+      }
+
+      case 'PBES2-HS256+A128KW':
+      case 'PBES2-HS384+A192KW':
+      case 'PBES2-HS512+A256KW': {
+        // In Key Encryption mode (PBES2) with key wrapping (A128KW, A192KW, A256KW), a randomly
+        // generated Content Encryption Key (CEK) is encrypted with a Key Encryption Key (KEK)
+        // derived from the given passphrase, salt (p2s), and iteration count (p2c) using the
+        // PBKDF2 key derivation function.
+
+        if (typeof joseHeader.p2c !== 'number') {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JOSE Header "p2c" (PBES2 Count) is missing or not a number.');
+        }
+
+        if (typeof joseHeader.p2s !== 'string') {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JOSE Header "p2s" (PBES2 salt) is missing or not a string.');
+        }
+
+        // Throw an error if the key management `key` is not a byte array.
+        if (!(key instanceof Uint8Array)) {
+          throw new CryptoError(CryptoErrorCode.InvalidJwe, 'Key management "key" must be a Uint8Array when using "PBES2" (Key Encryption Mode).');
+        }
+
+        // Generate a random Content Encryption Key (CEK) using the algorithm specified by the "enc"
+        // (encryption) Header Parameter.
+        cek = await crypto.generateKey({ algorithm: joseHeader.enc });
+
+        // Per {@link https://www.rfc-editor.org/rfc/rfc7518.html#section-4.8.1.1 | RFC 7518, Section 4.8.1.1},
+        // the salt value used with PBES2 should be of the format (UTF8(Alg) || 0x00 || Salt Input),
+        // where Alg is the "alg" (algorithm) Header Parameter value. This reduces the potential for
+        // a precomputed dictionary attack (also known as a rainbow table attack).
+        let salt: Uint8Array;
+        try {
+          salt = new Uint8Array([
+            ...Convert.string(joseHeader.alg).toUint8Array(),
+            0x00,
+            ...Convert.base64Url(joseHeader.p2s).toUint8Array()
+          ]);
+        } catch {
+          throw new CryptoError(CryptoErrorCode.EncodingError, 'Failed to decode the JOSE Header "p2s" (PBES2 salt) value.');
+        }
+
+        // Derive a Key Encryption Key (KEK) from the given passphrase, salt, and iteration count.
+        const kek = await crypto.deriveKey({
+          algorithm    : joseHeader.alg,
+          baseKeyBytes : key,
+          iterations   : joseHeader.p2c,
+          salt
+        });
+
+        // Encrypt the randomly generated CEK with the derived Key Encryption Key (KEK).
+        encryptedKey = await crypto.wrapKey({ encryptionKey: kek, unwrappedKey: cek });
+
+        break;
+      }
+
+      default: {
+        throw new CryptoError(
+          CryptoErrorCode.AlgorithmNotSupported,
+          `Unsupported "alg" (Algorithm) Header Parameter value: ${joseHeader.alg}`
+        );
+      }
+    }
+
+    return { cek, encryptedKey };
+  }
+}