unjwt 0.8.3 → 0.8.5

package/dist/_chunks/digest.mjs

@@ -1,5 +1,6 @@
 import { textEncoder } from "./libs/unsecure.mjs";
-import { JWTError, base64UrlStringify, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet } from "./_jwt-internal.mjs";
+import { JWTError } from "../error.mjs";
+import { base64UrlStringify, hasSymmetricSecret, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet } from "./jwt.mjs";
 const ECDSA_CURVES = /* @__PURE__ */ Object.freeze({
 	ES256: "P-256",
 	ES384: "P-384",
@@ -149,7 +150,7 @@ function unionFromJWKSet(keys, mapper, options) {
 	const algs = /* @__PURE__ */ new Set();
 	for (const k of keys) {
 		if (!isJWK(k)) continue;
-		if (k.kty === "oct" && !options?.allowSymmetric) continue;
+		if (!options?.allowSymmetric && hasSymmetricSecret(k)) continue;
 		const mapped = mapper(k);
 		if (!mapped) continue;
 		for (const a of mapped) algs.add(a);
@@ -159,6 +160,12 @@ function unionFromJWKSet(keys, mapper, options) {
 function isEd25519Signature(alg) {
 	return alg === "EdDSA" || alg === "Ed25519";
 }
+function isSameAlgorithm(a, b) {
+	return a === b || isEd25519Signature(a) && isEd25519Signature(b);
+}
+function jwkAlgServes(jwk, alg) {
+	return isSameAlgorithm(jwk.alg, alg) || jwk.kty === "oct" && alg === "dir" && isContentEncryptionAlgorithm(jwk.alg);
+}
 function jwsAlgsFromJWK(jwk) {
 	if (jwk.alg && isEd25519Signature(jwk.alg)) return ["EdDSA", "Ed25519"];
 	if (jwk.alg) return isJWSAlgorithm(jwk.alg) ? [jwk.alg] : void 0;
@@ -253,4 +260,4 @@ async function digestUrl(data, hash = "SHA-256") {
 	const bytes = typeof data === "string" ? textEncoder.encode(data) : data;
 	return base64UrlStringify(new Uint8Array(await crypto.subtle.digest(hash, bytes)));
 }
-export { ECDSA_CURVES, PBES2_ALGORITHMS, aesBitsOf, checkKeyUsage, cryptoKeyCurve, digestUrl, hashBitsOf, inferJWEAllowedAlgorithms, inferJWSAllowedAlgorithms, innerKeyWrapAlg, isAlgorithm, isContentEncryptionAlgorithm, isECDHESAlgorithm, isEd25519Signature, isJWSAlgorithm, isKeyManagementAlgorithm, isPBES2Algorithm, jwsHashOf, lengthOf, modulusLengthOf, namedCurveOf, pbes2HashOf, rsaOaepHashOf, shaBitsOf, unusableKey };
+export { ECDSA_CURVES, PBES2_ALGORITHMS, aesBitsOf, checkKeyUsage, cryptoKeyCurve, digestUrl, hashBitsOf, inferJWEAllowedAlgorithms, inferJWSAllowedAlgorithms, innerKeyWrapAlg, isAlgorithm, isContentEncryptionAlgorithm, isECDHESAlgorithm, isJWSAlgorithm, isKeyManagementAlgorithm, isPBES2Algorithm, isSameAlgorithm, jwkAlgServes, jwsHashOf, lengthOf, modulusLengthOf, namedCurveOf, pbes2HashOf, rsaOaepHashOf, shaBitsOf, unusableKey };

package/dist/_chunks/error.d.mts

@@ -0,0 +1,103 @@
+import { UnsecureError, UnsecureErrorCode } from "./libs/unsecure.mjs";
+/**
+ * The closed union of error codes unjwt itself throws.
+ *
+ * Code naming follows the JOSE spec hierarchy:
+ *   ERR_JWT_*  — RFC 7519 JSON Web Token claim validation
+ *   ERR_JWS_*  — RFC 7515 JSON Web Signature
+ *   ERR_JWE_*  — RFC 7516 JSON Web Encryption
+ *   ERR_JWK_*  — RFC 7517 JSON Web Key
+ *   ERR_DPOP_* — RFC 9449 proof validation
+ *   ERR_SESSION_* — the framework session adapters
+ *
+ * Use this type where a typo must not compile — {@link isJWTError} takes it,
+ * so `isJWTError(err, "ERR_JWS_INVALD")` is a type error rather than a check
+ * that silently never matches. Use {@link JWTErrorCode} for values that may
+ * legitimately carry a code this version does not know about.
+ */
+export type KnownJWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | "ERR_DPOP_INVALID" | "ERR_DPOP_CLAIM_INVALID" | "ERR_DPOP_NONCE_INVALID" | "ERR_DPOP_REPLAY" | "ERR_SESSION_TOKEN_INVALID" | "ERR_SESSION_READONLY_EVENT" | "ERR_SESSION_KEY_INVALID" | "ERR_SESSION_CONFIG_INVALID" | "ERR_INVALID_OPTION";
+/**
+ * A {@link JWTError} `code`: every {@link KnownJWTErrorCode}, plus any other
+ * string for forward compatibility — a newer unjwt (or a caller constructing
+ * its own `JWTError`) may carry a code this version's union does not list.
+ */
+export type JWTErrorCode = KnownJWTErrorCode | (string & {});
+/**
+ * Maps known error codes to their structured `cause` shapes.
+ * Only codes that carry decoded context beyond the message appear here.
+ * Extend this interface when new structured causes are introduced.
+ */
+export interface JWTErrorCauseMap {
+  /** Decoded claims available at the point the lifetime check failed. */
+  ERR_JWT_EXPIRED: {
+    jti?: string;
+    iat?: number;
+    exp?: number;
+  };
+}
+/**
+ * Base error class for all unjwt errors. Every error thrown by the library is
+ * an instance of `JWTError`, so a single `instanceof` check is sufficient to
+ * distinguish library errors from other thrown values. Use the `code` property
+ * (or the `isJWTError` type guard) to narrow to a specific error condition.
+ *
+ * @example
+ * import { JWTError, isJWTError } from "unjwt/jws";
+ *
+ * try {
+ *   await verify(token, key);
+ * } catch (err) {
+ *   if (isJWTError(err, "ERR_JWT_EXPIRED")) {
+ *     console.log(err.cause.jti); // string | undefined
+ *   }
+ * }
+ */
+export declare class JWTError<TCode extends JWTErrorCode = JWTErrorCode> extends Error {
+  readonly code: TCode;
+  override readonly cause?: unknown;
+  constructor(message: string, code: TCode, cause?: unknown);
+}
+/**
+ * Type guard that narrows `error` to `JWTError`.
+ *
+ * When called with a code that is a key of `JWTErrorCauseMap`, the return
+ * type is additionally narrowed to include the structured `cause` shape for
+ * that code. When called with any other `KnownJWTErrorCode`, `code` is narrowed
+ * but `cause` remains `unknown`. When called without a code, narrows only to
+ * `JWTError`.
+ *
+ * `code` is a {@link KnownJWTErrorCode}, so a misspelled code fails to
+ * type-check instead of silently never matching.
+ *
+ * @example
+ * if (isJWTError(err, "ERR_JWT_EXPIRED")) {
+ *   err.cause.jti // string | undefined  ✓
+ * }
+ */
+export declare function isJWTError<T extends keyof JWTErrorCauseMap>(error: unknown, code: T): error is JWTError<T> & {
+  cause: JWTErrorCauseMap[T];
+};
+export declare function isJWTError<T extends KnownJWTErrorCode>(error: unknown, code: T): error is JWTError<T>;
+export declare function isJWTError(error: unknown): error is JWTError;
+/**
+ * Type guard that narrows `error` to the bundled {@link UnsecureError}, the
+ * class thrown by unjwt's codec / JSON / random primitives and carried as the
+ * `cause` of a {@link JWTError} when a wire segment or key field fails to
+ * decode. Pass a `code` to narrow further.
+ *
+ * Check against this export rather than a `UnsecureError` imported from a
+ * consumer-installed `unsecure`: unjwt bundles its own copy, so the two classes
+ * are distinct and `instanceof` against the latter is always `false`.
+ *
+ * @example
+ * import { isJWTError, isUnsecureError } from "unjwt/jws";
+ *
+ * const error = await verify(token, key).catch((e) => e);
+ * if (isJWTError(error, "ERR_JWS_INVALID") && isUnsecureError(error.cause, "MALFORMED")) {
+ *   // a segment of the token is not canonical base64url
+ * }
+ */
+export declare function isUnsecureError<T extends UnsecureErrorCode>(error: unknown, code: T): error is UnsecureError & {
+  code: T;
+};
+export declare function isUnsecureError(error: unknown): error is UnsecureError;

package/dist/_chunks/export.mjs

@@ -0,0 +1,97 @@
+import { JWTError } from "../error.mjs";
+import { isAsymmetricJWK, isCryptoKey, isJWK, isPublicJWK } from "./jwt.mjs";
+import { copyJsonObject, keyToJWK, thumbprint } from "./algorithms.mjs";
+const RESERVED_JWK_PARAMS = /* @__PURE__ */ new Set([
+	"kty",
+	"alg",
+	"key_ops",
+	"ext",
+	"k",
+	"d",
+	"n",
+	"e",
+	"p",
+	"q",
+	"dp",
+	"dq",
+	"qi",
+	"oth",
+	"x",
+	"y",
+	"crv"
+]);
+function assertNoReservedJWKParams(jwkParams) {
+	const reserved = Object.keys(jwkParams).filter((name) => RESERVED_JWK_PARAMS.has(name));
+	if (reserved.length > 0) throw new JWTError(`jwkParams must not set reserved JWK members: ${reserved.join(", ")}`, "ERR_INVALID_OPTION");
+}
+function assertKidOption(kid) {
+	if (kid === void 0 || kid === false || typeof kid === "string") return kid;
+	throw new JWTError("\"kid\" must be a string or false.", "ERR_INVALID_OPTION");
+}
+async function withGeneratedKid(kid, jwk) {
+	if (kid === false) return jwk;
+	return {
+		...jwk,
+		kid: kid ?? await thumbprint(jwk)
+	};
+}
+function requestedKeyOps(options, key) {
+	return options.keyUsage === void 0 ? void 0 : [...key.usages];
+}
+function withKeyOps(jwk, keyOps) {
+	return keyOps === void 0 ? jwk : {
+		...jwk,
+		key_ops: keyOps
+	};
+}
+async function exportJWK(key, jwkParams) {
+	if (!isCryptoKey(key)) throw new JWTError("exportJWK expects a CryptoKey.", "ERR_INVALID_OPTION");
+	if (!key.extractable) throw new JWTError("A non-extractable CryptoKey cannot be exported as a JWK.", "ERR_JWK_INVALID");
+	const exportedJwk = await keyToJWK(key);
+	if (jwkParams) {
+		const extraParams = copyJsonObject(jwkParams, {
+			code: "ERR_INVALID_OPTION",
+			message: "JWK parameters must hold only JSON values."
+		});
+		assertNoReservedJWKParams(extraParams);
+		return {
+			...exportedJwk,
+			...extraParams
+		};
+	}
+	return exportedJwk;
+}
+async function exportKey(key, jwkParams) {
+	return exportJWK(key, jwkParams);
+}
+function toPublicJWK(jwk) {
+	if (!isAsymmetricJWK(jwk)) throw new JWTError(isJWK(jwk) ? "An oct JWK has no public half." : "toPublicJWK expects an asymmetric JWK.", "ERR_JWK_INVALID");
+	const { d: _d, p: _p, q: _q, dp: _dp, dq: _dq, qi: _qi, oth: _oth, k: _k, key_ops, ...publicMembers } = copyJsonObject({ ...jwk }, {
+		code: "ERR_JWK_INVALID",
+		message: "A JWK must hold only JSON values."
+	});
+	const publicKey = key_ops === void 0 ? publicMembers : {
+		...publicMembers,
+		key_ops: publicKeyOps(key_ops)
+	};
+	if (!isPublicJWK(publicKey)) throw new JWTError(`${jwk.kty} JWK lacks the public members of its key type.`, "ERR_JWK_INVALID");
+	return publicKey;
+}
+const PUBLIC_KEY_OPS = /* @__PURE__ */ new Map([
+	["sign", "verify"],
+	["verify", "verify"],
+	["decrypt", "encrypt"],
+	["encrypt", "encrypt"],
+	["unwrapKey", "wrapKey"],
+	["wrapKey", "wrapKey"]
+]);
+function publicKeyOps(keyOps) {
+	if (!Array.isArray(keyOps)) return [];
+	const ops = [];
+	for (const op of keyOps) {
+		const publicOp = typeof op === "string" ? PUBLIC_KEY_OPS.get(op) : void 0;
+		if (publicOp !== void 0 && !ops.includes(publicOp)) ops.push(publicOp);
+	}
+	return ops;
+}
+export { assertKidOption, assertNoReservedJWKParams, exportJWK, exportKey, requestedKeyOps, toPublicJWK, withGeneratedKid, withKeyOps };

package/dist/_chunks/index.d.mts

@@ -1,105 +1,4 @@
-import { UnsecureError, UnsecureErrorCode } from "./libs/unsecure.mjs";
-/**
- * The closed union of error codes unjwt itself throws.
- *
- * Code naming follows the JOSE spec hierarchy:
- *   ERR_JWT_*  — RFC 7519 JSON Web Token claim validation
- *   ERR_JWS_*  — RFC 7515 JSON Web Signature
- *   ERR_JWE_*  — RFC 7516 JSON Web Encryption
- *   ERR_JWK_*  — RFC 7517 JSON Web Key
- *   ERR_SESSION_* — the framework session adapters
- *
- * Use this type where a typo must not compile — {@link isJWTError} takes it,
- * so `isJWTError(err, "ERR_JWS_INVALD")` is a type error rather than a check
- * that silently never matches. Use {@link JWTErrorCode} for values that may
- * legitimately carry a code this version does not know about.
- */
-export type KnownJWTErrorCode = "ERR_JWT_EXPIRED" | "ERR_JWT_NBF" | "ERR_JWT_CLAIM_INVALID" | "ERR_JWT_CLAIM_MISSING" | "ERR_JWS_INVALID" | "ERR_JWS_INVALID_SERIALIZATION" | "ERR_JWS_SIGNATURE_INVALID" | "ERR_JWS_ALG_NOT_ALLOWED" | "ERR_JWS_ALG_MISSING" | "ERR_JWS_SIGNER_ALG_INFERENCE" | "ERR_JWS_NO_MATCHING_SIGNER" | "ERR_JWS_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWS_B64_INCONSISTENT" | "ERR_JWE_INVALID" | "ERR_JWE_INVALID_SERIALIZATION" | "ERR_JWE_DECRYPTION_FAILED" | "ERR_JWE_ALG_NOT_ALLOWED" | "ERR_JWE_ALG_MISSING" | "ERR_JWE_ALG_FORBIDDEN_IN_MULTI" | "ERR_JWE_ENC_MISSING" | "ERR_JWE_RECIPIENT_ALG_INFERENCE" | "ERR_JWE_NO_MATCHING_RECIPIENT" | "ERR_JWE_HEADER_PARAMS_NOT_DISJOINT" | "ERR_JWK_INVALID" | "ERR_JWK_KEY_NOT_FOUND" | "ERR_JWK_UNSUPPORTED" | "ERR_SESSION_TOKEN_INVALID" | "ERR_SESSION_READONLY_EVENT" | "ERR_SESSION_KEY_INVALID" | "ERR_SESSION_CONFIG_INVALID" | "ERR_INVALID_OPTION";
-/**
- * A {@link JWTError} `code`: every {@link KnownJWTErrorCode}, plus any other
- * string for forward compatibility — a newer unjwt (or a caller constructing
- * its own `JWTError`) may carry a code this version's union does not list.
- */
-export type JWTErrorCode = KnownJWTErrorCode | (string & {});
-/**
- * Maps known error codes to their structured `cause` shapes.
- * Only codes that carry decoded context beyond the message appear here.
- * Extend this interface when new structured causes are introduced.
- */
-export interface JWTErrorCauseMap {
-  /** Decoded claims available at the point the lifetime check failed. */
-  ERR_JWT_EXPIRED: {
-    jti?: string;
-    iat?: number;
-    exp?: number;
-  };
-}
-/**
- * Base error class for all unjwt errors. Every error thrown by the library is
- * an instance of `JWTError`, so a single `instanceof` check is sufficient to
- * distinguish library errors from other thrown values. Use the `code` property
- * (or the `isJWTError` type guard) to narrow to a specific error condition.
- *
- * @example
- * import { JWTError, isJWTError } from "unjwt/jws";
- *
- * try {
- *   await verify(token, key);
- * } catch (err) {
- *   if (isJWTError(err, "ERR_JWT_EXPIRED")) {
- *     console.log(err.cause.jti); // string | undefined
- *   }
- * }
- */
-export declare class JWTError<TCode extends JWTErrorCode = JWTErrorCode> extends Error {
-  readonly code: TCode;
-  override readonly cause?: unknown;
-  constructor(message: string, code: TCode, cause?: unknown);
-}
-/**
- * Type guard that narrows `error` to `JWTError`.
- *
- * When called with a code that is a key of `JWTErrorCauseMap`, the return
- * type is additionally narrowed to include the structured `cause` shape for
- * that code. When called with any other `KnownJWTErrorCode`, `code` is narrowed
- * but `cause` remains `unknown`. When called without a code, narrows only to
- * `JWTError`.
- *
- * `code` is a {@link KnownJWTErrorCode}, so a misspelled code fails to
- * type-check instead of silently never matching.
- *
- * @example
- * if (isJWTError(err, "ERR_JWT_EXPIRED")) {
- *   err.cause.jti // string | undefined  ✓
- * }
- */
-export declare function isJWTError<T extends keyof JWTErrorCauseMap>(error: unknown, code: T): error is JWTError<T> & {
-  cause: JWTErrorCauseMap[T];
-};
-export declare function isJWTError<T extends KnownJWTErrorCode>(error: unknown, code: T): error is JWTError<T>;
-export declare function isJWTError(error: unknown): error is JWTError;
-/**
- * Type guard that narrows `error` to the bundled {@link UnsecureError}, the
- * class thrown by unjwt's codec / JSON / random primitives and carried as the
- * `cause` of a {@link JWTError} when a wire segment or key field fails to
- * decode. Pass a `code` to narrow further.
- *
- * Check against this export rather than a `UnsecureError` imported from a
- * consumer-installed `unsecure`: unjwt bundles its own copy, so the two classes
- * are distinct and `instanceof` against the latter is always `false`.
- *
- * @example
- * import { isJWTError, isUnsecureError } from "unjwt/jws";
- *
- * const error = await verify(token, key).catch((e) => e);
- * if (isJWTError(error, "ERR_JWS_INVALID") && isUnsecureError(error.cause, "MALFORMED")) {
- *   // a segment of the token is not canonical base64url
- * }
- */
-export declare function isUnsecureError<T extends UnsecureErrorCode>(error: unknown, code: T): error is UnsecureError & {
-  code: T;
-};
-export declare function isUnsecureError(error: unknown): error is UnsecureError;
+import { JWTError } from "./error.mjs";
 /** Header Parameters common to JWE and JWS. */
 export interface JoseHeaderParameters {
   /** "kid" (Key ID) Header Parameter */
@@ -225,7 +124,10 @@ export interface JWTTimeClaimOptions {
 }
 /** Options shared by `verify` and `decrypt` (compact and multi). */
 export interface JOSEConsumerOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> extends JWTClaimValidationOptions {
-  /** Admit `oct` entries of a JWK Set as key material; only for application-controlled sets. @default false */
+  /**
+   * Admit `oct` entries of a JWK Set as key material; only for application-controlled sets. @default false
+   * @deprecated A JWK Set is key material the caller chose to trust, so its `oct` entries count like any other; the option goes away and symmetric entries are admitted without it.
+   */
   allowSymmetricJWKSet?: boolean;
   /** Payload decoding mode; a mismatch is `ERR_JWS_INVALID` / `ERR_JWE_INVALID`. @default "json" */
   payload?: Mode;

package/dist/_chunks/index2.d.mts

@@ -1,12 +1,206 @@
-import { JWK } from "./index.mjs";
-import { DigestHash } from "./digest.mjs";
-/** Hash functions RFC 7638 §3.4 leaves open to the application. */
-export type ThumbprintHash = DigestHash;
-/**
- * The base64url JWK Thumbprint of a key (RFC 7638), over its required members only, so a
- * public key and its private counterpart share one. `hash` defaults to `"SHA-256"`
- * (RFC 7638 §3.4); a missing required member or unknown `kty` throws `ERR_JWK_INVALID`.
- */
-export declare function thumbprint(jwk: JWK, options?: {
-  hash?: ThumbprintHash;
-}): Promise<string>;
+import "./error.mjs";
+import { ContentEncryptionAlgorithm, DeriveJWKOptions, DeriveJWKReturn, DeriveKeyOptions, DeriveKeyReturn, GenerateJWKOptions, GenerateJWKReturn, GenerateKeyAlgorithm, GenerateKeyOptions, GenerateKeyReturn, ImportedKey, ImportedPEMJWK, JWK, JWKAlgorithm, JWKCacheAdapter, JWKMetadata, JWKPEMAlgorithm, JWKSet, JWK_Asymmetric, JWK_ECDH_ES, JWK_EC_Private, JWK_EC_Public, JWK_PBES2, JWK_oct, KeyManagementAlgorithm, PEMType, ToPublicJWKReturn, UnwrapKeyOptions, UnwrapKeyResult, UnwrappingKeyFor, WrapKeyOptions, WrapKeyResult, WrappingKeyFor } from "./index.mjs";
+import "./index3.mjs";
+/**
+ * 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: JWKAlgorithm): CryptoKey | undefined;
+  set(jwk: JWK, alg: JWKAlgorithm, key: CryptoKey): void;
+}
+/**
+ * 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: JWKAlgorithm) =>
+ *   `${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>;
+/**
+ * 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?: JWKAlgorithm | {
+  /** Algorithm hint. Required when `key.alg` is absent on an asymmetric JWK. */
+  alg?: JWKAlgorithm;
+  /** 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>>;
+/**
+ * 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[];
+/**
+ * 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<TAlg extends JWK_PBES2, Kid extends string | false = string>(password: string | Uint8Array<ArrayBuffer>, options: DeriveJWKOptions<TAlg, Kid> & Omit<JWKMetadata, "kid">): Promise<DeriveJWKReturn<TAlg, Kid>>;
+/**
+ * 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 exportJWK<T extends JWK = JWK>(key: CryptoKey, jwkParams?: JWKMetadata): Promise<T>;
+/** @deprecated Use `exportJWK`; removed in 0.9.0. */
+export declare function exportKey<T extends JWK = JWK>(key: CryptoKey, jwkParams?: JWKMetadata): Promise<T>;
+/**
+ * Utility to derive the public half of an asymmetric JWK, or throw if the input is not asymmetric.
+ *
+ * @param jwk An asymmetric JWK (EC, OKP, RSA) with a private scalar (`d`).
+ * @throws `ERR_JWK_INVALID` if the input is not an asymmetric JWK.
+ * @returns A JWK with the same public members, without the private scalar or a `k` member.
+ */
+export declare function toPublicJWK<T extends JWK_Asymmetric>(jwk: T): ToPublicJWKReturn<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<A extends JWKPEMAlgorithm, Type extends PEMType | undefined = undefined>(pem: string, alg: A, options?: {
+  /** PEM type. Inferred from the PEM label when omitted, which leaves the result public or private. */
+  pemType?: Type;
+  /** Additional JWK properties merged into the exported key (e.g. `kid`). */
+  jwkParams?: JWKMetadata;
+}): Promise<ImportedPEMJWK<A, Type>>;
+/**
+ * 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>;
+/**
+ * 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>>;