unjwt 0.7.2 → 0.8.0

package/dist/_chunks/jwt.d.mts

@@ -0,0 +1,56 @@
+import { Duration, JOSEPayloadMode, JWTClaimValidationOptions, JWTClaims, JWTErrorCode, JWTTimeClaimOptions, PayloadOf } from "./index.mjs";
+/** Set `typ: "JWT"` on a header without `typ` when the payload is an object (not a `Uint8Array`). */
+export declare function applyTypDefault<T extends {
+  typ?: string;
+}>(header: T, payload: unknown): T;
+/** Options for {@link parsePayloadBytes} and {@link parsePayloadSegment}. */
+export interface ParsePayloadOptions<Mode extends JOSEPayloadMode = JOSEPayloadMode> {
+  /** How to interpret the payload bytes; the return type follows it. @default "json" */
+  payload?: Mode;
+  /** Family the rejection is reported under (`ERR_JWS_INVALID` / `ERR_JWE_INVALID`). @default "JWS" */
+  family?: "JWS" | "JWE";
+}
+/** Parse payload bytes under the declared mode: `"json"` needs a UTF-8 JSON object, `"string"` UTF-8; throws `ERR_JWS_INVALID` / `ERR_JWE_INVALID`. */
+export declare function parsePayloadBytes<T = JWTClaims>(bytes: Uint8Array<ArrayBuffer>, options?: ParsePayloadOptions<"json">): T;
+export declare function parsePayloadBytes<Mode extends JOSEPayloadMode = JOSEPayloadMode>(bytes: Uint8Array<ArrayBuffer>, options?: ParsePayloadOptions<Mode>): PayloadOf<Mode>;
+/** Decode payload bytes as UTF-8; throws `ERR_JWS_INVALID` / `ERR_JWE_INVALID` otherwise. */
+export declare function parsePayloadText(bytes: Uint8Array<ArrayBuffer>, options?: Pick<ParsePayloadOptions, "family">): string;
+/** {@link parsePayloadBytes} over a Base64URL-encoded payload segment. */
+export declare function parsePayloadSegment<T = JWTClaims>(payloadEncoded: string, options?: ParsePayloadOptions<"json">): T;
+export declare function parsePayloadSegment<Mode extends JOSEPayloadMode = JOSEPayloadMode>(payloadEncoded: string, options?: ParsePayloadOptions<Mode>): PayloadOf<Mode>;
+/** Encode a payload to bytes; a non-serializable one throws `ERR_INVALID_OPTION`. */
+export declare function getPlaintextBytes(payload: string | Uint8Array<ArrayBuffer> | Record<string, unknown>): Uint8Array<ArrayBuffer>;
+/** Options for {@link computeJwtTimeClaims}. */
+export type ComputeJwtTimeClaimsOptions = JWTTimeClaimOptions;
+/**
+ * Return a copy of an object payload with `iat` and the requested `exp` / `nbf`, or `undefined` when none applies.
+ * Both members of `expiresIn`/`expiresAt` or `notBeforeIn`/`notBeforeAt` throw `ERR_JWT_CLAIM_INVALID`.
+ */
+export declare function computeJwtTimeClaims(payload: unknown, options?: ComputeJwtTimeClaimsOptions): JWTClaims | undefined;
+/** Validate critical headers in JWS semantics. */
+export declare function validateCriticalHeadersJWS(protectedHeader: {
+  crit?: string[];
+} & Record<string, unknown>, recognizedHeaders?: string[]): void;
+/** Validate critical headers in JWE semantics. */
+export declare function validateCriticalHeadersJWE(protectedHeader: {
+  crit?: string[];
+} & Record<string, unknown>, recognizedHeaders?: string[]): void;
+/** Assert `crit` is a non-empty string array with no registered header name (RFC 7515 §4.1.11 / RFC 7516 §4.1.13). */
+export declare function assertCritShape(crit: unknown, options: {
+  family: "JWS" | "JWE";
+  code?: JWTErrorCode;
+}): asserts crit is string[];
+/** Whether headers declare JSON content: a string `typ` naming JWT, or a JSON `cty`. */
+export declare function isJWTContent(header: {
+  typ?: string;
+  cty?: string;
+} | undefined): boolean;
+/** Parse a `Duration` (e.g. `3600` or `"10m"`) into positive integer seconds; else `ERR_INVALID_OPTION`. */
+export declare function computeDurationInSeconds(duration: Duration): number;
+/** The `ERR_JWT_EXPIRED` message for a token whose `exp` (NumericDate seconds) has passed. */
+export declare function expiredClaimMessage(exp: number): string;
+/**
+ * Validate JWT claims against the set expectations. A malformed expectation throws
+ * `ERR_INVALID_OPTION`; an empty `audience` or `issuer` list matches no token.
+ */
+export declare function validateJwtClaims(jwtClaims: JWTClaims, options?: JWTClaimValidationOptions): void;

package/dist/_chunks/libs/unsecure.d.mts

@@ -1,94 +1,173 @@
 /**
-* Generate a Uint8Array of cryptographically secure random bytes.
-*
-* @param length Number of random bytes to generate.
-* @returns A Uint8Array filled with random bytes.
-*
-* @example
-* const key = secureRandomBytes(32); // 256-bit key material
-*/
-declare function secureRandomBytes(length: number): Uint8Array<ArrayBuffer>;
+ * What kind of mistake an {@link UnsecureError} reports.
+ *
+ * This is the complete set for this release, so a `switch` over it is
+ * exhaustive today. A later minor may add a member — keep a default branch, or
+ * a new code will fall through unhandled.
+ *
+ * - `INVALID_TYPE` — a value of the wrong JavaScript type, or nothing where a
+ *   value is required.
+ * - `OUT_OF_RANGE` — the right type, outside its documented domain: a number
+ *   past its bounds, an empty secret, an alphabet that is not 32 distinct
+ *   ASCII characters, no character set selected.
+ * - `MALFORMED` — text that is not what it claims to be: a non-canonical
+ *   encoding, decoded bytes that are not valid UTF-8, JSON that does not parse.
+ * - `UNSUPPORTED` — a name outside the set the library accepts: a digest
+ *   algorithm, a `returnAs`, an `otpauthURI` `type`.
+ * - `FROZEN` — a dangerous key cannot be removed because the object holding it
+ *   is frozen or sealed.
+ * - `PLATFORM` — the runtime's Web Crypto refused an operation the library had
+ *   already validated; `cause` carries the platform error.
+ */
+export type UnsecureErrorCode = "INVALID_TYPE" | "OUT_OF_RANGE" | "MALFORMED" | "UNSUPPORTED" | "FROZEN" | "PLATFORM";
 /**
-* Shuffles an array in-place using the Fisher-Yates algorithm with a
-* cryptographically secure random number generator.
-* @template T
-* @param {Array<T>} array The array to shuffle.
-* @param {SecureRandomGenerator} [generator] - An optional random number generator to reuse.
-*
-* @description If you require to shuffle multiple times it is adviced to pass the `generator` parameter to avoid creating a new generator for each shuffle. (refer to `createSecureRandomGenerator()` factory)
-*
-* @returns {Array<T>} The shuffled array.
-*/
+ * Everything this library throws.
+ *
+ * `message` says what was found and where; `code` is the machine-readable
+ * version of the same judgement, and is what a caller should branch on. A
+ * failure that came from outside the library — the runtime's Web Crypto, or
+ * `JSON.parse` — carries the original in `cause`.
+ *
+ * @example
+ * try {
+ *   await hmacVerify(secret, body, signature);
+ * } catch (error) {
+ *   if (!(error instanceof UnsecureError)) throw error;
+ *   switch (error.code) {
+ *     case "OUT_OF_RANGE": {
+ *       // The secret failed to load: a deployment problem, not a bad request.
+ *       return respond(500);
+ *     }
+ *     case "PLATFORM": {
+ *       return respond(503, { cause: error.cause });
+ *     }
+ *     default: {
+ *       return respond(400, { reason: error.code });
+ *     }
+ *   }
+ * }
+ */
+export declare class UnsecureError extends Error {
+  readonly code: UnsecureErrorCode;
+  constructor(code: UnsecureErrorCode, message: string, options?: ErrorOptions);
+}
 /**
-* Parse JSON while stripping prototype-pollution vectors during parsing.
-*
-* Uses a reviver to drop own properties named `__proto__`, `prototype`, or
-* `constructor` before they can be assigned. For nested payloads this is
-* cheaper than parsing first and sanitizing after, and it guarantees no
-* unsanitized object ever exists.
-*
-* @param json The JSON text to parse.
-* @returns The parsed value with dangerous keys stripped.
-* @throws {SyntaxError} If `json` is not valid JSON.
-*
-* @example
-* const payload = safeJsonParse<{ user: { name: string } }>(untrustedInput);
-*/
-declare function safeJsonParse<T = any>(json: string): T;
+ * Generate a Uint8Array of cryptographically secure random bytes. Up to 64
+ * bytes come from the shared entropy pool; longer requests go to
+ * `crypto.getRandomValues` directly, in 65536-byte chunks.
+ *
+ * @param length Number of random bytes to generate, from 0 to `2**31 - 1`.
+ * @returns A Uint8Array filled with random bytes.
+ *
+ * @throws {UnsecureError} `OUT_OF_RANGE` if `length` is not an integer in
+ *                         `[0, 2**31 - 1]`.
+ *
+ * @example
+ * const key = secureRandomBytes(32); // 256-bit key material
+ */
+export declare function secureRandomBytes(length: number): Uint8Array<ArrayBuffer>;
 /**
-* Remove prototype-pollution vectors from a plain record in-place.
-*
-* Strips own properties named `__proto__`, `prototype`, and `constructor`
-* recursively through nested objects and arrays. Cycle-safe.
-*
-* Returns the same reference for convenience. Use {@link sanitizeObjectCopy}
-* if you need a deep copy with the original preserved.
-*/
-declare function sanitizeObject<T extends Record<string, unknown> | undefined>(obj: T): T;
+ * Parse JSON and strip prototype-pollution vectors from the result.
+ *
+ * `JSON.parse` runs first, then the in-place sanitizer walks the parsed value
+ * and removes own properties named `__proto__`, `prototype`, or `constructor`
+ * at every depth. Nothing holding a dangerous key survives the call — the
+ * sanitizer finishes before the value is returned — and no caller-visible
+ * object is ever assigned through, so no prototype is polluted along the way.
+ *
+ * Any JSON root is handled: objects, arrays, and primitives alike.
+ *
+ * @param json The JSON text to parse.
+ * @returns The parsed value with dangerous keys stripped.
+ * @throws {UnsecureError} `MALFORMED` if `json` is not valid JSON — the engine's
+ *                         own error travels as `cause`; `FROZEN` if a dangerous key
+ *                         sits on a frozen or sealed object, see
+ *                         {@link sanitizeObject}.
+ *
+ * @example
+ * const payload = safeJsonParse<{ user: { name: string } }>(untrustedInput);
+ */
+export declare function safeJsonParse<T = any>(json: string): T;
 /**
-* Return a sanitized deep copy of `obj`. The input is never mutated.
-*
-* Dangerous keys (`__proto__`, `prototype`, `constructor`) are stripped
-* recursively. The returned structure consists of plain objects (rooted on
-* `Object.prototype`) and arrays. Cycle-safe: circular references in the
-* input are preserved in the output (pointing at the copied node, not the
-* original reference).
-*
-* Non-object / undefined inputs are returned unchanged.
-*/
-declare function sanitizeObjectCopy<T extends Record<string, unknown> | undefined>(obj: T): T;
+ * Remove prototype-pollution vectors from a plain record in-place.
+ *
+ * Strips own properties named `__proto__`, `prototype`, and `constructor`
+ * through nested objects and arrays, enumerable or not. Cycle-safe.
+ *
+ * Values are read from their property descriptors — array elements included —
+ * so a getter is never invoked: an accessor is neither traversed nor removed
+ * unless its name is one of the three. A `Proxy` is the exception and cannot
+ * be otherwise: its traps run for every property operation, so a proxied
+ * object is traversed through its own traps.
+ *
+ * Traversal reaches every object held in a data property, whatever its
+ * prototype. What such an object *holds* internally is another matter: `Map`
+ * entries, `Set` members and anything else living outside own properties are
+ * never read, so they are never sanitized.
+ *
+ * Returns the same reference for convenience. Use {@link sanitizeObjectCopy}
+ * if you need a deep copy with the original preserved.
+ *
+ * @throws {UnsecureError} `FROZEN` if a dangerous key cannot be removed because
+ *                         the object holding it is frozen or sealed. Leaving the
+ *                         key in place would report a sanitized object that is not
+ *                         one.
+ */
+export declare function sanitizeObject<T extends Record<string, unknown> | undefined>(obj: T): T;
 /**
-* Base64 encoding. Accepts `string` or raw bytes; throws `TypeError` on
-* `null`/`undefined`. Empty strings and empty `Uint8Array` return `""`.
-*/
-declare function base64Encode(data: Uint8Array | string): string;
+ * Return a sanitized deep copy of `obj`. The input is never mutated.
+ *
+ * Dangerous keys (`__proto__`, `prototype`, `constructor`) are stripped from
+ * every array and plain object reached. A plain object is one rooted on
+ * `Object.prototype` or on `null`; copies of both are rooted on
+ * `Object.prototype`. Every other value — `Date`, `Map`, `Set`, typed
+ * arrays, `RegExp`, class instances, functions — is carried into the copy by
+ * reference, exactly as {@link sanitizeObject} leaves it in place. By
+ * reference means unchanged *and* unsanitized: what a `Map` or `Set` holds is
+ * never read by either function.
+ *
+ * Only own enumerable data properties are copied — the JSON shape. Accessors
+ * are skipped rather than invoked, so the copy never runs caller code; an
+ * accessor at an array index leaves a hole there and the elements after it
+ * keep their positions. A `Proxy` is traversed through its own traps, which
+ * run whatever the copy asks for.
+ *
+ * Cycle-safe: circular references in the input are preserved in the output
+ * (pointing at the copied node, not the original reference).
+ *
+ * Non-object / undefined inputs — and objects that are not arrays or plain
+ * objects — are returned unchanged.
+ */
+export declare function sanitizeObjectCopy<T extends Record<string, unknown> | undefined>(obj: T): T;
 /**
-* Base64 URL-safe encoding (no padding). Accepts `string` or raw bytes;
-* throws `TypeError` on `null`/`undefined`. Empty inputs return `""`.
-*/
-declare function base64UrlEncode(data: Uint8Array | string): string;
-declare function base64Decode<T extends DecodeReturnAs>(data: string | Uint8Array, options: {
-  returnAs: T;
-}): T extends "string" ? string : Uint8Array<ArrayBuffer>;
-declare function base64Decode(data: string): string;
-declare function base64Decode(data: Uint8Array): Uint8Array<ArrayBuffer>;
-declare function base64UrlDecode<T extends DecodeReturnAs>(data: string | Uint8Array, options: {
-  returnAs: T;
-}): T extends "string" ? string : Uint8Array<ArrayBuffer>;
-declare function base64UrlDecode(data: string): string;
-declare function base64UrlDecode(data: Uint8Array): Uint8Array<ArrayBuffer>;
+ * Shared UTF-8 `TextEncoder`. Encoding holds no state between calls, so a
+ * single instance serves every caller.
+ */
+export declare const textEncoder: TextEncoder;
 /**
-* Hex encoding. Accepts `string` or raw bytes; throws `TypeError` on
-* `null`/`undefined`. Empty strings and empty `Uint8Array` return `""`.
-*/
+ * Any byte container the library accepts: an `ArrayBuffer` — shared or not —
+ * or a view over one. Wider than the DOM `BufferSource`, which excludes
+ * `SharedArrayBuffer`-backed views.
+ */
+export type BytesSource = ArrayBufferLike | ArrayBufferView<ArrayBufferLike>;
 /**
-* Output-shape option shared by `hexDecode`, `base64Decode`, `base64UrlDecode`,
-* and `base32Decode`. Decoders mirror their input type when this is omitted:
-* `string` input decodes to `string`, `Uint8Array` input decodes to `Uint8Array`.
-*
-* `"bytes"` is an alias for `"uint8array"`.
-*/
-type DecodeReturnAs = "string" | "uint8array" | "bytes";
-declare const textEncoder: TextEncoder;
-declare const textDecoder: TextDecoder;
-export { base64Decode, base64Encode, base64UrlDecode, base64UrlEncode, safeJsonParse, sanitizeObject, sanitizeObjectCopy, secureRandomBytes, textDecoder, textEncoder };
+ * Shared UTF-8 `TextDecoder` instance. `ignoreBOM` keeps a leading U+FEFF in
+ * the output: what the codecs decode is a byte string, and a BOM inside it is
+ * payload, not a signature to swallow.
+ */
+export declare const textDecoder: TextDecoder;
+/**
+ * Decoder output shape. Omit to mirror the input (`string` in → `string` out,
+ * `Uint8Array` in → `Uint8Array` out). `"bytes"` aliases `"uint8array"`.
+ */
+export type DecodeReturnAs = "string" | "uint8array" | "bytes";
+/** Shared `parse` options. */
+export interface DecodeOptions {
+  /** Output shape. Mirrors the input type when omitted. */
+  returnAs?: DecodeReturnAs;
+  /**
+   * Tolerate malformed input (skip/normalize) instead of throwing.
+   * @default false
+   */
+  loose?: boolean;
+}