jose 4.13.1 → 4.14.0

package/README.md

@@ -1,31 +1,19 @@
 # jose
 
-> "JSON Web Almost Everything" - JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes.
-
-## Implemented specs & features
-
-The following specifications are implemented by `jose`
-
-- JSON Web Signature (JWS) - [RFC7515][spec-jws]
-- JSON Web Encryption (JWE) - [RFC7516][spec-jwe]
-- JSON Web Key (JWK) - [RFC7517][spec-jwk]
-- JSON Web Algorithms (JWA) - [RFC7518][spec-jwa]
-- JSON Web Token (JWT) - [RFC7519][spec-jwt]
-- JSON Web Key Thumbprint - [RFC7638][spec-thumbprint]
-- JSON Web Key Thumbprint URI - [RFC9278][spec-thumbprint-uri]
-- JWS Unencoded Payload Option - [RFC7797][spec-b64]
-- CFRG Elliptic Curve ECDH and Signatures - [RFC8037][spec-okp]
-- secp256k1 EC Key curve support - [JOSE Registrations for WebAuthn Algorithms][spec-secp256k1]
-
-The test suite utilizes examples defined in [RFC7520][spec-cookbook] to confirm its JOSE
-implementation is correct.
+`jose` is JavaScript module for JSON Object Signing and Encryption, providing support for JSON Web Tokens (JWT), JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), JSON Web Key Set (JWKS), and more. The module is designed to work across various Web-interoperable runtimes including Node.js, browsers, Cloudflare Workers, Deno, Bun, and others.
 
 ## [💗 Help the project](https://github.com/sponsors/panva)
 
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
 ## Dependencies: 0
 
+`jose` has no dependencies and it exports tree-shakeable ESM. CJS is also supported.
+
 ## Documentation
 
+`jose` is distributed via [npmjs.com](https://www.npmjs.com/package/jose), [deno.land/x](https://deno.land/x/jose), [cdnjs.com](https://cdnjs.com/libraries/jose), [jsdelivr.com](https://www.jsdelivr.com/package/npm/jose), and [github.com](https://github.com/panva/jose).
+
 **`example`** ESM import
 ```js
 import * as jose from 'jose'
@@ -36,53 +24,96 @@ import * as jose from 'jose'
 const jose = require('jose')
 ```
 
-**`example`** Deno import
-```js
-import * as jose from 'https://deno.land/x/jose@v4.13.1/index.ts'
-```
+### JSON Web Tokens (JWT)
+
+The `jose` module supports JSON Web Tokens (JWT) and provides functionality for signing and verifying tokens, as well as their JWT Claims Set validation.
+
+- [Signing](docs/classes/jwt_sign.SignJWT.md) using the `SignJWT` class
+- [Verification & JWT Claims Set Validation](docs/functions/jwt_verify.jwtVerify.md) using the `jwtVerify` function
+  - [Using a remote JWKS](docs/functions/jwks_remote.createRemoteJWKSet.md)
+  - [Using a local JWKS](docs/functions/jwks_local.createLocalJWKSet.md)
+- Utility functions
+  - [Decoding Token's Protected Header](docs/functions/util_decode_protected_header.decodeProtectedHeader.md)
+  - [Decoding JWT Claims Set](docs/functions/util_decode_jwt.decodeJwt.md) prior to its validation
+
+### Encrypted JSON Web Tokens
+
+The `jose` module supports encrypted JSON Web Tokens and provides functionality for encrypting and decrypting tokens, as well as their JWT Claims Set validation.
+
+- [Encryption](docs/classes/jwt_encrypt.EncryptJWT.md) using the `EncryptJWT` class
+- [Decryption & JWT Claims Set Validation](docs/functions/jwt_decrypt.jwtDecrypt.md) using the `jwtDecrypt` function
+- Utility functions
+  - [Decoding Token's Protected Header](docs/functions/util_decode_protected_header.decodeProtectedHeader.md)
+
+### Key Utilities
+
+The `jose` module provides functionality for importing, exporting, and generating keys and secrets in various formats, including PEM formats like SPKI, X.509 certificate, and PKCS #8, as well as JSON Web Key (JWK).
+
+- Key Import Functions
+  - [JWK Import](docs/functions/key_import.importJWK.md)
+  - [Public Key Import (SPKI)](docs/functions/key_import.importSPKI.md)
+  - [Public Key Import (X.509 Certificate)](docs/functions/key_import.importX509.md)
+  - [Private Key Import (PKCS #8)](docs/functions/key_import.importPKCS8.md)
+- Key and Secret Generation Functions
+  - [Asymmetric Key Pair Generation](docs/functions/key_generate_key_pair.generateKeyPair.md)
+  - [Symmetric Secret Generation](docs/functions/key_generate_secret.generateSecret.md)
+- Key Export Functions
+  - [JWK Export](docs/functions/key_export.exportJWK.md)
+  - [Private Key Export](docs/functions/key_export.exportPKCS8.md)
+  - [Public Key Export](docs/functions/key_export.exportSPKI.md)
+
+### JSON Web Signature (JWS)
 
-- JSON Web Tokens (JWT)
-  - [Signing](docs/classes/jwt_sign.SignJWT.md#readme)
-  - [Verification & JWT Claims Set Validation](docs/functions/jwt_verify.jwtVerify.md#readme)
-  - Encrypted JSON Web Tokens
-    - [Encryption](docs/classes/jwt_encrypt.EncryptJWT.md#readme)
-    - [Decryption & JWT Claims Set Validation](docs/functions/jwt_decrypt.jwtDecrypt.md#readme)
-- Key Import
-  - [JWK Import](docs/functions/key_import.importJWK.md#readme)
-  - [Public Key Import (SPKI)](docs/functions/key_import.importSPKI.md#readme)
-  - [Public Key Import (X.509 Certificate)](docs/functions/key_import.importX509.md#readme)
-  - [Private Key Import (PKCS #8)](docs/functions/key_import.importPKCS8.md#readme)
-- JSON Web Encryption (JWE)
-  - Encryption - [Compact](docs/classes/jwe_compact_encrypt.CompactEncrypt.md#readme), [Flattened](docs/classes/jwe_flattened_encrypt.FlattenedEncrypt.md#readme), [General](docs/classes/jwe_general_encrypt.GeneralEncrypt.md#readme)
-  - Decryption - [Compact](docs/functions/jwe_compact_decrypt.compactDecrypt.md#readme), [Flattened](docs/functions/jwe_flattened_decrypt.flattenedDecrypt.md#readme), [General](docs/functions/jwe_general_decrypt.generalDecrypt.md#readme)
-- JSON Web Signature (JWS)
-  - Signing - [Compact](docs/classes/jws_compact_sign.CompactSign.md#readme), [Flattened](docs/classes/jws_flattened_sign.FlattenedSign.md#readme), [General](docs/classes/jws_general_sign.GeneralSign.md#readme)
-  - Verification - [Compact](docs/functions/jws_compact_verify.compactVerify.md#readme), [Flattened](docs/functions/jws_flattened_verify.flattenedVerify.md#readme), [General](docs/functions/jws_general_verify.generalVerify.md#readme)
-- JSON Web Key (JWK)
-  - [Calculating JWK Thumbprint](docs/functions/jwk_thumbprint.calculateJwkThumbprint.md#readme)
-  - [Calculating JWK Thumbprint URI](docs/functions/jwk_thumbprint.calculateJwkThumbprintUri.md#readme)
-  - [Verification using a JWK Embedded in a JWS Header](docs/functions/jwk_embedded.EmbeddedJWK.md#readme)
-- JSON Web Key Set (JWKS)
-  - [Verify using a local JWKSet](docs/functions/jwks_local.createLocalJWKSet.md#readme)
-  - [Verify using a remote JWKSet](docs/functions/jwks_remote.createRemoteJWKSet.md#readme)
-- Key Pair or Secret Generation
-  - [Asymmetric Key Pair Generation](docs/functions/key_generate_key_pair.generateKeyPair.md#readme)
-  - [Symmetric Secret Generation](docs/functions/key_generate_secret.generateSecret.md#readme)
-- Key Export
-  - [JWK Export](docs/functions/key_export.exportJWK.md#readme)
-  - [Private Key Export](docs/functions/key_export.exportPKCS8.md#readme)
-  - [Public Key Export](docs/functions/key_export.exportSPKI.md#readme)
-- Utilities
-  - [Decoding Token's Protected Header](docs/functions/util_decode_protected_header.decodeProtectedHeader.md#readme)
-  - [Decoding JWT Claims Set](docs/functions/util_decode_jwt.decodeJwt.md#readme)
-- [Unsecured JWT](docs/classes/jwt_unsecured.UnsecuredJWT.md#readme)
-- [JOSE Errors](docs/modules/util_errors.md#readme)
+The `jose` modules supports signing and verification of JWS messages with arbitrary payloads in Compact, Flattened JSON, and General JSON serialization syntaxes.
+
+- Signing - [Compact](docs/classes/jws_compact_sign.CompactSign.md), [Flattened JSON](docs/classes/jws_flattened_sign.FlattenedSign.md), [General JSON](docs/classes/jws_general_sign.GeneralSign.md)
+- Verification - [Compact](docs/functions/jws_compact_verify.compactVerify.md), [Flattened JSON](docs/functions/jws_flattened_verify.flattenedVerify.md), [General JSON](docs/functions/jws_general_verify.generalVerify.md)
+  - [Verify using a remote JWKS](docs/functions/jwks_remote.createRemoteJWKSet.md)
+  - [Verify using a local JWKS](docs/functions/jwks_local.createLocalJWKSet.md)
+- Utility functions
+  - [Decoding Token's Protected Header](docs/functions/util_decode_protected_header.decodeProtectedHeader.md)
+
+### JSON Web Encryption (JWE)
+
+The `jose` modules supports encryption and decryption of JWE messages with arbitrary plaintext in Compact, Flattened JSON, and General JSON serialization syntaxes.
+
+- Encryption - [Compact](docs/classes/jwe_compact_encrypt.CompactEncrypt.md), [Flattened JSON](docs/classes/jwe_flattened_encrypt.FlattenedEncrypt.md), [General JSON](docs/classes/jwe_general_encrypt.GeneralEncrypt.md)
+- Decryption - [Compact](docs/functions/jwe_compact_decrypt.compactDecrypt.md), [Flattened JSON](docs/functions/jwe_flattened_decrypt.flattenedDecrypt.md), [General JSON](docs/functions/jwe_general_decrypt.generalDecrypt.md)
+- Utility functions
+  - [Decoding Token's Protected Header](docs/functions/util_decode_protected_header.decodeProtectedHeader.md)
+
+### Other
+
+The following are additional features and utilities provided by the `jose` module:
+
+- [Calculating JWK Thumbprint](docs/functions/jwk_thumbprint.calculateJwkThumbprint.md)
+- [Calculating JWK Thumbprint URI](docs/functions/jwk_thumbprint.calculateJwkThumbprintUri.md)
+- [Verification using a JWK Embedded in a JWS Header](docs/functions/jwk_embedded.EmbeddedJWK.md)
+- [Unsecured JWT](docs/classes/jwt_unsecured.UnsecuredJWT.md)
+- [JOSE Errors](docs/modules/util_errors.md)
+
+## Implemented specifications
+
+The `jose` module implements the following specifications:
+
+- JSON Web Signature (JWS) - [RFC7515](https://www.rfc-editor.org/rfc/rfc7515)
+- JSON Web Encryption (JWE) - [RFC7516](https://www.rfc-editor.org/rfc/rfc7516)
+- JSON Web Key (JWK) - [RFC7517](https://www.rfc-editor.org/rfc/rfc7517)
+- JSON Web Algorithms (JWA) - [RFC7518](https://www.rfc-editor.org/rfc/rfc7518)
+- JSON Web Token (JWT) - [RFC7519](https://www.rfc-editor.org/rfc/rfc7519)
+- JSON Web Key Thumbprint - [RFC7638](https://www.rfc-editor.org/rfc/rfc7638)
+- JSON Web Key Thumbprint URI - [RFC9278](https://www.rfc-editor.org/rfc/rfc9278)
+- JWS Unencoded Payload Option - [RFC7797](https://www.rfc-editor.org/rfc/rfc7797)
+- CFRG Elliptic Curve ECDH and Signatures - [RFC8037](https://www.rfc-editor.org/rfc/rfc8037)
+- secp256k1 EC Key curve support - [RFC8812](https://www.rfc-editor.org/rfc/rfc8812)
+
+The algorithm implementations have been tested using test vectors from their respective specifications as well as [RFC7520](https://www.rfc-editor.org/rfc/rfc7520).
 
 ## Supported Runtimes
 
-The supported JavaScript runtimes include ones that support the utilized Web API globals and standard built-in objects or are Node.js
+The `jose` module is compatible with JavaScript runtimes that support the utilized Web API globals and standard built-in objects or are Node.js.
 
-These are _(this is not an exhaustive list)_:
+The following runtimes are supported _(this is not an exhaustive list)_:
 - [Bun](https://github.com/panva/jose/issues/471)
 - [Browsers](https://github.com/panva/jose/issues/263)
 - [Cloudflare Workers](https://github.com/panva/jose/issues/265)
@@ -91,36 +122,11 @@ These are _(this is not an exhaustive list)_:
 - [Node.js](https://github.com/panva/jose/issues/262)
 - [Vercel's Edge Runtime](https://github.com/panva/jose/issues/301)
 
-## FAQ
+Please note that certain algorithms may not be available depending on the runtime used. You can find a list of available algorithms for each runtime in the specific issue links provided above.
 
-#### Supported Versions
+## Supported Versions
 
 | Version | Security Fixes 🔑 | Other Bug Fixes 🐞 | New Features ⭐ |
 | ------- | --------- | -------- | -------- |
 | [v4.x](https://github.com/panva/jose/tree/v4.x) | ✅ | ✅ | ✅ |
 | [v3.x](https://github.com/panva/jose/tree/v3.x), [v2.x](https://github.com/panva/jose/tree/v2.x), [v1.x](https://github.com/panva/jose/tree/v1.x) | ✅ | ❌ | ❌ |
-
-#### Uint8Array?!
-
-- Whenever `Uint8Array` is a valid input, so is [`Buffer`](https://nodejs.org/api/buffer.html#buffer_buffer) since buffers are instances of Uint8Array.
-- Whenever `Uint8Array` is returned and you want a `Buffer` instead, use `Buffer.from(uint8array)`.
-
-#### Bundle Size, Package Size, Tree Shaking
-
-Yes the bundle size is on the larger side, that is because each module is actually published 
-multiple times so that it can remain truly without dependencies and be universal / isomorphic.
-
-Nevertheless, since each module can be required independently and is fully tree-shakeable, the
-install size should not be a cause for concern.
-
-[spec-b64]: https://www.rfc-editor.org/rfc/rfc7797
-[spec-cookbook]: https://www.rfc-editor.org/rfc/rfc7520
-[spec-jwa]: https://www.rfc-editor.org/rfc/rfc7518
-[spec-jwe]: https://www.rfc-editor.org/rfc/rfc7516
-[spec-jwk]: https://www.rfc-editor.org/rfc/rfc7517
-[spec-jws]: https://www.rfc-editor.org/rfc/rfc7515
-[spec-jwt]: https://www.rfc-editor.org/rfc/rfc7519
-[spec-okp]: https://www.rfc-editor.org/rfc/rfc8037
-[spec-secp256k1]: https://www.rfc-editor.org/rfc/rfc8812
-[spec-thumbprint]: https://www.rfc-editor.org/rfc/rfc7638
-[spec-thumbprint-uri]: https://www.rfc-editor.org/rfc/rfc9278

package/dist/browser/jws/general/sign.js

@@ -58,7 +58,7 @@ export class GeneralSign {
                 jws.payload = payload;
             }
             else if (jws.payload !== payload) {
-                throw new JWSInvalid('inconsistent use of JWS Unencoded Payload Option (RFC7797)');
+                throw new JWSInvalid('inconsistent use of JWS Unencoded Payload (RFC7797)');
             }
             jws.signatures.push(rest);
         }

package/dist/browser/lib/jwt_claims_set.js

@@ -29,15 +29,26 @@ export default (protectedHeader, encodedPayload, options = {}) => {
     if (!isObject(payload)) {
         throw new JWTInvalid('JWT Claims Set must be a top-level JSON object');
     }
-    const { issuer } = options;
+    const { requiredClaims = [], issuer, subject, audience, maxTokenAge } = options;
+    if (maxTokenAge !== undefined)
+        requiredClaims.push('iat');
+    if (audience !== undefined)
+        requiredClaims.push('aud');
+    if (subject !== undefined)
+        requiredClaims.push('sub');
+    if (issuer !== undefined)
+        requiredClaims.push('iss');
+    for (const claim of new Set(requiredClaims.reverse())) {
+        if (!(claim in payload)) {
+            throw new JWTClaimValidationFailed(`missing required "${claim}" claim`, claim, 'missing');
+        }
+    }
     if (issuer && !(Array.isArray(issuer) ? issuer : [issuer]).includes(payload.iss)) {
         throw new JWTClaimValidationFailed('unexpected "iss" claim value', 'iss', 'check_failed');
     }
-    const { subject } = options;
     if (subject && payload.sub !== subject) {
         throw new JWTClaimValidationFailed('unexpected "sub" claim value', 'sub', 'check_failed');
     }
-    const { audience } = options;
     if (audience &&
         !checkAudiencePresence(payload.aud, typeof audience === 'string' ? [audience] : audience)) {
         throw new JWTClaimValidationFailed('unexpected "aud" claim value', 'aud', 'check_failed');
@@ -58,7 +69,7 @@ export default (protectedHeader, encodedPayload, options = {}) => {
     }
     const { currentDate } = options;
     const now = epoch(currentDate || new Date());
-    if ((payload.iat !== undefined || options.maxTokenAge) && typeof payload.iat !== 'number') {
+    if ((payload.iat !== undefined || maxTokenAge) && typeof payload.iat !== 'number') {
         throw new JWTClaimValidationFailed('"iat" claim must be a number', 'iat', 'invalid');
     }
     if (payload.nbf !== undefined) {
@@ -77,9 +88,9 @@ export default (protectedHeader, encodedPayload, options = {}) => {
             throw new JWTExpired('"exp" claim timestamp check failed', 'exp', 'check_failed');
         }
     }
-    if (options.maxTokenAge) {
+    if (maxTokenAge) {
         const age = now - payload.iat;
-        const max = typeof options.maxTokenAge === 'number' ? options.maxTokenAge : secs(options.maxTokenAge);
+        const max = typeof maxTokenAge === 'number' ? maxTokenAge : secs(maxTokenAge);
         if (age - tolerance > max) {
             throw new JWTExpired('"iat" claim timestamp check failed (too far in the past)', 'iat', 'check_failed');
         }

package/dist/node/cjs/jws/general/sign.js

@@ -61,7 +61,7 @@ class GeneralSign {
                 jws.payload = payload;
             }
             else if (jws.payload !== payload) {
-                throw new errors_js_1.JWSInvalid('inconsistent use of JWS Unencoded Payload Option (RFC7797)');
+                throw new errors_js_1.JWSInvalid('inconsistent use of JWS Unencoded Payload (RFC7797)');
             }
             jws.signatures.push(rest);
         }

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

@@ -31,15 +31,26 @@ exports.default = (protectedHeader, encodedPayload, options = {}) => {
     if (!(0, is_object_js_1.default)(payload)) {
         throw new errors_js_1.JWTInvalid('JWT Claims Set must be a top-level JSON object');
     }
-    const { issuer } = options;
+    const { requiredClaims = [], issuer, subject, audience, maxTokenAge } = options;
+    if (maxTokenAge !== undefined)
+        requiredClaims.push('iat');
+    if (audience !== undefined)
+        requiredClaims.push('aud');
+    if (subject !== undefined)
+        requiredClaims.push('sub');
+    if (issuer !== undefined)
+        requiredClaims.push('iss');
+    for (const claim of new Set(requiredClaims.reverse())) {
+        if (!(claim in payload)) {
+            throw new errors_js_1.JWTClaimValidationFailed(`missing required "${claim}" claim`, claim, 'missing');
+        }
+    }
     if (issuer && !(Array.isArray(issuer) ? issuer : [issuer]).includes(payload.iss)) {
         throw new errors_js_1.JWTClaimValidationFailed('unexpected "iss" claim value', 'iss', 'check_failed');
     }
-    const { subject } = options;
     if (subject && payload.sub !== subject) {
         throw new errors_js_1.JWTClaimValidationFailed('unexpected "sub" claim value', 'sub', 'check_failed');
     }
-    const { audience } = options;
     if (audience &&
         !checkAudiencePresence(payload.aud, typeof audience === 'string' ? [audience] : audience)) {
         throw new errors_js_1.JWTClaimValidationFailed('unexpected "aud" claim value', 'aud', 'check_failed');
@@ -60,7 +71,7 @@ exports.default = (protectedHeader, encodedPayload, options = {}) => {
     }
     const { currentDate } = options;
     const now = (0, epoch_js_1.default)(currentDate || new Date());
-    if ((payload.iat !== undefined || options.maxTokenAge) && typeof payload.iat !== 'number') {
+    if ((payload.iat !== undefined || maxTokenAge) && typeof payload.iat !== 'number') {
         throw new errors_js_1.JWTClaimValidationFailed('"iat" claim must be a number', 'iat', 'invalid');
     }
     if (payload.nbf !== undefined) {
@@ -79,9 +90,9 @@ exports.default = (protectedHeader, encodedPayload, options = {}) => {
             throw new errors_js_1.JWTExpired('"exp" claim timestamp check failed', 'exp', 'check_failed');
         }
     }
-    if (options.maxTokenAge) {
+    if (maxTokenAge) {
         const age = now - payload.iat;
-        const max = typeof options.maxTokenAge === 'number' ? options.maxTokenAge : (0, secs_js_1.default)(options.maxTokenAge);
+        const max = typeof maxTokenAge === 'number' ? maxTokenAge : (0, secs_js_1.default)(maxTokenAge);
         if (age - tolerance > max) {
             throw new errors_js_1.JWTExpired('"iat" claim timestamp check failed (too far in the past)', 'iat', 'check_failed');
         }

package/dist/node/esm/jws/general/sign.js

@@ -58,7 +58,7 @@ export class GeneralSign {
                 jws.payload = payload;
             }
             else if (jws.payload !== payload) {
-                throw new JWSInvalid('inconsistent use of JWS Unencoded Payload Option (RFC7797)');
+                throw new JWSInvalid('inconsistent use of JWS Unencoded Payload (RFC7797)');
             }
             jws.signatures.push(rest);
         }

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

@@ -29,15 +29,26 @@ export default (protectedHeader, encodedPayload, options = {}) => {
     if (!isObject(payload)) {
         throw new JWTInvalid('JWT Claims Set must be a top-level JSON object');
     }
-    const { issuer } = options;
+    const { requiredClaims = [], issuer, subject, audience, maxTokenAge } = options;
+    if (maxTokenAge !== undefined)
+        requiredClaims.push('iat');
+    if (audience !== undefined)
+        requiredClaims.push('aud');
+    if (subject !== undefined)
+        requiredClaims.push('sub');
+    if (issuer !== undefined)
+        requiredClaims.push('iss');
+    for (const claim of new Set(requiredClaims.reverse())) {
+        if (!(claim in payload)) {
+            throw new JWTClaimValidationFailed(`missing required "${claim}" claim`, claim, 'missing');
+        }
+    }
     if (issuer && !(Array.isArray(issuer) ? issuer : [issuer]).includes(payload.iss)) {
         throw new JWTClaimValidationFailed('unexpected "iss" claim value', 'iss', 'check_failed');
     }
-    const { subject } = options;
     if (subject && payload.sub !== subject) {
         throw new JWTClaimValidationFailed('unexpected "sub" claim value', 'sub', 'check_failed');
     }
-    const { audience } = options;
     if (audience &&
         !checkAudiencePresence(payload.aud, typeof audience === 'string' ? [audience] : audience)) {
         throw new JWTClaimValidationFailed('unexpected "aud" claim value', 'aud', 'check_failed');
@@ -58,7 +69,7 @@ export default (protectedHeader, encodedPayload, options = {}) => {
     }
     const { currentDate } = options;
     const now = epoch(currentDate || new Date());
-    if ((payload.iat !== undefined || options.maxTokenAge) && typeof payload.iat !== 'number') {
+    if ((payload.iat !== undefined || maxTokenAge) && typeof payload.iat !== 'number') {
         throw new JWTClaimValidationFailed('"iat" claim must be a number', 'iat', 'invalid');
     }
     if (payload.nbf !== undefined) {
@@ -77,9 +88,9 @@ export default (protectedHeader, encodedPayload, options = {}) => {
             throw new JWTExpired('"exp" claim timestamp check failed', 'exp', 'check_failed');
         }
     }
-    if (options.maxTokenAge) {
+    if (maxTokenAge) {
         const age = now - payload.iat;
-        const max = typeof options.maxTokenAge === 'number' ? options.maxTokenAge : secs(options.maxTokenAge);
+        const max = typeof maxTokenAge === 'number' ? maxTokenAge : secs(maxTokenAge);
         if (age - tolerance > max) {
             throw new JWTExpired('"iat" claim timestamp check failed (too far in the past)', 'iat', 'check_failed');
         }

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

@@ -8,26 +8,16 @@ export interface CompactDecryptGetKey extends GetKeyFunction<CompactJWEHeaderPar
 /**
  * Decrypts a Compact JWE.
  *
- * @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))
- * ```
- *
  * @param jwe Compact JWE.
- * @param key Private Key or Secret to decrypt the JWE with.
+ * @param key Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
 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 getKey Function resolving Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
 export declare function compactDecrypt<T extends KeyLike = KeyLike>(jwe: string | Uint8Array, getKey: CompactDecryptGetKey, options?: DecryptOptions): Promise<CompactDecryptResult & ResolvedKey<T>>;

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

@@ -1,18 +1,7 @@
 import type { KeyLike, JWEKeyManagementHeaderParameters, CompactJWEHeaderParameters, EncryptOptions } from '../../types';
 /**
- * The CompactEncrypt class is a utility for creating Compact JWE strings.
+ * The CompactEncrypt class is used to build and encrypt 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;
@@ -53,7 +42,8 @@ export declare class CompactEncrypt {
     /**
      * Encrypts and resolves the value of the Compact JWE string.
      *
-     * @param key Public Key or Secret to encrypt the JWE with.
+     * @param key Public Key or Secret to encrypt the JWE with. See
+     *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      * @param options JWE Encryption options.
      */
     encrypt(key: KeyLike | Uint8Array, options?: EncryptOptions): Promise<string>;

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

@@ -8,36 +8,16 @@ export interface FlattenedDecryptGetKey extends GetKeyFunction<JWEHeaderParamete
 /**
  * Decrypts a Flattened JWE.
  *
- * @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))
- * ```
- *
  * @param jwe Flattened JWE.
- * @param key Private Key or Secret to decrypt the JWE with.
+ * @param key Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
 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 getKey Function resolving Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
 export declare function flattenedDecrypt<T extends KeyLike = KeyLike>(jwe: FlattenedJWE, getKey: FlattenedDecryptGetKey, options?: DecryptOptions): Promise<FlattenedDecryptResult & ResolvedKey<T>>;

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

@@ -2,20 +2,8 @@ import type { KeyLike, FlattenedJWE, JWEHeaderParameters, JWEKeyManagementHeader
 /** @private */
 export declare const unprotected: unique symbol;
 /**
- * The FlattenedEncrypt class is a utility for creating Flattened JWE objects.
+ * The FlattenedEncrypt class is used to build and encrypt 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;
@@ -82,7 +70,8 @@ export declare class FlattenedEncrypt {
     /**
      * Encrypts and resolves the value of the Flattened JWE object.
      *
-     * @param key Public Key or Secret to encrypt the JWE with.
+     * @param key Public Key or Secret to encrypt the JWE with. See
+     *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      * @param options JWE Encryption options.
      */
     encrypt(key: KeyLike | Uint8Array, options?: EncryptOptions): Promise<FlattenedJWE>;

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

@@ -8,40 +8,16 @@ export interface GeneralDecryptGetKey extends GetKeyFunction<JWEHeaderParameters
 /**
  * Decrypts a General JWE.
  *
- * @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))
- * ```
- *
  * @param jwe General JWE.
- * @param key Private Key or Secret to decrypt the JWE with.
+ * @param key Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
 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 getKey Function resolving Private Key or Secret to decrypt the JWE with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWE Decryption options.
  */
 export declare function generalDecrypt<T extends KeyLike = KeyLike>(jwe: GeneralJWE, getKey: GeneralDecryptGetKey, options?: DecryptOptions): Promise<GeneralDecryptResult & ResolvedKey<T>>;

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

@@ -14,23 +14,8 @@ export interface Recipient {
     done(): GeneralEncrypt;
 }
 /**
- * The GeneralEncrypt class is a utility for creating General JWE objects.
+ * The GeneralEncrypt class is used to build and encrypt General JWE objects.
  *
- * @example Usage
- *
- * ```js
- * const jwe = await new jose.GeneralEncrypt(
- *   new TextEncoder().encode('It’s a dangerous business, Frodo, going out your door.'),
- * )
- *   .setProtectedHeader({ enc: 'A256GCM' })
- *   .addRecipient(ecPublicKey)
- *   .setUnprotectedHeader({ alg: 'ECDH-ES+A256KW' })
- *   .addRecipient(rsaPublicKey)
- *   .setUnprotectedHeader({ alg: 'RSA-OAEP-384' })
- *   .encrypt()
- *
- * console.log(jwe)
- * ```
  */
 export declare class GeneralEncrypt {
     private _plaintext;
@@ -44,6 +29,7 @@ export declare class GeneralEncrypt {
      * Adds an additional recipient for the General JWE object.
      *
      * @param key Public Key or Secret to encrypt the Content Encryption Key for the recipient with.
+     *   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;

package/dist/types/jwk/embedded.d.ts

@@ -5,19 +5,5 @@ import type { KeyLike, FlattenedJWSInput, JWSHeaderParameters } from '../types';
  * token's "jwk" (JSON Web Key) Header Parameter. It is recommended to combine this with the verify
  * function's `algorithms` option to define accepted JWS "alg" (Algorithm) Header Parameter values.
  *
- * @example Usage
- *
- * ```js
- * const jwt =
- *   'eyJqd2siOnsiY3J2IjoiUC0yNTYiLCJ4IjoiVU05ZzVuS25aWFlvdldBbE03NmNMejl2VG96UmpfX0NIVV9kT2wtZ09vRSIsInkiOiJkczhhZVF3MWwyY0RDQTdiQ2tPTnZ3REtwWEFidFhqdnFDbGVZSDhXc19VIiwia3R5IjoiRUMifSwiYWxnIjoiRVMyNTYifQ.eyJpc3MiOiJ1cm46ZXhhbXBsZTppc3N1ZXIiLCJhdWQiOiJ1cm46ZXhhbXBsZTphdWRpZW5jZSIsImlhdCI6MTYwNDU4MDc5NH0.60boak3_dErnW47ZPty1C0nrjeVq86EN_eK0GOq6K8w2OA0thKoBxFK4j-NuU9yZ_A9UKGxPT_G87DladBaV9g'
- *
- * const { payload, protectedHeader } = await jose.jwtVerify(jwt, jose.EmbeddedJWK, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- *
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
  */
 export declare function EmbeddedJWK<T extends KeyLike = KeyLike>(protectedHeader?: JWSHeaderParameters, token?: FlattenedJWSInput): Promise<T>;