jose 4.5.1 → 4.6.0

package/dist/browser/jwe/compact/decrypt.js

@@ -13,7 +13,7 @@ export async function compactDecrypt(jwe, key, options) {
         throw new JWEInvalid('Invalid Compact JWE');
     }
     const decrypted = await flattenedDecrypt({
-        ciphertext: (ciphertext || undefined),
+        ciphertext,
         iv: (iv || undefined),
         protected: protectedHeader || undefined,
         tag: (tag || undefined),

package/dist/browser/jwe/general/encrypt.js

@@ -133,6 +133,12 @@ export class GeneralEncrypt {
             const recipient = this._recipients[i];
             const target = {};
             jwe.recipients.push(target);
+            const joseHeader = {
+                ...this._protectedHeader,
+                ...this._unprotectedHeader,
+                ...recipient.unprotectedHeader,
+            };
+            const p2c = joseHeader.alg.startsWith('PBES2') ? 2048 + i : undefined;
             if (i === 0) {
                 const flattened = await new FlattenedEncrypt(this._plaintext)
                     .setAdditionalAuthenticatedData(this._aad)
@@ -140,6 +146,7 @@ export class GeneralEncrypt {
                     .setProtectedHeader(this._protectedHeader)
                     .setSharedUnprotectedHeader(this._unprotectedHeader)
                     .setUnprotectedHeader(recipient.unprotectedHeader)
+                    .setKeyManagementParameters({ p2c })
                     .encrypt(recipient.key, {
                     ...recipient.options,
                     ...options,
@@ -161,7 +168,7 @@ export class GeneralEncrypt {
             }
             const { encryptedKey, parameters } = await encryptKeyManagement(((_a = recipient.unprotectedHeader) === null || _a === void 0 ? void 0 : _a.alg) ||
                 ((_b = this._protectedHeader) === null || _b === void 0 ? void 0 : _b.alg) ||
-                ((_c = this._unprotectedHeader) === null || _c === void 0 ? void 0 : _c.alg), enc, recipient.key, cek);
+                ((_c = this._unprotectedHeader) === null || _c === void 0 ? void 0 : _c.alg), enc, recipient.key, cek, { p2c });
             target.encrypted_key = base64url(encryptedKey);
             if (recipient.unprotectedHeader || parameters)
                 target.header = { ...recipient.unprotectedHeader, ...parameters };

package/dist/browser/lib/crypto_key.js

@@ -121,7 +121,7 @@ export function checkEncCryptoKey(key, alg, ...usages) {
                 throw unusable(expected, 'algorithm.length');
             break;
         }
-        case 'ECDH-ES':
+        case 'ECDH':
             if (!isAlgorithm(key.algorithm, 'ECDH'))
                 throw unusable('ECDH');
             break;

package/dist/browser/lib/decrypt_key_management.js

@@ -26,7 +26,7 @@ async function decryptKeyManagement(alg, key, encryptedKey, joseHeader) {
             if (!isObject(joseHeader.epk))
                 throw new JWEInvalid(`JOSE Header "epk" (Ephemeral Public Key) missing or invalid`);
             if (!ECDH.ecdhAllowed(key))
-                throw new JOSENotSupported('ECDH-ES with the provided key is not allowed or not supported by your javascript runtime');
+                throw new JOSENotSupported('ECDH with the provided key is not allowed or not supported by your javascript runtime');
             const epk = await importJWK(joseHeader.epk, alg);
             let partyUInfo;
             let partyVInfo;

package/dist/browser/lib/encrypt_key_management.js

@@ -23,7 +23,7 @@ async function encryptKeyManagement(alg, enc, key, providedCek, providedParamete
         case 'ECDH-ES+A192KW':
         case 'ECDH-ES+A256KW': {
             if (!ECDH.ecdhAllowed(key)) {
-                throw new JOSENotSupported('ECDH-ES with the provided key is not allowed or not supported by your javascript runtime');
+                throw new JOSENotSupported('ECDH with the provided key is not allowed or not supported by your javascript runtime');
             }
             const { apu, apv } = providedParameters;
             let { epk: ephemeralKey } = providedParameters;

package/dist/browser/runtime/ecdhes.js

@@ -7,15 +7,12 @@ export async function deriveKey(publicKey, privateKey, algorithm, keyLength, apu
     if (!isCryptoKey(publicKey)) {
         throw new TypeError(invalidKeyInput(publicKey, ...types));
     }
-    checkEncCryptoKey(publicKey, 'ECDH-ES');
+    checkEncCryptoKey(publicKey, 'ECDH');
     if (!isCryptoKey(privateKey)) {
         throw new TypeError(invalidKeyInput(privateKey, ...types));
     }
-    checkEncCryptoKey(privateKey, 'ECDH-ES', 'deriveBits', 'deriveKey');
+    checkEncCryptoKey(privateKey, 'ECDH', 'deriveBits');
     const value = concat(lengthAndInput(encoder.encode(algorithm)), lengthAndInput(apu), lengthAndInput(apv), uint32be(keyLength));
-    if (!privateKey.usages.includes('deriveBits')) {
-        throw new TypeError('ECDH-ES private key "usages" must include "deriveBits"');
-    }
     const sharedSecret = new Uint8Array(await crypto.subtle.deriveBits({
         name: 'ECDH',
         public: publicKey,

package/dist/browser/runtime/fetch_jwks.js

@@ -1,5 +1,4 @@
 import { JOSEError, JWKSTimeout } from '../util/errors.js';
-import { isCloudflareWorkers } from './env.js';
 const fetchJwks = async (url, timeout) => {
     let controller;
     let id;
@@ -14,14 +13,6 @@ const fetchJwks = async (url, timeout) => {
     const response = await fetch(url.href, {
         signal: controller ? controller.signal : undefined,
         redirect: 'manual',
-        method: 'GET',
-        ...(!isCloudflareWorkers()
-            ? {
-                referrerPolicy: 'no-referrer',
-                credentials: 'omit',
-                mode: 'cors',
-            }
-            : undefined),
     }).catch((err) => {
         if (timedOut)
             throw new JWKSTimeout();

package/dist/browser/runtime/pbes2kw.js

@@ -40,7 +40,7 @@ async function deriveKey(p2s, alg, p2c, key) {
     }
     throw new TypeError('PBKDF2 key "usages" must include "deriveBits" or "deriveKey"');
 }
-export const encrypt = async (alg, key, cek, p2c = Math.floor(Math.random() * 2049) + 2048, p2s = random(new Uint8Array(16))) => {
+export const encrypt = async (alg, key, cek, p2c = 2048, p2s = random(new Uint8Array(16))) => {
     const derived = await deriveKey(p2s, alg, p2c, key);
     const encryptedKey = await wrap(alg.slice(-6), derived, cek);
     return { encryptedKey, p2c, p2s: base64url(p2s) };

package/dist/node/cjs/jwe/compact/decrypt.js

@@ -16,7 +16,7 @@ async function compactDecrypt(jwe, key, options) {
         throw new errors_js_1.JWEInvalid('Invalid Compact JWE');
     }
     const decrypted = await (0, decrypt_js_1.flattenedDecrypt)({
-        ciphertext: (ciphertext || undefined),
+        ciphertext,
         iv: (iv || undefined),
         protected: protectedHeader || undefined,
         tag: (tag || undefined),

package/dist/node/cjs/jwe/general/encrypt.js

@@ -136,6 +136,12 @@ class GeneralEncrypt {
             const recipient = this._recipients[i];
             const target = {};
             jwe.recipients.push(target);
+            const joseHeader = {
+                ...this._protectedHeader,
+                ...this._unprotectedHeader,
+                ...recipient.unprotectedHeader,
+            };
+            const p2c = joseHeader.alg.startsWith('PBES2') ? 2048 + i : undefined;
             if (i === 0) {
                 const flattened = await new encrypt_js_1.FlattenedEncrypt(this._plaintext)
                     .setAdditionalAuthenticatedData(this._aad)
@@ -143,6 +149,7 @@ class GeneralEncrypt {
                     .setProtectedHeader(this._protectedHeader)
                     .setSharedUnprotectedHeader(this._unprotectedHeader)
                     .setUnprotectedHeader(recipient.unprotectedHeader)
+                    .setKeyManagementParameters({ p2c })
                     .encrypt(recipient.key, {
                     ...recipient.options,
                     ...options,
@@ -164,7 +171,7 @@ class GeneralEncrypt {
             }
             const { encryptedKey, parameters } = await (0, encrypt_key_management_js_1.default)(((_a = recipient.unprotectedHeader) === null || _a === void 0 ? void 0 : _a.alg) ||
                 ((_b = this._protectedHeader) === null || _b === void 0 ? void 0 : _b.alg) ||
-                ((_c = this._unprotectedHeader) === null || _c === void 0 ? void 0 : _c.alg), enc, recipient.key, cek);
+                ((_c = this._unprotectedHeader) === null || _c === void 0 ? void 0 : _c.alg), enc, recipient.key, cek, { p2c });
             target.encrypted_key = (0, base64url_js_1.encode)(encryptedKey);
             if (recipient.unprotectedHeader || parameters)
                 target.header = { ...recipient.unprotectedHeader, ...parameters };

package/dist/node/cjs/lib/crypto_key.js

@@ -125,7 +125,7 @@ function checkEncCryptoKey(key, alg, ...usages) {
                 throw unusable(expected, 'algorithm.length');
             break;
         }
-        case 'ECDH-ES':
+        case 'ECDH':
             if (!isAlgorithm(key.algorithm, 'ECDH'))
                 throw unusable('ECDH');
             break;

package/dist/node/cjs/lib/decrypt_key_management.js

@@ -28,7 +28,7 @@ async function decryptKeyManagement(alg, key, encryptedKey, joseHeader) {
             if (!(0, is_object_js_1.default)(joseHeader.epk))
                 throw new errors_js_1.JWEInvalid(`JOSE Header "epk" (Ephemeral Public Key) missing or invalid`);
             if (!ECDH.ecdhAllowed(key))
-                throw new errors_js_1.JOSENotSupported('ECDH-ES with the provided key is not allowed or not supported by your javascript runtime');
+                throw new errors_js_1.JOSENotSupported('ECDH with the provided key is not allowed or not supported by your javascript runtime');
             const epk = await (0, import_js_1.importJWK)(joseHeader.epk, alg);
             let partyUInfo;
             let partyVInfo;

package/dist/node/cjs/lib/encrypt_key_management.js

@@ -25,7 +25,7 @@ async function encryptKeyManagement(alg, enc, key, providedCek, providedParamete
         case 'ECDH-ES+A192KW':
         case 'ECDH-ES+A256KW': {
             if (!ECDH.ecdhAllowed(key)) {
-                throw new errors_js_1.JOSENotSupported('ECDH-ES with the provided key is not allowed or not supported by your javascript runtime');
+                throw new errors_js_1.JOSENotSupported('ECDH with the provided key is not allowed or not supported by your javascript runtime');
             }
             const { apu, apv } = providedParameters;
             let { epk: ephemeralKey } = providedParameters;

package/dist/node/cjs/runtime/ecdhes.js

@@ -15,7 +15,7 @@ const generateKeyPair = (0, util_1.promisify)(crypto_1.generateKeyPair);
 async function deriveKey(publicKee, privateKee, algorithm, keyLength, apu = new Uint8Array(0), apv = new Uint8Array(0)) {
     let publicKey;
     if ((0, webcrypto_js_1.isCryptoKey)(publicKee)) {
-        (0, crypto_key_js_1.checkEncCryptoKey)(publicKee, 'ECDH-ES');
+        (0, crypto_key_js_1.checkEncCryptoKey)(publicKee, 'ECDH');
         publicKey = crypto_1.KeyObject.from(publicKee);
     }
     else if ((0, is_key_object_js_1.default)(publicKee)) {
@@ -26,7 +26,7 @@ async function deriveKey(publicKee, privateKee, algorithm, keyLength, apu = new
     }
     let privateKey;
     if ((0, webcrypto_js_1.isCryptoKey)(privateKee)) {
-        (0, crypto_key_js_1.checkEncCryptoKey)(privateKee, 'ECDH-ES', 'deriveBits', 'deriveKey');
+        (0, crypto_key_js_1.checkEncCryptoKey)(privateKee, 'ECDH', 'deriveBits');
         privateKey = crypto_1.KeyObject.from(privateKee);
     }
     else if ((0, is_key_object_js_1.default)(privateKee)) {

package/dist/node/cjs/runtime/pbes2kw.js

@@ -27,7 +27,7 @@ function getPassword(key, alg) {
     }
     throw new TypeError((0, invalid_key_input_js_1.default)(key, ...is_key_like_js_1.types, 'Uint8Array'));
 }
-const encrypt = async (alg, key, cek, p2c = Math.floor(Math.random() * 2049) + 2048, p2s = (0, random_js_1.default)(new Uint8Array(16))) => {
+const encrypt = async (alg, key, cek, p2c = 2048, p2s = (0, random_js_1.default)(new Uint8Array(16))) => {
     (0, check_p2s_js_1.default)(p2s);
     const salt = (0, buffer_utils_js_1.p2s)(alg, p2s);
     const keylen = parseInt(alg.slice(13, 16), 10) >> 3;

package/dist/node/esm/jwe/compact/decrypt.js

@@ -13,7 +13,7 @@ export async function compactDecrypt(jwe, key, options) {
         throw new JWEInvalid('Invalid Compact JWE');
     }
     const decrypted = await flattenedDecrypt({
-        ciphertext: (ciphertext || undefined),
+        ciphertext,
         iv: (iv || undefined),
         protected: protectedHeader || undefined,
         tag: (tag || undefined),

package/dist/node/esm/jwe/general/encrypt.js

@@ -133,6 +133,12 @@ export class GeneralEncrypt {
             const recipient = this._recipients[i];
             const target = {};
             jwe.recipients.push(target);
+            const joseHeader = {
+                ...this._protectedHeader,
+                ...this._unprotectedHeader,
+                ...recipient.unprotectedHeader,
+            };
+            const p2c = joseHeader.alg.startsWith('PBES2') ? 2048 + i : undefined;
             if (i === 0) {
                 const flattened = await new FlattenedEncrypt(this._plaintext)
                     .setAdditionalAuthenticatedData(this._aad)
@@ -140,6 +146,7 @@ export class GeneralEncrypt {
                     .setProtectedHeader(this._protectedHeader)
                     .setSharedUnprotectedHeader(this._unprotectedHeader)
                     .setUnprotectedHeader(recipient.unprotectedHeader)
+                    .setKeyManagementParameters({ p2c })
                     .encrypt(recipient.key, {
                     ...recipient.options,
                     ...options,
@@ -161,7 +168,7 @@ export class GeneralEncrypt {
             }
             const { encryptedKey, parameters } = await encryptKeyManagement(((_a = recipient.unprotectedHeader) === null || _a === void 0 ? void 0 : _a.alg) ||
                 ((_b = this._protectedHeader) === null || _b === void 0 ? void 0 : _b.alg) ||
-                ((_c = this._unprotectedHeader) === null || _c === void 0 ? void 0 : _c.alg), enc, recipient.key, cek);
+                ((_c = this._unprotectedHeader) === null || _c === void 0 ? void 0 : _c.alg), enc, recipient.key, cek, { p2c });
             target.encrypted_key = base64url(encryptedKey);
             if (recipient.unprotectedHeader || parameters)
                 target.header = { ...recipient.unprotectedHeader, ...parameters };

package/dist/node/esm/lib/crypto_key.js

@@ -121,7 +121,7 @@ export function checkEncCryptoKey(key, alg, ...usages) {
                 throw unusable(expected, 'algorithm.length');
             break;
         }
-        case 'ECDH-ES':
+        case 'ECDH':
             if (!isAlgorithm(key.algorithm, 'ECDH'))
                 throw unusable('ECDH');
             break;

package/dist/node/esm/lib/decrypt_key_management.js

@@ -26,7 +26,7 @@ async function decryptKeyManagement(alg, key, encryptedKey, joseHeader) {
             if (!isObject(joseHeader.epk))
                 throw new JWEInvalid(`JOSE Header "epk" (Ephemeral Public Key) missing or invalid`);
             if (!ECDH.ecdhAllowed(key))
-                throw new JOSENotSupported('ECDH-ES with the provided key is not allowed or not supported by your javascript runtime');
+                throw new JOSENotSupported('ECDH with the provided key is not allowed or not supported by your javascript runtime');
             const epk = await importJWK(joseHeader.epk, alg);
             let partyUInfo;
             let partyVInfo;

package/dist/node/esm/lib/encrypt_key_management.js

@@ -23,7 +23,7 @@ async function encryptKeyManagement(alg, enc, key, providedCek, providedParamete
         case 'ECDH-ES+A192KW':
         case 'ECDH-ES+A256KW': {
             if (!ECDH.ecdhAllowed(key)) {
-                throw new JOSENotSupported('ECDH-ES with the provided key is not allowed or not supported by your javascript runtime');
+                throw new JOSENotSupported('ECDH with the provided key is not allowed or not supported by your javascript runtime');
             }
             const { apu, apv } = providedParameters;
             let { epk: ephemeralKey } = providedParameters;

package/dist/node/esm/runtime/ecdhes.js

@@ -12,7 +12,7 @@ const generateKeyPair = promisify(generateKeyPairCb);
 export async function deriveKey(publicKee, privateKee, algorithm, keyLength, apu = new Uint8Array(0), apv = new Uint8Array(0)) {
     let publicKey;
     if (isCryptoKey(publicKee)) {
-        checkEncCryptoKey(publicKee, 'ECDH-ES');
+        checkEncCryptoKey(publicKee, 'ECDH');
         publicKey = KeyObject.from(publicKee);
     }
     else if (isKeyObject(publicKee)) {
@@ -23,7 +23,7 @@ export async function deriveKey(publicKee, privateKee, algorithm, keyLength, apu
     }
     let privateKey;
     if (isCryptoKey(privateKee)) {
-        checkEncCryptoKey(privateKee, 'ECDH-ES', 'deriveBits', 'deriveKey');
+        checkEncCryptoKey(privateKee, 'ECDH', 'deriveBits');
         privateKey = KeyObject.from(privateKee);
     }
     else if (isKeyObject(privateKee)) {

package/dist/node/esm/runtime/pbes2kw.js

@@ -24,7 +24,7 @@ function getPassword(key, alg) {
     }
     throw new TypeError(invalidKeyInput(key, ...types, 'Uint8Array'));
 }
-export const encrypt = async (alg, key, cek, p2c = Math.floor(Math.random() * 2049) + 2048, p2s = random(new Uint8Array(16))) => {
+export const encrypt = async (alg, key, cek, p2c = 2048, p2s = random(new Uint8Array(16))) => {
     checkP2s(p2s);
     const salt = concatSalt(alg, p2s);
     const keylen = parseInt(alg.slice(13, 16), 10) >> 3;

package/dist/types/jwe/compact/decrypt.d.ts

@@ -1,5 +1,31 @@
 import type { KeyLike, DecryptOptions, CompactJWEHeaderParameters, GetKeyFunction, FlattenedJWE, CompactDecryptResult, ResolvedKey } from '../../types';
+/**
+ * Interface for Compact JWE Decryption dynamic key resolution.
+ * No token components have been verified at the time of this function call.
+ */
 export interface CompactDecryptGetKey extends GetKeyFunction<CompactJWEHeaderParameters, FlattenedJWE> {
 }
+/**
+ * Decrypts a Compact JWE.
+ *
+ * @param jwe Compact JWE.
+ * @param key Private Key or Secret to decrypt the JWE with.
+ * @param options JWE Decryption options.
+ *
+ * @example Usage
+ * ```js
+ * const jwe = 'eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0.nyQ19eq9ogh9wA7fFtnI2oouzy5_8b5DeLkoRMfi2yijgfTs2zEnayCEofz_qhnL-nwszabd9qUeHv0-IwvhhJJS7GUJOU3ikiIe42qcIAFme1A_Fo9CTxw4XTOy-I5qanl8So91u6hwfyN1VxAqVLsSE7_23EC-gfGEg_5znew9PyXXsOIE-K_HH7IQowRrlZ1X_bM_Liu53RzDpLDvRz59mp3S8L56YqpM8FexFGTGpEaoTcEIst375qncYt3-79IVR7gZN1RWsWgjPatfvVbnh74PglQcATSf3UUhaW0OAKn6q7r3PDx6DIKQ35bgHQg5QopuN00eIfLQL2trGw.W3grIVj5HVuAb76X.6PcuDe5D6ttWFYyv0oqqdDXfI2R8wBg1F2Q80UUA_Gv8eEimNWfxIWdLxrjzgQGSvIhxmFKuLM0.a93_Ug3uZHuczj70Zavx8Q'
+ *
+ * const { plaintext, protectedHeader } = await jose.compactDecrypt(jwe, privateKey)
+ *
+ * console.log(protectedHeader)
+ * console.log(new TextDecoder().decode(plaintext))
+ * ```
+ */
 export declare function compactDecrypt(jwe: string | Uint8Array, key: KeyLike | Uint8Array, options?: DecryptOptions): Promise<CompactDecryptResult>;
+/**
+ * @param jwe Compact JWE.
+ * @param getKey Function resolving Private Key or Secret to decrypt the JWE with.
+ * @param options JWE Decryption options.
+ */
 export declare function compactDecrypt(jwe: string | Uint8Array, getKey: CompactDecryptGetKey, options?: DecryptOptions): Promise<CompactDecryptResult & ResolvedKey>;

package/dist/types/jwe/compact/encrypt.d.ts

@@ -1,10 +1,66 @@
 import type { KeyLike, JWEKeyManagementHeaderParameters, CompactJWEHeaderParameters, EncryptOptions } from '../../types';
+/**
+ * The CompactEncrypt class is a utility for creating Compact JWE strings.
+ *
+ * @example Usage
+ * ```js
+ * const jwe = await new jose.CompactEncrypt(
+ *   new TextEncoder().encode(
+ *     'It’s a dangerous business, Frodo, going out your door.'
+ *   )
+ * )
+ *   .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
+ *   .encrypt(publicKey)
+ *
+ * console.log(jwe)
+ * ```
+ */
 export declare class CompactEncrypt {
     private _flattened;
+    /**
+     * @param plaintext Binary representation of the plaintext to encrypt.
+     */
     constructor(plaintext: Uint8Array);
+    /**
+     * Sets a content encryption key to use, by default a random suitable one
+     * is generated for the JWE enc" (Encryption Algorithm) Header Parameter.
+     *
+     * @param cek JWE Content Encryption Key.
+     *
+     * @deprecated You should not use this method. It is only really intended
+     * for test and vector validation purposes.
+     */
     setContentEncryptionKey(cek: Uint8Array): this;
+    /**
+     * Sets the JWE Initialization Vector to use for content encryption, by default
+     * a random suitable one is generated for the JWE enc" (Encryption Algorithm)
+     * Header Parameter.
+     *
+     * @param iv JWE Initialization Vector.
+     *
+     * @deprecated You should not use this method. It is only really intended
+     * for test and vector validation purposes.
+     */
     setInitializationVector(iv: Uint8Array): this;
+    /**
+     * Sets the JWE Protected Header on the CompactEncrypt object.
+     *
+     * @param protectedHeader JWE Protected Header object.
+     */
     setProtectedHeader(protectedHeader: CompactJWEHeaderParameters): this;
+    /**
+     * Sets the JWE Key Management parameters to be used when encrypting the Content
+     * Encryption Key. You do not need to invoke this method, it is only really
+     * intended for test and vector validation purposes.
+     *
+     * @param parameters JWE Key Management parameters.
+     */
     setKeyManagementParameters(parameters: JWEKeyManagementHeaderParameters): this;
+    /**
+     * Encrypts and resolves the value of the Compact JWE string.
+     *
+     * @param key Public Key or Secret to encrypt the JWE with.
+     * @param options JWE Encryption options.
+     */
     encrypt(key: KeyLike | Uint8Array, options?: EncryptOptions): Promise<string>;
 }

package/dist/types/jwe/flattened/decrypt.d.ts

@@ -1,5 +1,44 @@
 import type { FlattenedDecryptResult, KeyLike, FlattenedJWE, JWEHeaderParameters, DecryptOptions, GetKeyFunction, ResolvedKey } from '../../types';
+/**
+ * Interface for Flattened JWE Decryption dynamic key resolution.
+ * No token components have been verified at the time of this function call.
+ */
 export interface FlattenedDecryptGetKey extends GetKeyFunction<JWEHeaderParameters | undefined, FlattenedJWE> {
 }
+/**
+ * Decrypts a Flattened JWE.
+ *
+ * @param jwe Flattened JWE.
+ * @param key Private Key or Secret to decrypt the JWE with.
+ * @param options JWE Decryption options.
+ *
+ * @example Usage
+ * ```js
+ * const jwe = {
+ *   ciphertext: '9EzjFISUyoG-ifC2mSihfP0DPC80yeyrxhTzKt1C_VJBkxeBG0MI4Te61Pk45RAGubUvBpU9jm4',
+ *   iv: '8Fy7A_IuoX5VXG9s',
+ *   tag: 'W76IYV6arGRuDSaSyWrQNg',
+ *   encrypted_key: 'Z6eD4UK_yFb5ZoKvKkGAdqywEG_m0e4IYo0x8Vf30LAMJcsc-_zSgIeiF82teZyYi2YYduHKoqImk7MRnoPZOlEs0Q5BNK1OgBmSOhCE8DFyqh9Zh48TCTP6lmBQ52naqoUJFMtHzu-0LwZH26hxos0GP3Dt19O379MJB837TdKKa87skq0zHaVLAquRHOBF77GI54Bc7O49d8aOrSu1VEFGMThlW2caspPRiTSePDMDPq7_WGk50izRhB3Asl9wmP9wEeaTrkJKRnQj5ips1SAZ1hDBsqEQKKukxP1HtdcopHV5_qgwU8Hjm5EwSLMluMQuiE6hwlkXGOujZLVizA',
+ *   aad: 'VGhlIEZlbGxvd3NoaXAgb2YgdGhlIFJpbmc',
+ *   protected: 'eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0'
+ * }
+ *
+ * const {
+ *   plaintext,
+ *   protectedHeader,
+ *   additionalAuthenticatedData
+ * } = await jose.flattenedDecrypt(jwe, privateKey)
+ *
+ * console.log(protectedHeader)
+ * const decoder = new TextDecoder()
+ * console.log(decoder.decode(plaintext))
+ * console.log(decoder.decode(additionalAuthenticatedData))
+ * ```
+ */
 export declare function flattenedDecrypt(jwe: FlattenedJWE, key: KeyLike | Uint8Array, options?: DecryptOptions): Promise<FlattenedDecryptResult>;
+/**
+ * @param jwe Flattened JWE.
+ * @param getKey Function resolving Private Key or Secret to decrypt the JWE with.
+ * @param options JWE Decryption options.
+ */
 export declare function flattenedDecrypt(jwe: FlattenedJWE, getKey: FlattenedDecryptGetKey, options?: DecryptOptions): Promise<FlattenedDecryptResult & ResolvedKey>;

package/dist/types/jwe/flattened/encrypt.d.ts

@@ -1,5 +1,26 @@
 import type { KeyLike, FlattenedJWE, JWEHeaderParameters, JWEKeyManagementHeaderParameters, EncryptOptions } from '../../types';
+/**
+ * @private
+ */
 export declare const unprotected: unique symbol;
+/**
+ * The FlattenedEncrypt class is a utility for creating Flattened JWE
+ * objects.
+ *
+ * @example Usage
+ * ```js
+ * const jwe = await new jose.FlattenedEncrypt(
+ *   new TextEncoder().encode(
+ *     'It’s a dangerous business, Frodo, going out your door.'
+ *   )
+ * )
+ *   .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
+ *   .setAdditionalAuthenticatedData(encoder.encode('The Fellowship of the Ring'))
+ *   .encrypt(publicKey)
+ *
+ * console.log(jwe)
+ * ```
+ */
 export declare class FlattenedEncrypt {
     private _plaintext;
     private _protectedHeader;
@@ -9,13 +30,69 @@ export declare class FlattenedEncrypt {
     private _cek;
     private _iv;
     private _keyManagementParameters;
+    /**
+     * @param plaintext Binary representation of the plaintext to encrypt.
+     */
     constructor(plaintext: Uint8Array);
+    /**
+     * Sets the JWE Key Management parameters to be used when encrypting.
+     * Use of this is method is really only needed for ECDH based algorithms
+     * when utilizing the Agreement PartyUInfo or Agreement PartyVInfo parameters.
+     * Other parameters will always be randomly generated when needed and missing.
+     *
+     * @param parameters JWE Key Management parameters.
+     */
     setKeyManagementParameters(parameters: JWEKeyManagementHeaderParameters): this;
+    /**
+     * Sets the JWE Protected Header on the FlattenedEncrypt object.
+     *
+     * @param protectedHeader JWE Protected Header.
+     */
     setProtectedHeader(protectedHeader: JWEHeaderParameters): this;
+    /**
+     * Sets the JWE Shared Unprotected Header on the FlattenedEncrypt object.
+     *
+     * @param sharedUnprotectedHeader JWE Shared Unprotected Header.
+     */
     setSharedUnprotectedHeader(sharedUnprotectedHeader: JWEHeaderParameters): this;
+    /**
+     * Sets the JWE Per-Recipient Unprotected Header on the FlattenedEncrypt object.
+     *
+     * @param unprotectedHeader JWE Per-Recipient Unprotected Header.
+     */
     setUnprotectedHeader(unprotectedHeader: JWEHeaderParameters): this;
+    /**
+     * Sets the Additional Authenticated Data on the FlattenedEncrypt object.
+     *
+     * @param aad Additional Authenticated Data.
+     */
     setAdditionalAuthenticatedData(aad: Uint8Array): this;
+    /**
+     * Sets a content encryption key to use, by default a random suitable one
+     * is generated for the JWE enc" (Encryption Algorithm) Header Parameter.
+     *
+     * @param cek JWE Content Encryption Key.
+     *
+     * @deprecated You should not use this method. It is only really intended
+     * for test and vector validation purposes.
+     */
     setContentEncryptionKey(cek: Uint8Array): this;
+    /**
+     * Sets the JWE Initialization Vector to use for content encryption, by default
+     * a random suitable one is generated for the JWE enc" (Encryption Algorithm)
+     * Header Parameter.
+     *
+     * @param iv JWE Initialization Vector.
+     *
+     * @deprecated You should not use this method. It is only really intended
+     * for test and vector validation purposes.
+     */
     setInitializationVector(iv: Uint8Array): this;
+    /**
+     * Encrypts and resolves the value of the Flattened JWE object.
+     *
+     * @param key Public Key or Secret to encrypt the JWE with.
+     * @param options JWE Encryption options.
+     */
     encrypt(key: KeyLike | Uint8Array, options?: EncryptOptions): Promise<FlattenedJWE>;
 }

package/dist/types/jwe/general/decrypt.d.ts

@@ -1,5 +1,48 @@
 import type { KeyLike, DecryptOptions, JWEHeaderParameters, GetKeyFunction, FlattenedJWE, GeneralJWE, GeneralDecryptResult, ResolvedKey } from '../../types';
+/**
+ * Interface for General JWE Decryption dynamic key resolution.
+ * No token components have been verified at the time of this function call.
+ */
 export interface GeneralDecryptGetKey extends GetKeyFunction<JWEHeaderParameters, FlattenedJWE> {
 }
+/**
+ * Decrypts a General JWE.
+ *
+ * @param jwe General JWE.
+ * @param key Private Key or Secret to decrypt the JWE with.
+ * @param options JWE Decryption options.
+ *
+ * @example Usage
+ * ```js
+ * const jwe = {
+ *   ciphertext: '9EzjFISUyoG-ifC2mSihfP0DPC80yeyrxhTzKt1C_VJBkxeBG0MI4Te61Pk45RAGubUvBpU9jm4',
+ *   iv: '8Fy7A_IuoX5VXG9s',
+ *   tag: 'W76IYV6arGRuDSaSyWrQNg',
+ *   aad: 'VGhlIEZlbGxvd3NoaXAgb2YgdGhlIFJpbmc',
+ *   protected: 'eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0',
+ *   recipients: [
+ *     {
+ *       encrypted_key: 'Z6eD4UK_yFb5ZoKvKkGAdqywEG_m0e4IYo0x8Vf30LAMJcsc-_zSgIeiF82teZyYi2YYduHKoqImk7MRnoPZOlEs0Q5BNK1OgBmSOhCE8DFyqh9Zh48TCTP6lmBQ52naqoUJFMtHzu-0LwZH26hxos0GP3Dt19O379MJB837TdKKa87skq0zHaVLAquRHOBF77GI54Bc7O49d8aOrSu1VEFGMThlW2caspPRiTSePDMDPq7_WGk50izRhB3Asl9wmP9wEeaTrkJKRnQj5ips1SAZ1hDBsqEQKKukxP1HtdcopHV5_qgwU8Hjm5EwSLMluMQuiE6hwlkXGOujZLVizA'
+ *     }
+ *   ]
+ * }
+ *
+ * const {
+ *   plaintext,
+ *   protectedHeader,
+ *   additionalAuthenticatedData
+ * } = await jose.generalDecrypt(jwe, privateKey)
+ *
+ * console.log(protectedHeader)
+ * const decoder = new TextDecoder()
+ * console.log(decoder.decode(plaintext))
+ * console.log(decoder.decode(additionalAuthenticatedData))
+ * ```
+ */
 export declare function generalDecrypt(jwe: GeneralJWE, key: KeyLike | Uint8Array, options?: DecryptOptions): Promise<GeneralDecryptResult>;
+/**
+ * @param jwe General JWE.
+ * @param getKey Function resolving Private Key or Secret to decrypt the JWE with.
+ * @param options JWE Decryption options.
+ */
 export declare function generalDecrypt(jwe: GeneralJWE, getKey: GeneralDecryptGetKey, options?: DecryptOptions): Promise<GeneralDecryptResult & ResolvedKey>;