jose 4.5.3 → 4.6.2

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

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

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

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

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

@@ -1,20 +1,83 @@
 import type { KeyLike, GeneralJWE, JWEHeaderParameters, CritOption, DeflateOption } from '../../types';
 export interface Recipient {
+    /**
+     * Sets the JWE Per-Recipient Unprotected Header on the Recipient object.
+     *
+     * @param unprotectedHeader JWE Per-Recipient Unprotected Header.
+     */
     setUnprotectedHeader(unprotectedHeader: JWEHeaderParameters): Recipient;
+    /**
+     * A shorthand for calling addRecipient() on the enclosing GeneralEncrypt instance
+     */
     addRecipient(...args: Parameters<GeneralEncrypt['addRecipient']>): Recipient;
+    /**
+     * A shorthand for calling encrypt() on the enclosing GeneralEncrypt instance
+     */
     encrypt(...args: Parameters<GeneralEncrypt['encrypt']>): Promise<GeneralJWE>;
+    /**
+     * Returns the enclosing GeneralEncrypt
+     */
     done(): GeneralEncrypt;
 }
+/**
+ * The GeneralEncrypt class is a utility for creating 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;
     private _recipients;
     private _protectedHeader;
     private _unprotectedHeader;
     private _aad;
+    /**
+     * @param plaintext Binary representation of the plaintext to encrypt.
+     */
     constructor(plaintext: Uint8Array);
+    /**
+     * 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.
+     * @param options JWE Encryption options.
+     */
     addRecipient(key: KeyLike | Uint8Array, options?: CritOption): Recipient;
+    /**
+     * Sets the JWE Protected Header on the GeneralEncrypt object.
+     *
+     * @param protectedHeader JWE Protected Header object.
+     */
     setProtectedHeader(protectedHeader: JWEHeaderParameters): this;
+    /**
+     * Sets the JWE Shared Unprotected Header on the GeneralEncrypt object.
+     *
+     * @param sharedUnprotectedHeader JWE Shared Unprotected Header object.
+     */
     setSharedUnprotectedHeader(sharedUnprotectedHeader: JWEHeaderParameters): this;
+    /**
+     * Sets the Additional Authenticated Data on the GeneralEncrypt object.
+     *
+     * @param aad Additional Authenticated Data.
+     */
     setAdditionalAuthenticatedData(aad: Uint8Array): this;
+    /**
+     * Encrypts and resolves the value of the General JWE object.
+     *
+     * @param options JWE Encryption options.
+     */
     encrypt(options?: DeflateOption): Promise<GeneralJWE>;
 }

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

@@ -1,2 +1,22 @@
 import type { FlattenedJWSInput, JWSHeaderParameters } from '../types';
+/**
+ * EmbeddedJWK is an implementation of a GetKeyFunction intended to be used with the
+ * JWS/JWT verify operations whenever you need to opt-in to verify signatures with
+ * a public key embedded in the token's "jwk" (JSON Web Key) Header Parameter.
+ * It is recommended to combine this with the verify algorithms option to whitelist
+ * JWS algorithms to accept.
+ *
+ * @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(protectedHeader: JWSHeaderParameters, token: FlattenedJWSInput): Promise<import("../types.d").KeyLike>;

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

@@ -1,2 +1,21 @@
 import type { JWK } from '../types';
+/**
+ * Calculates a base64url-encoded JSON Web Key (JWK) Thumbprint as per
+ * [RFC7638](https://www.rfc-editor.org/rfc/rfc7638).
+ *
+ * @param jwk JSON Web Key.
+ * @param digestAlgorithm Digest Algorithm to use for calculating the thumbprint.
+ * Default is sha256. Accepted is "sha256", "sha384", "sha512".
+ *
+ * @example Usage
+ * ```js
+ * const thumbprint = await jose.calculateJwkThumbprint({
+ *   kty: 'RSA',
+ *   e: 'AQAB',
+ *   n: '12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ'
+ * })
+ *
+ * console.log(thumbprint)
+ * ```
+ */
 export declare function calculateJwkThumbprint(jwk: JWK, digestAlgorithm?: 'sha256' | 'sha384' | 'sha512'): Promise<string>;

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

@@ -1,9 +1,51 @@
 import type { KeyLike, JWSHeaderParameters, JSONWebKeySet, FlattenedJWSInput, GetKeyFunction } from '../types';
+/**
+ * @private
+ */
 export declare function isJWKSLike(jwks: unknown): jwks is JSONWebKeySet;
+/**
+ * @private
+ */
 export declare class LocalJWKSet {
     protected _jwks?: JSONWebKeySet;
     private _cached;
     constructor(jwks: unknown);
     getKey(protectedHeader: JWSHeaderParameters, token: FlattenedJWSInput): Promise<KeyLike>;
 }
+/**
+ * Returns a function that resolves to a key object from a locally
+ * stored, or otherwise available, JSON Web Key Set.
+ *
+ * Only a single public key must match the selection process.
+ *
+ * @param jwks JSON Web Key Set formatted object.
+ *
+ * @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)
+ * ```
+ */
 export declare function createLocalJWKSet(jwks: JSONWebKeySet): GetKeyFunction<JWSHeaderParameters, FlattenedJWSInput>;

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

@@ -1,11 +1,55 @@
 import type { JWSHeaderParameters, FlattenedJWSInput, GetKeyFunction } from '../types';
+/**
+ * Options for the remote JSON Web Key Set.
+ */
 export interface RemoteJWKSetOptions {
+    /**
+     * Timeout (in milliseconds) for the HTTP request. When reached the request will be
+     * aborted and the verification will fail. Default is 5000.
+     */
     timeoutDuration?: number;
+    /**
+     * Duration (in milliseconds) for which no more HTTP requests will be triggered
+     * after a previous successful fetch. Default is 30000.
+     */
     cooldownDuration?: number;
+    /**
+     * An instance of [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent)
+     * or [https.Agent](https://nodejs.org/api/https.html#https_class_https_agent) to pass
+     * to the [http.get](https://nodejs.org/api/http.html#http_http_get_options_callback)
+     * or [https.get](https://nodejs.org/api/https.html#https_https_get_options_callback)
+     * 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;
 }
 interface URL {
     href: string;
 }
+/**
+ * Returns a function that resolves to a key object downloaded from a
+ * remote endpoint returning a JSON Web Key Set, that is, for example,
+ * an OAuth 2.0 or OIDC jwks_uri. Only a single public key must match
+ * the selection process.
+ * The JSON Web Key Set is fetched when no key matches the selection
+ * process but only as frequently as the `cooldownDuration` option allows,
+ * to prevent abuse.
+ *
+ * @param url URL to fetch the JSON Web Key Set from.
+ * @param options Options for the remote JSON Web Key Set.
+ *
+ * @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)
+ * ```
+ */
 export declare function createRemoteJWKSet(url: URL, options?: RemoteJWKSetOptions): GetKeyFunction<JWSHeaderParameters, FlattenedJWSInput>;
 export {};

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

@@ -1,7 +1,37 @@
 import type { CompactJWSHeaderParameters, KeyLike, SignOptions } from '../../types';
+/**
+ * The CompactSign class is a utility for creating 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;
+    /**
+     * @param payload Binary representation of the payload to sign.
+     */
     constructor(payload: Uint8Array);
+    /**
+     * Sets the JWS Protected Header on the Sign object.
+     *
+     * @param protectedHeader JWS Protected Header.
+     */
     setProtectedHeader(protectedHeader: CompactJWSHeaderParameters): this;
+    /**
+     * Signs and resolves the value of the Compact JWS string.
+     *
+     * @param key Private Key or Secret to sign the JWS with.
+     * @param options JWS Sign options.
+     */
     sign(key: KeyLike | Uint8Array, options?: SignOptions): Promise<string>;
 }

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

@@ -1,5 +1,34 @@
 import type { CompactVerifyResult, FlattenedJWSInput, GetKeyFunction, CompactJWSHeaderParameters, KeyLike, VerifyOptions, ResolvedKey } from '../../types';
+/**
+ * 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.
+ */
 export interface CompactVerifyGetKey extends GetKeyFunction<CompactJWSHeaderParameters, FlattenedJWSInput> {
 }
+/**
+ * Verifies the signature and format of and afterwards decodes the Compact JWS.
+ *
+ * @param jws Compact JWS.
+ * @param key Key to verify the JWS with.
+ * @param options JWS Verify options.
+ *
+ * @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))
+ * ```
+ */
 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 options JWS Verify options.
+ */
 export declare function compactVerify(jws: string | Uint8Array, getKey: CompactVerifyGetKey, options?: VerifyOptions): Promise<CompactVerifyResult & ResolvedKey>;

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

@@ -1,10 +1,45 @@
 import type { KeyLike, FlattenedJWS, JWSHeaderParameters, SignOptions } from '../../types';
+/**
+ * The FlattenedSign class is a utility for creating 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;
     private _protectedHeader;
     private _unprotectedHeader;
+    /**
+     * @param payload Binary representation of the payload to sign.
+     */
     constructor(payload: Uint8Array);
+    /**
+     * Sets the JWS Protected Header on the FlattenedSign object.
+     *
+     * @param protectedHeader JWS Protected Header.
+     */
     setProtectedHeader(protectedHeader: JWSHeaderParameters): this;
+    /**
+     * Sets the JWS Unprotected Header on the FlattenedSign object.
+     *
+     * @param unprotectedHeader JWS Unprotected Header.
+     */
     setUnprotectedHeader(unprotectedHeader: JWSHeaderParameters): this;
+    /**
+     * Signs and resolves the value of the Flattened JWS object.
+     *
+     * @param key Private Key or Secret to sign the JWS with.
+     * @param options JWS Sign options.
+     */
     sign(key: KeyLike | Uint8Array, options?: SignOptions): Promise<FlattenedJWS>;
 }

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

@@ -1,5 +1,39 @@
 import type { FlattenedVerifyResult, KeyLike, FlattenedJWSInput, JWSHeaderParameters, VerifyOptions, GetKeyFunction, ResolvedKey } from '../../types';
+/**
+ * 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.
+ */
 export interface FlattenedVerifyGetKey extends GetKeyFunction<JWSHeaderParameters | undefined, FlattenedJWSInput> {
 }
+/**
+ * Verifies the signature and format of and afterwards decodes the Flattened JWS.
+ *
+ * @param jws Flattened JWS.
+ * @param key Key to verify the JWS with.
+ * @param options JWS Verify options.
+ *
+ * @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))
+ * ```
+ */
 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 options JWS Verify options.
+ */
 export declare function flattenedVerify(jws: FlattenedJWSInput, getKey: FlattenedVerifyGetKey, options?: VerifyOptions): Promise<FlattenedVerifyResult & ResolvedKey>;

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

@@ -1,15 +1,65 @@
 import type { KeyLike, GeneralJWS, JWSHeaderParameters, SignOptions } from '../../types';
 export interface Signature {
+    /**
+     * Sets the JWS Protected Header on the Signature object.
+     *
+     * @param protectedHeader JWS Protected Header.
+     */
     setProtectedHeader(protectedHeader: JWSHeaderParameters): Signature;
+    /**
+     * Sets the JWS Unprotected Header on the Signature object.
+     *
+     * @param unprotectedHeader JWS Unprotected Header.
+     */
     setUnprotectedHeader(unprotectedHeader: JWSHeaderParameters): Signature;
+    /**
+     * A shorthand for calling addSignature() on the enclosing GeneralSign instance
+     */
     addSignature(...args: Parameters<GeneralSign['addSignature']>): Signature;
+    /**
+     * A shorthand for calling encrypt() on the enclosing GeneralSign instance
+     */
     sign(...args: Parameters<GeneralSign['sign']>): Promise<GeneralJWS>;
+    /**
+     * Returns the enclosing GeneralSign
+     */
     done(): GeneralSign;
 }
+/**
+ * The GeneralSign class is a utility for creating 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;
     private _signatures;
+    /**
+     * @param payload Binary representation of the payload to sign.
+     */
     constructor(payload: Uint8Array);
+    /**
+     * Adds an additional signature for the General JWS object.
+     *
+     * @param key Private Key or Secret to sign the individual JWS signature with.
+     * @param options JWS Sign options.
+     */
     addSignature(key: KeyLike | Uint8Array, options?: SignOptions): Signature;
+    /**
+     * Signs and resolves the value of the General JWS object.
+     */
     sign(): Promise<GeneralJWS>;
 }

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

@@ -1,5 +1,42 @@
 import type { GeneralJWSInput, GeneralVerifyResult, FlattenedJWSInput, GetKeyFunction, JWSHeaderParameters, KeyLike, VerifyOptions, ResolvedKey } from '../../types';
+/**
+ * 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.
+ */
 export interface GeneralVerifyGetKey extends GetKeyFunction<JWSHeaderParameters, FlattenedJWSInput> {
 }
+/**
+ * Verifies the signature and format of and afterwards decodes the General JWS.
+ *
+ * @param jws General JWS.
+ * @param key Key to verify the JWS with.
+ * @param options JWS Verify options.
+ *
+ * @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))
+ * ```
+ */
 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 options JWS Verify options.
+ */
 export declare function generalVerify(jws: GeneralJWSInput, getKey: GeneralVerifyGetKey, options?: VerifyOptions): Promise<GeneralVerifyResult & ResolvedKey>;