@noble/curves 2.0.1 → 2.2.0

package/src/abstract/montgomery.ts

@@ -14,6 +14,8 @@ import {
   randomBytes,
   validateObject,
   type CryptoKeys,
+  type TArg,
+  type TRet,
 } from '../utils.ts';
 import { createKeygen, type CurveLengths } from './curve.ts';
 import { mod } from './modular.ts';
@@ -22,41 +24,118 @@ const _0n = BigInt(0);
 const _1n = BigInt(1);
 const _2n = BigInt(2);
 
+/** Curve-specific hooks required to build one X25519/X448 helper. */
 export type MontgomeryOpts = {
-  P: bigint; // finite field prime
+  /** Prime field modulus. */
+  P: bigint;
+  /** RFC 7748 variant name. */
   type: 'x25519' | 'x448';
-  adjustScalarBytes: (bytes: Uint8Array) => Uint8Array;
+  /**
+   * Clamp or otherwise normalize one scalar byte string before use.
+   * @param bytes - Raw secret scalar bytes.
+   * @returns Adjusted scalar bytes ready for Montgomery multiplication.
+   */
+  adjustScalarBytes: (bytes: TArg<Uint8Array>) => TRet<Uint8Array>;
+  /**
+   * Invert one field element with exponentiation by `p - 2`.
+   * @param x - Field element to invert.
+   * @returns Multiplicative inverse of `x`.
+   */
   powPminus2: (x: bigint) => bigint;
-  randomBytes?: (bytesLength?: number) => Uint8Array;
+  /**
+   * Optional randomness source for `keygen()` and `utils.randomSecretKey()`.
+   * Receives the requested byte length and returns fresh random bytes.
+   */
+  randomBytes?: (bytesLength?: number) => TRet<Uint8Array>;
 };
 
+/** Public X25519/X448 ECDH API built on a Montgomery ladder. */
 export type MontgomeryECDH = {
-  scalarMult: (scalar: Uint8Array, u: Uint8Array) => Uint8Array;
-  scalarMultBase: (scalar: Uint8Array) => Uint8Array;
-  getSharedSecret: (secretKeyA: Uint8Array, publicKeyB: Uint8Array) => Uint8Array;
-  getPublicKey: (secretKey: Uint8Array) => Uint8Array;
+  /**
+   * Multiply one scalar by one Montgomery `u` coordinate.
+   * @param scalar - Secret scalar bytes.
+   * @param u - Public Montgomery `u` coordinate.
+   * @returns Shared point encoded as bytes.
+   */
+  scalarMult: (scalar: TArg<Uint8Array>, u: TArg<Uint8Array>) => TRet<Uint8Array>;
+  /**
+   * Multiply one scalar by the curve base point.
+   * @param scalar - Secret scalar bytes.
+   * @returns Public key bytes.
+   */
+  scalarMultBase: (scalar: TArg<Uint8Array>) => TRet<Uint8Array>;
+  /**
+   * Derive a shared secret from a local secret key and peer public key.
+   * @param secretKeyA - Local secret key bytes.
+   * @param publicKeyB - Peer public key bytes.
+   * Rejects low-order public inputs instead of returning the all-zero shared secret.
+   * @returns Shared secret bytes.
+   */
+  getSharedSecret: (secretKeyA: TArg<Uint8Array>, publicKeyB: TArg<Uint8Array>) => TRet<Uint8Array>;
+  /**
+   * Derive one public key from a secret key.
+   * @param secretKey - Secret key bytes.
+   * @returns Public key bytes.
+   */
+  getPublicKey: (secretKey: TArg<Uint8Array>) => TRet<Uint8Array>;
+  /** Utility helpers for secret-key generation. */
   utils: {
-    randomSecretKey: () => Uint8Array;
+    /** Generate one random secret key with the curve's expected byte length. */
+    randomSecretKey: () => TRet<Uint8Array>;
   };
-  GuBytes: Uint8Array;
+  /** Encoded Montgomery base point `u`. */
+  GuBytes: TRet<Uint8Array>;
+  /** Public lengths for keys and seeds. */
   lengths: CurveLengths;
-  keygen: (seed?: Uint8Array) => { secretKey: Uint8Array; publicKey: Uint8Array };
+  /**
+   * Generate one random secret/public keypair.
+   * @param seed - Optional seed bytes to use instead of random generation.
+   * @returns Fresh secret/public keypair.
+   */
+  keygen: (seed?: TArg<Uint8Array>) => {
+    secretKey: TRet<Uint8Array>;
+    publicKey: TRet<Uint8Array>;
+  };
 };
 
-function validateOpts(curve: MontgomeryOpts) {
-  validateObject(curve, {
-    adjustScalarBytes: 'function',
-    powPminus2: 'function',
-  });
+function validateOpts(curve: TArg<MontgomeryOpts>) {
+  // Validate constructor config eagerly, but do not call user-provided hooks here:
+  // `randomBytes` may be transcript-backed or otherwise contextual. Runtime type checks are
+  // enough to fail fast on malformed configs without consuming user state.
+  validateObject(
+    curve,
+    {
+      P: 'bigint',
+      type: 'string',
+      adjustScalarBytes: 'function',
+      powPminus2: 'function',
+    },
+    {
+      randomBytes: 'function',
+    }
+  );
   return Object.freeze({ ...curve } as const);
 }
 
-export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
+/**
+ * @param curveDef - Montgomery curve definition.
+ * @returns ECDH helper namespace.
+ * @throws If the curve definition or derived shared point is invalid. {@link Error}
+ * @example
+ * Perform one X25519 key exchange through the generic Montgomery helper.
+ *
+ * ```ts
+ * import { x25519 } from '@noble/curves/ed25519.js';
+ * const alice = x25519.keygen();
+ * const shared = x25519.getSharedSecret(alice.secretKey, alice.publicKey);
+ * ```
+ */
+export function montgomery(curveDef: TArg<MontgomeryOpts>): TRet<MontgomeryECDH> {
   const CURVE = validateOpts(curveDef);
   const { P, type, adjustScalarBytes, powPminus2, randomBytes: rand } = CURVE;
   const is25519 = type === 'x25519';
   if (!is25519 && type !== 'x448') throw new Error('invalid type');
-  const randomBytes_ = rand || randomBytes;
+  const randomBytes_ = rand === undefined ? randomBytes : rand;
 
   const montgomeryBits = is25519 ? 255 : 448;
   const fieldLen = is25519 ? 32 : 56;
@@ -64,7 +143,7 @@ export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
   // RFC 7748 #5:
   // The constant a24 is (486662 - 2) / 4 = 121665 for curve25519/X25519 and
   // (156326 - 2) / 4 = 39081 for curve448/X448
-  // const a = is25519 ? 156326n : 486662n;
+  // const a = is25519 ? 486662n : 156326n;
   const a24 = is25519 ? BigInt(121665) : BigInt(39081);
   // RFC: x25519 "the resulting integer is of the form 2^254 plus
   // eight times a value between 0 and 2^251 - 1 (inclusive)"
@@ -76,10 +155,10 @@ export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
   const maxScalar = minScalar + maxAdded + _1n; // (inclusive)
   const modP = (n: bigint) => mod(n, P);
   const GuBytes = encodeU(Gu);
-  function encodeU(u: bigint): Uint8Array {
+  function encodeU(u: bigint): TRet<Uint8Array> {
     return numberToBytesLE(modP(u), fieldLen);
   }
-  function decodeU(u: Uint8Array): bigint {
+  function decodeU(u: TArg<Uint8Array>): bigint {
     const _u = copyBytes(abytes(u, fieldLen, 'uCoordinate'));
     // RFC: When receiving such an array, implementations of X25519
     // (but not X448) MUST mask the most significant bit in the final byte.
@@ -90,10 +169,10 @@ export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
     // - 1 through 2^448 - 1 for X448.
     return modP(bytesToNumberLE(_u));
   }
-  function decodeScalar(scalar: Uint8Array): bigint {
+  function decodeScalar(scalar: TArg<Uint8Array>): bigint {
     return bytesToNumberLE(adjustScalarBytes(copyBytes(abytes(scalar, fieldLen, 'scalar'))));
   }
-  function scalarMult(scalar: Uint8Array, u: Uint8Array): Uint8Array {
+  function scalarMult(scalar: TArg<Uint8Array>, u: TArg<Uint8Array>): TRet<Uint8Array> {
     const pu = montgomeryLadder(decodeU(u), decodeScalar(scalar));
     // Some public keys are useless, of low-order. Curve author doesn't think
     // it needs to be validated, but we do it nonetheless.
@@ -102,7 +181,7 @@ export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
     return encodeU(pu);
   }
   // Computes public key from private. By doing scalar multiplication of base point.
-  function scalarMultBase(scalar: Uint8Array): Uint8Array {
+  function scalarMultBase(scalar: TArg<Uint8Array>): TRet<Uint8Array> {
     return scalarMult(scalar, GuBytes);
   }
   const getPublicKey = scalarMultBase;
@@ -120,10 +199,10 @@ export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
   }
 
   /**
-   * Montgomery x-only multiplication ladder.
-   * @param pointU u coordinate (x) on Montgomery Curve 25519
-   * @param scalar by which the point would be multiplied
-   * @returns new Point on Montgomery curve
+   * Montgomery x-only multiplication ladder for the selected X25519/X448 curve.
+   * @param pointU - decoded Montgomery u coordinate for the selected curve
+   * @param scalar - decoded clamped scalar by which the point is multiplied
+   * @returns resulting Montgomery u coordinate for the selected curve
    */
   function montgomeryLadder(u: bigint, scalar: bigint): bigint {
     aInRange('u', u, _0n, P);
@@ -168,11 +247,16 @@ export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
     publicKey: fieldLen,
     seed: fieldLen,
   };
-  const randomSecretKey = (seed = randomBytes_(fieldLen)) => {
+  const randomSecretKey = (seed?: TArg<Uint8Array>): TRet<Uint8Array> => {
+    seed = seed === undefined ? randomBytes_(fieldLen) : seed;
     abytes(seed, lengths.seed, 'seed');
-    return seed;
+    // Reuse caller-supplied seed bytes verbatim; clamping is deferred until
+    // decodeScalar(...) when the secret key is actually used.
+    return seed as TRet<Uint8Array>;
   };
   const utils = { randomSecretKey };
+  Object.freeze(lengths);
+  Object.freeze(utils);
 
   return Object.freeze({
     keygen: createKeygen(randomSecretKey, getPublicKey),
@@ -181,7 +265,7 @@ export function montgomery(curveDef: MontgomeryOpts): MontgomeryECDH {
     scalarMult,
     scalarMultBase,
     utils,
-    GuBytes: GuBytes.slice(),
+    GuBytes: GuBytes.slice() as TRet<Uint8Array>,
     lengths,
   }) satisfies CryptoKeys;
 }