@noble/curves 0.5.0 → 0.5.2

package/lib/esm/abstract/edwards.js

@@ -1,41 +1,36 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 // Twisted Edwards curve. The formula is: ax² + y² = 1 + dx²y²
 // Differences from @noble/ed25519 1.7:
-// 1. Different field element lengths in ed448:
+// 1. Variable field element lengths between EDDSA/ECDH:
 //   EDDSA (RFC8032) is 456 bits / 57 bytes, ECDH (RFC7748) is 448 bits / 56 bytes
 // 2. Different addition formula (doubling is same)
 // 3. uvRatio differs between curves (half-expected, not only pow fn changes)
-// 4. Point decompression code is different too (unexpected), now using generalized formula
+// 4. Point decompression code is different (unexpected), now using generalized formula
 // 5. Domain function was no-op for ed25519, but adds some data even with empty context for ed448
 import * as mod from './modular.js';
-import { bytesToHex, concatBytes, ensureBytes, numberToBytesLE, bytesToNumberLE, hashToPrivateScalar, validateOpts as utilOpts, } from './utils.js'; // TODO: import * as u from './utils.js'?
+import * as ut from './utils.js';
+import { ensureBytes } from './utils.js';
 import { wNAF } from './group.js';
-import { hash_to_field, validateHTFOpts } from './hash-to-curve.js';
+import { hash_to_field as hashToField, validateHTFOpts } from './hash-to-curve.js';
 // Be friendly to bad ECMAScript parsers by not using bigint literals like 123n
 const _0n = BigInt(0);
 const _1n = BigInt(1);
 const _2n = BigInt(2);
 const _8n = BigInt(8);
-// Should be separate from overrides, since overrides can use information about curve (for example nBits)
 function validateOpts(curve) {
-    const opts = utilOpts(curve);
-    if (typeof opts.hash !== 'function' || !Number.isSafeInteger(opts.hash.outputLen))
+    const opts = ut.validateOpts(curve);
+    if (typeof opts.hash !== 'function' || !ut.isPositiveInt(opts.hash.outputLen))
         throw new Error('Invalid hash function');
     for (const i of ['a', 'd']) {
-        if (typeof opts[i] !== 'bigint')
-            throw new Error(`Invalid curve param ${i}=${opts[i]} (${typeof opts[i]})`);
+        const val = opts[i];
+        if (typeof val !== 'bigint')
+            throw new Error(`Invalid curve param ${i}=${val} (${typeof val})`);
     }
     for (const fn of ['randomBytes']) {
         if (typeof opts[fn] !== 'function')
             throw new Error(`Invalid ${fn} function`);
     }
-    for (const fn of [
-        'adjustScalarBytes',
-        'domain',
-        'uvRatio',
-        'mapToCurve',
-        'clearCofactor',
-    ]) {
+    for (const fn of ['adjustScalarBytes', 'domain', 'uvRatio', 'mapToCurve']) {
         if (opts[fn] === undefined)
             continue; // Optional
         if (typeof opts[fn] !== 'function')
@@ -51,34 +46,27 @@ export function twistedEdwards(curveDef) {
     const CURVE = validateOpts(curveDef);
     const Fp = CURVE.Fp;
     const CURVE_ORDER = CURVE.n;
-    const fieldLen = Fp.BYTES; // 32 (length of one field element)
-    if (fieldLen > 2048)
-        throw new Error('Field lengths over 2048 are not supported');
-    const groupLen = CURVE.nByteLength;
-    // (2n ** 256n).toString(16);
-    const maxGroupElement = _2n ** BigInt(groupLen * 8); // previous POW_2_256
+    const maxGroupElement = _2n ** BigInt(CURVE.nByteLength * 8);
     // Function overrides
     const { randomBytes } = CURVE;
     const modP = Fp.create;
     // sqrt(u/v)
-    function _uvRatio(u, v) {
-        try {
-            const value = Fp.sqrt(u * Fp.invert(v));
-            return { isValid: true, value };
-        }
-        catch (e) {
-            return { isValid: false, value: _0n };
-        }
-    }
-    const uvRatio = CURVE.uvRatio || _uvRatio;
-    const _adjustScalarBytes = (bytes) => bytes; // NOOP
-    const adjustScalarBytes = CURVE.adjustScalarBytes || _adjustScalarBytes;
-    function _domain(data, ctx, phflag) {
-        if (ctx.length || phflag)
-            throw new Error('Contexts/pre-hash are not supported');
-        return data;
-    }
-    const domain = CURVE.domain || _domain; // NOOP
+    const uvRatio = CURVE.uvRatio ||
+        ((u, v) => {
+            try {
+                return { isValid: true, value: Fp.sqrt(u * Fp.invert(v)) };
+            }
+            catch (e) {
+                return { isValid: false, value: _0n };
+            }
+        });
+    const adjustScalarBytes = CURVE.adjustScalarBytes || ((bytes) => bytes); // NOOP
+    const domain = CURVE.domain ||
+        ((data, ctx, phflag) => {
+            if (ctx.length || phflag)
+                throw new Error('Contexts/pre-hash are not supported');
+            return data;
+        }); // NOOP
     /**
      * Extended Point works in extended coordinates: (x, y, z, t) ∋ (x=x/z, y=y/z, t=xy).
      * Default Point works in affine coordinates: (x, y)
@@ -215,26 +203,28 @@ export function twistedEdwards(curveDef) {
         // Non-constant-time multiplication. Uses double-and-add algorithm.
         // It's faster, but should only be used when you don't care about
         // an exposed private key e.g. sig verification.
-        // Allows scalar bigger than curve order, but less than 2^256
         multiplyUnsafe(scalar) {
             let n = normalizeScalar(scalar, CURVE_ORDER, false);
-            const G = ExtendedPoint.BASE;
             const P0 = ExtendedPoint.ZERO;
             if (n === _0n)
                 return P0;
             if (this.equals(P0) || n === _1n)
                 return this;
-            if (this.equals(G))
+            if (this.equals(ExtendedPoint.BASE))
                 return this.wNAF(n);
             return wnaf.unsafeLadder(this, n);
         }
+        // Checks if point is of small order.
+        // If you add something to small order point, you will have "dirty"
+        // point with torsion component.
         // Multiplies point by cofactor and checks if the result is 0.
         isSmallOrder() {
             return this.multiplyUnsafe(CURVE.h).equals(ExtendedPoint.ZERO);
         }
-        // Multiplies point by a very big scalar n and checks if the result is 0.
+        // Multiplies point by curve order (very big scalar CURVE.n) and checks if the result is 0.
+        // Returns `false` is the point is dirty.
         isTorsionFree() {
-            return this.multiplyUnsafe(CURVE_ORDER).equals(ExtendedPoint.ZERO);
+            return wnaf.unsafeLadder(this, CURVE_ORDER).equals(ExtendedPoint.ZERO);
         }
         // Converts Extended point to default (x, y) coordinates.
         // Can accept precomputed Z^-1 - for example, from invertBatch.
@@ -253,18 +243,15 @@ export function twistedEdwards(curveDef) {
             return new Point(ax, ay);
         }
         clearCofactor() {
-            if (CURVE.h === _1n)
-                return this; // Fast-path
-            // clear_cofactor(P) := h_eff * P
-            // hEff = h for ed25519/ed448. Maybe worth moving to params?
-            if (CURVE.clearCofactor)
-                return CURVE.clearCofactor(ExtendedPoint, this);
-            return this.multiplyUnsafe(CURVE.h);
+            const { h: cofactor } = CURVE;
+            if (cofactor === _1n)
+                return this;
+            return this.multiplyUnsafe(cofactor);
         }
     }
     ExtendedPoint.BASE = new ExtendedPoint(CURVE.Gx, CURVE.Gy, _1n, modP(CURVE.Gx * CURVE.Gy));
     ExtendedPoint.ZERO = new ExtendedPoint(_0n, _1n, _1n, _0n);
-    const wnaf = wNAF(ExtendedPoint, groupLen * 8);
+    const wnaf = wNAF(ExtendedPoint, CURVE.nByteLength * 8);
     function assertExtPoint(other) {
         if (!(other instanceof ExtendedPoint))
             throw new TypeError('ExtendedPoint expected');
@@ -288,20 +275,21 @@ export function twistedEdwards(curveDef) {
         // Uses algo from RFC8032 5.1.3.
         static fromHex(hex, strict = true) {
             const { d, a } = CURVE;
-            hex = ensureBytes(hex, fieldLen);
+            const len = Fp.BYTES;
+            hex = ensureBytes(hex, len);
             // 1.  First, interpret the string as an integer in little-endian
             // representation. Bit 255 of this number is the least significant
             // bit of the x-coordinate and denote this value x_0.  The
             // y-coordinate is recovered simply by clearing this bit.  If the
             // resulting value is >= p, decoding fails.
             const normed = hex.slice();
-            const lastByte = hex[fieldLen - 1];
-            normed[fieldLen - 1] = lastByte & ~0x80;
-            const y = bytesToNumberLE(normed);
+            const lastByte = hex[len - 1];
+            normed[len - 1] = lastByte & ~0x80;
+            const y = ut.bytesToNumberLE(normed);
             if (strict && y >= Fp.ORDER)
                 throw new Error('Expected 0 < hex < P');
             if (!strict && y >= maxGroupElement)
-                throw new Error('Expected 0 < hex < 2**256');
+                throw new Error('Expected 0 < hex < CURVE.n');
             // 2.  To recover the x-coordinate, the curve equation implies
             // Ed25519: x² = (y² - 1) / (d y² + 1) (mod p).
             // Ed448: x² = (y² - 1) / (d y² - 1) (mod p).
@@ -333,14 +321,16 @@ export function twistedEdwards(curveDef) {
         // When compressing point, it's enough to only store its y coordinate
         // and use the last byte to encode sign of x.
         toRawBytes() {
-            const bytes = numberToBytesLE(this.y, fieldLen);
-            bytes[fieldLen - 1] |= this.x & _1n ? 0x80 : 0;
+            const bytes = ut.numberToBytesLE(this.y, Fp.BYTES);
+            bytes[Fp.BYTES - 1] |= this.x & _1n ? 0x80 : 0;
             return bytes;
         }
         // Same as toRawBytes, but returns string.
         toHex() {
-            return bytesToHex(this.toRawBytes());
+            return ut.bytesToHex(this.toRawBytes());
         }
+        // Determines if point is in prime-order subgroup.
+        // Returns `false` is the point is dirty.
         isTorsionFree() {
             return ExtendedPoint.fromAffine(this).isTorsionFree();
         }
@@ -375,22 +365,22 @@ export function twistedEdwards(curveDef) {
         // Encodes byte string to elliptic curve
         // https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-3
         static hashToCurve(msg, options) {
-            if (!CURVE.mapToCurve)
+            const { mapToCurve, htfDefaults } = CURVE;
+            if (!mapToCurve)
                 throw new Error('No mapToCurve defined for curve');
-            msg = ensureBytes(msg);
-            const u = hash_to_field(msg, 2, { ...CURVE.htfDefaults, ...options });
-            const { x: x0, y: y0 } = CURVE.mapToCurve(u[0]);
-            const { x: x1, y: y1 } = CURVE.mapToCurve(u[1]);
+            const u = hashToField(ensureBytes(msg), 2, { ...htfDefaults, ...options });
+            const { x: x0, y: y0 } = mapToCurve(u[0]);
+            const { x: x1, y: y1 } = mapToCurve(u[1]);
             const p = new Point(x0, y0).add(new Point(x1, y1)).clearCofactor();
             return p;
         }
         // https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-16#section-3
         static encodeToCurve(msg, options) {
-            if (!CURVE.mapToCurve)
+            const { mapToCurve, htfDefaults } = CURVE;
+            if (!mapToCurve)
                 throw new Error('No mapToCurve defined for curve');
-            msg = ensureBytes(msg);
-            const u = hash_to_field(msg, 1, { ...CURVE.htfDefaults, ...options });
-            const { x, y } = CURVE.mapToCurve(u[0]);
+            const u = hashToField(ensureBytes(msg), 1, { ...htfDefaults, ...options });
+            const { x, y } = mapToCurve(u[0]);
             return new Point(x, y).clearCofactor();
         }
     }
@@ -410,9 +400,10 @@ export function twistedEdwards(curveDef) {
             this.assertValidity();
         }
         static fromHex(hex) {
-            const bytes = ensureBytes(hex, 2 * fieldLen);
-            const r = Point.fromHex(bytes.slice(0, fieldLen), false);
-            const s = bytesToNumberLE(bytes.slice(fieldLen, 2 * fieldLen));
+            const len = Fp.BYTES;
+            const bytes = ensureBytes(hex, 2 * len);
+            const r = Point.fromHex(bytes.slice(0, len), false);
+            const s = ut.bytesToNumberLE(bytes.slice(len, 2 * len));
             return new Signature(r, s);
         }
         assertValidity() {
@@ -424,15 +415,15 @@ export function twistedEdwards(curveDef) {
             return this;
         }
         toRawBytes() {
-            return concatBytes(this.r.toRawBytes(), numberToBytesLE(this.s, fieldLen));
+            return ut.concatBytes(this.r.toRawBytes(), ut.numberToBytesLE(this.s, Fp.BYTES));
         }
         toHex() {
-            return bytesToHex(this.toRawBytes());
+            return ut.bytesToHex(this.toRawBytes());
         }
     }
     // Little-endian SHA512 with modulo n
-    function modlLE(hash) {
-        return mod.mod(bytesToNumberLE(hash), CURVE_ORDER);
+    function modnLE(hash) {
+        return mod.mod(ut.bytesToNumberLE(hash), CURVE_ORDER);
     }
     /**
      * Checks for num to be in range:
@@ -443,7 +434,7 @@ export function twistedEdwards(curveDef) {
     function normalizeScalar(num, max, strict = true) {
         if (!max)
             throw new TypeError('Specify max value');
-        if (typeof num === 'number' && Number.isSafeInteger(num))
+        if (ut.isPositiveInt(num))
             num = BigInt(num);
         if (typeof num === 'bigint' && num < max) {
             if (strict) {
@@ -455,36 +446,30 @@ export function twistedEdwards(curveDef) {
                     return num;
             }
         }
-        throw new TypeError('Expected valid scalar: 0 < scalar < max');
+        throw new TypeError(`Expected valid scalar: 0 < scalar < ${max}`);
     }
-    function checkPrivateKey(key) {
+    /** Convenience method that creates public key and other stuff. RFC8032 5.1.5 */
+    function getExtendedPublicKey(key) {
+        const groupLen = CURVE.nByteLength;
         // Normalize bigint / number / string to Uint8Array
-        key =
-            typeof key === 'bigint' || typeof key === 'number'
-                ? numberToBytesLE(normalizeScalar(key, maxGroupElement), groupLen)
-                : ensureBytes(key);
-        if (key.length !== groupLen)
-            throw new Error(`Expected ${groupLen} bytes, got ${key.length}`);
-        return key;
-    }
-    // Takes 64 bytes
-    function getKeyFromHash(hashed) {
-        // First 32 bytes of 64b uniformingly random input are taken,
-        // clears 3 bits of it to produce a random field element.
+        const keyb = typeof key === 'bigint' || typeof key === 'number'
+            ? ut.numberToBytesLE(normalizeScalar(key, maxGroupElement), groupLen)
+            : key;
+        // Hash private key with curve's hash function to produce uniformingly random input
+        // We check byte lengths e.g.: ensureBytes(64, hash(ensureBytes(32, key)))
+        const hashed = ensureBytes(CURVE.hash(ensureBytes(keyb, groupLen)), 2 * groupLen);
+        // First half's bits are cleared to produce a random field element.
         const head = adjustScalarBytes(hashed.slice(0, groupLen));
-        // Second 32 bytes is called key prefix (5.1.6)
+        // Second half is called key prefix (5.1.6)
         const prefix = hashed.slice(groupLen, 2 * groupLen);
         // The actual private scalar
-        const scalar = modlLE(head);
+        const scalar = modnLE(head);
         // Point on Edwards curve aka public key
         const point = Point.BASE.multiply(scalar);
+        // Uint8Array representation
         const pointBytes = point.toRawBytes();
         return { head, prefix, scalar, point, pointBytes };
     }
-    /** Convenience method that creates public key and other stuff. RFC8032 5.1.5 */
-    function getExtendedPublicKey(key) {
-        return getKeyFromHash(CURVE.hash(checkPrivateKey(key)));
-    }
     /**
      * Calculates ed25519 public key. RFC8032 5.1.5
      * 1. private key is hashed with sha512, then first 32 bytes are taken from the hash
@@ -496,7 +481,7 @@ export function twistedEdwards(curveDef) {
     const EMPTY = new Uint8Array();
     function hashDomainToScalar(message, context = EMPTY) {
         context = ensureBytes(context);
-        return modlLE(CURVE.hash(domain(message, context, !!CURVE.preHash)));
+        return modnLE(CURVE.hash(domain(message, context, !!CURVE.preHash)));
     }
     /** Signs message with privateKey. RFC8032 5.1.6 */
     function sign(message, privateKey, context) {
@@ -504,9 +489,9 @@ export function twistedEdwards(curveDef) {
         if (CURVE.preHash)
             message = CURVE.preHash(message);
         const { prefix, scalar, pointBytes } = getExtendedPublicKey(privateKey);
-        const r = hashDomainToScalar(concatBytes(prefix, message), context);
+        const r = hashDomainToScalar(ut.concatBytes(prefix, message), context);
         const R = Point.BASE.multiply(r); // R = rG
-        const k = hashDomainToScalar(concatBytes(R.toRawBytes(), pointBytes, message), context); // k = hash(R+P+msg)
+        const k = hashDomainToScalar(ut.concatBytes(R.toRawBytes(), pointBytes, message), context); // k = hash(R+P+msg)
         const s = mod.mod(r + k * scalar, CURVE_ORDER); // s = r + kp
         return new Signature(R, s).toRawBytes();
     }
@@ -545,27 +530,25 @@ export function twistedEdwards(curveDef) {
             throw new Error(`Wrong signature: ${sig}`);
         const { r, s } = sig;
         const SB = ExtendedPoint.BASE.multiplyUnsafe(s);
-        const k = hashDomainToScalar(concatBytes(r.toRawBytes(), publicKey.toRawBytes(), message), context);
+        const k = hashDomainToScalar(ut.concatBytes(r.toRawBytes(), publicKey.toRawBytes(), message), context);
         const kA = ExtendedPoint.fromAffine(publicKey).multiplyUnsafe(k);
         const RkA = ExtendedPoint.fromAffine(r).add(kA);
         // [8][S]B = [8]R + [8][k]A'
-        return RkA.subtract(SB).multiplyUnsafe(CURVE.h).equals(ExtendedPoint.ZERO);
+        return RkA.subtract(SB).clearCofactor().equals(ExtendedPoint.ZERO);
     }
     // Enable precomputes. Slows down first publicKey computation by 20ms.
     Point.BASE._setWindowSize(8);
     const utils = {
         getExtendedPublicKey,
-        mod: modP,
-        invert: Fp.invert,
         /**
          * Not needed for ed25519 private keys. Needed if you use scalars directly (rare).
          */
-        hashToPrivateScalar: (hash) => hashToPrivateScalar(hash, CURVE_ORDER, true),
+        hashToPrivateScalar: (hash) => ut.hashToPrivateScalar(hash, CURVE_ORDER, true),
         /**
          * ed25519 private keys are uniform 32-bit strings. We do not need to check for
          * modulo bias like we do in secp256k1 randomPrivateKey()
          */
-        randomPrivateKey: () => randomBytes(fieldLen),
+        randomPrivateKey: () => randomBytes(Fp.BYTES),
         /**
          * We're doing scalar multiplication (used in getPublicKey etc) with precomputed BASE_POINT
          * values. This slows down first getPublicKey() by milliseconds (see Speed section),

package/lib/esm/abstract/hash-to-curve.js

@@ -10,7 +10,7 @@ export function validateHTFOpts(opts) {
         throw new Error('Invalid htf/m');
     if (typeof opts.k !== 'number')
         throw new Error('Invalid htf/k');
-    if (typeof opts.expand !== 'boolean')
+    if (opts.expand !== 'xmd' && opts.expand !== 'xof' && opts.expand !== undefined)
         throw new Error('Invalid htf/expand');
     if (typeof opts.hash !== 'function' || !Number.isSafeInteger(opts.hash.outputLen))
         throw new Error('Invalid htf/hash function');
@@ -75,13 +75,31 @@ export function expand_message_xmd(msg, DST, lenInBytes, H) {
     const pseudo_random_bytes = concatBytes(...b);
     return pseudo_random_bytes.slice(0, lenInBytes);
 }
-// hashes arbitrary-length byte strings to a list of one or more elements of a finite field F
-// https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.3
-// Inputs:
-// msg - a byte string containing the message to hash.
-// count - the number of elements of F to output.
-// Outputs:
-// [u_0, ..., u_(count - 1)], a list of field elements.
+export function expand_message_xof(msg, DST, lenInBytes, k, H) {
+    // https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-16#section-5.3.3
+    // DST = H('H2C-OVERSIZE-DST-' || a_very_long_DST, Math.ceil((lenInBytes * k) / 8));
+    if (DST.length > 255) {
+        const dkLen = Math.ceil((2 * k) / 8);
+        DST = H.create({ dkLen }).update(stringToBytes('H2C-OVERSIZE-DST-')).update(DST).digest();
+    }
+    if (lenInBytes > 65535 || DST.length > 255)
+        throw new Error('expand_message_xof: invalid lenInBytes');
+    return (H.create({ dkLen: lenInBytes })
+        .update(msg)
+        .update(i2osp(lenInBytes, 2))
+        // 2. DST_prime = DST || I2OSP(len(DST), 1)
+        .update(DST)
+        .update(i2osp(DST.length, 1))
+        .digest());
+}
+/**
+ * Hashes arbitrary-length byte strings to a list of one or more elements of a finite field F
+ * https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-11#section-5.3
+ * @param msg a byte string containing the message to hash
+ * @param count the number of elements of F to output
+ * @param options `{DST: string, p: bigint, m: number, k: number, expand: 'xmd' | 'xof', hash: H}`
+ * @returns [u_0, ..., u_(count - 1)], a list of field elements.
+ */
 export function hash_to_field(msg, count, options) {
     // if options is provided but incomplete, fill any missing fields with the
     // value in hftDefaults (ie hash to G2).
@@ -90,9 +108,12 @@ export function hash_to_field(msg, count, options) {
     const len_in_bytes = count * options.m * L;
     const DST = stringToBytes(options.DST);
     let pseudo_random_bytes = msg;
-    if (options.expand) {
+    if (options.expand === 'xmd') {
         pseudo_random_bytes = expand_message_xmd(msg, DST, len_in_bytes, options.hash);
     }
+    else if (options.expand === 'xof') {
+        pseudo_random_bytes = expand_message_xof(msg, DST, len_in_bytes, options.k, options.hash);
+    }
     const u = new Array(count);
     for (let i = 0; i < count; i++) {
         const e = new Array(options.m);