feat!: JSON Web Key is now an allowed input everywhere

BREAKING CHANGE: resolved keys returned as part of verify/decrypt operations (when get key functions are used) are always normalized to either Uint8Array / CryptoKey depending on what's more efficient for the executed operation
BREAKING CHANGE: Key "Type" Generics are removed

Author: panva

.electron_flags.sh

@@ -2,7 +2,7 @@ echo $(electron -i <<< 'process.exit(0)' 2> /dev/null | grep "Using" | awk '{$1=
 
 electron -i <<< 'process.exit(parseInt(process.versions.node, 10))' &> /dev/null
 NODE_VERSION=$?
-export NODE_OPTIONS='--no-warnings'
+export NODE_OPTIONS='--no-warnings --enable-source-maps'
 
 if [[ $NODE_VERSION -eq 18 ]]; then
   export NODE_OPTIONS+=' --experimental-global-webcrypto'

.gitignore

@@ -121,7 +121,9 @@ dist-browser-tests
 
 .npmrc
 tap/*.js
+tap/*.js.map
 tap/run-*.mjs
+tap/run-*.mjs.map
 *.bak
 *.bun
 tap/.workerd.capnp

.node_flags.sh

@@ -2,7 +2,7 @@ echo "Using Node.js $(node --version)"
 
 node -e 'process.exit(parseInt(process.versions.node, 10))' &> /dev/null
 NODE_VERSION=$?
-export NODE_OPTIONS='--no-warnings'
+export NODE_OPTIONS='--no-warnings --enable-source-maps'
 
 if [[ $NODE_VERSION -eq 18 ]]; then
   export NODE_OPTIONS+=' --experimental-global-webcrypto'

src/index.ts

@@ -60,6 +60,8 @@ export type { GenerateSecretOptions } from './key/generate_secret.js'
 export * as base64url from './util/base64url.js'
 
 export type {
+  CryptoKey,
+  KeyObject,
   KeyLike,
   JWK,
   JWKParameters,

src/jwe/compact/decrypt.ts

@@ -2,13 +2,15 @@ import { flattenedDecrypt } from '../flattened/decrypt.js'
 import { JWEInvalid } from '../../util/errors.js'
 import { decoder } from '../../lib/buffer_utils.js'
 import type {
-  KeyLike,
+  CryptoKey,
   DecryptOptions,
   CompactJWEHeaderParameters,
   GetKeyFunction,
   FlattenedJWE,
   CompactDecryptResult,
   ResolvedKey,
+  KeyObject,
+  JWK,
 } from '../../types.d.ts'
 
 /**
@@ -43,7 +45,7 @@ export interface CompactDecryptGetKey
  */
 export async function compactDecrypt(
   jwe: string | Uint8Array,
-  key: KeyLike | Uint8Array,
+  key: CryptoKey | KeyObject | JWK | Uint8Array,
   options?: DecryptOptions,
 ): Promise<CompactDecryptResult>
 /**
@@ -52,14 +54,14 @@ export async function compactDecrypt(
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export async function compactDecrypt<KeyLikeType extends KeyLike = KeyLike>(
+export async function compactDecrypt(
   jwe: string | Uint8Array,
   getKey: CompactDecryptGetKey,
   options?: DecryptOptions,
-): Promise<CompactDecryptResult & ResolvedKey<KeyLikeType>>
+): Promise<CompactDecryptResult & ResolvedKey>
 export async function compactDecrypt(
   jwe: string | Uint8Array,
-  key: KeyLike | Uint8Array | CompactDecryptGetKey,
+  key: CryptoKey | KeyObject | JWK | Uint8Array | CompactDecryptGetKey,
   options?: DecryptOptions,
 ) {
   if (jwe instanceof Uint8Array) {

src/jwe/compact/encrypt.ts

@@ -1,9 +1,11 @@
 import { FlattenedEncrypt } from '../flattened/encrypt.js'
 import type {
-  KeyLike,
+  KeyObject,
+  CryptoKey,
   JWEKeyManagementHeaderParameters,
   CompactJWEHeaderParameters,
   EncryptOptions,
+  JWK,
 } from '../../types.d.ts'
 
 /**
@@ -89,7 +91,10 @@ export class CompactEncrypt {
    *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
    * @param options JWE Encryption options.
    */
-  async encrypt(key: KeyLike | Uint8Array, options?: EncryptOptions): Promise<string> {
+  async encrypt(
+    key: CryptoKey | KeyObject | JWK | Uint8Array,
+    options?: EncryptOptions,
+  ): Promise<string> {
     const jwe = await this._flattened.encrypt(key, options)
 
     return [jwe.protected, jwe.encrypted_key, jwe.iv, jwe.ciphertext, jwe.tag].join('.')

src/jwe/flattened/decrypt.ts

@@ -7,17 +7,21 @@ import isObject from '../../lib/is_object.js'
 import decryptKeyManagement from '../../lib/decrypt_key_management.js'
 import type {
   FlattenedDecryptResult,
-  KeyLike,
+  CryptoKey,
   FlattenedJWE,
   JWEHeaderParameters,
   DecryptOptions,
   GetKeyFunction,
   ResolvedKey,
+  KeyObject,
+  JWK,
 } from '../../types.d.ts'
 import { encoder, decoder, concat } from '../../lib/buffer_utils.js'
 import generateCek from '../../lib/cek.js'
 import validateCrit from '../../lib/validate_crit.js'
 import validateAlgorithms from '../../lib/validate_algorithms.js'
+import normalizeKey from '../../runtime/normalize_key.js'
+import checkKeyType from '../../lib/check_key_type.js'
 
 /**
  * Interface for Flattened JWE Decryption dynamic key resolution. No token components have been
@@ -61,7 +65,7 @@ export interface FlattenedDecryptGetKey
  */
 export function flattenedDecrypt(
   jwe: FlattenedJWE,
-  key: KeyLike | Uint8Array,
+  key: CryptoKey | KeyObject | JWK | Uint8Array,
   options?: DecryptOptions,
 ): Promise<FlattenedDecryptResult>
 /**
@@ -70,14 +74,14 @@ export function flattenedDecrypt(
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export function flattenedDecrypt<KeyLikeType extends KeyLike = KeyLike>(
+export function flattenedDecrypt(
   jwe: FlattenedJWE,
   getKey: FlattenedDecryptGetKey,
   options?: DecryptOptions,
-): Promise<FlattenedDecryptResult & ResolvedKey<KeyLikeType>>
+): Promise<FlattenedDecryptResult & ResolvedKey>
 export async function flattenedDecrypt(
   jwe: FlattenedJWE,
-  key: KeyLike | Uint8Array | FlattenedDecryptGetKey,
+  key: CryptoKey | KeyObject | JWK | Uint8Array | FlattenedDecryptGetKey,
   options?: DecryptOptions,
 ) {
   if (!isObject(jwe)) {
@@ -190,10 +194,12 @@ export async function flattenedDecrypt(
     key = await key(parsedProt, jwe)
     resolvedKey = true
   }
+  checkKeyType(alg === 'dir' ? enc : alg, key, 'decrypt')
 
-  let cek: KeyLike | Uint8Array
+  const k = await normalizeKey(key, alg)
+  let cek: CryptoKey | Uint8Array
   try {
-    cek = await decryptKeyManagement(alg, key, encryptedKey, joseHeader, options)
+    cek = await decryptKeyManagement(alg, k, encryptedKey, joseHeader, options)
   } catch (err) {
     if (err instanceof TypeError || err instanceof JWEInvalid || err instanceof JOSENotSupported) {
       throw err
@@ -265,7 +271,7 @@ export async function flattenedDecrypt(
   }
 
   if (resolvedKey) {
-    return { ...result, key }
+    return { ...result, key: k }
   }
 
   return result

src/jwe/flattened/encrypt.ts

@@ -3,17 +3,21 @@ import { unprotected } from '../../lib/private_symbols.js'
 import encrypt from '../../runtime/encrypt.js'
 
 import type {
-  KeyLike,
+  CryptoKey,
   FlattenedJWE,
   JWEHeaderParameters,
   JWEKeyManagementHeaderParameters,
   EncryptOptions,
+  KeyObject,
+  JWK,
 } from '../../types.d.ts'
 import encryptKeyManagement from '../../lib/encrypt_key_management.js'
 import { JOSENotSupported, JWEInvalid } from '../../util/errors.js'
 import isDisjoint from '../../lib/is_disjoint.js'
 import { encoder, decoder, concat } from '../../lib/buffer_utils.js'
 import validateCrit from '../../lib/validate_crit.js'
+import normalizeKey from '../../runtime/normalize_key.js'
+import checkKeyType from '../../lib/check_key_type.js'
 
 /**
  * The FlattenedEncrypt class is used to build and encrypt Flattened JWE objects.
@@ -165,7 +169,10 @@ export class FlattenedEncrypt {
    *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
    * @param options JWE Encryption options.
    */
-  async encrypt(key: KeyLike | Uint8Array, options?: EncryptOptions): Promise<FlattenedJWE> {
+  async encrypt(
+    key: CryptoKey | KeyObject | JWK | Uint8Array,
+    options?: EncryptOptions,
+  ): Promise<FlattenedJWE> {
     if (!this._protectedHeader && !this._unprotectedHeader && !this._sharedUnprotectedHeader) {
       throw new JWEInvalid(
         'either setProtectedHeader, setUnprotectedHeader, or sharedUnprotectedHeader must be called before #encrypt()',
@@ -212,13 +219,16 @@ export class FlattenedEncrypt {
       )
     }
 
-    let cek: KeyLike | Uint8Array
+    checkKeyType(alg === 'dir' ? enc : alg, key, 'encrypt')
+
+    let cek: CryptoKey | Uint8Array
     {
       let parameters: { [propName: string]: unknown } | undefined
+      const k = await normalizeKey(key, alg)
       ;({ cek, encryptedKey, parameters } = await encryptKeyManagement(
         alg,
         enc,
-        key,
+        k,
         this._cek,
         this._keyManagementParameters,
       ))

src/jwe/general/decrypt.ts

@@ -1,14 +1,16 @@
 import { flattenedDecrypt } from '../flattened/decrypt.js'
 import { JWEDecryptionFailed, JWEInvalid } from '../../util/errors.js'
 import type {
-  KeyLike,
+  CryptoKey,
   DecryptOptions,
   JWEHeaderParameters,
   GetKeyFunction,
   FlattenedJWE,
   GeneralJWE,
   GeneralDecryptResult,
   ResolvedKey,
+  KeyObject,
+  JWK,
 } from '../../types.d.ts'
 import isObject from '../../lib/is_object.js'
 
@@ -57,7 +59,7 @@ export interface GeneralDecryptGetKey extends GetKeyFunction<JWEHeaderParameters
  */
 export function generalDecrypt(
   jwe: GeneralJWE,
-  key: KeyLike | Uint8Array,
+  key: CryptoKey | KeyObject | JWK | Uint8Array,
   options?: DecryptOptions,
 ): Promise<GeneralDecryptResult>
 /**
@@ -66,14 +68,14 @@ export function generalDecrypt(
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
-export function generalDecrypt<KeyLikeType extends KeyLike = KeyLike>(
+export function generalDecrypt(
   jwe: GeneralJWE,
   getKey: GeneralDecryptGetKey,
   options?: DecryptOptions,
-): Promise<GeneralDecryptResult & ResolvedKey<KeyLikeType>>
+): Promise<GeneralDecryptResult & ResolvedKey>
 export async function generalDecrypt(
   jwe: GeneralJWE,
-  key: KeyLike | Uint8Array | GeneralDecryptGetKey,
+  key: CryptoKey | KeyObject | JWK | Uint8Array | GeneralDecryptGetKey,
   options?: DecryptOptions,
 ) {
   if (!isObject(jwe)) {

src/jwe/general/encrypt.ts

@@ -7,7 +7,16 @@ import encryptKeyManagement from '../../lib/encrypt_key_management.js'
 import { encode as base64url } from '../../runtime/base64url.js'
 import validateCrit from '../../lib/validate_crit.js'
 
-import type { KeyLike, GeneralJWE, JWEHeaderParameters, CritOption } from '../../types.d.ts'
+import type {
+  CryptoKey,
+  GeneralJWE,
+  JWEHeaderParameters,
+  CritOption,
+  KeyObject,
+  JWK,
+} from '../../types.d.ts'
+import normalizeKey from '../../runtime/normalize_key.js'
+import checkKeyType from '../../lib/check_key_type.js'
 
 export interface Recipient {
   /**
@@ -30,10 +39,14 @@ export interface Recipient {
 class IndividualRecipient implements Recipient {
   private parent: GeneralEncrypt
   unprotectedHeader?: JWEHeaderParameters
-  key: KeyLike | Uint8Array
+  key: CryptoKey | KeyObject | JWK | Uint8Array
   options: CritOption
 
-  constructor(enc: GeneralEncrypt, key: KeyLike | Uint8Array, options: CritOption) {
+  constructor(
+    enc: GeneralEncrypt,
+    key: CryptoKey | KeyObject | JWK | Uint8Array,
+    options: CritOption,
+  ) {
     this.parent = enc
     this.key = key
     this.options = options
@@ -105,7 +118,7 @@ export class GeneralEncrypt {
    *   See {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
    * @param options JWE Encryption options.
    */
-  addRecipient(key: KeyLike | Uint8Array, options?: CritOption): Recipient {
+  addRecipient(key: CryptoKey | KeyObject | JWK | Uint8Array, options?: CritOption): Recipient {
     const recipient = new IndividualRecipient(this, key, { crit: options?.crit })
     this._recipients.push(recipient)
     return recipient
@@ -277,15 +290,15 @@ export class GeneralEncrypt {
         continue
       }
 
-      const { encryptedKey, parameters } = await encryptKeyManagement(
+      const alg =
         recipient.unprotectedHeader?.alg! ||
-          this._protectedHeader?.alg! ||
-          this._unprotectedHeader?.alg!,
-        enc,
-        recipient.key,
-        cek,
-        { p2c },
-      )
+        this._protectedHeader?.alg! ||
+        this._unprotectedHeader?.alg!
+
+      checkKeyType(alg === 'dir' ? enc : alg, recipient.key, 'encrypt')
+
+      const k = await normalizeKey(recipient.key, alg)
+      const { encryptedKey, parameters } = await encryptKeyManagement(alg, enc, k, cek, { p2c })
       target.encrypted_key = base64url(encryptedKey!)
       if (recipient.unprotectedHeader || parameters)
         target.header = { ...recipient.unprotectedHeader, ...parameters }