@lumjs/encode 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@ 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,
+  and the corresponding `toBase64()` instance method. As those are rather new
+  APIs and aren't supported by every JS runtime yet, it will check for them and
+  use them if found, and fall back to the prior implementation otherwise.
+- Updated this changelog, as I forgot to after 2.0 was released last year.
+
+## [2.0.0] - 2024-08-14
+### Changed
+- A major overhaul, removing the dependency on `crypto-js` library.
+- Rewrote `base64` library to use `atob`, `btoa`, `TextEncoder`, and `TextDecoder`.
+- Rewrote `hash` library using the modern `SubtleCrypto` APIs.
+- Moved `urlize()` and `deurlize()` functions into `base64` library.
+### Removed
+- The `crypto` sub-module which was designed as a wrapper for `crypto-js`.
+- The `safe64` library has been moved into a standalone [safe64-data] package.
+- Dependencies on `php-serialize` and `ubjson` which were only used by `safe64`.
+
 ## [1.2.0] - 2023-01-06
 ### Changed
 - Bumped `@lumjs/core` to `1.8.0`.
@@ -23,7 +52,11 @@ 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/v1.2.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v2.1.0...HEAD
+[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
 [1.1.0]: https://github.com/supernovus/lum.encode.js/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/supernovus/lum.encode.js/releases/tag/v1.0.0
+[safe64-data]: https://github.com/supernovus/lum.safe64-data.js
+

package/TODO.md

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

package/lib/base64.js

@@ -1,11 +1,15 @@
 
-const {S,B,isObj} = require('@lumjs/core/types');
+const {S,B,F,isObj} = require('@lumjs/core/types');
 
 const D_MIME = 'application/octet-stream';
 const D_ENC  = 'utf-8';
 const P_DATA = 'data:';
 const P_B64  = ';base64,';
 const R_PRE  = /^data\:(.*?);base64,/;
+const B_64U  = 'base64url';
+
+const UI8_FB64  = (typeof Uint8Array.fromBase64 === F);
+const URL_CHARS = /_-/;
 
 /**
  * Base64 functions.
@@ -63,12 +67,22 @@ function deurlize(string)
  * 
  * This is a low-level function with no options.
  * See `decodeText()` for a more full-featured function.
+ *
+ * This now checks to see if `Uint8Array.fromBase64()` exists,
+ * and if it does, will use it. Otherwise it uses the original
+ * encoding algorithm.
  * 
  * @param {string} base64 - Base64 encoded-string
+ * @param {object} [options] Passed to fromBase64() if it exists
  * @returns {Uint8Array}
  */
-function toBytes(base64)
+function toBytes(base64, options={})
 {
+  if (UI8_FB64)
+  {
+    return Uint8Array.fromBase64(base64, options);
+  }
+
   const binString = atob(base64);
   return Uint8Array.from(binString, (m) => m.codePointAt(0));
 }
@@ -78,12 +92,22 @@ function toBytes(base64)
  * 
  * This is a low-level function with no options.
  * See `encodeText()` for a more full-featured function.
+ *
+ * This now checks to see if `bytes.toBase64()` exists,
+ * and if it does, will use it. Otherwise it uses the original
+ * decoding algorithm.
  * 
  * @param {Uint8Array} bytes - Byte array to convert
+ * @param {object} [options] Passed to toBase64() if it exists
  * @returns {string}
  */
-function fromBytes(bytes)
+function fromBytes(bytes, options={})
 {
+  if (typeof bytes.toBase64 === F)
+  {
+    return bytes.toBase64(options);
+  }
+
   const binString = Array.from(bytes, (byte) =>
     String.fromCodePoint(byte),
   ).join("");
@@ -115,8 +139,23 @@ function encodeText(data, options={})
   }
 
   const encoder = new TextEncoder();
-  const base64 = fromBytes(encoder.encode(data));
-  return options.url ? urlize(base64, options) : base64;
+  data = encoder.encode(data);
+  const toB64 = (typeof data.toBase64 === F);
+
+  if (toB64 && options.url)
+  {
+    if (typeof options.alphabet !== S)
+    {
+      options.alphabet = B_64U;
+    }
+    if (!options.useTildes && typeof options.omitPadding !== B)
+    {
+      options.omitPadding = true;
+    }
+  }
+
+  const base64 = fromBytes(data, options);
+  return (options.url && !toB64) ? urlize(base64, options) : base64;
 }
 
 /**
@@ -149,12 +188,25 @@ function decodeText(base64, options={})
 
   if (options.url !== false)
   { // Unless explicitly disabled, use deurlize() first.
-    base64 = deurlize(base64);
+    if (UI8_FB64)
+    {
+      if (typeof options.alphabet !== S)
+      {
+        if (URL_CHARS.test(base64))
+        {
+          options.alphabet = B_64U;
+        }
+      }
+    }
+    else
+    { 
+      base64 = deurlize(base64);
+    }
   }
 
   const encoding = options.encoding ?? D_ENC;
   const decoder = new TextDecoder(encoding, options);
-  return decoder.decode(toBytes(base64), options);
+  return decoder.decode(toBytes(base64, options), options);
 }
 
 /**
@@ -373,4 +425,6 @@ module.exports =
   toDataUrl, fromDataUrl,
   encodeData, decodeData,
   encode, decode,
+  NATIVE_BASE64: UI8_FB64,
 }
+

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.0.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":
   {