unjwt 0.7.3 → 0.8.0

package/dist/_chunks/index.d.mts

@@ -1,14 +1,107 @@
+import { UnsecureError, UnsecureErrorCode } from "./libs/unsecure.mjs";
+/**
+ * The closed union of error codes unjwt itself throws.
+ *
+ * Code naming follows the JOSE spec hierarchy:
+ *   ERR_JWT_*  — RFC 7519 JSON Web Token claim validation
+ *   ERR_JWS_*  — RFC 7515 JSON Web Signature
+ *   ERR_JWE_*  — RFC 7516 JSON Web Encryption
+ *   ERR_JWK_*  — RFC 7517 JSON Web Key
+ *   ERR_SESSION_* — the framework session adapters
+ *
+ * Use this type where a typo must not compile — {@link isJWTError} takes it,
+ * so `isJWTError(err, "ERR_JWS_INVALD")` is a type error rather than a check
+ * that silently never matches. Use {@link JWTErrorCode} for values that may
+ * legitimately carry a code this version does not know about.
+ */
+export type KnownJWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | "ERR_SESSION_TOKEN_INVALID" | "ERR_SESSION_READONLY_EVENT" | "ERR_SESSION_KEY_INVALID" | "ERR_SESSION_CONFIG_INVALID" | "ERR_INVALID_OPTION";
+/**
+ * A {@link JWTError} `code`: every {@link KnownJWTErrorCode}, plus any other
+ * string for forward compatibility — a newer unjwt (or a caller constructing
+ * its own `JWTError`) may carry a code this version's union does not list.
+ */
+export type JWTErrorCode = KnownJWTErrorCode | (string & {});
+/**
+ * Maps known error codes to their structured `cause` shapes.
+ * Only codes that carry decoded context beyond the message appear here.
+ * Extend this interface when new structured causes are introduced.
+ */
+export interface JWTErrorCauseMap {
+  /** Decoded claims available at the point the lifetime check failed. */
+  ERR_JWT_EXPIRED: {
+    jti?: string;
+    iat?: number;
+    exp?: number;
+  };
+}
+/**
+ * Base error class for all unjwt errors. Every error thrown by the library is
+ * an instance of `JWTError`, so a single `instanceof` check is sufficient to
+ * distinguish library errors from other thrown values. Use the `code` property
+ * (or the `isJWTError` type guard) to narrow to a specific error condition.
+ *
+ * @example
+ * import { JWTError, isJWTError } from "unjwt/jws";
+ *
+ * try {
+ *   await verify(token, key);
+ * } catch (err) {
+ *   if (isJWTError(err, "ERR_JWT_EXPIRED")) {
+ *     console.log(err.cause.jti); // string | undefined
+ *   }
+ * }
+ */
+export declare class JWTError<TCode extends JWTErrorCode = JWTErrorCode> extends Error {
+  readonly code: TCode;
+  override readonly cause?: unknown;
+  constructor(message: string, code: TCode, cause?: unknown);
+}
 /**
-* The decoded JOSE protected header received by a {@link JWKLookupFunction}.
-*
-* The most commonly inspected fields are explicitly typed; additional
-* algorithm-specific parameters (`epk`, `p2s`, `p2c`, `apu`, `apv`, …) are
-* accessible through the index signature.
-*
-* `alg` is always present on both JWS and JWE tokens. `enc` is only present
-* on JWE tokens.
-*/
-type JWKLookupFunctionHeader = {
+ * Type guard that narrows `error` to `JWTError`.
+ *
+ * When called with a code that is a key of `JWTErrorCauseMap`, the return
+ * type is additionally narrowed to include the structured `cause` shape for
+ * that code. When called with any other `KnownJWTErrorCode`, `code` is narrowed
+ * but `cause` remains `unknown`. When called without a code, narrows only to
+ * `JWTError`.
+ *
+ * `code` is a {@link KnownJWTErrorCode}, so a misspelled code fails to
+ * type-check instead of silently never matching.
+ *
+ * @example
+ * if (isJWTError(err, "ERR_JWT_EXPIRED")) {
+ *   err.cause.jti // string | undefined  ✓
+ * }
+ */
+export declare function isJWTError<T extends keyof JWTErrorCauseMap>(error: unknown, code: T): error is JWTError<T> & {
+  cause: JWTErrorCauseMap[T];
+};
+export declare function isJWTError<T extends KnownJWTErrorCode>(error: unknown, code: T): error is JWTError<T>;
+export declare function isJWTError(error: unknown): error is JWTError;
+/**
+ * Type guard that narrows `error` to the bundled {@link UnsecureError}, the
+ * class thrown by unjwt's codec / JSON / random primitives and carried as the
+ * `cause` of a {@link JWTError} when a wire segment or key field fails to
+ * decode. Pass a `code` to narrow further.
+ *
+ * Check against this export rather than a `UnsecureError` imported from a
+ * consumer-installed `unsecure`: unjwt bundles its own copy, so the two classes
+ * are distinct and `instanceof` against the latter is always `false`.
+ *
+ * @example
+ * import { isJWTError, isUnsecureError } from "unjwt/jws";
+ *
+ * const error = await verify(token, key).catch((e) => e);
+ * if (isJWTError(error, "ERR_JWS_INVALID") && isUnsecureError(error.cause, "MALFORMED")) {
+ *   // a segment of the token is not canonical base64url
+ * }
+ */
+export declare function isUnsecureError<T extends UnsecureErrorCode>(error: unknown, code: T): error is UnsecureError & {
+  code: T;
+};
+export declare function isUnsecureError(error: unknown): error is UnsecureError;
+/** Decoded protected header passed to a `JWKLookupFunction`; `enc` is present on JWE only. */
+export type JWKLookupFunctionHeader = {
   kid?: string;
   alg?: string;
   enc?: string;
@@ -16,237 +109,157 @@ type JWKLookupFunctionHeader = {
   crit?: string[];
   [propName: string]: unknown;
 };
-/**
-* A callback that resolves the decryption or verification key from a token's
-* decoded protected header and the raw compact token string.
-*
-* Accepted by both {@link verify} (JWS) and {@link decrypt} (JWE). When a
-* {@link JWKSet} is returned, the library tries each key whose `kid` and `alg`
-* are compatible with the header in order, stopping at the first that succeeds
-* — see {@link getJWKsFromSet} for the selection logic.
-*
-* Returning a `string` is meaningful for JWE only (PBES2 password); for JWS
-* a string return is encoded to bytes and used as a raw symmetric key.
-*
-* The optional `TReturn` generic lets callers who always hand back a specific
-* key shape (e.g. a `JWK_EC_Public<"ES256">`) preserve that narrowing all the
-* way into the `verify` / `decrypt` key resolution path.
-*/
-type JWKLookupFunction<TReturn = CryptoKey | JWK | JWKSet | string | Uint8Array<ArrayBuffer>> = (header: JWKLookupFunctionHeader, token: string) => TReturn | Promise<TReturn>;
-/**
-* Interface for custom JWK import cache implementations.
-*
-* The adapter receives the full JWK object so each implementation can choose
-* its own keying strategy:
-* - {@link WeakMapJWKCache} uses the object reference (GC-friendly, no string hashing needed)
-* - A `kid`-keyed cache extracts `jwk.kid` and uses it as a string key
-* - A content-hash cache hashes `jwk.k` or `jwk.n`+`jwk.e`
-*
-* @example Use a custom kid-keyed cache:
-* ```ts
-* import { configureJWKCache } from 'unjwt/jwk';
-* const map = new Map<string, CryptoKey>();
-* configureJWKCache({
-*   get: (jwk, alg) => map.get(`${jwk.kid}:${alg}`),
-*   set: (jwk, alg, key) => map.set(`${jwk.kid}:${alg}`, key),
-* });
-* ```
-*/
-interface JWKCacheAdapter {
-  get(jwk: JWK, alg: string): CryptoKey | undefined;
-  set(jwk: JWK, alg: string, key: CryptoKey): void;
+/** Resolves the verify/decrypt key from the protected header 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>> = (header: JWKLookupFunctionHeader, 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. */
+export interface JWKCacheAdapter {
+  get(jwk: JWK, alg: string): CryptoKey | undefined | Promise<CryptoKey | undefined>;
+  set(jwk: JWK, alg: string, key: CryptoKey): void | Promise<void>;
 }
 /** Structure returned for composite AES-CBC + HMAC keys. */
-type CompositeKey = {
-  /** The AES-CBC encryption/decryption key. */encryptionKey: CryptoKey; /** The HMAC key for integrity/authentication. */
+export type CompositeKey = {
+  encryptionKey: CryptoKey;
   macKey: CryptoKey;
 };
-type GenerateKeyAlgorithm = Exclude<JWKAlgorithm, "none" | "dir" | JWK_PBES2>;
-/** Options for the generateKey function. */
-interface GenerateKeyOptions {
-  /** Key usages for the generated key(s). Note: For composite keys (CBC), default usages are applied separately. */
+export type GenerateKeyAlgorithm = Exclude<JWKAlgorithm, "none" | "dir" | JWK_PBES2>;
+/** Options for `generateJWK`; `Kid` is the `kid` option that types the generated `kid`. */
+export interface GenerateJWKOptions<Kid extends string | false = string | false> {
+  /** Key usages; composite (CBC) keys get their default usages separately. */
   keyUsage?: KeyUsage[];
-  /**
-  * Mark the key(s) as extractable. Defaults to true. Ignored when `toJWK` is set —
-  * the JWK output requires exporting the intermediate key. For long-lived asymmetric
-  * private keys that should never leave the runtime, prefer `false` (and omit `toJWK`):
-  * the key still signs/decrypts but its material cannot be exported.
-  */
-  extractable?: boolean;
-  /** RSA modulus length. Defaults to 2048. */
+  /** RSA modulus length. Default: `2048`. */
   modulusLength?: number;
-  /** RSA public exponent. Defaults to 65537 (0x010001). */
+  /** RSA public exponent. Default: `65537`. */
   publicExponent?: Uint8Array<ArrayBuffer>;
-  /** Named curve for EC or OKP keys. Defaults to "P-256" for EC and "Ed25519" for OKP. */
-  namedCurve?: "P-256" | "P-384" | "P-521" | "X25519" | "Ed25519" | "Ed448";
-  /**
-  * Export the generated key(s) as JWK. When `true`, keys are returned in JWK
-  * format with a generated `kid`. To include additional JWK parameters
-  * (e.g. a custom `kid`), use {@link generateJWK} instead.
-  */
-  toJWK?: boolean;
-}
-type GenerateKeyReturnJWK<TAlg extends GenerateKeyAlgorithm> = TAlg extends JWK_Asymmetric_Algorithm ? JWK_Pair<TAlg> : TAlg extends JWK_AES_CBC_HMAC | JWK_Symmetric_Algorithm ? JWK_oct<TAlg> : never;
-type GenerateKeyReturnCrypto<TAlg extends GenerateKeyAlgorithm> = TAlg extends JWK_AES_CBC_HMAC ? Uint8Array<ArrayBuffer> : TAlg extends JWK_Asymmetric_Algorithm ? CryptoKeyPair : CryptoKey;
-type GenerateKeyReturn<TAlg extends GenerateKeyAlgorithm, TOptions extends GenerateKeyOptions> = TOptions["toJWK"] extends true ? GenerateKeyReturnJWK<TAlg> : GenerateKeyReturnCrypto<TAlg>;
-type GenerateJWKOptions = Omit<GenerateKeyOptions, "toJWK" | "extractable">;
-type GenerateJWKReturn<TAlg extends GenerateKeyAlgorithm> = GenerateKeyReturnJWK<TAlg>;
-/** Options for the deriveKeyFromPassword function. */
-interface DeriveKeyOptions {
-  /** Salt value (p2s). Must be at least 8 bytes. */
-  salt: Uint8Array<ArrayBuffer>;
-  /** Iteration count (p2c). Must be a positive integer. */
+  /** EC/OKP curve. Default: `"P-256"` (EC), `"Ed25519"` (OKP). */
+  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. */
+  kid?: Kid;
+}
+/** Options for `generateKey`; `ToJWK` is the `toJWK` literal that 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`. */
+  extractable?: boolean;
+  /** Return JWKs instead of key objects. */
+  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. */
+  kid?: Kid;
+}
+/** `generateKey` result per algorithm without `toJWK`: `CryptoKey` (symmetric), raw bytes (`A*CBC-HS*`), `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`. */
+export type GeneratedJWKMap<Kid extends string | false = string> = { [A in GenerateKeyAlgorithm]: A extends JWK_Asymmetric_Algorithm ? GeneratedJWKPair<JWK_Pair<A>, A, Kid> : JWK_oct<A> & GeneratedJWKMembers<A, Kid>; };
+/** `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`. */
+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`. */
+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. */
+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). */
+  salt: string | Uint8Array<ArrayBuffer>;
+  /** Iteration count (p2c), a positive integer. */
   iterations: number;
-  /** Key usages for the derived key. Defaults to ["wrapKey", "unwrapKey"]. */
+  /** Key usages. Default: `["wrapKey", "unwrapKey"]`. */
   keyUsage?: KeyUsage[];
-  /** Mark the derived key as extractable. Defaults to false. Ignored when `toJWK` is set — the JWK output requires exporting the derived key. */
+  /** Mark the derived key extractable; ignored when `toJWK` is set. Default: `false`. */
   extractable?: boolean;
-  /**
-  * Export the derived key as JWK_oct. When `true`, returns the derived key in
-  * JWK format. To include additional JWK parameters (e.g. a custom `kid`),
-  * use {@link deriveJWKFromPassword} instead.
-  */
+  /** Return the derived key as a `JWK_oct`. */
   toJWK?: boolean;
 }
-/** PBES2 → AES-KW alg that ends up stamped on the derived JWK's `alg`. */
+/** PBES2 → AES-KW `alg` stamped on the derived JWK. */
 type DerivedJWKAlg<TAlg extends JWK_PBES2> = TAlg extends "PBES2-HS256+A128KW" ? "A128KW" : TAlg extends "PBES2-HS384+A192KW" ? "A192KW" : TAlg extends "PBES2-HS512+A256KW" ? "A256KW" : JWK_AES_KW;
-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;
-type KeyManagementAlgorithm = JWK_RSA_ENC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_PBES2 | JWK_ECDH_ES | "dir";
-type ContentEncryptionAlgorithm = JWK_AES_GCM | JWK_AES_CBC_HMAC;
-/**
-* Keys admissible as the `wrappingKey` argument of {@link wrapKey}, narrowed
-* by the key management algorithm. Mirrors the runtime branches in
-* `jwk.wrapKey` and the inference in `inferJWEAllowedAlgorithms`.
-*
-* - `dir` accepts any symmetric JWK (the key _is_ the CEK).
-* - AES-GCMKW tolerates a JWK whose `alg` is the bare `A*GCM` counterpart —
-*   matches the `jweAlgsFromOctJWK` aliasing rule.
-*/
-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${"128" | "192" | "256"}GCM`> : A extends "dir" ? CryptoKey | JWK_oct | Uint8Array<ArrayBuffer> : never;
-/**
-* Keys admissible as the `unwrappingKey` argument of {@link unwrapKey}.
-* The private-side counterpart of {@link WrappingKeyFor} — symmetric branches
-* are identical; asymmetric branches use the `_Private` variants.
-*/
-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${"128" | "192" | "256"}GCM`> : A extends "dir" ? CryptoKey | JWK_oct | Uint8Array<ArrayBuffer> : never;
-/** Options for the wrapKey function. */
-interface WrapKeyOptions {
-  /**
-  * Initialization Vector for AES-GCMKW. A fresh random IV is generated when
-  * not provided — production code should always omit this option.
-  *
-  * **Never reuse an IV and never derive it from external input.** A single
-  * IV reused under the same wrapping key breaks AES-GCM entirely (plaintext
-  * recovery and forgery). Provided only for tests and reproduction of known
-  * vectors in security research.
-  */
+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;
+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. */
+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`. */
+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). */
   iv?: Uint8Array<ArrayBuffer>;
   /** PBES2 Salt value (p2s). Required for PBES2 algorithms. */
   p2s?: Uint8Array<ArrayBuffer>;
   /** PBES2 Iteration count (p2c). Required for PBES2 algorithms. */
   p2c?: number;
-  /** ECDH-ES specific options. */
   ecdh?: {
-    /**
-    * ECDH-ES ephemeral key material. A fresh ephemeral key pair is generated
-    * automatically when this is not provided.
-    */
-    ephemeralKey?: CryptoKey | JWK_EC_Private | CryptoKeyPair | {
-      publicKey: CryptoKey | JWK_EC_Public;
-      privateKey: CryptoKey | JWK_EC_Private;
-    }; /** Agreement PartyUInfo (apu). */
-    partyUInfo?: Uint8Array<ArrayBuffer>; /** Agreement PartyVInfo (apv). */
+    /** Ephemeral key material. Generated when omitted. */
+    ephemeralKey?: ECDHEphemeralKeyInput;
+    /** Agreement PartyUInfo (apu). */
+    partyUInfo?: Uint8Array<ArrayBuffer>;
+    /** Agreement PartyVInfo (apv). */
     partyVInfo?: Uint8Array<ArrayBuffer>;
-    /**
-    * Content encryption algorithm used for key-length derivation.
-    * Required only when `alg` is `"ECDH-ES"` (direct key agreement).
-    * Not needed for `ECDH-ES+A128KW`, `+A192KW`, or `+A256KW`.
-    */
+    /** Required only for direct `"ECDH-ES"` key agreement. */
     enc?: ContentEncryptionAlgorithm;
   };
 }
-/**
-* Result of {@link wrapKey}, discriminated by key management algorithm family.
-*
-* Narrow the shape by passing a literal `alg` to `wrapKey`:
-* - PBES2 → `{ encryptedKey, p2s, p2c }`
-* - AES-GCMKW → `{ encryptedKey, iv, tag }`
-* - ECDH-ES / ECDH-ES+A*KW → `{ encryptedKey, epk, apu?, apv? }`
-* - dir / AES-KW / RSA-OAEP → `{ encryptedKey }`
-*/
-type WrapKeyResult<TAlg extends KeyManagementAlgorithm = KeyManagementAlgorithm> = TAlg extends JWK_PBES2 ? {
-  encryptedKey: Uint8Array<ArrayBuffer>; /** PBES2 Salt value (p2s). Base64URL encoded. */
-  p2s: string; /** PBES2 Iteration count (p2c). */
+/** 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;
   p2c: number;
 } : TAlg extends JWK_AES_GCM_KW ? {
-  encryptedKey: Uint8Array<ArrayBuffer>; /** AES-GCMKW Initialization Vector. Base64URL encoded. */
-  iv: string; /** AES-GCMKW Authentication Tag. Base64URL encoded. */
+  encryptedKey: Uint8Array<ArrayBuffer>;
+  iv: string;
   tag: string;
 } : TAlg extends JWK_ECDH_ES ? {
-  encryptedKey: Uint8Array<ArrayBuffer>; /** Ephemeral Public Key. */
-  epk: JWK_EC_Public; /** Agreement PartyUInfo. Base64URL encoded. Present only when supplied. */
-  apu?: string; /** Agreement PartyVInfo. Base64URL encoded. Present only when supplied. */
+  encryptedKey: Uint8Array<ArrayBuffer>;
+  epk: JWK_EC_Public | JWK_OKP_Public;
+  apu?: string;
   apv?: string;
 } : {
   encryptedKey: Uint8Array<ArrayBuffer>;
 };
-/** Options for the unwrapKey function. */
-interface UnwrapKeyOptions {
-  /**
-  * Output format of the unwrapped key.
-  * - `"cryptokey"` (default) — returns a `CryptoKey` ready for use with WebCrypto.
-  * - `"raw"` — returns the raw key bytes as `Uint8Array` (useful for
-  *   interoperability or when the algorithm is not directly importable).
-  */
+/** Options for `unwrapKey`. */
+export interface UnwrapKeyOptions<TAlg extends KeyManagementAlgorithm = KeyManagementAlgorithm> {
+  alg: TAlg;
+  /** `"cryptokey"` returns a `CryptoKey`, `"raw"` the key bytes. Default: `"cryptokey"`. */
   format?: "cryptokey" | "raw";
-  /** Initialization Vector (required for AES-GCMKW). Base64URL encoded or Uint8Array. */
+  /** Required for AES-GCMKW; base64url or bytes. */
   iv?: Uint8Array<ArrayBuffer> | string;
-  /** Authentication Tag (required for AES-GCMKW). Base64URL encoded or Uint8Array. */
+  /** Required for AES-GCMKW; base64url or bytes. */
   tag?: Uint8Array<ArrayBuffer> | string;
-  /** PBES2 Salt value (required for PBES2). Base64URL encoded or Uint8Array. */
+  /** Required for PBES2; base64url or bytes. */
   p2s?: Uint8Array<ArrayBuffer> | string;
-  /** PBES2 Iteration count (required for PBES2). */
+  /** Required for PBES2. */
   p2c?: number;
   /** Minimum accepted PBES2 `p2c` on unwrap. Defaults to 1000 (RFC 7518 §4.8.1.2). */
   minIterations?: number;
-  /** Maximum accepted PBES2 `p2c` on unwrap. Defaults to 1_000_000 to cap PBKDF2 DoS potential. */
+  /** Maximum accepted PBES2 `p2c` on unwrap. Default: `600_000`. */
   maxIterations?: number;
-  /** ECDH-ES Ephemeral Public Key (required for ECDH-ES). */
-  epk?: JWK_EC_Public | CryptoKey;
-  /** ECDH-ES Agreement PartyUInfo. Base64URL encoded or Uint8Array. */
+  /** Required for ECDH-ES. */
+  epk?: JWK_EC_Public | JWK_OKP_Public | CryptoKey;
   apu?: Uint8Array<ArrayBuffer> | string;
-  /** ECDH-ES Agreement PartyVInfo. Base64URL encoded or Uint8Array. */
   apv?: Uint8Array<ArrayBuffer> | string;
-  /** Content Encryption Algorithm used with ECDH-ES (required for direct key agreement). */
+  /** Required for direct ECDH-ES key agreement. */
   enc?: ContentEncryptionAlgorithm;
-  /** Expected unwrapped key algorithm (e.g., 'AES-GCM', 'AES-CBC'). Used by crypto.subtle.unwrapKey. */
+  /** Algorithm to import the unwrapped key as. */
   unwrappedKeyAlgorithm?: string | Algorithm | RsaOaepParams | AesCtrParams | AesCbcParams | AesGcmParams;
-  /** Expected key usages for the unwrapped key. */
   keyUsage?: KeyUsage[];
-  /** Mark the unwrapped key as extractable. Defaults to true. */
+  /** Mark the unwrapped key extractable. Default: `true`. */
   extractable?: boolean;
 }
-/**
-* 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 JSON Web Key Parameters.
-*
-* The `Alg` type parameter constrains the JWK's `alg` field. Each concrete JWK
-* interface below tightens `Alg` to the algorithm family admissible for that key
-* type — e.g. a `JWK_oct<JWK_HMAC>` can only hold `"HS256" | "HS384" | "HS512"`
-* in `alg`.
-*/
-interface JWKParameters<Alg extends string = string> {
+/** Result of `unwrapKey`: bytes for `format: "raw"`, else a `CryptoKey`; a non-literal `format` keeps 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. */
+export interface JWKParameters<Alg extends string = string> {
   /** JWK "kty" (Key Type) Parameter */
   "kty": string;
-  /**
-  * JWK "alg" (Algorithm) Parameter
-  *
-  * @see {@link https://github.com/panva/jose/issues/210 Algorithm Key Requirements}
-  */
+  /** JWK "alg" (Algorithm) Parameter */
   "alg"?: Alg;
   /** JWK "key_ops" (Key Operations) Parameter */
   "key_ops"?: KeyUsage[];
@@ -264,16 +277,18 @@ interface JWKParameters<Alg extends string = string> {
   "x5u"?: string;
   /** JWK "kid" (Key ID) Parameter */
   "kid"?: string;
-  /**
-  * Non-standard JWK content encryption algorithm hint.
-  * When `alg` is `"dir"`, the library reads this field to infer the
-  * content encryption algorithm (`enc`) when it is not provided in options.
-  */
+  /** Non-standard `enc` hint, read when `alg` is `"dir"` and 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`. */
+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. */
+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 */
-interface JWK_EC_Public<Alg extends JWK_ECDSA | JWK_ECDH_ES | (string & {}) = string> extends JWKParameters<Alg> {
-  /** EC JWK "kty" (Key Type) Parameter */
+export interface JWK_EC_Public<Alg extends JWK_ECDSA | JWK_ECDH_ES | (string & {}) = string> extends JWKParameters<Alg> {
   kty: "EC";
   /** EC JWK "crv" (Curve) Parameter */
   crv: string;
@@ -283,15 +298,14 @@ interface JWK_EC_Public<Alg extends JWK_ECDSA | JWK_ECDH_ES | (string & {}) = st
   y: string;
 }
 /** Private EC JSON Web Keys */
-interface JWK_EC_Private<Alg extends JWK_ECDSA | JWK_ECDH_ES | (string & {}) = string> extends JWK_EC_Public<Alg> {
+export interface JWK_EC_Private<Alg extends JWK_ECDSA | JWK_ECDH_ES | (string & {}) = string> extends JWK_EC_Public<Alg> {
   /** EC JWK "d" (ECC Private Key) Parameter */
   d: string;
 }
 /** EC JSON Web Keys */
-type JWK_EC<Alg extends JWK_ECDSA | JWK_ECDH_ES | (string & {}) = string> = JWK_EC_Public<Alg> | JWK_EC_Private<Alg>;
+export type JWK_EC<Alg extends JWK_ECDSA | JWK_ECDH_ES | (string & {}) = string> = JWK_EC_Public<Alg> | JWK_EC_Private<Alg>;
 /** Public RSA JSON Web Keys */
-interface JWK_RSA_Public<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC | (string & {}) = string> extends JWKParameters<Alg> {
-  /** RSA JWK "kty" (Key Type) Parameter */
+export interface JWK_RSA_Public<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC | (string & {}) = string> extends JWKParameters<Alg> {
   kty: "RSA";
   /** RSA JWK "e" (Exponent) Parameter */
   e: string;
@@ -300,7 +314,7 @@ interface JWK_RSA_Public<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC |
   oth?: RsaOtherPrimesInfo[];
 }
 /** Private RSA JSON Web Keys */
-interface JWK_RSA_Private<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC | (string & {}) = string> extends JWK_RSA_Public<Alg> {
+export interface JWK_RSA_Private<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC | (string & {}) = string> extends JWK_RSA_Public<Alg> {
   /** RSA JWK "d" (Private Exponent) Parameter */
   d: string;
   /** RSA JWK "dp" (First Factor CRT Exponent) Parameter */
@@ -315,10 +329,9 @@ interface JWK_RSA_Private<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC |
   qi: string;
 }
 /** RSA JSON Web Keys */
-type JWK_RSA<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC | (string & {}) = string> = JWK_RSA_Public<Alg> | JWK_RSA_Private<Alg>;
+export type JWK_RSA<Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC | (string & {}) = string> = JWK_RSA_Public<Alg> | JWK_RSA_Private<Alg>;
 /** Public ED JSON Web Keys */
-interface JWK_OKP_Public<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES | (string & {}) = string> extends JWKParameters<Alg> {
-  /** ED JWK "kty" (Key Type) Parameter */
+export interface JWK_OKP_Public<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES | (string & {}) = string> extends JWKParameters<Alg> {
   kty: "OKP";
   /** ED JWK "crv" (Curve) Parameter */
   crv: string;
@@ -326,45 +339,30 @@ interface JWK_OKP_Public<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES | (string & {})
   x: string;
 }
 /** Private ED JSON Web Keys */
-interface JWK_OKP_Private<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES | (string & {}) = string> extends JWK_OKP_Public<Alg> {
+export interface JWK_OKP_Private<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES | (string & {}) = string> extends JWK_OKP_Public<Alg> {
   /** ED JWK "d" (Private Key) Parameter */
   d: string;
 }
 /** OKP JSON Web Keys */
-type JWK_OKP<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES | (string & {}) = string> = JWK_OKP_Public<Alg> | JWK_OKP_Private<Alg>;
+export type JWK_OKP<Alg extends JWK_OKP_SIGN | JWK_ECDH_ES | (string & {}) = string> = JWK_OKP_Public<Alg> | JWK_OKP_Private<Alg>;
 /** oct JSON Web Keys */
-interface JWK_oct<Alg extends JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC | JWK_PBES2 | "dir" | (string & {}) = string> extends JWKParameters<Alg> {
-  /** Oct JWK "kty" (Key Type) Parameter */
+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" | (string & {}) = string> extends JWKParameters<Alg> {
   kty: "oct";
   /** Oct JWK "k" (Key Value) Parameter */
   k: string;
 }
 /** Symmetric JSON Web Keys */
-type JWK_Symmetric<Alg extends JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW | JWK_AES_CBC_HMAC | JWK_PBES2 | "dir" | (string & {}) = string> = JWK_oct<Alg>;
+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" | (string & {}) = string> = JWK_oct<Alg>;
 /** Asymmetric JSON Web Keys */
-type JWK_Asymmetric<Alg extends string = string> = JWK_RSA<Alg> | JWK_EC<Alg> | JWK_OKP<Alg>;
+export type JWK_Asymmetric<Alg extends string = string> = JWK_RSA<Alg> | JWK_EC<Alg> | JWK_OKP<Alg>;
 /** Public JSON Web Keys */
-type JWK_Public<Alg extends string = string> = JWK_RSA_Public<Alg> | JWK_EC_Public<Alg> | JWK_OKP_Public<Alg>;
+export type JWK_Public<Alg extends string = string> = JWK_RSA_Public<Alg> | JWK_EC_Public<Alg> | JWK_OKP_Public<Alg>;
 /** Private JSON Web Keys */
-type JWK_Private<Alg extends string = string> = JWK_RSA_Private<Alg> | JWK_EC_Private<Alg> | JWK_OKP_Private<Alg>;
-/**
-* JSON Web Key ({@link https://www.rfc-editor.org/rfc/rfc7517 JWK}). "RSA", "EC", "OKP" and "oct" key types are supported.
-*/
-type JWK<Alg extends string = string> = JWK_oct<Alg> | JWK_RSA<Alg> | JWK_EC<Alg> | JWK_OKP<Alg>;
-/**
-* A pair of public and private JSON Web Keys, narrowed by `Alg` when that
-* uniquely identifies the key family:
-*
-* - `JWK_Pair<"RS256">` → RSA pair only
-* - `JWK_Pair<"ES256">` → EC pair only
-* - `JWK_Pair<"ECDH-ES+A256KW">` → EC pair **or** OKP pair (curve decides at runtime)
-* - `JWK_Pair<"Ed25519">` / `JWK_Pair<"EdDSA">` → OKP pair only
-*
-* The final branch is a generic fallback (`Alg = string`, or any custom /
-* forward-compat algorithm that doesn't match a known family) — it yields
-* the permissive three-branch union.
-*/
-type JWK_Pair<Alg extends string = string> = Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC ? {
+export type JWK_Private<Alg extends string = string> = JWK_RSA_Private<Alg> | JWK_EC_Private<Alg> | JWK_OKP_Private<Alg>;
+/** JSON Web Key (RFC 7517) of type "RSA", "EC", "OKP" or "oct". */
+export type JWK<Alg extends string = string> = JWK_oct<Alg> | JWK_RSA<Alg> | JWK_EC<Alg> | JWK_OKP<Alg>;
+/** Public/private JWK pair, narrowed to the key family `Alg` identifies (ECDH-ES: EC or OKP). */
+export type JWK_Pair<Alg extends string = string> = Alg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC ? {
   publicKey: JWK_RSA_Public<Alg>;
   privateKey: JWK_RSA_Private<Alg>;
 } : Alg extends JWK_ECDSA ? {
@@ -389,38 +387,49 @@ type JWK_Pair<Alg extends string = string> = Alg extends JWK_RSA_SIGN | JWK_RSA_
   publicKey: JWK_OKP_Public<Alg>;
   privateKey: JWK_OKP_Private<Alg>;
 };
-/**
-* JSON Web Key Set ({@link https://www.rfc-editor.org/rfc/rfc7517 JWK Set}). "RSA", "EC" and "oct" key types are supported.
-*
-* The optional `T` generic preserves the precise key tuple when constructed
-* in TS — e.g. `JWKSet<[JWK_oct<"HS256">, JWK_EC_Public<"ES256">]>` — while the
-* default `JWK[]` keeps the permissive behavior expected for JWKS fetched from
-* external sources (runtime trials each candidate).
-*/
-interface JWKSet<T extends readonly JWK[] = JWK[]> {
-  /** JWK Set "keys" Parameter */
+/** JSON Web Key Set (RFC 7517); `T` preserves a precise key tuple. */
+export interface JWKSet<T extends readonly JWK[] = JWK[]> {
   keys: T;
   [parameter: string]: unknown;
 }
 /** JWK Key Algorithms */
-type JWK_HMAC = "HS256" | "HS384" | "HS512";
-type JWK_RSA_SIGN = "RS256" | "RS384" | "RS512";
-type JWK_RSA_PSS = "PS256" | "PS384" | "PS512";
-type JWK_ECDSA = "ES256" | "ES384" | "ES512";
-type JWK_RSA_ENC = "RSA-OAEP" | "RSA-OAEP-256" | "RSA-OAEP-384" | "RSA-OAEP-512";
-type JWK_AES_KW = "A128KW" | "A192KW" | "A256KW";
-type JWK_AES_CBC_HMAC = "A128CBC-HS256" | "A192CBC-HS384" | "A256CBC-HS512";
-type JWK_AES_GCM = "A128GCM" | "A192GCM" | "A256GCM";
-type JWK_AES_GCM_KW = "A128GCMKW" | "A192GCMKW" | "A256GCMKW";
-type JWK_PBES2 = "PBES2-HS256+A128KW" | "PBES2-HS384+A192KW" | "PBES2-HS512+A256KW";
-type JWK_ECDH_ES = "ECDH-ES" | "ECDH-ES+A128KW" | "ECDH-ES+A192KW" | "ECDH-ES+A256KW";
-type JWK_OKP_SIGN = "Ed25519" | "EdDSA";
-type JWK_Symmetric_Algorithm = JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM_KW;
-type JWK_Asymmetric_Algorithm = JWK_RSA_SIGN | JWK_RSA_PSS | JWK_ECDSA | JWK_RSA_ENC | JWK_OKP_SIGN | JWK_ECDH_ES;
-type JWKAlgorithm = JWK_Symmetric_Algorithm | JWK_Asymmetric_Algorithm | JWK_AES_CBC_HMAC | JWK_PBES2 | JWK_ECDH_ES | "dir";
-type JWKPEMAlgorithm = JWK_RSA_PSS | JWK_RSA_SIGN | JWK_RSA_ENC | JWK_ECDSA | JWK_ECDH_ES | JWK_OKP_SIGN;
-/** Header Parameters common to JWE and JWS */
-interface JoseHeaderParameters {
+export type JWK_HMAC = "HS256" | "HS384" | "HS512";
+export type JWK_RSA_SIGN = "RS256" | "RS384" | "RS512";
+export type JWK_RSA_PSS = "PS256" | "PS384" | "PS512";
+export type JWK_ECDSA = "ES256" | "ES384" | "ES512";
+export type JWK_RSA_ENC = "RSA-OAEP" | "RSA-OAEP-256" | "RSA-OAEP-384" | "RSA-OAEP-512";
+export type JWK_AES_KW = "A128KW" | "A192KW" | "A256KW";
+export type JWK_AES_CBC_HMAC = "A128CBC-HS256" | "A192CBC-HS384" | "A256CBC-HS512";
+export type JWK_AES_GCM = "A128GCM" | "A192GCM" | "A256GCM";
+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";
+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;
+export type JWKAlgorithm = JWK_Symmetric_Algorithm | JWK_Asymmetric_Algorithm | JWK_AES_CBC_HMAC | JWK_PBES2 | JWK_ECDH_ES | "dir";
+export type JWKPEMAlgorithm = JWK_RSA_PSS | JWK_RSA_SIGN | JWK_RSA_ENC | JWK_ECDSA | JWK_ECDH_ES | JWK_OKP_SIGN;
+type GeneratedJWKMembers<A, Kid> = [Kid] extends [false] ? {
+  alg: A;
+} : [Kid] extends [string] ? {
+  alg: A;
+  kid: string;
+} : {
+  alg: A;
+  kid?: string;
+};
+type GeneratedJWKPair<P, A, Kid> = P extends {
+  privateKey: infer Private;
+  publicKey: infer Public;
+} ? {
+  privateKey: Private & GeneratedJWKMembers<A, Kid>;
+  publicKey: Public & GeneratedJWKMembers<A, Kid>;
+} : never;
+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];
+/** Header Parameters common to JWE and JWS. */
+export interface JoseHeaderParameters {
   /** "kid" (Key ID) Header Parameter */
   kid?: string;
   /** "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter */
@@ -439,19 +448,21 @@ interface JoseHeaderParameters {
   cty?: string;
   /** "crit" (Critical) Header Parameter */
   crit?: string[];
-  /** Any other JWS/JWE Header member. */
   [propName: string]: unknown;
 }
-/**
-* Payload accepted by {@link sign} and {@link encrypt}.
-*
-* Covers raw strings and bytes for non-JWT use, plus any JSON-serializable
-* object for JWT and generic structured payloads. JWT-specific claim names
-* are not enforced at this level — use {@link JWTClaims} when you want typed
-* claim names and spec-compliant field types.
-*/
-type JOSEPayload = string | Uint8Array<ArrayBuffer> | Record<string, unknown>;
-interface JWTClaims {
+/** Payload accepted by `sign` and `encrypt`: a string, raw bytes, or a JSON object. */
+export type JOSEPayload = string | Uint8Array<ArrayBuffer> | Record<string, unknown>;
+/** How a verified or decrypted payload is decoded: `"json"` object, UTF-8 `"string"`, or raw `"bytes"`. */
+export type JOSEPayloadMode = keyof JOSEPayloadTypeMap;
+/** The payload type each `JOSEPayloadMode` resolves to. */
+export interface JOSEPayloadTypeMap<T = JWTClaims> {
+  json: T;
+  string: string;
+  bytes: Uint8Array<ArrayBuffer>;
+}
+/** The payload type returned under `Mode`; a union of modes yields the union of payloads. */
+export type PayloadOf<Mode extends JOSEPayloadMode, T = JWTClaims> = JOSEPayloadTypeMap<T>[Mode];
+export interface JWTClaims {
   /** "iss" (Issuer) Claim */
   iss?: string;
   /** "sub" (Subject) Claim */
@@ -466,679 +477,360 @@ interface JWTClaims {
   iat?: number;
   /** "jti" (JWT ID) Claim */
   jti?: string;
-  /** Any other JWT member. */
   [propName: string]: unknown;
 }
-interface JWT<T = JWTClaims> {
+export interface JWT<T = JWTClaims> {
   header: JoseHeaderParameters & {
-    /** "alg" (Algorithm) Header Parameter */alg: string;
+    /** "alg" (Algorithm) Header Parameter */
+    alg: string;
   };
   claims: T;
 }
-interface JWTClaimValidationOptions {
-  /** Expected JWT "aud" (Audience) Claim value(s). Implies presence requirement. */
+/** Per-call work bounds; each entry must be a positive integer, else `ERR_INVALID_OPTION`. */
+export interface JOSELimits {
+  /** Max `signatures[]` entries in a JWS JSON serialization. @default 16 */
+  signatures?: number;
+  /** Max `recipients[]` entries in a JWE JSON serialization. @default 16 */
+  recipients?: number;
+  /** Max JWK Set candidates tried per token after `kid`/`alg`/`use` filtering. @default 8 */
+  keyCandidates?: number;
+  /** Total PBKDF2 iterations one call may spend across PBES2 attempts. @default 2_400_000 */
+  pbes2Iterations?: number;
+}
+/** Claim expectations, each checked when set; an empty or malformed value is `ERR_INVALID_OPTION`. */
+export interface JWTClaimValidationOptions {
+  /** Expected "aud" value(s); `aud` is checked only when this is set (RFC 7519 §4.1.3). */
   audience?: string | string[];
-  /** Expected JWT "iss" (Issuer) Claim value(s). Implies presence requirement. */
+  /** Expected "iss" value(s); implies presence. */
   issuer?: string | string[];
-  /** Expected JWT "sub" (Subject) Claim value. Implies presence requirement. */
+  /** Expected "sub" value; implies presence. */
   subject?: string;
-  /** Maximum token age, from the JWT "iat" (Issued At) Claim value. Implies presence requirement. */
+  /** Maximum token age from "iat"; implies presence. */
   maxTokenAge?: MaxTokenAge;
-  /**
-  * Clock skew tolerance (in seconds) for validating time-based claims (nbf/exp/iat).
-  *
-  * @default 0
-  */
-  clockTolerance?: number;
-  /** Expected JWT "typ" (Type) Header Parameter value. Implies presence requirement. */
+  /** Clock skew tolerance for nbf/exp/iat, in seconds or a `Duration`. @default 0 */
+  clockTolerance?: number | Duration;
+  /** Expected "typ" header, compared as a media type (RFC 7515 §4.1.9); implies presence. */
   typ?: string;
-  /** Date to use when comparing NumericDate claims, defaults to `new Date()`. */
+  /** Date used for NumericDate comparisons. @default new Date() */
   currentDate?: Date;
   /** Additional required claim names. */
   requiredClaims?: string[];
-  /**
-  * Critical header parameters that this caller understands and has processed.
-  * If the token's `crit` header lists a parameter not present in this list
-  * (and not natively understood by the library), verification will fail per
-  * 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). */
   recognizedHeaders?: string[];
 }
-/**
-* All known error codes thrown by unjwt.
-*
-* Code naming follows the JOSE spec hierarchy:
-*   ERR_JWT_*  — RFC 7519 JSON Web Token claim validation
-*   ERR_JWS_*  — RFC 7515 JSON Web Signature
-*   ERR_JWE_*  — RFC 7516 JSON Web Encryption
-*   ERR_JWK_*  — RFC 7517 JSON Web Key
-*/
-type JWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | (string & {});
-/**
-* Maps known error codes to their structured `cause` shapes.
-* Only codes that carry decoded context beyond the message appear here.
-* Extend this interface when new structured causes are introduced.
-*/
-interface JWTErrorCauseMap {
-  /** Decoded claims available at the point the lifetime check failed. */
-  ERR_JWT_EXPIRED: {
-    jti?: string;
-    iat?: number;
-    exp?: number;
-  };
+/** Time claims a producer computes; a claim already in the payload is kept as given. */
+export interface JWTTimeClaimOptions {
+  /** Reference moment for `iat` and relative durations. @default new Date() */
+  currentDate?: Date;
+  /** Duration until `exp`; exclusive with `expiresAt`. */
+  expiresIn?: ExpiresIn;
+  /** Absolute `exp`; exclusive with `expiresIn`. */
+  expiresAt?: Date;
+  /** Duration from `iat` until `nbf` (`0` sets `nbf = iat`); exclusive with `notBeforeAt`. */
+  notBeforeIn?: ExpiresIn;
+  /** Absolute `nbf` (RFC 7519 §4.1.5); exclusive with `notBeforeIn`. */
+  notBeforeAt?: Date;
 }
-/**
-* Base error class for all unjwt errors. Every error thrown by the library is
-* an instance of `JWTError`, so a single `instanceof` check is sufficient to
-* distinguish library errors from other thrown values. Use the `code` property
-* (or the `isJWTError` type guard) to narrow to a specific error condition.
-*
-* @example
-* import { JWTError, isJWTError } from "unjwt/jws";
-*
-* try {
-*   await verify(token, key);
-* } catch (err) {
-*   if (isJWTError(err, "ERR_JWT_EXPIRED")) {
-*     console.log(err.cause.jti); // string | undefined
-*   }
-* }
-*/
-declare class JWTError<TCode extends JWTErrorCode = JWTErrorCode> extends Error {
-  readonly code: TCode;
-  override readonly cause?: unknown;
-  constructor(message: string, code: TCode, cause?: unknown);
+/** Options shared by `verify` and `decrypt` (compact and multi). */
+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 */
+  allowSymmetricJWKSet?: boolean;
+  /** Payload decoding mode; a mismatch is `ERR_JWS_INVALID` / `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
+   */
+  forceUint8Array?: boolean;
+  /** `false` skips claim validation; `true` with a non-`"json"` payload is `ERR_INVALID_OPTION`. */
+  validateClaims?: boolean;
 }
-/**
-* Type guard that narrows `error` to `JWTError`.
-*
-* When called with a code that is a key of `JWTErrorCauseMap`, the return
-* type is additionally narrowed to include the structured `cause` shape for
-* that code. When called with any other `JWTErrorCode`, `code` is narrowed
-* but `cause` remains `unknown`. When called without a code, narrows only to
-* `JWTError`.
-*
-* @example
-* if (isJWTError(err, "ERR_JWT_EXPIRED")) {
-*   err.cause.jti // string | undefined  ✓
-* }
-*/
-declare function isJWTError<T extends keyof JWTErrorCauseMap>(error: unknown, code: T): error is JWTError<T> & {
-  cause: JWTErrorCauseMap[T];
-};
-declare function isJWTError<T extends JWTErrorCode>(error: unknown, code: T): error is JWTError<T>;
-declare function isJWTError(error: unknown): error is JWTError;
-type StrictOmit<T, K extends keyof T | (string & {}) | (number & {}) | (symbol & {})> = { [P in keyof T as P extends K ? never : P]: T[P] };
+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. */
-type JWSAlgorithm = JWK_HMAC | JWK_RSA_SIGN | JWK_RSA_PSS | JWK_ECDSA | JWK_OKP_SIGN;
-/**
-* Asymmetric private JWKs admissible as a signing key. RSA keys carry a
-* signing `alg` (RS* or PS*); EC keys carry an ECDSA alg; OKP keys carry an Ed
-* signing alg.
-*/
-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. RSA keys carry a
-* signing `alg` (RS* or PS*); EC keys carry an ECDSA alg; OKP keys carry an Ed
-* signing alg.
-*/
-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 the `key` argument of {@link sign}. HMAC oct keys carry a
-* {@link JWK_HMAC} alg; asymmetric private keys carry their family's signing alg.
-* A JWK whose `alg` points at a non-signing family (e.g. `"RSA-OAEP"`) is
-* rejected at the type level.
-*/
-type JWSSignJWK = JWK_oct<JWK_HMAC> | JWSAsymmetricPrivateJWK;
-/**
-* JWKs admissible as a `key` for {@link verify}. HMAC oct keys carry a
-* {@link JWK_HMAC} alg; asymmetric public keys carry their family's signing alg.
-* A JWK whose `alg` points at a non-signing family (e.g. `"RSA-OAEP"`) is
-* rejected at the type level.
-*/
-type JWSVerifyJWK = JWK_oct<JWK_HMAC> | JWSAsymmetricPublicJWK;
-/** Recognized JWS Header Parameters, any other Header Members may also be present. */
-interface JWSHeaderParameters extends JoseHeaderParameters {
+export type JWSAlgorithm = JWK_HMAC | JWK_RSA_SIGN | JWK_RSA_PSS | JWK_ECDSA | JWK_OKP_SIGN;
+/** Asymmetric private JWKs admissible as a signing key. */
+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. */
+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. */
+export type JWSSignJWK = JWK_oct<JWK_HMAC> | JWSAsymmetricPrivateJWK;
+/** JWKs admissible as a `verify` key; a non-signing `alg` is a type error. */
+export type JWSVerifyJWK = JWK_oct<JWK_HMAC> | JWSAsymmetricPublicJWK;
+/** Recognized JWS Header Parameters; other members may be present. */
+export interface JWSHeaderParameters extends JoseHeaderParameters {
   /** JWS "alg" (Algorithm) Header Parameter */
   alg?: JWSAlgorithm;
-  /**
-  * This JWS Extension Header Parameter modifies the JWS Payload representation and the JWS Signing
-  * Input computation as per {@link https://www.rfc-editor.org/rfc/rfc7797 RFC7797}.
-  * If `false`, the payload is used directly without Base64URL encoding.
-  * Defaults to `true`.
-  */
+  /** `false` signs the payload unencoded (RFC 7797). @default true */
   b64?: boolean;
 }
 /** JWS Protected Header */
-interface JWSProtectedHeader extends JWSHeaderParameters {
+export interface JWSProtectedHeader extends JWSHeaderParameters {
   alg: JWSAlgorithm;
 }
-/**
-* JWS (JSON Web Signature) options for signing
-*/
-interface JWSSignOptions {
-  /** The JWS Algorithm to use. Must be provided. */
+/** Options for `sign`. */
+export interface JWSSignOptions extends JWTTimeClaimOptions {
+  /** JWS algorithm; inferred from the key when omitted. */
   alg?: JWSAlgorithm;
-  /**
-  * Additional protected header parameters. `alg` is always derived from the top-level `alg`
-  * option (or inferred from the key) and cannot be overridden. `typ` defaults to `"JWT"`
-  * when the payload is a JSON object.
-  */
+  /** Extra protected header parameters; `alg` cannot be set, `typ` defaults to `"JWT"` for an object payload. */
   protectedHeader?: StrictOmit<JWSHeaderParameters, "alg"> & {
     alg?: never;
   };
-  /** Date to use when comparing NumericDate claims, defaults to `new Date()`. */
-  currentDate?: Date;
-  /**
-  * Duration until the JWS should expire, relative to `currentDate` (or `new Date()`).
-  * Skipped when the payload already carries an `exp` claim.
-  *
-  * Mutually exclusive with {@link expiresAt}.
-  */
-  expiresIn?: ExpiresIn;
-  /**
-  * Absolute moment at which the JWS should expire (sets the `exp` claim directly).
-  * Skipped when the payload already carries an `exp` claim.
-  *
-  * Mutually exclusive with {@link expiresIn}.
-  */
-  expiresAt?: Date;
-  /**
-  * Duration from `iat` before which the JWS must not be accepted.
-  * `0` is allowed and sets `nbf = iat` (explicit temporal floor at sign time).
-  * Skipped when the payload already carries an `nbf` claim.
-  *
-  * Mutually exclusive with {@link notBeforeAt}.
-  */
-  notBeforeIn?: ExpiresIn;
-  /**
-  * Absolute moment before which the JWS must not be accepted (sets the `nbf`
-  * claim directly per RFC 7519 §4.1.5). Skipped when the payload already
-  * carries an `nbf` claim.
-  *
-  * Mutually exclusive with {@link notBeforeIn}.
-  */
-  notBeforeAt?: Date;
 }
-/** Result of JWS verification */
-interface JWSVerifyResult<T extends JOSEPayload = JOSEPayload> {
-  /** The decoded and verified payload. */
+/** Result of JWS verification. */
+export interface JWSVerifyResult<T extends JOSEPayload = JOSEPayload> {
   payload: T;
-  /** The JWS Protected Header. */
   protectedHeader: JWSProtectedHeader;
 }
-/** Options for JWS verification */
-interface JWSVerifyOptions extends JWTClaimValidationOptions {
-  /**
-  * List of allowed algorithms. If provided, the JWS `alg` must be in this list.
-  * When omitted, the allowlist is inferred from the key's shape — keys without
-  * usable metadata (raw `Uint8Array`/string, alg-less JWKs, lookup functions)
-  * cannot be inferred and require this option explicitly.
-  */
+/** Options for `verify`; `Mode` is the `payload` option's literal. */
+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. */
   algorithms?: JWSAlgorithm[];
-  /** If true, forces the payload to be returned as a Uint8Array, otherwise type is inferred. */
-  forceUint8Array?: boolean;
-  /**
-  * Controls JWT claim validation after a successful verification.
-  *
-  * - `true` — always validate claims regardless of the `typ` header
-  * - `false` — skip claim validation entirely
-  * - `undefined` (default) — validate when `typ` is `"JWT"` or contains `"jwt"`
-  */
-  validateClaims?: boolean;
+  /** Max JWK Set candidates per token; more is `ERR_JWK_KEY_NOT_FOUND`. @default { keyCandidates: 8 } */
+  limits?: Pick<JOSELimits, "keyCandidates">;
 }
-/**
-* JWS Flattened JSON Serialization, RFC 7515 §7.2.2. Accepted as input by
-* {@link verifyMulti} and normalized to {@link JWSGeneralSerialization}
-* internally. Emitted by {@link generalToFlattenedJWS} on a single-signature
-* General serialization.
-*/
-interface JWSFlattenedSerialization {
-  /** The JWS Payload. base64url-encoded when `b64 !== false`. */
+/** JWS Flattened JSON Serialization (RFC 7515 §7.2.2). */
+export interface JWSFlattenedSerialization {
+  /** The JWS Payload; base64url-encoded unless `b64: false`. */
   payload: string;
-  /** Base64URL-encoded JWS Protected Header (part of the signing input). */
+  /** Base64url-encoded JWS Protected Header. */
   protected?: string;
-  /** JWS Unprotected Header (not part of the signing input). */
+  /** JWS Unprotected Header (not signed). */
   header?: JWSHeaderParameters;
-  /** Base64URL-encoded signature bytes. */
+  /** Base64url-encoded signature. */
   signature: string;
 }
-/**
-* JWS General JSON Serialization, RFC 7515 §7.2.1. Canonical multi-signature
-* output shape of {@link signMulti}.
-*
-* `payload` is shared across all signatures and carries base64url-encoded
-* bytes by default. When the consistent `b64: false` signing mode is used
-* (RFC 7797), `payload` holds the raw UTF-8 payload string instead.
-*/
-interface JWSGeneralSerialization extends Omit<JWSFlattenedSerialization, "protected" | "header" | "signature"> {
+/** JWS General JSON Serialization (RFC 7515 §7.2.1). */
+export interface JWSGeneralSerialization extends Omit<JWSFlattenedSerialization, "protected" | "header" | "signature"> {
   /** One entry per signer. */
   signatures: JWSGeneralSignature[];
 }
-/** A single signature entry within {@link JWSGeneralSerialization.signatures}. */
-type JWSGeneralSignature = Pick<JWSFlattenedSerialization, "protected" | "header" | "signature">;
-/**
-* Input shape for a single signer passed to {@link signMulti}.
-*
-* `alg` is inferred from `key.alg`; throws `ERR_JWS_SIGNER_ALG_INFERENCE`
-* when absent. `kid` is pulled from `key.kid` when present.
-*/
-interface JWSMultiSigner {
-  /** Signing key (JWK-first; `alg` inferred from `key.alg`). */
-  key: JWSSignJWK;
-  /**
-  * Extra per-signer JWS Protected Header parameters (RFC 7515 §7.2.1).
-  * `alg` is always derived from the JWK and cannot be set here. `b64`
-  * MUST be consistent across every signer (RFC 7797 §3) — if set on one
-  * signer it must match on all.
-  */
+/** A single entry of `JWSGeneralSerialization.signatures`. */
+export type JWSGeneralSignature = Pick<JWSFlattenedSerialization, "protected" | "header" | "signature">;
+/** One signer passed to `signMulti`. */
+export interface JWSMultiSigner {
+  /** Signing key; `kid` is taken from a JWK, a `CryptoKey` must set it in `protectedHeader`. */
+  key: JWSSignJWK | CryptoKey;
+  /** JWS algorithm; inferred from the key when possible, else `ERR_JWS_SIGNER_ALG_INFERENCE`. */
+  alg?: JWSAlgorithm;
+  /** Per-signer protected header; `b64` must match across signers (RFC 7797 §3), `typ` defaults to `"JWT"`. */
   protectedHeader?: StrictOmit<JWSHeaderParameters, "alg"> & {
     alg?: never;
   };
-  /** Per-signer JWS Unprotected Header (not part of signing input). */
+  /** Per-signer JWS Unprotected Header (not signed). */
   unprotectedHeader?: JWSHeaderParameters;
 }
-/**
-* Options for {@link signMulti}. Mirrors {@link JWSSignOptions} minus the
-* per-signer fields (`alg`, `protectedHeader` — set those on each
-* {@link JWSMultiSigner} instead).
-*/
-interface JWSMultiSignOptions extends StrictOmit<JWSSignOptions, "alg" | "protectedHeader"> {}
-/** Options for {@link verifyMulti}. Extends {@link JWSVerifyOptions}. */
-interface JWSMultiVerifyOptions extends JWSVerifyOptions {
-  /**
-  * When `false` (default), verification trials signatures in order — mirrors
-  * the multi-key retry behaviour of {@link verify} against a JWK Set. When
-  * `true`, only signatures whose header unambiguously matches the provided
-  * key (by `kid`, then by `kty`/`crv`/length) are attempted, and any
-  * mismatch throws `ERR_JWS_NO_MATCHING_SIGNER` before any crypto work.
-  */
+/** 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 */
   strictSignerMatch?: boolean;
 }
-/**
-* Result of a {@link verifyMulti} operation. Extends {@link JWSVerifyResult}
-* with the per-signer header and matched signature index.
-*/
-interface JWSMultiVerifyResult<T extends JOSEPayload = JOSEPayload> extends JWSVerifyResult<T> {
-  /** Parsed per-signer unprotected header of the signature that verified. */
+/** Result of `verifyMulti`. */
+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). */
+  protectedHeader: JWSHeaderParameters;
+  /** Unprotected header of the verified signature. */
   signerHeader?: JWSHeaderParameters;
-  /** Index into `jws.signatures` of the signature that successfully verified. */
+  /** Index into `signatures` of the verified signature. */
   signerIndex: number;
 }
-/**
-* Options for {@link verifyMultiAll}. Inherits the same validation knobs as
-* {@link JWSMultiVerifyOptions} minus `strictSignerMatch` (not meaningful when
-* every signature is independently reported).
-*/
-interface JWSMultiVerifyAllOptions extends StrictOmit<JWSMultiVerifyOptions, "strictSignerMatch"> {}
-/**
-* Per-signature outcome collected by {@link verifyMultiAll}. Discriminated by
-* `verified`:
-*
-*   - `verified: true` — the signature cryptographically verified and any
-*     claim/`crit` validation the caller asked for also passed. `payload` is
-*     provided.
-*   - `verified: false` — verification could not be completed for this
-*     signature. `error` carries the {@link JWTError} reason (signature
-*     invalid, disallowed alg, `typ` mismatch, key-resolver failure, malformed
-*     protected header, expired claim, etc.). `protectedHeader` / `signerHeader`
-*     are populated when they were successfully parsed before failure.
-*
-* Callers apply their own policy over the returned array — e.g. "all must
-* verify", "quorum of N", "signed by these specific kids".
-*/
-type JWSMultiVerifyOutcome<T extends JOSEPayload = JOSEPayload> = {
+/** 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`. */
+export type JWSMultiVerifyOutcome<T extends JOSEPayload = JOSEPayload> = {
   signerIndex: number;
   verified: true;
   payload: T;
-  protectedHeader: JWSProtectedHeader;
+  protectedHeader: JWSHeaderParameters;
   signerHeader?: JWSHeaderParameters;
 } | {
   signerIndex: number;
   verified: false;
   error: JWTError;
-  protectedHeader?: JWSProtectedHeader;
+  protectedHeader?: JWSHeaderParameters;
   signerHeader?: JWSHeaderParameters;
 };
-/**
-* Algorithms admissible on an `oct` JWK used for JWE key management. Mirrors
-* the runtime aliasing table in `jweAlgsFromOctJWK` — HMAC algs intentionally
-* excluded (they don't resolve to any JWE `alg`).
-*/
+/** `oct` JWK algorithms admissible for JWE key management (HMAC excluded). */
 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 keys carry an
-* RSA-OAEP alg; EC/OKP keys carry an ECDH-ES alg.
-*/
-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 keys carry an
-* RSA-OAEP alg; EC/OKP keys carry an ECDH-ES alg.
-*/
-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` argument of {@link encrypt}. A JWK whose `alg`
-* points at a non-JWE family (e.g. `"HS256"`, `"RS256"`) is rejected at the
-* type level.
-*/
-type JWEEncryptJWK = JWK_oct<_JWEOctAlg> | JWEAsymmetricPublicJWK;
-/**
-* JWKs admissible as a `key` for {@link decrypt}. A JWK whose `alg` points at
-* a non-JWE family (e.g. `"HS256"`, `"RS256"`) is rejected at the type level.
-*/
-type JWEDecryptJWK = JWK_oct<_JWEOctAlg> | JWEAsymmetricPrivateJWK;
-/** Recognized JWE Header Parameters, any other Header Members may also be present. */
-interface JWEHeaderParameters extends JoseHeaderParameters {
-  /**
-  * `alg` (Algorithm): Header Parameter - Key Management Algorithm
-  */
+/** Asymmetric public JWKs admissible for JWE encryption (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). */
+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. */
+export type JWEEncryptJWK = JWK_oct<_JWEOctAlg> | JWEAsymmetricPublicJWK;
+/** JWKs admissible as a `key` of `decrypt`; a non-JWE `alg` is a type error. */
+export type JWEDecryptJWK = JWK_oct<_JWEOctAlg> | JWEAsymmetricPrivateJWK;
+/** Recognized JWE Header Parameters; other members may also be present. */
+export interface JWEHeaderParameters extends JoseHeaderParameters {
+  /** Key Management Algorithm. */
   alg?: KeyManagementAlgorithm | (string & {});
-  /**
-  * `enc` (Encryption Algorithm): Header Parameter - Content Encryption Algorithm
-  */
+  /** Content Encryption Algorithm. */
   enc?: ContentEncryptionAlgorithm | (string & {});
-  /**
-  * `p2c` (PBES2 Count): Header Parameter
-  */
+  /** PBES2 Count. */
   p2c?: number;
-  /**
-  * `p2s` (PBES2 Salt): Header Parameter. Base64URL encoded.
-  */
+  /** PBES2 Salt, base64url. */
   p2s?: string;
-  /**
-  * "iv" (Initialization Vector) Header Parameter for AES GCM Key Wrapping. Base64URL encoded.
-  */
+  /** AES-GCMKW Initialization Vector, base64url. */
   iv?: string;
-  /**
-  * "tag" (Authentication Tag) Header Parameter for AES GCM Key Wrapping. Base64URL encoded.
-  */
+  /** AES-GCMKW Authentication Tag, base64url. */
   tag?: string;
-  /**
-  * "epk" (Ephemeral Public Key) Header Parameter for ECDH-ES.
-  */
-  epk?: JWK_EC_Public;
-  /**
-  * "apu" (Agreement PartyUInfo) Header Parameter for ECDH-ES. Base64URL encoded.
-  */
+  /** ECDH-ES Ephemeral Public Key. */
+  epk?: JWK_EC_Public | JWK_OKP_Public;
+  /** ECDH-ES Agreement PartyUInfo, base64url. */
   apu?: string;
-  /**
-  * "apv" (Agreement PartyVInfo) Header Parameter for ECDH-ES. Base64URL encoded.
-  */
+  /** ECDH-ES Agreement PartyVInfo, base64url. */
   apv?: string;
-  /** Any other JWE Header member. */
+  /** Compression (RFC 7516 §4.1.3) is not supported: a token carrying `zip` is rejected. */
+  zip?: never;
   [propName: string]: unknown;
 }
-/** Recognized JWE Key Management-related Header Parameters. */
-interface JWEKeyManagementHeaderParameters {
+/** Recognized JWE Key Management-related Header Parameters; all but `apu`/`apv` are internal. */
+export interface JWEKeyManagementHeaderParameters {
   apu?: Uint8Array<ArrayBuffer>;
   apv?: Uint8Array<ArrayBuffer>;
-  /**
-  * For Internal use only
-  */
   p2c?: number;
-  /**
-  * For Internal use only
-  */
   p2s?: Uint8Array<ArrayBuffer>;
-  /**
-  * For Internal use only
-  */
   iv?: Uint8Array<ArrayBuffer>;
-  /**
-  * For Internal use only
-  */
-  epk?: CryptoKey | JWK_EC_Public;
-  /**
-  * For Internal use only
-  */
-  epkPrivateKey?: CryptoKey | JWK_EC_Private;
+  epk?: CryptoKey | JWK_EC_Public | JWK_OKP_Public;
+  epkPrivateKey?: CryptoKey | JWK_EC_Private | JWK_OKP_Private;
 }
-/**
-* JWE (JSON Web Encryption) encryption options
-*/
-interface JWEEncryptOptions {
-  /** JWE "alg" (Algorithm) Header Parameter. Key Management Algorithm. */
+/** Header parameters the library writes itself and no caller header may set (RFC 7516 §4.1, RFC 7518 §4.6–§4.8). */
+export type JWELibraryHeaderName = "alg" | "enc" | "iv" | "tag" | "p2s" | "p2c" | "epk" | "apu" | "apv";
+/** JWE encryption options. */
+export interface JWEEncryptOptions extends JWTTimeClaimOptions {
   alg?: KeyManagementAlgorithm;
-  /** JWE "enc" (Encryption Algorithm) Header Parameter. Content Encryption Algorithm. */
   enc?: ContentEncryptionAlgorithm;
-  /** Date to use when computing NumericDate claims, defaults to `new Date()`. */
-  currentDate?: Date;
-  /**
-  * Duration until the JWT should expire, relative to `currentDate` (or `new Date()`).
-  * Skipped when the payload already carries an `exp` claim.
-  *
-  * Mutually exclusive with {@link expiresAt}.
-  */
-  expiresIn?: ExpiresIn;
-  /**
-  * Absolute moment at which the JWT should expire (sets the `exp` claim directly).
-  * Skipped when the payload already carries an `exp` claim.
-  *
-  * Mutually exclusive with {@link expiresIn}.
-  */
-  expiresAt?: Date;
-  /**
-  * Duration from `iat` before which the JWT must not be accepted.
-  * `0` is allowed and sets `nbf = iat` (explicit temporal floor at sign time).
-  * Skipped when the payload already carries an `nbf` claim.
-  *
-  * Mutually exclusive with {@link notBeforeAt}.
-  */
-  notBeforeIn?: ExpiresIn;
-  /**
-  * Absolute moment before which the JWT must not be accepted (sets the `nbf`
-  * claim directly per RFC 7519 §4.1.5). Skipped when the payload already
-  * carries an `nbf` claim.
-  *
-  * Mutually exclusive with {@link notBeforeIn}.
-  */
-  notBeforeAt?: Date;
-  /** Additional JWE Protected Header parameters. */
-  protectedHeader?: StrictOmit<JWEHeaderParameters, "alg" | "enc" | "iv" | "tag" | "p2s" | "p2c" | "epk" | "apu" | "apv">;
-  /** Initialization Vector for AES-GCMKW key wrapping. Generated if not provided. */
+  /** 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). */
+  protectedHeader?: StrictOmit<JWEHeaderParameters, JWELibraryHeaderName>;
+  /** AES-GCMKW key-wrapping IV. Generated when omitted. */
   keyManagementIV?: Uint8Array<ArrayBuffer>;
-  /** PBES2 Salt value (p2s). Required for PBES2 algorithms. */
+  /** PBES2 Salt (p2s). Required for PBES2 algorithms. */
   p2s?: Uint8Array<ArrayBuffer>;
-  /** PBES2 Iteration count (p2c). Required for PBES2 algorithms. */
+  /** PBES2 iteration count (p2c), between `1000` and `600_000`. Default: `600_000`. */
   p2c?: number;
-  /** ECDH-ES specific options. */
   ecdh?: {
-    /**
-    * ECDH-ES Ephemeral key material. Provide a private key (CryptoKey or JWK),
-    * a CryptoKeyPair, or an object exposing both public and private parts.
-    */
-    ephemeralKey?: CryptoKey | JWK_EC_Private | CryptoKeyPair | {
-      publicKey: CryptoKey | JWK_EC_Public;
-      privateKey: CryptoKey | JWK_EC_Private;
-    }; /** ECDH-ES Agreement PartyUInfo. */
-    partyUInfo?: Uint8Array<ArrayBuffer>; /** ECDH-ES Agreement PartyVInfo. */
+    ephemeralKey?: ECDHEphemeralKeyInput;
+    partyUInfo?: Uint8Array<ArrayBuffer>;
     partyVInfo?: Uint8Array<ArrayBuffer>;
   };
-  /**
-  * Content Encryption Key (CEK) to use.
-  * If provided, it will be used directly. Otherwise, a CEK will be generated.
-  */
+  /** Content Encryption Key. Generated when omitted. */
   cek?: Uint8Array<ArrayBuffer>;
-  /**
-  * Initialization Vector for content encryption.
-  * If provided, it will be used. Otherwise, one will be generated.
-  */
+  /** Content encryption IV. Generated when omitted. */
   contentEncryptionIV?: Uint8Array<ArrayBuffer>;
 }
-/**
-* JWE (JSON Web Encryption) decryption options
-*/
-interface JWEDecryptOptions extends JWTClaimValidationOptions {
-  /**
-  * A list of allowed JWE "alg" (Algorithm) Header Parameter values for key management.
-  * When omitted, the allowlist is inferred from the key's shape — password strings
-  * and raw `Uint8Array` keys infer the PBES2 family plus `dir`; lookup functions
-  * cannot be inferred and require this option explicitly.
-  */
+/** JWE decryption options; `Mode` is the `payload` option's literal, 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. */
   algorithms?: KeyManagementAlgorithm[];
-  /** A list of allowed JWE "enc" (Encryption Algorithm) Header Parameter values for content encryption. */
+  /** 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 }`. */
+  limits?: Pick<JOSELimits, "keyCandidates" | "pbes2Iterations">;
+  /** Allowed `enc` values. */
   encryptionAlgorithms?: ContentEncryptionAlgorithm[];
-  /** Algorithm to import the unwrapped CEK as (e.g., { name: 'AES-GCM' }). Defaults based on 'enc'. */
+  /** Algorithm to import the unwrapped CEK as. Defaults based on `enc`. */
   unwrappedKeyAlgorithm?: Parameters<typeof crypto.subtle.importKey>[2];
-  /** Key usages for the unwrapped CEK. Defaults based on 'enc' (typically ['encrypt', 'decrypt']). */
+  /** Unwrapped CEK usages. Defaults based on `enc`. */
   keyUsage?: KeyUsage[];
-  /** Mark the unwrapped CEK as extractable. Defaults to true. */
+  /** Mark the unwrapped CEK extractable. Default: `true`. */
   extractable?: boolean;
-  /** If true, forces the payload to be returned as a Uint8Array, otherwise type is inferred based on JWE headers. */
-  forceUint8Array?: boolean;
-  /**
-  * Controls JWT claim validation after a successful decryption.
-  *
-  * - `true` — always validate claims regardless of the `typ` header
-  * - `false` — skip claim validation entirely
-  * - `undefined` (default) — validate when `typ` is `"JWT"` or contains `"jwt"`
-  */
-  validateClaims?: boolean;
-  /** If true, include the Content Encryption Key (CEK) and Additional Authenticated Data (AAD) in the result. */
+  /** Include the CEK and AAD in the result. */
   returnCek?: boolean;
   /** Minimum accepted PBES2 `p2c` on unwrap. Defaults to 1000 (RFC 7518 §4.8.1.2). */
   minIterations?: number;
-  /** Maximum accepted PBES2 `p2c` on unwrap. Defaults to 1_000_000 to cap PBKDF2 DoS potential. */
+  /** Maximum accepted PBES2 `p2c` on unwrap. Default: `600_000`. */
   maxIterations?: number;
 }
-/**
-* JWE Protected Header — the parsed and validated protected header returned
-* after a successful {@link decrypt} call. Both `alg` and `enc` are present
-* and strongly typed because decryption could not have succeeded without them.
-*/
-interface JWEProtectedHeader extends JWEHeaderParameters {
-  /** Key management algorithm. */
+/** Validated protected header returned by `decrypt`; `alg` and `enc` are always present. */
+export interface JWEProtectedHeader extends JWEHeaderParameters {
   alg: KeyManagementAlgorithm;
-  /** Content encryption algorithm. */
   enc: ContentEncryptionAlgorithm;
 }
-/**
-* Result of a JWE decryption operation.
-*/
-interface JWEDecryptResult<T extends JOSEPayload = JOSEPayload> {
-  /** The decrypted payload. */
+/** Result of a JWE decryption. */
+export interface JWEDecryptResult<T extends JOSEPayload = JOSEPayload> {
   payload: T;
-  /** The JWE Protected Header. */
   protectedHeader: JWEProtectedHeader;
-  /** The Content Encryption Key (CEK) used for decryption, as Uint8Array. Only present when `returnCek` is true. */
+  /** Present only when `returnCek` is true. */
   cek?: Uint8Array<ArrayBuffer>;
-  /** The Additional Authenticated Data (AAD) used, as Uint8Array. Only present when `returnCek` is true. */
+  /** Present only when `returnCek` is true. */
   aad?: Uint8Array<ArrayBuffer>;
 }
-/**
-* JWE Flattened JSON Serialization, RFC 7516 §7.2.2.
-*/
-interface JWEFlattenedSerialization {
+/** JWE Flattened JSON Serialization (RFC 7516 §7.2.2); string members are base64url. */
+export interface JWEFlattenedSerialization {
   header?: JWEHeaderParameters;
   encrypted_key?: string;
-  /** Base64URL-encoded JWE Protected Header (part of AAD). */
+  /** JWE Protected Header (part of AAD). */
   protected?: string;
-  /** Shared JWE Unprotected Header (JSON, not part of AAD). */
+  /** Shared Unprotected Header (not part of AAD). */
   unprotected?: JWEHeaderParameters;
-  /** Base64URL-encoded external Additional Authenticated Data. */
+  /** External Additional Authenticated Data. */
   aad?: string;
-  /** Base64URL-encoded IV (Initialization Vector). */
-  iv?: string;
-  /** Base64URL-encoded ciphertext. */
+  iv: string;
   ciphertext: string;
-  /** Base64URL-encoded authentication tag. */
-  tag?: string;
+  tag: string;
 }
-/**
-* JWE General JSON Serialization, RFC 7516 §7.2.1. The canonical
-* multi-recipient output shape of {@link encryptMulti}.
-*/
-interface JWEGeneralSerialization extends Omit<JWEFlattenedSerialization, "encrypted_key" | "header"> {
-  /** One entry per recipient. */
+/** JWE General JSON Serialization (RFC 7516 §7.2.1), the output of `encryptMulti`. */
+export interface JWEGeneralSerialization extends Omit<JWEFlattenedSerialization, "encrypted_key" | "header"> {
   recipients: JWEGeneralRecipient[];
 }
-/** A single recipient entry within {@link JWEGeneralSerialization.recipients}. */
-interface JWEGeneralRecipient {
-  /** Per-recipient JWE Unprotected Header (JSON, not part of AAD). */
+/** One recipient entry of a JWE General JSON Serialization. */
+export interface JWEGeneralRecipient {
+  /** Per-recipient Unprotected Header (not part of AAD). */
   header?: JWEHeaderParameters;
-  /** Base64URL-encoded encrypted CEK for this recipient. */
   encrypted_key?: string;
 }
-/**
-* Input shape for a single recipient passed to {@link encryptMulti}.
-*
-* `alg` is inferred from `key.alg` or from the JWK's kty/curve/length using
-* the same rules as {@link encrypt}. `kid` is pulled from `key.kid` when
-* present. To override either, spread or set via {@link JWEMultiRecipient.header}.
-*/
-interface JWEMultiRecipient {
-  /** Recipient key (JWK-first; `alg` inferred if absent from JWK). */
+/** One recipient of `encryptMulti`; `alg` and `kid` come from the key unless set in `header`. */
+export interface JWEMultiRecipient {
   key: JWEEncryptJWK;
-  /**
-  * Extra per-recipient JWE Unprotected Header parameters (RFC 7516 §7.2.1).
-  * Excludes fields the library writes automatically: `alg`, `enc`, `iv`,
-  * `tag`, `p2s`, `p2c`, `epk`, `apu`, `apv`.
-  *
-  * Typical use: `x5c`, `x5t`, custom routing metadata.
-  */
-  header?: StrictOmit<JWEHeaderParameters, "alg" | "enc" | "iv" | "tag" | "p2s" | "p2c" | "epk" | "apu" | "apv">;
-  /** ECDH-ES ephemeral key / party info for this recipient. */
+  /** Extra per-recipient Unprotected Header parameters (RFC 7516 §7.2.1). */
+  header?: StrictOmit<JWEHeaderParameters, JWELibraryHeaderName>;
   ecdh?: JWEEncryptOptions["ecdh"];
-  /** PBES2 salt for this recipient. Randomized (16 bytes) when omitted. */
+  /** PBES2 salt. Random 16 bytes when omitted. */
   p2s?: Uint8Array<ArrayBuffer>;
-  /** PBES2 iteration count for this recipient. Defaults to 600_000. */
+  /** PBES2 iteration count, between `1000` and `600_000`. Default: `600_000`. */
   p2c?: number;
-  /** Initialization vector for AES-GCMKW key wrapping for this recipient. */
   keyManagementIV?: Uint8Array<ArrayBuffer>;
 }
-/**
-* Options for {@link encryptMulti}. Extends {@link JWEEncryptOptions} and drops
-* the fields that are per-recipient in multi-recipient mode (`alg`, `ecdh`,
-* `p2s`, `p2c`, `keyManagementIV` — set those on each {@link JWEMultiRecipient}
-* instead).
-*/
-interface JWEMultiEncryptOptions extends StrictOmit<JWEEncryptOptions, "alg" | "ecdh" | "p2s" | "p2c" | "keyManagementIV"> {
-  /** Shared JWE Unprotected Header (surfaces as `unprotected` in the output). */
+/** Options for `encryptMulti`; per-recipient fields are set on each `JWEMultiRecipient`. */
+export interface JWEMultiEncryptOptions extends StrictOmit<JWEEncryptOptions, "alg" | "ecdh" | "p2s" | "p2c" | "keyManagementIV"> {
+  /** Shared Unprotected Header, written as `unprotected`. */
   sharedUnprotectedHeader?: Record<string, unknown>;
-  /**
-  * External Additional Authenticated Data (RFC 7516 §5.1). Encoded as
-  * base64url and written to the `aad` field; the content cipher AAD becomes
-  * `BASE64URL(protected) || '.' || BASE64URL(aad)`.
-  */
+  /** External AAD (RFC 7516 §5.1); empty means none (RFC 7516 §7.2.1); not a string or bytes is `ERR_INVALID_OPTION`. */
   aad?: Uint8Array<ArrayBuffer> | string;
 }
-/**
-* Options for {@link decryptMulti}. Extends {@link JWEDecryptOptions}.
-*/
-interface JWEMultiDecryptOptions extends JWEDecryptOptions {
-  /**
-  * When `false` (default) decryption trials recipients in order — mirrors the
-  * multi-key retry behaviour of {@link decrypt} against a JWK Set. When
-  * `true`, only recipients whose header unambiguously matches the provided
-  * key (by `kid`, then by `kty`/`crv`/length) are attempted, and any mismatch
-  * throws `ERR_JWE_NO_MATCHING_RECIPIENT` before any crypto work.
-  */
+/** Key material `decryptMulti` accepts, or a function resolving it from the recipient's header. */
+export type JWEMultiDecryptKey = CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWKLookupFunction;
+/** 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). */
   strictRecipientMatch?: boolean;
 }
-/**
-* Result of a {@link decryptMulti} operation. Extends {@link JWEDecryptResult}
-* with the per-recipient header tier surfaced on the matching recipient.
-*/
-interface JWEMultiDecryptResult<T extends JOSEPayload = JOSEPayload> extends JWEDecryptResult<T> {
-  /** Parsed shared unprotected header, when present on the serialization. */
+/** Result of `decryptMulti`, with the header tiers 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). */
+  protectedHeader: JWEHeaderParameters;
   sharedUnprotectedHeader?: JWEHeaderParameters;
-  /** Parsed per-recipient unprotected header of the recipient that decrypted. */
+  /** Unprotected header of the recipient that decrypted. */
   recipientHeader?: JWEHeaderParameters;
-  /** Index into `jwe.recipients` of the recipient that successfully decrypted. */
+  /** Index into `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}.
-*/
-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"}`;
+ * 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}.
+ */
+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}. */
-type ExpiresIn = Duration;
+export type ExpiresIn = Duration;
 /** Duration from `iat` for `nbf` — the `notBeforeIn` option on {@link sign} / {@link encrypt}. */
-type NotBeforeIn = Duration;
+export type NotBeforeIn = Duration;
 /** Duration for `maxTokenAge` validation on {@link verify} / {@link decrypt}. */
-type MaxTokenAge = Duration;
-export { CompositeKey, ContentEncryptionAlgorithm, DeriveKeyOptions, DeriveKeyReturn, Duration, ExpiresIn, GenerateJWKOptions, GenerateJWKReturn, GenerateKeyAlgorithm, GenerateKeyOptions, GenerateKeyReturn, JOSEPayload, JWEAsymmetricPrivateJWK, JWEAsymmetricPublicJWK, JWEDecryptJWK, JWEDecryptOptions, JWEDecryptResult, JWEEncryptJWK, JWEEncryptOptions, JWEFlattenedSerialization, JWEGeneralRecipient, JWEGeneralSerialization, JWEHeaderParameters, JWEKeyManagementHeaderParameters, JWEMultiDecryptOptions, JWEMultiDecryptResult, JWEMultiEncryptOptions, JWEMultiRecipient, JWEProtectedHeader, JWK, JWKAlgorithm, JWKCacheAdapter, JWKLookupFunction, JWKLookupFunctionHeader, JWKPEMAlgorithm, JWKParameters, JWKSet, JWK_AES_CBC_HMAC, JWK_AES_GCM, JWK_AES_GCM_KW, JWK_AES_KW, JWK_Asymmetric, JWK_Asymmetric_Algorithm, JWK_EC, JWK_ECDH_ES, JWK_ECDSA, JWK_EC_Private, JWK_EC_Public, JWK_HMAC, JWK_OKP, JWK_OKP_Private, JWK_OKP_Public, JWK_OKP_SIGN, JWK_PBES2, JWK_Pair, JWK_Private, JWK_Public, JWK_RSA, JWK_RSA_ENC, JWK_RSA_PSS, JWK_RSA_Private, JWK_RSA_Public, JWK_RSA_SIGN, JWK_Symmetric, JWK_Symmetric_Algorithm, JWK_oct, JWSAlgorithm, JWSAsymmetricPrivateJWK, JWSAsymmetricPublicJWK, JWSFlattenedSerialization, JWSGeneralSerialization, JWSGeneralSignature, JWSHeaderParameters, JWSMultiSignOptions, JWSMultiSigner, JWSMultiVerifyAllOptions, JWSMultiVerifyOptions, JWSMultiVerifyOutcome, JWSMultiVerifyResult, JWSProtectedHeader, JWSSignJWK, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWSVerifyResult, JWT, JWTClaimValidationOptions, JWTClaims, JWTError, JWTErrorCauseMap, JWTErrorCode, JoseHeaderParameters, KeyManagementAlgorithm, MaxTokenAge, NotBeforeIn, StrictOmit, UnwrapKeyOptions, UnwrappingKeyFor, WrapKeyOptions, WrapKeyResult, WrappingKeyFor, isJWTError };
+export type MaxTokenAge = Duration;
+export {};