@opcat-labs/opcat 1.0.1 → 1.0.3

package/{lib/crypto/bn.js → cjs/crypto/bn.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-var BN = require('../bn');
-var $ = require('../util/preconditions');
-var _ = require('../util/_');
+var BN = require('../bn.cjs');
+var $ = require('../util/preconditions.cjs');
+var _ = require('../util/_.cjs');
 
 var reversebuf = function (buf) {
   var buf2 = Buffer.alloc(buf.length);

package/{lib/crypto/ecdsa.js → cjs/crypto/ecdsa.cjs}

@@ -1,15 +1,20 @@
 'use strict';
 
-var BN = require('./bn');
-var Point = require('./point');
-var Signature = require('./signature');
-var PublicKey = require('../publickey');
-var Random = require('./random');
-var Hash = require('./hash');
-var _ = require('../util/_');
-var $ = require('../util/preconditions');
-
-var ECDSA = function ECDSA(obj) {
+var BN = require('./bn.cjs');
+var Point = require('./point.cjs');
+var Signature = require('./signature.cjs');
+var PublicKey = require('../publickey.cjs');
+var Random = require('./random.cjs');
+var Hash = require('./hash.cjs');
+var _ = require('../util/_.cjs');
+var $ = require('../util/preconditions.cjs');
+
+/**
+ * Creates an ECDSA instance.
+ * @constructor
+ * @param {Object} [obj] - Optional object containing properties to initialize the instance.
+ */
+function ECDSA(obj) {
   if (!(this instanceof ECDSA)) {
     return new ECDSA(obj);
   }
@@ -18,6 +23,18 @@ var ECDSA = function ECDSA(obj) {
   }
 };
 
+/**
+ * Updates the ECDSA instance properties with provided values.
+ * @param {Object} obj - Object containing properties to update
+ * @param {Buffer} [obj.hashbuf] - Hash buffer
+ * @param {string} [obj.endian] - Endianness of hashbuf
+ * @param {PrivateKey} [obj.privkey] - Private key
+ * @param {PublicKey} [obj.pubkey] - Public key (derived from privkey if not provided)
+ * @param {Signature} [obj.sig] - Signature
+ * @param {BigInteger} [obj.k] - Random number k
+ * @param {boolean} [obj.verified] - Verification status
+ * @returns {ECDSA} Returns the updated ECDSA instance
+ */
 ECDSA.prototype.set = function (obj) {
   this.hashbuf = obj.hashbuf || this.hashbuf;
   this.endian = obj.endian || this.endian; // the endianness of hashbuf
@@ -29,10 +46,21 @@ ECDSA.prototype.set = function (obj) {
   return this;
 };
 
+/**
+ * Converts the private key to a public key and stores it in the `pubkey` property.
+ */
 ECDSA.prototype.privkey2pubkey = function () {
   this.pubkey = this.privkey.toPublicKey();
 };
 
+/**
+ * Calculates the recovery factor (i) for ECDSA signature verification.
+ * Iterates through possible recovery factors (0-3) to find the one that
+ * reconstructs the correct public key from the signature.
+ * 
+ * @returns {ECDSA} Returns the instance with updated signature properties if successful.
+ * @throws {Error} Throws if no valid recovery factor is found after all iterations.
+ */
 ECDSA.prototype.calci = function () {
   for (var i = 0; i < 4; i++) {
     this.sig.i = i;
@@ -54,11 +82,21 @@ ECDSA.prototype.calci = function () {
   throw new Error('Unable to find valid recovery factor');
 };
 
+/**
+ * Creates an ECDSA instance from a JSON string representation.
+ * @param {string} str - JSON string containing ECDSA parameters.
+ * @returns {ECDSA} New ECDSA instance initialized with parsed data.
+ */
 ECDSA.fromString = function (str) {
   var obj = JSON.parse(str);
   return new ECDSA(obj);
 };
 
+/**
+ * Generates a random value `k` for ECDSA signing.
+ * The value is generated within the range (0, N) where N is the curve order.
+ * The generated `k` is stored in the instance and returned for chaining.
+ */
 ECDSA.prototype.randomK = function () {
   var N = Point.getN();
   var k;
@@ -69,7 +107,15 @@ ECDSA.prototype.randomK = function () {
   return this;
 };
 
-// https://tools.ietf.org/html/rfc6979#section-3.2
+
+/**
+ * Generates a deterministic K value for ECDSA signing as per RFC 6979.
+ * See:
+ *  https://tools.ietf.org/html/rfc6979#section-3.2
+ * Handles invalid r/s cases by incrementing badrs counter and regenerating K.
+ * @param {number} [badrs=0] - Counter for invalid r/s cases (default: 0)
+ * @returns {ECDSA} Returns the ECDSA instance for chaining
+ */
 ECDSA.prototype.deterministicK = function (badrs) {
   // if r or s were invalid when this function was used in signing,
   // we do not want to actually compute r, s here for efficiency, so,
@@ -105,9 +151,20 @@ ECDSA.prototype.deterministicK = function (badrs) {
   return this;
 };
 
-// Information about public key recovery:
-// https://bitcointalk.org/index.php?topic=6430.0
-// http://stackoverflow.com/questions/19665491/how-do-i-get-an-ecdsa-public-key-from-just-a-bitcoin-signature-sec1-4-1-6-k
+/**
+ * Converts an ECDSA signature to its corresponding public key.
+ * 
+ * The method follows the ECDSA public key recovery process:
+ * 1. Validates the recovery parameter `i` (must be 0-3)
+ * 2. Derives the public key point Q using the formula: Q = r⁻¹(sR - eG)
+ * 3. Validates the derived curve point
+ * 
+ * see:
+ *  https://bitcointalk.org/index.php?topic=6430.0
+ *  http://stackoverflow.com/questions/19665491/how-do-i-get-an-ecdsa-public-key-from-just-a-bitcoin-signature-sec1-4-1-6-k
+ * @returns {PublicKey} The recovered public key
+ * @throws {Error} If recovery parameter is invalid or derived point is invalid
+ */
 ECDSA.prototype.toPublicKey = function () {
   var i = this.sig.i;
   $.checkArgument(
@@ -155,6 +212,14 @@ ECDSA.prototype.toPublicKey = function () {
   return pubkey;
 };
 
+/**
+ * Validates an ECDSA signature and returns an error message if invalid.
+ * Checks:
+ * - hashbuf is a 32-byte buffer
+ * - r and s values are within valid range
+ * - Signature verification against public key
+ * @returns {string|boolean} Error message if invalid, false if valid
+ */
 ECDSA.prototype.sigError = function () {
   if (!Buffer.isBuffer(this.hashbuf) || this.hashbuf.length !== 32) {
     return 'hashbuf must be a 32 byte buffer';
@@ -191,6 +256,13 @@ ECDSA.prototype.sigError = function () {
   }
 };
 
+/**
+ * Converts the signature `s` value to its low-S form to comply with BIP 62.
+ * This prevents signature malleability by ensuring `s` is not greater than half the curve order.
+ * @param {BN} s - The signature `s` value as a big number.
+ * @returns {BN} The low-S normalized value.
+ * @static
+ */
 ECDSA.toLowS = function (s) {
   // enforce low s
   // see BIP 62, "low S values in signatures"
@@ -206,6 +278,15 @@ ECDSA.toLowS = function (s) {
   return s;
 };
 
+/**
+ * Finds a valid ECDSA signature (r, s) for the given private key `d` and message hash `e`.
+ * Uses deterministic k-value generation if initial attempts fail.
+ * 
+ * @param {BN} d - Private key as a big number.
+ * @param {BN} e - Message hash as a big number.
+ * @returns {Object} Signature object with properties `r` and `s` (big numbers).
+ * @throws Will throw if unable to find valid signature after multiple attempts.
+ */
 ECDSA.prototype._findSignature = function (d, e) {
   var N = Point.getN();
   var G = Point.getG();
@@ -233,6 +314,14 @@ ECDSA.prototype._findSignature = function (d, e) {
   };
 };
 
+/**
+ * Signs a message using ECDSA.
+ * 
+ * @param {Buffer} hashbuf - 32-byte buffer containing the hash of the message to sign.
+ * @param {PrivateKey} privkey - Private key used for signing.
+ * @returns {ECDSA} Returns the instance for chaining.
+ * @throws {Error} Throws if parameters are invalid or hashbuf is not a 32-byte buffer.
+ */
 ECDSA.prototype.sign = function () {
   var hashbuf = this.hashbuf;
   var privkey = this.privkey;
@@ -260,11 +349,22 @@ ECDSA.prototype.sign = function () {
   return this;
 };
 
+/**
+ * Signs the message using a randomly generated k value.
+ * 
+ * @returns The signature object containing r and s values.
+ */
 ECDSA.prototype.signRandomK = function () {
   this.randomK();
   return this.sign();
 };
 
+/**
+ * Converts the ECDSA instance to a JSON string representation.
+ * Includes hash buffer, private key, public key, signature, and k value if present.
+ * Each property is converted to a string format (hex for hashbuf, toString() for others).
+ * @returns {string} JSON string containing the ECDSA instance properties
+ */
 ECDSA.prototype.toString = function () {
   var obj = {};
   if (this.hashbuf) {
@@ -285,6 +385,10 @@ ECDSA.prototype.toString = function () {
   return JSON.stringify(obj);
 };
 
+/**
+ * Verifies the ECDSA signature and updates the `verified` property.
+ * @returns {ECDSA} The current instance for chaining.
+ */
 ECDSA.prototype.verify = function () {
   if (!this.sigError()) {
     this.verified = true;
@@ -294,6 +398,13 @@ ECDSA.prototype.verify = function () {
   return this;
 };
 
+/**
+ * Signs a message hash using ECDSA with the given private key.
+ * @param {Buffer} hashbuf - The hash of the message to sign
+ * @param {PrivateKey} privkey - The private key to sign with
+ * @param {string} [endian] - Endianness of the input/output (optional)
+ * @returns {Signature} The ECDSA signature
+ */
 ECDSA.sign = function (hashbuf, privkey, endian) {
   return ECDSA()
     .set({
@@ -304,6 +415,14 @@ ECDSA.sign = function (hashbuf, privkey, endian) {
     .sign().sig;
 };
 
+/**
+ * Signs a hash buffer with a private key and calculates the 'i' value.
+ * @param {Buffer} hashbuf - The hash buffer to sign.
+ * @param {Buffer} privkey - The private key used for signing.
+ * @param {string} [endian] - The endianness of the input data (optional).
+ * @returns {Buffer} The resulting signature.
+ * @static
+ */
 ECDSA.signWithCalcI = function (hashbuf, privkey, endian) {
   return ECDSA()
     .set({
@@ -315,6 +434,14 @@ ECDSA.signWithCalcI = function (hashbuf, privkey, endian) {
     .calci().sig;
 };
 
+/**
+ * Signs a message hash using ECDSA with a randomly generated K value.
+ * @param {Buffer} hashbuf - The message hash to sign.
+ * @param {Buffer} privkey - The private key used for signing.
+ * @param {string} [endian] - The endianness of the input/output (default: 'big').
+ * @returns {Buffer} The generated ECDSA signature.
+ * @static
+ */
 ECDSA.signRandomK = function (hashbuf, privkey, endian) {
   return ECDSA()
     .set({
@@ -325,6 +452,15 @@ ECDSA.signRandomK = function (hashbuf, privkey, endian) {
     .signRandomK().sig;
 };
 
+/**
+ * Verifies an ECDSA signature against a hash and public key.
+ * @param {Buffer} hashbuf - The hash buffer to verify against.
+ * @param {Signature} sig - The signature to verify.
+ * @param {PublicKey} pubkey - The public key to verify with.
+ * @param {string} [endian] - The endianness of the input data (optional).
+ * @returns {boolean} True if the signature is valid, false otherwise.
+ * @static
+ */
 ECDSA.verify = function (hashbuf, sig, pubkey, endian) {
   return ECDSA()
     .set({

package/{lib/crypto/hash.node.js → cjs/crypto/hash.cjs}

@@ -1,9 +1,17 @@
 'use strict';
 
 var crypto = require('crypto');
-var $ = require('../util/preconditions');
+var $ = require('../util/preconditions.cjs');
 
-var Hash = module.exports;
+/**
+ * Represents a hash utility class.
+ * @constructor
+ */
+function Hash() {
+  if (!(this instanceof Hash)) {
+    return new Hash();
+  }
+};
 
 /**
  * A SHA or SHA1 hash, which is always 160 bits or 20 bytes long.
@@ -169,3 +177,6 @@ Hash.sha256hmac = function (data, key) {
 Hash.sha512hmac = function (data, key) {
   return Hash.hmac(Hash.sha512, data, key);
 };
+
+
+module.exports = Hash

package/cjs/crypto/index.cjs

@@ -0,0 +1,16 @@
+var BN = require('./bn.cjs');
+var ECDSA = require('./ecdsa.cjs');
+var Hash = require('./hash.cjs');
+var Random = require('./random.cjs');
+var Point = require('./point.cjs');
+var Signature = require('./signature.cjs');
+
+module.exports = {
+    BN: BN,
+    ECDSA: ECDSA,
+    Hash: Hash,
+    Random: Random,
+    Point: Point,
+    Signature: Signature
+}
+

package/{lib/crypto/point.js → cjs/crypto/point.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var BN = require('./bn');
+var BN = require('./bn.cjs');
 var elliptic = require('elliptic');
 var EC = elliptic.ec;
 var ec = new EC('secp256k1');
@@ -20,10 +20,10 @@ var ecPointFromX = ec.curve.pointFromX.bind(ec.curve);
  * @returns {Point} An instance of Point
  * @constructor
  */
-var Point = function Point(x, y, isRed) {
+function Point(x, y, isRed) {
   try {
     var point = ecPoint(x, y, isRed);
-  } catch (e) {
+  } catch (_) {
     throw new Error('Invalid Point');
   }
   point.validate();
@@ -41,6 +41,7 @@ Point.prototype = Object.getPrototypeOf(ec.curve.point());
  * @param {BN|String} x - The X coordinate
  * @throws {Error} A validation error if exists
  * @returns {Point} An instance of Point
+ * @static
  */
 Point.fromX = function fromX(odd, x) {
   try {
@@ -58,6 +59,7 @@ Point.fromX = function fromX(odd, x) {
  *
  * @link https://en.bitcoin.it/wiki/Secp256k1
  * @returns {Point} An instance of the base point.
+ * @static
  */
 Point.getG = function getG() {
   return ec.curve.g;
@@ -70,6 +72,7 @@ Point.getG = function getG() {
  *
  * @link https://en.bitcoin.it/wiki/Private_key#Range_of_valid_ECDSA_private_keys
  * @returns {BN} A BN instance of the number of points on the curve
+ * @static
  */
 Point.getN = function getN() {
   return new BN(ec.curve.n.toArray());
@@ -116,7 +119,7 @@ Point.prototype.validate = function validate() {
   var p2;
   try {
     p2 = ecPointFromX(this.getX(), this.getY().isOdd());
-  } catch (e) {
+  } catch (_) {
     throw new Error('Point does not lie on the curve');
   }
 
@@ -140,6 +143,7 @@ Point.prototype.validate = function validate() {
  *
  * @param {Point} point An instance of Point.
  * @returns {Buffer} A compressed point in the form of a buffer.
+ * @static
  */
 Point.pointToCompressed = function pointToCompressed(point) {
   var xbuf = point.getX().toBuffer({ size: 32 });
@@ -160,6 +164,7 @@ Point.pointToCompressed = function pointToCompressed(point) {
  *
  * @param {Buffer} buf A compressed point.
  * @returns {Point} A Point.
+ * @static
  */
 Point.pointFromCompressed = function (buf) {
   if (buf.length !== 33) {
@@ -203,6 +208,7 @@ Point.prototype.toHex = function () {
  *
  * @param {Buffer} buf A compressed point.
  * @returns {Point} A Point.
+ * @static
  */
 Point.fromBuffer = function (buf) {
   return Point.pointFromCompressed(buf);
@@ -213,6 +219,7 @@ Point.fromBuffer = function (buf) {
  *
  * @param {Buffer} hex A compressed point as a hex string.
  * @returns {Point} A Point.
+ * @static
  */
 Point.fromHex = function (hex) {
   return Point.fromBuffer(Buffer.from(hex, 'hex'));

package/cjs/crypto/random.cjs

@@ -0,0 +1,18 @@
+'use strict';
+var crypto = require('crypto');
+
+/**
+ * A utility class for generating random values.
+ */
+function Random() { }
+
+/**
+ * Generates a cryptographically secure random buffer of the specified size.
+ * @param {number} size - The number of bytes to generate.
+ * @returns {Buffer} A buffer filled with cryptographically secure random bytes.
+ */
+Random.getRandomBuffer = function (size) {
+    return crypto.randomBytes(size);
+};
+
+module.exports = Random;