jose 6.2.11 → 6.2.13

package/README.md

@@ -70,7 +70,7 @@ The `jose` module supports importing, exporting, and generating keys and secrets
 
 ### JSON Web Signature (JWS)
 
-The `jose` module supports signing and verification of JWS messages with arbitrary payloads in Compact, Flattened JSON, and General JSON serialization syntaxes.
+The `jose` module supports digital signature and MAC computation and validation over arbitrary JWS Payloads using the JWS Compact Serialization and the flattened and general JWS JSON Serialization syntaxes ([RFC 7515, Section 7](https://www.rfc-editor.org/info/rfc7515/#section-7)).
 
 - Signing - [Compact](docs/jws/compact/sign/classes/CompactSign.md), [Flattened JSON](docs/jws/flattened/sign/classes/FlattenedSign.md), [General JSON](docs/jws/general/sign/classes/GeneralSign.md)
 - Verification - [Compact](docs/jws/compact/verify/functions/compactVerify.md), [Flattened JSON](docs/jws/flattened/verify/functions/flattenedVerify.md), [General JSON](docs/jws/general/verify/functions/generalVerify.md)
@@ -81,7 +81,7 @@ The `jose` module supports signing and verification of JWS messages with arbitra
 
 ### JSON Web Encryption (JWE)
 
-The `jose` module supports encryption and decryption of JWE messages with arbitrary plaintext in Compact, Flattened JSON, and General JSON serialization syntaxes.
+The `jose` module supports encryption and authenticated decryption of arbitrary plaintext using the JWE Compact Serialization and the flattened and general JWE JSON Serialization syntaxes ([RFC 7516, Section 7](https://www.rfc-editor.org/info/rfc7516/#section-7)).
 
 - Encryption - [Compact](docs/jwe/compact/encrypt/classes/CompactEncrypt.md), [Flattened JSON](docs/jwe/flattened/encrypt/classes/FlattenedEncrypt.md), [General JSON](docs/jwe/general/encrypt/classes/GeneralEncrypt.md)
 - Decryption - [Compact](docs/jwe/compact/decrypt/functions/compactDecrypt.md), [Flattened JSON](docs/jwe/flattened/decrypt/functions/flattenedDecrypt.md), [General JSON](docs/jwe/general/decrypt/functions/generalDecrypt.md)

package/dist/types/index.d.ts

@@ -48,8 +48,7 @@ import * as base64url from './util/base64url.js';
 export { base64url };
 export type { AnyJWK, CompactDecryptResult, CompactJWEHeaderParameters, CompactJWSHeaderParameters, CompactVerifyResult, CritOption, CryptoKey, DecryptOptions, EncryptOptions, FlattenedDecryptResult, FlattenedJWE, FlattenedJWS, FlattenedJWSInput, FlattenedVerifyResult, GeneralDecryptResult, GeneralJWE, GeneralJWS, GeneralJWSInput, GeneralVerifyResult, GetKeyFunction, JoseHeaderParameters, JSONWebKeySet, JWEContentEncryptionAlgorithm, JWEHeaderParameters, JWEKeyManagementAlgorithm, JWEKeyManagementHeaderParameters, JWK_AKP_Private, JWK_AKP_Public, JWK_EC_Private, JWK_EC_Public, JWK_oct, JWK_OKP_Private, JWK_OKP_Public, JWK_RSA_Private, JWK_RSA_Public, JWK, JWKKeyType, JWKParameters, JWSAlgorithm, JWSHeaderParameters, JWTClaimVerificationOptions, JWTDecryptResult, JWTHeaderParameters, JWTPayload, JWTVerifyResult, KeyInput, KeyObject, ProduceJWT, ResolvedKey, SignOptions, VerifyOptions, } from './types.d.ts';
 /**
- * In prior releases this indicated whether a Node.js-specific build was loaded, this is now fixed
- * to `"WebCryptoAPI"`
+ * Identified the loaded runtime-specific build in prior releases; now always `"WebCryptoAPI"`.
  *
  * @deprecated Remove any runtime branching on this value; it is always `"WebCryptoAPI"`.
  */

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

@@ -1,28 +1,25 @@
 import type * as t from '../../types.d.ts';
-/** Dynamic key resolver for Compact JWE decryption. */
+/** Resolves a key for Compact JWE decryption from unverified headers and token data. */
 export interface CompactDecryptGetKey<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array> extends t.GetKeyFunction<t.CompactJWEHeaderParameters, t.FlattenedJWE, KeyType | t.KeyObject | t.JWK> {
 }
 /**
- * Decrypts a Compact JWE.
+ * Authenticates and decrypts a JWE Compact Serialization.
  *
- * @param key Private Key or Secret to decrypt the JWE with. See
+ * @param key Private key or shared secret. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  */
 export declare function compactDecrypt(jwe: string | Uint8Array, key: t.KeyInput, options?: t.DecryptOptions): Promise<t.CompactDecryptResult>;
 /**
- * Decrypts a Compact JWE, resolving the key dynamically. The result additionally carries the
- * {@link t.ResolvedKey.key resolved key}.
+ * Authenticates and decrypts a JWE Compact Serialization with a dynamically resolved key, included
+ * in the result.
  *
- * @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 getKey Resolves a private key or shared secret from unverified token data.
  */
 export declare function compactDecrypt<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array>(jwe: string | Uint8Array, getKey: CompactDecryptGetKey<KeyType>, options?: t.DecryptOptions): Promise<t.CompactDecryptResult & t.ResolvedKey<KeyType>>;
 /**
- * Accepts either form of the `key` argument. Use this overload when forwarding a value that may be
- * either a key or a key resolution function; `key` is present on the result only when a resolution
- * function was used.
+ * Authenticates and decrypts a JWE Compact Serialization with a key or key resolver. The result
+ * includes `key` only when a resolver is used.
  *
- * @param key Private Key or Secret, or a function resolving one, to decrypt the JWE with. See
- *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param key Private key or shared secret, or a function resolving one.
  */
 export declare function compactDecrypt(jwe: string | Uint8Array, key: t.KeyInput | CompactDecryptGetKey, options?: t.DecryptOptions): Promise<t.CompactDecryptResult & Partial<t.ResolvedKey>>;

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

@@ -1,42 +1,39 @@
 import type * as t from '../../types.d.ts';
-/** Builds and encrypts Compact JWE strings. */
+/** Produces JWE Compact Serialization using authenticated encryption. */
 export declare class CompactEncrypt {
     #private;
     /**
-     * {@link CompactEncrypt} constructor
+     * Creates an encryptor for JWE Compact Serialization.
      *
      * @param plaintext Binary representation of the plaintext to encrypt.
      */
     constructor(plaintext: Uint8Array);
     /**
-     * Sets a content encryption key to use, by default a random suitable one is generated for the JWE
-     * "enc" (Encryption Algorithm) Header Parameter.
+     * Sets a content encryption key instead of generating a random one for the JWE "enc" algorithm.
+     * May only be called once.
      *
-     * @deprecated You should not use this method. It is only really intended for test and vector
-     *   validation purposes.
+     * @deprecated Use only for testing and vector validation.
      */
     setContentEncryptionKey(cek: Uint8Array): this;
     /**
-     * Sets the JWE Initialization Vector to use for content encryption, by default a random suitable
-     * one is generated for the JWE "enc" (Encryption Algorithm) Header Parameter.
+     * Sets the content encryption IV instead of generating a random one for the JWE "enc" algorithm.
+     * May only be called once.
      *
-     * @deprecated You should not use this method. It is only really intended for test and vector
-     *   validation purposes.
+     * @deprecated Use only for testing and vector validation.
      */
     setInitializationVector(iv: Uint8Array): this;
-    /** Sets the JWE Protected Header on the CompactEncrypt object. */
+    /** Sets the JWE Protected Header. May only be called once. */
     setProtectedHeader(protectedHeader: t.CompactJWEHeaderParameters): this;
     /**
-     * Sets the JWE Key Management parameters to be used when encrypting. Use this method instead of
-     * the header setters to configure algorithm inputs such as ECDH-ES "apu" (Agreement PartyUInfo)
-     * and "apv" (Agreement PartyVInfo), or PBES2 "p2c" (PBES2 Count). The parameters are added to the
-     * appropriate JOSE Header.
+     * Sets key management inputs such as ECDH-ES "apu"/"apv" or PBES2 "p2c". Use this method instead
+     * of header setters; the resulting parameters are added to the JOSE Header. May only be called
+     * once.
      */
     setKeyManagementParameters(parameters: t.JWEKeyManagementHeaderParameters): this;
     /**
-     * Encrypts and resolves the value of the Compact JWE string.
+     * Encrypts the plaintext and returns the JWE Compact Serialization.
      *
-     * @param key Public Key or Secret to encrypt the JWE with. See
+     * @param key Public key or shared secret. See
      *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      */
     encrypt(key: t.KeyInput, options?: t.EncryptOptions): Promise<string>;

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

@@ -1,28 +1,25 @@
 import type * as t from '../../types.d.ts';
-/** Dynamic key resolver for Flattened JWE decryption. */
+/** Resolves a key for Flattened JWE decryption from unverified headers and token data. */
 export interface FlattenedDecryptGetKey<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array> extends t.GetKeyFunction<t.JWEHeaderParameters | undefined, t.FlattenedJWE, KeyType | t.KeyObject | t.JWK> {
 }
 /**
- * Decrypts a Flattened JWE.
+ * Authenticates and decrypts a flattened JWE JSON Serialization.
  *
- * @param key Private Key or Secret to decrypt the JWE with. See
+ * @param key Private key or shared secret. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  */
 export declare function flattenedDecrypt(jwe: t.FlattenedJWE, key: t.KeyInput, options?: t.DecryptOptions): Promise<t.FlattenedDecryptResult>;
 /**
- * Decrypts a Flattened JWE, resolving the key dynamically. The result additionally carries the
- * {@link t.ResolvedKey.key resolved key}.
+ * Authenticates and decrypts a flattened JWE JSON Serialization with a dynamically resolved key,
+ * included in the result.
  *
- * @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 getKey Resolves a private key or shared secret from unverified token data.
  */
 export declare function flattenedDecrypt<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array>(jwe: t.FlattenedJWE, getKey: FlattenedDecryptGetKey<KeyType>, options?: t.DecryptOptions): Promise<t.FlattenedDecryptResult & t.ResolvedKey<KeyType>>;
 /**
- * Accepts either form of the `key` argument. Use this overload when forwarding a value that may be
- * either a key or a key resolution function; `key` is present on the result only when a resolution
- * function was used.
+ * Authenticates and decrypts a flattened JWE JSON Serialization with a key or key resolver. The
+ * result includes `key` only when a resolver is used.
  *
- * @param key Private Key or Secret, or a function resolving one, to decrypt the JWE with. See
- *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param key Private key or shared secret, or a function resolving one.
  */
 export declare function flattenedDecrypt(jwe: t.FlattenedJWE, key: t.KeyInput | FlattenedDecryptGetKey, options?: t.DecryptOptions): Promise<t.FlattenedDecryptResult & Partial<t.ResolvedKey>>;

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

@@ -1,48 +1,45 @@
 import type * as t from '../../types.d.ts';
-/** Builds and encrypts Flattened JWE objects. */
+/** Produces flattened JWE JSON Serialization using authenticated encryption. */
 export declare class FlattenedEncrypt {
     #private;
     /**
-     * {@link FlattenedEncrypt} constructor
+     * Creates an encryptor for flattened JWE JSON Serialization.
      *
      * @param plaintext Binary representation of the plaintext to encrypt.
      */
     constructor(plaintext: Uint8Array);
     /**
-     * Sets the JWE Key Management parameters to be used when encrypting. Use this method instead of
-     * the header setters to configure algorithm inputs such as ECDH-ES "apu" (Agreement PartyUInfo)
-     * and "apv" (Agreement PartyVInfo), or PBES2 "p2c" (PBES2 Count). The parameters are added to the
-     * appropriate JOSE Header.
+     * Sets key management inputs such as ECDH-ES "apu"/"apv" or PBES2 "p2c". Use this method instead
+     * of header setters; the resulting parameters are added to the JOSE Header. May only be called
+     * once.
      */
     setKeyManagementParameters(parameters: t.JWEKeyManagementHeaderParameters): this;
-    /** Sets the JWE Protected Header on the FlattenedEncrypt object. */
+    /** Sets the JWE Protected Header. May only be called once. */
     setProtectedHeader(protectedHeader: t.JWEHeaderParameters): this;
-    /** Sets the JWE Shared Unprotected Header on the FlattenedEncrypt object. */
+    /** Sets the JWE Shared Unprotected Header. May only be called once. */
     setSharedUnprotectedHeader(sharedUnprotectedHeader: t.JWEHeaderParameters): this;
-    /** Sets the JWE Per-Recipient Unprotected Header on the FlattenedEncrypt object. */
+    /** Sets the JWE Per-Recipient Unprotected Header. May only be called once. */
     setUnprotectedHeader(unprotectedHeader: t.JWEHeaderParameters): this;
-    /** Sets the Additional Authenticated Data on the FlattenedEncrypt object. */
+    /** Sets the JWE AAD, which is integrity protected but not encrypted. */
     setAdditionalAuthenticatedData(aad: Uint8Array): this;
     /**
-     * Sets a content encryption key to use, by default a random suitable one is generated for the JWE
-     * "enc" (Encryption Algorithm) Header Parameter.
+     * Sets a content encryption key instead of generating a random one for the JWE "enc" algorithm.
+     * May only be called once.
      *
-     * @deprecated You should not use this method. It is only really intended for test and vector
-     *   validation purposes.
+     * @deprecated Use only for testing and vector validation.
      */
     setContentEncryptionKey(cek: Uint8Array): this;
     /**
-     * Sets the JWE Initialization Vector to use for content encryption, by default a random suitable
-     * one is generated for the JWE "enc" (Encryption Algorithm) Header Parameter.
+     * Sets the content encryption IV instead of generating a random one for the JWE "enc" algorithm.
+     * May only be called once.
      *
-     * @deprecated You should not use this method. It is only really intended for test and vector
-     *   validation purposes.
+     * @deprecated Use only for testing and vector validation.
      */
     setInitializationVector(iv: Uint8Array): this;
     /**
-     * Encrypts and resolves the value of the Flattened JWE object.
+     * Encrypts the plaintext and returns the flattened JWE JSON Serialization.
      *
-     * @param key Public Key or Secret to encrypt the JWE with. See
+     * @param key Public key or shared secret. See
      *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      */
     encrypt(key: t.KeyInput, options?: t.EncryptOptions): Promise<t.FlattenedJWE>;

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

@@ -1,34 +1,29 @@
 import type * as t from '../../types.d.ts';
-/** Dynamic key resolver for General JWE decryption. */
+/** Resolves a key for General JWE decryption from unverified headers and token data. */
 export interface GeneralDecryptGetKey<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array> extends t.GetKeyFunction<t.JWEHeaderParameters | undefined, t.FlattenedJWE, KeyType | t.KeyObject | t.JWK> {
 }
 /**
- * Decrypts a General JWE.
+ * Authenticates and decrypts a general JWE JSON Serialization.
  *
- * > Note: The function iterates over the `recipients` array in the General JWE and returns the decryption
- * > result of the first recipient entry that can be successfully decrypted. The result only contains
- * > the plaintext and headers of that successfully decrypted recipient entry. Other recipient entries
- * > in the General JWE are not validated, and their headers are not included in the returned result.
- * > Recipients of a General JWE should only rely on the returned (decrypted) data.
+ * > Note: Returns plaintext and headers from the first recipient that decrypts successfully. Other
+ * > recipients may be inspected to enforce serialization rules, but their headers are not included in
+ * > the result. Rely only on the returned data.
  *
- * @param key Private Key or Secret to decrypt the JWE with. See
+ * @param key Private key or shared secret. See
  *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
  */
 export declare function generalDecrypt(jwe: t.GeneralJWE, key: t.KeyInput, options?: t.DecryptOptions): Promise<t.GeneralDecryptResult>;
 /**
- * Decrypts a General JWE, resolving the key dynamically. The result additionally carries the
- * {@link t.ResolvedKey.key resolved key}.
+ * Authenticates and decrypts a general JWE JSON Serialization with a dynamically resolved key,
+ * included in the result.
  *
- * @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 getKey Resolves a private key or shared secret from unverified token data.
  */
 export declare function generalDecrypt<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array>(jwe: t.GeneralJWE, getKey: GeneralDecryptGetKey<KeyType>, options?: t.DecryptOptions): Promise<t.GeneralDecryptResult & t.ResolvedKey<KeyType>>;
 /**
- * Accepts either form of the `key` argument. Use this overload when forwarding a value that may be
- * either a key or a key resolution function; `key` is present on the result only when a resolution
- * function was used.
+ * Authenticates and decrypts a general JWE JSON Serialization with a key or key resolver. The
+ * result includes `key` only when a resolver is used.
  *
- * @param key Private Key or Secret, or a function resolving one, to decrypt the JWE with. See
- *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
+ * @param key Private key or shared secret, or a function resolving one.
  */
 export declare function generalDecrypt(jwe: t.GeneralJWE, key: t.KeyInput | GeneralDecryptGetKey, options?: t.DecryptOptions): Promise<t.GeneralDecryptResult & Partial<t.ResolvedKey>>;

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

@@ -1,54 +1,51 @@
 import type * as t from '../../types.d.ts';
 /** Configures an individual recipient in a General JWE. */
 export interface Recipient {
-    /** Sets the JWE Per-Recipient Unprotected Header on the Recipient object. */
+    /** Sets the JWE Per-Recipient Unprotected Header. May only be called once. */
     setUnprotectedHeader(unprotectedHeader: t.JWEHeaderParameters): Recipient;
     /**
-     * Sets the JWE Key Management parameters to be used when encrypting. Use this method instead of
-     * the header setters to configure algorithm inputs such as ECDH-ES "apu" (Agreement PartyUInfo)
-     * and "apv" (Agreement PartyVInfo), or PBES2 "p2c" (PBES2 Count). The parameters are added to the
-     * appropriate JOSE Header.
+     * Sets key management inputs such as ECDH-ES "apu"/"apv" or PBES2 "p2c". Use this method instead
+     * of header setters; the resulting parameters are added to the JOSE Header. May only be called
+     * once.
      */
     setKeyManagementParameters(parameters: t.JWEKeyManagementHeaderParameters): Recipient;
     /**
-     * A shorthand for calling {@link GeneralEncrypt.addRecipient addRecipient()} on the enclosing
-     * {@link GeneralEncrypt} instance.
+     * Adds another recipient to the enclosing {@link GeneralEncrypt} and returns its configuration.
      *
-     * @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 key Public key or shared secret. See
+     *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      */
     addRecipient(key: t.KeyInput, options?: t.CritOption): Recipient;
     /**
-     * A shorthand for calling {@link GeneralEncrypt.encrypt encrypt()} on the enclosing
-     * {@link GeneralEncrypt} instance. Takes no arguments — each recipient's key is supplied to
-     * {@link addRecipient}.
+     * Encrypts for all recipients on the enclosing {@link GeneralEncrypt}, using their configured
+     * keys.
      */
     encrypt(): Promise<t.GeneralJWE>;
-    /** Returns the enclosing {@link GeneralEncrypt} instance */
+    /** Returns the enclosing {@link GeneralEncrypt} instance. */
     done(): GeneralEncrypt;
 }
-/** Builds and encrypts General JWE objects. */
+/** Produces general JWE JSON Serialization using authenticated encryption. */
 export declare class GeneralEncrypt {
     #private;
     /**
-     * {@link GeneralEncrypt} constructor
+     * Creates an encryptor for general JWE JSON Serialization.
      *
      * @param plaintext Binary representation of the plaintext to encrypt.
      */
     constructor(plaintext: Uint8Array);
     /**
-     * Adds an additional recipient for the General JWE object.
+     * Adds a recipient and returns its configuration.
      *
-     * @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 key Public key or shared secret. See
+     *   {@link https://github.com/panva/jose/issues/210#jwe-alg Algorithm Key Requirements}.
      */
     addRecipient(key: t.KeyInput, options?: t.CritOption): Recipient;
-    /** Sets the JWE Protected Header on the GeneralEncrypt object. */
+    /** Sets the JWE Protected Header. May only be called once. */
     setProtectedHeader(protectedHeader: t.JWEHeaderParameters): this;
-    /** Sets the JWE Shared Unprotected Header on the GeneralEncrypt object. */
+    /** Sets the JWE Shared Unprotected Header. May only be called once. */
     setSharedUnprotectedHeader(sharedUnprotectedHeader: t.JWEHeaderParameters): this;
-    /** Sets the Additional Authenticated Data on the GeneralEncrypt object. */
+    /** Sets the JWE AAD, which is integrity protected but not encrypted. */
     setAdditionalAuthenticatedData(aad: Uint8Array): this;
-    /** Encrypts and resolves the value of the General JWE object. */
+    /** Encrypts the plaintext and returns the general JWE JSON Serialization. */
     encrypt(): Promise<t.GeneralJWE>;
 }

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

@@ -1,6 +1,8 @@
 import type * as t from '../types.d.ts';
 /**
- * Resolves a verification key from an embedded "jwk" (JSON Web Key) Header Parameter.
+ * Resolves a verification key from an embedded "jwk" (JSON Web Key) Header Parameter. This key
+ * resolver opts JWS and JWT verification into trusting a public key supplied by the token. Use the
+ * verification function's `algorithms` option to restrict accepted algorithms.
  *
  * @param token The consumed JWS token.
  * @returns The public key from the JWS "jwk" (JSON Web Key) Header Parameter.

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

@@ -1,17 +1,15 @@
 import type * as t from '../types.d.ts';
 /**
- * Calculates a base64url-encoded JSON Web Key (JWK) Thumbprint.
+ * Calculates a base64url-encoded JWK Thumbprint. CryptoKey inputs must be extractable.
  *
  * @param key Key to calculate the thumbprint for.
- * @param digestAlgorithm Digest Algorithm to use for calculating the thumbprint. Default is
- *   "sha256".
+ * @param digestAlgorithm Digest algorithm. Defaults to "sha256".
  */
 export declare function calculateJwkThumbprint(key: t.JWK | t.CryptoKey | t.KeyObject, digestAlgorithm?: 'sha256' | 'sha384' | 'sha512'): Promise<string>;
 /**
- * Calculates a JSON Web Key (JWK) Thumbprint URI.
+ * Calculates a JWK Thumbprint URI. CryptoKey inputs must be extractable.
  *
  * @param key Key to calculate the thumbprint for.
- * @param digestAlgorithm Digest Algorithm to use for calculating the thumbprint. Default is
- *   "sha256".
+ * @param digestAlgorithm Digest algorithm. Defaults to "sha256".
  */
 export declare function calculateJwkThumbprintUri(key: t.CryptoKey | t.KeyObject | t.JWK, digestAlgorithm?: 'sha256' | 'sha384' | 'sha512'): Promise<string>;

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

@@ -2,14 +2,15 @@ import type * as t from '../types.d.ts';
 /** A key resolver created by {@link createLocalJWKSet}. */
 export interface LocalJWKSet {
     (protectedHeader?: t.JWSHeaderParameters, token?: t.FlattenedJWSInput): Promise<t.CryptoKey>;
-    /** Returns a structured clone of the JSON Web Key Set this resolver was created with. */
+    /** Returns a structured clone of the original JSON Web Key Set. */
     jwks: () => t.JSONWebKeySet;
 }
 /**
- * Creates a resolver for a locally available JSON Web Key Set.
+ * Creates a resolver for a locally available JSON Web Key Set. Selection uses the header's "alg"
+ * (Algorithm) and "kid" (Key ID), and respects the JWK's "use" (Public Key Use) and "key_ops" (Key
+ * Operations). Exactly one key must match.
  *
- * > Note: The function's purpose is to resolve public keys used for verifying signatures and will not work
- * > for public encryption keys.
+ * > Note: Only public signature verification keys are supported, not public encryption keys.
  *
  * @param jwks JSON Web Key Set formatted object.
  */

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

@@ -1,20 +1,18 @@
 import type * as t from '../types.d.ts';
 /**
- * Symbol used to configure a custom fetch implementation for remote JWKS retrieval.
+ * Configures a custom fetch implementation for remote JWKS retrieval.
  *
- * > Note: Known caveat: Expect Type-related issues when passing the inputs through to fetch-like modules,
- * > they hardly ever get their typings inline with actual fetch, you should `@ts-expect-error` them.
+ * > Note: Fetch-like libraries may have incompatible TypeScript signatures even when they accept the
+ * > supplied arguments at runtime.
  */
 export declare const customFetch: unique symbol;
-/** Function signature accepted by {@link customFetch}. */
+/** Custom fetch function. Must return HTTP 200 with a JSON JWKS. See {@link customFetch}. */
 export type FetchImplementation = (
-/** URL the request is being made sent to {@link !fetch} as the `resource` argument */
+/** JWKS URL, passed as the fetch resource. */
 url: string, 
-/** Options otherwise sent to {@link !fetch} as the `options` argument */
+/** Options passed to fetch. */
 options: {
-    /** HTTP Headers */
     headers: Headers;
-    /** The {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods request method} */
     method: 'GET';
     /** See {@link !Request.redirect} */
     redirect: 'manual';
@@ -23,9 +21,8 @@ options: {
 /**
  * Symbol used to configure an externally persisted remote JWKS cache.
  *
- * > Warning: This option has security implications that must be understood, assessed for applicability, and
- * > accepted before use. It is critical that the JSON Web Key Set cache only be writable by your own
- * > code.
+ * > Warning: Only trusted application code must be allowed to write this cache; its keys are trusted for
+ * > signature verification.
  */
 export declare const jwksCache: unique symbol;
 /** Remote JWKS resolver options. */
@@ -36,13 +33,13 @@ export interface RemoteJWKSetOptions {
      */
     timeoutDuration?: number;
     /**
-     * Duration (in milliseconds) for which no more HTTP requests will be triggered after a previous
-     * successful fetch. Must not be `NaN`. Default is 30000 (30 seconds).
+     * Time in milliseconds after a successful fetch before a missing key can trigger another fetch.
+     * Must not be `NaN`. Defaults to 30000 (30 seconds).
      */
     cooldownDuration?: number;
     /**
-     * Maximum time (in milliseconds) between successful HTTP requests. Default is 600000 (10
-     * minutes). Must not be `NaN`.
+     * Maximum age of cached keys in milliseconds. Defaults to 600000 (10 minutes); `Infinity`
+     * disables expiry. Must not be `NaN`.
      */
     cacheMaxAge?: number | typeof Infinity;
     /** Headers to be sent with the HTTP request. */
@@ -56,7 +53,7 @@ export interface RemoteJWKSetOptions {
 export interface ExportedJWKSCache {
     /** Current cached JSON Web Key Set */
     jwks: t.JSONWebKeySet;
-    /** Last updated at timestamp (milliseconds since epoch) */
+    /** Last successful fetch, in milliseconds since Unix epoch. */
     uat: number;
 }
 /** Values accepted by the {@link jwksCache} option. */
@@ -79,16 +76,18 @@ export interface RemoteJWKSet {
      */
     reload: () => Promise<void>;
     /**
-     * The currently cached JSON Web Key Set, or `undefined` when none has been fetched or seeded via
-     * {@link jwksCache} yet.
+     * Returns a structured clone of the cached JSON Web Key Set, or `undefined` before keys have been
+     * fetched or seeded via {@link jwksCache}.
      */
     jwks: () => t.JSONWebKeySet | undefined;
 }
 /**
- * Creates a resolver for a JSON Web Key Set available at an HTTP(S) URL.
+ * Creates a resolver for a JSON Web Key Set available at an HTTP(S) URL. Fetches the JSON Web Key
+ * Set when the cache is missing or stale. An unmatched key triggers another fetch only when
+ * `cooldownDuration` has elapsed since the last successful fetch. Selection uses the header's "alg"
+ * and "kid" and respects the JWK's "use" and "key_ops". Exactly one key must match.
  *
- * > Note: The function's purpose is to resolve public keys used for verifying signatures and will not work
- * > for public encryption keys.
+ * > Note: Only public signature verification keys are supported, not public encryption keys.
  *
  * @param url URL to fetch the JSON Web Key Set from.
  */

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

@@ -1,19 +1,20 @@
 import type * as t from '../../types.d.ts';
-/** Builds and signs Compact JWS strings. */
+/** Produces JWS Compact Serialization using a digital signature or MAC. */
 export declare class CompactSign {
     #private;
     /**
-     * {@link CompactSign} constructor
+     * Creates a signer for JWS Compact Serialization.
      *
-     * @param payload Binary representation of the payload to sign.
+     * @param payload JWS Payload bytes to sign or MAC.
      */
     constructor(payload: Uint8Array);
-    /** Sets the JWS Protected Header on the CompactSign object. */
+    /** Sets the JWS Protected Header. May only be called once. */
     setProtectedHeader(protectedHeader: t.CompactJWSHeaderParameters): this;
     /**
-     * Signs and resolves the value of the Compact JWS string.
+     * Computes the JWS Signature (digital signature or MAC) and returns the JWS Compact
+     * Serialization.
      *
-     * @param key Private Key or Secret to sign the JWS with. See
+     * @param key Private key or shared secret. See
      *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
      */
     sign(key: t.KeyInput, options?: t.SignOptions): Promise<string>;

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

@@ -1,28 +1,25 @@
 import type * as t from '../../types.d.ts';
-/** Dynamic key resolver for Compact JWS verification. */
+/** Resolves a key for Compact JWS verification from unverified headers and token data. */
 export interface CompactVerifyGetKey<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array> extends t.GetKeyFunction<t.CompactJWSHeaderParameters, t.FlattenedJWSInput, KeyType | t.KeyObject | t.JWK> {
 }
 /**
- * Verifies a Compact JWS signature and decodes its payload.
+ * Validates a JWS Compact Serialization (digital signature or MAC) and decodes its JWS Payload.
  *
- * @param key Key to verify the JWS with. See
+ * @param key Public key or shared secret. See
  *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
  */
 export declare function compactVerify(jws: string | Uint8Array, key: t.KeyInput, options?: t.VerifyOptions): Promise<t.CompactVerifyResult>;
 /**
- * Verifies a Compact JWS signature and decodes its payload, resolving the key dynamically. The
- * result additionally carries the {@link t.ResolvedKey.key resolved key}.
+ * Validates a JWS Compact Serialization (digital signature or MAC) and decodes its JWS Payload with
+ * a dynamically resolved key, included in the result.
  *
- * @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 getKey Resolves a public key or shared secret from unverified token data.
  */
 export declare function compactVerify<KeyType extends t.CryptoKey | Uint8Array = t.CryptoKey | Uint8Array>(jws: string | Uint8Array, getKey: CompactVerifyGetKey<KeyType>, options?: t.VerifyOptions): Promise<t.CompactVerifyResult & t.ResolvedKey<KeyType>>;
 /**
- * Accepts either form of the `key` argument. Use this overload when forwarding a value that may be
- * either a key or a key resolution function; `key` is present on the result only when a resolution
- * function was used.
+ * Validates a JWS Compact Serialization (digital signature or MAC) and decodes its JWS Payload
+ * using a key or key resolver. The result includes `key` only when a resolver is used.
  *
- * @param key Key, or function resolving a key, to verify the JWS with. See
- *   {@link https://github.com/panva/jose/issues/210#jws-alg Algorithm Key Requirements}.
+ * @param key Public key or shared secret, or a function resolving one.
  */
 export declare function compactVerify(jws: string | Uint8Array, key: t.KeyInput | CompactVerifyGetKey, options?: t.VerifyOptions): Promise<t.CompactVerifyResult & Partial<t.ResolvedKey>>;