@lumjs/encode 2.1.0 → 2.2.2

package/CHANGELOG.md

@@ -6,7 +6,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.1.0]
+## [2.2.2] - 2026-01-13
+### Fixed
+- A few typos and bugs in the HMAC/HOTP/TOTP libraries I added last time.
+- Added some missing timestamps in this changelog.
+- Fixed references in this changelog.
+### Changed
+- While fixing the broken bits, I made a bunch of previously hard-coded values
+  into options. They'll need to be properly documented at some point.
+- Changed how `hash.getAlgorithm()` works behind the scenes.
+- v2.2.1 never got published for reasons, so no log or tag for it.
+
+## [2.2.0] - 2025-11-18
+### Added
+- intToBytes() and hexToBytes() functions added to util.js
+- A HMAC wrapper library, and a generic Signature class used by it.
+- HOTP/TOTP generation and valdiation classes.
+  They are loosely based on the ones from the `notp` package, but while that
+  package exports some static functions and depends on the node.js `crypto`
+  module, this one has two JS classes and uses the SubtleCrypto API.
+- A TODO file with things I want to do.
+
+## [2.1.0] - 2025-90-09
 ### Changed
 - The `base64` library now supports the `Uint8Array.fromBase64` static method,
   and the corresponding `toBase64()` instance method. As those are rather new
@@ -42,7 +63,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release.
 
-[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v2.1.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v2.2.2...HEAD
+[2.2.2]: https://github.com/supernovus/lum.encode.js/compare/v2.2.0...v2.2.2
+[2.2.0]: https://github.com/supernovus/lum.encode.js/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/supernovus/lum.encode.js/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/supernovus/lum.encode.js/compare/v1.2.0...v2.0.0
 [1.2.0]: https://github.com/supernovus/lum.encode.js/compare/v1.1.0...v1.2.0

package/TODO.md

@@ -0,0 +1,3 @@
+# TODO
+
+- Write tests for HMAC, HOTP, TOTP, etc.

package/lib/hash.js

@@ -1,3 +1,5 @@
+'use strict';
+
 const {S,F,isObj,isNil} = require('@lumjs/core/types');
 
 const util   = require('./util');
@@ -25,6 +27,11 @@ const ALGO_INFO =
   'SHA-512': {length: 512, block: 1024},
 }
 
+for (let algo in ALGO_INFO) {
+  ALGO_INFO[algo].id = algo;
+  Object.freeze(ALGO_INFO[algo]);
+}
+
 const DATA_ENCODERS = 
 {
   base64, base91,
@@ -182,7 +189,7 @@ module.exports = class
 
     if (id in ALGO_INFO)
     {
-      return Object.assign({id}, ALGO_INFO[id]);
+      return ALGO_INFO[id];
     }
 
     // Invalid algorithm id, nothing to return.
@@ -297,8 +304,8 @@ module.exports = class
   async base64(input, opts=this.defaults.base64)
   {
     const hash = await this.hash(input);
-    const b64str = base64.fromBytes(new Uint8Array(hash));
-    return opts.url ? base64.urlize(b64str) : b64str;
+    const b64str = base64.fromBytes(new Uint8Array(hash), opts);
+    return opts.url ? base64.urlize(b64str, opts) : b64str;
   }
 
   /**
@@ -330,7 +337,7 @@ module.exports = class
 
     if (nba)
     {
-      hash = util.numByteArray(hash);
+      hash = util.numByteArray(hash, nba);
     }
 
     return base91.encode(new Uint8Array(hash));
@@ -341,7 +348,7 @@ module.exports = class
    *
    * @param {(string|object)} input - A value to add to the hash.
    * 
-   * If it is an `object` then it will be processed with the `addWith`
+   * If it is an `object` then it will be processed with the `addUsing`
    * handler. See the constructor for details on supported formats.
    * 
    * String values are simply added _as-is_.

package/lib/hmac.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const Signature = require('./signature');
+
+const CKEY = Symbol('@lumjs/encore/hmac~key');
+const HMAC = 'HMAC';
+const DEF_OPTS = {
+  algorithm: 'SHA-256',
+  extractable: false,
+  keyFormat: 'raw', 
+  usages: ['sign'] 
+};
+
+/**
+ * The main class to perform HMAC signing.
+ * @exports module:@lumjs/encode/hmac
+ */
+class HmacEncoder {
+  /**
+   * Create an encoder.
+   * 
+   * @param {(string|TypedArray|ArrayBuffer)} keyValue - The secret key value.
+   * Will be used to generate the crypto key.
+   * @param {object} [options] Options
+   * @param {string} [options.algorithm="SHA-256"] Digest algorithm for HMAC.
+   */
+  constructor(keyValue, options) {
+    this.te = new TextEncoder();
+    this.keyBytes = ArrayBuffer.isView(keyValue)
+      ? keyValue
+      : this.te.encode(keyValue);
+    this.options = Object.assign({}, DEF_OPTS, options);
+  }
+
+  /**
+   * Get the crypto key for this encoder instance.
+   * @returns {Promise<CryptoKey>}
+   */
+  async getKey() {
+    if (this[CKEY]) {
+      return this[CKEY];
+    }
+
+    let hmac = { name: HMAC, hash: this.options.algorithm }
+    let key = await crypto.subtle.importKey(
+      this.options.keyFormat,   // Key format
+      this.keyBytes,            // Key data
+      hmac,                     // Algorithm
+      this.options.extractable, // Is key extractable
+      this.options.usages,      // Allowed key usages
+    );
+
+    this[CKEY] = key;
+    return key;
+  }
+
+  /**
+   * Sign a message (any kind of data).
+   * @param {(string|TypedArray|ArrayBuffer)} message - Message to be signed.
+   * @returns {Promise<module:@lumjs/encode/signature>}
+   */
+  async sign(message) {
+    if (!ArrayBuffer.isView(message)) {
+      message = this.te.encode(message);
+    }
+
+    let key = await this.getKey();
+    let sig = await crypto.subtle.sign(
+      HMAC,            // Algorithm
+      key,             // HMAC CryptoKey
+      message,         // Data to sign
+    );
+
+    return new Signature(sig);
+  }
+
+}
+
+module.exports = HmacEncoder;

package/lib/hotp.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const HmacEncoder = require('./hmac');
+const { intToBytes } = require('./util');
+
+const DEF_OPTS = { 
+  algorithm: 'SHA-1',
+  checkSize: 7,
+  counter: 0, 
+  window: 50 
+};
+
+const cp = Object.assign;
+const isError = v => (typeof v === 'function' && Error.isPrototypeOf(v));
+
+function needKey(key) {
+  if (!key) {
+    throw new Error("No signing key was specified");
+  }
+}
+
+/**
+ * HMAC-based One-Time-Passwords.
+ * @exports module:@lumjs/encode/hotp
+ */
+class HOTP {
+  constructor(options) {
+    this.setOptions(options);
+  }
+
+  setOptions(options) {
+    if (this.options) {
+      cp(this.options, options);
+    }
+    else {
+      this.options = cp({}, ...this.defaultOptions, options);
+    }
+    return this;
+  }
+
+  getOptions() {
+    return cp({}, this.options, ...arguments);
+  }
+
+  get defaultKey() {
+    return this.options.key;
+  }
+
+  get defaultOptions() {
+    return [DEF_OPTS];
+  }
+
+  async generate(key = this.defaultKey, opts) {
+    needKey(key);
+    opts = this.getOptions(opts);
+
+    let encoder = new HmacEncoder(key, opts);
+    let data = new Uint8Array(intToBytes(opts.counter));
+    let hash = await encoder.sign(data);
+    let hb = hash.byteArray;
+
+    let offset = hb[19] & 0xf;
+    let v1 =
+      (hb[offset] & 0x7f) << 24 |
+      (hb[offset + 1] & 0xff) << 16 |
+      (hb[offset + 2] & 0xff) << 8 |
+      (hb[offset + 3] & 0xff);
+
+    let v2 = (v1 % 1000000) + '';
+    let code = Array(opts.checkSize - v2.length).join('0') + v2;
+
+    let res = {
+      opts,
+      data,
+      hash,
+      hashBytes: hb,
+      offset,
+      v1,
+      v2,
+      code,
+      toString,
+    }
+
+    if (opts.debug) console.debug(res.code, res);
+
+    return res;
+  }
+
+  async verify(token, key = this.defaultKey, opts) {
+    needKey(key);
+    opts = this.getOptions(opts);
+
+    let win = opts.window;
+    let cnt = opts.counter;
+    let info = { ok: false };
+
+    if (opts.debug) info.stack = [];
+
+    for (let i = cnt - win; i <= cnt + win; ++i) {
+      opts.counter = i;
+      let res = this.generate(key, opts);
+      if (opts.debug) info.stack.push(res);
+      if (res.code === token) {
+        return cp(info, { ok: true, delta: i - cnt });
+      }
+    }
+
+    if (opts.throw) {
+      let EClass = isError(opts.throw) ? opts.throw : Error;
+      throw new EClass("OTP verification failure");
+    }
+
+    return info;
+  }
+}
+
+module.exports = HOTP;

package/lib/index.js

@@ -9,8 +9,15 @@ const E = def.e;
 
 const util = require('./util');
 
+/**
+ * @alias module:@lumjs/encode.util
+ * @see {@link module:@lumjs/encode/util}
+ */
+def(exports, 'util', {value: util}, E);
+
 /**
  * @alias module:@lumjs/encode.ord
+ * @deprecated this alias to `util.ord` will be removed in 3.x.
  * @see {@link module:@lumjs/encode/util.ord}
  */
 def(exports, 'ord', util.ord, E);
@@ -18,6 +25,7 @@ def(exports, 'ord', util.ord, E);
 /**
  * @name module:@lumjs/encode.numByteArray
  * @function
+ * @deprecated this alias to `util.numByteArray` will be removed in 3.x.
  * @see {@link module:@lumjs/encode/util.numByteArray}
  */
 def(exports, 'numByteArray', util.numByteArray, E);
@@ -39,3 +47,27 @@ lazy(exports, 'Base91', () => require('./base91'), E);
  * @see {@link module:@lumjs/encode/hash}
  */
 lazy(exports, 'Hash', () => require('./hash'), E);
+
+/**
+ * @name module:@lumjs/encode.HMAC
+ * @see {@link module:@lumjs/encode/hmac}
+ */
+lazy(exports, 'HMAC', () => require('./hmac'), E);
+
+/**
+ * @name module:@lumjs/encode.HOTP
+ * @see {@link module:@lumjs/encode/hotp}
+ */
+lazy(exports, 'HOTP', () => require('./hotp'), E);
+
+/**
+ * @name module:@lumjs/encode.TOTP
+ * @see {@link module:@lumjs/encode/totp}
+ */
+lazy(exports, 'TOTP', () => require('./totp'), E);
+
+/**
+ * @name module:@lumjs/encode.Signature
+ * @see {@link module:@lumjs/encode/signature}
+ */
+lazy(exports, 'Signature', () => require('./signature'), E);

package/lib/signature.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * A small wrapepr class representing a crypto signature.
+ * @alias module:@lumjs/encode/signature
+ */
+class Signature {
+  /**
+   * Build a Signature instance.
+   * @param {ArrayBuffer} buffer - The signature data.
+   */
+  constructor(buffer) {
+    this.buffer = buffer;
+  }
+
+  /**
+   * Get the signature as a Uint8Array.
+   */
+  get uint8Array() {
+    return new Uint8Array(this.buffer);
+  }
+
+  /**
+   * Get the signature as an array of bytes.
+   */
+  get byteArray() {
+    return Array.from(this.uint8Array);
+  }
+
+  /**
+   * Get the signature as a Hex string.
+   */
+  get hex() {
+    return this.byteArray.map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+}

package/lib/totp.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const HOTP = require('./hotp');
+const DEF_OPTS = {step: 30};
+
+/**
+ * Time-based One-Time-Passwords.
+ * @exports module:@lumjs/encode/totp
+ */
+class TOTP extends HOTP {
+  get defaultOptions() {
+    return [...super.defaultOptions, DEF_OPTS];
+  }
+
+  getOptions() {
+    let opts = super.getOptions(...arguments);
+    if (!opts.time) opts.time = Date.now();
+    opts.counter = Math.floor((opts.time / 1000) / opts.step);
+    return opts;
+  }
+}
+
+module.exports = TOTP;

package/lib/util.js

@@ -2,6 +2,8 @@
  * Low-level encoding utilities
  * @module @lumjs/encode/util
  */
+'use strict';
+
 const {N} = require('@lumjs/core/types');
 
 /**
@@ -189,3 +191,42 @@ exports.wordArrayToUint8Array = function(wordArray)
   }
   return result;
 }
+
+/**
+ * Convert an integer to a byte array.
+ *
+ * This is a much simpler algorithm than numByteArray,
+ * and was borrowed from the `notp` package.
+ *
+ * @param {Integer} num
+ * @return {Array} bytes
+ */
+exports.intToBytes = function(num) 
+{
+	let bytes = [];
+
+	for(let i=7 ; i>=0 ; --i) 
+  {
+		bytes[i] = num & (255);
+		num = num >> 8;
+	}
+
+	return bytes;
+}
+
+/**
+ * Convert a hex value to a byte array.
+ *
+ * Also taken from the `notp` package.
+ *
+ * @param {String} hex string of hex to convert to a byte array
+ * @return {Array} bytes
+ */
+exports.hexToBytes = function(hex) {
+	var bytes = [];
+	for(var c = 0, C = hex.length; c < C; c += 2) {
+		bytes.push(parseInt(hex.substr(c, 2), 16));
+	}
+	return bytes;
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/encode",
-  "version": "2.1.0",
+  "version": "2.2.2",
   "main": "lib/index.js",
   "exports":
   {
@@ -8,6 +8,10 @@
     "./base64": "./lib/base64.js",
     "./base91": "./lib/base91.js",
     "./hash": "./lib/hash.js",
+    "./hmac": "./lib/hmac.js",
+    "./hotp": "./lib/hotp.js",
+    "./signature": "./lib/signature.js",
+    "./totp": "./lib/totp.js",
     "./util": "./lib/util.js",
     "./package.json": "./package.json"
   },
@@ -19,7 +23,7 @@
   },
   "dependencies": 
   {
-    "@lumjs/core": "^1.26.0"
+    "@lumjs/core": "^1.28.0"
   },
   "devDependencies":
   {