jose 4.13.1 → 4.14.0

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

@@ -6,9 +6,7 @@ export interface JWTVerifyOptions extends VerifyOptions, JWTClaimVerificationOpt
  * Interface for JWT 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 JWTVerifyGetKey extends GetKeyFunction<JWTHeaderParameters, FlattenedJWSInput> {
 }
@@ -16,93 +14,16 @@ export interface JWTVerifyGetKey extends GetKeyFunction<JWTHeaderParameters, Fla
  * Verifies the JWT format (to be a JWS Compact format), verifies the JWS signature, validates the
  * JWT Claims Set.
  *
- * @example Usage with a symmetric secret
- *
- * ```js
- * const secret = new TextEncoder().encode(
- *   'cc7e0d44fd473002f1c42167459001140ec6389b7353f8088f4d9a95f2f596f2',
- * )
- * const jwt =
- *   'eyJhbGciOiJIUzI1NiJ9.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6dHJ1ZSwiaWF0IjoxNjY5MDU2MjMxLCJpc3MiOiJ1cm46ZXhhbXBsZTppc3N1ZXIiLCJhdWQiOiJ1cm46ZXhhbXBsZTphdWRpZW5jZSJ9.C4iSlLfAUMBq--wnC6VqD9gEOhwpRZpoRarE0m7KEnI'
- *
- * const { payload, protectedHeader } = await jose.jwtVerify(jwt, secret, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- *
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
- * @example Usage with a public SPKI encoded RSA key
- *
- * ```js
- * const alg = 'RS256'
- * const spki = `-----BEGIN PUBLIC KEY-----
- * MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwhYOFK2Ocbbpb/zVypi9
- * SeKiNUqKQH0zTKN1+6fpCTu6ZalGI82s7XK3tan4dJt90ptUPKD2zvxqTzFNfx4H
- * HHsrYCf2+FMLn1VTJfQazA2BvJqAwcpW1bqRUEty8tS/Yv4hRvWfQPcc2Gc3+/fQ
- * OOW57zVy+rNoJc744kb30NjQxdGp03J2S3GLQu7oKtSDDPooQHD38PEMNnITf0pj
- * +KgDPjymkMGoJlO3aKppsjfbt/AH6GGdRghYRLOUwQU+h+ofWHR3lbYiKtXPn5dN
- * 24kiHy61e3VAQ9/YAZlwXC/99GGtw/NpghFAuM4P1JDn0DppJldy3PGFC0GfBCZA
- * SwIDAQAB
- * -----END PUBLIC KEY-----`
- * const publicKey = await jose.importSPKI(spki, alg)
- * const jwt =
- *   'eyJhbGciOiJSUzI1NiJ9.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6dHJ1ZSwiaWF0IjoxNjY5MDU2NDg4LCJpc3MiOiJ1cm46ZXhhbXBsZTppc3N1ZXIiLCJhdWQiOiJ1cm46ZXhhbXBsZTphdWRpZW5jZSJ9.gXrPZ3yM_60dMXGE69dusbpzYASNA-XIOwsb5D5xYnSxyj6_D6OR_uR_1vqhUm4AxZxcrH1_-XJAve9HCw8az_QzHcN-nETt-v6stCsYrn6Bv1YOc-mSJRZ8ll57KVqLbCIbjKwerNX5r2_Qg2TwmJzQdRs-AQDhy-s_DlJd8ql6wR4n-kDZpar-pwIvz4fFIN0Fj57SXpAbLrV6Eo4Byzl0xFD8qEYEpBwjrMMfxCZXTlAVhAq6KCoGlDTwWuExps342-0UErEtyIqDnDGcrfNWiUsoo8j-29IpKd-w9-C388u-ChCxoHz--H8WmMSZzx3zTXsZ5lXLZ9IKfanDKg'
- *
- * const { payload, protectedHeader } = await jose.jwtVerify(jwt, publicKey, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- *
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
- * @example Usage with a public 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',
- * }
- * const publicKey = await jose.importJWK(jwk, alg)
- * const jwt =
- *   'eyJhbGciOiJSUzI1NiJ9.eyJ1cm46ZXhhbXBsZTpjbGFpbSI6dHJ1ZSwiaWF0IjoxNjY5MDU2NDg4LCJpc3MiOiJ1cm46ZXhhbXBsZTppc3N1ZXIiLCJhdWQiOiJ1cm46ZXhhbXBsZTphdWRpZW5jZSJ9.gXrPZ3yM_60dMXGE69dusbpzYASNA-XIOwsb5D5xYnSxyj6_D6OR_uR_1vqhUm4AxZxcrH1_-XJAve9HCw8az_QzHcN-nETt-v6stCsYrn6Bv1YOc-mSJRZ8ll57KVqLbCIbjKwerNX5r2_Qg2TwmJzQdRs-AQDhy-s_DlJd8ql6wR4n-kDZpar-pwIvz4fFIN0Fj57SXpAbLrV6Eo4Byzl0xFD8qEYEpBwjrMMfxCZXTlAVhAq6KCoGlDTwWuExps342-0UErEtyIqDnDGcrfNWiUsoo8j-29IpKd-w9-C388u-ChCxoHz--H8WmMSZzx3zTXsZ5lXLZ9IKfanDKg'
- *
- * const { payload, protectedHeader } = await jose.jwtVerify(jwt, publicKey, {
- *   issuer: 'urn:example:issuer',
- *   audience: 'urn:example:audience',
- * })
- *
- * console.log(protectedHeader)
- * console.log(payload)
- * ```
- *
  * @param jwt JSON Web Token value (encoded as JWS).
- * @param key Key to verify the JWT with.
+ * @param key Key to verify the JWT with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWT Decryption and JWT Claims Set validation options.
  */
 export declare function jwtVerify(jwt: string | Uint8Array, key: KeyLike | Uint8Array, options?: JWTVerifyOptions): Promise<JWTVerifyResult>;
 /**
- * @example Usage with a public JSON Web Key Set hosted on a remote URL
- *
- * ```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)
- * ```
- *
  * @param jwt JSON Web Token value (encoded as JWS).
- * @param getKey Function resolving a key to verify the JWT with.
+ * @param getKey Function resolving a key to verify the JWT with. See
+ *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  * @param options JWT Decryption and JWT Claims Set validation options.
  */
 export declare function jwtVerify<T extends KeyLike = KeyLike>(jwt: string | Uint8Array, getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): Promise<JWTVerifyResult & ResolvedKey<T>>;

package/dist/types/key/export.d.ts

@@ -3,14 +3,6 @@ import type { JWK, KeyLike } from '../types';
  * Exports a runtime-specific public key representation (KeyObject or CryptoKey) to a PEM-encoded
  * SPKI string format.
  *
- * @example Usage
- *
- * ```js
- * const spkiPem = await jose.exportSPKI(publicKey)
- *
- * console.log(spkiPem)
- * ```
- *
  * @param key Key representation to transform to a PEM-encoded SPKI string format.
  */
 export declare function exportSPKI(key: KeyLike): Promise<string>;
@@ -18,30 +10,12 @@ export declare function exportSPKI(key: KeyLike): Promise<string>;
  * Exports a runtime-specific private key representation (KeyObject or CryptoKey) to a PEM-encoded
  * PKCS8 string format.
  *
- * @example Usage
- *
- * ```js
- * const pkcs8Pem = await jose.exportPKCS8(privateKey)
- *
- * console.log(pkcs8Pem)
- * ```
- *
  * @param key Key representation to transform to a PEM-encoded PKCS8 string format.
  */
 export declare function exportPKCS8(key: KeyLike): Promise<string>;
 /**
  * Exports a runtime-specific key representation (KeyLike) to a JWK.
  *
- * @example Usage
- *
- * ```js
- * const privateJwk = await jose.exportJWK(privateKey)
- * const publicJwk = await jose.exportJWK(publicKey)
- *
- * console.log(privateJwk)
- * console.log(publicJwk)
- * ```
- *
  * @param key Key representation to export as JWK.
  */
 export declare function exportJWK(key: KeyLike | Uint8Array): Promise<JWK>;

package/dist/types/key/generate_key_pair.d.ts

@@ -18,7 +18,7 @@ export interface GenerateKeyPairOptions {
     modulusLength?: number;
     /**
      * (Only effective in Web Crypto API runtimes) The value to use as
-     * [SubtleCrypto.generateKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey SubtleCrypto.generateKey()}
      * `extractable` argument. Default is false.
      */
     extractable?: boolean;
@@ -30,14 +30,6 @@ export interface GenerateKeyPairOptions {
  * Note: Under Web Crypto API runtime the `privateKey` is generated with `extractable` set to
  * `false` by default.
  *
- * @example Usage
- *
- * ```js
- * const { publicKey, privateKey } = await jose.generateKeyPair('PS256')
- * console.log(publicKey)
- * console.log(privateKey)
- * ```
- *
  * @param alg JWA Algorithm Identifier to be used with the generated key pair.
  * @param options Additional options passed down to the key pair generation.
  */

package/dist/types/key/generate_secret.d.ts

@@ -2,7 +2,7 @@ import type { KeyLike } from '../types';
 export interface GenerateSecretOptions {
     /**
      * (Only effective in Web Crypto API runtimes) The value to use as
-     * [SubtleCrypto.generateKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey SubtleCrypto.generateKey()}
      * `extractable` argument. Default is false.
      */
     extractable?: boolean;
@@ -13,13 +13,6 @@ export interface GenerateSecretOptions {
  * Note: Under Web Crypto API runtime the secret key is generated with `extractable` set to `false`
  * by default.
  *
- * @example Usage
- *
- * ```js
- * const secret = await jose.generateSecret('HS256')
- * console.log(secret)
- * ```
- *
  * @param alg JWA Algorithm Identifier to be used with the generated secret.
  * @param options Additional options passed down to the secret generation.
  */

package/dist/types/key/import.d.ts

@@ -2,117 +2,52 @@ import type { JWK, KeyLike } from '../types';
 export interface PEMImportOptions {
     /**
      * (Only effective in Web Crypto API runtimes) The value to use as
-     * [SubtleCrypto.importKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey)
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey SubtleCrypto.importKey()}
      * `extractable` argument. Default is false.
      */
     extractable?: boolean;
 }
 /**
  * Imports a PEM-encoded SPKI string as a runtime-specific public key representation (KeyObject or
- * CryptoKey). See [Algorithm Key Requirements](https://github.com/panva/jose/issues/210) to learn
- * about key to algorithm requirements and mapping.
- *
- * @example Usage
- *
- * ```js
- * const algorithm = 'ES256'
- * const spki = `-----BEGIN PUBLIC KEY-----
- * MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFlHHWfLk0gLBbsLTcuCrbCqoHqmM
- * YJepMC+Q+Dd6RBmBiA41evUsNMwLeN+PNFqib+xwi9JkJ8qhZkq8Y/IzGg==
- * -----END PUBLIC KEY-----`
- * const ecPublicKey = await jose.importSPKI(spki, algorithm)
- * ```
+ * CryptoKey).
  *
  * @param pem PEM-encoded SPKI string
  * @param alg (Only effective in Web Crypto API runtimes) JSON Web Algorithm identifier to be used
- *   with the imported key, its presence is only enforced in Web Crypto API runtimes.
+ *   with the imported key, its presence is only enforced in Web Crypto API runtimes. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
  */
 export declare function importSPKI<T extends KeyLike = KeyLike>(spki: string, alg: string, options?: PEMImportOptions): Promise<T>;
 /**
  * Imports the SPKI from an X.509 string certificate as a runtime-specific public key representation
- * (KeyObject or CryptoKey). See [Algorithm Key
- * Requirements](https://github.com/panva/jose/issues/210) to learn about key to algorithm
- * requirements and mapping.
- *
- * @example Usage
- *
- * ```js
- * const algorithm = 'ES256'
- * const x509 = `-----BEGIN CERTIFICATE-----
- * MIIBXjCCAQSgAwIBAgIGAXvykuMKMAoGCCqGSM49BAMCMDYxNDAyBgNVBAMMK3Np
- * QXBNOXpBdk1VaXhXVWVGaGtjZXg1NjJRRzFyQUhXaV96UlFQTVpQaG8wHhcNMjEw
- * OTE3MDcwNTE3WhcNMjIwNzE0MDcwNTE3WjA2MTQwMgYDVQQDDCtzaUFwTTl6QXZN
- * VWl4V1VlRmhrY2V4NTYyUUcxckFIV2lfelJRUE1aUGhvMFkwEwYHKoZIzj0CAQYI
- * KoZIzj0DAQcDQgAE8PbPvCv5D5xBFHEZlBp/q5OEUymq7RIgWIi7tkl9aGSpYE35
- * UH+kBKDnphJO3odpPZ5gvgKs2nwRWcrDnUjYLDAKBggqhkjOPQQDAgNIADBFAiEA
- * 1yyMTRe66MhEXID9+uVub7woMkNYd0LhSHwKSPMUUTkCIFQGsfm1ecXOpeGOufAh
- * v+A1QWZMuTWqYt+uh/YSRNDn
- * -----END CERTIFICATE-----`
- * const ecPublicKey = await jose.importX509(x509, algorithm)
- * ```
+ * (KeyObject or CryptoKey).
  *
  * @param pem X.509 certificate string
  * @param alg (Only effective in Web Crypto API runtimes) JSON Web Algorithm identifier to be used
- *   with the imported key, its presence is only enforced in Web Crypto API runtimes.
+ *   with the imported key, its presence is only enforced in Web Crypto API runtimes. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
  */
 export declare function importX509<T extends KeyLike = KeyLike>(x509: string, alg: string, options?: PEMImportOptions): Promise<T>;
 /**
  * Imports a PEM-encoded PKCS#8 string as a runtime-specific private key representation (KeyObject
- * or CryptoKey). See [Algorithm Key Requirements](https://github.com/panva/jose/issues/210) to
- * learn about key to algorithm requirements and mapping. Encrypted keys are not supported.
- *
- * @example Usage
- *
- * ```js
- * const algorithm = 'ES256'
- * const pkcs8 = `-----BEGIN PRIVATE KEY-----
- * MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgiyvo0X+VQ0yIrOaN
- * nlrnUclopnvuuMfoc8HHly3505OhRANCAAQWUcdZ8uTSAsFuwtNy4KtsKqgeqYxg
- * l6kwL5D4N3pEGYGIDjV69Sw0zAt43480WqJv7HCL0mQnyqFmSrxj8jMa
- * -----END PRIVATE KEY-----`
- * const ecPrivateKey = await jose.importPKCS8(pkcs8, algorithm)
- * ```
+ * or CryptoKey).
  *
  * @param pem PEM-encoded PKCS#8 string
  * @param alg (Only effective in Web Crypto API runtimes) JSON Web Algorithm identifier to be used
- *   with the imported key, its presence is only enforced in Web Crypto API runtimes.
+ *   with the imported key, its presence is only enforced in Web Crypto API runtimes. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
  */
 export declare function importPKCS8<T extends KeyLike = KeyLike>(pkcs8: string, alg: string, options?: PEMImportOptions): Promise<T>;
 /**
  * Imports a JWK to a runtime-specific key representation (KeyLike). Either JWK "alg" (Algorithm)
- * Parameter must be present or the optional "alg" argument. When running on a runtime using [Web
- * Cryptography API](https://www.w3.org/TR/WebCryptoAPI/) the jwk parameters "use", "key_ops", and
- * "ext" are also used in the resulting `CryptoKey`. See [Algorithm Key
- * Requirements](https://github.com/panva/jose/issues/210) to learn about key to algorithm
- * requirements and mapping.
- *
- * @example Usage
- *
- * ```js
- * const ecPublicKey = await jose.importJWK(
- *   {
- *     crv: 'P-256',
- *     kty: 'EC',
- *     x: 'ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw',
- *     y: '_LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo',
- *   },
- *   'ES256',
- * )
- *
- * const rsaPublicKey = await jose.importJWK(
- *   {
- *     kty: 'RSA',
- *     e: 'AQAB',
- *     n: '12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ',
- *   },
- *   'PS256',
- * )
- * ```
+ * Parameter must be present or the optional "alg" argument. When running on a runtime using
+ * {@link https://www.w3.org/TR/WebCryptoAPI/ Web Cryptography API} the jwk parameters "use",
+ * "key_ops", and "ext" are also used in the resulting `CryptoKey`.
  *
  * @param jwk JSON Web Key.
  * @param alg (Only effective in Web Crypto API runtimes) JSON Web Algorithm identifier to be used
  *   with the imported key. Default is the "alg" property on the JWK, its presence is only enforced
- *   in Web Crypto API runtimes.
+ *   in Web Crypto API runtimes. See
+ *   {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}.
  * @param octAsKeyObject Forces a symmetric key to be imported to a KeyObject or CryptoKey. Default
  *   is true unless JWK "ext" (Extractable) is true.
  */

package/dist/types/types.d.ts

@@ -1,98 +1,37 @@
 /**
  * KeyLike are runtime-specific classes representing asymmetric keys or symmetric secrets. These are
- * instances of [CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) and
- * additionally [KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) in Node.js runtime.
- * [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
+ * instances of {@link https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey CryptoKey} and
+ * additionally {@link https://nodejs.org/api/crypto.html#class-keyobject KeyObject} in Node.js
+ * runtime.
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array Uint8Array}
  * instances are also accepted as symmetric secret representation only.
  *
- * [Key Import Functions](../modules/key_import.md#readme) can be used to import PEM, or JWK
- * formatted asymmetric keys and certificates to these runtime-specific representations.
+ * [Key Import Functions](../modules/key_import.md) can be used to import PEM, or JWK formatted
+ * asymmetric keys and certificates to these runtime-specific representations.
  *
- * In Node.js the [Buffer](https://nodejs.org/api/buffer.html#buffer) class is a subclass of
+ * In Node.js the {@link https://nodejs.org/api/buffer.html#buffer Buffer} class is a subclass of
  * Uint8Array and so Buffer can be provided for symmetric secrets as well.
  *
- * [KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) is a representation of a
+ * {@link https://nodejs.org/api/crypto.html#class-keyobject KeyObject} is a representation of a
  * key/secret available in the Node.js runtime. In addition to the import functions of this library
  * you may use the runtime APIs
- * [crypto.createPublicKey](https://nodejs.org/api/crypto.html#cryptocreatepublickeykey),
- * [crypto.createPrivateKey](https://nodejs.org/api/crypto.html#cryptocreateprivatekeykey), and
- * [crypto.createSecretKey](https://nodejs.org/api/crypto.html#cryptocreatesecretkeykey-encoding) to
- * obtain a KeyObject from your existing key material.
+ * {@link https://nodejs.org/api/crypto.html#cryptocreatepublickeykey crypto.createPublicKey},
+ * {@link https://nodejs.org/api/crypto.html#cryptocreateprivatekeykey crypto.createPrivateKey}, and
+ * {@link https://nodejs.org/api/crypto.html#cryptocreatesecretkeykey-encoding crypto.createSecretKey}
+ * to obtain a `KeyObject` from your existing key material.
  *
- * [CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) is a representation of a
- * key/secret available in the Browser and Web-interoperable runtimes. In addition to the import
- * functions of this library you may use the
- * [SubtleCrypto.importKey](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey)
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey CryptoKey} is a representation
+ * of a key/secret available in the Browser and Web-interoperable runtimes. In addition to the
+ * import functions of this library you may use the
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey SubtleCrypto.importKey}
  * API to obtain a CryptoKey from your existing key material.
  *
- * @example Import a PEM-encoded SPKI Public Key
- *
- * ```js
- * const algorithm = 'ES256'
- * const spki = `-----BEGIN PUBLIC KEY-----
- * MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFlHHWfLk0gLBbsLTcuCrbCqoHqmM
- * YJepMC+Q+Dd6RBmBiA41evUsNMwLeN+PNFqib+xwi9JkJ8qhZkq8Y/IzGg==
- * -----END PUBLIC KEY-----`
- * const ecPublicKey = await jose.importSPKI(spki, algorithm)
- * ```
- *
- * @example Import SPKI from an X.509 Certificate
- *
- * ```js
- * const algorithm = 'ES256'
- * const x509 = `-----BEGIN CERTIFICATE-----
- * MIIBXjCCAQSgAwIBAgIGAXvykuMKMAoGCCqGSM49BAMCMDYxNDAyBgNVBAMMK3Np
- * QXBNOXpBdk1VaXhXVWVGaGtjZXg1NjJRRzFyQUhXaV96UlFQTVpQaG8wHhcNMjEw
- * OTE3MDcwNTE3WhcNMjIwNzE0MDcwNTE3WjA2MTQwMgYDVQQDDCtzaUFwTTl6QXZN
- * VWl4V1VlRmhrY2V4NTYyUUcxckFIV2lfelJRUE1aUGhvMFkwEwYHKoZIzj0CAQYI
- * KoZIzj0DAQcDQgAE8PbPvCv5D5xBFHEZlBp/q5OEUymq7RIgWIi7tkl9aGSpYE35
- * UH+kBKDnphJO3odpPZ5gvgKs2nwRWcrDnUjYLDAKBggqhkjOPQQDAgNIADBFAiEA
- * 1yyMTRe66MhEXID9+uVub7woMkNYd0LhSHwKSPMUUTkCIFQGsfm1ecXOpeGOufAh
- * v+A1QWZMuTWqYt+uh/YSRNDn
- * -----END CERTIFICATE-----`
- * const ecPublicKey = await jose.importX509(x509, algorithm)
- * ```
- *
- * @example Import a PEM-encoded PKCS8 Private Key
- *
- * ```js
- * const algorithm = 'ES256'
- * const pkcs8 = `-----BEGIN PRIVATE KEY-----
- * MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgiyvo0X+VQ0yIrOaN
- * nlrnUclopnvuuMfoc8HHly3505OhRANCAAQWUcdZ8uTSAsFuwtNy4KtsKqgeqYxg
- * l6kwL5D4N3pEGYGIDjV69Sw0zAt43480WqJv7HCL0mQnyqFmSrxj8jMa
- * -----END PRIVATE KEY-----`
- * const ecPrivateKey = await jose.importPKCS8(pkcs8, algorithm)
- * ```
- *
- * @example Import a JSON Web Key (JWK)
- *
- * ```js
- * const ecPublicKey = await jose.importJWK(
- *   {
- *     crv: 'P-256',
- *     kty: 'EC',
- *     x: 'ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw',
- *     y: '_LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo',
- *   },
- *   'ES256',
- * )
- *
- * const rsaPublicKey = await jose.importJWK(
- *   {
- *     kty: 'RSA',
- *     e: 'AQAB',
- *     n: '12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ',
- *   },
- *   'PS256',
- * )
- * ```
  */
 export type KeyLike = { type: string }
 
 /**
- * JSON Web Key ([JWK](https://www.rfc-editor.org/rfc/rfc7517)). "RSA", "EC", "OKP", and "oct" key
- * types are supported.
+ * JSON Web Key ({@link https://www.rfc-editor.org/rfc/rfc7517 JWK}). "RSA", "EC", "OKP", and "oct"
+ * key types are supported.
  */
 export interface JWK {
   /** JWK "alg" (Algorithm) Parameter. */
@@ -185,8 +124,9 @@ export interface FlattenedJWSInput {
  */
 export interface GeneralJWSInput {
   /**
-   * The "payload" member MUST be present and contain the value BASE64URL(JWS Payload). When RFC7797
-   * "b64": false is used the value passed may also be a Uint8Array.
+   * The "payload" member MUST be present and contain the value BASE64URL(JWS Payload). When when
+   * JWS Unencoded Payload ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) "b64": false is
+   * used the value passed may also be a Uint8Array.
    */
   payload: string | Uint8Array
 
@@ -199,7 +139,7 @@ export interface GeneralJWSInput {
 
 /**
  * Flattened JWS definition. Payload is returned as an empty string when JWS Unencoded Payload
- * Option [RFC7797](https://www.rfc-editor.org/rfc/rfc7797) is used.
+ * ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) is used.
  */
 export interface FlattenedJWS extends Partial<FlattenedJWSInput> {
   payload: string
@@ -207,8 +147,8 @@ export interface FlattenedJWS extends Partial<FlattenedJWSInput> {
 }
 
 /**
- * General JWS definition. Payload is returned as an empty string when JWS Unencoded Payload Option
- * [RFC7797](https://www.rfc-editor.org/rfc/rfc7797) is used.
+ * General JWS definition. Payload is returned as an empty string when JWS Unencoded Payload
+ * ({@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}) is used.
  */
 export interface GeneralJWS {
   payload: string
@@ -248,7 +188,7 @@ export interface JWSHeaderParameters extends JoseHeaderParameters {
 
   /**
    * This JWS Extension Header Parameter modifies the JWS Payload representation and the JWS Signing
-   * Input computation as per [RFC7797](https://www.rfc-editor.org/rfc/rfc7797).
+   * Input computation as per {@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}.
    */
   b64?: boolean
 
@@ -354,7 +294,13 @@ export interface JWEHeaderParameters extends JoseHeaderParameters {
   /** JWE "crit" (Critical) Header Parameter. */
   crit?: string[]
 
-  /** JWE "zip" (Compression Algorithm) Header Parameter. */
+  /**
+   * JWE "zip" (Compression Algorithm) Header Parameter.
+   *
+   * @deprecated Compression of data SHOULD NOT be done before encryption, because such compressed
+   *   data often reveals information about the plaintext.
+   * @see {@link https://www.rfc-editor.org/rfc/rfc8725#name-avoid-compression-of-encryp Avoid Compression of Encryption Inputs}
+   */
   zip?: string
 
   /** Any other JWE Header member. */
@@ -455,6 +401,16 @@ export interface JWTClaimVerificationOptions {
 
   /** Date to use when comparing NumericDate claims, defaults to `new Date()`. */
   currentDate?: Date
+
+  /**
+   * Array of required Claim Names that must be present in the JWT Claims Set. Default is that: if
+   * the {@link JWTClaimVerificationOptions.issuer issuer option} is set, then "iss" must be present;
+   * if the {@link JWTClaimVerificationOptions.audience audience option} is set, then "aud" must be
+   * present; if the {@link JWTClaimVerificationOptions.subject subject option} is set, then "sub"
+   * must be present; if the {@link JWTClaimVerificationOptions.maxTokenAge maxTokenAge option} is
+   * set, then "iat" must be present.
+   */
+  requiredClaims?: string[]
 }
 
 /** JWS Verification options. */
@@ -475,45 +431,49 @@ export interface JWTPayload {
   /**
    * JWT Issuer
    *
-   * @see [RFC7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1)
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 RFC7519#section-4.1.1}
    */
   iss?: string
 
   /**
    * JWT Subject
    *
-   * @see [RFC7519#section-4.1.2](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2)
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2 RFC7519#section-4.1.2}
    */
   sub?: string
 
-  /** JWT Audience [RFC7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3). */
+  /**
+   * JWT Audience
+   *
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 RFC7519#section-4.1.3}
+   */
   aud?: string | string[]
 
   /**
    * JWT ID
    *
-   * @see [RFC7519#section-4.1.7](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7)
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7 RFC7519#section-4.1.7}
    */
   jti?: string
 
   /**
    * JWT Not Before
    *
-   * @see [RFC7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5)
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 RFC7519#section-4.1.5}
    */
   nbf?: number
 
   /**
    * JWT Expiration Time
    *
-   * @see [RFC7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4)
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 RFC7519#section-4.1.4}
    */
   exp?: number
 
   /**
    * JWT Issued At
    *
-   * @see [RFC7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6)
+   * @see {@link https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6 RFC7519#section-4.1.6}
    */
   iat?: number
 
@@ -523,7 +483,11 @@ export interface JWTPayload {
 
 /**
  * Deflate Raw implementation, e.g. promisified
- * [zlib.deflateRaw](https://nodejs.org/api/zlib.html#zlibdeflaterawbuffer-options-callback).
+ * {@link https://nodejs.org/api/zlib.html#zlibdeflaterawbuffer-options-callback zlib.deflateRaw}.
+ *
+ * @deprecated Compression of data SHOULD NOT be done before encryption, because such compressed
+ *   data often reveals information about the plaintext.
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8725#name-avoid-compression-of-encryp Avoid Compression of Encryption Inputs}
  */
 export interface DeflateFunction {
   (input: Uint8Array): Promise<Uint8Array>
@@ -531,7 +495,11 @@ export interface DeflateFunction {
 
 /**
  * Inflate Raw implementation, e.g. promisified
- * [zlib.inflateRaw](https://nodejs.org/api/zlib.html#zlibinflaterawbuffer-options-callback).
+ * {@link https://nodejs.org/api/zlib.html#zlibinflaterawbuffer-options-callback zlib.inflateRaw}.
+ *
+ * @deprecated Compression of data SHOULD NOT be done before encryption, because such compressed
+ *   data often reveals information about the plaintext.
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8725#name-avoid-compression-of-encryp Avoid Compression of Encryption Inputs}
  */
 export interface InflateFunction {
   (input: Uint8Array): Promise<Uint8Array>

package/dist/types/util/decode_jwt.d.ts

@@ -5,13 +5,6 @@ import type { JWTPayload } from '../types';
  * and JWS signature verification use `jose.jwtVerify()`. For an encrypted JWT Claims Set validation
  * and JWE decryption use `jose.jwtDecrypt()`.
  *
- * @example Usage
- *
- * ```js
- * const claims = jose.decodeJwt(token)
- * console.log(claims)
- * ```
- *
  * @param jwt JWT token in compact JWS serialization.
  */
 export declare function decodeJwt(jwt: string): JWTPayload;

package/dist/types/util/decode_protected_header.d.ts

@@ -3,13 +3,6 @@ export type ProtectedHeaderParameters = JWSHeaderParameters & JWEHeaderParameter
 /**
  * Decodes the Protected Header of a JWE/JWS/JWT token utilizing any JOSE serialization.
  *
- * @example Usage
- *
- * ```js
- * const protectedHeader = jose.decodeProtectedHeader(token)
- * console.log(protectedHeader)
- * ```
- *
  * @param token JWE/JWS/JWT token in any JOSE serialization.
  */
 export declare function decodeProtectedHeader(token: string | object): ProtectedHeaderParameters;