jose 4.13.0 → 4.13.2

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

@@ -2,46 +2,18 @@ import type { JWK } from '../types';
 /**
  * Calculates a base64url-encoded JSON Web Key (JWK) Thumbprint
  *
- * @example Usage
- *
- * ```js
- * const thumbprint = await jose.calculateJwkThumbprint({
- *   kty: 'EC',
- *   crv: 'P-256',
- *   x: 'jJ6Flys3zK9jUhnOHf6G49Dyp5hah6CNP84-gY-n9eo',
- *   y: 'nhI6iD5eFXgBTLt_1p3aip-5VbZeMhxeFSpjfEAf7Ww',
- * })
- *
- * console.log(thumbprint)
- * // 'w9eYdC6_s_tLQ8lH6PUpc0mddazaqtPgeC2IgWDiqY8'
- * ```
- *
  * @param jwk JSON Web Key.
  * @param digestAlgorithm Digest Algorithm to use for calculating the thumbprint. Default is
  *   "sha256".
- * @see [RFC7638](https://www.rfc-editor.org/rfc/rfc7638)
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7638 RFC7638}
  */
 export declare function calculateJwkThumbprint(jwk: JWK, digestAlgorithm?: 'sha256' | 'sha384' | 'sha512'): Promise<string>;
 /**
  * Calculates a JSON Web Key (JWK) Thumbprint URI
  *
- * @example Usage
- *
- * ```js
- * const thumbprintUri = await jose.calculateJwkThumbprintUri({
- *   kty: 'EC',
- *   crv: 'P-256',
- *   x: 'jJ6Flys3zK9jUhnOHf6G49Dyp5hah6CNP84-gY-n9eo',
- *   y: 'nhI6iD5eFXgBTLt_1p3aip-5VbZeMhxeFSpjfEAf7Ww',
- * })
- *
- * console.log(thumbprint)
- * // 'urn:ietf:params:oauth:jwk-thumbprint:sha-256:w9eYdC6_s_tLQ8lH6PUpc0mddazaqtPgeC2IgWDiqY8'
- * ```
- *
  * @param jwk JSON Web Key.
  * @param digestAlgorithm Digest Algorithm to use for calculating the thumbprint. Default is
  *   "sha256".
- * @see [RFC9278](https://www.rfc-editor.org/rfc/rfc9278)
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9278 RFC9278}
  */
 export declare function calculateJwkThumbprintUri(jwk: JWK, digestAlgorithm?: 'sha256' | 'sha384' | 'sha512'): Promise<string>;

package/dist/types/jwks/local.d.ts

@@ -21,65 +21,6 @@ export declare class LocalJWKSet<T extends KeyLike = KeyLike> {
  * multiple keys get matched it is possible to opt-in to iterate over the matched keys and attempt
  * verification in an iterative manner.
  *
- * @example Usage
- *
- * ```js
- * const JWKS = jose.createLocalJWKSet({
- *   keys: [
- *     {
- *       kty: 'RSA',
- *       e: 'AQAB',
- *       n: '12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ',
- *       alg: 'PS256',
- *     },
- *     {
- *       crv: 'P-256',
- *       kty: 'EC',
- *       x: 'ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw',
- *       y: '_LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo',
- *       alg: 'ES256',
- *     },
- *   ],
- * })
- *
- * const { payload, protectedHeader } = await jose.jwtVerify(jwt, JWKS, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
- * @example Opting-in to multiple JWKS matches using `createLocalJWKSet`
- *
- * ```js
- * const options = {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * }
- * const { payload, protectedHeader } = await jose
- *   .jwtVerify(jwt, JWKS, options)
- *   .catch(async (error) => {
- *     if (error?.code === 'ERR_JWKS_MULTIPLE_MATCHING_KEYS') {
- *       for await (const publicKey of error) {
- *         try {
- *           return await jose.jwtVerify(jwt, publicKey, options)
- *         } catch (innerError) {
- *           if (innerError?.code === 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED') {
- *             continue
- *           }
- *           throw innerError
- *         }
- *       }
- *       throw new jose.errors.JWSSignatureVerificationFailed()
- *     }
- *
- *     throw error
- *   })
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
  * @param jwks JSON Web Key Set formatted object.
  */
 export declare function createLocalJWKSet<T extends KeyLike = KeyLike>(jwks: JSONWebKeySet): (protectedHeader?: JWSHeaderParameters, token?: FlattenedJWSInput) => Promise<T>;

package/dist/types/jwks/remote.d.ts

@@ -17,11 +17,11 @@ export interface RemoteJWKSetOptions {
      */
     cacheMaxAge?: number | typeof Infinity;
     /**
-     * An instance of [http.Agent](https://nodejs.org/api/http.html#class-httpagent) or
-     * [https.Agent](https://nodejs.org/api/https.html#class-httpsagent) to pass to the
-     * [http.get](https://nodejs.org/api/http.html#httpgetoptions-callback) or
-     * [https.get](https://nodejs.org/api/https.html#httpsgetoptions-callback) method's options. Use
-     * when behind an http(s) proxy. This is a Node.js runtime specific option, it is ignored when
+     * An instance of {@link https://nodejs.org/api/http.html#class-httpagent http.Agent} or
+     * {@link https://nodejs.org/api/https.html#class-httpsagent https.Agent} to pass to the
+     * {@link https://nodejs.org/api/http.html#httpgetoptions-callback http.get} or
+     * {@link https://nodejs.org/api/https.html#httpsgetoptions-callback https.get} method's options.
+     * Use when behind an http(s) proxy. This is a Node.js runtime specific option, it is ignored when
      * used outside of Node.js runtime.
      */
     agent?: any;
@@ -43,49 +43,6 @@ export interface RemoteJWKSetOptions {
  * multiple keys get matched it is possible to opt-in to iterate over the matched keys and attempt
  * verification in an iterative manner.
  *
- * @example Usage
- *
- * ```js
- * const JWKS = jose.createRemoteJWKSet(new URL('https://www.googleapis.com/oauth2/v3/certs'))
- *
- * const { payload, protectedHeader } = await jose.jwtVerify(jwt, JWKS, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
- * @example Opting-in to multiple JWKS matches using `createRemoteJWKSet`
- *
- * ```js
- * const options = {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * }
- * const { payload, protectedHeader } = await jose
- *   .jwtVerify(jwt, JWKS, options)
- *   .catch(async (error) => {
- *     if (error?.code === 'ERR_JWKS_MULTIPLE_MATCHING_KEYS') {
- *       for await (const publicKey of error) {
- *         try {
- *           return await jose.jwtVerify(jwt, publicKey, options)
- *         } catch (innerError) {
- *           if (innerError?.code === 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED') {
- *             continue
- *           }
- *           throw innerError
- *         }
- *       }
- *       throw new jose.errors.JWSSignatureVerificationFailed()
- *     }
- *
- *     throw error
- *   })
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
  * @param url URL to fetch the JSON Web Key Set from.
  * @param options Options for the remote JSON Web Key Set.
  */

package/dist/types/jws/compact/sign.d.ts

@@ -1,18 +1,7 @@
 import type { CompactJWSHeaderParameters, KeyLike, SignOptions } from '../../types';
 /**
- * The CompactSign class is a utility for creating Compact JWS strings.
+ * The CompactSign class is used to build and sign Compact JWS strings.
  *
- * @example Usage
- *
- * ```js
- * const jws = await new jose.CompactSign(
- *   new TextEncoder().encode('It’s a dangerous business, Frodo, going out your door.'),
- * )
- *   .setProtectedHeader({ alg: 'ES256' })
- *   .sign(privateKey)
- *
- * console.log(jws)
- * ```
  */
 export declare class CompactSign {
     private _flattened;
@@ -27,7 +16,8 @@ export declare class CompactSign {
     /**
      * Signs and resolves the value of the Compact JWS string.
      *
-     * @param key Private Key or Secret to sign the JWS with.
+     * @param key Private Key or Secret to sign the JWS with. See
+     *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
      * @param options JWS Sign options.
      */
     sign(key: KeyLike | Uint8Array, options?: SignOptions): Promise<string>;

package/dist/types/jws/compact/verify.d.ts

@@ -3,35 +3,23 @@ import type { CompactVerifyResult, FlattenedJWSInput, GetKeyFunction, CompactJWS
  * Interface for Compact JWS Verification dynamic key resolution. No token components have been
  * verified at the time of this function call.
  *
- * See
- * [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset)
- * to verify using a remote JSON Web Key Set.
+ * @see [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
  */
 export interface CompactVerifyGetKey extends GetKeyFunction<CompactJWSHeaderParameters, FlattenedJWSInput> {
 }
 /**
  * Verifies the signature and format of and afterwards decodes the Compact JWS.
  *
- * @example Usage
- *
- * ```js
- * const jws =
- *   'eyJhbGciOiJFUzI1NiJ9.SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IHlvdXIgZG9vci4.kkAs_gPPxWMI3rHuVlxHaTPfDWDoqdI8jSvuSmqV-8IHIWXg9mcAeC9ggV-45ZHRbiRJ3obUIFo1rHphPA5URg'
- *
- * const { payload, protectedHeader } = await jose.compactVerify(jws, publicKey)
- *
- * console.log(protectedHeader)
- * console.log(new TextDecoder().decode(payload))
- * ```
- *
  * @param jws Compact JWS.
- * @param key Key to verify the JWS with.
+ * @param key Key to verify the JWS with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWS Verify options.
  */
 export declare function compactVerify(jws: string | Uint8Array, key: KeyLike | Uint8Array, options?: VerifyOptions): Promise<CompactVerifyResult>;
 /**
  * @param jws Compact JWS.
- * @param getKey Function resolving a key to verify the JWS with.
+ * @param getKey Function resolving a key to verify the JWS with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWS Verify options.
  */
 export declare function compactVerify<T extends KeyLike = KeyLike>(jws: string | Uint8Array, getKey: CompactVerifyGetKey, options?: VerifyOptions): Promise<CompactVerifyResult & ResolvedKey<T>>;

package/dist/types/jws/flattened/sign.d.ts

@@ -1,18 +1,7 @@
 import type { KeyLike, FlattenedJWS, JWSHeaderParameters, SignOptions } from '../../types';
 /**
- * The FlattenedSign class is a utility for creating Flattened JWS objects.
+ * The FlattenedSign class is used to build and sign Flattened JWS objects.
  *
- * @example Usage
- *
- * ```js
- * const jws = await new jose.FlattenedSign(
- *   new TextEncoder().encode('It’s a dangerous business, Frodo, going out your door.'),
- * )
- *   .setProtectedHeader({ alg: 'ES256' })
- *   .sign(privateKey)
- *
- * console.log(jws)
- * ```
  */
 export declare class FlattenedSign {
     private _payload;
@@ -35,7 +24,8 @@ export declare class FlattenedSign {
     /**
      * Signs and resolves the value of the Flattened JWS object.
      *
-     * @param key Private Key or Secret to sign the JWS with.
+     * @param key Private Key or Secret to sign the JWS with. See
+     *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
      * @param options JWS Sign options.
      */
     sign(key: KeyLike | Uint8Array, options?: SignOptions): Promise<FlattenedJWS>;

package/dist/types/jws/flattened/verify.d.ts

@@ -3,40 +3,23 @@ import type { FlattenedVerifyResult, KeyLike, FlattenedJWSInput, JWSHeaderParame
  * Interface for Flattened JWS Verification dynamic key resolution. No token components have been
  * verified at the time of this function call.
  *
- * See
- * [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset)
- * to verify using a remote JSON Web Key Set.
+ * @see [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
  */
 export interface FlattenedVerifyGetKey extends GetKeyFunction<JWSHeaderParameters | undefined, FlattenedJWSInput> {
 }
 /**
  * Verifies the signature and format of and afterwards decodes the Flattened JWS.
  *
- * @example Usage
- *
- * ```js
- * const decoder = new TextDecoder()
- * const jws = {
- *   signature:
- *     'FVVOXwj6kD3DqdfD9yYqfT2W9jv-Nop4kOehp_DeDGNB5dQNSPRvntBY6xH3uxlCxE8na9d_kyhYOcanpDJ0EA',
- *   payload: 'SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IHlvdXIgZG9vci4',
- *   protected: 'eyJhbGciOiJFUzI1NiJ9',
- * }
- *
- * const { payload, protectedHeader } = await jose.flattenedVerify(jws, publicKey)
- *
- * console.log(protectedHeader)
- * console.log(decoder.decode(payload))
- * ```
- *
  * @param jws Flattened JWS.
- * @param key Key to verify the JWS with.
+ * @param key Key to verify the JWS with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWS Verify options.
  */
 export declare function flattenedVerify(jws: FlattenedJWSInput, key: KeyLike | Uint8Array, options?: VerifyOptions): Promise<FlattenedVerifyResult>;
 /**
  * @param jws Flattened JWS.
- * @param getKey Function resolving a key to verify the JWS with.
+ * @param getKey Function resolving a key to verify the JWS with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWS Verify options.
  */
 export declare function flattenedVerify<T extends KeyLike = KeyLike>(jws: FlattenedJWSInput, getKey: FlattenedVerifyGetKey, options?: VerifyOptions): Promise<FlattenedVerifyResult & ResolvedKey<T>>;

package/dist/types/jws/general/sign.d.ts

@@ -20,22 +20,8 @@ export interface Signature {
     done(): GeneralSign;
 }
 /**
- * The GeneralSign class is a utility for creating General JWS objects.
+ * The GeneralSign class is used to build and sign General JWS objects.
  *
- * @example Usage
- *
- * ```js
- * const jws = await new jose.GeneralSign(
- *   new TextEncoder().encode('It’s a dangerous business, Frodo, going out your door.'),
- * )
- *   .addSignature(ecPrivateKey)
- *   .setProtectedHeader({ alg: 'ES256' })
- *   .addSignature(rsaPrivateKey)
- *   .setProtectedHeader({ alg: 'PS256' })
- *   .sign()
- *
- * console.log(jws)
- * ```
  */
 export declare class GeneralSign {
     private _payload;
@@ -45,7 +31,8 @@ export declare class GeneralSign {
     /**
      * Adds an additional signature for the General JWS object.
      *
-     * @param key Private Key or Secret to sign the individual JWS signature with.
+     * @param key Private Key or Secret to sign the individual JWS signature with. See
+     *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
      * @param options JWS Sign options.
      */
     addSignature(key: KeyLike | Uint8Array, options?: SignOptions): Signature;

package/dist/types/jws/general/verify.d.ts

@@ -3,43 +3,23 @@ import type { GeneralJWSInput, GeneralVerifyResult, FlattenedJWSInput, GetKeyFun
  * Interface for General JWS Verification dynamic key resolution. No token components have been
  * verified at the time of this function call.
  *
- * See
- * [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset)
- * to verify using a remote JSON Web Key Set.
+ * @see [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
  */
 export interface GeneralVerifyGetKey extends GetKeyFunction<JWSHeaderParameters, FlattenedJWSInput> {
 }
 /**
  * Verifies the signature and format of and afterwards decodes the General JWS.
  *
- * @example Usage
- *
- * ```js
- * const jws = {
- *   payload: 'SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IHlvdXIgZG9vci4',
- *   signatures: [
- *     {
- *       signature:
- *         'FVVOXwj6kD3DqdfD9yYqfT2W9jv-Nop4kOehp_DeDGNB5dQNSPRvntBY6xH3uxlCxE8na9d_kyhYOcanpDJ0EA',
- *       protected: 'eyJhbGciOiJFUzI1NiJ9',
- *     },
- *   ],
- * }
- *
- * const { payload, protectedHeader } = await jose.generalVerify(jws, publicKey)
- *
- * console.log(protectedHeader)
- * console.log(new TextDecoder().decode(payload))
- * ```
- *
  * @param jws General JWS.
- * @param key Key to verify the JWS with.
+ * @param key Key to verify the JWS with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWS Verify options.
  */
 export declare function generalVerify(jws: GeneralJWSInput, key: KeyLike | Uint8Array, options?: VerifyOptions): Promise<GeneralVerifyResult>;
 /**
  * @param jws General JWS.
- * @param getKey Function resolving a key to verify the JWS with.
+ * @param getKey Function resolving a key to verify the JWS with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWS Verify options.
  */
 export declare function generalVerify<T extends KeyLike = KeyLike>(jws: GeneralJWSInput, getKey: GeneralVerifyGetKey, options?: VerifyOptions): Promise<GeneralVerifyResult & ResolvedKey<T>>;

package/dist/types/jwt/decrypt.d.ts

@@ -12,30 +12,16 @@ export interface JWTDecryptGetKey extends GetKeyFunction<CompactJWEHeaderParamet
  * Verifies the JWT format (to be a JWE Compact format), decrypts the ciphertext, validates the JWT
  * Claims Set.
  *
- * @example Usage
- *
- * ```js
- * const secret = jose.base64url.decode('zH4NRP1HMALxxCFnRZABFA7GOJtzU_gIj02alfL1lvI')
- * const jwt =
- *   'eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..MB66qstZBPxAXKdsjet_lA.WHbtJTl4taHp7otOHLq3hBvv0yNPsPEKHYInmCPdDDeyV1kU-f-tGEiU4FxlSqkqAT2hVs8_wMNiQFAzPU1PUgIqWCPsBrPP3TtxYsrtwagpn4SvCsUsx0Mhw9ZhliAO8CLmCBQkqr_T9AcYsz5uZw.7nX9m7BGUu_u1p1qFHzyIg'
- *
- * const { payload, protectedHeader } = await jose.jwtDecrypt(jwt, secret, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- *
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
  * @param jwt JSON Web Token value (encoded as JWE).
- * @param key Private Key or Secret to decrypt and verify the JWT with.
+ * @param key Private Key or Secret to decrypt and verify the JWT with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWT Decryption and JWT Claims Set validation options.
  */
 export declare function jwtDecrypt(jwt: string | Uint8Array, key: KeyLike | Uint8Array, options?: JWTDecryptOptions): Promise<JWTDecryptResult>;
 /**
  * @param jwt JSON Web Token value (encoded as JWE).
- * @param getKey Function resolving Private Key or Secret to decrypt and verify the JWT with.
+ * @param getKey Function resolving Private Key or Secret to decrypt and verify the JWT with. See
+ *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  * @param options JWT Decryption and JWT Claims Set validation options.
  */
 export declare function jwtDecrypt<T extends KeyLike = KeyLike>(jwt: string | Uint8Array, getKey: JWTDecryptGetKey, options?: JWTDecryptOptions): Promise<JWTDecryptResult & ResolvedKey<T>>;

package/dist/types/jwt/encrypt.d.ts

@@ -1,22 +1,8 @@
 import type { EncryptOptions, CompactJWEHeaderParameters, JWEKeyManagementHeaderParameters, KeyLike } from '../types';
 import { ProduceJWT } from './produce';
 /**
- * The EncryptJWT class is a utility for creating Compact JWE formatted JWT strings.
+ * The EncryptJWT class is used to build and encrypt Compact JWE formatted JSON Web Tokens.
  *
- * @example Usage
- *
- * ```js
- * const secret = jose.base64url.decode('zH4NRP1HMALxxCFnRZABFA7GOJtzU_gIj02alfL1lvI')
- * const jwt = await new jose.EncryptJWT({ 'urn:example:claim': true })
- *   .setProtectedHeader({ alg: 'dir', enc: 'A128CBC-HS256' })
- *   .setIssuedAt()
- *   .setIssuer('urn:example:issuer')
- *   .setAudience('urn:example:audience')
- *   .setExpirationTime('2h')
- *   .encrypt(secret)
- *
- * console.log(jwt)
- * ```
  */
 export declare class EncryptJWT extends ProduceJWT {
     private _cek;
@@ -61,24 +47,28 @@ export declare class EncryptJWT extends ProduceJWT {
      */
     setInitializationVector(iv: Uint8Array): this;
     /**
-     * Replicates the "iss" (Issuer) Claim as a JWE Protected Header Parameter as per
-     * [RFC7519#section-5.3](https://www.rfc-editor.org/rfc/rfc7519#section-5.3).
+     * Replicates the "iss" (Issuer) Claim as a JWE Protected Header Parameter.
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-5.3 RFC7519#section-5.3}
      */
     replicateIssuerAsHeader(): this;
     /**
-     * Replicates the "sub" (Subject) Claim as a JWE Protected Header Parameter as per
-     * [RFC7519#section-5.3](https://www.rfc-editor.org/rfc/rfc7519#section-5.3).
+     * Replicates the "sub" (Subject) Claim as a JWE Protected Header Parameter.
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-5.3 RFC7519#section-5.3}
      */
     replicateSubjectAsHeader(): this;
     /**
-     * Replicates the "aud" (Audience) Claim as a JWE Protected Header Parameter as per
-     * [RFC7519#section-5.3](https://www.rfc-editor.org/rfc/rfc7519#section-5.3).
+     * Replicates the "aud" (Audience) Claim as a JWE Protected Header Parameter.
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-5.3 RFC7519#section-5.3}
      */
     replicateAudienceAsHeader(): this;
     /**
      * Encrypts and returns the JWT.
      *
-     * @param key Public Key or Secret to encrypt the JWT with.
+     * @param key Public Key or Secret to encrypt the JWT 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/jwt/sign.d.ts

@@ -1,99 +1,8 @@
 import type { JWTHeaderParameters, KeyLike, SignOptions } from '../types';
 import { ProduceJWT } from './produce';
 /**
- * The SignJWT class is a utility for creating Compact JWS formatted JWT strings.
+ * The SignJWT class is used to build and sign Compact JWS formatted JSON Web Tokens.
  *
- * @example Usage with a symmetric secret
- *
- * ```js
- * const secret = new TextEncoder().encode(
- *   'cc7e0d44fd473002f1c42167459001140ec6389b7353f8088f4d9a95f2f596f2',
- * )
- * const alg = 'HS256'
- *
- * const jwt = await new jose.SignJWT({ 'urn:example:claim': true })
- *   .setProtectedHeader({ alg })
- *   .setIssuedAt()
- *   .setIssuer('urn:example:issuer')
- *   .setAudience('urn:example:audience')
- *   .setExpirationTime('2h')
- *   .sign(secret)
- *
- * console.log(jwt)
- * ```
- *
- * @example Usage with a private PKCS#8 encoded RSA key
- *
- * ```js
- * const alg = 'RS256'
- * const pkcs8 = `-----BEGIN PRIVATE KEY-----
- * MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDCFg4UrY5xtulv
- * /NXKmL1J4qI1SopAfTNMo3X7p+kJO7plqUYjzaztcre1qfh0m33Sm1Q8oPbO/GpP
- * MU1/HgcceytgJ/b4UwufVVMl9BrMDYG8moDBylbVupFQS3Ly1L9i/iFG9Z9A9xzY
- * Zzf799A45bnvNXL6s2glzvjiRvfQ2NDF0anTcnZLcYtC7ugq1IMM+ihAcPfw8Qw2
- * chN/SmP4qAM+PKaQwagmU7doqmmyN9u38AfoYZ1GCFhEs5TBBT6H6h9YdHeVtiIq
- * 1c+fl03biSIfLrV7dUBD39gBmXBcL/30Ya3D82mCEUC4zg/UkOfQOmkmV3Lc8YUL
- * QZ8EJkBLAgMBAAECggEAVuVE/KEP6323WjpbBdAIv7HGahGrgGANvbxZsIhm34ls
- * VOPK0XDegZkhAybMZHjRhp+gwVxX5ChC+J3cUpOBH5FNxElgW6HizD2Jcq6t6LoL
- * YgPSrfEHm71iHg8JsgrqfUnGYFzMJmv88C6WdCtpgG/qJV1K00/Ly1G1QKoBffEs
- * +v4fAMJrCbUdCz1qWto+PU+HLMEo+krfEpGgcmtZeRlDADh8cETMQlgQfQX2VWq/
- * aAP4a1SXmo+j0cvRU4W5Fj0RVwNesIpetX2ZFz4p/JmB5sWFEj/fC7h5z2lq+6Bm
- * e2T3BHtXkIxoBW0/pYVnASC8P2puO5FnVxDmWuHDYQKBgQDTuuBd3+0tSFVEX+DU
- * 5qpFmHm5nyGItZRJTS+71yg5pBxq1KqNCUjAtbxR0q//fwauakh+BwRVCPOrqsUG
- * jBSb3NYE70Srp6elqxgkE54PwQx4Mr6exJPnseM9U4K+hULllf5yjM9edreJE1nV
- * NVgFjeyafQhrHKwgr7PERJ/ikwKBgQDqqsT1M+EJLmI1HtCspOG6cu7q3gf/wKRh
- * E8tu84i3YyBnI8uJkKy92RNVI5fvpBARe3tjSdM25rr2rcrcmF/5g6Q9ImxZPGCt
- * 86eOgO9ErNtbc4TEgybsP319UE4O41aKeNiBTAZKoYCxv/dMqG0j4avmWzd+foHq
- * gSNUvR2maQKBgQCYeqOsV2B6VPY7KIVFLd0AA9/dwvEmgAYLiA/RShDI+hwQ/5jX
- * uxDu37KAhqeC65sHLrmIMUt4Zdr+DRyZK3aIDNEAesPMjw/X6lCXYp1ZISD2yyym
- * MFGH8X8CIkstI9Faf9vf6PJKSFrC1/HA7wq17VCwrUzLvrljTMW8meM/CwKBgCpo
- * 2leGHLFQFKeM/iF1WuYbR1pi7gcmhY6VyTowARFDdOOu8GXYI5/bz0afvCGvAMho
- * DJCREv7lC/zww6zCTPYG+HOj+PjXlJFba3ixjIxYwPvyEJiDK1Ge18sB7Fl8dHNq
- * C5ayaqCqN1voWYUdGzxU2IA1E/5kVo5O8FesJeOhAoGBAImJbZFf+D5kA32Xxhac
- * 59lLWBCsocvvbd1cvDMNlRywAAyhsCb1SuX4nEAK9mrSBdfmoF2Nm3eilfsOds0f
- * K5mX069IKG82CMqh3Mzptd7e7lyb9lsoGO0BAtjho3cWtha/UZ70vfaMzGuZ6JmQ
- * ak6k+8+UFd93M4z0Qo74OhXB
- * -----END PRIVATE KEY-----`
- * const privateKey = await jose.importPKCS8(pkcs8, alg)
- *
- * const jwt = await new jose.SignJWT({ 'urn:example:claim': true })
- *   .setProtectedHeader({ alg })
- *   .setIssuedAt()
- *   .setIssuer('urn:example:issuer')
- *   .setAudience('urn:example:audience')
- *   .setExpirationTime('2h')
- *   .sign(privateKey)
- *
- * console.log(jwt)
- * ```
- *
- * @example Usage with a private JWK encoded RSA key
- *
- * ```js
- * const alg = 'RS256'
- * const jwk = {
- *   kty: 'RSA',
- *   n: 'whYOFK2Ocbbpb_zVypi9SeKiNUqKQH0zTKN1-6fpCTu6ZalGI82s7XK3tan4dJt90ptUPKD2zvxqTzFNfx4HHHsrYCf2-FMLn1VTJfQazA2BvJqAwcpW1bqRUEty8tS_Yv4hRvWfQPcc2Gc3-_fQOOW57zVy-rNoJc744kb30NjQxdGp03J2S3GLQu7oKtSDDPooQHD38PEMNnITf0pj-KgDPjymkMGoJlO3aKppsjfbt_AH6GGdRghYRLOUwQU-h-ofWHR3lbYiKtXPn5dN24kiHy61e3VAQ9_YAZlwXC_99GGtw_NpghFAuM4P1JDn0DppJldy3PGFC0GfBCZASw',
- *   e: 'AQAB',
- *   d: 'VuVE_KEP6323WjpbBdAIv7HGahGrgGANvbxZsIhm34lsVOPK0XDegZkhAybMZHjRhp-gwVxX5ChC-J3cUpOBH5FNxElgW6HizD2Jcq6t6LoLYgPSrfEHm71iHg8JsgrqfUnGYFzMJmv88C6WdCtpgG_qJV1K00_Ly1G1QKoBffEs-v4fAMJrCbUdCz1qWto-PU-HLMEo-krfEpGgcmtZeRlDADh8cETMQlgQfQX2VWq_aAP4a1SXmo-j0cvRU4W5Fj0RVwNesIpetX2ZFz4p_JmB5sWFEj_fC7h5z2lq-6Bme2T3BHtXkIxoBW0_pYVnASC8P2puO5FnVxDmWuHDYQ',
- *   p: '07rgXd_tLUhVRF_g1OaqRZh5uZ8hiLWUSU0vu9coOaQcatSqjQlIwLW8UdKv_38GrmpIfgcEVQjzq6rFBowUm9zWBO9Eq6enpasYJBOeD8EMeDK-nsST57HjPVOCvoVC5ZX-cozPXna3iRNZ1TVYBY3smn0IaxysIK-zxESf4pM',
- *   q: '6qrE9TPhCS5iNR7QrKThunLu6t4H_8CkYRPLbvOIt2MgZyPLiZCsvdkTVSOX76QQEXt7Y0nTNua69q3K3Jhf-YOkPSJsWTxgrfOnjoDvRKzbW3OExIMm7D99fVBODuNWinjYgUwGSqGAsb_3TKhtI-Gr5ls3fn6B6oEjVL0dpmk',
- *   dp: 'mHqjrFdgelT2OyiFRS3dAAPf3cLxJoAGC4gP0UoQyPocEP-Y17sQ7t-ygIanguubBy65iDFLeGXa_g0cmSt2iAzRAHrDzI8P1-pQl2KdWSEg9ssspjBRh_F_AiJLLSPRWn_b3-jySkhawtfxwO8Kte1QsK1My765Y0zFvJnjPws',
- *   dq: 'KmjaV4YcsVAUp4z-IXVa5htHWmLuByaFjpXJOjABEUN0467wZdgjn9vPRp-8Ia8AyGgMkJES_uUL_PDDrMJM9gb4c6P4-NeUkVtreLGMjFjA-_IQmIMrUZ7XywHsWXx0c2oLlrJqoKo3W-hZhR0bPFTYgDUT_mRWjk7wV6wl46E',
- *   qi: 'iYltkV_4PmQDfZfGFpzn2UtYEKyhy-9t3Vy8Mw2VHLAADKGwJvVK5ficQAr2atIF1-agXY2bd6KV-w52zR8rmZfTr0gobzYIyqHczOm13t7uXJv2WygY7QEC2OGjdxa2Fr9RnvS99ozMa5nomZBqTqT7z5QV33czjPRCjvg6FcE',
- * }
- * const privateKey = await jose.importJWK(jwk, alg)
- *
- * const jwt = await new jose.SignJWT({ 'urn:example:claim': true })
- *   .setProtectedHeader({ alg })
- *   .setIssuedAt()
- *   .setIssuer('urn:example:issuer')
- *   .setAudience('urn:example:audience')
- *   .setExpirationTime('2h')
- *   .sign(privateKey)
- *
- * console.log(jwt)
- * ```
  */
 export declare class SignJWT extends ProduceJWT {
     private _protectedHeader;
@@ -106,7 +15,8 @@ export declare class SignJWT extends ProduceJWT {
     /**
      * Signs and returns the JWT.
      *
-     * @param key Private Key or Secret to sign the JWT with.
+     * @param key Private Key or Secret to sign the JWT with. See
+     *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
      * @param options JWT Sign options.
      */
     sign(key: KeyLike | Uint8Array, options?: SignOptions): Promise<string>;

package/dist/types/jwt/unsecured.d.ts

@@ -7,29 +7,6 @@ export interface UnsecuredResult {
 /**
  * The UnsecuredJWT class is a utility for dealing with `{ "alg": "none" }` Unsecured JWTs.
  *
- * @example Encoding
- *
- * ```js
- * const unsecuredJwt = new jose.UnsecuredJWT({ 'urn:example:claim': true })
- *   .setIssuedAt()
- *   .setIssuer('urn:example:issuer')
- *   .setAudience('urn:example:audience')
- *   .setExpirationTime('2h')
- *   .encode()
- *
- * console.log(unsecuredJwt)
- * ```
- *
- * @example Decoding
- *
- * ```js
- * const payload = jose.UnsecuredJWT.decode(jwt, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- *
- * console.log(payload)
- * ```
  */
 export declare class UnsecuredJWT extends ProduceJWT {
     /** Encodes the Unsecured JWT. */