unjwt 0.6.0 → 0.7.0

package/dist/_chunks/index.d.mts

@@ -1,4 +1,3 @@
-//#region src/core/types/jwk.d.ts
 /**
 * The decoded JOSE protected header received by a {@link JWKLookupFunction}.
 *
@@ -81,9 +80,15 @@ interface GenerateKeyOptions {
 type GenerateKeyReturnJWK<TAlg extends GenerateKeyAlgorithm> = TAlg extends JWK_Asymmetric_Algorithm ? TAlg extends JWK_RSA_SIGN | JWK_RSA_PSS | JWK_RSA_ENC ? {
   privateKey: JWK_RSA_Private;
   publicKey: JWK_RSA_Public;
-} : TAlg extends JWK_ECDSA | JWK_ECDH_ES ? {
+} : TAlg extends JWK_ECDSA ? {
   privateKey: JWK_EC_Private;
   publicKey: JWK_EC_Public;
+} : TAlg extends JWK_ECDH_ES ? {
+  privateKey: JWK_EC_Private;
+  publicKey: JWK_EC_Public;
+} | {
+  privateKey: JWK_OKP_Private;
+  publicKey: JWK_OKP_Public;
 } : TAlg extends JWK_OKP_SIGN ? {
   privateKey: JWK_OKP_Private;
   publicKey: JWK_OKP_Public;
@@ -140,25 +145,31 @@ interface WrapKeyOptions {
     enc?: ContentEncryptionAlgorithm;
   };
 }
-/** Result of the wrapKey function. */
-interface WrapKeyResult {
-  /** The wrapped key (Ciphertext). */
-  encryptedKey: Uint8Array<ArrayBuffer>;
-  /** Initialization Vector used (only for AES-GCMKW). Base64URL encoded. */
-  iv?: string;
-  /** Authentication Tag generated (only for AES-GCMKW). Base64URL encoded. */
-  tag?: string;
-  /** PBES2 Salt value used (only for PBES2). Base64URL encoded. */
-  p2s?: string;
-  /** PBES2 Iteration count used (only for PBES2). */
-  p2c?: number;
-  /** ECDH-ES Ephemeral Public Key used (only for ECDH-ES). */
-  epk?: JWK_EC_Public;
-  /** ECDH-ES Agreement PartyUInfo used (only for ECDH-ES). Base64URL encoded. */
-  apu?: string;
-  /** ECDH-ES Agreement PartyVInfo used (only for ECDH-ES). Base64URL encoded. */
+/**
+* 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). */
+  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. */
+  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. */
   apv?: string;
-}
+} : {
+  encryptedKey: Uint8Array<ArrayBuffer>;
+};
 /** Options for the unwrapKey function. */
 interface UnwrapKeyOptions {
   /**
@@ -176,6 +187,10 @@ interface UnwrapKeyOptions {
   p2s?: Uint8Array<ArrayBuffer> | string;
   /** PBES2 Iteration count (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. */
+  maxIterations?: number;
   /** ECDH-ES Ephemeral Public Key (required for ECDH-ES). */
   epk?: JWK_EC_Public | CryptoKey;
   /** ECDH-ES Agreement PartyUInfo. Base64URL encoded or Uint8Array. */
@@ -345,8 +360,6 @@ type JWK_Symmetric_Algorithm = JWK_HMAC | JWK_AES_KW | JWK_AES_GCM | JWK_AES_GCM
 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;
-//#endregion
-//#region src/core/types/jwt.d.ts
 /** Header Parameters common to JWE and JWS */
 interface JoseHeaderParameters {
   /** "kid" (Key ID) Header Parameter */
@@ -412,7 +425,11 @@ interface JWTClaimValidationOptions {
   subject?: string;
   /** Maximum token age, from the JWT "iat" (Issued At) Claim value. Implies presence requirement. */
   maxTokenAge?: MaxTokenAge;
-  /** Clock skew tolerance (in seconds) for validating time-based claims (nbf/exp/iat). */
+  /**
+  * 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. */
   typ?: string;
@@ -428,8 +445,71 @@ interface JWTClaimValidationOptions {
   */
   recognizedHeaders?: string[];
 }
-//#endregion
-//#region src/core/types/jws.d.ts
+/**
+* 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;
+  };
+}
+/**
+* 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);
+}
+/**
+* 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] };
 /** JWS Signing Algorithm Identifier. */
 type JWSAlgorithm = JWK_HMAC | JWK_RSA_SIGN | JWK_RSA_PSS | JWK_ECDSA | JWK_OKP_SIGN;
 /** Recognized JWS Header Parameters, any other Header Members may also be present. */
@@ -455,16 +535,45 @@ interface JWSSignOptions {
   /** The JWS Algorithm to use. Must be provided. */
   alg?: JWSAlgorithm;
   /**
-  * Additional protected header parameters. `alg` is automatically included.
-  * `typ` defaults to "JWT" if not provided and payload is an object.
+  * 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.
   */
-  protectedHeader?: JWSHeaderParameters;
+  protectedHeader?: StrictOmit<JWSHeaderParameters, "alg"> & {
+    alg?: never;
+  };
   /** Date to use when comparing NumericDate claims, defaults to `new Date()`. */
   currentDate?: Date;
   /**
-  * Time at which the JWS should expire, if no `exp` was already provided.
+  * 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> {
@@ -488,11 +597,119 @@ interface JWSVerifyOptions extends JWTClaimValidationOptions {
   */
   validateClaims?: boolean;
 }
-//#endregion
-//#region src/core/utils/types.d.ts
-type StrictOmit<T, K extends keyof T | (string & {}) | (number & {}) | (symbol & {})> = { [P in keyof T as P extends K ? never : P]: T[P] };
-//#endregion
-//#region src/core/types/jwe.d.ts
+/**
+* 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`. */
+  payload: string;
+  /** Base64URL-encoded JWS Protected Header (part of the signing input). */
+  protected?: string;
+  /** JWS Unprotected Header (not part of the signing input). */
+  header?: JWSHeaderParameters;
+  /** Base64URL-encoded signature bytes. */
+  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"> {
+  /** 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: JWK;
+  /**
+  * 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.
+  */
+  protectedHeader?: StrictOmit<JWSHeaderParameters, "alg"> & {
+    alg?: never;
+  };
+  /** Per-signer JWS Unprotected Header (not part of signing input). */
+  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.
+  */
+  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. */
+  signerHeader?: JWSHeaderParameters;
+  /** Index into `jws.signatures` of the signature that successfully verified. */
+  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> = {
+  signerIndex: number;
+  verified: true;
+  payload: T;
+  protectedHeader: JWSProtectedHeader;
+  signerHeader?: JWSHeaderParameters;
+} | {
+  signerIndex: number;
+  verified: false;
+  error: JWTError;
+  protectedHeader?: JWSProtectedHeader;
+  signerHeader?: JWSHeaderParameters;
+};
 /** Recognized JWE Header Parameters, any other Header Members may also be present. */
 interface JWEHeaderParameters extends JoseHeaderParameters {
   /**
@@ -569,8 +786,36 @@ interface JWEEncryptOptions {
   enc?: ContentEncryptionAlgorithm;
   /** Date to use when computing NumericDate claims, defaults to `new Date()`. */
   currentDate?: Date;
-  /** Time at which the JWT should expire, if no `exp` was already provided (only when typ is "JWT" or explicitly parsing JWT). */
+  /**
+  * 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. */
@@ -629,6 +874,10 @@ interface JWEDecryptOptions extends JWTClaimValidationOptions {
   validateClaims?: boolean;
   /** If true, include the Content Encryption Key (CEK) and Additional Authenticated Data (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. */
+  maxIterations?: number;
 }
 /**
 * JWE Protected Header — the parsed and validated protected header returned
@@ -654,9 +903,120 @@ interface JWEDecryptResult<T extends JOSEPayload = JOSEPayload> {
   /** The Additional Authenticated Data (AAD) used, as Uint8Array. Only present when `returnCek` is true. */
   aad?: Uint8Array<ArrayBuffer>;
 }
-//#endregion
-//#region src/core/types/index.d.ts
-type ExpiresIn = number | `${number}` | `${number}${"s" | "second" | "seconds" | "m" | "minute" | "minutes" | "h" | "hour" | "hours" | "D" | "day" | "days" | "W" | "week" | "weeks" | "M" | "month" | "months" | "Y" | "year" | "years"}`;
-type MaxTokenAge = ExpiresIn;
-//#endregion
-export { JWK_OKP_SIGN as $, JWK as A, JWK_AES_GCM_KW as B, DeriveKeyOptions as C, GenerateKeyAlgorithm as D, GenerateJWKReturn as E, JWKPEMAlgorithm as F, JWK_ECDH_ES as G, JWK_Asymmetric as H, JWKParameters as I, JWK_EC_Public as J, JWK_ECDSA as K, JWKSet as L, JWKCacheAdapter as M, JWKLookupFunction as N, GenerateKeyOptions as O, JWKLookupFunctionHeader as P, JWK_OKP_Public as Q, JWK_AES_CBC_HMAC as R, ContentEncryptionAlgorithm as S, GenerateJWKOptions as T, JWK_Asymmetric_Algorithm as U, JWK_AES_KW as V, JWK_EC as W, JWK_OKP as X, JWK_HMAC as Y, JWK_OKP_Private as Z, JWT as _, JWEEncryptOptions as a, JWK_RSA_ENC as at, JoseHeaderParameters as b, JWEProtectedHeader as c, JWK_RSA_Public as ct, JWSHeaderParameters as d, JWK_Symmetric_Algorithm as dt, JWK_PBES2 as et, JWSProtectedHeader as f, JWK_oct as ft, JOSEPayload as g, WrapKeyResult as gt, JWSVerifyResult as h, WrapKeyOptions as ht, JWEDecryptResult as i, JWK_RSA as it, JWKAlgorithm as j, GenerateKeyReturn as k, StrictOmit as l, JWK_RSA_SIGN as lt, JWSVerifyOptions as m, UnwrapKeyOptions as mt, MaxTokenAge as n, JWK_Private as nt, JWEHeaderParameters as o, JWK_RSA_PSS as ot, JWSSignOptions as p, KeyManagementAlgorithm as pt, JWK_EC_Private as q, JWEDecryptOptions as r, JWK_Public as rt, JWEKeyManagementHeaderParameters as s, JWK_RSA_Private as st, ExpiresIn as t, JWK_Pair as tt, JWSAlgorithm as u, JWK_Symmetric as ut, JWTClaimValidationOptions as v, DeriveKeyReturn as w, CompositeKey as x, JWTClaims as y, JWK_AES_GCM as z };
+/**
+* JWE Flattened JSON Serialization, RFC 7516 §7.2.2.
+*/
+interface JWEFlattenedSerialization {
+  header?: JWEHeaderParameters;
+  encrypted_key?: string;
+  /** Base64URL-encoded JWE Protected Header (part of AAD). */
+  protected?: string;
+  /** Shared JWE Unprotected Header (JSON, not part of AAD). */
+  unprotected?: JWEHeaderParameters;
+  /** Base64URL-encoded external Additional Authenticated Data. */
+  aad?: string;
+  /** Base64URL-encoded IV (Initialization Vector). */
+  iv?: string;
+  /** Base64URL-encoded ciphertext. */
+  ciphertext: string;
+  /** Base64URL-encoded authentication tag. */
+  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. */
+  recipients: JWEGeneralRecipient[];
+}
+/** A single recipient entry within {@link JWEGeneralSerialization.recipients}. */
+interface JWEGeneralRecipient {
+  /** Per-recipient JWE Unprotected Header (JSON, 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). */
+  key: JWK;
+  /**
+  * 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. */
+  ecdh?: JWEEncryptOptions["ecdh"];
+  /** PBES2 salt for this recipient. Randomized (16 bytes) when omitted. */
+  p2s?: Uint8Array<ArrayBuffer>;
+  /** PBES2 iteration count for this recipient. Defaults to 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). */
+  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)`.
+  */
+  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.
+  */
+  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. */
+  sharedUnprotectedHeader?: JWEHeaderParameters;
+  /** Parsed per-recipient unprotected header of the recipient that decrypted. */
+  recipientHeader?: JWEHeaderParameters;
+  /** Index into `jwe.recipients` of the recipient that successfully 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"}`;
+/** Duration until `exp` — the `expiresIn` option on {@link sign} / {@link encrypt}. */
+type ExpiresIn = Duration;
+/** Duration from `iat` for `nbf` — the `notBeforeIn` option on {@link sign} / {@link encrypt}. */
+type NotBeforeIn = Duration;
+/** Duration for `maxTokenAge` validation on {@link verify} / {@link decrypt}. */
+type MaxTokenAge = Duration;
+export { JWKAlgorithm as $, JWSSignOptions as A, JWK_RSA_Public as At, JWTClaimValidationOptions as B, JWSMultiSignOptions as C, JWK_Pair as Ct, JWSMultiVerifyOutcome as D, JWK_RSA_ENC as Dt, JWSMultiVerifyOptions as E, JWK_RSA as Et, JWTErrorCauseMap as F, KeyManagementAlgorithm as Ft, DeriveKeyOptions as G, JoseHeaderParameters as H, JWTErrorCode as I, UnwrapKeyOptions as It, GenerateJWKReturn as J, DeriveKeyReturn as K, isJWTError as L, WrapKeyOptions as Lt, JWSVerifyResult as M, JWK_Symmetric as Mt, StrictOmit as N, JWK_Symmetric_Algorithm as Nt, JWSMultiVerifyResult as O, JWK_RSA_PSS as Ot, JWTError as P, JWK_oct as Pt, JWK as Q, JOSEPayload as R, WrapKeyResult as Rt, JWSHeaderParameters as S, JWK_PBES2 as St, JWSMultiVerifyAllOptions as T, JWK_Public as Tt, CompositeKey as U, JWTClaims as V, ContentEncryptionAlgorithm as W, GenerateKeyOptions as X, GenerateKeyAlgorithm as Y, GenerateKeyReturn as Z, JWEProtectedHeader as _, JWK_HMAC as _t, JWEDecryptOptions as a, JWKSet as at, JWSGeneralSerialization as b, JWK_OKP_Public as bt, JWEFlattenedSerialization as c, JWK_AES_GCM_KW as ct, JWEHeaderParameters as d, JWK_Asymmetric_Algorithm as dt, JWKCacheAdapter as et, JWEKeyManagementHeaderParameters as f, JWK_EC as ft, JWEMultiRecipient as g, JWK_EC_Public as gt, JWEMultiEncryptOptions as h, JWK_EC_Private as ht, NotBeforeIn as i, JWKParameters as it, JWSVerifyOptions as j, JWK_RSA_SIGN as jt, JWSProtectedHeader as k, JWK_RSA_Private as kt, JWEGeneralRecipient as l, JWK_AES_KW as lt, JWEMultiDecryptResult as m, JWK_ECDSA as mt, ExpiresIn as n, JWKLookupFunctionHeader as nt, JWEDecryptResult as o, JWK_AES_CBC_HMAC as ot, JWEMultiDecryptOptions as p, JWK_ECDH_ES as pt, GenerateJWKOptions as q, MaxTokenAge as r, JWKPEMAlgorithm as rt, JWEEncryptOptions as s, JWK_AES_GCM as st, Duration as t, JWKLookupFunction as tt, JWEGeneralSerialization as u, JWK_Asymmetric as ut, JWSAlgorithm as v, JWK_OKP as vt, JWSMultiSigner as w, JWK_Private as wt, JWSGeneralSignature as x, JWK_OKP_SIGN as xt, JWSFlattenedSerialization as y, JWK_OKP_Private as yt, JWT as z };

package/dist/_chunks/jwe.d.mts

@@ -0,0 +1,82 @@
+import { Ft as KeyManagementAlgorithm, Mt as JWK_Symmetric, Q as JWK, R as JOSEPayload, W as ContentEncryptionAlgorithm, a as JWEDecryptOptions, at as JWKSet, c as JWEFlattenedSerialization, g as JWEMultiRecipient, h as JWEMultiEncryptOptions, m as JWEMultiDecryptResult, o as JWEDecryptResult, p as JWEMultiDecryptOptions, s as JWEEncryptOptions, tt as JWKLookupFunction, u as JWEGeneralSerialization, wt as JWK_Private } from "./index.mjs";
+/**
+* Encrypt a payload to multiple recipients using JWE General JSON Serialization
+* (RFC 7516 §7.2.1).
+*
+* One shared CEK encrypts the payload once; the CEK is then wrapped
+* independently per recipient using each recipient's key-management algorithm.
+* Per-recipient `alg` is read from `key.alg` and throws `ERR_JWE_RECIPIENT_ALG_INFERENCE`
+* when absent.
+*
+* Throws `ERR_JWE_ALG_FORBIDDEN_IN_MULTI` when any recipient resolves to `dir`
+* or bare `ECDH-ES` — those algorithms require exactly one recipient; use
+* {@link encrypt} instead.
+*
+* @example
+* const jwe = await encryptMulti({ sub: "u1" }, [
+*   { key: aliceRsaPublicJwk },
+*   { key: bobEcdhPublicJwk },
+* ], { enc: "A256GCM", expiresIn: "1h" });
+*/
+declare function encryptMulti(payload: JOSEPayload, recipients: JWEMultiRecipient[], options?: JWEMultiEncryptOptions): Promise<JWEGeneralSerialization>;
+/**
+* Decrypt a JWE in JSON Serialization object form (General RFC 7516 §7.2.1 or
+* Flattened §7.2.2 — both accepted).
+*
+* Matches recipients by, in order: `kid` equality, `kty`/`crv`/length
+* compatibility, then trial decryption. Set `strictRecipientMatch: true` to
+* disable the trial fallback.
+*
+* For compact (string) tokens, use {@link decrypt}.
+*/
+declare function decryptMulti<T extends JOSEPayload = JOSEPayload>(jwe: JWEGeneralSerialization | JWEFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWK_Private | JWK_Symmetric | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWEMultiDecryptOptions): Promise<JWEMultiDecryptResult<T>>;
+/**
+* Convert a {@link JWEGeneralSerialization} with exactly one recipient into
+* the {@link JWEFlattenedSerialization} form (RFC 7516 §7.2.2). Throws
+* `ERR_JWE_INVALID_SERIALIZATION` when the input has zero or multiple
+* recipients — Flattened is strictly single-recipient.
+*
+* `encryptMulti` never emits Flattened itself (stable return shape across
+* recipient counts); this is the canonical post-processing step when
+* interoperating with a strict Flattened-only consumer.
+*
+* @example
+* const general = await encryptMulti(payload, [recipient], opts);
+* const flattened = generalToFlattened(general);
+*/
+declare function generalToFlattened(jwe: JWEGeneralSerialization): JWEFlattenedSerialization;
+/**
+* Encrypts a payload to produce a JWE Compact Serialization string.
+*
+* @param payload The payload to encrypt. Can be a string, Uint8Array, or a JSON-serializable object.
+* @param key The key encryption key (KEK). Can be a CryptoKey, JWK, or for PBES2, a password string/Uint8Array.
+* @param options JWE encryption options, including `alg` (key management algorithm) and `enc` (content encryption algorithm).
+* @returns A Promise resolving to the JWE Compact Serialization string.
+*/
+declare function encrypt(payload: JOSEPayload, key: JWK | string | Uint8Array<ArrayBuffer>, options?: JWEEncryptOptions): Promise<string>;
+declare function encrypt(payload: JOSEPayload, key: CryptoKey | JWK_Symmetric | Uint8Array<ArrayBuffer>, options: JWEEncryptOptions & {
+  alg: "dir";
+  enc: ContentEncryptionAlgorithm;
+}): Promise<string>;
+declare function encrypt(payload: JOSEPayload, key: CryptoKey, options: JWEEncryptOptions & {
+  alg: KeyManagementAlgorithm;
+  enc: ContentEncryptionAlgorithm;
+}): Promise<string>;
+declare function encrypt(payload: JOSEPayload, key: CryptoKey | JWK | string | Uint8Array<ArrayBuffer>, options: JWEEncryptOptions & {
+  alg: KeyManagementAlgorithm;
+  enc: ContentEncryptionAlgorithm;
+}): Promise<string>;
+/**
+* Decrypts a JWE Compact Serialization string.
+*
+* @param jwe The JWE Compact Serialization string.
+* @param key The key decryption key (KEK) or a function to look up the key.
+* @param options JWE decryption options.
+* @returns A Promise resolving to an object containing the decrypted plaintext, protected header, CEK, and AAD.
+* @throws If JWE is invalid, decryption fails, or options are not met.
+*/
+declare function decrypt<T extends JOSEPayload>(jwe: string, key: CryptoKey | JWKSet | JWK_Private | JWK_Symmetric | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWEDecryptOptions): Promise<JWEDecryptResult<T>>;
+declare function decrypt(jwe: string, key: CryptoKey | JWKSet | JWK_Private | JWK_Symmetric | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options: JWEDecryptOptions & {
+  forceUint8Array: true;
+}): Promise<JWEDecryptResult<Uint8Array<ArrayBuffer>>>;
+export { generalToFlattened as a, encryptMulti as i, encrypt as n, decryptMulti as r, decrypt as t };