unjwt 0.8.5 → 0.9.1

package/dist/_chunks/index.d.mts

@@ -1,5 +1,5 @@
 import { JWTError } from "./error.mjs";
-/** Header Parameters common to JWE and JWS. */
+/** Header Parameters common to JWS and JWE (RFC 7515 §4.1, RFC 7516 §4.1). */
 export interface JoseHeaderParameters {
   /** "kid" (Key ID) Header Parameter */
   kid?: string;
@@ -21,9 +21,9 @@ export interface JoseHeaderParameters {
   crit?: string[];
   [propName: string]: unknown;
 }
-/** Payload accepted by `sign` and `encrypt`: a string, raw bytes, or a JSON object. */
+/** A payload for `sign` and `encrypt`: a string, raw bytes, or an object serialized as JSON. */
 export type JOSEPayload = string | Uint8Array<ArrayBuffer> | object;
-/** How a verified or decrypted payload is decoded: `"json"` object, UTF-8 `"string"`, or raw `"bytes"`. */
+/** How a verified or decrypted payload is returned: a `"json"` object, a UTF-8 `"string"`, or raw `"bytes"`. */
 export type JOSEPayloadMode = keyof JOSEPayloadTypeMap;
 /** The payload type each `JOSEPayloadMode` resolves to. */
 export interface JOSEPayloadTypeMap<T = JWTClaims> {
@@ -31,24 +31,25 @@ export interface JOSEPayloadTypeMap<T = JWTClaims> {
   string: string;
   bytes: Uint8Array<ArrayBuffer>;
 }
-/** The payload type returned under `Mode`; a union of modes yields the union of payloads. */
+/** The payload type returned under `Mode`. A union of modes gives the union of their payloads. */
 export type PayloadOf<Mode extends JOSEPayloadMode, T = JWTClaims> = JOSEPayloadTypeMap<T>[Mode];
 /** "cnf" (Confirmation) Claim members (RFC 7800 §3.1), with `jkt` (RFC 9449 §6.1) and `x5t#S256` (RFC 8705 §3.1). */
 export interface JWTConfirmation {
-  /** The proof-of-possession key as a public JWK */
+  /** The proof-of-possession key as a public JWK. `sign` and `encrypt` throw `ERR_JWT_CLAIM_INVALID` for a private or malformed one. */
   "jwk"?: JWK_Public;
-  /** The proof-of-possession key as an encrypted JWK, a JWE in compact serialization */
+  /** The proof-of-possession key as an encrypted JWK, in JWE Compact Serialization. */
   "jwe"?: string;
-  /** A Key ID the recipient resolves out of band */
+  /** The Key ID of a proof-of-possession key the recipient already holds. */
   "kid"?: string;
-  /** A JWK Set URL holding the key, selected by `kid` */
+  /** The URL of a JWK Set that holds the key, selected by `kid`. */
   "jku"?: string;
-  /** The RFC 7638 SHA-256 thumbprint of the DPoP public key */
+  /** The RFC 7638 SHA-256 thumbprint of the DPoP public key. */
   "jkt"?: string;
-  /** The SHA-256 thumbprint of the client certificate, base64url */
+  /** The base64url SHA-256 thumbprint of the client certificate. */
   "x5t#S256"?: string;
   [member: string]: unknown;
 }
+/** JWT claims (RFC 7519 §4.1). `verify` and `decrypt` check the registered ones against {@link JWTClaimValidationOptions}. */
 export interface JWTClaims {
   /** "iss" (Issuer) Claim */
   iss?: string;
@@ -64,10 +65,11 @@ export interface JWTClaims {
   iat?: number;
   /** "jti" (JWT ID) Claim */
   jti?: string;
-  /** "cnf" (Confirmation) Claim, the proof-of-possession key; never validated, read by the application */
+  /** "cnf" (Confirmation) Claim: the proof-of-possession key (RFC 7800). `verify` and `decrypt` do not check it. */
   cnf?: JWTConfirmation;
   [propName: string]: unknown;
 }
+/** A decoded JWT: its JOSE header and its claims. */
 export interface JWT<T = JWTClaims> {
   header: JoseHeaderParameters & {
     /** "alg" (Algorithm) Header Parameter */
@@ -75,127 +77,130 @@ export interface JWT<T = JWTClaims> {
   };
   claims: T;
 }
-/** Per-call work bounds; each entry must be a positive integer, else `ERR_INVALID_OPTION`. */
+/** Work limits for one call. Each entry is a positive integer, else the call throws `ERR_INVALID_OPTION`. */
 export interface JOSELimits {
-  /** Max `signatures[]` entries in a JWS JSON serialization. @default 16 */
+  /** Max `signatures[]` entries in a JWS JSON Serialization. More throws `ERR_JWS_INVALID`. @default 16 */
   signatures?: number;
-  /** Max `recipients[]` entries in a JWE JSON serialization. @default 16 */
+  /** Max `recipients[]` entries in a JWE JSON Serialization. More throws `ERR_JWE_INVALID`. @default 16 */
   recipients?: number;
-  /** Max JWK Set candidates tried per token after `kid`/`alg`/`use` filtering. @default 8 */
+  /** Max JWK Set keys tried per token, after filtering by `kid`, `alg` and `use`. More throws `ERR_JWK_KEY_NOT_FOUND`. @default 8 */
   keyCandidates?: number;
-  /** Total PBKDF2 iterations one call may spend across PBES2 attempts. @default 2_400_000 */
+  /** Max key trials over all entries of one `verifyMulti`, `verifyMultiAll` or `decryptMulti` call. One trial is one signature check or unwrap with one key. More throws `ERR_JWK_KEY_NOT_FOUND`. @default 16 */
+  keyAttempts?: number;
+  /** Max PBKDF2 iterations over all PBES2 attempts of one call. More throws `ERR_JWE_INVALID`. @default 2_400_000 */
   pbes2Iterations?: number;
 }
-/** Claim expectations, each checked when set; an empty or malformed value is `ERR_INVALID_OPTION`. */
+/** Claim expectations, each checked when set. A malformed value throws `ERR_INVALID_OPTION`. */
 export interface JWTClaimValidationOptions {
-  /** Expected "aud" value(s); `aud` is checked only when this is set (RFC 7519 §4.1.3). */
+  /** Accepted `aud` values. The token passes when its `aud` holds one of them (RFC 7519 §4.1.3). Implies presence. */
   audience?: string | string[];
-  /** Expected "iss" value(s); implies presence. */
+  /** Accepted `iss` values. Implies presence. */
   issuer?: string | string[];
-  /** Expected "sub" value; implies presence. */
+  /** Expected `sub` value. Implies presence. */
   subject?: string;
-  /** Maximum token age from "iat"; implies presence. */
+  /** Oldest accepted `iat`, counted back from `currentDate`. Older throws `ERR_JWT_EXPIRED`. Implies `iat` presence. */
   maxTokenAge?: MaxTokenAge;
-  /** Clock skew tolerance for nbf/exp/iat, in seconds or a `Duration`. @default 0 */
+  /** Clock skew allowed on `exp`, `nbf` and `iat`: non-negative seconds or a `Duration`. @default 0 */
   clockTolerance?: number | Duration;
-  /** Expected "typ" header, compared as a media type (RFC 7515 §4.1.9); implies presence. */
+  /** Expected `typ` of the protected header, compared as a media type (RFC 7515 §4.1.9). A missing or different `typ` throws `ERR_JWS_INVALID` or `ERR_JWE_INVALID`. */
   typ?: string;
-  /** Date used for NumericDate comparisons. @default new Date() */
+  /** The time the claims are checked against. @default new Date() */
   currentDate?: Date;
-  /** Additional required claim names. */
+  /** Claim names the token must contain, else `ERR_JWT_CLAIM_MISSING`. */
   requiredClaims?: string[];
-  /** `crit` header parameters the caller understands (RFC 7515 §4.1.11, RFC 7516 §4.1.13). */
+  /** `crit` Header Parameters the caller understands (RFC 7515 §4.1.11, RFC 7516 §4.1.13). Any other `crit` entry throws. */
   recognizedHeaders?: string[];
 }
-/** Time claims a producer computes; a claim already in the payload is kept as given. */
+/** Time claims `sign` and `encrypt` write into an object payload. A claim already in the payload is kept. Any of these options with a string or bytes payload throws `ERR_INVALID_OPTION`. */
 export interface JWTTimeClaimOptions {
-  /** The clock: `iat` when written, and the base of `expiresIn` / `notBeforeIn`. @default new Date() */
+  /** The current time: the written `iat`, and the base of `expiresIn` and `notBeforeIn`. @default new Date() */
   currentDate?: Date;
-  /** Writes `iat` on its own: `true` as `currentDate`, a `Date` as that instant; `false` is unset. `exp`/`nbf` options write it either way. */
+  /** Writes `iat`: `true` as `currentDate`, a `Date` as that instant. Any `exp` or `nbf` option writes `iat` too, even when this is `false`. */
   issuedAt?: boolean | Date;
-  /** Duration from `currentDate` until `exp`; exclusive with `expiresAt`. */
+  /** Sets `exp` to `currentDate` plus this positive duration. Setting `expiresAt` too throws `ERR_JWT_CLAIM_INVALID`. */
   expiresIn?: ExpiresIn;
-  /** Absolute `exp`; exclusive with `expiresIn`. */
+  /** Sets `exp` to this instant. Setting `expiresIn` too throws `ERR_JWT_CLAIM_INVALID`. */
   expiresAt?: Date;
-  /** Duration from `currentDate` until `nbf` (`0` sets `nbf` to it); exclusive with `notBeforeAt`. */
+  /** Sets `nbf` to `currentDate` plus this duration, zero or more. Setting `notBeforeAt` too throws `ERR_JWT_CLAIM_INVALID`. */
   notBeforeIn?: ExpiresIn;
-  /** Absolute `nbf` (RFC 7519 §4.1.5); exclusive with `notBeforeIn`. */
+  /** Sets `nbf` to this instant (RFC 7519 §4.1.5). Setting `notBeforeIn` too throws `ERR_JWT_CLAIM_INVALID`. */
   notBeforeAt?: Date;
 }
-/** Options shared by `verify` and `decrypt` (compact and multi). */
+/** Options shared by `verify`, `decrypt` and their multi variants. */
 export interface JOSEConsumerOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> extends JWTClaimValidationOptions {
-  /**
-   * Admit `oct` entries of a JWK Set as key material; only for application-controlled sets. @default false
-   * @deprecated A JWK Set is key material the caller chose to trust, so its `oct` entries count like any other; the option goes away and symmetric entries are admitted without it.
-   */
-  allowSymmetricJWKSet?: boolean;
-  /** Payload decoding mode; a mismatch is `ERR_JWS_INVALID` / `ERR_JWE_INVALID`. @default "json" */
+  /** How the payload is returned. Under `"json"`, a payload that is not a JSON object throws `ERR_JWS_INVALID` or `ERR_JWE_INVALID`. @default "json" */
   payload?: Mode;
   /**
-   * If true, forces the payload to be returned as a `Uint8Array`.
-   *
-   * @deprecated Use `payload: "bytes"`. Deprecated in v0.8.0, removed in v0.9.0
+   * `false` skips claim validation. Claims are checked only under `payload: "json"`.
+   * `true` with another payload, or a claim option (`audience`, `issuer`, `subject`, `maxTokenAge`, `requiredClaims`) while claims go unchecked, throws `ERR_INVALID_OPTION`.
+   * @default true
    */
-  forceUint8Array?: boolean;
-  /** `false` skips claim validation; `true` with a non-`"json"` payload is `ERR_INVALID_OPTION`. */
   validateClaims?: boolean;
 }
 export type StrictOmit<T, K extends keyof T | (string & {}) | (number & {}) | (symbol & {})> = { [P in keyof T as P extends K ? never : P]: T[P]; };
-/** JWS Signing Algorithm Identifier. */
+/** A JWS signing algorithm (RFC 7518 §3, RFC 8037 §3.1). */
 export type JWSAlgorithm = JWK_HMAC | JWK_RSA_SIGN | JWK_RSA_PSS | JWK_ECDSA | JWK_OKP_SIGN;
-/** A key lookup for `verify`: it receives the validated JWS header. */
+/** A key lookup for `verify` and the multi variants. It receives `{ header, token }`: the decoded JWS header and the token. */
 export type JWSKeyLookup<TReturn = CryptoKey | JWK | JWKSet | string | Uint8Array<ArrayBuffer>> = JWKLookupFunction<TReturn, JWSHeaderParameters>;
-/** JWS algorithms that name their digest (`*256`/`*384`/`*512`); EdDSA does not. */
+/** The JWS algorithms that name their digest (`*256`, `*384`, `*512`). `EdDSA` and `Ed25519` do not. */
 export type JWSHashedAlgorithm = Exclude<JWSAlgorithm, JWK_OKP_SIGN>;
-/** Asymmetric private JWKs admissible as a signing key. */
+/** The asymmetric private JWKs that can sign. */
 export type JWSAsymmetricPrivateJWK = JWK_RSA_Private<JWK_RSA_SIGN | JWK_RSA_PSS> | JWK_EC_Private<JWK_ECDSA> | JWK_OKP_Private<JWK_OKP_SIGN>;
-/** Asymmetric public JWKs admissible as a verification key. */
+/** The asymmetric public JWKs that can verify. */
 export type JWSAsymmetricPublicJWK = JWK_RSA_Public<JWK_RSA_SIGN | JWK_RSA_PSS> | JWK_EC_Public<JWK_ECDSA> | JWK_OKP_Public<JWK_OKP_SIGN>;
-/** JWKs admissible as a `sign` key; a non-signing `alg` is a type error. */
+/** The JWKs `sign` accepts. A JWK whose `alg` is not a signing algorithm is a type error. */
 export type JWSSignJWK = JWK_oct<JWK_HMAC> | JWSAsymmetricPrivateJWK;
-/** JWKs admissible as a `verify` key; a non-signing `alg` is a type error. */
+/** The JWKs `verify` accepts. A JWK whose `alg` is not a signing algorithm is a type error. */
 export type JWSVerifyJWK = JWK_oct<JWK_HMAC> | JWSAsymmetricPublicJWK;
-/** Recognized JWS Header Parameters; other members may be present. */
+/** JWS Header Parameters (RFC 7515 §4.1). Other members are allowed. */
 export interface JWSHeaderParameters extends JoseHeaderParameters {
-  /** JWS "alg" (Algorithm) Header Parameter */
+  /** "alg" (Algorithm) Header Parameter */
   alg?: JWSAlgorithm;
-  /** `false` signs the payload unencoded (RFC 7797). @default true */
+  /** `false` signs the payload unencoded (RFC 7797). Allowed in the protected header only. @default true */
   b64?: boolean;
 }
-/** JWS Protected Header */
+/** A JWS Protected Header, which always holds `alg`. */
 export interface JWSProtectedHeader extends JWSHeaderParameters {
   alg: JWSAlgorithm;
 }
 /** Options for `sign`. */
 export interface JWSSignOptions extends JWTTimeClaimOptions {
-  /** JWS algorithm; inferred from the key when omitted. */
+  /** The signing algorithm. Defaults to the JWK's `alg`, else to the one an EC or Ed25519 JWK's curve names. A key that names none throws `ERR_JWS_ALG_MISSING`. */
   alg?: JWSAlgorithm;
-  /** Extra protected header parameters; `alg` cannot be set, `typ` defaults to `"JWT"` for an object payload. */
+  /**
+   * Protected Header Parameters to add. `alg` cannot be set here.
+   * `kid` defaults to the JWK's `kid`. `typ` defaults to `"JWT"` for an object payload.
+   * A `jwk` member must be a public JWK, else `ERR_INVALID_OPTION`.
+   */
   protectedHeader?: StrictOmit<JWSHeaderParameters, "alg"> & {
     alg?: never;
   };
 }
-/** Result of JWS verification. */
+/** The result of `verify`. */
 export interface JWSVerifyResult<T extends JOSEPayload = JOSEPayload> {
   payload: T;
   protectedHeader: JWSProtectedHeader;
 }
-/** Options for `verify`; `Mode` is the `payload` option's literal. */
+/** Options for `verify`. `Mode` is the literal of the `payload` option. */
 export interface JWSVerifyOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> extends JOSEConsumerOptions<Mode> {
-  /** Allowed `alg` values; inferred from the key when omitted, required for raw secrets, alg-less JWKs and resolvers. */
+  /**
+   * The accepted header `alg` values, else `ERR_JWS_ALG_NOT_ALLOWED`.
+   * When omitted, the key's JWK `alg` is the policy, else the algorithms its type serves.
+   * Pass it for raw bytes and for an `oct` or RSA JWK without `alg`.
+   */
   algorithms?: JWSAlgorithm[];
-  /** Max JWK Set candidates per token; more is `ERR_JWK_KEY_NOT_FOUND`. @default { keyCandidates: 8 } */
+  /** Max JWK Set keys tried per token. More throws `ERR_JWK_KEY_NOT_FOUND`. @default { keyCandidates: 8 } */
   limits?: Pick<JOSELimits, "keyCandidates">;
 }
 /** JWS Flattened JSON Serialization (RFC 7515 §7.2.2). */
 export interface JWSFlattenedSerialization {
-  /** The JWS Payload; base64url-encoded unless `b64: false`. */
+  /** The JWS Payload, base64url-encoded unless `b64` is `false`. */
   payload: string;
-  /** Base64url-encoded JWS Protected Header. */
+  /** The base64url-encoded JWS Protected Header. */
   protected?: string;
-  /** JWS Unprotected Header (not signed). */
+  /** The JWS Unprotected Header, which the signature does not cover. */
   header?: JWSHeaderParameters;
-  /** Base64url-encoded signature. */
+  /** The base64url-encoded signature. */
   signature: string;
 }
 /** JWS General JSON Serialization (RFC 7515 §7.2.1). */
@@ -203,42 +208,46 @@ export interface JWSGeneralSerialization extends Omit<JWSFlattenedSerialization,
   /** One entry per signer. */
   signatures: JWSGeneralSignature[];
 }
-/** A single entry of `JWSGeneralSerialization.signatures`. */
+/** One entry of `JWSGeneralSerialization.signatures`. */
 export type JWSGeneralSignature = Pick<JWSFlattenedSerialization, "protected" | "header" | "signature">;
-/** One signer passed to `signMulti`. */
+/** One signer of `signMulti`. */
 export interface JWSMultiSigner {
-  /** Signing key; `kid` is taken from a JWK, a `CryptoKey` must set it in `protectedHeader`. */
+  /** The signing key. A JWK's `kid` is written to the protected header. For a `CryptoKey`, set `kid` in `protectedHeader`. */
   key: JWSSignJWK | CryptoKey;
-  /** JWS algorithm; inferred from the key when possible, else `ERR_JWS_SIGNER_ALG_INFERENCE`. */
+  /** The signing algorithm. Defaults to the one the key names, an EC or Ed25519 JWK's curve included, else `ERR_JWS_SIGNER_ALG_INFERENCE`. */
   alg?: JWSAlgorithm;
-  /** Per-signer protected header; `b64` must match across signers (RFC 7797 §3), `typ` defaults to `"JWT"`. */
+  /** This signer's Protected Header Parameters. `b64` must match across signers (RFC 7797 §3). `typ` defaults to `"JWT"` for an object payload. */
   protectedHeader?: StrictOmit<JWSHeaderParameters, "alg"> & {
     alg?: never;
   };
-  /** Per-signer JWS Unprotected Header (not signed). */
+  /** This signer's JWS Unprotected Header. It cannot hold `crit`, `b64`, or a name the protected header holds. */
   unprotectedHeader?: JWSHeaderParameters;
 }
-/** Options for `signMulti`; `alg` and `protectedHeader` are set per signer. */
+/** Options for `signMulti`. `alg` and `protectedHeader` are set per signer. */
 export interface JWSMultiSignOptions extends StrictOmit<JWSSignOptions, "alg" | "protectedHeader"> {}
 /** Options for `verifyMulti`. */
 export interface JWSMultiVerifyOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> extends JWSVerifyOptions<Mode> {
-  /** Max `signatures[]` (more is `ERR_JWS_INVALID`) and JWK Set candidates per signature. @default { signatures: 16, keyCandidates: 8 } */
-  limits?: Pick<JOSELimits, "signatures" | "keyCandidates">;
-  /** Try only signatures the key could have produced (by `kid`, `kty`, curve, length), else `ERR_JWS_NO_MATCHING_SIGNER`. @default false */
+  /**
+   * Max `signatures[]` entries (more throws `ERR_JWS_INVALID`), JWK Set keys per signature, and key trials over the call.
+   * Too many keys or trials throws `ERR_JWK_KEY_NOT_FOUND`.
+   * @default { signatures: 16, keyCandidates: 8, keyAttempts: 16 }
+   */
+  limits?: Pick<JOSELimits, "signatures" | "keyCandidates" | "keyAttempts">;
+  /** Skips signatures whose `kid` or `alg` the key cannot serve. No signature left throws `ERR_JWS_NO_MATCHING_SIGNER`. @default false */
   strictSignerMatch?: boolean;
 }
-/** Result of `verifyMulti`. */
+/** The result of `verifyMulti`: the first signature that verified. */
 export interface JWSMultiVerifyResult<T extends JOSEPayload = JOSEPayload> extends Omit<JWSVerifyResult<T>, "protectedHeader"> {
-  /** Protected header of the verified signature as signed; `alg` may sit in `signerHeader` (RFC 7515 §7.2.1). */
+  /** The verified signature's protected header, as signed. `alg` can be in `signerHeader` instead (RFC 7515 §7.2.1). */
   protectedHeader: JWSHeaderParameters;
-  /** Unprotected header of the verified signature. */
+  /** The verified signature's unprotected header. */
   signerHeader?: JWSHeaderParameters;
-  /** Index into `signatures` of the verified signature. */
+  /** The verified signature's index in `signatures`. */
   signerIndex: number;
 }
 /** Options for `verifyMultiAll`. */
 export interface JWSMultiVerifyAllOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> extends StrictOmit<JWSMultiVerifyOptions<Mode>, "strictSignerMatch"> {}
-/** Per-signature outcome of `verifyMultiAll`, discriminated by `verified`; failures carry `error`. */
+/** One signature's outcome in `verifyMultiAll`. `verified: false` holds the `error`. */
 export type JWSMultiVerifyOutcome<T extends JOSEPayload = JOSEPayload> = {
   signerIndex: number;
   verified: true;
@@ -252,7 +261,7 @@ export type JWSMultiVerifyOutcome<T extends JOSEPayload = JOSEPayload> = {
   protectedHeader?: JWSHeaderParameters;
   signerHeader?: JWSHeaderParameters;
 };
-/** Decoded protected header a `JWKLookupFunction` receives, its algorithms already checked against the ones this version implements; `enc` is present on JWE only. */
+/** The decoded header a `JWKLookupFunction` receives. Its `alg` and `enc` are already checked as supported. `enc` is set on a JWE only. */
 export type JWKLookupFunctionHeader = {
   kid?: string;
   alg?: JWSAlgorithm | KeyManagementAlgorithm;
@@ -261,117 +270,125 @@ export type JWKLookupFunctionHeader = {
   crit?: string[];
   [propName: string]: unknown;
 };
-/** Resolves the verify/decrypt key from the protected header (`THeader`: the family's, else the generic one) and compact token; a string is a PBES2 password (JWE) or raw key bytes (JWS); `undefined`, `null` or a throw is `ERR_JWK_KEY_NOT_FOUND`. */
-export type JWKLookupFunction<TReturn = CryptoKey | JWK | JWKSet | string | Uint8Array<ArrayBuffer>, THeader = JWKLookupFunctionHeader> = (header: THeader, token: string) => TReturn | undefined | null | Promise<TReturn | undefined | null>;
-/** Custom JWK import cache; key on the JWK `thumbprint` plus private/public half and `alg`, never on `kid`. Both methods may return a promise. */
+/**
+ * Returns the key that verifies or decrypts a token, from `{ header, token }`: its decoded header and the token itself.
+ * A string is a PBES2 password on a JWE. Any other use of a string throws `ERR_JWK_INVALID`.
+ * `undefined` means no key for this token, reported as `ERR_JWK_KEY_NOT_FOUND`. A thrown `JWTError` propagates as it is,
+ * and any other throw is `ERR_JWK_KEY_NOT_FOUND` with the thrown error as `cause`.
+ */
+export type JWKLookupFunction<TReturn = CryptoKey | JWK | JWKSet | string | Uint8Array<ArrayBuffer>, THeader = JWKLookupFunctionHeader> = (lookup: {
+  header: THeader;
+  token: string;
+}) => TReturn | undefined | Promise<TReturn | undefined>;
+/** A JWK import cache for `configureJWKCache`. Both methods can return a promise. Key the entries on the RFC 7638 thumbprint, the private or public half, and `alg`, never on `kid`. */
 export interface JWKCacheAdapter {
   get(jwk: JWK, alg: JWKAlgorithm): CryptoKey | undefined | Promise<CryptoKey | undefined>;
   set(jwk: JWK, alg: JWKAlgorithm, key: CryptoKey): void | Promise<void>;
 }
-/** Structure returned for composite AES-CBC + HMAC keys. */
+/** A composite AES-CBC with HMAC key, split into its two halves. */
 export type CompositeKey = {
   encryptionKey: CryptoKey;
   macKey: CryptoKey;
 };
 export type GenerateKeyAlgorithm = Exclude<JWKAlgorithm, "none" | "dir" | JWK_PBES2>;
-/** Options for `generateJWK`; `Kid` is the `kid` option that types the generated `kid`. */
+/** Options for `generateJWK`. `Kid` is the type of the `kid` option, which types the generated `kid`. */
 export interface GenerateJWKOptions<Kid extends string | false = string | false> {
-  /** Key usages; composite (CBC) keys get their default usages separately. */
+  /** Narrows the usages `alg` admits and is written as `key_ops`. Without it, the key has every usage `alg` admits and no `key_ops`. */
   keyUsage?: KeyUsage[];
-  /** RSA modulus length. Default: `2048`. */
+  /** The RSA modulus length in bits, at least 2048. Default: `2048`. */
   modulusLength?: number;
-  /** RSA public exponent. Default: `65537`. */
+  /** The RSA public exponent as big-endian bytes. Default: `65537`. */
   publicExponent?: Uint8Array<ArrayBuffer>;
-  /** EC/OKP curve. Default: `"P-256"` (EC), `"Ed25519"` (OKP). */
+  /** The curve for `ECDH-ES*` and `EdDSA`. `ES*` and `Ed25519` fix their own curve. Default: `"P-256"` for `ECDH-ES*`, `"Ed25519"` for `EdDSA`. */
   namedCurve?: "P-256" | "P-384" | "P-521" | "X25519" | "Ed25519";
-  /** `kid` to set verbatim, or `false` for none. Default: the RFC 7638 thumbprint, a SHA-256 digest per key. */
+  /** The `kid` to set as given, or `false` for none. Default: the key's RFC 7638 SHA-256 thumbprint. */
   kid?: Kid;
 }
-/** Options for `generateKey`; `ToJWK` is the `toJWK` literal that picks key objects or JWKs. */
+/** Options for `generateKey`. `ToJWK` is the literal of the `toJWK` option, which picks key objects or JWKs. */
 export interface GenerateKeyOptions<ToJWK extends boolean = boolean, Kid extends string | false = string | false> extends GenerateJWKOptions<Kid> {
-  /** Mark the key(s) extractable; ignored when `toJWK` is set. Default: `true`. */
+  /** Makes the generated keys extractable. Ignored with `toJWK`. Default: `true`. */
   extractable?: boolean;
-  /** Return JWKs instead of key objects. */
+  /** Returns JWKs instead of key objects. Default: `false`. */
   toJWK?: ToJWK;
-  /** Read only with `toJWK`: `kid` to set verbatim, or `false` for none. Default: the RFC 7638 thumbprint, a SHA-256 digest per key. */
+  /** With `toJWK`, the `kid` to set as given, or `false` for none. Ignored without `toJWK`. Default: the key's RFC 7638 SHA-256 thumbprint. */
   kid?: Kid;
 }
-/** `generateKey` result per algorithm without `toJWK`: `CryptoKey` (symmetric), raw bytes (`A*CBC-HS*`), `CryptoKeyPair` (asymmetric). */
+/** The `generateKey` result per algorithm without `toJWK`: a `CryptoKey` (symmetric), raw bytes (`A*CBC-HS*`), or a `CryptoKeyPair` (asymmetric). */
 export type GeneratedKeyMap = { [A in GenerateKeyAlgorithm]: A extends JWK_AES_CBC_HMAC ? Uint8Array<ArrayBuffer> : A extends JWK_Asymmetric_Algorithm ? CryptoKeyPair : CryptoKey; };
-/** `generateJWK` result per algorithm: an `oct` JWK or a JWK pair, each carrying `alg`, and `kid` unless `Kid` is `false`. */
+/** The `generateJWK` result per algorithm: an `oct` JWK or a JWK pair. Each JWK has `alg`, and `kid` unless `Kid` is `false`. */
 export type GeneratedJWKMap<Kid extends string | false = string> = { [A in GenerateKeyAlgorithm]: A extends JWK_Asymmetric_Algorithm ? GeneratedJWKPair<JWK_Pair<A>, A, Kid> : JWK_oct<Exclude<A, JWK_Asymmetric_Algorithm>> & GeneratedJWKMembers<A, Kid>; };
-/** `generateKey` return type for `TAlg` under `TOptions`; JWKs when `toJWK` is `true`. */
+/** The `generateKey` return type for `TAlg` under `TOptions`. JWKs when `toJWK` is `true`. */
 export type GenerateKeyReturn<TAlg extends GenerateKeyAlgorithm, TOptions extends GenerateKeyOptions> = GeneratedKeyShape<TAlg, Exclude<TOptions["toJWK"], undefined>, GeneratedKid<TOptions>>;
-/** `generateJWK` return type for `TAlg` under the `kid` option `Kid`. */
+/** The `generateJWK` return type for `TAlg` under the `kid` option `Kid`. */
 export type GenerateJWKReturn<TAlg extends GenerateKeyAlgorithm, Kid extends string | false = string> = GeneratedJWKMap<Kid>[TAlg];
-/** What `importKey` resolves to per input: bytes and `oct` JWKs to raw bytes, a `CryptoKey` as is, asymmetric JWKs to a `CryptoKey`. */
+/** What `importKey` returns per input: raw bytes for bytes and `oct` JWKs, the same `CryptoKey` for a `CryptoKey`, and a `CryptoKey` for an asymmetric JWK. */
 export interface ImportedKeyMap {
   bytes: Uint8Array<ArrayBuffer>;
   oct: Uint8Array<ArrayBuffer>;
   cryptoKey: CryptoKey;
   asymmetric: CryptoKey;
 }
-/** `ImportedKeyMap` entry for key input `K`; a union input yields a union. */
+/** The `ImportedKeyMap` entry for key input `K`. A union input gives a union. */
 export type ImportedKey<K> = ImportedKeyMap[K extends Uint8Array ? "bytes" : K extends CryptoKey ? "cryptoKey" : K extends JWK_oct ? "oct" : "asymmetric"];
 /** Options for `deriveKeyFromPassword`. */
 export interface DeriveKeyOptions {
   alg: JWK_PBES2;
-  /** Salt (p2s), bytes or UTF-8 text; at least 8 octets (RFC 7518 §4.8.1.1). */
+  /** The salt (`p2s`) as bytes or UTF-8 text, at least 8 octets (RFC 7518 §4.8.1.1). */
   salt: string | Uint8Array<ArrayBuffer>;
-  /** Iteration count (p2c), a positive integer. */
+  /** The iteration count (`p2c`), an integer of at least 1000 (RFC 7518 §4.8.1.2). */
   iterations: number;
-  /** Key usages. Default: `["wrapKey", "unwrapKey"]`. */
+  /** The derived key's usages, written as `key_ops` with `toJWK`. Default: `["wrapKey", "unwrapKey"]`. */
   keyUsage?: KeyUsage[];
-  /** Mark the derived key extractable; ignored when `toJWK` is set. Default: `false`. */
+  /** Makes the derived key extractable. Ignored with `toJWK`. Default: `false`. */
   extractable?: boolean;
-  /** Return the derived key as a `JWK_oct`. */
+  /** Returns the derived key as a `JWK_oct` with the inner AES-KW `alg`. Default: `false`. */
   toJWK?: boolean;
 }
-/** The AES-KW algorithm a `PBES2-*` or `ECDH-ES+*` algorithm wraps the CEK with: its last six characters. */
+/** The AES-KW algorithm a `PBES2-*` or `ECDH-ES+*` algorithm wraps the CEK with. */
 export type KeyWrapAlgorithmOf<A extends KeyWrappingAlgorithm> = A extends `${string}A128KW` ? "A128KW" : A extends `${string}A192KW` ? "A192KW" : A extends `${string}A256KW` ? "A256KW" : never;
-/** Key management algorithms that wrap the CEK with an inner AES-KW step. */
+/** The key management algorithms that wrap the CEK with an inner AES-KW step. */
 export type KeyWrappingAlgorithm = JWK_PBES2 | Exclude<JWK_ECDH_ES, "ECDH-ES">;
-/** PBES2 → AES-KW `alg` stamped on the derived JWK. */
+/** The AES-KW `alg` of the JWK derived for a PBES2 algorithm. */
 type DerivedJWKAlg<TAlg extends JWK_PBES2> = KeyWrapAlgorithmOf<TAlg>;
 export type DeriveKeyReturn<TOptions extends DeriveKeyOptions, TAlg extends JWK_PBES2 = JWK_PBES2> = TOptions["toJWK"] extends true ? JWK_oct<DerivedJWKAlg<TAlg>> : TOptions["toJWK"] extends object ? JWK_oct<DerivedJWKAlg<TAlg>> : CryptoKey;
-/** Options of `deriveJWKFromPassword`: PBES2 derivation without `toJWK`/`extractable`, plus `kid` (`false` for none). */
+/** Options for `deriveJWKFromPassword`: the `deriveKeyFromPassword` options without `toJWK` and `extractable`, plus `kid` (`false` for none). */
 export type DeriveJWKOptions<TAlg extends JWK_PBES2 = JWK_PBES2, Kid extends string | false = string> = Omit<DeriveKeyOptions, "alg" | "toJWK" | "extractable"> & {
   alg: TAlg;
   kid?: Kid;
 };
-/** `deriveJWKFromPassword` return type: the AES-KW `oct` JWK for `TAlg`, with `kid` unless `Kid` is `false`. */
+/** The `deriveJWKFromPassword` return type: the AES-KW `oct` JWK for `TAlg`, with `kid` unless `Kid` is `false`. */
 export type DeriveJWKReturn<TAlg extends JWK_PBES2, Kid extends string | false = string> = JWK_oct<DerivedJWKAlg<TAlg>> & GeneratedJWKMembers<DerivedJWKAlg<TAlg>, Kid>;
-/** PEM label families `importPEM` reads. */
+/** The PEM types `importPEM` reads. */
 export type PEMType = "pkcs8" | "spki" | "x509";
-/** `importPEM` result for `Alg`: the private JWK of a PKCS#8 PEM, the public one of SPKI/X.509, both when the label is inferred. */
+/** The `importPEM` result for `Alg`: a private JWK for PKCS#8, a public JWK for SPKI or X.509, and either when the type is inferred. */
 export type ImportedPEMJWK<Alg extends JWKPEMAlgorithm, Type extends PEMType | undefined = undefined> = Type extends "pkcs8" ? JWK_Pair<Alg>["privateKey"] : Type extends "spki" | "x509" ? JWK_Pair<Alg>["publicKey"] : JWK_Pair<Alg>["privateKey"] | JWK_Pair<Alg>["publicKey"];
 export type KeyManagementAlgorithm = JWK_RSA_ENC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_PBES2 | JWK_ECDH_ES | "dir";
 export type ContentEncryptionAlgorithm = JWK_AES_GCM | JWK_AES_CBC_HMAC;
-/** Keys admissible as the `wrappingKey` of `wrapKey` for algorithm `A`; `dir` takes any symmetric key. */
+/** The keys `wrapKey` accepts as `wrappingKey` for algorithm `A`. `dir` takes any symmetric key. */
 export type WrappingKeyFor<A extends KeyManagementAlgorithm> = A extends JWK_RSA_ENC ? CryptoKey | JWK_RSA_Public<A> : A extends JWK_ECDH_ES ? CryptoKey | JWK_EC_Public<A> | JWK_OKP_Public<A> : A extends JWK_PBES2 ? string | Uint8Array<ArrayBuffer> | JWK_oct<A> : A extends JWK_AES_KW ? CryptoKey | JWK_oct<A> : A extends JWK_AES_GCM_KW ? CryptoKey | JWK_oct<A> : A extends "dir" ? CryptoKey | JWK_oct | Uint8Array<ArrayBuffer> : never;
-/** Private-side counterpart of `WrappingKeyFor`, for the `unwrappingKey` of `unwrapKey`. */
+/** The keys `unwrapKey` accepts as `unwrappingKey` for algorithm `A`. */
 export type UnwrappingKeyFor<A extends KeyManagementAlgorithm> = A extends JWK_RSA_ENC ? CryptoKey | JWK_RSA_Private<A> : A extends JWK_ECDH_ES ? CryptoKey | JWK_EC_Private<A> | JWK_OKP_Private<A> : A extends JWK_PBES2 ? string | Uint8Array<ArrayBuffer> | JWK_oct<A> : A extends JWK_AES_KW ? CryptoKey | JWK_oct<A> : A extends JWK_AES_GCM_KW ? CryptoKey | JWK_oct<A> : A extends "dir" ? CryptoKey | JWK_oct | Uint8Array<ArrayBuffer> : never;
 /** Options for `wrapKey`. */
 export interface WrapKeyOptions<TAlg extends KeyManagementAlgorithm = KeyManagementAlgorithm> {
   alg: TAlg;
-  /** AES-GCMKW IV, random when omitted; never reuse one under the same key (tests and known vectors only). */
+  /** The AES-GCMKW IV. Random when omitted. Pass one only for tests and known vectors: an IV reused under one key breaks AES-GCM. */
   iv?: Uint8Array<ArrayBuffer>;
-  /** PBES2 Salt value (p2s). Required for PBES2 algorithms. */
+  /** The PBES2 salt (`p2s`), at least 8 octets. Required for PBES2, else `ERR_JWE_INVALID`. */
   p2s?: Uint8Array<ArrayBuffer>;
-  /** PBES2 Iteration count (p2c). Required for PBES2 algorithms. */
+  /** The PBES2 iteration count (`p2c`), from 1000 to `600_000`. Required for PBES2, else `ERR_JWE_INVALID`. */
   p2c?: number;
   ecdh?: {
-    /** Ephemeral key material. Generated when omitted. */
+    /** The ephemeral key. Generated when omitted. */
     ephemeralKey?: ECDHEphemeralKeyInput;
-    /** Agreement PartyUInfo (apu). */
+    /** The agreement PartyUInfo (`apu`), at most 1024 bytes. */
     partyUInfo?: Uint8Array<ArrayBuffer>;
-    /** Agreement PartyVInfo (apv). */
+    /** The agreement PartyVInfo (`apv`), at most 1024 bytes. */
     partyVInfo?: Uint8Array<ArrayBuffer>;
-    /** Required only for direct `"ECDH-ES"` key agreement. */
+    /** The content encryption algorithm. Required for direct `"ECDH-ES"`, else `ERR_JWK_INVALID`. */
     enc?: ContentEncryptionAlgorithm;
   };
 }
-/** Result of `wrapKey`, shaped by the `alg` family; string members are base64url. */
+/** The result of `wrapKey`, shaped by the `alg` family. String members are base64url. */
 export type WrapKeyResult<TAlg extends KeyManagementAlgorithm = KeyManagementAlgorithm> = TAlg extends JWK_PBES2 ? {
   encryptedKey: Uint8Array<ArrayBuffer>;
   p2s: string;
@@ -391,38 +408,41 @@ export type WrapKeyResult<TAlg extends KeyManagementAlgorithm = KeyManagementAlg
 /** Options for `unwrapKey`. */
 export interface UnwrapKeyOptions<TAlg extends KeyManagementAlgorithm = KeyManagementAlgorithm> {
   alg: TAlg;
-  /** `"cryptokey"` returns a `CryptoKey`, `"raw"` the key bytes. Default: `"cryptokey"`. */
+  /** `"cryptokey"` returns a `CryptoKey`, `"raw"` returns the key bytes. Default: `"cryptokey"`. */
   format?: "cryptokey" | "raw";
-  /** Required for AES-GCMKW; base64url or bytes. */
+  /** The AES-GCMKW IV, as base64url or bytes. Required for AES-GCMKW. */
   iv?: Uint8Array<ArrayBuffer> | string;
-  /** Required for AES-GCMKW; base64url or bytes. */
+  /** The AES-GCMKW tag, as base64url or bytes. Required for AES-GCMKW. */
   tag?: Uint8Array<ArrayBuffer> | string;
-  /** Required for PBES2; base64url or bytes. */
+  /** The PBES2 salt, as base64url or bytes. Required for PBES2. */
   p2s?: Uint8Array<ArrayBuffer> | string;
-  /** Required for PBES2. */
+  /** The PBES2 iteration count. Required for PBES2. */
   p2c?: number;
-  /** Minimum accepted PBES2 `p2c` on unwrap. Defaults to 1000 (RFC 7518 §4.8.1.2). */
+  /** The lowest PBES2 `p2c` accepted, else `ERR_JWE_INVALID` (RFC 7518 §4.8.1.2). Default: `1000`. */
   minIterations?: number;
-  /** Maximum accepted PBES2 `p2c` on unwrap. Default: `600_000`. */
+  /** The highest PBES2 `p2c` accepted, else `ERR_JWE_INVALID`. Default: `600_000`. */
   maxIterations?: number;
-  /** Required for ECDH-ES. */
+  /** The sender's ephemeral public key. Required for ECDH-ES. */
   epk?: JWK_EC_Public | JWK_OKP_Public | CryptoKey;
+  /** The agreement PartyUInfo, as base64url or bytes, at most 1024 bytes. */
   apu?: Uint8Array<ArrayBuffer> | string;
+  /** The agreement PartyVInfo, as base64url or bytes, at most 1024 bytes. */
   apv?: Uint8Array<ArrayBuffer> | string;
-  /** Required for direct ECDH-ES key agreement. */
+  /** The content encryption algorithm. Required for direct ECDH-ES. With `dir` and RSA-OAEP, it checks the key length and picks the import algorithm. */
   enc?: ContentEncryptionAlgorithm;
-  /** Algorithm to import the unwrapped key as. */
+  /** The algorithm the unwrapped key is imported as. Default: AES-GCM, or for RSA-OAEP the one `enc` and the key length name. */
   unwrappedKeyAlgorithm?: string | Algorithm | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams;
+  /** The unwrapped key's usages. Default: `["encrypt", "decrypt"]`. */
   keyUsage?: KeyUsage[];
-  /** Mark the unwrapped key extractable. Default: `true`. */
+  /** Makes the unwrapped key extractable. Default: `true`. */
   extractable?: boolean;
 }
-/** Result of `unwrapKey`: bytes for `format: "raw"`, else a `CryptoKey`; a non-literal `format` keeps both. */
+/** The result of `unwrapKey`: bytes for `format: "raw"`, else a `CryptoKey`. A non-literal `format` gives both. */
 export type UnwrapKeyResult<TOptions extends {
   format?: "cryptokey" | "raw";
 }> = "format" extends keyof TOptions ? [TOptions["format"]] extends ["raw"] ? Uint8Array<ArrayBuffer> : [TOptions["format"]] extends ["cryptokey" | undefined] ? CryptoKey : CryptoKey | Uint8Array<ArrayBuffer> : CryptoKey;
 /** Forked from https://github.com/panva/jose/tree/v6.0.10, Copyright (c) 2018 Filip Skokan, LICENSE: https://github.com/panva/jose/blob/v6.0.10/LICENSE.md */
-/** Generic JWK parameters; `Alg` constrains the `alg` member. */
+/** The JWK members common to every key type (RFC 7517 §4). `Alg` constrains `alg`. */
 export interface JWKParameters<Alg extends JWKAlgorithm = JWKAlgorithm> {
   /** JWK "kty" (Key Type) Parameter */
   "kty": string;
@@ -444,17 +464,17 @@ export interface JWKParameters<Alg extends JWKAlgorithm = JWKAlgorithm> {
   "x5u"?: string;
   /** JWK "kid" (Key ID) Parameter */
   "kid"?: string;
-  /** Non-standard `enc` hint, read when `alg` is `"dir"` and no `enc` option is given. */
+  /** A content encryption hint outside RFC 7517. `encrypt` reads it when no `enc` option is given. */
   "enc"?: ContentEncryptionAlgorithm;
 }
-/** JWK members a caller may set on a produced key: all but `alg`, `kty`, `key_ops` and `ext`. */
+/** The JWK members a caller can set on a generated or derived key: all but `alg`, `kty`, `key_ops` and `ext`. */
 export type JWKMetadata = Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">;
-/** ECDH-ES ephemeral key material: a private key, a `CryptoKeyPair`, or an object with both halves. */
+/** An ECDH-ES ephemeral key: a private key, a `CryptoKeyPair`, or an object with both halves. */
 export type ECDHEphemeralKeyInput = CryptoKey | JWK_EC_Private | JWK_OKP_Private | CryptoKeyPair | {
   publicKey: CryptoKey | JWK_EC_Public | JWK_OKP_Public;
   privateKey: CryptoKey | JWK_EC_Private | JWK_OKP_Private;
 };
-/** Public EC JSON Web Keys */
+/** A public EC JWK. */
 export interface JWK_EC_Public<Alg extends JWK_ECDSA | JWK_ECDH_ES = JWK_ECDSA | JWK_ECDH_ES> extends JWKParameters<Alg> {
   kty: "EC";
   /** EC JWK "crv" (Curve) Parameter */
@@ -464,14 +484,14 @@ export interface JWK_EC_Public<Alg extends JWK_ECDSA | JWK_ECDH_ES = JWK_ECDSA |
   /** EC JWK "y" (Y Coordinate) Parameter */
   y: string;
 }
-/** Private EC JSON Web Keys */
+/** A private EC JWK. */
 export interface JWK_EC_Private<Alg extends JWK_ECDSA | JWK_ECDH_ES = JWK_ECDSA | JWK_ECDH_ES> extends JWK_EC_Public<Alg> {
   /** EC JWK "d" (ECC Private Key) Parameter */
   d: string;
 }
-/** EC JSON Web Keys */
+/** A public or private EC JWK. */
 export type JWK_EC<Alg extends JWK_ECDSA | JWK_ECDH_ES = JWK_ECDSA | JWK_ECDH_ES> = JWK_EC_Public<Alg> | JWK_EC_Private<Alg>;
-/** Public RSA JSON Web Keys */
+/** A public RSA JWK. */
 export interface JWK_RSA_Public<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC = JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC> extends JWKParameters<Alg> {
   kty: "RSA";
   /** RSA JWK "e" (Exponent) Parameter */
@@ -480,7 +500,7 @@ export interface JWK_RSA_Public<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA
   n: string;
   oth?: RsaOtherPrimesInfo[];
 }
-/** Private RSA JSON Web Keys */
+/** A private RSA JWK. */
 export interface JWK_RSA_Private<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC = JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC> extends JWK_RSA_Public<Alg> {
   /** RSA JWK "d" (Private Exponent) Parameter */
   d: string;
@@ -495,46 +515,46 @@ export interface JWK_RSA_Private<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RS
   /** RSA JWK "qi" (First CRT Coefficient) Parameter */
   qi: string;
 }
-/** RSA JSON Web Keys */
+/** A public or private RSA JWK. */
 export type JWK_RSA<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC = JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC> = JWK_RSA_Public<Alg> | JWK_RSA_Private<Alg>;
-/** Public ED JSON Web Keys */
+/** A public OKP JWK (RFC 8037). */
 export interface JWK_OKP_Public<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES = JWK_OKP_SIGN | JWK_ECDH_ES> extends JWKParameters<Alg> {
   kty: "OKP";
-  /** ED JWK "crv" (Curve) Parameter */
+  /** OKP JWK "crv" (Curve) Parameter */
   crv: string;
-  /** ED JWK "x" (X Coordinate) Parameter */
+  /** OKP JWK "x" (Public Key) Parameter */
   x: string;
 }
-/** Private ED JSON Web Keys */
+/** A private OKP JWK (RFC 8037). */
 export interface JWK_OKP_Private<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES = JWK_OKP_SIGN | JWK_ECDH_ES> extends JWK_OKP_Public<Alg> {
-  /** ED JWK "d" (Private Key) Parameter */
+  /** OKP JWK "d" (Private Key) Parameter */
   d: string;
 }
-/** OKP JSON Web Keys */
+/** A public or private OKP JWK. */
 export type JWK_OKP<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES = JWK_OKP_SIGN | JWK_ECDH_ES> = JWK_OKP_Public<Alg> | JWK_OKP_Private<Alg>;
-/** oct JSON Web Keys */
+/** A symmetric (`oct`) JWK. */
 export interface JWK_oct<Alg extends JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC | JWK_PBES2 | "dir" = JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC | JWK_PBES2 | "dir"> extends JWKParameters<Alg> {
   kty: "oct";
   /** Oct JWK "k" (Key Value) Parameter */
   k: string;
 }
-/** Symmetric JSON Web Keys */
+/** A symmetric JWK, the same as `JWK_oct`. */
 export type JWK_Symmetric<Alg extends JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC | JWK_PBES2 | "dir" = JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC | JWK_PBES2 | "dir"> = JWK_oct<Alg>;
-/** Asymmetric JSON Web Keys. */
+/** An asymmetric JWK, narrowed to the key types `Alg` can use. */
 export type JWK_Asymmetric<Alg extends JWK_Asymmetric_Algorithm = JWK_Asymmetric_Algorithm> = RSAFor<Alg, JWK_RSA<Extract<Alg, JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC>>> | ECFor<Alg, JWK_EC<Extract<Alg, JWK_ECDSA | JWK_ECDH_ES>>> | OKPFor<Alg, JWK_OKP<Extract<Alg, JWK_OKP_SIGN | JWK_ECDH_ES>>>;
-/** Public JSON Web Keys. */
+/** A public JWK, narrowed to the key types `Alg` can use. */
 export type JWK_Public<Alg extends JWK_Asymmetric_Algorithm = JWK_Asymmetric_Algorithm> = RSAFor<Alg, JWK_RSA_Public<Extract<Alg, JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC>>> | ECFor<Alg, JWK_EC_Public<Extract<Alg, JWK_ECDSA | JWK_ECDH_ES>>> | OKPFor<Alg, JWK_OKP_Public<Extract<Alg, JWK_OKP_SIGN | JWK_ECDH_ES>>>;
-/** Private JSON Web Keys. */
+/** A private JWK, narrowed to the key types `Alg` can use. */
 export type JWK_Private<Alg extends JWK_Asymmetric_Algorithm = JWK_Asymmetric_Algorithm> = RSAFor<Alg, JWK_RSA_Private<Extract<Alg, JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC>>> | ECFor<Alg, JWK_EC_Private<Extract<Alg, JWK_ECDSA | JWK_ECDH_ES>>> | OKPFor<Alg, JWK_OKP_Private<Extract<Alg, JWK_OKP_SIGN | JWK_ECDH_ES>>>;
-/** `toPublicJWK` result: the public interface of the input's family and `alg`, keeping a `kid` the input is typed to carry. */
+/** The `toPublicJWK` result: the public JWK of the input's key type and `alg`, with `kid` when the input type has one. */
 export type ToPublicJWKReturn<T extends JWK_Asymmetric> = (T extends JWK_RSA<infer Alg> ? JWK_RSA_Public<Alg> : T extends JWK_EC<infer Alg> ? JWK_EC_Public<Alg> : T extends JWK_OKP<infer Alg> ? JWK_OKP_Public<Alg> : never) & (T extends {
   kid: string;
 } ? {
   kid: string;
 } : unknown);
-/** JSON Web Key (RFC 7517) of type "RSA", "EC", "OKP" or "oct". */
+/** A JWK (RFC 7517) of type `"RSA"`, `"EC"`, `"OKP"` or `"oct"`, narrowed to the key types `Alg` can use. */
 export type JWK<Alg extends JWKAlgorithm = JWKAlgorithm> = OctFor<Alg, JWK_oct<Extract<Alg, Exclude<JWKAlgorithm, JWK_Asymmetric_Algorithm>>>> | JWK_Asymmetric<Extract<Alg, JWK_Asymmetric_Algorithm>>;
-/** Public/private JWK pair, narrowed to the key family `Alg` identifies (ECDH-ES: EC or OKP). */
+/** A public and private JWK pair of the key type `Alg` names. ECDH-ES gives an EC or an OKP pair. */
 export type JWK_Pair<Alg extends JWK_Asymmetric_Algorithm = JWK_Asymmetric_Algorithm> = Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC ? {
   publicKey: JWK_RSA_Public<Alg>;
   privateKey: JWK_RSA_Private<Alg>;
@@ -551,12 +571,12 @@ export type JWK_Pair<Alg extends JWK_Asymmetric_Algorithm = JWK_Asymmetric_Algor
   publicKey: JWK_OKP_Public<Alg>;
   privateKey: JWK_OKP_Private<Alg>;
 } : never;
-/** JSON Web Key Set (RFC 7517); `T` preserves a precise key tuple. */
+/** A JWK Set (RFC 7517 §5). `T` keeps a precise key tuple. */
 export interface JWKSet<T extends readonly JWK[] = JWK[]> {
   keys: T;
   [parameter: string]: unknown;
 }
-/** JWK Key Algorithms */
+/** JWA algorithm identifiers, grouped by family (RFC 7518, RFC 8037). */
 export type JWK_HMAC = "HS256" | "HS384" | "HS512";
 export type JWK_RSA_SIGN = "RS256" | "RS384" | "RS512";
 export type JWK_RSA_PSS = "PS256" | "PS384" | "PS512";
@@ -569,7 +589,7 @@ export type JWK_AES_GCM_KW = "A128GCMKW" | "A192GCMKW" | "A256GCMKW";
 export type JWK_PBES2 = "PBES2-HS256+A128KW" | "PBES2-HS384+A192KW" | "PBES2-HS512+A256KW";
 export type JWK_ECDH_ES = "ECDH-ES" | "ECDH-ES+A128KW" | "ECDH-ES+A192KW" | "ECDH-ES+A256KW";
 export type JWK_OKP_SIGN = "Ed25519" | "EdDSA";
-/** Every algorithm named after an AES key size: the `A128`/`A192`/`A256` families. */
+/** Every algorithm named after an AES key size: the `A128`, `A192` and `A256` families. */
 export type JWK_AES_Algorithm = JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC;
 export type JWK_Symmetric_Algorithm = JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW;
 export type JWK_Asymmetric_Algorithm = JWK_RSA_SIGN | JWK_RSA_PSS | JWK_ECDSA | JWK_RSA_ENC | JWK_OKP_SIGN | JWK_ECDH_ES;
@@ -594,46 +614,46 @@ type GeneratedJWKPair<P, A, Kid> = P extends {
 type GeneratedKid<TOptions> = "kid" extends keyof TOptions ? ThumbprintIfUnset<Extract<TOptions["kid" & keyof TOptions], string | false>> : string;
 type ThumbprintIfUnset<Kid extends string | false> = [Kid] extends [never] ? string : Kid;
 type GeneratedKeyShape<TAlg extends GenerateKeyAlgorithm, ToJWK, Kid extends string | false> = [ToJWK] extends [never] ? GeneratedKeyMap[TAlg] : ToJWK extends true ? GeneratedJWKMap<Kid>[TAlg] : GeneratedKeyMap[TAlg];
-/** `Shape` when `Alg` has a member of that family, else nothing: a family never appears for an `alg` it cannot carry. */
+/** `Shape` when `Alg` has a member of that key type, else `never`. */
 type OctFor<Alg, Shape> = [Extract<Alg, Exclude<JWKAlgorithm, JWK_Asymmetric_Algorithm>>] extends [never] ? never : Shape;
 type RSAFor<Alg, Shape> = [Extract<Alg, JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC>] extends [never] ? never : Shape;
 type ECFor<Alg, Shape> = [Extract<Alg, JWK_ECDSA | JWK_ECDH_ES>] extends [never] ? never : Shape;
 type OKPFor<Alg, Shape> = [Extract<Alg, JWK_OKP_SIGN | JWK_ECDH_ES>] extends [never] ? never : Shape;
-/** `oct` JWK algorithms admissible for JWE key management (HMAC excluded). */
+/** The `oct` JWK `alg` values a JWE key accepts: all but HMAC. */
 type _JWEOctAlg = JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC | JWK_PBES2 | "dir";
-/** Asymmetric public JWKs admissible for JWE encryption (RSA-OAEP or ECDH-ES). */
+/** The asymmetric public JWKs that can encrypt: RSA-OAEP or ECDH-ES. */
 export type JWEAsymmetricPublicJWK = JWK_RSA_Public<JWK_RSA_ENC> | JWK_EC_Public<JWK_ECDH_ES> | JWK_OKP_Public<JWK_ECDH_ES>;
-/** Asymmetric private JWKs admissible for JWE decryption (RSA-OAEP or ECDH-ES). */
+/** The asymmetric private JWKs that can decrypt: RSA-OAEP or ECDH-ES. */
 export type JWEAsymmetricPrivateJWK = JWK_RSA_Private<JWK_RSA_ENC> | JWK_EC_Private<JWK_ECDH_ES> | JWK_OKP_Private<JWK_ECDH_ES>;
-/** JWKs admissible as the `key` of `encrypt`; a non-JWE `alg` is a type error. */
+/** The JWKs `encrypt` accepts. A JWK whose `alg` is not a JWE algorithm is a type error. */
 export type JWEEncryptJWK = JWK_oct<_JWEOctAlg> | JWEAsymmetricPublicJWK;
-/** JWKs admissible as a `key` of `decrypt`; a non-JWE `alg` is a type error. */
+/** The JWKs `decrypt` accepts. A JWK whose `alg` is not a JWE algorithm is a type error. */
 export type JWEDecryptJWK = JWK_oct<_JWEOctAlg> | JWEAsymmetricPrivateJWK;
-/** Recognized JWE Header Parameters; other members may also be present. */
+/** JWE Header Parameters (RFC 7516 §4.1, RFC 7518 §4.6 to §4.8). Other members are allowed. */
 export interface JWEHeaderParameters extends JoseHeaderParameters {
-  /** Key Management Algorithm. */
+  /** "alg" (Key Management Algorithm) Header Parameter */
   alg?: KeyManagementAlgorithm;
-  /** Content Encryption Algorithm. */
+  /** "enc" (Content Encryption Algorithm) Header Parameter */
   enc?: ContentEncryptionAlgorithm;
-  /** PBES2 Count. */
+  /** "p2c" (PBES2 Count) Header Parameter */
   p2c?: number;
-  /** PBES2 Salt, base64url. */
+  /** "p2s" (PBES2 Salt Input) Header Parameter, base64url */
   p2s?: string;
-  /** AES-GCMKW Initialization Vector, base64url. */
+  /** "iv" (AES-GCMKW Initialization Vector) Header Parameter, base64url */
   iv?: string;
-  /** AES-GCMKW Authentication Tag, base64url. */
+  /** "tag" (AES-GCMKW Authentication Tag) Header Parameter, base64url */
   tag?: string;
-  /** ECDH-ES Ephemeral Public Key. */
+  /** "epk" (ECDH-ES Ephemeral Public Key) Header Parameter */
   epk?: JWK_EC_Public | JWK_OKP_Public;
-  /** ECDH-ES Agreement PartyUInfo, base64url. */
+  /** "apu" (ECDH-ES Agreement PartyUInfo) Header Parameter, base64url */
   apu?: string;
-  /** ECDH-ES Agreement PartyVInfo, base64url. */
+  /** "apv" (ECDH-ES Agreement PartyVInfo) Header Parameter, base64url */
   apv?: string;
-  /** Compression (RFC 7516 §4.1.3) is not supported: a token carrying `zip` is rejected. */
+  /** Compression (RFC 7516 §4.1.3) is not supported. Decrypting a token with `zip` throws `ERR_JWE_INVALID`. */
   zip?: never;
   [propName: string]: unknown;
 }
-/** Recognized JWE Key Management-related Header Parameters; all but `apu`/`apv` are internal. */
+/** Key management inputs as bytes and keys, before they are written to the header. */
 export interface JWEKeyManagementHeaderParameters {
   apu?: Uint8Array<ArrayBuffer>;
   apv?: Uint8Array<ArrayBuffer>;
@@ -643,141 +663,157 @@ export interface JWEKeyManagementHeaderParameters {
   epk?: CryptoKey | JWK_EC_Public | JWK_OKP_Public;
   epkPrivateKey?: CryptoKey | JWK_EC_Private | JWK_OKP_Private;
 }
-/** Header parameters the library writes itself and no caller header may set (RFC 7516 §4.1, RFC 7518 §4.6–§4.8). */
+/** The Header Parameters unjwt writes, which no caller header can set (RFC 7516 §4.1, RFC 7518 §4.6 to §4.8). */
 export type JWELibraryHeaderName = "alg" | "enc" | "iv" | "tag" | "p2s" | "p2c" | "epk" | "apu" | "apv";
-/** JWE encryption options. */
+/** Options for `encrypt`. */
 export interface JWEEncryptOptions extends JWTTimeClaimOptions {
+  /** The key management algorithm. Without it, a password uses `PBES2-HS256+A128KW`, an `oct` JWK whose `alg` is an `enc` uses `dir`, and any other JWK uses its `alg`. */
   alg?: KeyManagementAlgorithm;
+  /** The content encryption algorithm. Without it, the JWK's `enc` applies, else `A256GCM`. For `dir`, the CEK JWK's `alg` or `enc` applies, else `ERR_JWE_ENC_MISSING`. */
   enc?: ContentEncryptionAlgorithm;
-  /** Extra protected header; `typ` defaults to `"JWT"` for a JSON object payload, `cty` is never added (`"JWT"` for a nested JWT, RFC 7519 §5.2). */
+  /**
+   * Protected Header Parameters to add. `kid` defaults to the JWK's `kid`. `typ` defaults to `"JWT"` for an object payload.
+   * `cty` is never added. Set it to `"JWT"` for a nested JWT (RFC 7519 §5.2). A `zip` member throws `ERR_INVALID_OPTION`.
+   */
   protectedHeader?: StrictOmit<JWEHeaderParameters, JWELibraryHeaderName>;
-  /** AES-GCMKW key-wrapping IV. Generated when omitted. */
+  /** The AES-GCMKW key wrapping IV. Random when omitted. */
   keyManagementIV?: Uint8Array<ArrayBuffer>;
-  /** PBES2 Salt (p2s). Required for PBES2 algorithms. */
+  /** The PBES2 salt (`p2s`), at least 8 octets. Default: 16 random bytes. */
   p2s?: Uint8Array<ArrayBuffer>;
-  /** PBES2 iteration count (p2c), between `1000` and `600_000`. Default: `600_000`. */
+  /** The PBES2 iteration count (`p2c`), from `1000` to `600_000`. Default: `600_000`. */
   p2c?: number;
+  /** ECDH-ES inputs: the ephemeral key (generated when omitted), and `partyUInfo` and `partyVInfo` of at most 1024 bytes each. */
   ecdh?: {
     ephemeralKey?: ECDHEphemeralKeyInput;
     partyUInfo?: Uint8Array<ArrayBuffer>;
     partyVInfo?: Uint8Array<ArrayBuffer>;
   };
-  /** Content Encryption Key. Generated when omitted. */
+  /** The Content Encryption Key, sized for `enc`. Random when omitted. */
   cek?: Uint8Array<ArrayBuffer>;
-  /** Content encryption IV. Generated when omitted. */
+  /** The content encryption IV, sized for `enc`. Random when omitted. */
   contentEncryptionIV?: Uint8Array<ArrayBuffer>;
 }
-/** JWE decryption options; `Mode` is the `payload` option's literal, which sets the returned payload type. */
+/** Options for `decrypt`. `Mode` is the literal of the `payload` option, which sets the returned payload type. */
 export interface JWEDecryptOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> extends JOSEConsumerOptions<Mode> {
-  /** Allowed `alg` values. Inferred from the key when omitted (a password infers PBES2); required for raw bytes and lookup functions. */
+  /**
+   * The accepted header `alg` values, else `ERR_JWE_ALG_NOT_ALLOWED`.
+   * When omitted, the key's JWK `alg` is the policy, else the algorithms its type serves. A password accepts the three PBES2 algorithms.
+   * Pass it for raw bytes and for a JWK whose type does not narrow the algorithm.
+   */
   algorithms?: KeyManagementAlgorithm[];
-  /** Max JWK Set candidates per token (else `ERR_JWK_KEY_NOT_FOUND`) and PBKDF2 iterations per call (else `ERR_JWE_INVALID`). Default: `{ keyCandidates: 8, pbes2Iterations: 2_400_000 }`. */
+  /** Max JWK Set keys per token (more throws `ERR_JWK_KEY_NOT_FOUND`) and PBKDF2 iterations per call (more throws `ERR_JWE_INVALID`). Default: `{ keyCandidates: 8, pbes2Iterations: 2_400_000 }`. */
   limits?: Pick<JOSELimits, "keyCandidates" | "pbes2Iterations">;
-  /** Allowed `enc` values. */
+  /** The accepted header `enc` values, else `ERR_JWE_ALG_NOT_ALLOWED`. Any supported `enc` when omitted. */
   encryptionAlgorithms?: ContentEncryptionAlgorithm[];
-  /** Algorithm to import the unwrapped CEK as. Defaults based on `enc`. */
+  /** The algorithm an AES-GCM CEK is imported as. Default: AES-GCM. */
   unwrappedKeyAlgorithm?: Parameters<typeof crypto.subtle.importKey>[2];
-  /** Unwrapped CEK usages. Defaults based on `enc`. */
+  /** The usages of an imported CEK. Default: `["decrypt"]`. */
   keyUsage?: KeyUsage[];
-  /** Mark the unwrapped CEK extractable. Default: `true`. */
+  /** Makes an imported CEK extractable. `returnCek` needs it. Default: `true`. */
   extractable?: boolean;
-  /** Include the CEK and AAD in the result. */
+  /** Adds the CEK and the AAD to the result. Default: `false`. */
   returnCek?: boolean;
-  /** Minimum accepted PBES2 `p2c` on unwrap. Defaults to 1000 (RFC 7518 §4.8.1.2). */
+  /** The lowest PBES2 `p2c` accepted, else `ERR_JWE_INVALID` (RFC 7518 §4.8.1.2). Default: `1000`. */
   minIterations?: number;
-  /** Maximum accepted PBES2 `p2c` on unwrap. Default: `600_000`. */
+  /** The highest PBES2 `p2c` accepted, else `ERR_JWE_INVALID`. Default: `600_000`. */
   maxIterations?: number;
 }
-/** Validated protected header returned by `decrypt`; `alg` and `enc` are always present. */
+/** The protected header `decrypt` returns, which always holds `alg` and `enc`. */
 export interface JWEProtectedHeader extends JWEHeaderParameters {
   alg: KeyManagementAlgorithm;
   enc: ContentEncryptionAlgorithm;
 }
-/** Result of a JWE decryption. */
+/** The result of `decrypt`. */
 export interface JWEDecryptResult<T extends JOSEPayload = JOSEPayload> {
   payload: T;
   protectedHeader: JWEProtectedHeader;
-  /** Present only when `returnCek` is true. */
+  /** The CEK bytes. Set only with `returnCek`. */
   cek?: Uint8Array<ArrayBuffer>;
-  /** Present only when `returnCek` is true. */
+  /** The AAD that authenticates the content. Set only with `returnCek`. */
   aad?: Uint8Array<ArrayBuffer>;
 }
-/** JWE Flattened JSON Serialization (RFC 7516 §7.2.2); string members are base64url. */
+/** A JWE Flattened JSON Serialization (RFC 7516 §7.2.2). String members are base64url. */
 export interface JWEFlattenedSerialization {
   header?: JWEHeaderParameters;
   encrypted_key?: string;
-  /** JWE Protected Header (part of AAD). */
+  /** The JWE Protected Header, covered by the AAD. */
   protected?: string;
-  /** Shared Unprotected Header (not part of AAD). */
+  /** The JWE Shared Unprotected Header, not covered by the AAD. */
   unprotected?: JWEHeaderParameters;
-  /** External Additional Authenticated Data. */
+  /** The JWE AAD supplied by the producer. */
   aad?: string;
   iv: string;
   ciphertext: string;
   tag: string;
 }
-/** JWE General JSON Serialization (RFC 7516 §7.2.1), the output of `encryptMulti`. */
+/** A JWE General JSON Serialization (RFC 7516 §7.2.1), as `encryptMulti` returns. */
 export interface JWEGeneralSerialization extends Omit<JWEFlattenedSerialization, "encrypted_key" | "header"> {
   recipients: JWEGeneralRecipient[];
 }
-/** One recipient entry of a JWE General JSON Serialization. */
+/** One recipient of a JWE General JSON Serialization. */
 export interface JWEGeneralRecipient {
-  /** Per-recipient Unprotected Header (not part of AAD). */
+  /** The JWE Per-Recipient Unprotected Header, not covered by the AAD. */
   header?: JWEHeaderParameters;
   encrypted_key?: string;
 }
-/** One recipient of `encryptMulti`; `alg` and `kid` come from the key unless set in `header`. */
+/** One recipient of `encryptMulti`. `alg` is the JWK's `alg`, else `ERR_JWE_RECIPIENT_ALG_INFERENCE`. */
 export interface JWEMultiRecipient {
+  /** The recipient's JWK. Its `kid` is written to the recipient header. */
   key: JWEEncryptJWK;
-  /** Extra per-recipient Unprotected Header parameters (RFC 7516 §7.2.1). */
+  /** Per-Recipient Unprotected Header Parameters to add (RFC 7516 §7.2.1). They override the JWK's `kid`. */
   header?: StrictOmit<JWEHeaderParameters, JWELibraryHeaderName>;
+  /** ECDH-ES inputs for this recipient, as on `encrypt`. */
   ecdh?: JWEEncryptOptions["ecdh"];
-  /** PBES2 salt. Random 16 bytes when omitted. */
+  /** The PBES2 salt, at least 8 octets. Default: 16 random bytes. */
   p2s?: Uint8Array<ArrayBuffer>;
-  /** PBES2 iteration count, between `1000` and `600_000`. Default: `600_000`. */
+  /** The PBES2 iteration count, from `1000` to `600_000`. Default: `600_000`. */
   p2c?: number;
+  /** The AES-GCMKW key wrapping IV. Random when omitted. */
   keyManagementIV?: Uint8Array<ArrayBuffer>;
 }
-/** Options for `encryptMulti`; per-recipient fields are set on each `JWEMultiRecipient`. */
+/** Options for `encryptMulti`. Key management fields are set on each `JWEMultiRecipient`. */
 export interface JWEMultiEncryptOptions extends StrictOmit<JWEEncryptOptions, "alg" | "ecdh" | "p2s" | "p2c" | "keyManagementIV"> {
-  /** Shared Unprotected Header, written as `unprotected`. */
+  /** The JWE Shared Unprotected Header, written as `unprotected`. It cannot hold `crit` or `zip`. */
   sharedUnprotectedHeader?: Record<string, unknown>;
-  /** External AAD (RFC 7516 §5.1); empty means none (RFC 7516 §7.2.1); not a string or bytes is `ERR_INVALID_OPTION`. */
+  /** The JWE AAD (RFC 7516 §5.1), as UTF-8 text or bytes. An empty value writes no `aad` member (RFC 7516 §7.2.1). Any other type throws `ERR_INVALID_OPTION`. */
   aad?: Uint8Array<ArrayBuffer> | string;
 }
-/** A key lookup for `decrypt`: it receives the validated JWE header. */
+/** A key lookup for `decrypt` and `decryptMulti`. It receives `{ header, token }`: the decoded JWE header and the token. */
 export type JWEKeyLookup<TReturn = CryptoKey | JWK | JWKSet | string | Uint8Array<ArrayBuffer>> = JWKLookupFunction<TReturn, JWEHeaderParameters>;
-/** Key material `decryptMulti` accepts, or a function resolving it from the recipient's header. */
+/** The key `decryptMulti` accepts, or a lookup that returns it from a recipient's header. */
 export type JWEMultiDecryptKey = CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWEKeyLookup;
 /** Options for `decryptMulti`. */
 export interface JWEMultiDecryptOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> extends JWEDecryptOptions<Mode> {
-  /** Max recipients (else `ERR_JWE_INVALID`), JWK Set candidates per recipient, and PBKDF2 iterations summed over the call. Default: `{ recipients: 16, keyCandidates: 8, pbes2Iterations: 2_400_000 }`. */
-  limits?: Pick<JOSELimits, "recipients" | "keyCandidates" | "pbes2Iterations">;
-  /** Try only recipients the key could open, else `ERR_JWE_NO_MATCHING_RECIPIENT`; a JWK Set with no candidate is `ERR_JWK_KEY_NOT_FOUND`. Default: `false` (trial in order). */
+  /**
+   * Max `recipients[]` entries (more throws `ERR_JWE_INVALID`), JWK Set keys per recipient, key trials over the call, and PBKDF2 iterations over the call.
+   * Too many keys or trials throws `ERR_JWK_KEY_NOT_FOUND`.
+   * Default: `{ recipients: 16, keyCandidates: 8, keyAttempts: 16, pbes2Iterations: 2_400_000 }`.
+   */
+  limits?: Pick<JOSELimits, "recipients" | "keyCandidates" | "keyAttempts" | "pbes2Iterations">;
+  /** Skips recipients whose `kid` or `alg` the key cannot serve. No recipient left throws `ERR_JWE_NO_MATCHING_RECIPIENT`. Default: `false`, which tries every recipient in order. */
   strictRecipientMatch?: boolean;
 }
-/** Result of `decryptMulti`, with the header tiers of the recipient that decrypted. */
+/** The result of `decryptMulti`, with the headers of the recipient that decrypted. */
 export interface JWEMultiDecryptResult<T extends JOSEPayload = JOSEPayload> extends Omit<JWEDecryptResult<T>, "protectedHeader"> {
-  /** Protected header as integrity protected (`{}` when absent); `alg`/`enc` may sit in the unprotected tiers (RFC 7516 §7.2.1). */
+  /** The protected header as encrypted, `{}` when absent. `alg` and `enc` can be in the unprotected headers instead (RFC 7516 §7.2.1). */
   protectedHeader: JWEHeaderParameters;
+  /** The JWE Shared Unprotected Header, when present. */
   sharedUnprotectedHeader?: JWEHeaderParameters;
-  /** Unprotected header of the recipient that decrypted. */
+  /** The unprotected header of the recipient that decrypted. */
   recipientHeader?: JWEHeaderParameters;
-  /** Index into `recipients` of the recipient that decrypted. */
+  /** The index in `recipients` of the recipient that decrypted. */
   recipientIndex: number;
 }
 /**
- * A time duration, expressed as an integer number of seconds or a human-readable
- * shorthand like `"10m"`, `"2h"`, `"7D"`.
- *
- * Shared base type for every duration-valued option in the library:
- * {@link ExpiresIn}, {@link NotBeforeIn}, {@link MaxTokenAge}.
+ * A duration: an integer number of seconds, or a string such as `"10m"`, `"2h"` or `"7D"`.
+ * A string without a unit counts seconds. `"M"` is 30 days and `"Y"` is 365 days.
+ * A non-integer number or an unparsed string throws `ERR_INVALID_OPTION`.
  */
 export type Duration = number | `${number}` | `${number}${"s" | "second" | "seconds" | "m" | "minute" | "minutes" | "h" | "hour" | "hours" | "D" | "day" | "days" | "W" | "week" | "weeks" | "M" | "month" | "months" | "Y" | "year" | "years"}`;
-/** Duration until `exp` — the `expiresIn` option on {@link sign} / {@link encrypt}. */
+/** The `expiresIn` option of `sign` and `encrypt`: `exp` is the current time plus this positive duration. */
 export type ExpiresIn = Duration;
-/** Duration from `iat` for `nbf` — the `notBeforeIn` option on {@link sign} / {@link encrypt}. */
+/** The `notBeforeIn` option of `sign` and `encrypt`: `nbf` is the current time plus this duration, zero or more. */
 export type NotBeforeIn = Duration;
-/** Duration for `maxTokenAge` validation on {@link verify} / {@link decrypt}. */
+/** The `maxTokenAge` option of `verify` and `decrypt`: the oldest `iat` accepted, as a positive duration. */
 export type MaxTokenAge = Duration;
 export {};