@noble/curves 2.0.0 → 2.2.0

package/abstract/weierstrass.js

@@ -27,17 +27,22 @@
 /*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
 import { hmac as nobleHmac } from '@noble/hashes/hmac.js';
 import { ahash } from '@noble/hashes/utils.js';
-import { abool, abytes, aInRange, bitLen, bitMask, bytesToHex, bytesToNumberBE, concatBytes, createHmacDrbg, hexToBytes, isBytes, memoized, numberToHexUnpadded, validateObject, randomBytes as wcRandomBytes, } from "../utils.js";
+import { abignumber, abool, abytes, aInRange, asafenumber, bitLen, bitMask, bytesToHex, bytesToNumberBE, concatBytes, createHmacDrbg, hexToBytes, isBytes, numberToHexUnpadded, validateObject, randomBytes as wcRandomBytes, } from "../utils.js";
 import { createCurveFields, createKeygen, mulEndoUnsafe, negateCt, normalizeZ, wNAF, } from "./curve.js";
-import { FpInvertBatch, getMinHashLength, mapHashToField, validateField, } from "./modular.js";
-// We construct basis in such way that den is always positive and equals n, but num sign depends on basis (not on secret value)
+import { FpInvertBatch, FpIsSquare, getMinHashLength, mapHashToField, validateField, } from "./modular.js";
+// We construct the basis so `den` is always positive and equals `n`,
+// but the `num` sign depends on the basis, not on the secret value.
+// Exact half-way cases round away from zero, which keeps the split symmetric
+// around the reduced-basis boundaries used by endomorphism decomposition.
 const divNearest = (num, den) => (num + (num >= 0 ? den : -den) / _2n) / den;
-/**
- * Splits scalar for GLV endomorphism.
- */
+/** Splits scalar for GLV endomorphism. */
 export function _splitEndoScalar(k, basis, n) {
     // Split scalar into two such that part is ~half bits: `abs(part) < sqrt(N)`
     // Since part can be negative, we need to do this on point.
+    // Callers must provide a reduced GLV basis whose vectors satisfy
+    // `a + b * lambda ≡ 0 (mod n)`; this helper only sees the basis and `n`.
+    // Reject unreduced scalars instead of silently treating them mod n.
+    aInRange('scalar', k, _0n, n);
     // TODO: verifyScalar function which consumes lambda
     const [[a1, b1], [a2, b2]] = basis;
     const c1 = divNearest(b2 * k, n);
@@ -53,10 +58,11 @@ export function _splitEndoScalar(k, basis, n) {
     if (k2neg)
         k2 = -k2;
     // Double check that resulting scalar less than half bits of N: otherwise wNAF will fail.
-    // This should only happen on wrong basises. Also, math inside is too complex and I don't trust it.
+    // This should only happen on wrong bases.
+    // Also, the math inside is complex enough that this guard is worth keeping.
     const MAX_NUM = bitMask(Math.ceil(bitLen(n) / 2)) + _1n; // Half bits of N
     if (k1 < _0n || k1 >= MAX_NUM || k2 < _0n || k2 >= MAX_NUM) {
-        throw new Error('splitScalar (endomorphism): failed, k=' + k);
+        throw new Error('splitScalar (endomorphism): failed for k');
     }
     return { k1neg, k1, k2neg, k2 };
 }
@@ -66,7 +72,11 @@ function validateSigFormat(format) {
     return format;
 }
 function validateSigOpts(opts, def) {
+    validateObject(opts);
     const optsn = {};
+    // Normalize only the declared option subset from `def`; unknown keys are
+    // intentionally ignored so shared / superset option bags stay valid here too.
+    // `extraEntropy` stays an opaque payload until the signing path consumes it.
     for (let optName of Object.keys(def)) {
         // @ts-ignore
         optsn[optName] = opts[optName] === undefined ? def[optName] : opts[optName];
@@ -77,6 +87,15 @@ function validateSigOpts(opts, def) {
         validateSigFormat(optsn.format);
     return optsn;
 }
+/**
+ * @param m - Error message.
+ * @example
+ * Throw a DER-specific error when signature parsing encounters invalid bytes.
+ *
+ * ```ts
+ * new DERErr('bad der');
+ * ```
+ */
 export class DERErr extends Error {
     constructor(m = '') {
         super(m);
@@ -87,7 +106,14 @@ export class DERErr extends Error {
  *
  *     [0x30 (SEQUENCE), bytelength, 0x02 (INTEGER), intLength, R, 0x02 (INTEGER), intLength, S]
  *
- * Docs: https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der/, https://luca.ntop.org/Teaching/Appunti/asn1.html
+ * Docs: {@link https://letsencrypt.org/docs/a-warm-welcome-to-asn1-and-der/ | Let's Encrypt ASN.1 guide} and
+ * {@link https://luca.ntop.org/Teaching/Appunti/asn1.html | Luca Deri's ASN.1 notes}.
+ * @example
+ * ASN.1 DER encoding utilities.
+ *
+ * ```ts
+ * const der = DER.hexFromSig({ r: 1n, s: 2n });
+ * ```
  */
 export const DER = {
     // asn.1 DER encoding utils
@@ -96,8 +122,13 @@ export const DER = {
     _tlv: {
         encode: (tag, data) => {
             const { Err: E } = DER;
-            if (tag < 0 || tag > 256)
+            asafenumber(tag, 'tag');
+            if (tag < 0 || tag > 255)
                 throw new E('tlv.encode: wrong tag');
+            if (typeof data !== 'string')
+                throw new TypeError('"data" expected string, got type=' + typeof data);
+            // Internal helper: callers hand this already-validated hex payload, so we only enforce
+            // byte alignment here instead of re-validating every nibble.
             if (data.length & 1)
                 throw new E('tlv.encode: unpadded data');
             const dataLen = data.length / 2;
@@ -112,13 +143,15 @@ export const DER = {
         // v - value, l - left bytes (unparsed)
         decode(tag, data) {
             const { Err: E } = DER;
+            data = abytes(data, undefined, 'DER data');
             let pos = 0;
-            if (tag < 0 || tag > 256)
+            if (tag < 0 || tag > 255)
                 throw new E('tlv.encode: wrong tag');
             if (data.length < 2 || data[pos++] !== tag)
                 throw new E('tlv.decode: wrong tlv');
             const first = data[pos++];
-            const isLong = !!(first & 0b1000_0000); // First bit of first length byte is flag for short/long form
+            // First bit of first length byte is the short/long form flag.
+            const isLong = !!(first & 0b1000_0000);
             let length = 0;
             if (!isLong)
                 length = first;
@@ -127,8 +160,9 @@ export const DER = {
                 const lenLen = first & 0b0111_1111;
                 if (!lenLen)
                     throw new E('tlv.decode(long): indefinite length not supported');
+                // This would overflow u32 in JS.
                 if (lenLen > 4)
-                    throw new E('tlv.decode(long): byte length is too big'); // this will overflow u32 in js
+                    throw new E('tlv.decode(long): byte length is too big');
                 const lengthBytes = data.subarray(pos, pos + lenLen);
                 if (lengthBytes.length !== lenLen)
                     throw new E('tlv.decode: length bytes not complete');
@@ -153,6 +187,7 @@ export const DER = {
     _int: {
         encode(num) {
             const { Err: E } = DER;
+            abignumber(num);
             if (num < _0n)
                 throw new E('integer: negative integers are not allowed');
             let hex = numberToHexUnpadded(num);
@@ -165,9 +200,12 @@ export const DER = {
         },
         decode(data) {
             const { Err: E } = DER;
+            if (data.length < 1)
+                throw new E('invalid signature integer: empty');
             if (data[0] & 0b1000_0000)
                 throw new E('invalid signature integer: negative');
-            if (data[0] === 0x00 && !(data[1] & 0b1000_0000))
+            // Single-byte zero `00` is the canonical DER INTEGER encoding for zero.
+            if (data.length > 1 && data[0] === 0x00 && !(data[1] & 0b1000_0000))
                 throw new E('invalid signature integer: unnecessary leading zero');
             return bytesToNumberBE(data);
         },
@@ -193,31 +231,41 @@ export const DER = {
         return tlv.encode(0x30, seq);
     },
 };
+Object.freeze(DER._tlv);
+Object.freeze(DER._int);
+Object.freeze(DER);
 // Be friendly to bad ECMAScript parsers by not using bigint literals
 // prettier-ignore
-const _0n = BigInt(0), _1n = BigInt(1), _2n = BigInt(2), _3n = BigInt(3), _4n = BigInt(4);
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1), _2n = /* @__PURE__ */ BigInt(2), _3n = /* @__PURE__ */ BigInt(3), _4n = /* @__PURE__ */ BigInt(4);
 /**
  * Creates weierstrass Point constructor, based on specified curve options.
  *
  * See {@link WeierstrassOpts}.
+ * @param params - Curve parameters. See {@link WeierstrassOpts}.
+ * @param extraOpts - Optional helpers and overrides. See {@link WeierstrassExtraOpts}.
+ * @returns Weierstrass point constructor.
+ * @throws If the curve parameters, overrides, or point codecs are invalid. {@link Error}
  *
  * @example
-```js
-const opts = {
-  p: 0xfffffffffffffffffffffffffffffffeffffac73n,
-  n: 0x100000000000000000001b8fa16dfab9aca16b6b3n,
-  h: 1n,
-  a: 0n,
-  b: 7n,
-  Gx: 0x3b4c382ce37aa192a4019e763036f4f5dd4d7ebbn,
-  Gy: 0x938cf935318fdced6bc28286531733c3f03c4feen,
-};
-const secp160k1_Point = weierstrass(opts);
-```
+ * Construct a point type from explicit Weierstrass curve parameters.
+ *
+ * ```js
+ * const opts = {
+ *   p: 0xfffffffffffffffffffffffffffffffeffffac73n,
+ *   n: 0x100000000000000000001b8fa16dfab9aca16b6b3n,
+ *   h: 1n,
+ *   a: 0n,
+ *   b: 7n,
+ *   Gx: 0x3b4c382ce37aa192a4019e763036f4f5dd4d7ebbn,
+ *   Gy: 0x938cf935318fdced6bc28286531733c3f03c4feen,
+ * };
+ * const secp160k1_Point = weierstrass(opts);
+ * ```
  */
 export function weierstrass(params, extraOpts = {}) {
     const validated = createCurveFields('weierstrass', params, extraOpts);
-    const { Fp, Fn } = validated;
+    const Fp = validated.Fp;
+    const Fn = validated.Fn;
     let CURVE = validated.CURVE;
     const { h: cofactor, n: CURVE_ORDER } = CURVE;
     validateObject(extraOpts, {}, {
@@ -228,7 +276,9 @@ export function weierstrass(params, extraOpts = {}) {
         toBytes: 'function',
         endo: 'object',
     });
-    const { endo } = extraOpts;
+    // Snapshot constructor-time flags whose later mutation would otherwise change
+    // validity semantics of an already-built point type.
+    const { endo, allowInfinityPoint } = extraOpts;
     if (endo) {
         // validateObject(endo, { beta: 'bigint', splitScalar: 'function' });
         if (!Fp.is0(CURVE.a) || typeof endo.beta !== 'bigint' || !Array.isArray(endo.basises)) {
@@ -242,6 +292,10 @@ export function weierstrass(params, extraOpts = {}) {
     }
     // Implements IEEE P1363 point encoding
     function pointToBytes(_c, point, isCompressed) {
+        // SEC 1 v2.0 §2.3.3 encodes infinity as the single octet 0x00. Only curves
+        // that opt into infinity as a public point value should expose that byte form.
+        if (allowInfinityPoint && point.is0())
+            return Uint8Array.of(0);
         const { x, y } = point.toAffine();
         const bx = Fp.toBytes(x);
         abool(isCompressed, 'isCompressed');
@@ -260,6 +314,13 @@ export function weierstrass(params, extraOpts = {}) {
         const length = bytes.length;
         const head = bytes[0];
         const tail = bytes.subarray(1);
+        if (allowInfinityPoint && length === 1 && head === 0x00)
+            return { x: Fp.ZERO, y: Fp.ZERO };
+        // SEC 1 v2.0 §2.3.4 decodes 0x00 as infinity, but §3.2.2 public-key validation
+        // rejects infinity. We therefore keep 0x00 rejected by default because callers
+        // reuse this parser as the strict public-key boundary, and only admit it when
+        // the curve explicitly opts into infinity as a public point value. secp256k1
+        // crosstests show OpenSSL raw point codecs accept 0x00 too.
         // No actual validation is done here: use .assertValidity()
         if (length === comp && (head === 0x02 || head === 0x03)) {
             const x = Fp.fromBytes(tail);
@@ -294,8 +355,8 @@ export function weierstrass(params, extraOpts = {}) {
             throw new Error(`bad point: got length ${length}, expected compressed=${comp} or uncompressed=${uncomp}`);
         }
     }
-    const encodePoint = extraOpts.toBytes || pointToBytes;
-    const decodePoint = extraOpts.fromBytes || pointFromBytes;
+    const encodePoint = extraOpts.toBytes === undefined ? pointToBytes : extraOpts.toBytes;
+    const decodePoint = extraOpts.fromBytes === undefined ? pointFromBytes : extraOpts.fromBytes;
     function weierstrassEquation(x) {
         const x2 = Fp.sqr(x); // x * x
         const x3 = Fp.mul(x2, x); // x² * x
@@ -308,7 +369,8 @@ export function weierstrass(params, extraOpts = {}) {
         const right = weierstrassEquation(x); // x³ + ax + b
         return Fp.eql(left, right);
     }
-    // Validate whether the passed curve params are valid.
+    // Keep constructor-time generator validation cheap: callers are responsible for supplying the
+    // correct prime-order base point, while eager subgroup checks here would slow heavy module imports.
     // Test 1: equation y² = x³ + ax + b should work for generator point.
     if (!isValidXY(CURVE.Gx, CURVE.Gy))
         throw new Error('bad curve params: generator point');
@@ -333,50 +395,6 @@ export function weierstrass(params, extraOpts = {}) {
             throw new Error('no endo');
         return _splitEndoScalar(k, endo.basises, Fn.ORDER);
     }
-    // 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, iz) => {
-        const { X, Y, Z } = p;
-        // Fast-path for normalized points
-        if (Fp.eql(Z, Fp.ONE))
-            return { x: X, y: 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 x = Fp.mul(X, iz);
-        const y = 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, y };
-    });
-    // NOTE: on exception this will crash 'cached' and no value will be set.
-    // Otherwise true will be return
-    const assertValidMemo = memoized((p) => {
-        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 invalid representation of ZERO.
-            if (extraOpts.allowInfinityPoint && !Fp.is0(p.Y))
-                return;
-            throw new Error('bad point: ZERO');
-        }
-        // Some 3rd-party test vectors require different wording between here & `fromCompressedHex`
-        const { x, y } = p.toAffine();
-        if (!Fp.isValid(x) || !Fp.isValid(y))
-            throw new Error('bad point: x or y not field elements');
-        if (!isValidXY(x, y))
-            throw new Error('bad point: equation left != right');
-        if (!p.isTorsionFree())
-            throw new Error('bad point: not in prime-order subgroup');
-        return true;
-    });
     function finishEndo(endoBeta, k1p, k2p, k1neg, k2neg) {
         k2p = new Point(Fp.mul(k2p.X, endoBeta), k2p.Y, k2p.Z);
         k1p = negateCt(k1neg, k1p);
@@ -403,6 +421,9 @@ export function weierstrass(params, extraOpts = {}) {
         /** Does NOT validate if the point is valid. Use `.assertValidity()`. */
         constructor(X, Y, Z) {
             this.X = acoord('x', X);
+            // This is not just about ZERO / infinity: ambient curves can have real
+            // finite points with y=0. Those points are 2-torsion, so they cannot lie
+            // in the odd prime-order subgroups this point type is meant to represent.
             this.Y = acoord('y', Y, true);
             this.Z = acoord('z', Z);
             Object.freeze(this);
@@ -439,7 +460,7 @@ export function weierstrass(params, extraOpts = {}) {
         /**
          *
          * @param windowSize
-         * @param isLazy true will defer table computation until the first multiplication
+         * @param isLazy - true will defer table computation until the first multiplication
          * @returns
          */
         precompute(windowSize = 8, isLazy = true) {
@@ -451,7 +472,24 @@ export function weierstrass(params, extraOpts = {}) {
         // TODO: return `this`
         /** A point on curve is valid if it conforms to equation. */
         assertValidity() {
-            assertValidMemo(this);
+            const p = this;
+            if (p.is0()) {
+                // (0, 1, 0) aka ZERO is invalid in most contexts.
+                // In BLS, ZERO can be serialized, so we allow it.
+                // Keep the accepted infinity encoding canonical: projective-equivalent (X, Y, 0) points
+                // like (1, 1, 0) compare equal to ZERO, but only (0, 1, 0) should pass this guard.
+                if (extraOpts.allowInfinityPoint && Fp.is0(p.X) && Fp.eql(p.Y, Fp.ONE) && Fp.is0(p.Z))
+                    return;
+                throw new Error('bad point: ZERO');
+            }
+            // Some 3rd-party test vectors require different wording between here & `fromCompressedHex`
+            const { x, y } = p.toAffine();
+            if (!Fp.isValid(x) || !Fp.isValid(y))
+                throw new Error('bad point: x or y not field elements');
+            if (!isValidXY(x, y))
+                throw new Error('bad point: equation left != right');
+            if (!p.isTorsionFree())
+                throw new Error('bad point: not in prime-order subgroup');
         }
         hasEvenY() {
             const { y } = this.toAffine();
@@ -568,6 +606,9 @@ export function weierstrass(params, extraOpts = {}) {
             return new Point(X3, Y3, Z3);
         }
         subtract(other) {
+            // Validate before calling `negate()` so wrong inputs fail with the point guard
+            // instead of leaking a foreign `negate()` error.
+            aprjpoint(other);
             return this.add(other.negate());
         }
         is0() {
@@ -579,13 +620,16 @@ export function weierstrass(params, extraOpts = {}) {
          * but takes 2x longer to generate and consumes 2x memory.
          * Uses precomputes when available.
          * Uses endomorphism for Koblitz curves.
-         * @param scalar by which the point would be multiplied
+         * @param scalar - by which the point would be multiplied
          * @returns New point
          */
         multiply(scalar) {
             const { endo } = extraOpts;
+            // Keep the subgroup-scalar contract strict instead of reducing 0 / n to ZERO.
+            // In key/signature-style callers, those values usually mean broken hash/scalar plumbing,
+            // and failing closed is safer than silently producing the identity point.
             if (!Fn.isValidNot0(scalar))
-                throw new Error('invalid scalar: out of range'); // 0 is invalid
+                throw new RangeError('invalid scalar: out of range'); // 0 is invalid
             let point, fake; // Fake point is used to const-time mult
             const mul = (n) => wnaf.cached(this, n, (p) => normalizeZ(Point, p));
             /** See docs for {@link EndomorphismOpts} */
@@ -609,11 +653,14 @@ export function weierstrass(params, extraOpts = {}) {
          * It's faster, but should only be used when you don't care about
          * an exposed secret key e.g. sig verification, which works over *public* keys.
          */
-        multiplyUnsafe(sc) {
+        multiplyUnsafe(scalar) {
             const { endo } = extraOpts;
             const p = this;
+            const sc = scalar;
+            // Public-scalar callers may need 0, but n and larger values stay rejected here too.
+            // Reducing them mod n would turn bad caller input into an accidental identity point.
             if (!Fn.isValid(sc))
-                throw new Error('invalid scalar: out of range'); // 0 is valid
+                throw new RangeError('invalid scalar: out of range'); // 0 is valid
             if (sc === _0n || p.is0())
                 return Point.ZERO; // 0
             if (sc === _1n)
@@ -633,10 +680,29 @@ export function weierstrass(params, extraOpts = {}) {
         }
         /**
          * Converts Projective point to affine (x, y) coordinates.
-         * @param invertedZ Z^-1 (inverted zero) - optional, precomputation is useful for invertBatch
+         * (X, Y, Z) ∋ (x=X/Z, y=Y/Z).
+         * @param invertedZ - Z^-1 (inverted zero) - optional, precomputation is useful for invertBatch
          */
         toAffine(invertedZ) {
-            return toAffineMemo(this, invertedZ);
+            const p = this;
+            let iz = invertedZ;
+            const { X, Y, Z } = p;
+            // Fast-path for normalized points
+            if (Fp.eql(Z, Fp.ONE))
+                return { x: X, y: 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 x = Fp.mul(X, iz);
+            const y = 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, y };
         }
         /**
          * Checks whether Point is free of torsion elements (is in prime subgroup).
@@ -656,14 +722,20 @@ export function weierstrass(params, extraOpts = {}) {
                 return this; // Fast-path
             if (clearCofactor)
                 return clearCofactor(Point, this);
+            // Default fallback assumes the cofactor fits the usual subgroup-scalar
+            // multiplyUnsafe() contract. Curves with larger / structured cofactors
+            // should define a clearCofactor override anyway (e.g. psi/Frobenius maps).
             return this.multiplyUnsafe(cofactor);
         }
         isSmallOrder() {
-            // can we use this.clearCofactor()?
-            return this.multiplyUnsafe(cofactor).is0();
+            if (cofactor === _1n)
+                return this.is0(); // Fast-path
+            return this.clearCofactor().is0();
         }
         toBytes(isCompressed = true) {
             abool(isCompressed, 'isCompressed');
+            // Same policy as pointFromBytes(): keep ZERO out of the default byte surface because
+            // callers use these encodings as public keys, where SEC 1 validation rejects infinity.
             this.assertValidity();
             return encodePoint(Point, this, isCompressed);
         }
@@ -676,7 +748,12 @@ export function weierstrass(params, extraOpts = {}) {
     }
     const bits = Fn.BITS;
     const wnaf = new wNAF(Point, extraOpts.endo ? Math.ceil(bits / 2) : bits);
-    Point.BASE.precompute(8); // Enable precomputes. Slows down first publicKey computation by 20ms.
+    // Tiny toy curves can have scalar fields narrower than 8 bits. Skip the
+    // eager W=8 cache there instead of rejecting an otherwise valid constructor.
+    if (bits >= 8)
+        Point.BASE.precompute(8); // Enable precomputes. Slows down first publicKey computation by 20ms.
+    Object.freeze(Point.prototype);
+    Object.freeze(Point);
     return Point;
 }
 // Points start with byte 0x02 when y is even; otherwise 0x03
@@ -688,13 +765,26 @@ function pprefix(hasEvenY) {
  * TODO: check if there is a way to merge this with uvRatio in Edwards; move to modular.
  * b = True and y = sqrt(u / v) if (u / v) is square in F, and
  * b = False and y = sqrt(Z * (u / v)) otherwise.
- * @param Fp
- * @param Z
- * @returns
+ * RFC 9380 expects callers to provide `v != 0`; this helper does not enforce it.
+ * @param Fp - Field implementation.
+ * @param Z - Simplified SWU map parameter.
+ * @returns Square-root ratio helper.
+ * @example
+ * Build the square-root ratio helper used by SWU map implementations.
+ *
+ * ```ts
+ * import { SWUFpSqrtRatio } from '@noble/curves/abstract/weierstrass.js';
+ * import { Field } from '@noble/curves/abstract/modular.js';
+ * const Fp = Field(17n);
+ * const sqrtRatio = SWUFpSqrtRatio(Fp, 3n);
+ * const out = sqrtRatio(4n, 1n);
+ * ```
  */
 export function SWUFpSqrtRatio(Fp, Z) {
+    // Fail with the usual field-shape error before touching pow/cmov on malformed field shims.
+    const F = validateField(Fp);
     // Generic implementation
-    const q = Fp.ORDER;
+    const q = F.ORDER;
     let l = _0n;
     for (let o = q - _1n; o % _2n === _0n; o /= _2n)
         l += _1n;
@@ -707,54 +797,60 @@ export function SWUFpSqrtRatio(Fp, Z) {
     const c3 = (c2 - _1n) / _2n; // 3. c3 = (c2 - 1) / 2            # Integer arithmetic
     const c4 = _2n_pow_c1 - _1n; // 4. c4 = 2^c1 - 1                # Integer arithmetic
     const c5 = _2n_pow_c1_1; // 5. c5 = 2^(c1 - 1)                  # Integer arithmetic
-    const c6 = Fp.pow(Z, c2); // 6. c6 = Z^c2
-    const c7 = Fp.pow(Z, (c2 + _1n) / _2n); // 7. c7 = Z^((c2 + 1) / 2)
+    const c6 = F.pow(Z, c2); // 6. c6 = Z^c2
+    const c7 = F.pow(Z, (c2 + _1n) / _2n); // 7. c7 = Z^((c2 + 1) / 2)
+    // RFC 9380 Appendix F.2.1.1 defines sqrt_ratio(u, v) only for v != 0.
+    // We keep v=0 on the regular result path with isValid=false instead of
+    // throwing so the helper stays closer to the RFC's fixed control flow.
     let sqrtRatio = (u, v) => {
         let tv1 = c6; // 1. tv1 = c6
-        let tv2 = Fp.pow(v, c4); // 2. tv2 = v^c4
-        let tv3 = Fp.sqr(tv2); // 3. tv3 = tv2^2
-        tv3 = Fp.mul(tv3, v); // 4. tv3 = tv3 * v
-        let tv5 = Fp.mul(u, tv3); // 5. tv5 = u * tv3
-        tv5 = Fp.pow(tv5, c3); // 6. tv5 = tv5^c3
-        tv5 = Fp.mul(tv5, tv2); // 7. tv5 = tv5 * tv2
-        tv2 = Fp.mul(tv5, v); // 8. tv2 = tv5 * v
-        tv3 = Fp.mul(tv5, u); // 9. tv3 = tv5 * u
-        let tv4 = Fp.mul(tv3, tv2); // 10. tv4 = tv3 * tv2
-        tv5 = Fp.pow(tv4, c5); // 11. tv5 = tv4^c5
-        let isQR = Fp.eql(tv5, Fp.ONE); // 12. isQR = tv5 == 1
-        tv2 = Fp.mul(tv3, c7); // 13. tv2 = tv3 * c7
-        tv5 = Fp.mul(tv4, tv1); // 14. tv5 = tv4 * tv1
-        tv3 = Fp.cmov(tv2, tv3, isQR); // 15. tv3 = CMOV(tv2, tv3, isQR)
-        tv4 = Fp.cmov(tv5, tv4, isQR); // 16. tv4 = CMOV(tv5, tv4, isQR)
+        let tv2 = F.pow(v, c4); // 2. tv2 = v^c4
+        let tv3 = F.sqr(tv2); // 3. tv3 = tv2^2
+        tv3 = F.mul(tv3, v); // 4. tv3 = tv3 * v
+        let tv5 = F.mul(u, tv3); // 5. tv5 = u * tv3
+        tv5 = F.pow(tv5, c3); // 6. tv5 = tv5^c3
+        tv5 = F.mul(tv5, tv2); // 7. tv5 = tv5 * tv2
+        tv2 = F.mul(tv5, v); // 8. tv2 = tv5 * v
+        tv3 = F.mul(tv5, u); // 9. tv3 = tv5 * u
+        let tv4 = F.mul(tv3, tv2); // 10. tv4 = tv3 * tv2
+        tv5 = F.pow(tv4, c5); // 11. tv5 = tv4^c5
+        let isQR = F.eql(tv5, F.ONE); // 12. isQR = tv5 == 1
+        tv2 = F.mul(tv3, c7); // 13. tv2 = tv3 * c7
+        tv5 = F.mul(tv4, tv1); // 14. tv5 = tv4 * tv1
+        tv3 = F.cmov(tv2, tv3, isQR); // 15. tv3 = CMOV(tv2, tv3, isQR)
+        tv4 = F.cmov(tv5, tv4, isQR); // 16. tv4 = CMOV(tv5, tv4, isQR)
         // 17. for i in (c1, c1 - 1, ..., 2):
         for (let i = c1; i > _1n; i--) {
             let tv5 = i - _2n; // 18.    tv5 = i - 2
             tv5 = _2n << (tv5 - _1n); // 19.    tv5 = 2^tv5
-            let tvv5 = Fp.pow(tv4, tv5); // 20.    tv5 = tv4^tv5
-            const e1 = Fp.eql(tvv5, Fp.ONE); // 21.    e1 = tv5 == 1
-            tv2 = Fp.mul(tv3, tv1); // 22.    tv2 = tv3 * tv1
-            tv1 = Fp.mul(tv1, tv1); // 23.    tv1 = tv1 * tv1
-            tvv5 = Fp.mul(tv4, tv1); // 24.    tv5 = tv4 * tv1
-            tv3 = Fp.cmov(tv2, tv3, e1); // 25.    tv3 = CMOV(tv2, tv3, e1)
-            tv4 = Fp.cmov(tvv5, tv4, e1); // 26.    tv4 = CMOV(tv5, tv4, e1)
+            let tvv5 = F.pow(tv4, tv5); // 20.    tv5 = tv4^tv5
+            const e1 = F.eql(tvv5, F.ONE); // 21.    e1 = tv5 == 1
+            tv2 = F.mul(tv3, tv1); // 22.    tv2 = tv3 * tv1
+            tv1 = F.mul(tv1, tv1); // 23.    tv1 = tv1 * tv1
+            tvv5 = F.mul(tv4, tv1); // 24.    tv5 = tv4 * tv1
+            tv3 = F.cmov(tv2, tv3, e1); // 25.    tv3 = CMOV(tv2, tv3, e1)
+            tv4 = F.cmov(tvv5, tv4, e1); // 26.    tv4 = CMOV(tv5, tv4, e1)
         }
-        return { isValid: isQR, value: tv3 };
+        // RFC 9380 Appendix F.2.1.1 defines sqrt_ratio(u, v) for v != 0.
+        // When u = 0 and v != 0, u / v = 0 is square and the computed root is
+        // still 0, so widen only the final flag and keep the full control flow.
+        return { isValid: !F.is0(v) && (isQR || F.is0(u)), value: tv3 };
     };
-    if (Fp.ORDER % _4n === _3n) {
+    if (F.ORDER % _4n === _3n) {
         // sqrt_ratio_3mod4(u, v)
-        const c1 = (Fp.ORDER - _3n) / _4n; // 1. c1 = (q - 3) / 4     # Integer arithmetic
-        const c2 = Fp.sqrt(Fp.neg(Z)); // 2. c2 = sqrt(-Z)
+        const c1 = (F.ORDER - _3n) / _4n; // 1. c1 = (q - 3) / 4     # Integer arithmetic
+        const c2 = F.sqrt(F.neg(Z)); // 2. c2 = sqrt(-Z)
         sqrtRatio = (u, v) => {
-            let tv1 = Fp.sqr(v); // 1. tv1 = v^2
-            const tv2 = Fp.mul(u, v); // 2. tv2 = u * v
-            tv1 = Fp.mul(tv1, tv2); // 3. tv1 = tv1 * tv2
-            let y1 = Fp.pow(tv1, c1); // 4. y1 = tv1^c1
-            y1 = Fp.mul(y1, tv2); // 5. y1 = y1 * tv2
-            const y2 = Fp.mul(y1, c2); // 6. y2 = y1 * c2
-            const tv3 = Fp.mul(Fp.sqr(y1), v); // 7. tv3 = y1^2; 8. tv3 = tv3 * v
-            const isQR = Fp.eql(tv3, u); // 9. isQR = tv3 == u
-            let y = Fp.cmov(y2, y1, isQR); // 10. y = CMOV(y2, y1, isQR)
-            return { isValid: isQR, value: y }; // 11. return (isQR, y) isQR ? y : y*c2
+            let tv1 = F.sqr(v); // 1. tv1 = v^2
+            const tv2 = F.mul(u, v); // 2. tv2 = u * v
+            tv1 = F.mul(tv1, tv2); // 3. tv1 = tv1 * tv2
+            let y1 = F.pow(tv1, c1); // 4. y1 = tv1^c1
+            y1 = F.mul(y1, tv2); // 5. y1 = y1 * tv2
+            const y2 = F.mul(y1, c2); // 6. y2 = y1 * c2
+            const tv3 = F.mul(F.sqr(y1), v); // 7. tv3 = y1^2; 8. tv3 = tv3 * v
+            const isQR = F.eql(tv3, u); // 9. isQR = tv3 == u
+            let y = F.cmov(y2, y1, isQR); // 10. y = CMOV(y2, y1, isQR)
+            return { isValid: !F.is0(v) && isQR, value: y }; // 11. return (isQR, y) isQR ? y : y*c2
         };
     }
     // No curves uses that
@@ -763,47 +859,82 @@ export function SWUFpSqrtRatio(Fp, Z) {
 }
 /**
  * Simplified Shallue-van de Woestijne-Ulas Method
- * https://www.rfc-editor.org/rfc/rfc9380#section-6.6.2
+ * See {@link https://www.rfc-editor.org/rfc/rfc9380#section-6.6.2 | RFC 9380 section 6.6.2}.
+ * @param Fp - Field implementation.
+ * @param opts - SWU parameters:
+ *   - `A`: Curve parameter `A`.
+ *   - `B`: Curve parameter `B`.
+ *   - `Z`: Simplified SWU map parameter.
+ * @returns Deterministic map-to-curve function.
+ * @throws If the SWU parameters are invalid or the field lacks the required helpers. {@link Error}
+ * @example
+ * Map one field element to a Weierstrass curve point with the SWU recipe.
+ *
+ * ```ts
+ * import { mapToCurveSimpleSWU } from '@noble/curves/abstract/weierstrass.js';
+ * import { Field } from '@noble/curves/abstract/modular.js';
+ * const Fp = Field(17n);
+ * const map = mapToCurveSimpleSWU(Fp, { A: 1n, B: 2n, Z: 3n });
+ * const point = map(5n);
+ * ```
  */
 export function mapToCurveSimpleSWU(Fp, opts) {
-    validateField(Fp);
+    const F = validateField(Fp);
     const { A, B, Z } = opts;
-    if (!Fp.isValid(A) || !Fp.isValid(B) || !Fp.isValid(Z))
+    if (!F.isValidNot0(A) || !F.isValidNot0(B) || !F.isValid(Z))
         throw new Error('mapToCurveSimpleSWU: invalid opts');
-    const sqrtRatio = SWUFpSqrtRatio(Fp, Z);
-    if (!Fp.isOdd)
+    // RFC 9380 §6.6.2 and Appendix H.2 require:
+    // 1. Z is non-square in F
+    // 2. Z != -1 in F
+    // 3. g(x) - Z is irreducible over F
+    // 4. g(B / (Z * A)) is square in F
+    // We can enforce 1, 2, and 4 with the current field API.
+    // Criterion 3 is not checked here because generic `IField<T>` does not expose
+    // polynomial-ring / irreducibility operations, and this helper is used for
+    // both prime and extension fields.
+    if (F.eql(Z, F.neg(F.ONE)) || FpIsSquare(F, Z))
+        throw new Error('mapToCurveSimpleSWU: invalid opts');
+    // RFC 9380 Appendix H.2 criterion 4: g(B / (Z * A)) is square in F.
+    // x = B / (Z * A)
+    const x = F.mul(B, F.inv(F.mul(Z, A)));
+    // g(x) = x^3 + A*x + B
+    const gx = F.add(F.add(F.mul(F.sqr(x), x), F.mul(A, x)), B);
+    if (!FpIsSquare(F, gx))
+        throw new Error('mapToCurveSimpleSWU: invalid opts');
+    const sqrtRatio = SWUFpSqrtRatio(F, Z);
+    if (!F.isOdd)
         throw new Error('Field does not have .isOdd()');
     // Input: u, an element of F.
     // Output: (x, y), a point on E.
     return (u) => {
         // prettier-ignore
         let tv1, tv2, tv3, tv4, tv5, tv6, x, y;
-        tv1 = Fp.sqr(u); // 1.  tv1 = u^2
-        tv1 = Fp.mul(tv1, Z); // 2.  tv1 = Z * tv1
-        tv2 = Fp.sqr(tv1); // 3.  tv2 = tv1^2
-        tv2 = Fp.add(tv2, tv1); // 4.  tv2 = tv2 + tv1
-        tv3 = Fp.add(tv2, Fp.ONE); // 5.  tv3 = tv2 + 1
-        tv3 = Fp.mul(tv3, B); // 6.  tv3 = B * tv3
-        tv4 = Fp.cmov(Z, Fp.neg(tv2), !Fp.eql(tv2, Fp.ZERO)); // 7.  tv4 = CMOV(Z, -tv2, tv2 != 0)
-        tv4 = Fp.mul(tv4, A); // 8.  tv4 = A * tv4
-        tv2 = Fp.sqr(tv3); // 9.  tv2 = tv3^2
-        tv6 = Fp.sqr(tv4); // 10. tv6 = tv4^2
-        tv5 = Fp.mul(tv6, A); // 11. tv5 = A * tv6
-        tv2 = Fp.add(tv2, tv5); // 12. tv2 = tv2 + tv5
-        tv2 = Fp.mul(tv2, tv3); // 13. tv2 = tv2 * tv3
-        tv6 = Fp.mul(tv6, tv4); // 14. tv6 = tv6 * tv4
-        tv5 = Fp.mul(tv6, B); // 15. tv5 = B * tv6
-        tv2 = Fp.add(tv2, tv5); // 16. tv2 = tv2 + tv5
-        x = Fp.mul(tv1, tv3); // 17.   x = tv1 * tv3
+        tv1 = F.sqr(u); // 1.  tv1 = u^2
+        tv1 = F.mul(tv1, Z); // 2.  tv1 = Z * tv1
+        tv2 = F.sqr(tv1); // 3.  tv2 = tv1^2
+        tv2 = F.add(tv2, tv1); // 4.  tv2 = tv2 + tv1
+        tv3 = F.add(tv2, F.ONE); // 5.  tv3 = tv2 + 1
+        tv3 = F.mul(tv3, B); // 6.  tv3 = B * tv3
+        tv4 = F.cmov(Z, F.neg(tv2), !F.eql(tv2, F.ZERO)); // 7.  tv4 = CMOV(Z, -tv2, tv2 != 0)
+        tv4 = F.mul(tv4, A); // 8.  tv4 = A * tv4
+        tv2 = F.sqr(tv3); // 9.  tv2 = tv3^2
+        tv6 = F.sqr(tv4); // 10. tv6 = tv4^2
+        tv5 = F.mul(tv6, A); // 11. tv5 = A * tv6
+        tv2 = F.add(tv2, tv5); // 12. tv2 = tv2 + tv5
+        tv2 = F.mul(tv2, tv3); // 13. tv2 = tv2 * tv3
+        tv6 = F.mul(tv6, tv4); // 14. tv6 = tv6 * tv4
+        tv5 = F.mul(tv6, B); // 15. tv5 = B * tv6
+        tv2 = F.add(tv2, tv5); // 16. tv2 = tv2 + tv5
+        x = F.mul(tv1, tv3); // 17.   x = tv1 * tv3
         const { isValid, value } = sqrtRatio(tv2, tv6); // 18. (is_gx1_square, y1) = sqrt_ratio(tv2, tv6)
-        y = Fp.mul(tv1, u); // 19.   y = tv1 * u  -> Z * u^3 * y1
-        y = Fp.mul(y, value); // 20.   y = y * y1
-        x = Fp.cmov(x, tv3, isValid); // 21.   x = CMOV(x, tv3, is_gx1_square)
-        y = Fp.cmov(y, value, isValid); // 22.   y = CMOV(y, y1, is_gx1_square)
-        const e1 = Fp.isOdd(u) === Fp.isOdd(y); // 23.  e1 = sgn0(u) == sgn0(y)
-        y = Fp.cmov(Fp.neg(y), y, e1); // 24.   y = CMOV(-y, y, e1)
-        const tv4_inv = FpInvertBatch(Fp, [tv4], true)[0];
-        x = Fp.mul(x, tv4_inv); // 25.   x = x / tv4
+        y = F.mul(tv1, u); // 19.   y = tv1 * u  -> Z * u^3 * y1
+        y = F.mul(y, value); // 20.   y = y * y1
+        x = F.cmov(x, tv3, isValid); // 21.   x = CMOV(x, tv3, is_gx1_square)
+        y = F.cmov(y, value, isValid); // 22.   y = CMOV(y, y1, is_gx1_square)
+        const e1 = F.isOdd(u) === F.isOdd(y); // 23.  e1 = sgn0(u) == sgn0(y)
+        y = F.cmov(F.neg(y), y, e1); // 24.   y = CMOV(-y, y, e1)
+        const tv4_inv = FpInvertBatch(F, [tv4], true)[0];
+        x = F.mul(x, tv4_inv); // 25.   x = x / tv4
         return { x, y };
     };
 }
@@ -813,17 +944,37 @@ function getWLengths(Fp, Fn) {
         publicKey: 1 + Fp.BYTES,
         publicKeyUncompressed: 1 + 2 * Fp.BYTES,
         publicKeyHasPrefix: true,
+        // Raw compact `(r || s)` signature width; DER and recovered signatures use
+        // different lengths outside this helper.
         signature: 2 * Fn.BYTES,
     };
 }
 /**
  * Sometimes users only need getPublicKey, getSharedSecret, and secret key handling.
  * This helper ensures no signature functionality is present. Less code, smaller bundle size.
+ * @param Point - Weierstrass point constructor.
+ * @param ecdhOpts - Optional randomness helpers:
+ *   - `randomBytes` (optional): Optional RNG override.
+ * @returns ECDH helper namespace.
+ * @example
+ * Sometimes users only need getPublicKey, getSharedSecret, and secret key handling.
+ *
+ * ```ts
+ * import { ecdh } from '@noble/curves/abstract/weierstrass.js';
+ * import { p256 } from '@noble/curves/nist.js';
+ * const dh = ecdh(p256.Point);
+ * const alice = dh.keygen();
+ * const shared = dh.getSharedSecret(alice.secretKey, alice.publicKey);
+ * ```
  */
 export function ecdh(Point, ecdhOpts = {}) {
     const { Fn } = Point;
-    const randomBytes_ = ecdhOpts.randomBytes || wcRandomBytes;
-    const lengths = Object.assign(getWLengths(Point.Fp, Fn), { seed: getMinHashLength(Fn.ORDER) });
+    const randomBytes_ = ecdhOpts.randomBytes === undefined ? wcRandomBytes : ecdhOpts.randomBytes;
+    // Keep the advertised seed length aligned with mapHashToField(), which keeps a hard 16-byte
+    // minimum even on toy curves.
+    const lengths = Object.assign(getWLengths(Point.Fp, Fn), {
+        seed: Math.max(getMinHashLength(Fn.ORDER), 16),
+    });
     function isValidSecretKey(secretKey) {
         try {
             const num = Fn.fromBytes(secretKey);
@@ -851,12 +1002,13 @@ export function ecdh(Point, ecdhOpts = {}) {
      * Produces cryptographically secure secret key from random of size
      * (groupLen + ceil(groupLen / 2)) with modulo bias being negligible.
      */
-    function randomSecretKey(seed = randomBytes_(lengths.seed)) {
+    function randomSecretKey(seed) {
+        seed = seed === undefined ? randomBytes_(lengths.seed) : seed;
         return mapHashToField(abytes(seed, lengths.seed, 'seed'), Fn.ORDER);
     }
     /**
      * Computes public key for a secret key. Checks for validity of the secret key.
-     * @param isCompressed whether to return compact (default), or full key
+     * @param isCompressed - whether to return compact (default), or full key
      * @returns Public key, full when isCompressed=false; short when isCompressed=true
      */
     function getPublicKey(secretKey, isCompressed = true) {
@@ -867,20 +1019,28 @@ export function ecdh(Point, ecdhOpts = {}) {
      */
     function isProbPub(item) {
         const { secretKey, publicKey, publicKeyUncompressed } = lengths;
+        const allowedLengths = Fn._lengths;
         if (!isBytes(item))
             return undefined;
-        if (('_lengths' in Fn && Fn._lengths) || secretKey === publicKey)
-            return undefined;
         const l = abytes(item, undefined, 'key').length;
-        return l === publicKey || l === publicKeyUncompressed;
+        const isPub = l === publicKey || l === publicKeyUncompressed;
+        const isSec = l === secretKey || !!allowedLengths?.includes(l);
+        // P-521 accepts both 65- and 66-byte secret keys, so overlapping lengths stay ambiguous.
+        if (isPub && isSec)
+            return undefined;
+        return isPub;
     }
     /**
      * ECDH (Elliptic Curve Diffie Hellman).
-     * Computes shared public key from secret key A and public key B.
+     * Computes encoded shared point from secret key A and public key B.
      * Checks: 1) secret key validity 2) shared key is on-curve.
-     * Does NOT hash the result.
-     * @param isCompressed whether to return compact (default), or full key
-     * @returns shared public key
+     * Does NOT hash the result or expose the SEC 1 x-coordinate-only `z`.
+     * Returns the encoded shared point on purpose: callers that need `x_P`
+     * can derive it from the encoded point, but `x_P` alone cannot recover the
+     * point/parity back.
+     * This helper only exposes the fully validated public-key path, not cofactor DH.
+     * @param isCompressed - whether to return compact (default), or full key
+     * @returns shared point encoding
      */
     function getSharedSecret(secretKeyA, publicKeyB, isCompressed = true) {
         if (isProbPub(secretKeyA) === true)
@@ -897,25 +1057,41 @@ export function ecdh(Point, ecdhOpts = {}) {
         randomSecretKey,
     };
     const keygen = createKeygen(randomSecretKey, getPublicKey);
+    Object.freeze(utils);
+    Object.freeze(lengths);
     return Object.freeze({ getPublicKey, getSharedSecret, keygen, Point, utils, lengths });
 }
 /**
  * Creates ECDSA signing interface for given elliptic curve `Point` and `hash` function.
  *
- * @param Point created using {@link weierstrass} function
- * @param hash used for 1) message prehash-ing 2) k generation in `sign`, using hmac_drbg(hash)
- * @param ecdsaOpts rarely needed, see {@link ECDSAOpts}
+ * @param Point - created using {@link weierstrass} function
+ * @param hash - used for 1) message prehash-ing 2) k generation in `sign`, using hmac_drbg(hash)
+ * @param ecdsaOpts - rarely needed, see {@link ECDSAOpts}:
+ *   - `lowS`: Default low-S policy.
+ *   - `hmac`: HMAC implementation used by RFC6979 DRBG.
+ *   - `randomBytes`: Optional RNG override.
+ *   - `bits2int`: Optional hash-to-int conversion override.
+ *   - `bits2int_modN`: Optional hash-to-int-mod-n conversion override.
  *
+ * @returns ECDSA helper namespace.
  * @example
- * ```js
- * const p256_Point = weierstrass(...);
- * const p256_sha256 = ecdsa(p256_Point, sha256);
- * const p256_sha224 = ecdsa(p256_Point, sha224);
- * const p256_sha224_r = ecdsa(p256_Point, sha224, { randomBytes: (length) => { ... } });
+ * Create an ECDSA signer/verifier bundle for one curve implementation.
+ *
+ * ```ts
+ * import { ecdsa } from '@noble/curves/abstract/weierstrass.js';
+ * import { p256 } from '@noble/curves/nist.js';
+ * import { sha256 } from '@noble/hashes/sha2.js';
+ * const p256ecdsa = ecdsa(p256.Point, sha256);
+ * const { secretKey, publicKey } = p256ecdsa.keygen();
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = p256ecdsa.sign(msg, secretKey);
+ * const isValid = p256ecdsa.verify(sig, msg, publicKey);
  * ```
  */
 export function ecdsa(Point, hash, ecdsaOpts = {}) {
-    ahash(hash);
+    // Custom hash / bits2int hooks are treated as pure functions over validated caller-owned bytes.
+    const hash_ = hash;
+    ahash(hash_);
     validateObject(ecdsaOpts, {}, {
         hmac: 'function',
         lowS: 'boolean',
@@ -924,8 +1100,10 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
         bits2int_modN: 'function',
     });
     ecdsaOpts = Object.assign({}, ecdsaOpts);
-    const randomBytes = ecdsaOpts.randomBytes || wcRandomBytes;
-    const hmac = ecdsaOpts.hmac || ((key, msg) => nobleHmac(hash, key, msg));
+    const randomBytes = ecdsaOpts.randomBytes === undefined ? wcRandomBytes : ecdsaOpts.randomBytes;
+    const hmac = ecdsaOpts.hmac === undefined
+        ? (key, msg) => nobleHmac(hash_, key, msg)
+        : ecdsaOpts.hmac;
     const { Fp, Fn } = Point;
     const { ORDER: CURVE_ORDER, BITS: fnBits } = Fn;
     const { keygen, getPublicKey, getSharedSecret, utils, lengths } = ecdh(Point, ecdsaOpts);
@@ -935,7 +1113,11 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
         format: 'compact',
         extraEntropy: false,
     };
-    const hasLargeCofactor = CURVE_ORDER * _2n < Fp.ORDER; // Won't CURVE().h > 2n be more effective?
+    // SEC 1 4.1.6 public-key recovery tries x = r + jn for j = 0..h. Our recovered-signature
+    // format only stores one overflow bit, so it can only distinguish q.x = r from q.x = r + n.
+    // A third lift would have the form q.x = r + 2n. Since valid ECDSA r is in 1..n-1, the
+    // smallest such lift is 1 + 2n, not 2n.
+    const hasLargeRecoveryLifts = CURVE_ORDER * _2n + _1n < Fp.ORDER;
     function isBiggerThanHalfOrder(number) {
         const HALF = CURVE_ORDER >> _1n;
         return number > HALF;
@@ -945,16 +1127,15 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
             throw new Error(`invalid signature ${title}: out of range 1..Point.Fn.ORDER`);
         return num;
     }
-    function assertSmallCofactor() {
-        // ECDSA recovery is hard for cofactor > 1 curves.
-        // In sign, `r = q.x mod n`, and here we recover q.x from r.
-        // While recovering q.x >= n, we need to add r+n for cofactor=1 curves.
-        // However, for cofactor>1, r+n may not get q.x:
-        // r+n*i would need to be done instead where i is unknown.
+    function assertRecoverableCurve() {
+        // ECDSA recovery only supports curves where the current recovery id can distinguish
+        // q.x = r and q.x = r + n; larger lifts may need additional `r + n*i` branches.
+        // SEC 1 4.1.6 recovers candidates via x = r + jn, but this format only encodes j = 0 or 1.
+        // The next possible candidate is q.x = r + 2n, and its smallest valid value is 1 + 2n.
         // To easily get i, we either need to:
         // a. increase amount of valid recid values (4, 5...); OR
-        // b. prohibit non-prime-order signatures (recid > 1).
-        if (hasLargeCofactor)
+        // b. prohibit recovered signatures for those curves.
+        if (hasLargeRecoveryLifts)
             throw new Error('"recovered" sig type is not supported for cofactor >2 curves');
     }
     function validateSigLength(bytes, format) {
@@ -974,7 +1155,7 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
             this.r = validateRS('r', r); // r in [1..N-1];
             this.s = validateRS('s', s); // s in [1..N-1];
             if (recovery != null) {
-                assertSmallCofactor();
+                assertRecoverableCurve();
                 if (![0, 1, 2, 3].includes(recovery))
                     throw new Error('invalid recovery id');
                 this.recovery = recovery;
@@ -1010,6 +1191,8 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
         addRecoveryBit(recovery) {
             return new Signature(this.r, this.s, recovery);
         }
+        // Unlike the top-level helper below, this method expects a digest that has
+        // already been hashed to the curve's message representative.
         recoverPublicKey(messageHash) {
             const { r, s } = this;
             const recovery = this.assertRecovery();
@@ -1041,7 +1224,7 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
             const rb = Fn.toBytes(r);
             const sb = Fn.toBytes(s);
             if (format === 'recovered') {
-                assertSmallCofactor();
+                assertRecoverableCurve();
                 return concatBytes(Uint8Array.of(this.assertRecovery()), rb, sb);
             }
             return concatBytes(rb, sb);
@@ -1050,12 +1233,14 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
             return bytesToHex(this.toBytes(format));
         }
     }
+    Object.freeze(Signature.prototype);
+    Object.freeze(Signature);
     // RFC6979: ensure ECDSA msg is X bytes and < N. RFC suggests optional truncating via bits2octets.
     // FIPS 186-4 4.6 suggests the leftmost min(nBitLen, outLen) bits, which matches bits2int.
     // bits2int can produce res>N, we can do mod(res, N) since the bitLen is the same.
     // int2octets can't be used; pads small msgs with 0: unacceptatble for trunc as per RFC vectors
-    const bits2int = ecdsaOpts.bits2int ||
-        function bits2int_def(bytes) {
+    const bits2int = ecdsaOpts.bits2int === undefined
+        ? function bits2int_def(bytes) {
             // Our custom check "just in case", for protection against DoS
             if (bytes.length > 8192)
                 throw new Error('input is too large');
@@ -1064,22 +1249,23 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
             const num = bytesToNumberBE(bytes); // check for == u8 done here
             const delta = bytes.length * 8 - fnBits; // truncate to nBitLength leftmost bits
             return delta > 0 ? num >> BigInt(delta) : num;
-        };
-    const bits2int_modN = ecdsaOpts.bits2int_modN ||
-        function bits2int_modN_def(bytes) {
+        }
+        : ecdsaOpts.bits2int;
+    const bits2int_modN = ecdsaOpts.bits2int_modN === undefined
+        ? function bits2int_modN_def(bytes) {
             return Fn.create(bits2int(bytes)); // can't use bytesToNumberBE here
-        };
-    // Pads output with zero as per spec
+        }
+        : ecdsaOpts.bits2int_modN;
     const ORDER_MASK = bitMask(fnBits);
+    // Pads output with zero as per spec.
     /** Converts to bytes. Checks if num in `[0..ORDER_MASK-1]` e.g.: `[0..2^256-1]`. */
     function int2octets(num) {
-        // IMPORTANT: the check ensures working for case `Fn.BYTES != Fn.BITS * 8`
         aInRange('num < 2^' + fnBits, num, _0n, ORDER_MASK);
         return Fn.toBytes(num);
     }
     function validateMsgAndHash(message, prehash) {
         abytes(message, undefined, 'message');
-        return prehash ? abytes(hash(message), undefined, 'prehashed message') : message;
+        return (prehash ? abytes(hash_(message), undefined, 'prehashed message') : message);
     }
     /**
      * Steps A, D of RFC6979 3.2.
@@ -1137,12 +1323,14 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
                 normS = Fn.neg(s); // if lowS was passed, ensure s is always in the bottom half of N
                 recovery ^= 1;
             }
-            return new Signature(r, normS, hasLargeCofactor ? undefined : recovery);
+            return new Signature(r, normS, hasLargeRecoveryLifts ? undefined : recovery);
         }
         return { seed, k2sig };
     }
     /**
-     * Signs message hash with a secret key.
+     * Signs a message or message hash with a secret key.
+     * With the default `prehash: true`, raw message bytes are hashed internally;
+     * only `{ prehash: false }` expects a caller-supplied digest.
      *
      * ```
      * sign(m, d) where
@@ -1154,7 +1342,7 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
      */
     function sign(message, secretKey, opts = {}) {
         const { seed, k2sig } = prepSig(message, secretKey, opts); // Steps A, D of RFC6979 3.2.
-        const drbg = createHmacDrbg(hash.outputLen, Fn.BYTES, hmac);
+        const drbg = createHmacDrbg(hash_.outputLen, Fn.BYTES, hmac);
         const sig = drbg(seed, k2sig); // Steps B, C, D, E, F, G
         return sig.toBytes(opts.format);
     }
@@ -1201,6 +1389,8 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
         }
     }
     function recoverPublicKey(signature, message, opts = {}) {
+        // Top-level recovery mirrors `sign()` / `verify()`: it hashes raw message
+        // bytes first unless the caller passes `{ prehash: false }`.
         const { prehash } = validateSigOpts(opts, defaultSigOpts);
         message = validateMsgAndHash(message, prehash);
         return Signature.fromBytes(signature, 'recovered').recoverPublicKey(message).toBytes();
@@ -1216,7 +1406,7 @@ export function ecdsa(Point, hash, ecdsaOpts = {}) {
         verify,
         recoverPublicKey,
         Signature,
-        hash,
+        hash: hash_,
     });
 }
 //# sourceMappingURL=weierstrass.js.map