@lumjs/encode 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -6,7 +6,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.2.0]
+## [2.3.0] - 2026-01-13
+### Added
+- New `base32` module with encoding and decoding of four variants of Base32.
+- Tests for the `base32` module.
+
+## [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.
@@ -16,7 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   module, this one has two JS classes and uses the SubtleCrypto API.
 - A TODO file with things I want to do.
 
-## [2.1.0]
+## [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
@@ -52,7 +68,10 @@ 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.3.0...HEAD
+[2.3.0]: https://github.com/supernovus/lum.encode.js/compare/v2.2.2...v2.3.0
+[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/lib/base32.js

@@ -0,0 +1,227 @@
+/**
+ * Base32 encoding in pure JS.
+ * 
+ * Originally based on an implementation from Richard Thiessen:
+ * https://gist.github.com/RichardThiessen/5a4e32d57aafd5430c09122f23e4b757
+ * 
+ * With a lot of my own tweaks and enhancements obviously.
+ * 
+ * @module @lumjs/encode/base32
+ */
+'use strict';
+
+const { isObj } = require('@lumjs/core/types');
+const cp = Object.assign;
+const lock = Object.freeze;
+
+/**
+ * Supported Base32 variants.
+ * 
+ * Unlike Base64 which typically only has two versions (which only have minor
+ * differences), Base32 has multiple variants which use vastly different
+ * encoding alphabets. We support a handful of well known variants.
+ * 
+ * For every lowercase property name in this object, there is
+ * also an uppcase alias that is the exact same type definition.
+ * 
+ * This namespace object is also exported as `TYPES`.
+ * 
+ * @alias module:@lumjs/encode/base32.Base32Types
+ */
+const Base32Types = {
+  /** The RFC4648 standard format. */
+  rfc4648: lock(['ABCDEFGHIJKLMNOPQRSTUVWXYZ234567']),
+  /** The zbase32 variant. */
+  zbase32: lock(['ybndrfg8ejkmcpqxot1uwisza345h769']),
+  /** The geohash variant. */
+  geohash: lock(['0123456789bcdefghjkmnpqrstuvwxyz']),
+  /** Douglas Crockford's variant. */
+  crockford: lock(['0123456789ABCDEFGHJKMNPQRSTVWXYZ', 'O0', 'I1', 'L1']),
+}
+
+/**
+ * An alias to RFC4648 recognizing that it is the default variant.
+ */
+Base32Types.default = Base32Types.rfc4648;
+
+for (let lcid in Base32Types) {
+  let ucid = lcid.toUpperCase();
+  Base32Types[ucid] = Base32Types[lcid];
+}
+
+lock(Base32Types);
+
+const UTF8 = 'utf-8';
+const encodeText = s => new TextEncoder(UTF8).encode(s);
+const decodeText = b => new TextDecoder(UTF8).decode(b);
+
+function _opts(opts, bopt) {
+  if (typeof opts === 'string' || Array.isArray(opts)) {
+    opts = { type: opts };
+  }
+  else if (typeof opts === 'boolean') {
+    return { [bopt]: opts, type: Base32Types.default };
+  }
+  else if (!isObj(opts)) {
+    return { type: Base32Types.default }
+  }
+
+  if (typeof opts.type === 'string') {
+    if (Array.isArray(Base32Types[opts.type])) {
+      opts.type = Base32Types[opts.type];
+    }
+    else {
+      console.error("unknown base32 type", opts.type, opts);
+      opts.type = Base32Types.default;
+    }
+  }
+  else if (Array.isArray(opts.type)) {
+    if (typeof opts.type[0] !== 'string' || opts.type[0].length !== 32) {
+      console.error("invalid base32 type def", opts.type, opts);
+      opts.type = Base32Types.default;
+    }
+  }
+  else {
+    if (opts.type !== undefined) {
+      console.error("invalid base32 type option value", opts.type, opts);
+    }
+    opts.type = Base32Types.default;
+  }
+
+  return opts;
+}
+
+function _b32_map(typedef) {
+  let alphabet = typedef[0].toUpperCase();
+  let aliases = typedef.slice(1);
+  let lookup = new Map(alphabet.split("").map((c, i) => [c, i]));
+  aliases.map(x => lookup.set(x[0], lookup.get(x[1])));
+  return lookup;
+}
+
+/**
+ * Decode a Base32-encoded string.
+ * @param {string} str - Base32 string.
+ * @param {(object|string)} [opts] Options.
+ * 
+ * If this is a boolean it will be used as `opts.string`.
+ * 
+ * If this is a string or one of the `Base32Types` properties,
+ * it will be used as `opts.type`.
+ * 
+ * @param {(string|Array)} [opts.type] Base32 variant to use.
+ * 
+ * If this is a string it must be the name (uppercase or lowercase)
+ * of one of the properties in the `Base32Types` object.
+ * 
+ * If it is an Array it is expected that it is one of the properties
+ * from the Base32Types, or a compatible type def where the first
+ * item in the array is a string consisting of exactly 32 unique characters.
+ * 
+ * @param {boolean} [opts.string=false] Return a UTF-8 string?
+ * 
+ * If this is true then we will assume the original encoded value was a UTF-8
+ * string, and will decode it as such using a TextDecoder instance.
+ * 
+ * If this is false (the default) we will return a Uint8Array.
+ * 
+ * @returns {(Uint8Array|string)}
+ * @alias module:@lumjs/encode/base32.decode
+ */
+function base32Decode(str, opts) {
+  opts = _opts(opts, 'string');
+  let lookup = _b32_map(opts.type);
+  // remove whitespace and padding
+  str = str.replace(/\s+/g, "").replace(/=*$/g, "");
+  let vals = str.toUpperCase().split("").map(c => lookup.get(c));
+  if (vals.indexOf(undefined) != -1) {
+    throw new RangeError("Base32: string includes non-Base32 characters");
+  }
+
+  let bytes = new Uint8Array((vals.length * 5 / 8) | 0);
+  for (let i = 0; i < vals.length; i += 8) {
+    //do all, missing indices will fail silently
+    let b_o = (i / 8 * 5) | 0;
+    bytes[b_o + 0] = (vals[i + 0] << 3) | (vals[i + 1] >> 2);
+    bytes[b_o + 1] = (vals[i + 1] << 6) | (vals[i + 2] << 1) | (vals[i + 3] >> 4);
+    bytes[b_o + 2] = (vals[i + 3] << 4) | (vals[i + 4] >> 1);
+    bytes[b_o + 3] = (vals[i + 4] << 7) | (vals[i + 5] << 2) | (vals[i + 6] >> 3);
+    bytes[b_o + 4] = (vals[i + 6] << 5) | (vals[i + 7] >> 0);
+  }
+
+  return opts.string ? decodeText(bytes) : bytes;
+}
+
+/**
+ * Encode a value into a Base32 string.
+ * 
+ * @param {(ArrayBuffer|TypedArray|string)} data - Data to be encoded.
+ * 
+ * If this is a string it will be converted into a Uint8Array using a
+ * TextEncoder instance.
+ * 
+ * @param {(object|string|boolean)} [opts] Options.
+ * 
+ * If this is a boolean it will be used as `opts.pad`.
+ * 
+ * If this is a string or one of the `Base32Types` properties,
+ * it will be used as `opts.type`.
+ * 
+ * @param {(string|Array)} [opts.type] Base32 variant to use.
+ * 
+ * If this is a string it must be the name (uppercase or lowercase)
+ * of one of the properties in the `Base32Types` object.
+ * 
+ * If it is an Array it is expected that it is one of the properties
+ * from the Base32Types, or a compatible type def where the first
+ * item in the array is a string consisting of exactly 32 unique characters.
+ * 
+ * @param {boolean} [opts.pad=true] Add `=` padding characters?
+ * 
+ * Base32 (like Base64) uses `=` as a padding character to ensure the length
+ * of the encoded strings are divisible by 8. As that is a part of
+ * the standard specification, this option defaults to true.
+ * 
+ * If you explicitly set this to false the string won't have any padding
+ * added to it, regardless of its length.
+ * 
+ * @returns {string}
+ * @alias module:@lumjs/encode/base32.encode
+ */
+function base32Encode(buf, opts) {
+  opts = _opts(opts, 'pad');
+  let alphabet = opts.type[0];
+  if (buf.byteLength === undefined) { //not Arraybuffer?
+    buf = encodeText(buf);
+  }
+
+  //may need extra zero at end of buf for some bits of last value
+  let bytes = new Uint8Array(buf.byteLength + 1);
+  bytes.set(buf, 0)
+  let out = new Uint8Array(((buf.byteLength * 8 + 4) / 5) | 0);
+
+  for (let i = 0; i < out.length; i += 8) {
+    //do all,missing indices will fail silently
+    let b_o = (i / 8 * 5) | 0;
+    out[i + 0] = (bytes[b_o + 0] >> 3);
+    out[i + 1] = (bytes[b_o + 0] << 2) | (bytes[b_o + 1] >> 6);
+    out[i + 2] = (bytes[b_o + 1] >> 1);
+    out[i + 3] = (bytes[b_o + 1] << 4) | (bytes[b_o + 2] >> 4);
+    out[i + 4] = (bytes[b_o + 2] << 1) | (bytes[b_o + 3] >> 7);
+    out[i + 5] = (bytes[b_o + 3] >> 2);
+    out[i + 6] = (bytes[b_o + 3] << 3) | (bytes[b_o + 4] >> 5);
+    out[i + 7] = (bytes[b_o + 4] >> 0);
+  }
+  
+  let str = Array.from(out.entries(), x => alphabet[x[1] & 31]).join("");
+  if (opts.pad ?? true) {
+    str = str.padEnd(out.length + (8 - (out.length % 8)) % 8, "=");
+  }
+  return str;
+}
+
+module.exports = {
+  Base32Types, TYPES: Base32Types,
+  base32Encode, encode: base32Encode,
+  base32Decode, decode: base32Decode,
+}

package/lib/hash.js

@@ -27,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,
@@ -184,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.
@@ -299,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;
   }
 
   /**
@@ -332,7 +337,7 @@ module.exports = class
 
     if (nba)
     {
-      hash = util.numByteArray(hash);
+      hash = util.numByteArray(hash, nba);
     }
 
     return base91.encode(new Uint8Array(hash));
@@ -343,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

@@ -2,8 +2,14 @@
 
 const Signature = require('./signature');
 
+const CKEY = Symbol('@lumjs/encore/hmac~key');
 const HMAC = 'HMAC';
-const DEF_OPTS = { algorithm: 'SHA-256' };
+const DEF_OPTS = {
+  algorithm: 'SHA-256',
+  extractable: false,
+  keyFormat: 'raw', 
+  usages: ['sign'] 
+};
 
 /**
  * The main class to perform HMAC signing.
@@ -31,20 +37,20 @@ class HmacEncoder {
    * @returns {Promise<CryptoKey>}
    */
   async getKey() {
-    if (this._key) {
-      return this._key;
+    if (this[CKEY]) {
+      return this[CKEY];
     }
 
     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.options.keyFormat,   // Key format
+      this.keyBytes,            // Key data
+      hmac,                     // Algorithm
+      this.options.extractable, // Is key extractable
+      this.options.usages,      // Allowed key usages
     );
 
-    this._key = key;
+    this[CKEY] = key;
     return key;
   }
 

package/lib/hotp.js

@@ -3,7 +3,12 @@
 const HmacEncoder = require('./hmac');
 const { intToBytes } = require('./util');
 
-const DEF_OPTS = { algorithm: 'SHA-1', counter: 0, window: 50 };
+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));
@@ -62,7 +67,7 @@ class HOTP {
       (hb[offset + 3] & 0xff);
 
     let v2 = (v1 % 1000000) + '';
-    let code = Array(LEN - v2.length).join('0') + v2;
+    let code = Array(opts.checkSize - v2.length).join('0') + v2;
 
     let res = {
       opts,

package/lib/index.js

@@ -17,6 +17,7 @@ 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);
@@ -24,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);

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@lumjs/encode",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "main": "lib/index.js",
   "exports":
   {
     ".": "./lib/index.js",
+    "./base32": "./lib/base32.js",
     "./base64": "./lib/base64.js",
     "./base91": "./lib/base91.js",
     "./hash": "./lib/hash.js",