unjwt 0.8.5 → 0.9.1

package/dist/_chunks/index5.d.mts

@@ -2,59 +2,96 @@ import "./error.mjs";
 import { JOSEPayload, JOSEPayloadMode, JWKSet, JWSAlgorithm, JWSFlattenedSerialization, JWSGeneralSerialization, JWSKeyLookup, JWSMultiSignOptions, JWSMultiSigner, JWSMultiVerifyAllOptions, JWSMultiVerifyOptions, JWSMultiVerifyOutcome, JWSMultiVerifyResult, JWSSignJWK, JWSSignOptions, JWSVerifyJWK, JWSVerifyOptions, JWSVerifyResult, JWTClaims, PayloadOf } from "./index.mjs";
 import "./limits.mjs";
 /**
- * Signs a payload with multiple signers as a JWS General JSON Serialization (RFC 7515 §7.2.1).
- * Each signer's `alg` is inferred from its key when omitted (`ERR_JWS_SIGNER_ALG_INFERENCE`);
- * `b64` must match across signers (RFC 7797 §3, `ERR_JWS_B64_INCONSISTENT`).
+ * Signs `payload` once per signer and returns a JWS General JSON Serialization (RFC 7515 §7.2.1).
+ * A signer without `alg` takes it from its JWK or `CryptoKey`.
+ * Signers that set `b64` must agree, and the value applies to every signer (RFC 7797 §3).
+ *
+ * @throws `ERR_JWS_INVALID` if `signers` is empty or not an array.
+ * @throws `ERR_JWS_SIGNER_ALG_INFERENCE` if a signer has no `alg` and its key does not name one.
+ * @throws `ERR_JWS_B64_INCONSISTENT` if two signers set different `b64` values.
+ * @throws `ERR_JWS_HEADER_PARAMS_NOT_DISJOINT` if a signer sets one parameter in both of its headers.
+ * @throws `ERR_JWS_ALG_NOT_ALLOWED` if an `alg` is `"none"` or not a supported signing algorithm.
+ * @throws `ERR_JWK_INVALID` if a key is a string or cannot sign with its `alg`.
+ * @throws `ERR_INVALID_OPTION` if an option is malformed, or a time option is set on a string or bytes payload.
+ * @throws `ERR_JWT_CLAIM_INVALID` if both members of a time option pair are set, or `cnf.jwk` is not a public JWK.
  */
 export declare function signMulti(payload: JOSEPayload, signers: JWSMultiSigner[], options?: JWSMultiSignOptions): Promise<JWSGeneralSerialization>;
 /**
  * Verifies a JWS General or Flattened JSON Serialization (RFC 7515 §7.2) and returns the first signature that verifies.
- * Per-signature failures are collected and the last one is thrown when none verifies.
+ * Signatures are tried in order, and a failure scoped to one signature moves on to the next.
+ * Once a signature verifies, a `crit`, payload or claim failure throws at once.
  * The payload type follows `options.payload`, as in `verify`.
+ *
+ * @throws its own error if the only signature fails, as `verify` would.
+ * @throws `ERR_JWS_SIGNATURE_INVALID` if none of several signatures verifies, with one `JWTError` per signature as `cause`, in order.
+ * @throws `ERR_JWS_NO_MATCHING_SIGNER` if `strictSignerMatch` is set and no signature fits the key.
+ * @throws `ERR_JWS_INVALID_SERIALIZATION` if the object is not a General or Flattened JWS.
+ * @throws `ERR_JWS_INVALID` if the signatures exceed `limits.signatures`, or the verified signature fails `crit` or payload decoding.
+ * @throws `ERR_JWK_KEY_NOT_FOUND` if the key trials exceed `limits.keyAttempts`.
+ * @throws `ERR_INVALID_OPTION` if an option is malformed, or a claim option is set where claims are not validated.
+ * @throws `ERR_JWT_EXPIRED` if `exp` has passed or the token is older than `maxTokenAge`.
+ * @throws `ERR_JWT_NBF` if `nbf` is in the future.
+ * @throws `ERR_JWT_CLAIM_INVALID` if a claim does not match its option or has the wrong type.
+ * @throws `ERR_JWT_CLAIM_MISSING` if a claim in `requiredClaims` or one an option checks is absent.
  */
-export declare function verifyMulti<T extends object = JWTClaims>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options?: JWSMultiVerifyOptions<"json"> & {
-  forceUint8Array?: false;
-}): Promise<JWSMultiVerifyResult<T>>;
-/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
-export declare function verifyMulti(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options: JWSMultiVerifyOptions & {
-  forceUint8Array: true;
-}): Promise<JWSMultiVerifyResult<Uint8Array<ArrayBuffer>>>;
+export declare function verifyMulti<T extends object = JWTClaims>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options?: JWSMultiVerifyOptions<"json">): Promise<JWSMultiVerifyResult<T>>;
 export declare function verifyMulti<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options?: JWSMultiVerifyOptions<Mode>): Promise<JWSMultiVerifyResult<PayloadOf<Mode>>>;
 /**
- * Verifies every signature independently and returns one outcome per signature; only
- * a malformed envelope throws (`ERR_JWS_INVALID_SERIALIZATION`). The payload type follows `options.payload`.
+ * Verifies every signature on its own and returns one outcome per signature, in signature order.
+ * A failed signature is an outcome with `verified: false` and its `error`.
+ * The payload type follows `options.payload`.
+ *
+ * @throws `ERR_JWS_INVALID_SERIALIZATION` if the object is not a General or Flattened JWS.
+ * @throws `ERR_JWS_INVALID` if the signatures exceed `limits.signatures`.
+ * @throws `ERR_JWK_KEY_NOT_FOUND` if the key trials exceed `limits.keyAttempts`.
+ * @throws `ERR_INVALID_OPTION` if an option is malformed, or a claim option is set where claims are not validated.
  *
  * @example
  * const outcomes = await verifyMultiAll(jws, (header) => jwkSet);
  * if (!outcomes.every((o) => o.verified)) throw new Error("not all signatures verified");
  */
-export declare function verifyMultiAll<T extends object = JWTClaims>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWSKeyLookup, options?: JWSMultiVerifyAllOptions<"json"> & {
-  forceUint8Array?: false;
-}): Promise<JWSMultiVerifyOutcome<T>[]>;
-/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
-export declare function verifyMultiAll(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWSKeyLookup, options: JWSMultiVerifyAllOptions & {
-  forceUint8Array: true;
-}): Promise<JWSMultiVerifyOutcome<Uint8Array<ArrayBuffer>>[]>;
+export declare function verifyMultiAll<T extends object = JWTClaims>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWSKeyLookup, options?: JWSMultiVerifyAllOptions<"json">): Promise<JWSMultiVerifyOutcome<T>[]>;
 export declare function verifyMultiAll<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jws: JWSGeneralSerialization | JWSFlattenedSerialization, keyResolver: JWSKeyLookup, options?: JWSMultiVerifyAllOptions<Mode>): Promise<JWSMultiVerifyOutcome<PayloadOf<Mode>>[]>;
-/** Converts a single-signature General JWS to Flattened form (RFC 7515 §7.2.2); otherwise `ERR_JWS_INVALID_SERIALIZATION`. */
+/**
+ * Converts a General JWS with exactly one signature to the Flattened form (RFC 7515 §7.2.2).
+ *
+ * @throws `ERR_JWS_INVALID_SERIALIZATION` if the input has no `signatures` array, or not exactly one signature.
+ */
 export declare function generalToFlattenedJWS(jws: JWSGeneralSerialization): JWSFlattenedSerialization;
 /**
- * Creates a JWS Compact Serialization; an object payload is JSON-serialized, `alg` is required unless the JWK carries one.
- * An unencoded (`b64: false`) compact payload cannot contain "." (RFC 7797 §5.2).
+ * Signs `payload` and returns a JWS Compact Serialization (RFC 7515 §7.1).
+ * An object payload is serialized as JSON and gets `typ: "JWT"` unless `protectedHeader` sets one.
+ * Pass `alg` unless the JWK names one or is an EC or Ed25519 JWK, whose curve names it (`ES256`, `ES384`, `ES512`, `EdDSA`).
+ * With `b64: false`, the payload must not contain "." (RFC 7797 §5.2).
+ *
+ * @throws `ERR_JWS_ALG_MISSING` if no `alg` is given and the key names none: a `CryptoKey`, raw bytes, or an RSA or `oct` JWK without `alg`.
+ * @throws `ERR_JWS_ALG_NOT_ALLOWED` if `alg` is `"none"` or not a supported signing algorithm.
+ * @throws `ERR_JWK_INVALID` if the key is a string or cannot sign with `alg`.
+ * @throws `ERR_INVALID_OPTION` if an option is malformed, or a time option is set on a string or bytes payload.
+ * @throws `ERR_JWT_CLAIM_INVALID` if both members of a time option pair are set, or `cnf.jwk` is not a public JWK.
+ * @throws `ERR_JWS_INVALID` if an unencoded payload contains ".".
  */
 export declare function sign(payload: JOSEPayload, key: JWSSignJWK, options?: JWSSignOptions): Promise<string>;
 export declare function sign(payload: JOSEPayload, key: CryptoKey | Uint8Array<ArrayBuffer>, options: JWSSignOptions & {
   alg: JWSAlgorithm;
 }): Promise<string>;
 /**
- * Verifies a JWS Compact Serialization against a key, JWK Set or key resolver.
+ * Verifies a JWS Compact Serialization against a key, a JWK Set or a key lookup function.
+ * The header `alg` must be in `algorithms`, else match the JWK's `alg`, else fit the key type.
+ * Pass `algorithms` for a raw-bytes key.
  * The payload type follows `options.payload`: claims `T` for `"json"` (default), `string`, or `Uint8Array`.
+ * A `"json"` payload has its claims validated unless `validateClaims: false`.
+ *
+ * @throws `ERR_JWS_INVALID` if the token is malformed, its `b64` or `typ` is wrong, or a `crit` member is not recognized.
+ * @throws `ERR_JWS_ALG_NOT_ALLOWED` if the header `alg` is unsupported or not allowed for the key.
+ * @throws `ERR_JWS_SIGNATURE_INVALID` if the signature does not verify.
+ * @throws `ERR_JWK_INVALID` if no key is given, or the key cannot verify with the header `alg`.
+ * @throws `ERR_JWK_KEY_NOT_FOUND` if the lookup returns `undefined` or throws an error that is not a `JWTError` (as `cause`), or a JWK Set has no candidate.
+ * @throws `ERR_INVALID_OPTION` if an option is malformed, or a claim option is set where claims are not validated.
+ * @throws `ERR_JWT_EXPIRED` if `exp` has passed or the token is older than `maxTokenAge`.
+ * @throws `ERR_JWT_NBF` if `nbf` is in the future.
+ * @throws `ERR_JWT_CLAIM_INVALID` if a claim does not match its option or has the wrong type.
+ * @throws `ERR_JWT_CLAIM_MISSING` if a claim in `requiredClaims` or one an option checks is absent.
  */
-export declare function verify<T extends object = JWTClaims>(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options?: JWSVerifyOptions<"json"> & {
-  forceUint8Array?: false;
-}): Promise<JWSVerifyResult<T>>;
-/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
-export declare function verify(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options: JWSVerifyOptions & {
-  forceUint8Array: true;
-}): Promise<JWSVerifyResult<Uint8Array<ArrayBuffer>>>;
+export declare function verify<T extends object = JWTClaims>(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options?: JWSVerifyOptions<"json">): Promise<JWSVerifyResult<T>>;
 export declare function verify<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jws: string, key: CryptoKey | JWKSet | JWSVerifyJWK | Uint8Array<ArrayBuffer> | JWSKeyLookup, options?: JWSVerifyOptions<Mode>): Promise<JWSVerifyResult<PayloadOf<Mode>>>;

package/dist/_chunks/index6.d.mts

@@ -1,113 +1,94 @@
 import "./libs/unsecure.mjs";
 import "./error.mjs";
 import { JWK, JWKSet, JWK_EC_Private, JWK_EC_Public, JWK_OKP_Private, JWK_OKP_Public, JWK_Private, JWK_Public, JWK_RSA_Private, JWK_RSA_Public, JWK_oct, JWSAlgorithm, KeyManagementAlgorithm } from "./index.mjs";
+import "./jwt.mjs";
 import "./digest.mjs";
-import { ComputeJwtTimeClaimsOptions as ComputeJwtTimeClaimsOptions$1, ParsePayloadOptions, applyTypDefault, assertCritShape as assertCritShape$1, computeJwtTimeClaims as computeJwtTimeClaims$1, getPlaintextBytes as getPlaintextBytes$1, parsePayloadBytes, parsePayloadSegment, validateCriticalHeadersJWE as validateCriticalHeadersJWE$1, validateCriticalHeadersJWS as validateCriticalHeadersJWS$1 } from "./jwt.mjs";
-/** Decoder output shape. `"bytes"` aliases `"uint8array"`. */
+/** The decoder output: `"string"` for UTF-8 text, `"uint8array"` or `"bytes"` for the bytes. */
 export type DecodeReturnAs = "string" | "uint8array" | "bytes";
 export interface Base64ParseOptions {
   /**
-   * Output shape: UTF-8 text, or the bytes themselves.
+   * Return the decoded bytes as UTF-8 text (`"string"`) or as a `Uint8Array`.
    * @default "string"
    */
   returnAs?: DecodeReturnAs;
 }
-/** Encode bytes, or the UTF-8 bytes of a string, as unpadded base64url (RFC 7515 §2). */
+/**
+ * Encodes bytes, or the UTF-8 bytes of a string, as unpadded base64url (RFC 7515 §2).
+ * @throws {UnsecureError} `INVALID_TYPE` if `data` is neither a string nor a `Uint8Array`.
+ */
 export declare function base64UrlStringify(data: string | Uint8Array): string;
-/** Encode bytes, or the UTF-8 bytes of a string, as padded standard base64 (RFC 4648 §4). */
+/**
+ * Encodes bytes, or the UTF-8 bytes of a string, as padded standard base64 (RFC 4648 §4).
+ * @throws {UnsecureError} `INVALID_TYPE` if `data` is neither a string nor a `Uint8Array`.
+ */
 export declare function base64Stringify(data: string | Uint8Array): string;
 /**
- * Decode unpadded base64url (RFC 7515 §2). Strict: only the canonical encoding of a byte string
- * is accepted, so `=`, whitespace, characters outside the URL-safe alphabet and set bits past
- * the final byte are rejected; a `string` result must be valid UTF-8.
+ * Decodes unpadded base64url (RFC 7515 §2). Only the canonical encoding of a byte string passes.
+ * `=`, whitespace, characters outside the URL-safe alphabet and set bits past the final byte fail.
+ * A `string` result must be valid UTF-8.
  *
- * @throws {UnsecureError} `MALFORMED` for text that is not such an encoding; `INVALID_TYPE` for input that is not a string
+ * @throws {UnsecureError} `MALFORMED` if `text` is not such an encoding.
+ * @throws {UnsecureError} `INVALID_TYPE` if `text` is not a string.
  */
 export declare function base64UrlParse<T extends DecodeReturnAs>(text: string, options: Base64ParseOptions & {
   returnAs: T;
 }): T extends "string" ? string : Uint8Array<ArrayBuffer>;
 export declare function base64UrlParse(text: string, options?: Base64ParseOptions): string;
 /**
- * Decode padded standard base64 (RFC 4648 §4). Strict: the canonical encoding with its `=` run
- * present, no whitespace, no set bits past the final byte; a `string` result must be valid UTF-8.
+ * Decodes padded standard base64 (RFC 4648 §4). Only the canonical encoding passes.
+ * The `=` padding must be present. Whitespace and set bits past the final byte fail.
+ * A `string` result must be valid UTF-8.
  *
- * @throws {UnsecureError} `MALFORMED` for text that is not such an encoding; `INVALID_TYPE` for input that is not a string
+ * @throws {UnsecureError} `MALFORMED` if `text` is not such an encoding.
+ * @throws {UnsecureError} `INVALID_TYPE` if `text` is not a string.
  */
 export declare function base64Parse<T extends DecodeReturnAs>(text: string, options: Base64ParseOptions & {
   returnAs: T;
 }): T extends "string" ? string : Uint8Array<ArrayBuffer>;
 export declare function base64Parse(text: string, options?: Base64ParseOptions): string;
-/** @deprecated Renamed to {@link Base64ParseOptions}; removed in v0.9.0. */
-export type DecodeOptions = Base64ParseOptions;
-/** @deprecated Renamed to {@link base64UrlStringify} in v0.8.0; removed in v0.9.0. */
-export declare const base64UrlEncode: typeof base64UrlStringify;
-/** @deprecated Renamed to {@link base64UrlParse} in v0.8.0; removed in v0.9.0. */
-export declare const base64UrlDecode: typeof base64UrlParse;
-/** @deprecated Renamed to {@link base64Stringify} in v0.8.0; removed in v0.9.0. */
-export declare const base64Encode: typeof base64Stringify;
-/** @deprecated Renamed to {@link base64Parse} in v0.8.0; removed in v0.9.0. */
-export declare const base64Decode: typeof base64Parse;
-/** Concatenate multiple `Uint8Array`s into a single contiguous buffer. */
+/** Returns one `Uint8Array` with the bytes of `arrays` in order. */
 export declare function concatUint8Arrays(...arrays: Readonly<Uint8Array<ArrayBuffer>[]>): Uint8Array<ArrayBuffer>;
-/** Wrap a value in an array; returns the array unchanged if already an array. */
+/** Returns `item` when it is an array, else `[item]`. */
 export declare function maybeArray<T>(item: T | T[]): T[];
 /** Whether `key` is a JWK whose `kty` this library models (`oct`, `RSA`, `EC`, `OKP`). */
 export declare function isJWK(key: unknown): key is JWK;
-/** Whether `key` is an object with a `keys` array. */
+/** Whether `key` is an object with a `keys` array. The entries are not checked. */
 export declare function isJWKSet(key: unknown): key is JWKSet;
-/** Asserts that `key` is a `CryptoKey`; throws `ERR_JWK_INVALID` otherwise. */
+/**
+ * Asserts that `key` is a `CryptoKey`.
+ * @throws `ERR_JWK_INVALID` if it is not.
+ */
 export declare function assertCryptoKey(key: unknown): asserts key is CryptoKey;
-/** Whether `key` is a `CryptoKey`, checked via `Symbol.toStringTag` to work across realms. */
+/** Whether `key` is a `CryptoKey`. A key from another realm matches too. */
 export declare function isCryptoKey(key: unknown): key is CryptoKey;
-/** Whether `key` is a `CryptoKeyPair` of two CryptoKeys. */
+/** Whether `key` has a `CryptoKey` in both `publicKey` and `privateKey`. */
 export declare const isCryptoKeyPair: (key: unknown) => key is CryptoKeyPair;
-/** Whether the JWK is symmetric (`oct`); its `k` is always secret. */
+/** Whether the JWK is symmetric: `kty` is `oct` and `k` is a string. Its `k` is secret. */
 export declare function isSymmetricJWK<T extends JWK>(key: T): key is Extract<T, JWK_oct>;
 export declare function isSymmetricJWK(key: unknown): key is JWK_oct;
-/** Whether the JWK is asymmetric (RSA, EC, OKP). */
+/** Whether the JWK is asymmetric: `kty` is `RSA`, `EC` or `OKP`. */
 export declare function isAsymmetricJWK<T extends JWK>(key: T): key is Exclude<T, JWK_oct>;
 export declare function isAsymmetricJWK(key: unknown): key is Exclude<JWK, JWK_oct>;
 /**
- * Whether the JWK holds asymmetric private material (`d`). It is `false` for `oct` keys,
- * so `!isPrivateJWK(key)` is not a "safe to publish" check; use `isPublicJWK`.
+ * Whether the JWK is an asymmetric private key: it has a string `d`.
+ * It is `false` for `oct` keys, so `!isPrivateJWK(key)` does not mean safe to publish.
+ * Use `isPublicJWK` for that check.
  */
 export declare function isPrivateJWK<T extends JWK>(key: T): key is Extract<T, JWK_EC_Private | JWK_OKP_Private | JWK_RSA_Private>;
 export declare function isPrivateJWK(key: unknown): key is JWK_Private;
-/** Whether the JWK is an asymmetric public key without `d`: the "safe to publish" check. */
+/**
+ * Whether the JWK is an asymmetric public key: no `d`, no `k`, and its public members present.
+ * Use it to check that a JWK is safe to publish.
+ */
 export declare function isPublicJWK<T extends JWK>(key: T): key is Exclude<Extract<T, JWK_EC_Public | JWK_OKP_Public | JWK_RSA_Public>, JWK_Private>;
 export declare function isPublicJWK(key: unknown): key is JWK_Public;
-/** How a JWK Set's entries are read during algorithm inference. */
-export interface InferAlgorithmsOptions {
-  /** Admit `oct` entries of a JWK Set. Defaults to `false`. */
-  allowSymmetric?: boolean;
-}
 /**
- * Infer the JWS algorithms a key unambiguously supports, or `undefined` when it cannot
- * (raw bytes, ambiguous JWK, lookup function) and `options.algorithms` must be passed.
+ * Returns the JWS algorithms `key` unambiguously supports: a pair's public key's, a JWK Set's union.
+ * Raw bytes, a string, a lookup function or an ambiguous JWK yield `undefined`: pass `algorithms`.
  */
-export declare function inferJWSAllowedAlgorithms(key: unknown, options?: InferAlgorithmsOptions): JWSAlgorithm[] | undefined;
+export declare function inferJWSAllowedAlgorithms(key: unknown): JWSAlgorithm[] | undefined;
 /**
- * Infer the JWE key management algorithms a key unambiguously supports, or `undefined`
- * when it cannot; a password string infers the PBES2 variants, raw bytes nothing.
+ * Returns the JWE key management algorithms `key` unambiguously supports: a pair's private key's,
+ * a JWK Set's union, the PBES2 three for a password. Raw bytes, a function or an ambiguous JWK yield `undefined`.
  */
-export declare function inferJWEAllowedAlgorithms(key: unknown, options?: InferAlgorithmsOptions): KeyManagementAlgorithm[] | undefined;
-/** @deprecated Use `ParsePayloadOptions` from `unjwt/internal`; removed in v0.9.0. */
-export type DecodePayloadOptions = ParsePayloadOptions;
-/** @deprecated Use `ComputeJwtTimeClaimsOptions` from `unjwt/internal`; removed in v0.9.0. */
-export type ComputeJwtTimeClaimsOptions = ComputeJwtTimeClaimsOptions$1;
-/** @deprecated Use `applyTypDefault` from `unjwt/internal`; removed in v0.9.0. */
-export declare const applyTypCtyDefaults: typeof applyTypDefault;
-/** @deprecated Use `parsePayloadBytes` from `unjwt/internal`; removed in v0.9.0. */
-export declare const decodePayloadFromBytes: typeof parsePayloadBytes;
-/** @deprecated Use `parsePayloadSegment` from `unjwt/internal`; removed in v0.9.0. */
-export declare const decodePayloadFromB64UrlSegment: typeof parsePayloadSegment;
-/** @deprecated Use `getPlaintextBytes` from `unjwt/internal`; removed in v0.9.0. */
-export declare const getPlaintextBytes: typeof getPlaintextBytes$1;
-/** @deprecated Use `computeJwtTimeClaims` from `unjwt/internal`; removed in v0.9.0. */
-export declare const computeJwtTimeClaims: typeof computeJwtTimeClaims$1;
-/** @deprecated Use `validateCriticalHeadersJWS` from `unjwt/internal`; removed in v0.9.0. */
-export declare const validateCriticalHeadersJWS: typeof validateCriticalHeadersJWS$1;
-/** @deprecated Use `validateCriticalHeadersJWE` from `unjwt/internal`; removed in v0.9.0. */
-export declare const validateCriticalHeadersJWE: typeof validateCriticalHeadersJWE$1;
-/** @deprecated Use `assertCritShape` from `unjwt/internal`; removed in v0.9.0. */
-export declare const assertCritShape: typeof assertCritShape$1;
+export declare function inferJWEAllowedAlgorithms(key: unknown): KeyManagementAlgorithm[] | undefined;

package/dist/_chunks/jwe.mjs

@@ -1,7 +1,8 @@
 import { secureRandomBytes, textEncoder } from "./libs/unsecure.mjs";
 import { JWTError } from "../error.mjs";
-import { applyTypDefault, base64UrlStringify, computeJwtTimeClaims, getPlaintextBytes, isCryptoKey, isJWK, isJWKSet, parsePayloadBytes, validateCriticalHeadersJWE } from "./jwt.mjs";
-import { DEFAULT_PBES2_ITERATIONS, asDecryptionError, asKeyLookupError, assertCompactToken, assertConsumerOptions, assertDirectKeyRole, assertEntryLimit, assertJWEEncSupported, assertJWKSetCandidates, assertOptionEntry, assertPBES2Iterations, assertPBES2Params, assertProducerConfirmation, assertProducerCrit, assertProducerKeyHeaders, assertProtectedOnlyOption, assertSerializationObject, bitLengthCEK, bitLengthIV, bitLengthTag, buildECDHAgreementParams, buildJWKSetFilter, checkAlgAllowed, checkAlgSupported, checkJWEEncSupported, checkProtectedTyp, checkSerializationEntry, copyJsonObject, decodeProtectedHeader, decodeSegment, decrypt as decrypt$1, encrypt as encrypt$1, encryptKey, generateCEK, generateIV, getJWKsFromSet, importKey, keyMatchesHeader, resolveKeyInput, resolveLimit, resolvePasswordKey, serializeProtectedHeader } from "./algorithms.mjs";
+import { base64UrlStringify, isCryptoKey, isJWK, isJWKSet } from "./jwt.mjs";
+import { applyTypDefault, computeJwtTimeClaims, getPlaintextBytes, parsePayloadBytes, validateCriticalHeadersJWE } from "./jwt2.mjs";
+import { DEFAULT_PBES2_ITERATIONS, asDecryptionError, asKeyLookupError, assertCompactToken, assertConsumerOptions, assertDirectKeyRole, assertEntryLimit, assertJWEEncSupported, assertJWKSetCandidates, assertOptionEntry, assertPBES2Iterations, assertPBES2Params, assertProducerConfirmation, assertProducerCrit, assertProducerKeyHeaders, assertProtectedOnlyOption, assertSerializationObject, bitLengthCEK, bitLengthIV, bitLengthTag, buildECDHAgreementParams, buildJWKSetFilter, checkAlgAllowed, checkAlgSupported, checkJWEEncSupported, checkProtectedTyp, checkSerializationEntry, copyJsonObject, createKeyAttemptBudget, decodeProtectedHeader, decodeSegment, decrypt as decrypt$1, encrypt as encrypt$1, encryptKey, generateCEK, generateIV, getJWKsFromSet, importKey, keyMatchesHeader, resolveKeyInput, resolveLimit, resolvePasswordKey, serializeProtectedHeader } from "./algorithms.mjs";
 import { inferJWEAllowedAlgorithms, isContentEncryptionAlgorithm, isKeyManagementAlgorithm, isPBES2Algorithm } from "./digest.mjs";
 import { resolvePayloadMode, validateClaimsIfJson } from "./payload.mjs";
 import { unwrapKey } from "./wrap.mjs";
@@ -21,9 +22,6 @@ function checkJWEAlgSupported(alg) {
 		role: "key management algorithm"
 	});
 }
-function isJWEAlgSupported(alg) {
-	return isKeyManagementAlgorithm(alg);
-}
 function assertJWEAlgSupported(alg) {
 	const error = checkJWEAlgSupported(alg);
 	if (error) throw error;
@@ -124,39 +122,45 @@ function buildKeyManagementParams(alg, source) {
 	return params;
 }
 async function unwrapAndDecrypt(alg, rawKeyMaterial, options) {
-	const { enc, encryptedKey, unwrapKeyOptions, ciphertext, iv, tag, aad, kid, allowSymmetric, keyCandidates, pbes2Budget } = options;
+	const { enc, encryptedKey, unwrapKeyOptions, ciphertext, iv, tag, aad, kid, keyCandidates, pbes2Budget, keyAttempts } = options;
 	if (isJWKSet(rawKeyMaterial)) {
 		const candidates = getJWKsFromSet(rawKeyMaterial, buildJWKSetFilter({
 			kid,
 			alg
-		}, {
-			op: "enc",
-			allowSymmetric
-		}));
+		}, { op: "enc" }));
 		assertJWKSetCandidates(candidates, {
 			limit: keyCandidates,
 			kid
 		});
 		const attempts = [];
-		for (const candidate of candidates) try {
-			if (alg === "dir") assertDirectKeyRole(candidate, enc);
-			pbes2Budget.spend(unwrapKeyOptions);
-			const unwrappingKey = await importKey(candidate, {
-				alg,
-				expect: "private"
-			});
-			const cek = await unwrapKey(encryptedKey, unwrappingKey, unwrapKeyOptions);
-			return {
-				cek,
-				plaintextBytes: await decrypt$1(enc, cek, ciphertext, iv, tag, aad)
-			};
-		} catch (err) {
-			attempts.push(asDecryptionError(err));
+		for (const candidate of candidates) {
+			try {
+				if (alg === "dir") assertDirectKeyRole(candidate, enc);
+				pbes2Budget.spend(unwrapKeyOptions);
+			} catch (err) {
+				attempts.push(asDecryptionError(err));
+				continue;
+			}
+			keyAttempts?.spend();
+			try {
+				const unwrappingKey = await importKey(candidate, {
+					alg,
+					expect: "private"
+				});
+				const cek = await unwrapKey(encryptedKey, unwrappingKey, unwrapKeyOptions);
+				return {
+					cek,
+					plaintextBytes: await decrypt$1(enc, cek, ciphertext, iv, tag, aad)
+				};
+			} catch (err) {
+				attempts.push(asDecryptionError(err));
+			}
 		}
 		throw new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED", attempts);
 	}
 	if (alg === "dir") assertDirectKeyRole(rawKeyMaterial, enc);
 	pbes2Budget.spend(unwrapKeyOptions);
+	keyAttempts?.spend();
 	try {
 		const unwrappingKey = await importKey(resolvePasswordKey(alg, rawKeyMaterial), {
 			alg,
@@ -349,6 +353,7 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 	const payloadMode = resolvePayloadMode(options);
 	const recipientLimit = resolveLimit(options.limits, "recipients");
 	const keyCandidates = resolveLimit(options.limits, "keyCandidates");
+	const keyAttempts = createKeyAttemptBudget(resolveLimit(options.limits, "keyAttempts"));
 	const pbes2Budget = createPBES2Budget(resolveLimit(options.limits, "pbes2Iterations"));
 	const general = _normalizeSerialization(jwe);
 	if (typeof general.iv !== "string" || typeof general.ciphertext !== "string" || typeof general.tag !== "string" || !Array.isArray(general.recipients) || general.recipients.length === 0) throw new JWTError("Invalid JWE JSON Serialization: missing iv/ciphertext/tag/recipients.", "ERR_JWE_INVALID_SERIALIZATION");
@@ -395,7 +400,7 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 	const segmentError = checkJWEContentSegments(enc, ivBytes, tagBytes);
 	if (segmentError) throw segmentError;
 	const contentAadBytes = textEncoder.encode(general.aad === void 0 ? protectedHeaderEncoded : `${protectedHeaderEncoded}.${general.aad}`);
-	let lastError;
+	const failures = [];
 	let cryptoAttempted = false;
 	for (let i = 0; i < general.recipients.length; i++) {
 		const shapeError = checkSerializationEntry(general.recipients[i], {
@@ -405,7 +410,7 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 			strings: ["encrypted_key"]
 		});
 		if (shapeError) {
-			lastError = shapeError;
+			failures.push(shapeError);
 			continue;
 		}
 		const wireRecipient = general.recipients[i];
@@ -415,28 +420,29 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 		});
 		const recipientError = checkJWEUnprotectedCrit(recipientHeader) ?? checkJWEZip(recipientHeader);
 		if (recipientError) {
-			lastError = recipientError;
+			failures.push(recipientError);
 			continue;
 		}
 		try {
 			_assertDisjointHeaders(protectedHeader, sharedUnprotected, recipientHeader);
 		} catch (err) {
-			lastError = asDecryptionError(err);
+			failures.push(asDecryptionError(err));
 			continue;
 		}
 		const effective = _mergeHeaders(protectedHeader, sharedUnprotected, recipientHeader);
 		const alg = effective.alg;
 		if (!alg) {
-			lastError = new JWTError(`Recipient[${i}] has no "alg" in the effective header.`, "ERR_JWE_INVALID");
+			failures.push(new JWTError(`Recipient[${i}] has no "alg" in the effective header.`, "ERR_JWE_INVALID"));
 			continue;
 		}
-		if (!isJWEAlgSupported(alg)) {
-			lastError = checkJWEAlgSupported(alg);
+		const supportError = checkJWEAlgSupported(alg);
+		if (supportError) {
+			failures.push(supportError);
 			continue;
 		}
 		const directKeyError = checkJWEDirectEncryptedKey(alg, wireRecipient.encrypted_key);
 		if (directKeyError) {
-			lastError = directKeyError;
+			failures.push(directKeyError);
 			continue;
 		}
 		let rawKeyMaterial;
@@ -447,22 +453,21 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 				what: `recipient[${i}]`
 			});
 		} catch (err) {
-			lastError = asKeyLookupError(err, `recipient[${i}]`);
+			failures.push(asKeyLookupError(err, `recipient[${i}]`));
 			continue;
 		}
 		const algError = checkAlgAllowed(alg, rawKeyMaterial, {
 			ctx: JWE_ALG_CTX,
-			algorithms: options.algorithms,
-			allowSymmetric: options.allowSymmetricJWKSet
+			algorithms: options.algorithms
 		});
 		if (algError) {
-			lastError = algError;
+			failures.push(algError);
+			continue;
+		}
+		if (options.strictRecipientMatch && !keyMatchesHeader(effective, rawKeyMaterial, { ctx: JWE_ALG_CTX })) {
+			failures.push(new JWTError(`JWE recipient[${i}] does not match the key under strictRecipientMatch.`, "ERR_JWE_NO_MATCHING_RECIPIENT"));
 			continue;
 		}
-		if (options.strictRecipientMatch && !keyMatchesHeader(effective, rawKeyMaterial, {
-			ctx: JWE_ALG_CTX,
-			allowSymmetric: options.allowSymmetricJWKSet
-		})) continue;
 		let encryptedKeyBytes;
 		try {
 			encryptedKeyBytes = decodeSegment(wireRecipient.encrypted_key ?? "", {
@@ -470,7 +475,7 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 				what: "Encrypted key"
 			});
 		} catch (err) {
-			lastError = asDecryptionError(err);
+			failures.push(asDecryptionError(err));
 			continue;
 		}
 		const unwrapKeyOpts = buildUnwrapKeyOptions(effective, {
@@ -490,12 +495,13 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 				tag: tagBytes,
 				aad: contentAadBytes,
 				kid: effective.kid,
-				allowSymmetric: options.allowSymmetricJWKSet,
 				keyCandidates,
-				pbes2Budget
+				pbes2Budget,
+				keyAttempts
 			}));
 		} catch (err) {
-			lastError = asDecryptionError(err);
+			if (keyAttempts.exhausted) throw keyAttempts.exhausted;
+			failures.push(asDecryptionError(err));
 			continue;
 		}
 		const payload = decodeJWEPayload(plaintextBytes, payloadMode);
@@ -514,7 +520,8 @@ async function decryptMulti(jwe, keyOrLookup, options = {}) {
 		return result;
 	}
 	if (options.strictRecipientMatch && !cryptoAttempted) throw new JWTError("No recipient matched the provided key under strictRecipientMatch.", "ERR_JWE_NO_MATCHING_RECIPIENT");
-	throw lastError ?? new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED");
+	if (failures.length === 1) throw failures[0];
+	throw new JWTError("JWE decryption failed.", "ERR_JWE_DECRYPTION_FAILED", failures);
 }
 function generalToFlattened(jwe) {
 	assertSerializationObject(jwe, "JWE");
@@ -634,8 +641,7 @@ async function decrypt(jwe, key, options = {}) {
 	});
 	const algError = checkAlgAllowed(alg, rawKeyMaterial, {
 		ctx: JWE_ALG_CTX,
-		algorithms: options.algorithms,
-		allowSymmetric: options.allowSymmetricJWKSet
+		algorithms: options.algorithms
 	});
 	if (algError) throw algError;
 	const unwrapKeyOpts = buildUnwrapKeyOptions(protectedHeader, {
@@ -652,7 +658,6 @@ async function decrypt(jwe, key, options = {}) {
 		tag: contentAuthTagBytes,
 		aad: aadBytes,
 		kid: protectedHeader.kid,
-		allowSymmetric: options.allowSymmetricJWKSet,
 		keyCandidates: keyCandidateLimit,
 		pbes2Budget
 	});

package/dist/_chunks/jwk.mjs

@@ -289,7 +289,9 @@ async function deriveKeyFromPassword(password, options) {
 	const passwordBytes = typeof password === "string" ? textEncoder.encode(password) : password;
 	const derivedBytes = await deriveKey(saltBytes, alg, iterations, passwordBytes);
 	const wrappingAlg = innerKeyWrapAlg(alg);
-	const finalUsages = keyUsage ?? ["wrapKey", "unwrapKey"];
+	const defaultUsages = ["wrapKey", "unwrapKey"];
+	const finalUsages = keyUsage ?? defaultUsages;
+	for (const usage of finalUsages) if (!defaultUsages.includes(usage)) throw new JWTError(`keyUsage "${usage}" is not valid for an AES-KW key, use "wrapKey" or "unwrapKey".`, "ERR_INVALID_OPTION");
 	const finalExtractable = exportToJWK ? true : extractable === true;
 	const derivedKey = await crypto.subtle.importKey("raw", derivedBytes, { name: "AES-KW" }, finalExtractable, finalUsages);
 	if (exportToJWK) {
@@ -417,10 +419,14 @@ async function deriveSharedSecret(publicKey, privateKey, options) {
 	});
 	let keyLength;
 	if (requestedKeyLength !== void 0) keyLength = requestedKeyLength;
-	else if (alg === "ECDH-ES") throw new JWTError("deriveSharedSecret with enc \"ECDH-ES\" requires an explicit keyLength in options", "ERR_JWK_INVALID");
+	else if (alg === "ECDH-ES") throw new JWTError("deriveSharedSecret with enc \"ECDH-ES\" requires an explicit keyLength in options", "ERR_INVALID_OPTION");
 	else if (isECDHESAlgorithm(alg)) keyLength = aesBitsOf(innerKeyWrapAlg(alg));
 	else keyLength = bitLengthCEK(alg);
-	return deriveECDHESKey(pubCryptoKey, privCryptoKey, alg, keyLength, partyUInfo ?? /* @__PURE__ */ new Uint8Array(0), partyVInfo ?? /* @__PURE__ */ new Uint8Array(0));
+	try {
+		return await deriveECDHESKey(pubCryptoKey, privCryptoKey, alg, keyLength, partyUInfo ?? /* @__PURE__ */ new Uint8Array(0), partyVInfo ?? /* @__PURE__ */ new Uint8Array(0));
+	} catch (error_) {
+		throw new JWTError("Key agreement failed: both keys must be agreement keys on the same curve.", "ERR_JWK_INVALID", error_);
+	}
 }
 function assertDerivedKeyLength(keyLength) {
 	if (!Number.isInteger(keyLength) || keyLength <= 0 || keyLength % 8 !== 0 || keyLength > 8192) throw new JWTError(`keyLength must be a positive multiple of 8 no greater than 8192 bits, got ${keyLength}`, "ERR_INVALID_OPTION");