Update jsbt. Improve error messages and type checks.

paulmillr · paulmillr · commit 20c4a43d8008 · 2026-06-09T15:53:24.000Z
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -5,7 +5,7 @@ on:
 jobs:
   release-js:
     name: jsbt v0.5.1
-    uses: paulmillr/jsbt/.github/workflows/release.yml@d156c5951d47d615d673d039aa03de6b9669449f
+    uses: paulmillr/jsbt/.github/workflows/release.yml@9a270529fbbc31451aee938da7dad227ba87f828
     permissions:
       contents: read
       id-token: write
diff --git a/.github/workflows/test-slow.yml b/.github/workflows/test-slow.yml
@@ -6,6 +6,6 @@ on:
 jobs:
   slow:
     name: Slow large input tests
-    uses: paulmillr/jsbt/.github/workflows/test-custom.yml@231cc389fe2f825b6531285ad8c275584bf76588
+    uses: paulmillr/jsbt/.github/workflows/test-custom.yml@9a270529fbbc31451aee938da7dad227ba87f828
     with:
       npm-task: test:slow
diff --git a/.github/workflows/test-ts.yml b/.github/workflows/test-ts.yml
@@ -5,4 +5,4 @@ on:
 jobs:
   test-ts:
     name: jsbt v0.5.1
-    uses: paulmillr/jsbt/.github/workflows/test.yml@d156c5951d47d615d673d039aa03de6b9669449f
+    uses: paulmillr/jsbt/.github/workflows/test.yml@9a270529fbbc31451aee938da7dad227ba87f828
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -10,7 +10,7 @@
     "*.d.ts.map"
   ],
   "devDependencies": {
-    "@paulmillr/jsbt": "0.5.0",
+    "@paulmillr/jsbt": "0.5.1",
     "@scure/base": "2.0.0",
     "@types/node": "25.3.0",
     "fast-check": "4.2.0",
@@ -22,10 +22,7 @@
     "bench:compare": "cd test/benchmark; npm install; node compare.ts",
     "build": "tsc",
     "build:release": "npx --no @paulmillr/jsbt esbuild test/build",
-    "check": "npm run check:readme && npm run check:treeshake && npm run check:jsdoc",
-    "check:readme": "npx --no @paulmillr/jsbt readme package.json",
-    "check:treeshake": "npx --no @paulmillr/jsbt treeshake package.json test/build/out-treeshake",
-    "check:jsdoc": "npx --no @paulmillr/jsbt tsdoc package.json",
+    "check": "npx --no @paulmillr/jsbt check package.json",
     "build:clean": "rm *.{js,js.map,d.ts,d.ts.map} 2> /dev/null",
     "format": "prettier --write 'src/**/*.{js,ts}' 'test/**/*.{js,ts,mjs}'",
     "test": "node test/index.ts",
diff --git a/src/_arx.ts b/src/_arx.ts
@@ -370,7 +370,7 @@ export class _XorStreamPRG implements PRG {
     this.nonce = this.state.subarray(this.keyLen) as TRet<Uint8Array>;
   }
   private reseed(seed: TArg<Uint8Array>) {
-    abytes(seed);
+    abytes(seed, undefined, 'seed');
     if (!seed || seed.length === 0) throw new Error('entropy required');
     // Mix variable-length entropy cyclically across the whole key||nonce state, then restart the
     // keystream so buffered leftovers from the previous state are never reused.
@@ -380,7 +380,7 @@ export class _XorStreamPRG implements PRG {
   }
   addEntropy(seed: TArg<Uint8Array>): void {
     // Reject empty entropy before re-keying, otherwise a throwing call would still advance state.
-    abytes(seed);
+    abytes(seed, undefined, 'seed');
     if (seed.length === 0) throw new Error('entropy required');
     // Re-key from the current stream first, then mix external entropy into the fresh key||nonce
     // state through reseed() so stale buffered bytes are discarded.
diff --git a/src/aes.ts b/src/aes.ts
@@ -901,7 +901,8 @@ function computeTag(
  * import { randomBytes } from '@noble/ciphers/utils.js';
  * const key = randomBytes(16);
  * const nonce = randomBytes(12);
- * const cipher = gcm(key, nonce);
+ * const aad = new TextEncoder().encode('session metadata');
+ * const cipher = gcm(key, nonce, aad);
  * cipher.encrypt(new Uint8Array([1, 2, 3]));
  * ```
  */
@@ -1026,7 +1027,8 @@ const limit = (name: string, min: number, max: number) => (value: number) => {
  * import { randomBytes } from '@noble/ciphers/utils.js';
  * const key = randomBytes(16);
  * const nonce = randomBytes(12);
- * const cipher = gcmsiv(key, nonce);
+ * const aad = new TextEncoder().encode('session metadata');
+ * const cipher = gcmsiv(key, nonce, aad);
  * cipher.encrypt(new Uint8Array([1, 2, 3]));
  * ```
  */
diff --git a/src/chacha.ts b/src/chacha.ts
@@ -505,7 +505,8 @@ export const _poly1305_aead =
  * import { randomBytes } from '@noble/ciphers/utils.js';
  * const key = randomBytes(32);
  * const nonce = randomBytes(12);
- * const cipher = chacha20poly1305(key, nonce);
+ * const aad = new TextEncoder().encode('session metadata');
+ * const cipher = chacha20poly1305(key, nonce, aad);
  * cipher.encrypt(new Uint8Array([1, 2, 3]));
  * ```
  */
@@ -530,7 +531,8 @@ export const chacha20poly1305: TRet<ARXCipher & { withAAD: true }> = /* @__PURE_
  * import { randomBytes } from '@noble/ciphers/utils.js';
  * const key = randomBytes(32);
  * const nonce = randomBytes(24);
- * const cipher = xchacha20poly1305(key, nonce);
+ * const aad = new TextEncoder().encode('session metadata');
+ * const cipher = xchacha20poly1305(key, nonce, aad);
  * cipher.encrypt(new Uint8Array([1, 2, 3]));
  * ```
  */
diff --git a/src/ff1.ts b/src/ff1.ts
@@ -5,6 +5,7 @@
  */
 import { unsafe } from './aes.ts';
 import {
+  aarray,
   abytes,
   anumber,
   bytesToNumberBE,
@@ -137,9 +138,9 @@ export function FF1(
   key: TArg<Uint8Array>,
   tweak: TArg<Uint8Array> = EMPTY_BUF
 ): { encrypt(x: number[]): number[]; decrypt(x: number[]): number[] } {
-  anumber(radix);
-  abytes(key);
-  abytes(tweak);
+  anumber(radix, 'radix');
+  abytes(key, undefined, 'key');
+  abytes(tweak, undefined, 'tweak');
   // This borrows caller key/tweak buffers by reference through the bound closure; mutating them
   // after construction changes later encrypt/decrypt outputs.
   const PQ = getRound.bind(null, radix, key, tweak);
@@ -174,7 +175,7 @@ export function FF1(
 // Binary wrapper uses little-endian bit order within each byte so bit 0 stays
 // in the first numeral slot for this library-defined byte-array surface.
 const binLE = {
-  encode(bytes: TArg<Uint8Array>): number[] {
+  encode(bytes: TArg<Uint8Array> | number[]): number[] {
     const x = [];
     for (let i = 0; i < bytes.length; i++) {
       for (let j = 0, tmp = bytes[i]; j < 8; j++, tmp >>= 1) x.push(tmp & 1);
@@ -214,9 +215,27 @@ export function BinaryFF1(
 ): TRet<Cipher> {
   const ff1 = FF1(2, key, tweak);
   return {
-    encrypt: (x: TArg<Uint8Array>): TRet<Uint8Array> =>
-      binLE.decode(ff1.encrypt(binLE.encode(x))) as TRet<Uint8Array>,
-    decrypt: (x: TArg<Uint8Array>): TRet<Uint8Array> =>
-      binLE.decode(ff1.decrypt(binLE.encode(x))) as TRet<Uint8Array>,
+    encrypt: (x: TArg<Uint8Array> | number[]): TRet<Uint8Array> => {
+      if (Array.isArray(x)) {
+        aarray<number>(x, 'x', (elm, title) => {
+          anumber(elm, title);
+          if (elm > 255) throw new RangeError(`"${title}" expected byte`);
+        });
+      } else {
+        x = abytes(x, undefined, 'x');
+      }
+      return binLE.decode(ff1.encrypt(binLE.encode(x))) as TRet<Uint8Array>;
+    },
+    decrypt: (x: TArg<Uint8Array> | number[]): TRet<Uint8Array> => {
+      if (Array.isArray(x)) {
+        aarray<number>(x, 'x', (elm, title) => {
+          anumber(elm, title);
+          if (elm > 255) throw new RangeError(`"${title}" expected byte`);
+        });
+      } else {
+        x = abytes(x, undefined, 'x');
+      }
+      return binLE.decode(ff1.decrypt(binLE.encode(x))) as TRet<Uint8Array>;
+    },
   } as TRet<Cipher>;
 }
diff --git a/src/salsa.ts b/src/salsa.ts
@@ -314,7 +314,7 @@ export const xsalsa20poly1305: TRet<ARXCipher> = /* @__PURE__ */ wrapCipher(
         // [0..32]      [32..48]      [48..]
         // Authenticate the ciphertext before decrypting it; on tag failure the scratch/output
         // buffer may already contain copied ciphertext and derived auth-key material.
-        abytes(ciphertext);
+        abytes(ciphertext, undefined, 'data');
         output = getOutput(ciphertext.length + 32, output, false);
         // output[0..32] is auth-key scratch, output[32..48] is passed tag,
         // output[48..] is ciphertext then plaintext.
diff --git a/src/utils.ts b/src/utils.ts
@@ -110,6 +110,17 @@ export type TRet<T> = T extends unknown
         : TypedRet<T>)
   : never;
 
+export function aarray<T>(
+  item: unknown,
+  title: string,
+  inner: (elm: T, title: string) => void = () => {}
+): T[] {
+  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;
+}
+
 /**
  * Checks if something is Uint8Array. Be careful: nodejs Buffer will return true.
  * @param a - Value to inspect.
@@ -146,8 +157,11 @@ export function isBytes(a: unknown): a is Uint8Array {
  * abool(true);
  * ```
  */
-export function abool(b: boolean): void {
-  if (typeof b !== 'boolean') throw new TypeError(`boolean expected, not ${b}`);
+export function abool(b: boolean, title: string = ''): void {
+  if (typeof b !== 'boolean') {
+    const prefix = title && `"${title}" `;
+    throw new TypeError(`${prefix}expected boolean, got type=${typeof b}`);
+  }
 }
 
 /**
@@ -162,10 +176,13 @@ export function abool(b: boolean): void {
  * anumber(1);
  * ```
  */
-export function anumber(n: number): void {
-  if (typeof n !== 'number') throw new TypeError('number expected, got ' + typeof n);
+export function anumber(n: number, title: string = ''): void {
+  if (typeof n !== 'number') {
+    const prefix = title && `"${title}" `;
+    throw new TypeError(`${prefix}expected number, got ${typeof n}`);
+  }
   if (!Number.isSafeInteger(n) || n < 0)
-    throw new RangeError('positive integer expected, got ' + n);
+    throw new RangeError(`${title ? `"${title}" ` : ''}expected integer >= 0, got ${n}`);
 }
 
 /**
@@ -192,6 +209,7 @@ export function abytes(
   const bytes = isBytes(value);
   const len = value?.length;
   const needsLen = length !== undefined;
+  if (needsLen) anumber(length, 'length');
   if (!bytes || (needsLen && len !== length)) {
     const prefix = title && `"${title}" `;
     const ofLen = needsLen ? ` of length ${length}` : '';
@@ -203,6 +221,45 @@ export function abytes(
   return value as TRet<Uint8Array>;
 }
 
+function validateObject(
+  object: Record<string, any>,
+  fields: Record<string, string> = {},
+  optFields: Record<string, string> = {},
+  title = 'object'
+): void {
+  const checkObject = (value: Record<string, any>, label: string) => {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+      throw new TypeError(
+        label === 'object'
+          ? 'expected valid options object'
+          : `"${label}" expected object, got type=${typeof value}`
+      );
+  };
+  checkObject(object, title);
+  checkObject(fields, 'fields');
+  checkObject(optFields, 'optFields');
+  type Item = keyof typeof object;
+  function checkField(fieldName: Item, expectedType: string, isOpt: boolean) {
+    const label =
+      title === 'object' ? `param "${String(fieldName)}"` : `"${title}.${String(fieldName)}"`;
+    const val = object[fieldName];
+    if (
+      !Object.hasOwn(object, fieldName) &&
+      (isOpt ? val !== undefined : expectedType !== 'function')
+    ) {
+      throw new TypeError(`${label} is invalid: expected own property`);
+    }
+    if (isOpt && val === undefined) return;
+    const current = typeof val;
+    if (current !== expectedType || val === null)
+      throw new TypeError(`${label} is invalid: expected ${expectedType}, got ${current}`);
+  }
+  const iter = (f: typeof fields, isOpt: boolean) =>
+    Object.entries(f).forEach(([k, v]) => checkField(k, v, isOpt));
+  iter(fields, false);
+  iter(optFields, true);
+}
+
 /**
  * Asserts a hash- or MAC-like instance has not been destroyed or finished.
  * @param instance - Stateful instance to validate.
@@ -217,6 +274,7 @@ export function abytes(
  * ```
  */
 export function aexists(instance: any, checkFinished = true): void {
+  validateObject(instance, {}, { destroyed: 'boolean', finished: 'boolean' }, 'instance');
   if (instance.destroyed) throw new Error('Hash instance has been destroyed');
   if (checkFinished && instance.finished) throw new Error('Hash#digest() has already been called');
 }
@@ -240,6 +298,8 @@ export function aexists(instance: any, checkFinished = true): void {
  */
 export function aoutput(out: any, instance: any, onlyAligned = false): void {
   abytes(out, undefined, 'output');
+  validateObject(instance, { outputLen: 'number' }, {}, 'instance');
+  anumber(instance.outputLen, 'instance.outputLen');
   const min = instance.outputLen;
   if (out.length < min) {
     throw new RangeError('digestInto() expects output buffer of length at least ' + min);
@@ -705,7 +765,8 @@ export function checkOpts<T1 extends EmptyObj, T2 extends EmptyObj>(
   defaults: T1,
   opts: T2
 ): T1 & T2 {
-  if (opts == null || typeof opts !== 'object') throw new Error('options must be defined');
+  validateObject(defaults, {}, {}, 'defaults');
+  validateObject(opts, {}, {}, 'opts');
   // Mutates defaults by design. __proto__ follows Object.assign semantics here and can only
   // affect this local option object; callers already control this low-level options surface.
   const merged = Object.assign(defaults, opts);
@@ -934,12 +995,12 @@ export const wrapCipher = <C extends CipherCons<any>, P extends CipherParams>(
         if (called) throw new Error('cannot encrypt() twice with same key + nonce');
         // Any encrypt attempt consumes the instance, even if validation rejects below.
         called = true;
-        abytes(data);
+        abytes(data, undefined, 'data');
         checkOutput(cipher.encrypt.length, output);
         return (cipher as CipherWithOutput).encrypt(data, output);
       },
       decrypt(data: TArg<Uint8Array>, output?: TArg<Uint8Array>) {
-        abytes(data);
+        abytes(data, undefined, 'data');
         if (tagl && data.length < tagl)
           throw new Error('"ciphertext" expected length bigger than tagLength=' + tagl);
         checkOutput(cipher.decrypt.length, output);
@@ -1171,8 +1232,12 @@ export function managedNonce<T extends CipherWithNonce>(
   fn: T,
   randomBytes_: typeof randomBytes = randomBytes
 ): TRet<RemoveNonce<T>> {
+  if (typeof fn !== 'function')
+    throw new TypeError('"fn" expected cipher constructor, got type=' + typeof fn);
+  if (typeof randomBytes_ !== 'function')
+    throw new TypeError('"randomBytes_" expected function, got type=' + typeof randomBytes_);
   const { nonceLength } = fn;
-  anumber(nonceLength);
+  anumber(nonceLength, 'fn.nonceLength');
   const addNonce = (
     nonce: TArg<Uint8Array>,
     ciphertext: TArg<Uint8Array>,
@@ -1191,7 +1256,7 @@ export function managedNonce<T extends CipherWithNonce>(
   // - previously we passed all args to cipher, but that was mistake!
   const res = ((key: TArg<Uint8Array>, ...args: any[]): any => ({
     encrypt(plaintext: TArg<Uint8Array>) {
-      abytes(plaintext);
+      abytes(plaintext, undefined, 'data');
       const nonce = randomBytes_(nonceLength);
       const encrypted = fn(key, nonce, ...args).encrypt(plaintext);
       // @ts-ignore
@@ -1200,7 +1265,7 @@ export function managedNonce<T extends CipherWithNonce>(
       return addNonce(nonce, encrypted, plaintext);
     },
     decrypt(ciphertext: TArg<Uint8Array>) {
-      abytes(ciphertext);
+      abytes(ciphertext, undefined, 'data');
       const nonce = ciphertext.subarray(0, nonceLength);
       const decrypted = ciphertext.subarray(nonceLength);
       return fn(key, nonce, ...args).decrypt(decrypted);
diff --git a/src/webcrypto.ts b/src/webcrypto.ts
@@ -93,8 +93,8 @@ function generate(
     nonce: TArg<Uint8Array>,
     AAD?: TArg<Uint8Array>
   ): TRet<AsyncCipher> => {
-    abytes(key);
-    abytes(nonce);
+    abytes(key, undefined, 'key');
+    abytes(nonce, undefined, 'nonce');
     // Reject falsy non-byte AAD locally; otherwise false/0/''/null silently become "no AAD".
     if (AAD !== undefined) {
       if (!withAAD) throw new Error('AAD not supported');
@@ -112,13 +112,13 @@ function generate(
     return {
       // keyLength,
       encrypt(plaintext: TArg<Uint8Array>): Promise<TRet<Uint8Array>> {
-        abytes(plaintext);
+        abytes(plaintext, undefined, 'data');
         if (consumed) throw new Error('Cannot encrypt() twice with same key / nonce');
         consumed = true;
         return utils.encrypt(key, keyParams, cryptParams, plaintext);
       },
       decrypt(ciphertext: TArg<Uint8Array>): Promise<TRet<Uint8Array>> {
-        abytes(ciphertext);
+        abytes(ciphertext, undefined, 'data');
         return utils.decrypt(key, keyParams, cryptParams, ciphertext);
       },
     } as TRet<AsyncCipher>;
