@lumjs/encode 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0]
+### 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]
 ### Changed
 - The `base64` library now supports the `Uint8Array.fromBase64` static method,

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');

package/lib/hmac.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const Signature = require('./signature');
+
+const HMAC = 'HMAC';
+const DEF_OPTS = { algorithm: 'SHA-256' };
+
+/**
+ * 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._key) {
+      return this._key;
+    }
+
+    let hmac = { name: HMAC, hash: this.options.algorithm }
+    let key = await crypto.subtle.importKey(
+      "raw",              // Key format
+      this.keyBytes,      // Key data
+      hmac,               // Algorithm
+      false,              // Not extractable
+      ["sign"]            // Usages
+    );
+
+    this._key = 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,112 @@
+'use strict';
+
+const HmacEncoder = require('./hmac');
+const { intToBytes } = require('./util');
+
+const DEF_OPTS = { algorithm: 'SHA-1', 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(LEN - 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,6 +9,12 @@ 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
  * @see {@link module:@lumjs/encode/util.ord}
@@ -39,3 +45,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.0",
   "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":
   {