@noble/curves 1.4.2 → 1.5.0

package/src/abstract/weierstrass.ts

@@ -3,7 +3,7 @@
 import { AffinePoint, BasicCurve, Group, GroupConstructor, validateBasic, wNAF } from './curve.js';
 import * as mod from './modular.js';
 import * as ut from './utils.js';
-import { CHash, Hex, PrivKey, ensureBytes } from './utils.js';
+import { CHash, Hex, PrivKey, ensureBytes, memoized, abool } from './utils.js';
 
 export type { AffinePoint };
 type HmacFnSync = (key: Uint8Array, ...messages: Uint8Array[]) => Uint8Array;
@@ -31,6 +31,11 @@ type Entropy = Hex | boolean;
 export type SignOpts = { lowS?: boolean; extraEntropy?: Entropy; prehash?: boolean };
 export type VerOpts = { lowS?: boolean; prehash?: boolean };
 
+function validateSigVerOpts(opts: SignOpts | VerOpts) {
+  if (opts.lowS !== undefined) abool('lowS', opts.lowS);
+  if (opts.prehash !== undefined) abool('prehash', opts.prehash);
+}
+
 /**
  * ### Design rationale for types
  *
@@ -228,15 +233,12 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
 
   // Valid group elements reside in range 1..n-1
   function isWithinCurveOrder(num: bigint): boolean {
-    return typeof num === 'bigint' && _0n < num && num < CURVE.n;
-  }
-  function assertGE(num: bigint) {
-    if (!isWithinCurveOrder(num)) throw new Error('Expected valid bigint: 0 < bigint < curve.n');
+    return ut.inRange(num, _1n, CURVE.n);
   }
   // Validates if priv key is valid and converts it to bigint.
   // Supports options allowedPrivateKeyLengths and wrapPrivateKey.
   function normPrivateKeyToScalar(key: PrivKey): bigint {
-    const { allowedPrivateKeyLengths: lengths, nByteLength, wrapPrivateKey, n } = CURVE;
+    const { allowedPrivateKeyLengths: lengths, nByteLength, wrapPrivateKey, n: N } = CURVE;
     if (lengths && typeof key !== 'bigint') {
       if (ut.isBytes(key)) key = ut.bytesToHex(key);
       // Normalize to hex string, pad. E.g. P521 would norm 130-132 char hex to 132-char bytes
@@ -252,15 +254,56 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
     } catch (error) {
       throw new Error(`private key must be ${nByteLength} bytes, hex or bigint, not ${typeof key}`);
     }
-    if (wrapPrivateKey) num = mod.mod(num, n); // disabled by default, enabled for BLS
-    assertGE(num); // num in range [1..N-1]
+    if (wrapPrivateKey) num = mod.mod(num, N); // disabled by default, enabled for BLS
+    ut.aInRange('private key', num, _1n, N); // num in range [1..N-1]
     return num;
   }
 
-  const pointPrecomputes = new Map<Point, Point[]>();
   function assertPrjPoint(other: unknown) {
     if (!(other instanceof Point)) throw new Error('ProjectivePoint expected');
   }
+
+  // Memoized toAffine / validity check. They are heavy. Points are immutable.
+
+  // Converts Projective point to affine (x, y) coordinates.
+  // Can accept precomputed Z^-1 - for example, from invertBatch.
+  // (x, y, z) ∋ (x=x/z, y=y/z)
+  const toAffineMemo = memoized((p: Point, iz?: T): AffinePoint<T> => {
+    const { px: x, py: y, pz: z } = p;
+    // Fast-path for normalized points
+    if (Fp.eql(z, Fp.ONE)) return { x, y };
+    const is0 = p.is0();
+    // If invZ was 0, we return zero point. However we still want to execute
+    // all operations, so we replace invZ with a random number, 1.
+    if (iz == null) iz = is0 ? Fp.ONE : Fp.inv(z);
+    const ax = Fp.mul(x, iz);
+    const ay = Fp.mul(y, iz);
+    const zz = Fp.mul(z, iz);
+    if (is0) return { x: Fp.ZERO, y: Fp.ZERO };
+    if (!Fp.eql(zz, Fp.ONE)) throw new Error('invZ was invalid');
+    return { x: ax, y: ay };
+  });
+  // NOTE: on exception this will crash 'cached' and no value will be set.
+  // Otherwise true will be return
+  const assertValidMemo = memoized((p: Point) => {
+    if (p.is0()) {
+      // (0, 1, 0) aka ZERO is invalid in most contexts.
+      // In BLS, ZERO can be serialized, so we allow it.
+      // (0, 0, 0) is wrong representation of ZERO and is always invalid.
+      if (CURVE.allowInfinityPoint && !Fp.is0(p.py)) return;
+      throw new Error('bad point: ZERO');
+    }
+    // Some 3rd-party test vectors require different wording between here & `fromCompressedHex`
+    const { x, y } = p.toAffine();
+    // Check if x, y are valid field elements
+    if (!Fp.isValid(x) || !Fp.isValid(y)) throw new Error('bad point: x or y not FE');
+    const left = Fp.sqr(y); // y²
+    const right = weierstrassEquation(x); // x³ + ax + b
+    if (!Fp.eql(left, right)) throw new Error('bad point: equation left != right');
+    if (!p.isTorsionFree()) throw new Error('bad point: not in prime-order subgroup');
+    return true;
+  });
+
   /**
    * Projective Point works in 3d / projective (homogeneous) coordinates: (x, y, z) ∋ (x=x/z, y=y/z)
    * Default Point works in 2d / affine coordinates: (x, y)
@@ -278,6 +321,7 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
       if (px == null || !Fp.isValid(px)) throw new Error('x required');
       if (py == null || !Fp.isValid(py)) throw new Error('y required');
       if (pz == null || !Fp.isValid(pz)) throw new Error('z required');
+      Object.freeze(this);
     }
 
     // Does not validate if the point is on-curve.
@@ -325,35 +369,16 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
       return Point.BASE.multiply(normPrivateKeyToScalar(privateKey));
     }
 
-    // We calculate precomputes for elliptic curve point multiplication
-    // using windowed method. This specifies window size and
-    // stores precomputed values. Usually only base point would be precomputed.
-    _WINDOW_SIZE?: number;
-
     // "Private method", don't use it directly
     _setWindowSize(windowSize: number) {
-      this._WINDOW_SIZE = windowSize;
-      pointPrecomputes.delete(this);
+      wnaf.setWindowSize(this, windowSize);
     }
 
     // A point on curve is valid if it conforms to equation.
     assertValidity(): void {
-      if (this.is0()) {
-        // (0, 1, 0) aka ZERO is invalid in most contexts.
-        // In BLS, ZERO can be serialized, so we allow it.
-        // (0, 0, 0) is wrong representation of ZERO and is always invalid.
-        if (CURVE.allowInfinityPoint && !Fp.is0(this.py)) return;
-        throw new Error('bad point: ZERO');
-      }
-      // Some 3rd-party test vectors require different wording between here & `fromCompressedHex`
-      const { x, y } = this.toAffine();
-      // Check if x, y are valid field elements
-      if (!Fp.isValid(x) || !Fp.isValid(y)) throw new Error('bad point: x or y not FE');
-      const left = Fp.sqr(y); // y²
-      const right = weierstrassEquation(x); // x³ + ax + b
-      if (!Fp.eql(left, right)) throw new Error('bad point: equation left != right');
-      if (!this.isTorsionFree()) throw new Error('bad point: not in prime-order subgroup');
+      assertValidMemo(this);
     }
+
     hasEvenY(): boolean {
       const { y } = this.toAffine();
       if (Fp.isOdd) return !Fp.isOdd(y);
@@ -480,14 +505,11 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
       return this.add(other.negate());
     }
 
-    private is0() {
+    is0() {
       return this.equals(Point.ZERO);
     }
     private wNAF(n: bigint): { p: Point; f: Point } {
-      return wnaf.wNAFCached(this, pointPrecomputes, n, (comp: Point[]) => {
-        const toInv = Fp.invertBatch(comp.map((p) => p.pz));
-        return comp.map((p, i) => p.toAffine(toInv[i])).map(Point.fromAffine);
-      });
+      return wnaf.wNAFCached(this, n, Point.normalizeZ);
     }
 
     /**
@@ -495,16 +517,16 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
      * It's faster, but should only be used when you don't care about
      * an exposed private key e.g. sig verification, which works over *public* keys.
      */
-    multiplyUnsafe(n: bigint): Point {
+    multiplyUnsafe(sc: bigint): Point {
+      ut.aInRange('scalar', sc, _0n, CURVE.n);
       const I = Point.ZERO;
-      if (n === _0n) return I;
-      assertGE(n); // Will throw on 0
-      if (n === _1n) return this;
+      if (sc === _0n) return I;
+      if (sc === _1n) return this;
       const { endo } = CURVE;
-      if (!endo) return wnaf.unsafeLadder(this, n);
+      if (!endo) return wnaf.unsafeLadder(this, sc);
 
       // Apply endomorphism
-      let { k1neg, k1, k2neg, k2 } = endo.splitScalar(n);
+      let { k1neg, k1, k2neg, k2 } = endo.splitScalar(sc);
       let k1p = I;
       let k2p = I;
       let d: Point = this;
@@ -531,12 +553,11 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
      * @returns New point
      */
     multiply(scalar: bigint): Point {
-      assertGE(scalar);
-      let n = scalar;
+      const { endo, n: N } = CURVE;
+      ut.aInRange('scalar', scalar, _1n, N);
       let point: Point, fake: Point; // Fake point is used to const-time mult
-      const { endo } = CURVE;
       if (endo) {
-        const { k1neg, k1, k2neg, k2 } = endo.splitScalar(n);
+        const { k1neg, k1, k2neg, k2 } = endo.splitScalar(scalar);
         let { p: k1p, f: f1p } = this.wNAF(k1);
         let { p: k2p, f: f2p } = this.wNAF(k2);
         k1p = wnaf.constTimeNegate(k1neg, k1p);
@@ -545,7 +566,7 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
         point = k1p.add(k2p);
         fake = f1p.add(f2p);
       } else {
-        const { p, f } = this.wNAF(n);
+        const { p, f } = this.wNAF(scalar);
         point = p;
         fake = f;
       }
@@ -573,17 +594,7 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
     // Can accept precomputed Z^-1 - for example, from invertBatch.
     // (x, y, z) ∋ (x=x/z, y=y/z)
     toAffine(iz?: T): AffinePoint<T> {
-      const { px: x, py: y, pz: z } = this;
-      const is0 = this.is0();
-      // If invZ was 0, we return zero point. However we still want to execute
-      // all operations, so we replace invZ with a random number, 1.
-      if (iz == null) iz = is0 ? Fp.ONE : Fp.inv(z);
-      const ax = Fp.mul(x, iz);
-      const ay = Fp.mul(y, iz);
-      const zz = Fp.mul(z, iz);
-      if (is0) return { x: Fp.ZERO, y: Fp.ZERO };
-      if (!Fp.eql(zz, Fp.ONE)) throw new Error('invZ was invalid');
-      return { x: ax, y: ay };
+      return toAffineMemo(this, iz);
     }
     isTorsionFree(): boolean {
       const { h: cofactor, isTorsionFree } = CURVE;
@@ -599,11 +610,13 @@ export function weierstrassPoints<T>(opts: CurvePointsType<T>): CurvePointsRes<T
     }
 
     toRawBytes(isCompressed = true): Uint8Array {
+      abool('isCompressed', isCompressed);
       this.assertValidity();
       return toBytes(Point, this, isCompressed);
     }
 
     toHex(isCompressed = true): string {
+      abool('isCompressed', isCompressed);
       return ut.bytesToHex(this.toRawBytes(isCompressed));
     }
   }
@@ -691,15 +704,19 @@ export type CurveFn = {
   };
 };
 
+/**
+ * Creates short weierstrass curve and ECDSA signature methods for it.
+ * @example
+ * import { Field } from '@noble/curves/abstract/modular';
+ * // Before that, define BigInt-s: a, b, p, n, Gx, Gy
+ * const curve = weierstrass({ a, b, Fp: Field(p), n, Gx, Gy, h: 1n })
+ */
 export function weierstrass(curveDef: CurveType): CurveFn {
   const CURVE = validateOpts(curveDef) as ReturnType<typeof validateOpts>;
   const { Fp, n: CURVE_ORDER } = CURVE;
   const compressedLen = Fp.BYTES + 1; // e.g. 33 for 32
   const uncompressedLen = 2 * Fp.BYTES + 1; // e.g. 65 for 32
 
-  function isValidFieldElement(num: bigint): boolean {
-    return _0n < num && num < Fp.ORDER; // 0 is banned since it's not invertible FE
-  }
   function modN(a: bigint) {
     return mod.mod(a, CURVE_ORDER);
   }
@@ -718,6 +735,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
       const a = point.toAffine();
       const x = Fp.toBytes(a.x);
       const cat = ut.concatBytes;
+      abool('isCompressed', isCompressed);
       if (isCompressed) {
         return cat(Uint8Array.from([point.hasEvenY() ? 0x02 : 0x03]), x);
       } else {
@@ -731,7 +749,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
       // this.assertValidity() is done inside of fromHex
       if (len === compressedLen && (head === 0x02 || head === 0x03)) {
         const x = ut.bytesToNumberBE(tail);
-        if (!isValidFieldElement(x)) throw new Error('Point is not on curve');
+        if (!ut.inRange(x, _1n, Fp.ORDER)) throw new Error('Point is not on curve');
         const y2 = weierstrassEquation(x); // y² = x³ + ax + b
         let y: bigint;
         try {
@@ -797,9 +815,8 @@ export function weierstrass(curveDef: CurveType): CurveFn {
     }
 
     assertValidity(): void {
-      // can use assertGE here
-      if (!isWithinCurveOrder(this.r)) throw new Error('r must be 0 < r < CURVE.n');
-      if (!isWithinCurveOrder(this.s)) throw new Error('s must be 0 < s < CURVE.n');
+      ut.aInRange('r', this.r, _1n, CURVE_ORDER); // r in [1..N]
+      ut.aInRange('s', this.s, _1n, CURVE_ORDER); // s in [1..N]
     }
 
     addRecoveryBit(recovery: number): RecoveredSignature {
@@ -949,9 +966,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
    * Converts to bytes. Checks if num in `[0..ORDER_MASK-1]` e.g.: `[0..2^256-1]`.
    */
   function int2octets(num: bigint): Uint8Array {
-    if (typeof num !== 'bigint') throw new Error('bigint expected');
-    if (!(_0n <= num && num < ORDER_MASK))
-      throw new Error(`bigint expected < 2^${CURVE.nBitLength}`);
+    ut.aInRange(`num < 2^${CURVE.nBitLength}`, num, _0n, ORDER_MASK);
     // works with order, can have different size than numToField!
     return ut.numberToBytesBE(num, CURVE.nByteLength);
   }
@@ -968,6 +983,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
     let { lowS, prehash, extraEntropy: ent } = opts; // generates low-s sigs by default
     if (lowS == null) lowS = true; // RFC6979 3.2: we skip step A, because we already provide hash
     msgHash = ensureBytes('msgHash', msgHash);
+    validateSigVerOpts(opts);
     if (prehash) msgHash = ensureBytes('prehashed msgHash', hash(msgHash));
 
     // We can't later call bits2octets, since nested bits2int is broken for curves
@@ -1058,6 +1074,7 @@ export function weierstrass(curveDef: CurveType): CurveFn {
     msgHash = ensureBytes('msgHash', msgHash);
     publicKey = ensureBytes('publicKey', publicKey);
     if ('strict' in opts) throw new Error('options.strict was renamed to lowS');
+    validateSigVerOpts(opts);
     const { lowS, prehash } = opts;
 
     let _sig: Signature | undefined = undefined;