shelving 1.136.0 → 1.138.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.136.0",
+	"version": "1.138.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/util/base64.d.ts

@@ -1,8 +1,13 @@
-/** Encode a string to Base64 (with no `=` padding on the end). */
-export declare function base64Encode(str: string): string;
-/** Decode a string from Base64 (strips `=` padding on the end). */
-export declare function base64Decode(b64: string): string;
-/** Encode a string to URL-safe Base64 */
-export declare function base64UrlEncode(str: string): string;
+import { type PossibleBytes } from "./bytes.js";
+/** Encode a string or binary data to Base64 string. */
+export declare function encodeBase64(input: PossibleBytes, pad?: boolean): string;
+/** Decode Base64 string to string. */
+export declare function decodeBase64String(base64: string): string;
+/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
+export declare function decodeBase64Bytes(base64: string): Uint8Array;
+/** Encode a string or binary data to URL-safe Base64 */
+export declare function encodeBase64Url(input: PossibleBytes, pad?: boolean): string;
 /** Decode a string from URL-safe Base64. */
-export declare function base64UrlDecode(b64: string): string;
+export declare function decodeBase64UrlString(base64: string): string;
+/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
+export declare function decodeBase64UrlBytes(base64: string): Uint8Array;

package/util/base64.js

@@ -1,16 +1,77 @@
-/** Encode a string to Base64 (with no `=` padding on the end). */
-export function base64Encode(str) {
-    return btoa(str).replace(/=+$/, "");
+import { requireBytes } from "./bytes.js";
+const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const BASE64URL_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/**
+ * @todo DH: When it's well supported, use `Uint8Array.toBase64()`: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array/toBase64
+ */
+function _encode(bytes, alphabet, pad) {
+    const len = bytes.length;
+    let output = "";
+    for (let i = 0; i < len; i += 3) {
+        const b1 = bytes[i];
+        const b2 = i + 1 < len ? bytes[i + 1] : 0;
+        const b3 = i + 2 < len ? bytes[i + 2] : 0;
+        const combined = (b1 << 16) | (b2 << 8) | b3;
+        const c1 = (combined >> 18) & 0x3f;
+        const c2 = (combined >> 12) & 0x3f;
+        const c3 = (combined >> 6) & 0x3f;
+        const c4 = combined & 0x3f;
+        output += `${alphabet[c1]}${alphabet[c2]}${i + 1 < len ? alphabet[c3] : pad}${i + 2 < len ? alphabet[c4] : pad}`;
+    }
+    return output;
 }
-/** Decode a string from Base64 (strips `=` padding on the end). */
-export function base64Decode(b64) {
-    return atob(b64.replace(/=+$/, ""));
+function _decode(base64, alphabet) {
+    // Create a reverse lookup table: char -> 6-bit value
+    const values = new Uint8Array(128);
+    for (let i = 0; i < alphabet.length; i++)
+        values[alphabet.charCodeAt(i)] = i;
+    // Remove padding.
+    const cleaned = base64.replace(/=+$/, "");
+    const length = cleaned.length;
+    // Calculate output byte length
+    // Every 4 base64 chars = 3 bytes; adjust for padding
+    const outputLength = Math.floor((length * 6) / 8);
+    const output = new Uint8Array(outputLength);
+    let j = 0;
+    for (let i = 0; i < length; i += 4) {
+        // Get 4 characters (or less at the end)
+        const c1 = values[cleaned.charCodeAt(i)];
+        const c2 = values[cleaned.charCodeAt(i + 1)];
+        const c3 = i + 2 < length ? values[cleaned.charCodeAt(i + 2)] : 0;
+        const c4 = i + 3 < length ? values[cleaned.charCodeAt(i + 3)] : 0;
+        // Combine into 24 bits
+        const combined = (c1 << 18) | (c2 << 12) | (c3 << 6) | c4;
+        // Extract bytes and add to output if within range
+        if (j < outputLength)
+            output[j++] = (combined >> 16) & 0xff;
+        if (j < outputLength)
+            output[j++] = (combined >> 8) & 0xff;
+        if (j < outputLength)
+            output[j++] = combined & 0xff;
+    }
+    return output;
 }
-/** Encode a string to URL-safe Base64 */
-export function base64UrlEncode(str) {
-    return base64Encode(str).replace(/\+/g, "-").replace(/\//g, "_");
+/** Encode a string or binary data to Base64 string. */
+export function encodeBase64(input, pad = true) {
+    return _encode(requireBytes(input), BASE64_CHARS, pad ? "=" : "");
+}
+/** Decode Base64 string to string. */
+export function decodeBase64String(base64) {
+    return new TextDecoder("utf-8").decode(_decode(base64, BASE64_CHARS));
+}
+/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
+export function decodeBase64Bytes(base64) {
+    return _decode(base64, BASE64_CHARS);
+}
+/** Encode a string or binary data to URL-safe Base64 */
+export function encodeBase64Url(input, pad = false) {
+    return _encode(requireBytes(input), BASE64URL_CHARS, pad ? "=" : "");
 }
 /** Decode a string from URL-safe Base64. */
-export function base64UrlDecode(b64) {
-    return base64Decode(b64.replace(/-/g, "+").replace(/_/g, "/"));
+export function decodeBase64UrlString(base64) {
+    return new TextDecoder("utf-8").decode(_decode(base64, BASE64URL_CHARS));
+}
+/** Decode URL-safe Base64 string to binary data (as a UInt8Array). */
+export function decodeBase64UrlBytes(base64) {
+    return _decode(base64, BASE64URL_CHARS);
 }

package/util/buffer.d.ts

@@ -0,0 +1,7 @@
+export type TypedArray<T extends ArrayBufferLike = ArrayBufferLike> = Uint8Array<T> | Uint16Array<T> | Uint32Array<T> | Int8Array<T> | Int16Array<T> | Int32Array<T> | Float32Array<T> | Float64Array<T>;
+/** Detect if an unknown value is an `ArrayBuffer` (not a view like `Uint8Array` or `Float32Array` or `DataView`). */
+export declare function isBuffer(value: unknown): value is ArrayBuffer;
+/** Detect if an unknown value is an `ArrayBufferView`, like `Uint8Array` or `Float32Array` or `DataView` */
+export declare function isBufferView(value: unknown): value is ArrayBufferView;
+/** Detect if an unknown value is a `TypedArray`, like `Uint8Array` or `Float32Array` (not including `DataView`). */
+export declare function isTypedArray(value: unknown): value is TypedArray;

package/util/buffer.js

@@ -0,0 +1,12 @@
+/** Detect if an unknown value is an `ArrayBuffer` (not a view like `Uint8Array` or `Float32Array` or `DataView`). */
+export function isBuffer(value) {
+    return value instanceof ArrayBuffer;
+}
+/** Detect if an unknown value is an `ArrayBufferView`, like `Uint8Array` or `Float32Array` or `DataView` */
+export function isBufferView(value) {
+    return ArrayBuffer.isView(value);
+}
+/** Detect if an unknown value is a `TypedArray`, like `Uint8Array` or `Float32Array` (not including `DataView`). */
+export function isTypedArray(value) {
+    return value instanceof Object.getPrototypeOf(Uint8Array);
+}

package/util/bytes.d.ts

@@ -0,0 +1,12 @@
+/** Types that can be converted to a `Uint8Array` byte sequence. */
+export type PossibleBytes = Uint8Array | ArrayBuffer | string;
+/**
+ * Convert an unknown value to a `Uint8Array` byte sequence, or `undefined` if the value cannot be converted.
+ *
+ * - ArrayBuffers and TypedArrays are converted to `Uint8Array`
+ * - Strings are encoded as UTF-8.
+ * - Everything else returns `undefined`
+ */
+export declare function getBytes(value: unknown): Uint8Array | undefined;
+/** Convert an unknown value to a `Uint8Array` byte sequence, or throw `RequiredError` if the value cannot be converted. */
+export declare function requireBytes(value: PossibleBytes): Uint8Array;

package/util/bytes.js

@@ -0,0 +1,24 @@
+import { RequiredError } from "../error/RequiredError.js";
+/**
+ * Convert an unknown value to a `Uint8Array` byte sequence, or `undefined` if the value cannot be converted.
+ *
+ * - ArrayBuffers and TypedArrays are converted to `Uint8Array`
+ * - Strings are encoded as UTF-8.
+ * - Everything else returns `undefined`
+ */
+export function getBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (typeof value === "string")
+        return new TextEncoder().encode(value);
+    return undefined;
+}
+/** Convert an unknown value to a `Uint8Array` byte sequence, or throw `RequiredError` if the value cannot be converted. */
+export function requireBytes(value) {
+    const bytes = getBytes(value);
+    if (bytes === undefined)
+        throw new RequiredError("Value cannot be converted to byte array", { received: value, caller: requireBytes });
+    return bytes;
+}

package/util/index.d.ts

@@ -2,6 +2,8 @@ export * from "./array.js";
 export * from "./async.js";
 export * from "./base64.js";
 export * from "./boolean.js";
+export * from "./buffer.js";
+export * from "./bytes.js";
 export * from "./callback.js";
 export * from "./class.js";
 export * from "./color.js";
@@ -25,6 +27,7 @@ export * from "./hydrate.js";
 export * from "./item.js";
 export * from "./iterate.js";
 export * from "./jsx.js";
+export * from "./jwt.js";
 export * from "./lazy.js";
 export * from "./link.js";
 export * from "./map.js";

package/util/index.js

@@ -2,6 +2,8 @@ export * from "./array.js";
 export * from "./async.js";
 export * from "./base64.js";
 export * from "./boolean.js";
+export * from "./buffer.js";
+export * from "./bytes.js";
 export * from "./callback.js";
 export * from "./class.js";
 export * from "./color.js";
@@ -25,6 +27,7 @@ export * from "./hydrate.js";
 export * from "./item.js";
 export * from "./iterate.js";
 export * from "./jsx.js";
+export * from "./jwt.js";
 export * from "./lazy.js";
 export * from "./link.js";
 export * from "./map.js";

package/util/jwt.d.ts

@@ -0,0 +1,31 @@
+import type { Data } from "./data.js";
+import type { AnyFunction } from "./function.js";
+/**
+ * Encode a JWT and return the string token.
+ * - Currently only supports HMAC SHA-512 signing.
+ *
+ * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
+ */
+export declare function encodeToken(claims: Data, secret: string): Promise<string>;
+/** Parts that make up a JSON Web Token. */
+export type TokenData = {
+    header: string;
+    payload: string;
+    signature: string;
+    headerData: Data;
+    payloadData: Data;
+};
+/**
+ * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
+ */
+export declare function splitToken(token: unknown): TokenData;
+export declare function _splitToken(caller: AnyFunction, token: unknown): TokenData;
+/**
+ * Decode a JWT, verify it, and return the full payload data.
+ * - Currently only supports HMAC SHA-512 signing.
+ *
+ * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
+ * @throws RequestError If the token is invalid or malformed.
+ * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
+ */
+export declare function verifyToken(token: unknown, secret: string): Promise<Data>;

package/util/jwt.js

@@ -0,0 +1,101 @@
+import { RequestError, UnauthorizedError } from "../error/RequestError.js";
+import { ValueError } from "../error/ValueError.js";
+import { decodeBase64UrlBytes, decodeBase64UrlString, encodeBase64Url } from "./base64.js";
+import { requireBytes } from "./bytes.js";
+import { DAY } from "./constants.js";
+// Constants.
+const TOKEN_HEADER = { alg: "HS512", typ: "JWT" };
+const TOKEN_EXPIRY_MS = DAY * 10;
+const TOKEN_MINIMUM_SECRET = 16;
+function _getKey(secret, ...usages) {
+    return crypto.subtle.importKey("raw", requireBytes(secret), { name: "HMAC", hash: { name: "SHA-512" } }, false, usages);
+}
+/**
+ * Encode a JWT and return the string token.
+ * - Currently only supports HMAC SHA-512 signing.
+ *
+ * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
+ */
+export async function encodeToken(claims, secret) {
+    if (typeof secret !== "string" || secret.length < TOKEN_MINIMUM_SECRET)
+        throw new ValueError(`JWT secret must be string with minimum ${TOKEN_MINIMUM_SECRET} characters`, {
+            received: secret,
+            caller: encodeToken,
+        });
+    // Encode header.
+    const header = encodeBase64Url(JSON.stringify(TOKEN_HEADER));
+    // Encode payload.
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = Math.floor(iat + TOKEN_EXPIRY_MS / 1000);
+    const payload = encodeBase64Url(JSON.stringify({ iat, exp, ...claims }));
+    // Create signature.
+    const key = await _getKey(secret, "sign");
+    const signature = encodeBase64Url(await crypto.subtle.sign("HMAC", key, requireBytes(`${header}.${payload}`)));
+    // Combine token.
+    return `${header}.${payload}.${signature}`;
+}
+/**
+ * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
+ */
+export function splitToken(token) {
+    return _splitToken(splitToken, token);
+}
+export function _splitToken(caller, token) {
+    if (typeof token !== "string")
+        throw new RequestError("JWT token must be string", { received: token, caller });
+    // Split token.
+    const [header, payload, signature] = token.split(".");
+    if (!header || !payload || !signature)
+        throw new RequestError("JWT token must have header, payload, and signature", { received: token, caller });
+    // Decode header.
+    let headerData;
+    try {
+        headerData = JSON.parse(decodeBase64UrlString(header));
+    }
+    catch {
+        throw new RequestError("JWT token header must be base64Url encoded JSON", { received: token, caller });
+    }
+    // Decode payload.
+    let payloadData;
+    try {
+        payloadData = JSON.parse(decodeBase64UrlString(payload));
+    }
+    catch {
+        throw new RequestError("JWT token payload must be base64Url encoded JSON", { received: token, caller });
+    }
+    return { header, payload, headerData, payloadData, signature };
+}
+/**
+ * Decode a JWT, verify it, and return the full payload data.
+ * - Currently only supports HMAC SHA-512 signing.
+ *
+ * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
+ * @throws RequestError If the token is invalid or malformed.
+ * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
+ */
+export async function verifyToken(token, secret) {
+    if (typeof secret !== "string" || secret.length < TOKEN_MINIMUM_SECRET)
+        throw new ValueError(`JWT secret must be string with minimum ${TOKEN_MINIMUM_SECRET} characters`, {
+            received: secret,
+            caller: verifyToken,
+        });
+    const { header, payload, signature, headerData, payloadData } = _splitToken(verifyToken, token);
+    // Validate header.
+    if (headerData.typ !== TOKEN_HEADER.typ)
+        throw new RequestError(`JWT header type must be \"${TOKEN_HEADER.typ}\"`, { received: headerData.typ, caller: verifyToken });
+    if (headerData.alg !== TOKEN_HEADER.alg)
+        throw new RequestError(`JWT header algorithm must be \"${TOKEN_HEADER.alg}\"`, { received: headerData.alg, caller: verifyToken });
+    // Validate signature.
+    const key = await _getKey(secret, "verify");
+    const isValid = await crypto.subtle.verify("HMAC", key, decodeBase64UrlBytes(signature), requireBytes(`${header}.${payload}`));
+    if (!isValid)
+        throw new UnauthorizedError("JWT signature does not match", { received: token, caller: verifyToken });
+    // Validate payload.
+    const { iat, exp } = payloadData;
+    const now = Math.floor(Date.now() / 1000);
+    if (typeof iat === "number" && iat > now)
+        throw new UnauthorizedError("JWT not issued yet", { received: iat, caller: verifyToken });
+    if (typeof exp === "number" && exp < now)
+        throw new UnauthorizedError("JWT has expired", { received: exp, caller: verifyToken });
+    return payloadData;
+}

package/util/validate.d.ts

@@ -29,7 +29,7 @@ export type ValidatorsType<T> = {
     readonly [K in keyof T]: ValidatorType<T[K]>;
 };
 /** Get value that validates against a given `Validator`, or throw `ValueError` */
-export declare function getValid<T>(unsafeValue: unknown, validator: Validator<T>, ErrorConstructor?: Constructor<BaseError, [string, BaseErrorOptions]>): T;
+export declare function getValid<T>(value: unknown, validator: Validator<T>, ErrorConstructor?: Constructor<BaseError, [string, BaseErrorOptions]>): T;
 /**
  * Validate an iterable set of items with a validator.
  *

package/util/validate.js

@@ -9,13 +9,13 @@ import { isIterable } from "./iterate.js";
 import { getNull } from "./null.js";
 import { getUndefined } from "./undefined.js";
 /** Get value that validates against a given `Validator`, or throw `ValueError` */
-export function getValid(unsafeValue, validator, ErrorConstructor = ValueError) {
+export function getValid(value, validator, ErrorConstructor = ValueError) {
     try {
-        return validator.validate(unsafeValue);
+        return validator.validate(value);
     }
     catch (thrown) {
         if (thrown instanceof Feedback)
-            throw new ErrorConstructor("Invalid value", { cause: thrown, caller: getValid });
+            throw new ErrorConstructor(thrown.message, { received: value, cause: thrown, caller: getValid });
         throw thrown;
     }
 }