unjwt 0.7.3 → 0.8.1

package/dist/core/jwk.d.mts

@@ -1,387 +1,199 @@
-import { CompositeKey, ContentEncryptionAlgorithm, DeriveKeyOptions, DeriveKeyReturn, GenerateJWKOptions, GenerateJWKReturn, GenerateKeyAlgorithm, GenerateKeyOptions, GenerateKeyReturn, 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, JWTError, JWTErrorCauseMap, JWTErrorCode, JoseHeaderParameters, KeyManagementAlgorithm, UnwrapKeyOptions, UnwrappingKeyFor, WrapKeyOptions, WrapKeyResult, WrappingKeyFor, isJWTError } from "../_chunks/index.mjs";
-/**
-* Generates a cryptographic key for the specified JWA algorithm.
-*
-* The return type is narrowed by `alg` and `options.toJWK`. When `toJWK` is not set
-* (or is `false`):
-*
-* - **Symmetric algorithms** (`HS*`, `A*KW`, `A*GCM`, `A*GCMKW`) → `CryptoKey`. The key
-*   is imported with Web Crypto usages derived from the algorithm (e.g. `["sign", "verify"]`
-*   for HMAC, `["wrapKey", "unwrapKey"]` for AES-KW, `["encrypt", "decrypt"]` for AES-GCM).
-* - **AES-CBC + HMAC composites** (`A128CBC-HS256`, `A192CBC-HS384`, `A256CBC-HS512`) →
-*   `Uint8Array`. These keys are returned as raw bytes because the composite layout
-*   (AES key ∥ HMAC key) is not directly importable via `crypto.subtle.importKey`. They
-*   are split internally during encrypt/decrypt.
-* - **Asymmetric algorithms** (`RS*`, `PS*`, `ES*`, `RSA-OAEP*`, `Ed25519`, `EdDSA`,
-*   `ECDH-ES*`) → `CryptoKeyPair`.
-*
-* When `options.toJWK` is `true`, the same call returns a JWK / JWK pair instead, with
-* a freshly generated `kid` attached (use {@link generateJWK} to customise `kid`,
-* `use`, etc.). Composite AES-CBC+HMAC keys are serialised to a single `JWK_oct` and
-* re-split internally on use.
-*
-* PBES2 is not a key-generation algorithm — use {@link deriveKeyFromPassword} or
-* {@link deriveJWKFromPassword} instead.
-*
-* @param alg The JWA algorithm identifier (e.g. `"HS256"`, `"RS256"`, `"A128GCM"`,
-*            `"A256CBC-HS512"`). PBES2, `"dir"`, and `"none"` are not accepted.
-* @param options
-*   - `toJWK?` — when `true`, return JWK / JWK pair instead of `CryptoKey` / `CryptoKeyPair`.
-*   - `extractable?` — forwarded to `crypto.subtle.generateKey`. Defaults to `true`.
-*     Ignored when `toJWK` is set — the JWK output requires exporting the intermediate key.
-*   - `keyUsage?` — override the default usages derived from `alg`.
-*   - `modulusLength?` — RSA only; defaults to `2048`.
-*   - `publicExponent?` — RSA only; defaults to `0x010001`.
-*   - `namedCurve?` — EC and OKP only; defaults to `"P-256"` for EC and `"Ed25519"` for OKP.
-*
-* @example
-* ```ts
-* // HS256 → CryptoKey
-* const hmac = await generateKey("HS256");
-*
-* // A256CBC-HS512 → Uint8Array (composite key)
-* const cek = await generateKey("A256CBC-HS512");
-*
-* // RS256 → CryptoKeyPair
-* const rsa = await generateKey("RS256", { modulusLength: 2048 });
-*
-* // As JWK pair
-* const { privateKey, publicKey } = await generateKey("ES256", { toJWK: true });
-* ```
-*/
-declare function generateKey<TAlg extends GenerateKeyAlgorithm, TOptions extends GenerateKeyOptions>(alg: TAlg, options?: TOptions): Promise<GenerateKeyReturn<TAlg, TOptions>>;
-/**
-* Generates a ready-to-use JWK (or JWK pair) for the specified algorithm.
-*
-* Always returns JWK form with a `kid` attached — auto-generated via
-* `crypto.randomUUID()` when not supplied. For a `CryptoKey` / `CryptoKeyPair`
-* result instead, use {@link generateKey}. PBES2 is not a key-generation
-* algorithm — use {@link deriveJWKFromPassword}.
-*
-* Composite AES-CBC+HMAC keys (`A128CBC-HS256`, `A192CBC-HS384`, `A256CBC-HS512`)
-* are serialised to a single `JWK_oct` and re-split internally on use.
-*
-* @param alg The JWA algorithm identifier (e.g. `"HS256"`, `"RS256"`, `"ES256"`,
-*            `"A128GCM"`, `"A256CBC-HS512"`). PBES2, `"dir"`, and `"none"` are
-*            not accepted.
-* @param options
-*   - `keyUsage?` — override the default usages derived from `alg`.
-*   - `modulusLength?` — RSA only; defaults to `2048`.
-*   - `publicExponent?` — RSA only; defaults to `0x010001`.
-*   - `namedCurve?` — EC and OKP only; defaults to `"P-256"` for EC and `"Ed25519"` for OKP.
-*   - JWK metadata (`kid`, `use`, `x5c`, `x5t`, `x5t#S256`, `x5u`) is merged onto the
-*     result. `alg`, `kty`, `key_ops`, and `ext` are managed by the library and cannot
-*     be overridden here.
-*
-* @example
-* ```ts
-* // HS256 → JWK_oct
-* const hmac = await generateJWK("HS256");
-*
-* // RS256 → { privateKey: JWK_RSA_Private; publicKey: JWK_RSA_Public }
-* const rsa = await generateJWK("RS256", { modulusLength: 2048, kid: "rsa-1" });
-*
-* // ES256 with explicit metadata
-* const { privateKey, publicKey } = await generateJWK("ES256", { kid: "ec-1", use: "sig" });
-* ```
-*/
-declare function generateJWK<TAlg extends GenerateKeyAlgorithm>(alg: TAlg, options?: GenerateJWKOptions & Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">): Promise<GenerateJWKReturn<TAlg>>;
-/**
-* Derives a key from a password using PBKDF2 as specified by PBES2 algorithms.
-*
-* @param password The password to derive the key from (string or Uint8Array).
-* @param alg The PBES2 algorithm identifier (e.g., "PBES2-HS256+A128KW").
-* @param options Configuration options including salt and iterations.
-* @returns A Promise resolving to the derived key (CryptoKey) or its JWK_oct representation.
-*/
-declare function deriveKeyFromPassword<TAlg extends JWK_PBES2, TOptions extends DeriveKeyOptions>(password: string | Uint8Array<ArrayBuffer>, alg: TAlg, options: TOptions): Promise<DeriveKeyReturn<TOptions>>;
-/**
-* Derives a `JWK_oct` from a password using PBKDF2 as specified by PBES2
-* (RFC 7518 §4.8). The resulting JWK's `alg` is the underlying AES-KW variant
-* (`A128KW` / `A192KW` / `A256KW`), ready to use with {@link wrapKey} /
-* {@link unwrapKey}.
-*
-* For a `CryptoKey` result without JWK metadata, use {@link deriveKeyFromPassword}.
-*
-* @param password The password to derive the key from (string or `Uint8Array`).
-* @param alg The PBES2 algorithm identifier (e.g. `"PBES2-HS256+A128KW"`).
-* @param options
-*   - `salt` — PBKDF2 salt input (`p2s`). Must be at least 8 octets (RFC 7518 §4.8.1.1).
-*   - `iterations` — PBKDF2 iteration count (`p2c`). Must be a positive integer.
-*   - `keyUsage?` — defaults to `["wrapKey", "unwrapKey"]`.
-*   - JWK metadata (`kid`, `use`, `x5c`, `x5t`, `x5t#S256`, `x5u`) is merged onto the
-*     result. `alg`, `kty`, `key_ops`, and `ext` are managed by the library and cannot
-*     be overridden here.
-*/
-declare function deriveJWKFromPassword(password: string | Uint8Array<ArrayBuffer>, alg: JWK_PBES2, options: Omit<DeriveKeyOptions, "toJWK" | "extractable"> & Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">): Promise<JWK_oct>;
-/**
-* Default JWK import cache backed by a WeakMap.
-*
-* The outer WeakMap is keyed by the JWK object reference — a cache hit only
-* occurs when the exact same object variable is passed to {@link importKey}.
-* Reconstructing a structurally identical JWK (e.g. `{ ...jwk }`) will miss
-* the cache.
-*
-* The inner `Record<string, CryptoKey>` uses a plain object rather than `Map`
-* because typical entries have 1–2 algorithm strings per key. V8 applies
-* hidden-class optimisation to small plain objects, making property access
-* faster than `Map.get()` at this cardinality.
-*/
-declare class WeakMapJWKCache implements JWKCacheAdapter {
+import { UnsecureError, UnsecureErrorCode } from "../_chunks/libs/unsecure.mjs";
+import { CompositeKey, ContentEncryptionAlgorithm, DeriveKeyOptions, DeriveKeyReturn, ECDHEphemeralKeyInput, GenerateJWKOptions, GenerateJWKReturn, GenerateKeyAlgorithm, GenerateKeyOptions, GenerateKeyReturn, GeneratedJWKMap, GeneratedKeyMap, ImportedKey, ImportedKeyMap, JWK, JWKAlgorithm, JWKCacheAdapter, JWKLookupFunction, JWKLookupFunctionHeader, JWKMetadata, 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, JWTError, JWTErrorCauseMap, JWTErrorCode, KeyManagementAlgorithm, KnownJWTErrorCode, UnwrapKeyOptions, UnwrapKeyResult, UnwrappingKeyFor, WrapKeyOptions, WrapKeyResult, WrappingKeyFor, isJWTError, isUnsecureError } from "../_chunks/index.mjs";
+import { ThumbprintHash, thumbprint } from "../_chunks/index2.mjs";
+/**
+ * Generates a key for a JWA algorithm: a `CryptoKey` for symmetric algorithms, raw bytes for
+ * the `A*CBC-HS*` composites, a `CryptoKeyPair` for asymmetric ones; with `toJWK: true`, a JWK
+ * (or JWK pair) named by the `kid` option or its RFC 7638 thumbprint. PBES2, `"dir"` and `"none"` are refused.
+ *
+ * @param options
+ *   - `extractable?` — defaults to `true`; ignored when `toJWK` is set.
+ *   - `kid?` — with `toJWK`, a string set verbatim or `false` for no `kid`, either skipping the
+ *     thumbprint digest; anything else throws `ERR_INVALID_OPTION`.
+ *   - `keyUsage?` — narrows the usages derived from `alg`; leaving either half of a pair with
+ *     no usage throws `ERR_INVALID_OPTION`.
+ *   - `modulusLength?` — RSA only; defaults to `2048`.
+ *   - `publicExponent?` — RSA only; big-endian bytes, defaults to `0x010001`.
+ *   - `namedCurve?` — EC/OKP only; defaults to `"P-256"` / `"Ed25519"`. One that contradicts
+ *     the curve `ES*` or `Ed25519` names throws `ERR_INVALID_OPTION`.
+ */
+export declare function generateKey<TAlg extends GenerateKeyAlgorithm, ToJWK extends boolean = false, Kid extends string | false = string>(alg: TAlg, options?: GenerateKeyOptions<ToJWK, Kid>): Promise<GenerateKeyReturn<TAlg, GenerateKeyOptions<ToJWK, Kid>>>;
+/**
+ * Generates a JWK (or JWK pair) for a JWA algorithm, its `kid` the caller's, none with
+ * `kid: false`, or else its RFC 7638 thumbprint. PBES2, `"dir"` and `"none"` are refused.
+ *
+ * @param options
+ *   - `keyUsage?`, `modulusLength?` (default `2048`), `publicExponent?` (default `0x010001`),
+ *     `namedCurve?` (default `"P-256"` / `"Ed25519"`); a narrowing that empties a pair half or
+ *     a curve that contradicts `alg` throws `ERR_INVALID_OPTION`.
+ *   - `kid?` — a string set verbatim or `false` for no `kid`, either skipping the thumbprint
+ *     digest; anything else throws `ERR_INVALID_OPTION`.
+ *   - JWK metadata (`use`, `x5c`, `x5t`, `x5t#S256`, `x5u`) is merged onto the result;
+ *     `alg`, `kty`, `key_ops`, `ext` and key-material members are reserved (`ERR_INVALID_OPTION`).
+ */
+export declare function generateJWK<TAlg extends GenerateKeyAlgorithm, Kid extends string | false = string>(alg: TAlg, options?: GenerateJWKOptions<Kid> & Omit<JWKMetadata, "kid">): Promise<GenerateJWKReturn<TAlg, Kid>>;
+/**
+ * Derives an AES-KW key from a password with PBKDF2 per PBES2 (RFC 7518 §4.8).
+ *
+ * @param options
+ *   - `alg` — a PBES2 algorithm; any other throws `ERR_JWK_UNSUPPORTED`.
+ *   - `salt` — PBKDF2 salt (`p2s`), at least 8 octets (RFC 7518 §4.8.1.1).
+ *   - `iterations` — PBKDF2 count (`p2c`), an integer of at least 1000 (RFC 7518 §4.8.1.2);
+ *     anything else throws `ERR_INVALID_OPTION`.
+ *   - `keyUsage?` — defaults to `["wrapKey", "unwrapKey"]`.
+ *   - `extractable?` — defaults to `false`; ignored when `toJWK` is set.
+ *   - `toJWK?` — return a `JWK_oct` carrying the inner AES-KW `alg` instead of a `CryptoKey`.
+ */
+export declare function deriveKeyFromPassword<TOptions extends DeriveKeyOptions>(password: string | Uint8Array<ArrayBuffer>, options: TOptions): Promise<DeriveKeyReturn<TOptions, TOptions["alg"]>>;
+/**
+ * Derives a `JWK_oct` from a password per PBES2 (RFC 7518 §4.8); its `alg` is the inner AES-KW
+ * variant and its `kid` the caller's, none with `kid: false`, or else its RFC 7638 thumbprint.
+ *
+ * @param options
+ *   - `alg` (PBES2 only, else `ERR_JWK_UNSUPPORTED`), `salt` (at least 8 octets), `iterations`
+ *     (integer of at least 1000, else `ERR_INVALID_OPTION`), `keyUsage?` (default
+ *     `["wrapKey", "unwrapKey"]`).
+ *   - `kid?` — a string set verbatim or `false` for no `kid`, either skipping the thumbprint
+ *     digest; anything else throws `ERR_INVALID_OPTION`.
+ *   - JWK metadata (`use`, `x5c`, `x5t`, `x5t#S256`, `x5u`) is merged onto the result;
+ *     `alg`, `kty`, `key_ops`, `ext` and key-material members are reserved (`ERR_INVALID_OPTION`).
+ */
+export declare function deriveJWKFromPassword(password: string | Uint8Array<ArrayBuffer>, options: Omit<DeriveKeyOptions, "toJWK" | "extractable"> & Omit<JWKMetadata, "kid"> & {
+  kid?: string | false;
+}): Promise<JWK_oct>;
+/**
+ * Default JWK import cache, keyed by JWK object identity: a copied JWK misses it, and a JWK
+ * mutated in place keeps serving the old `CryptoKey`. Rotate by replacing the object.
+ */
+export declare class WeakMapJWKCache implements JWKCacheAdapter {
   private readonly _map;
   get(jwk: JWK, alg: string): CryptoKey | undefined;
   set(jwk: JWK, alg: string, key: CryptoKey): void;
 }
 /**
-* Replace or disable the JWK import cache used by {@link importKey}.
-*
-* Pass a custom {@link JWKCacheAdapter} to use your own cache strategy
-* (LRU, Redis-backed wrapper, test spy, etc.). Pass `false` to disable
-* caching entirely.
-*
-* @example Disable caching:
-* ```ts
-* configureJWKCache(false);
-* ```
-* @example Use a custom kid-keyed cache:
-* ```ts
-* 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),
-* });
-* ```
-*/
-declare function configureJWKCache(cache: JWKCacheAdapter | false): void;
-/**
-* Reset the JWK import cache to a fresh {@link WeakMapJWKCache}.
-* Useful in test environments to clear all cached CryptoKey references
-* between test runs without disabling the cache entirely.
-*/
-declare function clearJWKCache(): void;
-/**
-* Imports a key from various formats (CryptoKey, JWK, Uint8Array).
-*
-* - If `key` is a `CryptoKey`, it's returned directly.
-* - If `key` is a `Uint8Array`, it's returned directly.
-* - If `key` is a `JWK_oct` (symmetric key with `k`), the raw key bytes are returned as `Uint8Array`.
-* - If `key` is any other JWK type (asymmetric), an algorithm hint is required (positional or via options)
-*   and a `CryptoKey` is returned.
-*
-* ### `expect` option (asymmetric only)
-*
-* Pass `expect: "public"` or `expect: "private"` to validate the caller's intent against the key's
-* shape before the import. A private JWK passed with `expect: "public"` throws `ERR_JWK_INVALID`
-* instead of silently importing the private material. Callers who deliberately want to drop private
-* fields can do so themselves — no silent stripping.
-*
-* `expect` is a no-op for symmetric (`oct`) JWKs and for `CryptoKey` instances whose
-* `algorithm.type` is `"secret"`.
-*/
-declare function importKey(key: string): Promise<Uint8Array<ArrayBuffer>>;
-declare function importKey(key: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
-declare function importKey(key: CryptoKey): Promise<CryptoKey>;
-declare function importKey(key: JWK_oct): Promise<Uint8Array<ArrayBuffer>>;
-declare function importKey(key: JWK_oct, options: {
-  asCryptoKey: true; /** Algorithm to import the key as (e.g. `{ name: "AES-GCM", length: 256 }`). */
-  algorithm: Parameters<typeof crypto.subtle.importKey>[2]; /** Key usages for the resulting CryptoKey. */
-  usage: KeyUsage[]; /** Mark the key as extractable. Defaults to `false`. */
+ * Replaces the JWK import cache used by `importKey`, or disables it with `false`.
+ *
+ * A cache shared across JWK objects keys on the RFC 7638 thumbprint, the pair half (`d` present)
+ * and `alg`: the thumbprint covers public members only, and a `kid` may name different keys.
+ * `get` and `set` may return promises.
+ *
+ * @example
+ * ```ts
+ * const cacheKey = async (jwk: JWK, alg: string) =>
+ *   `${await thumbprint(jwk)}:${"d" in jwk ? "private" : "public"}:${alg}`;
+ * const map = new Map<string, CryptoKey>();
+ * configureJWKCache({
+ *   get: async (jwk, alg) => map.get(await cacheKey(jwk, alg)),
+ *   set: async (jwk, alg, key) => {
+ *     map.set(await cacheKey(jwk, alg), key);
+ *   },
+ * });
+ * ```
+ */
+export declare function configureJWKCache(cache: JWKCacheAdapter | false): void;
+/** Resets the JWK import cache to a fresh `WeakMapJWKCache`. */
+export declare function clearJWKCache(): void;
+/** Imports the secret of an `oct` JWK as a `CryptoKey` under `algorithm` and `usage`. */
+export declare function importKey(key: JWK_oct, options: {
+  asCryptoKey: true;
+  /** Algorithm to import the key as (e.g. `{ name: "AES-GCM", length: 256 }`). */
+  algorithm: Parameters<typeof crypto.subtle.importKey>[2];
+  usage: KeyUsage[];
+  /** Mark the key as extractable. Defaults to `false`. */
   extractable?: boolean;
 }): Promise<CryptoKey>;
-declare function importKey(key: CryptoKey | JWK | Uint8Array<ArrayBuffer> | string, options: {
-  /** Algorithm hint. Required when `key.alg` is absent on an asymmetric JWK. */alg?: string; /** Reject on shape mismatch instead of silently importing. */
-  expect?: "public" | "private";
-}): Promise<CryptoKey | Uint8Array<ArrayBuffer>>;
-declare function importKey(key: CryptoKey | JWK | Uint8Array<ArrayBuffer> | string, alg?: string): Promise<CryptoKey | Uint8Array<ArrayBuffer>>;
-/**
-* Exports a CryptoKey to a JWK (JSON Web Key) format.
-*
-* @param key The CryptoKey to export.
-* @param jwk Optional partial JWK to merge with the exported key, allowing overrides.
-* @returns A Promise resolving to the exported JWK.
-*/
-declare function exportKey<T extends JWK>(key: CryptoKey, jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">): Promise<T>;
 /**
-* Wraps a Content Encryption Key (CEK) using the specified algorithm and wrapping key.
-*
-* The return shape is narrowed by `alg` — see {@link WrapKeyResult}.
-*
-* @param alg The JWA key management algorithm (e.g., "A128KW", "RSA-OAEP", "PBES2-HS256+A128KW").
-* @param keyToWrap The key to be wrapped (CEK), typically a symmetric key as Uint8Array or CryptoKey.
-* @param wrappingKey The key used to wrap the CEK (CryptoKey, JWK, or password string/Uint8Array for PBES2).
-* @param options Additional options required by certain algorithms (e.g., p2s, p2c for PBES2).
-* @returns A Promise resolving to an alg-specific {@link WrapKeyResult}.
-*/
-declare function wrapKey<TAlg extends KeyManagementAlgorithm>(alg: TAlg, keyToWrap: CryptoKey | Uint8Array<ArrayBuffer>, wrappingKey: WrappingKeyFor<TAlg>, options?: WrapKeyOptions): Promise<WrapKeyResult<TAlg>>;
-/**
-* Unwraps a Content Encryption Key (CEK) using the specified algorithm and unwrapping key.
-*
-* @param alg The JWA key management algorithm (e.g., "A128KW", "RSA-OAEP", "PBES2-HS256+A128KW").
-* @param wrappedKey The wrapped key (ciphertext) as Uint8Array.
-* @param unwrappingKey The key used to unwrap the CEK (CryptoKey, JWK, or password string/Uint8Array for PBES2).
-* @param options Additional options required by certain algorithms (e.g., iv, tag, p2s, p2c, epk).
-* @returns A Promise resolving to the unwrapped key (CEK) as a CryptoKey or Uint8Array.
-*/
-declare function unwrapKey<TAlg extends KeyManagementAlgorithm>(alg: TAlg, wrappedKey: Uint8Array<ArrayBuffer>, unwrappingKey: UnwrappingKeyFor<TAlg>, options: UnwrapKeyOptions & {
-  format: "raw";
-}): Promise<Uint8Array<ArrayBuffer>>;
-declare function unwrapKey<TAlg extends KeyManagementAlgorithm>(alg: TAlg, wrappedKey: Uint8Array<ArrayBuffer>, unwrappingKey: UnwrappingKeyFor<TAlg>, options?: UnwrapKeyOptions & {
-  format?: "cryptokey";
-}): Promise<CryptoKey>;
-declare function unwrapKey<TAlg extends KeyManagementAlgorithm>(alg: TAlg, wrappedKey: Uint8Array<ArrayBuffer>, unwrappingKey: UnwrappingKeyFor<TAlg>, options: UnwrapKeyOptions): Promise<CryptoKey | Uint8Array<ArrayBuffer>>;
-/**
-* Imports a PEM-encoded key and returns it as a JWK.
-*
-* The PEM type is inferred from the `-----BEGIN <X>-----` label:
-* - `PRIVATE KEY` → PKCS#8 private key (RFC 5208)
-* - `PUBLIC KEY`  → SubjectPublicKeyInfo public key (RFC 5280 §4.1.2.7)
-* - `CERTIFICATE` → X.509 certificate; its SPKI is extracted into the JWK and all cert metadata
-*                   (issuer, validity, extensions) is discarded — a JWK cannot represent it
-*
-* A caller can override the inference via `options.pemType`; the underlying label assertion
-* still runs, so a mismatched override (e.g. `pemType: "pkcs8"` on a SPKI body) throws
-* `ERR_JWK_INVALID` before any crypto work.
-*
-* @param pem The PEM-encoded string.
-* @param alg The JWA algorithm identifier. Required for `crypto.subtle.importKey` to understand
-*            the key's intended algorithm and for setting the `alg` field on the resulting JWK.
-* @param options
-*   - `pemType?` — explicit PEM type; inferred from the label when omitted.
-*   - `jwkParams?` — additional JWK properties merged into the result (e.g. `kid`, `use`).
-*
-* The returned JWK always contains the key material in plain JavaScript — non-extractable
-* import is impossible for a PEM → JWK conversion (JWK export requires an extractable key).
-* To obtain a non-extractable `CryptoKey`, pass the result to
-* `importKey(jwk, { extractable: false })`.
-*     `alg`, `kty`, `key_ops`, and `ext` are reserved and cannot be overridden here.
-* @throws `JWTError("ERR_JWK_INVALID")` if the PEM type cannot be inferred (no recognised label
-*         and no `options.pemType`), or if the label does not match the requested/inferred type.
-* @throws `JWTError("ERR_JWK_UNSUPPORTED")` if `options.pemType` is a value outside the supported set.
-*
-* @example
-* ```ts
-* // Inferred — label on the PEM drives selection.
-* const jwk = await importPEM(pemString, "RS256", { jwkParams: { kid: "rsa-1" } });
-*
-* // Explicit override.
-* const jwk2 = await importPEM(pemString, "RS256", { pemType: "x509" });
-* ```
-*/
-declare function importPEM<T extends JWK>(pem: string, alg: JWKPEMAlgorithm, options?: {
-  /** PEM type. Inferred from the PEM label when omitted. */pemType?: "pkcs8" | "spki" | "x509"; /** Additional JWK properties merged into the exported key (e.g. `kid`). */
-  jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">;
-}): Promise<T>;
-/**
-* @deprecated Use {@link importPEM} instead. `pemType` has moved into the options object and
-* is now inferred from the PEM label by default.
-*/
-declare function importFromPEM<T extends JWK>(pem: string, pemType: "pkcs8" | "spki" | "x509", alg: JWKPEMAlgorithm, options?: {
-  jwkParams?: Omit<JWKParameters, "alg" | "kty" | "key_ops" | "ext">;
+ * Imports key material: a `CryptoKey` or `Uint8Array` is returned as is, an `oct` JWK as its raw
+ * bytes, an asymmetric JWK as a `CryptoKey` under its own `alg` or the hint. A string throws
+ * `ERR_JWK_INVALID`.
+ *
+ * `expect` and `extractable` apply to asymmetric keys only; `expect` rejects the other pair half
+ * with `ERR_JWK_INVALID`. A JWK's `alg` is authoritative (RFC 7517 §4.4): a different requested
+ * `alg` throws `ERR_JWK_INVALID`, except an `oct` JWK declaring a content encryption `alg` under
+ * `"dir"`.
+ */
+export declare function importKey<K extends CryptoKey | JWK | Uint8Array<ArrayBuffer>>(key: K, options?: string | {
+  /** Algorithm hint. Required when `key.alg` is absent on an asymmetric JWK. */
+  alg?: string;
+  /** Reject on shape mismatch instead of silently importing. */
+  expect?: "public" | "private";
+  /** Defaults to `false` for private, `true` for public material; JWK `ext: false` wins. */
+  extractable?: boolean;
+}): Promise<ImportedKey<K>>;
+/**
+ * Exports an extractable `CryptoKey` as a JWK, merging optional `jwkParams` metadata.
+ *
+ * The `alg` is WebCrypto's, which knows no JOSE roles: an AES-GCM key minted for `A128GCMKW`
+ * exports as `A128GCM`, so key-wrapping keys are minted with `generateJWK` instead.
+ *
+ * @throws `ERR_INVALID_OPTION` if `key` is not a `CryptoKey` or `jwkParams` sets a reserved member
+ *   (`alg`, `kty`, `key_ops`, `ext`, key material); `ERR_JWK_INVALID` for a non-extractable key.
+ */
+export declare function exportKey<T extends JWK = JWK>(key: CryptoKey, jwkParams?: JWKMetadata): Promise<T>;
+/**
+ * Wraps a CEK under a JWA key management algorithm; the result shape follows `alg`.
+ *
+ * @param wrappingKey A `CryptoKey`, a JWK, or for PBES2 a password string or bytes.
+ * @param options `alg` plus its parameters (`p2s`/`p2c` for PBES2, `ecdh` for ECDH-ES, …).
+ */
+export declare function wrapKey<TAlg extends KeyManagementAlgorithm>(keyToWrap: CryptoKey | Uint8Array<ArrayBuffer>, wrappingKey: WrappingKeyFor<TAlg>, options: WrapKeyOptions<TAlg>): Promise<WrapKeyResult<TAlg>>;
+/**
+ * Unwraps a CEK under a JWA key management algorithm.
+ *
+ * @param unwrappingKey A `CryptoKey`, a JWK, or for PBES2 a password string or bytes.
+ * @param options `alg`, `format?` (`"cryptokey"` by default, or `"raw"`), plus the algorithm's
+ *   parameters (`iv`/`tag`, `p2s`/`p2c`, `epk`, …).
+ * @throws `ERR_JWE_DECRYPTION_FAILED` for any failed unwrap, its cause undisclosed (RFC 7516
+ *   §11.5); `ERR_INVALID_OPTION` for a malformed `wrappedKey` or `options`; `ERR_JWE_INVALID` for
+ *   missing or malformed algorithm parameters.
+ */
+export declare function unwrapKey<TOptions extends UnwrapKeyOptions>(wrappedKey: Uint8Array<ArrayBuffer>, unwrappingKey: UnwrappingKeyFor<TOptions["alg"]>, options: TOptions): Promise<UnwrapKeyResult<TOptions>>;
+/**
+ * Imports a PEM key as a JWK carrying `alg`. The type follows the label — `PRIVATE KEY`
+ * (PKCS#8), `PUBLIC KEY` (SPKI), `CERTIFICATE` (X.509, only its SPKI kept) — unless
+ * `options.pemType` overrides it. The JWK holds the key material in plain JavaScript.
+ *
+ * @throws `ERR_JWK_INVALID` if the type cannot be inferred or does not match the label;
+ *   `ERR_JWK_UNSUPPORTED` for an unknown `pemType`; `ERR_INVALID_OPTION` if `jwkParams` sets
+ *   `alg`, `kty`, `key_ops`, `ext` or a key-material member.
+ */
+export declare function importPEM<T extends JWK>(pem: string, alg: JWKPEMAlgorithm, options?: {
+  /** PEM type. Inferred from the PEM label when omitted. */
+  pemType?: "pkcs8" | "spki" | "x509";
+  /** Additional JWK properties merged into the exported key (e.g. `kid`). */
+  jwkParams?: JWKMetadata;
 }): Promise<T>;
 /**
-* Exports a JWK to a PEM-encoded string.
-*
-* The PEM format is inferred from the JWK shape:
-* - JWK with `d` (private component) → PKCS#8 (`-----BEGIN PRIVATE KEY-----`)
-* - JWK without `d` → SubjectPublicKeyInfo (`-----BEGIN PUBLIC KEY-----`)
-*
-* X.509 certificate export is intentionally not supported: a certificate carries metadata
-* (subject/issuer DNs, validity window, extensions) and a CA signature that a JWK cannot provide.
-* Producing a cert is a CA operation, not a key-format conversion.
-*
-* Symmetric `oct` JWKs cannot be exported to PEM — PKCS#8/SPKI are asymmetric-key formats.
-*
-* @param jwk The JWK to export. Must not be `kty: "oct"`.
-* @param options
-*   - `pemFormat?` — force the output format. Inferred from the JWK shape when omitted.
-*   - `alg?` — algorithm hint used only when `jwk.alg` is absent (both `kty: "RSA"` / `"EC"` /
-*     `"OKP"` JWKs need an algorithm to be round-tripped through `crypto.subtle.importKey`).
-* @throws `JWTError("ERR_JWK_UNSUPPORTED")` for `oct` JWKs, or an unrecognised `pemFormat`.
-* @throws `JWTError("ERR_JWK_INVALID")` if the JWK requires an `alg` hint that was not supplied,
-*         or if `pemFormat` is forced to a value incompatible with the JWK's public/private shape.
-*
-* @example
-* ```ts
-* // Inferred — private JWKs become PKCS#8, public JWKs become SPKI.
-* const pem = await exportPEM(jwk);
-*
-* // Override (will throw if incompatible with the JWK shape).
-* const spki = await exportPEM(jwk, { pemFormat: "spki" });
-*
-* // JWK without `alg` — provide a hint.
-* const pem2 = await exportPEM(rawJwk, { alg: "RS256" });
-* ```
-*/
-declare function exportPEM(jwk: JWK, options?: {
-  /** PEM format. Inferred from the JWK shape when omitted. */pemFormat?: "pkcs8" | "spki"; /** Algorithm hint used when `jwk.alg` is absent. */
+ * Exports an asymmetric JWK as PEM: PKCS#8 when it carries `d`, SPKI otherwise.
+ *
+ * @throws `ERR_JWK_UNSUPPORTED` for `oct` JWKs or an unknown format or algorithm;
+ *   `ERR_JWK_INVALID` for a missing `alg` or a `pemFormat` that contradicts the JWK's half.
+ */
+export declare function exportPEM(jwk: JWK, options?: {
+  /** PEM format. Inferred from the JWK shape when omitted. */
+  pemFormat?: "pkcs8" | "spki";
+  /** Algorithm hint used when `jwk.alg` is absent. */
   alg?: JWKPEMAlgorithm;
 }): Promise<string>;
 /**
-* @deprecated Use {@link exportPEM} instead. `pemFormat` has moved into the options object and
-* is now inferred from the JWK shape by default. The `algForCryptoKeyImport` parameter has
-* been renamed to `options.alg`.
-*/
-declare function exportToPEM(jwk: JWK, pemFormat: "pkcs8" | "spki", algForCryptoKeyImport?: JWKPEMAlgorithm): Promise<string>;
-/**
-* Derives a shared secret using ECDH-ES key agreement (RFC 7518 §4.6).
-*
-* Performs an Elliptic Curve Diffie-Hellman Ephemeral-Static key derivation
-* followed by a Concat KDF (NIST SP 800-56A) to produce key material of the
-* requested length. The result can be used directly as a CEK (for `ECDH-ES`
-* direct key agreement) or as a KEK to wrap a separately generated CEK (for
-* `ECDH-ES+A*KW`).
-*
-* For multi-recipient JWE, call this once per recipient with their public key
-* and a fresh ephemeral private key, then wrap the shared CEK with the derived
-* material using {@link wrapKey}.
-*
-* @param publicKey The recipient's static public key (or the sender's
-*   ephemeral public key on the decryption side).
-* @param privateKey The sender's ephemeral private key (or the recipient's
-*   static private key on the decryption side).
-* @param alg The algorithm identifier used as the `AlgorithmID` in the
-*   concat KDF info structure. Pass a {@link JWK_ECDH_ES} variant
-*   (e.g. `"ECDH-ES+A128KW"`) or a {@link ContentEncryptionAlgorithm}
-*   (e.g. `"A256GCM"`) for direct key agreement.
-* @param options Optional overrides for key length and party info.
-*/
-declare function deriveSharedSecret(publicKey: CryptoKey | JWK_EC_Public, privateKey: CryptoKey | JWK_EC_Private, alg: JWK_ECDH_ES | ContentEncryptionAlgorithm, options?: {
-  /** Override the derived key length in bits. Defaults to the standard length for `alg`. */keyLength?: number; /** Agreement PartyUInfo (apu). */
-  partyUInfo?: Uint8Array<ArrayBuffer>; /** Agreement PartyVInfo (apv). */
+ * Derives ECDH-ES key material (RFC 7518 §4.6): ECDH followed by the Concat KDF.
+ *
+ * @param publicKey The recipient's static public key (the ephemeral one when decrypting).
+ * @param privateKey The ephemeral private key (the recipient's static one when decrypting).
+ */
+export declare function deriveSharedSecret(publicKey: CryptoKey | JWK_EC_Public, privateKey: CryptoKey | JWK_EC_Private, options: {
+  /** Algorithm identifier fed to the concat KDF as `AlgorithmID`. */
+  enc: JWK_ECDH_ES | ContentEncryptionAlgorithm;
+  /** Derived length in bits. Defaults to `enc`'s length; required for `"ECDH-ES"`. */
+  keyLength?: number;
+  /** Agreement PartyUInfo (apu). */
+  partyUInfo?: Uint8Array<ArrayBuffer>;
+  /** Agreement PartyVInfo (apv). */
   partyVInfo?: Uint8Array<ArrayBuffer>;
 }): Promise<Uint8Array<ArrayBuffer>>;
 /**
-* @deprecated For set queries, use {@link getJWKsFromSet} which returns all
-* matching keys as an array. This function remains available for internal
-* single-key resolution by `kid` or JOSE header (used by `verify` and `decrypt`).
-*
-* Retrieves a JWK (JSON Web Key) from a JWKSet based on a key ID (kid) or
-* properties from a JOSE Header.
-*
-* @param jwkSet The JWKSet to search within.
-* @param kidOrProtectedHeader Either a string representing the 'kid' (Key ID)
-*        or an object representing the JOSE Protected Header. If an object is
-*        provided, it must contain a 'kid' property. It can optionally contain
-*        'alg' (Algorithm) and 'kty' (Key Type) to further refine the search.
-* @returns The matching JWK from the set.
-* @throws TypeError if `jwkSet` is invalid or `kidOrProtectedHeader` is not a
-*         string or a valid header object.
-* @throws Error if no key is found matching the provided criteria, or if the
-*         header object is missing the 'kid' property.
-*/
-declare function getJWKFromSet(jwkSet: JWKSet, kidOrProtectedHeader: string | (JoseHeaderParameters & {
-  alg?: string;
-  kty?: string;
-})): JWK;
-/**
-* Returns all JWKs from a JWK Set, optionally narrowed by a predicate.
-*
-* Useful for multi-key verification retry, key rotation tooling, and
-* constructing multi-recipient JWE JSON Serialization structures.
-*
-* @param jwkSet The JWK Set to search.
-* @param filter Optional predicate `(jwk: JWK) => boolean`. Returns all keys when omitted.
-* @returns An array of matching JWKs.
-*/
-declare function getJWKsFromSet(jwkSet: JWKSet, filter?: (jwk: JWK) => boolean): JWK[];
-export { type CompositeKey, type ContentEncryptionAlgorithm, type DeriveKeyOptions, type DeriveKeyReturn, type GenerateJWKOptions, type GenerateJWKReturn, type GenerateKeyAlgorithm, type GenerateKeyOptions, type GenerateKeyReturn, type JWK, type JWKAlgorithm, type JWKCacheAdapter, type JWKLookupFunction, type JWKLookupFunctionHeader, type JWKPEMAlgorithm, type JWKParameters, type JWKSet, type JWK_AES_CBC_HMAC, type JWK_AES_GCM, type JWK_AES_GCM_KW, type JWK_AES_KW, type JWK_Asymmetric, type JWK_Asymmetric_Algorithm, type JWK_EC, type JWK_ECDH_ES, type JWK_ECDSA, type JWK_EC_Private, type JWK_EC_Public, type JWK_HMAC, type JWK_OKP, type JWK_OKP_Private, type JWK_OKP_Public, type JWK_OKP_SIGN, type JWK_PBES2, type JWK_Pair, type JWK_Private, type JWK_Public, type JWK_RSA, type JWK_RSA_ENC, type JWK_RSA_PSS, type JWK_RSA_Private, type JWK_RSA_Public, type JWK_RSA_SIGN, type JWK_Symmetric, type JWK_Symmetric_Algorithm, type JWK_oct, JWTError, type JWTErrorCauseMap, type JWTErrorCode, type KeyManagementAlgorithm, type UnwrapKeyOptions, type UnwrappingKeyFor, WeakMapJWKCache, type WrapKeyOptions, type WrapKeyResult, type WrappingKeyFor, clearJWKCache, configureJWKCache, deriveJWKFromPassword, deriveKeyFromPassword, deriveSharedSecret, exportKey, exportPEM, exportToPEM, generateJWK, generateKey, getJWKFromSet, getJWKsFromSet, importFromPEM, importKey, importPEM, isJWTError, unwrapKey, wrapKey };
+ * Returns the JWKs of a JWK Set, dropping non-JWK entries, optionally narrowed by `filter`.
+ * An invalid set throws `ERR_JWK_INVALID`.
+ */
+export declare function getJWKsFromSet(jwkSet: JWKSet, filter?: (jwk: JWK) => boolean): JWK[];
+export { type CompositeKey, type ContentEncryptionAlgorithm, type DeriveKeyOptions, type DeriveKeyReturn, type ECDHEphemeralKeyInput, type GenerateJWKOptions, type GenerateJWKReturn, type GenerateKeyAlgorithm, type GenerateKeyOptions, type GenerateKeyReturn, type GeneratedJWKMap, type GeneratedKeyMap, type ImportedKey, type ImportedKeyMap, type JWK, type JWKAlgorithm, type JWKCacheAdapter, type JWKLookupFunction, type JWKLookupFunctionHeader, type JWKMetadata, type JWKPEMAlgorithm, type JWKParameters, type JWKSet, type JWK_AES_CBC_HMAC, type JWK_AES_GCM, type JWK_AES_GCM_KW, type JWK_AES_KW, type JWK_Asymmetric, type JWK_Asymmetric_Algorithm, type JWK_EC, type JWK_ECDH_ES, type JWK_ECDSA, type JWK_EC_Private, type JWK_EC_Public, type JWK_HMAC, type JWK_OKP, type JWK_OKP_Private, type JWK_OKP_Public, type JWK_OKP_SIGN, type JWK_PBES2, type JWK_Pair, type JWK_Private, type JWK_Public, type JWK_RSA, type JWK_RSA_ENC, type JWK_RSA_PSS, type JWK_RSA_Private, type JWK_RSA_Public, type JWK_RSA_SIGN, type JWK_Symmetric, type JWK_Symmetric_Algorithm, type JWK_oct, JWTError, type JWTErrorCauseMap, type JWTErrorCode, type KeyManagementAlgorithm, type KnownJWTErrorCode, type ThumbprintHash, UnsecureError, type UnsecureErrorCode, type UnwrapKeyOptions, type UnwrapKeyResult, type UnwrappingKeyFor, type WrapKeyOptions, type WrapKeyResult, type WrappingKeyFor, isJWTError, isUnsecureError, thumbprint };

package/dist/core/jwk.mjs

@@ -1,3 +1,4 @@
-import { JWTError, isJWTError } from "../_chunks/utils.mjs";
-import { WeakMapJWKCache, clearJWKCache, configureJWKCache, deriveJWKFromPassword, deriveKeyFromPassword, deriveSharedSecret, exportKey, exportPEM, exportToPEM, generateJWK, generateKey, getJWKFromSet, getJWKsFromSet, importFromPEM, importKey, importPEM, unwrapKey, wrapKey } from "../_chunks/jwk.mjs";
-export { JWTError, WeakMapJWKCache, clearJWKCache, configureJWKCache, deriveJWKFromPassword, deriveKeyFromPassword, deriveSharedSecret, exportKey, exportPEM, exportToPEM, generateJWK, generateKey, getJWKFromSet, getJWKsFromSet, importFromPEM, importKey, importPEM, isJWTError, unwrapKey, wrapKey };
+import { UnsecureError } from "../_chunks/libs/unsecure.mjs";
+import { JWTError, isJWTError, isUnsecureError } from "../_chunks/_jwt-internal.mjs";
+import { WeakMapJWKCache, clearJWKCache, configureJWKCache, deriveJWKFromPassword, deriveKeyFromPassword, deriveSharedSecret, exportKey, exportPEM, generateJWK, generateKey, getJWKsFromSet, importKey, importPEM, thumbprint, unwrapKey, wrapKey } from "../_chunks/jwk.mjs";
+export { JWTError, UnsecureError, WeakMapJWKCache, clearJWKCache, configureJWKCache, deriveJWKFromPassword, deriveKeyFromPassword, deriveSharedSecret, exportKey, exportPEM, generateJWK, generateKey, getJWKsFromSet, importKey, importPEM, isJWTError, isUnsecureError, thumbprint, unwrapKey, wrapKey };