unjwt 0.7.2 → 0.8.0

package/dist/_chunks/index2.d.mts

@@ -0,0 +1,11 @@
+import { JWK } from "./index.mjs";
+/** Hash functions RFC 7638 §3.4 leaves open to the application. */
+export type ThumbprintHash = "SHA-256" | "SHA-384" | "SHA-512";
+/**
+ * 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>;

package/dist/_chunks/index3.d.mts

@@ -0,0 +1,108 @@
+import { BytesSource, DecodeOptions, DecodeReturnAs } from "./libs/unsecure.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 { 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";
+/**
+ * Encode bytes or a UTF-8 string as base64url the way JOSE defines it
+ * (RFC 7515 §2): URL-safe alphabet, no `=` padding, no line breaks.
+ */
+export declare function base64UrlStringify(data: string | BytesSource): string;
+/**
+ * Decode JOSE base64url (RFC 7515 §2). Strict: only the canonical, unpadded
+ * encoding of a byte string is accepted — `=`, whitespace, characters outside
+ * the URL-safe alphabet and set bits past the final byte are rejected, and a
+ * `string` result must be valid UTF-8. The return type mirrors the input unless
+ * `returnAs` is given. `{ loose: true }` drops what it cannot use instead of
+ * throwing: meant for application data, never for token material.
+ *
+ * @throws {UnsecureError} `MALFORMED` unless `loose`; `INVALID_TYPE` for input that is neither text nor bytes
+ */
+export declare function base64UrlParse<T extends DecodeReturnAs>(input: string | Uint8Array, options: DecodeOptions & {
+  returnAs: T;
+}): T extends "string" ? string : Uint8Array<ArrayBuffer>;
+export declare function base64UrlParse(input: string, options?: DecodeOptions): string;
+export declare function base64UrlParse(input: Uint8Array, options?: DecodeOptions): Uint8Array<ArrayBuffer>;
+/** Encode bytes or a UTF-8 string as standard base64 (RFC 4648 §4), with `=` padding. */
+export declare function base64Stringify(data: string | BytesSource): string;
+/**
+ * Decode standard base64 (RFC 4648 §4). Strict: the canonical encoding with its
+ * `=` padding present. Otherwise the same contract as {@link base64UrlParse}.
+ *
+ * @throws {UnsecureError} `MALFORMED` unless `loose`; `INVALID_TYPE` for input that is neither text nor bytes
+ */
+export declare function base64Parse<T extends DecodeReturnAs>(input: string | Uint8Array, options: DecodeOptions & {
+  returnAs: T;
+}): T extends "string" ? string : Uint8Array<ArrayBuffer>;
+export declare function base64Parse(input: string, options?: DecodeOptions): string;
+export declare function base64Parse(input: Uint8Array, options?: DecodeOptions): Uint8Array<ArrayBuffer>;
+/** @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. */
+export declare function concatUint8Arrays(...arrays: Readonly<Uint8Array<ArrayBuffer>[]>): Uint8Array<ArrayBuffer>;
+/** Wrap a value in an array; returns the array unchanged if already an array. */
+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. */
+export declare function isJWKSet(key: unknown): key is JWKSet;
+/** Asserts that `key` is a `CryptoKey`; throws `ERR_JWK_INVALID` otherwise. */
+export declare function assertCryptoKey(key: unknown): asserts key is CryptoKey;
+/** Whether `key` is a `CryptoKey`, checked via `Symbol.toStringTag` to work across realms. */
+export declare function isCryptoKey(key: unknown): key is CryptoKey;
+/** Whether `key` is a `CryptoKeyPair` of two CryptoKeys. */
+export declare const isCryptoKeyPair: (key: unknown) => key is CryptoKeyPair;
+/** Whether the JWK is symmetric (`oct`); its `k` is always secret. */
+export declare function isSymmetricJWK<T>(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). */
+export declare function isAsymmetricJWK<T>(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`.
+ */
+export declare function isPrivateJWK<T>(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. */
+export declare function isPublicJWK<T>(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.
+ */
+export declare function inferJWSAllowedAlgorithms(key: unknown, options?: InferAlgorithmsOptions): 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.
+ */
+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;

package/dist/_chunks/jwe.d.mts

@@ -1,84 +1,61 @@
-import { ContentEncryptionAlgorithm, JOSEPayload, JWEDecryptJWK, JWEDecryptOptions, JWEDecryptResult, JWEEncryptJWK, JWEEncryptOptions, JWEFlattenedSerialization, JWEGeneralSerialization, JWEMultiDecryptOptions, JWEMultiDecryptResult, JWEMultiEncryptOptions, JWEMultiRecipient, JWKLookupFunction, JWKSet, KeyManagementAlgorithm } from "./index.mjs";
+import { ContentEncryptionAlgorithm, JOSEPayload, JOSEPayloadMode, JWEDecryptJWK, JWEDecryptOptions, JWEDecryptResult, JWEEncryptJWK, JWEEncryptOptions, JWEFlattenedSerialization, JWEGeneralSerialization, JWEMultiDecryptKey, JWEMultiDecryptOptions, JWEMultiDecryptResult, JWEMultiEncryptOptions, JWEMultiRecipient, JWKLookupFunction, JWKSet, JWTClaims, KeyManagementAlgorithm, PayloadOf } from "./index.mjs";
+import "./_internal.mjs";
 /**
-* Encrypt a payload to multiple recipients using JWE General JSON Serialization
-* (RFC 7516 §7.2.1).
-*
-* One shared CEK encrypts the payload once; the CEK is then wrapped
-* independently per recipient using each recipient's key-management algorithm.
-* Per-recipient `alg` is read from `key.alg` and throws `ERR_JWE_RECIPIENT_ALG_INFERENCE`
-* when absent.
-*
-* Throws `ERR_JWE_ALG_FORBIDDEN_IN_MULTI` when any recipient resolves to `dir`
-* or bare `ECDH-ES` — those algorithms require exactly one recipient; use
-* {@link encrypt} instead.
-*
-* @example
-* const jwe = await encryptMulti({ sub: "u1" }, [
-*   { key: aliceRsaPublicJwk },
-*   { key: bobEcdhPublicJwk },
-* ], { enc: "A256GCM", expiresIn: "1h" });
-*/
-declare function encryptMulti(payload: JOSEPayload, recipients: JWEMultiRecipient[], options?: JWEMultiEncryptOptions): Promise<JWEGeneralSerialization>;
+ * Encrypt a payload to multiple recipients as JWE General JSON Serialization (RFC 7516 §7.2.1).
+ * Each recipient's `alg` comes from `key.alg` (`ERR_JWE_RECIPIENT_ALG_INFERENCE` when absent);
+ * `dir` and bare `ECDH-ES` throw `ERR_JWE_ALG_FORBIDDEN_IN_MULTI`.
+ */
+export declare function encryptMulti(payload: JOSEPayload, recipients: JWEMultiRecipient[], options?: JWEMultiEncryptOptions): Promise<JWEGeneralSerialization>;
 /**
-* Decrypt a JWE in JSON Serialization object form (General RFC 7516 §7.2.1 or
-* Flattened §7.2.2 — both accepted).
-*
-* Matches recipients by, in order: `kid` equality, `kty`/`crv`/length
-* compatibility, then trial decryption. Set `strictRecipientMatch: true` to
-* disable the trial fallback.
-*
-* For compact (string) tokens, use {@link decrypt}.
-*/
-declare function decryptMulti<T extends JOSEPayload = JOSEPayload>(jwe: JWEGeneralSerialization | JWEFlattenedSerialization, keyOrLookup: CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWEMultiDecryptOptions): Promise<JWEMultiDecryptResult<T>>;
+ * Decrypt a JWE General (RFC 7516 §7.2.1) or Flattened (§7.2.2) JSON Serialization.
+ * Recipients are tried in order; per-recipient failures surface only when none unwraps.
+ * `strictRecipientMatch` skips recipients the key cannot open and throws
+ * `ERR_JWE_NO_MATCHING_RECIPIENT` when none qualifies; a JWK Set with no `kid` candidate
+ * throws `ERR_JWK_KEY_NOT_FOUND`. The payload type follows `options.payload`.
+ */
+export declare function decryptMulti<T extends Record<string, unknown> = JWTClaims>(jwe: JWEGeneralSerialization | JWEFlattenedSerialization, keyOrLookup: JWEMultiDecryptKey, options?: JWEMultiDecryptOptions<"json"> & {
+  forceUint8Array?: false;
+}): Promise<JWEMultiDecryptResult<T>>;
+/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
+export declare function decryptMulti(jwe: JWEGeneralSerialization | JWEFlattenedSerialization, keyOrLookup: JWEMultiDecryptKey, options: JWEMultiDecryptOptions & {
+  forceUint8Array: true;
+}): Promise<JWEMultiDecryptResult<Uint8Array<ArrayBuffer>>>;
+/** Decrypts a JWE JSON Serialization whose plaintext decodes under `options.payload`; see {@link PayloadOf}. */
+export declare function decryptMulti<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jwe: JWEGeneralSerialization | JWEFlattenedSerialization, keyOrLookup: JWEMultiDecryptKey, options?: JWEMultiDecryptOptions<Mode>): Promise<JWEMultiDecryptResult<PayloadOf<Mode>>>;
 /**
-* Convert a {@link JWEGeneralSerialization} with exactly one recipient into
-* the {@link JWEFlattenedSerialization} form (RFC 7516 §7.2.2). Throws
-* `ERR_JWE_INVALID_SERIALIZATION` when the input has zero or multiple
-* recipients — Flattened is strictly single-recipient.
-*
-* `encryptMulti` never emits Flattened itself (stable return shape across
-* recipient counts); this is the canonical post-processing step when
-* interoperating with a strict Flattened-only consumer.
-*
-* @example
-* const general = await encryptMulti(payload, [recipient], opts);
-* const flattened = generalToFlattened(general);
-*/
-declare function generalToFlattened(jwe: JWEGeneralSerialization): JWEFlattenedSerialization;
+ * Convert a single-recipient General JWE to the Flattened form (RFC 7516 §7.2.2).
+ * Throws `ERR_JWE_INVALID_SERIALIZATION` for zero or multiple recipients.
+ */
+export declare function generalToFlattened(jwe: JWEGeneralSerialization): JWEFlattenedSerialization;
 /**
-* Encrypts a payload to produce a JWE Compact Serialization string.
-*
-* @param payload The payload to encrypt. Can be a string, Uint8Array, or a JSON-serializable object.
-* @param key The key encryption key (KEK). Can be a CryptoKey, JWK, or for PBES2, a password string/Uint8Array.
-* @param options JWE encryption options, including `alg` (key management algorithm) and `enc` (content encryption algorithm).
-* @returns A Promise resolving to the JWE Compact Serialization string.
-*/
-declare function encrypt(payload: JOSEPayload, key: JWEEncryptJWK | string | Uint8Array<ArrayBuffer>, options?: JWEEncryptOptions): Promise<string>;
-declare function encrypt(payload: JOSEPayload, key: CryptoKey | Extract<JWEEncryptJWK, {
+ * Encrypt a payload into a JWE Compact Serialization string. `key` is a CryptoKey, a JWK, or
+ * a PBES2 password; `alg` is inferred from it when omitted and `enc` defaults to `A256GCM`.
+ */
+export declare function encrypt(payload: JOSEPayload, key: JWEEncryptJWK | string | Uint8Array<ArrayBuffer>, options?: JWEEncryptOptions): Promise<string>;
+export declare function encrypt(payload: JOSEPayload, key: CryptoKey | Extract<JWEEncryptJWK, {
   kty: "oct";
 }> | Uint8Array<ArrayBuffer>, options: JWEEncryptOptions & {
   alg: "dir";
   enc: ContentEncryptionAlgorithm;
 }): Promise<string>;
-declare function encrypt(payload: JOSEPayload, key: CryptoKey, options: JWEEncryptOptions & {
+export declare function encrypt(payload: JOSEPayload, key: CryptoKey, options: JWEEncryptOptions & {
   alg: KeyManagementAlgorithm;
   enc: ContentEncryptionAlgorithm;
 }): Promise<string>;
-declare function encrypt(payload: JOSEPayload, key: CryptoKey | JWEEncryptJWK | string | Uint8Array<ArrayBuffer>, options: JWEEncryptOptions & {
+export declare function encrypt(payload: JOSEPayload, key: CryptoKey | JWEEncryptJWK | string | Uint8Array<ArrayBuffer>, options: JWEEncryptOptions & {
   alg: KeyManagementAlgorithm;
   enc: ContentEncryptionAlgorithm;
 }): Promise<string>;
 /**
-* Decrypts a JWE Compact Serialization string.
-*
-* @param jwe The JWE Compact Serialization string.
-* @param key The key decryption key (KEK) or a function to look up the key.
-* @param options JWE decryption options.
-* @returns A Promise resolving to an object containing the decrypted plaintext, protected header, CEK, and AAD.
-* @throws If JWE is invalid, decryption fails, or options are not met.
-*/
-declare function decrypt<T extends JOSEPayload>(jwe: string, key: CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWEDecryptOptions): Promise<JWEDecryptResult<T>>;
-declare function decrypt(jwe: string, key: CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options: JWEDecryptOptions & {
+ * Decrypt a JWE Compact Serialization string; `key` may be a lookup function.
+ * The payload type follows `options.payload` (claims `T` by default).
+ */
+export declare function decrypt<T extends Record<string, unknown> = JWTClaims>(jwe: string, key: CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWEDecryptOptions<"json"> & {
+  forceUint8Array?: false;
+}): Promise<JWEDecryptResult<T>>;
+/** @deprecated `forceUint8Array` is replaced by `payload: "bytes"`; removed in v0.9.0. */
+export declare function decrypt(jwe: string, key: CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options: JWEDecryptOptions & {
   forceUint8Array: true;
 }): Promise<JWEDecryptResult<Uint8Array<ArrayBuffer>>>;
-export { decrypt, decryptMulti, encrypt, encryptMulti, generalToFlattened };
+/** Decrypts a compact JWE whose plaintext decodes under `options.payload`; see {@link PayloadOf}. */
+export declare function decrypt<Mode extends JOSEPayloadMode = JOSEPayloadMode>(jwe: string, key: CryptoKey | JWKSet | JWEDecryptJWK | string | Uint8Array<ArrayBuffer> | JWKLookupFunction, options?: JWEDecryptOptions<Mode>): Promise<JWEDecryptResult<PayloadOf<Mode>>>;