@noble/post-quantum 0.6.0 → 0.7.0

package/utils.d.ts

@@ -4,6 +4,46 @@
  */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
 import { type CHash, type TypedArray, abytes, concatBytes, randomBytes as randb } from '@noble/hashes/utils.js';
+/**
+ * Bytes API type helpers for old + new TypeScript.
+ *
+ * TS 5.6 has `Uint8Array`, while TS 5.9+ made it generic `Uint8Array<ArrayBuffer>`.
+ * We can't use specific return type, because TS 5.6 will error.
+ * We can't use generic return type, because most TS 5.9 software will expect specific type.
+ *
+ * Maps typed-array input leaves to broad forms.
+ * These are compatibility adapters, not ownership guarantees.
+ *
+ * - `TArg` keeps byte inputs broad.
+ * - `TRet` marks byte outputs for TS 5.6 and TS 5.9+ compatibility.
+ */
+export type TypedArg<T> = T extends BigInt64Array ? BigInt64Array : T extends BigUint64Array ? BigUint64Array : T extends Float32Array ? Float32Array : T extends Float64Array ? Float64Array : T extends Int16Array ? Int16Array : T extends Int32Array ? Int32Array : T extends Int8Array ? Int8Array : T extends Uint16Array ? Uint16Array : T extends Uint32Array ? Uint32Array : T extends Uint8ClampedArray ? Uint8ClampedArray : T extends Uint8Array ? Uint8Array : never;
+/** Maps typed-array output leaves to narrow TS-compatible forms. */
+export type TypedRet<T> = T extends BigInt64Array ? ReturnType<typeof BigInt64Array.of> : T extends BigUint64Array ? ReturnType<typeof BigUint64Array.of> : T extends Float32Array ? ReturnType<typeof Float32Array.of> : T extends Float64Array ? ReturnType<typeof Float64Array.of> : T extends Int16Array ? ReturnType<typeof Int16Array.of> : T extends Int32Array ? ReturnType<typeof Int32Array.of> : T extends Int8Array ? ReturnType<typeof Int8Array.of> : T extends Uint16Array ? ReturnType<typeof Uint16Array.of> : T extends Uint32Array ? ReturnType<typeof Uint32Array.of> : T extends Uint8ClampedArray ? ReturnType<typeof Uint8ClampedArray.of> : T extends Uint8Array ? ReturnType<typeof Uint8Array.of> : never;
+/** Recursively adapts byte-carrying API input types. See {@link TypedArg}. */
+export type TArg<T> = T | ([TypedArg<T>] extends [never] ? T extends (...args: infer A) => infer R ? ((...args: {
+    [K in keyof A]: TRet<A[K]>;
+}) => TArg<R>) & {
+    [K in keyof T]: T[K] extends (...args: any) => any ? T[K] : TArg<T[K]>;
+} : T extends [infer A, ...infer R] ? [TArg<A>, ...{
+    [K in keyof R]: TArg<R[K]>;
+}] : T extends readonly [infer A, ...infer R] ? readonly [TArg<A>, ...{
+    [K in keyof R]: TArg<R[K]>;
+}] : T extends (infer A)[] ? TArg<A>[] : T extends readonly (infer A)[] ? readonly TArg<A>[] : T extends Promise<infer A> ? Promise<TArg<A>> : T extends object ? {
+    [K in keyof T]: TArg<T[K]>;
+} : T : TypedArg<T>);
+/** Recursively adapts byte-carrying API output types. See {@link TypedArg}. */
+export type TRet<T> = T extends unknown ? T & ([TypedRet<T>] extends [never] ? T extends (...args: infer A) => infer R ? ((...args: {
+    [K in keyof A]: TArg<A[K]>;
+}) => TRet<R>) & {
+    [K in keyof T]: T[K] extends (...args: any) => any ? T[K] : TRet<T[K]>;
+} : T extends [infer A, ...infer R] ? [TRet<A>, ...{
+    [K in keyof R]: TRet<R[K]>;
+}] : T extends readonly [infer A, ...infer R] ? readonly [TRet<A>, ...{
+    [K in keyof R]: TRet<R[K]>;
+}] : T extends (infer A)[] ? TRet<A>[] : T extends readonly (infer A)[] ? readonly TRet<A>[] : T extends Promise<infer A> ? Promise<TRet<A>> : T extends object ? {
+    [K in keyof T]: TRet<T[K]>;
+} : T : TypedRet<T>) : never;
 /**
  * Asserts that a value is a byte array and optionally checks its length.
  * Returns the original reference unchanged on success, and currently also accepts Node `Buffer`
@@ -35,6 +75,8 @@ export { concatBytesDoc as concatBytes };
  * Requires `globalThis.crypto.getRandomValues` and throws if that API is unavailable.
  * `bytesLength` is validated by the upstream helper as a non-negative integer before allocation,
  * so negative and fractional values both throw instead of truncating through JS `ToIndex`.
+ * @param bytesLength - Number of random bytes to generate.
+ * @returns Fresh random bytes.
  * @example
  * Generate a fresh random seed.
  * ```ts
@@ -42,9 +84,11 @@ export { concatBytesDoc as concatBytes };
  * ```
  */
 export declare const randomBytes: typeof randb;
+export declare function aarray<T>(item: unknown, title: string, inner?: (elm: T, title: string) => void): T[];
+export declare function aobject<T extends object>(value: unknown, title?: string): T;
 /**
  * Compares two byte arrays in a length-constant way for equal lengths.
- * Unequal lengths return `false` immediately, and there is no runtime type validation.
+ * Inputs are validated as byte arrays; unequal lengths return `false` immediately.
  * @param a - First byte array.
  * @param b - Second byte array.
  * @returns Whether both arrays contain the same bytes.
@@ -54,11 +98,10 @@ export declare const randomBytes: typeof randb;
  * equalBytes(new Uint8Array([1]), new Uint8Array([1]));
  * ```
  */
-export declare function equalBytes(a: Uint8Array, b: Uint8Array): boolean;
+export declare function equalBytes(a: TArg<Uint8Array>, b: TArg<Uint8Array>): boolean;
 /**
  * Copies bytes into a fresh `Uint8Array`.
- * Returns a detached plain `Uint8Array`, and currently accepts broader array-like / iterable
- * inputs because it delegates directly to `Uint8Array.from(...)`.
+ * Returns a detached plain `Uint8Array` after validating that the input is real bytes.
  * @param bytes - Source bytes.
  * @returns Copy of the input bytes.
  * @example
@@ -67,15 +110,32 @@ export declare function equalBytes(a: Uint8Array, b: Uint8Array): boolean;
  * copyBytes(new Uint8Array([1, 2]));
  * ```
  */
-export declare function copyBytes(bytes: Uint8Array): Uint8Array;
+export declare function copyBytes(bytes: TArg<Uint8Array>): TRet<Uint8Array>;
 /**
  * Byte-swaps each 64-bit lane in place.
  * Falcon's exact binary64 tables are stored as little-endian byte payloads, so BE runtimes need
  * this boundary helper before aliasing them as host `Float64Array` lanes.
  * @param arr - Byte buffer whose length is a multiple of 8.
  * @returns The same buffer after in-place 64-bit lane byte swaps.
+ * @example
+ * Byte-swap one 64-bit lane in place.
+ * ```ts
+ * byteSwap64(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]));
+ * ```
  */
 export declare function byteSwap64<T extends ArrayBufferView>(arr: T): T;
+/**
+ * Byte-swaps 64-bit lanes on big-endian runtimes and returns the input unchanged on little-endian.
+ * This keeps Falcon's binary64 tables in canonical little-endian order before aliasing them as
+ * `Float64Array` lanes on the current host.
+ * @param arr - Buffer to pass through or swap in place.
+ * @returns The same buffer, normalized for Falcon's little-endian table layout.
+ * @example
+ * Normalize one host-endian buffer for Falcon's float tables.
+ * ```ts
+ * baswap64If(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]));
+ * ```
+ */
 export declare const baswap64If: <T extends ArrayBufferView>(arr: T) => T;
 /** Shared key-generation surface for signers and KEMs. */
 export type CryptoKeys = {
@@ -94,16 +154,16 @@ export type CryptoKeys = {
      * @param seed - Optional seed bytes for deterministic key generation.
      * @returns Fresh secret/public keypair.
      */
-    keygen: (seed?: Uint8Array) => {
-        secretKey: Uint8Array;
-        publicKey: Uint8Array;
+    keygen: (seed?: TArg<Uint8Array>) => {
+        secretKey: TRet<Uint8Array>;
+        publicKey: TRet<Uint8Array>;
     };
     /**
      * Derive one public key from a secret key.
      * @param secretKey - Secret key bytes.
      * @returns Public key bytes.
      */
-    getPublicKey: (secretKey: Uint8Array) => Uint8Array;
+    getPublicKey: (secretKey: TArg<Uint8Array>) => TRet<Uint8Array>;
 };
 /** Verification options shared by the signature APIs. */
 export type VerOpts = {
@@ -138,7 +198,7 @@ export declare function validateOpts(opts: object): void;
  * validateVerOpts({ context: new Uint8Array([1]) });
  * ```
  */
-export declare function validateVerOpts(opts: VerOpts): void;
+export declare function validateVerOpts(opts: TArg<VerOpts>): void;
 /**
  * Validates common signing options.
  * `extraEntropy` is validated with `abytes(...)`; exact lengths and extra algorithm-specific
@@ -151,7 +211,7 @@ export declare function validateVerOpts(opts: VerOpts): void;
  * validateSigOpts({ extraEntropy: new Uint8Array([1]) });
  * ```
  */
-export declare function validateSigOpts(opts: SigOpts): void;
+export declare function validateSigOpts(opts: TArg<SigOpts>): void;
 /** Generic signature interface with key generation, signing, and verification. */
 export type Signer = CryptoKeys & {
     /** Public byte lengths for signatures and signing randomness. */
@@ -166,7 +226,7 @@ export type Signer = CryptoKeys & {
      * @param opts - Optional signing options.
      * @returns Signature bytes.
      */
-    sign: (msg: Uint8Array, secretKey: Uint8Array, opts?: SigOpts) => Uint8Array;
+    sign: (msg: TArg<Uint8Array>, secretKey: TArg<Uint8Array>, opts?: TArg<SigOpts>) => TRet<Uint8Array>;
     /**
      * Verify one signature.
      * @param sig - Signature bytes.
@@ -178,7 +238,7 @@ export type Signer = CryptoKeys & {
      * a verification failure and return `false`.
      * @throws On malformed API arguments or unsupported verification options.
      */
-    verify: (sig: Uint8Array, msg: Uint8Array, publicKey: Uint8Array, opts?: VerOpts) => boolean;
+    verify: (sig: TArg<Uint8Array>, msg: TArg<Uint8Array>, publicKey: TArg<Uint8Array>, opts?: TArg<VerOpts>) => boolean;
 };
 /** Generic key encapsulation mechanism interface. */
 export type KEM = CryptoKeys & {
@@ -194,9 +254,9 @@ export type KEM = CryptoKeys & {
      * @param msg - Optional caller-provided randomness/message seed.
      * @returns Ciphertext plus shared secret.
      */
-    encapsulate: (publicKey: Uint8Array, msg?: Uint8Array) => {
-        cipherText: Uint8Array;
-        sharedSecret: Uint8Array;
+    encapsulate: (publicKey: TArg<Uint8Array>, msg?: TArg<Uint8Array>) => {
+        cipherText: TRet<Uint8Array>;
+        sharedSecret: TRet<Uint8Array>;
     };
     /**
      * Recover the shared secret from a ciphertext and recipient secret key.
@@ -204,7 +264,7 @@ export type KEM = CryptoKeys & {
      * @param secretKey - Recipient secret key bytes.
      * @returns Decapsulated shared secret.
      */
-    decapsulate: (cipherText: Uint8Array, secretKey: Uint8Array) => Uint8Array;
+    decapsulate: (cipherText: TArg<Uint8Array>, secretKey: TArg<Uint8Array>) => TRet<Uint8Array>;
 };
 /** Bidirectional encoder/decoder interface. */
 export interface Coder<F, T> {
@@ -259,9 +319,9 @@ type SplitOut<T extends (number | BytesCoderLen<any>)[]> = {
  * splitCoder('demo', 1, 2).encode([new Uint8Array([1]), new Uint8Array([2, 3])]);
  * ```
  */
-export declare function splitCoder<T extends (number | BytesCoderLen<any>)[]>(label: string, ...lengths: T): BytesCoder<SplitOut<T>> & {
+export declare function splitCoder<T extends (number | BytesCoderLen<any>)[]>(label: string, ...lengths: T): TRet<BytesCoder<SplitOut<T>> & {
     bytesLen: number;
-};
+}>;
 /**
  * Builds a fixed-length vector coder from another fixed-length coder.
  * Element decoding receives `subarray(...)` views, so aliasing depends on the element coder.
@@ -281,7 +341,7 @@ export declare function splitCoder<T extends (number | BytesCoderLen<any>)[]>(la
  * ).encode([1, 2]);
  * ```
  */
-export declare function vecCoder<T>(c: BytesCoderLen<T>, vecLen: number): BytesCoderLen<T[]>;
+export declare function vecCoder<T>(c: TArg<BytesCoderLen<T>>, vecLen: number): TRet<BytesCoderLen<T[]>>;
 /**
  * Overwrites supported typed-array inputs with zeroes in place.
  * Accepts direct typed arrays and one-level arrays of them.
@@ -298,6 +358,8 @@ export declare function cleanBytes(...list: (TypedArray | TypedArray[])[]): void
  * Creates a 32-bit mask with the lowest `bits` bits set.
  * @param bits - Number of low bits to keep.
  * @returns Bit mask with `bits` ones.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
  * @example
  * Create a low-bit mask for packed-field operations.
  * ```ts
@@ -306,7 +368,7 @@ export declare function cleanBytes(...list: (TypedArray | TypedArray[])[]): void
  */
 export declare function getMask(bits: number): number;
 /** Shared empty byte array used as the default context. */
-export declare const EMPTY: Uint8Array;
+export declare const EMPTY: TRet<Uint8Array>;
 /**
  * Builds the domain-separated message payload for the pure sign/verify paths.
  * Context length `255` is valid; only `ctx.length > 255` is rejected.
@@ -320,7 +382,7 @@ export declare const EMPTY: Uint8Array;
  * const payload = getMessage(new Uint8Array([1, 2]));
  * ```
  */
-export declare function getMessage(msg: Uint8Array, ctx?: Uint8Array): Uint8Array;
+export declare function getMessage(msg: TArg<Uint8Array>, ctx?: TArg<Uint8Array>): TRet<Uint8Array>;
 /**
  * Validates that a hash exposes a NIST hash OID and enough collision resistance.
  * Current accepted surface is broader than the FIPS algorithm tables: any hash/XOF under the NIST
@@ -357,5 +419,18 @@ export declare function checkHash(hash: CHash, requiredStrength?: number): void;
  * getMessagePrehash(sha256, new Uint8Array([1, 2]));
  * ```
  */
-export declare function getMessagePrehash(hash: CHash, msg: Uint8Array, ctx?: Uint8Array): Uint8Array;
-//# sourceMappingURL=utils.d.ts.map
+export declare function getMessagePrehash(hash: CHash, msg: TArg<Uint8Array>, ctx?: TArg<Uint8Array>): TRet<Uint8Array>;
+/**
+ * Asserts something is a string.
+ * @param value - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The validated string.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a label string.
+ *
+ * ```ts
+ * astring('example', 'label');
+ * ```
+ */
+export declare function astring(value: unknown, title?: string): string;

package/utils.js

@@ -3,7 +3,7 @@
  * @module
  */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
-import { abytes, abytes as abytes_, concatBytes, isLE, randomBytes as randb, } from '@noble/hashes/utils.js';
+import { abytes, abytes as abytes_, ahash as ahash_, anumber, concatBytes, isBytes, isLE, randomBytes as randb, } from '@noble/hashes/utils.js';
 /**
  * Asserts that a value is a byte array and optionally checks its length.
  * Returns the original reference unchanged on success, and currently also accepts Node `Buffer`
@@ -35,6 +35,8 @@ export { concatBytesDoc as concatBytes };
  * Requires `globalThis.crypto.getRandomValues` and throws if that API is unavailable.
  * `bytesLength` is validated by the upstream helper as a non-negative integer before allocation,
  * so negative and fractional values both throw instead of truncating through JS `ToIndex`.
+ * @param bytesLength - Number of random bytes to generate.
+ * @returns Fresh random bytes.
  * @example
  * Generate a fresh random seed.
  * ```ts
@@ -42,9 +44,23 @@ export { concatBytesDoc as concatBytes };
  * ```
  */
 export const randomBytes = randb;
+export function aarray(item, title, inner = () => { }) {
+    if (!Array.isArray(item))
+        throw new TypeError(`"${title}" expected array, got type=${typeof item}`);
+    for (let i = 0; i < item.length; i++)
+        inner(item[i], `${title}[${i}]`);
+    return item;
+}
+export function aobject(value, title = 'object') {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError(title === 'object'
+            ? 'expected valid options object'
+            : `"${title}" expected object, got type=${typeof value}`);
+    return value;
+}
 /**
  * Compares two byte arrays in a length-constant way for equal lengths.
- * Unequal lengths return `false` immediately, and there is no runtime type validation.
+ * Inputs are validated as byte arrays; unequal lengths return `false` immediately.
  * @param a - First byte array.
  * @param b - Second byte array.
  * @returns Whether both arrays contain the same bytes.
@@ -55,6 +71,8 @@ export const randomBytes = randb;
  * ```
  */
 export function equalBytes(a, b) {
+    a = abytes(a);
+    b = abytes(b);
     if (a.length !== b.length)
         return false;
     let diff = 0;
@@ -64,8 +82,7 @@ export function equalBytes(a, b) {
 }
 /**
  * Copies bytes into a fresh `Uint8Array`.
- * Returns a detached plain `Uint8Array`, and currently accepts broader array-like / iterable
- * inputs because it delegates directly to `Uint8Array.from(...)`.
+ * Returns a detached plain `Uint8Array` after validating that the input is real bytes.
  * @param bytes - Source bytes.
  * @returns Copy of the input bytes.
  * @example
@@ -75,7 +92,9 @@ export function equalBytes(a, b) {
  * ```
  */
 export function copyBytes(bytes) {
-    return Uint8Array.from(bytes);
+    // `Uint8Array.from(...)` would also accept arrays / other typed arrays. Keep this helper strict
+    // because callers use it at byte-validation boundaries before mutating the detached copy.
+    return Uint8Array.from(abytes(bytes));
 }
 /**
  * Byte-swaps each 64-bit lane in place.
@@ -83,6 +102,11 @@ export function copyBytes(bytes) {
  * this boundary helper before aliasing them as host `Float64Array` lanes.
  * @param arr - Byte buffer whose length is a multiple of 8.
  * @returns The same buffer after in-place 64-bit lane byte swaps.
+ * @example
+ * Byte-swap one 64-bit lane in place.
+ * ```ts
+ * byteSwap64(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]));
+ * ```
  */
 export function byteSwap64(arr) {
     const bytes = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
@@ -102,6 +126,18 @@ export function byteSwap64(arr) {
     }
     return arr;
 }
+/**
+ * Byte-swaps 64-bit lanes on big-endian runtimes and returns the input unchanged on little-endian.
+ * This keeps Falcon's binary64 tables in canonical little-endian order before aliasing them as
+ * `Float64Array` lanes on the current host.
+ * @param arr - Buffer to pass through or swap in place.
+ * @returns The same buffer, normalized for Falcon's little-endian table layout.
+ * @example
+ * Normalize one host-endian buffer for Falcon's float tables.
+ * ```ts
+ * baswap64If(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]));
+ * ```
+ */
 export const baswap64If = isLE
     ? (arr) => arr
     : byteSwap64;
@@ -117,8 +153,9 @@ export const baswap64If = isLE
  */
 export function validateOpts(opts) {
     // Arrays silently passed here before, but these call sites expect named option-bag fields.
-    if (Object.prototype.toString.call(opts) !== '[object Object]')
-        throw new TypeError('expected valid options object');
+    if (isBytes(opts))
+        throw new TypeError('"opts" expected object, got Uint8Array');
+    aobject(opts, 'opts');
 }
 /**
  * Validates common verification options.
@@ -170,7 +207,7 @@ export function validateSigOpts(opts) {
  * ```
  */
 export function splitCoder(label, ...lengths) {
-    const getLength = (c) => (typeof c === 'number' ? c : c.bytesLen);
+    const getLength = (c) => typeof c === 'number' ? c : c.bytesLen;
     const bytesLen = lengths.reduce((sum, a) => sum + getLength(a), 0);
     return {
         bytesLen,
@@ -222,15 +259,17 @@ export function splitCoder(label, ...lengths) {
  * ```
  */
 export function vecCoder(c, vecLen) {
-    const bytesLen = vecLen * c.bytesLen;
+    const coder = c;
+    const bytesLen = vecLen * coder.bytesLen;
     return {
         bytesLen,
         encode: (u) => {
-            if (u.length !== vecLen)
-                throw new RangeError(`vecCoder.encode: wrong length=${u.length}. Expected: ${vecLen}`);
+            const uArr = aarray(u, 'u');
+            if (uArr.length !== vecLen)
+                throw new RangeError(`vecCoder.encode: wrong length=${uArr.length}. Expected: ${vecLen}`);
             const res = new Uint8Array(bytesLen);
-            for (let i = 0, pos = 0; i < u.length; i++) {
-                const b = c.encode(u[i]);
+            for (let i = 0, pos = 0; i < uArr.length; i++) {
+                const b = coder.encode(uArr[i]);
                 res.set(b, pos);
                 b.fill(0); // clean
                 pos += b.length;
@@ -240,8 +279,8 @@ export function vecCoder(c, vecLen) {
         decode: (a) => {
             abytes_(a, bytesLen);
             const r = [];
-            for (let i = 0; i < a.length; i += c.bytesLen)
-                r.push(c.decode(a.subarray(i, i + c.bytesLen)));
+            for (let i = 0; i < a.length; i += coder.bytesLen)
+                r.push(coder.decode(a.subarray(i, i + coder.bytesLen)));
             return r;
         },
     };
@@ -270,6 +309,8 @@ export function cleanBytes(...list) {
  * Creates a 32-bit mask with the lowest `bits` bits set.
  * @param bits - Number of low bits to keep.
  * @returns Bit mask with `bits` ones.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
  * @example
  * Create a low-bit mask for packed-field operations.
  * ```ts
@@ -277,8 +318,9 @@ export function cleanBytes(...list) {
  * ```
  */
 export function getMask(bits) {
-    if (!Number.isSafeInteger(bits) || bits < 0 || bits > 32)
-        throw new RangeError(`expected bits in [0..32], got ${bits}`);
+    anumber(bits, 'bits');
+    if (bits > 32)
+        throw new RangeError('"bits" expected <= 32, got ' + bits);
     // JS shifts are modulo 32, so bit 32 needs an explicit full-width mask.
     return bits === 32 ? 0xffffffff : ~(-1 << bits) >>> 0;
 }
@@ -298,8 +340,8 @@ export const EMPTY = /* @__PURE__ */ Uint8Array.of();
  * ```
  */
 export function getMessage(msg, ctx = EMPTY) {
-    abytes_(msg);
-    abytes_(ctx);
+    abytes_(msg, undefined, 'msg');
+    abytes_(ctx, undefined, 'ctx');
     if (ctx.length > 255)
         throw new RangeError('context should be 255 bytes or less');
     return concatBytes(new Uint8Array([0, ctx.length]), ctx, msg);
@@ -327,8 +369,14 @@ const oidNistP = /* @__PURE__ */ Uint8Array.from([6, 9, 0x60, 0x86, 0x48, 1, 0x6
  * ```
  */
 export function checkHash(hash, requiredStrength = 0) {
-    if (!hash.oid || !equalBytes(hash.oid.subarray(0, 10), oidNistP))
-        throw new Error('hash.oid is invalid: expected NIST hash');
+    if (typeof hash !== 'function' || typeof hash.create !== 'function')
+        throw new TypeError('"hash" expected hash function, got type=' + typeof hash);
+    ahash_(hash);
+    anumber(requiredStrength, 'requiredStrength');
+    const oid = hash.oid;
+    abytes_(oid, undefined, 'hash.oid');
+    if (!equalBytes(oid.subarray(0, 10), oidNistP))
+        throw new Error('"hash.oid" is invalid: expected NIST hash');
     // FIPS 204 / FIPS 205 require both collision and second-preimage strength; for approved NIST
     // hashes/XOFs under this OID subtree, the collision bound from the configured digest length is
     // the tighter runtime check, so enforce that lower bound here.
@@ -359,11 +407,31 @@ export function checkHash(hash, requiredStrength = 0) {
  * ```
  */
 export function getMessagePrehash(hash, msg, ctx = EMPTY) {
-    abytes_(msg);
-    abytes_(ctx);
+    checkHash(hash);
+    abytes_(msg, undefined, 'msg');
+    abytes_(ctx, undefined, 'ctx');
     if (ctx.length > 255)
         throw new RangeError('context should be 255 bytes or less');
     const hashed = hash(msg);
     return concatBytes(new Uint8Array([1, ctx.length]), ctx, hash.oid, hashed);
 }
-//# sourceMappingURL=utils.js.map
+/**
+ * Asserts something is a string.
+ * @param value - Value to validate.
+ * @param title - Label included in thrown errors.
+ * @returns The validated string.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate a label string.
+ *
+ * ```ts
+ * astring('example', 'label');
+ * ```
+ */
+export function astring(value, title = '') {
+    if (typeof value !== 'string') {
+        const prefix = title && `"${title}" `;
+        throw new TypeError(prefix + 'expected string, got type=' + typeof value);
+    }
+    return value;
+}

package/_crystals.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_crystals.d.ts","sourceRoot":"","sources":["src/_crystals.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,aAAa,EAAc,KAAK,KAAK,EAAW,MAAM,YAAY,CAAC;AAEjF,qEAAqE;AACrE,MAAM,MAAM,GAAG,GAAG,CAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,CAAC,EAAE,MAAM,KACd;IACH;;;OAGG;IACH,KAAK,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;;;;;;OASG;IACH,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,UAAU,CAAC;IAChD,mEAAmE;IACnE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,wCAAwC;AACxC,oEAAoE;AACpE,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,IAAI;IAC9C;;;;OAIG;IACH,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACtB,wCAAwC;IACxC,CAAC,EAAE,MAAM,CAAC;IACV,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAC;IACV;;OAEG;IACH,CAAC,EAAE,MAAM,CAAC;IACV,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,UAAU,IAAI,CAAC,CAAC,EAAE,MAAM,KAAK,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,UAAU,EAC9C,MAAM,WAAW,CAAC,CAAC,CAAC,KACnB;IACD,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C,QAAQ,EAAE,CAAC,CAAC;IACZ,GAAG,EAAE;QACH,2DAA2D;QAC3D,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QACpB,2DAA2D;QAC3D,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;KACrB,CAAC;IACF,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC;CA+FtE,CAAC;AAwCF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,EAAE,GAA8C,CAAC;AACpE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,EAAE,GAA8C,CAAC"}

package/_crystals.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"_crystals.js","sourceRoot":"","sources":["src/_crystals.ts"],"names":[],"mappings":"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"}

package/falcon.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"falcon.d.ts","sourceRoot":"","sources":["src/falcon.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,WAAW,EAKZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAIL,KAAK,UAAU,EAEf,KAAK,MAAM,EACX,KAAK,OAAO,EAKZ,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AA2oCpB,KAAK,aAAa,GAAG,OAAO,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,WAAW,CAAA;CAAE,CAAC;AAC/D,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;IACxC,kEAAkE;IAClE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,UAAU,CAAC;IAC/E;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC1E,CAAC;AACF,uEAAuE;AACvE,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAioCF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,EAAE,MAC2B,CAAC;AACpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,MAKvB,CAAC;AAaR;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,MAIlB,CAAC;AACR;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAKxB,CAAC;AAGR,eAAO,MAAM,OAAO,EAAE,GAYjB,CAAC"}