@lumjs/encode 2.3.1 → 2.4.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-01-19
+### Added
+- A new `pem` module (which exports a `PEM` class) for parsing PEM strings.
+- Tests for the `pem` module.
+- A `str2ta()` function was added to the `util` module.
+### Fixed
+- A fatal error in the `base64.encodeData()` function.
+
+## [2.3.2] - 2026-01-14
+### Fixed
+- More things I missed, sigh.
+
 ## [2.3.1] - 2026-01-14
 ### Fixed
 - Another broken reference in the HOTP library from its prototype stage.
@@ -73,7 +85,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.3.1...HEAD
+[Unreleased]: https://github.com/supernovus/lum.encode.js/compare/v2.4.0...HEAD
+[2.4.0]: https://github.com/supernovus/lum.encode.js/compare/v2.3.2...v2.4.0
+[2.3.2]: https://github.com/supernovus/lum.encode.js/compare/v2.3.1...v2.3.2
 [2.3.1]: https://github.com/supernovus/lum.encode.js/compare/v2.3.0...v2.3.1
 [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

package/lib/base64.js

@@ -65,7 +65,7 @@ function deurlize(string)
 /**
  * Convert a Base64-encoded string into a Uint8Array.
  * 
- * This is a low-level function with no options.
+ * This is a low-level function with minimal options.
  * See `decodeText()` for a more full-featured function.
  *
  * This now checks to see if `Uint8Array.fromBase64()` exists,
@@ -117,10 +117,16 @@ function fromBytes(bytes, options={})
 /**
  * Encode a string to Base64.
  * 
- * Uses the `TextEncoder` API and `fromBytes()`.
- * May optionally pass the output through `urlize()`.
+ * This adds a bunch of extra features on top of `fromBytes()`,
+ * including optionally passing the output through `urlize()`.
+ * 
+ * @param {(string|Uint8Array)} data - Data to be encoded.
+ * 
+ * If this is a String we'll use a `TextEncoder` instance to
+ * convert it into a Uint8Array before passing it to fromBytes().
+ * 
+ * If this is a Uint8Array, we can skip the TextEncoder part.
  * 
- * @param {string} data - Any valid (Unicode) string
  * @param {(object|boolean)} [options] Options
  * 
  * - If `boolean`, used as `options.url`
@@ -138,8 +144,11 @@ function encodeText(data, options={})
     options = {url: options};
   }
 
-  const encoder = new TextEncoder();
-  data = encoder.encode(data);
+  if (!(data instanceof Uint8Array))
+  {
+    const encoder = new TextEncoder();
+    data = encoder.encode(data);
+  }
   const toB64 = (typeof data.toBase64 === F);
 
   if (toB64 && options.url)
@@ -171,13 +180,15 @@ function encodeText(data, options={})
  * - Passed to `new TextDecoder()`
  * - Passed to `decoder.decode()`
  * 
- * @param {boolean} [options.url=true] Deurlize the output?
+ * @param {boolean} [options.string=true] Decode as a string?
+ * @param {boolean} [options.url=true] Deurlize the base64 string?
  * 
  * Unless this is explicitly set as `false`, the `base64`
  * string will be passed to `deurlize()` before being
  * processed further.
  * 
- * @returns {string} A Unicode string
+ * @returns {(string|Uint8Array)} 
+ * Returned type depends on `opts.string`.
  */
 function decodeText(base64, options={})
 {
@@ -186,7 +197,7 @@ function decodeText(base64, options={})
     options = {url: options};
   }
 
-  if (options.url !== false)
+  if (options.url ?? true)
   { // Unless explicitly disabled, use deurlize() first.
     if (UI8_FB64)
     {
@@ -204,9 +215,13 @@ function decodeText(base64, options={})
     }
   }
 
-  const encoding = options.encoding ?? D_ENC;
-  const decoder = new TextDecoder(encoding, options);
-  return decoder.decode(toBytes(base64, options), options);
+  const bytes = toBytes(base64, options);
+  if (options.string ?? true) {
+    const encoding = options.encoding ?? D_ENC;
+    const decoder = new TextDecoder(encoding, options);
+    return decoder.decode(bytes, options);
+  }
+  return bytes;
 }
 
 /**
@@ -324,7 +339,7 @@ async function fromDataUrl(dataUrl, options={})
  */
 async function encodeData(data, options={})
 {
-  let base64 = await toDataUrl(data, options).replace(R_PRE, '');
+  let base64 = (await toDataUrl(data, options)).replace(R_PRE, '');
   return options.url ? urlize(base64, options) : base64;
 }
 

package/lib/hash.js

@@ -3,6 +3,7 @@
 const {S,F,isObj,isNil} = require('@lumjs/core/types');
 
 const util   = require('./util');
+const base32 = require('./base32');
 const base64 = require('./base64');
 const base91 = require('./base91');
 
@@ -156,6 +157,7 @@ module.exports = class
 
     this.defaults =
     {
+      base32: options.base32 ?? {},
       base64: options.base64 ?? {},
       base91: options.base91 ?? {},
     }
@@ -289,6 +291,22 @@ module.exports = class
     return (hashArr.map((b)=>b.toString(16).padStart(2, "0")).join(""));
   }
 
+  /**
+   * Get hash as a Base32-encoded string.
+   * 
+   * @param {(string|object|null)} [input]
+   * See [hash()]{@link module:@lumjs/encode/hash#hash}
+   * 
+   * @param {object} [options] Options to pass to base32.encode().
+   * 
+   * @returns {string}
+   */
+  async base32(input, opts=this.defaults.base32)
+  {
+    const hash = await this.hash(input);
+    return base32.encode(new Uint8Array(hash), opts);
+  }
+
   /**
    * Get hash as a Base64-encoded string.
    *
@@ -311,12 +329,14 @@ module.exports = class
   /**
    * Get hash as a Base91-encoded string.
    * 
-   * @param {(string|WordArray)} [input] 
+   * @param {(string|object|null)} [input] 
    * See [hash()]{@link module:@lumjs/encode/hash#hash}
    * @param {object} [opts] Options for how to encode the hash.
    * 
    * @param {(boolean|object)} [opts.nba=false] Use `numByteArray()` ?
    * 
+   * This options is deprecated and will be removed in v3.0.
+   * 
    * If this is `true` the *hash string* will be passed to `numByteArray()`
    * with the *default options* and the output from that will be passed to 
    * `base91.encode()`.

package/lib/index.js

@@ -66,6 +66,12 @@ lazy(exports, 'HMAC', () => require('./hmac'), E);
  */
 lazy(exports, 'HOTP', () => require('./hotp'), E);
 
+/**
+ * @name module:@lumjs/encode.PEM
+ * @see {@link module:@lumjs/encode/pem}
+ */
+lazy(exports, 'PEM', () => require('./pem'), E);
+
 /**
  * @name module:@lumjs/encode.TOTP
  * @see {@link module:@lumjs/encode/totp}

package/lib/pem.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const { str2ta } = require('./util');
+
+const UI8_FB64 = (typeof Uint8Array.fromBase64 === 'function');
+const PEM_TEXT = /^\s*-----BEGIN\s+(?<label>[A-Z\s]+)-----\n(?<base64>.*?)\n-----END\s+\k<label>-----\s*$/s;
+const parseText = (str) => (PEM_TEXT.exec(str)?.groups ?? null);
+const validInfo = (pem) => (pem
+  && typeof pem === 'object' 
+  && typeof pem.label === 'string'
+  && typeof pem.base64 === 'string'
+);
+
+/**
+ * A class for parsing and decoding PEM documents.
+ * 
+ * PEM is a format commonly used for encryption keys.
+ * See: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
+ * 
+ * @alias {module:@lumjs/encode/pem}
+ */
+class PEM {
+
+  /**
+   * Parse a string into a PEM object instance.
+   * 
+   * This method is strict and will throw an error on failure.
+   * For a more lenient way to parse PEM documents, see the
+   * {@link module:@lumjs/encode/pem.parse parse()} method. 
+   * 
+   * @param {string} pem - PEM format string to be parsed.
+   * @throws {TypeError} If the `pem` argument is an invalid value.
+   * @throws {SyntaxErrror} If the `pem` string was not able to be parsed.
+   */
+  constructor(pem) {
+
+    if (typeof pem === 'string') {
+      let pemStr = pem;
+      pem = parseText(pemStr);
+      if (!validInfo(pem)) {
+        console.error('new PEM()', pemStr);
+        throw new SyntaxError("invalid PEM string passed to PEM constructor");
+      }
+    }
+    else if (!validInfo(pem)) {
+      console.error('new PEM()', pem);
+      throw new TypeError("invalid argument passed to PEM constructor");
+    }
+
+    // Copy the properties from the info into this.
+    Object.assign(this, pem);
+  }
+
+  /**
+   * Decode the base64 content.
+   * 
+   * @param {(boolean|function)} [typeClass=false] Return a TypedArray?
+   * 
+   * This may be set to the constructor function of any TypedArray class.
+   * It may also be set to `true` as an alias for `Uint8Array`.
+   * 
+   * If it is set to `false` (the default), then the binary string output
+   * from the `atob()` global function will be used as the return value.
+   * 
+   * If this is set to Uint8Array (either explicitly or by using `true`),
+   * and a method named `Uint8Array.fromBase64` exists, then this will use
+   * that to parse the base64 content rather than using the
+   * {@link module:@lumjs/encode/util.str2ta str2ta()} function.
+   * 
+   * @returns {(string|TypedArray|Error)}
+   * 
+   * If an error is thrown by any functions being used to decode the base64
+   * content, that error will be the return value.
+   * 
+   * Otherwise the `typeClass` argument will determine the returned type.
+   */
+  decode(typeClass=false) {
+    if (typeClass === true) {
+      typeClass = Uint8Array;
+    }
+
+    let val = null;
+
+    if (UI8_FB64 && typeClass === Uint8Array) { 
+      try {
+        val = typeClass.fromBase64(this.base64);
+      } catch (err) {
+        return err;
+      }
+      return val;
+    }
+
+    try {
+      val = atob(this.base64); 
+    } catch (err) {
+      return err;
+    }
+    
+    if (typeClass && typeof val === 'string') {
+      try {
+        val = str2ta(val, typeClass);
+      } catch (err) {
+        return err;
+      }
+    }
+
+    return val;
+  }
+
+  /**
+   * Parse a string into a PEM object instance.
+   * 
+   * This is almost identical to the main class constructor,
+   * except this version will simply return null if the argument
+   * could not be parsed as a valid PEM string.
+   * 
+   * @param {string} pemText - PEM format string to be parsed.
+   * @returns {?module:@lumjs/encode/pem} A PEM instance;
+   * or null if the pemText could not be parsed.
+   */
+  static parse(pemText) {
+    let info = parseText(pemText);
+    return info ? new this(info) : info;
+  }
+
+}
+
+module.exports = PEM;

package/lib/util.js

@@ -4,7 +4,7 @@
  */
 'use strict';
 
-const {N} = require('@lumjs/core/types');
+const { TypedArray } = require('@lumjs/core/types');
 
 /**
  * Return the ASCII/Unicode number for a character.
@@ -96,7 +96,7 @@ exports.ord = function (string)
  */
 exports.numByteArray = function (numStr, options={})
 {
-  if (typeof options === N)
+  if (typeof options === 'number')
   {
     options = {size: options};
   }
@@ -104,7 +104,7 @@ exports.numByteArray = function (numStr, options={})
   const numOpt = (name, defval, min, max) => 
   {
     const optval = options[name];
-    if (typeof optval !== N)
+    if (typeof optval !== 'number')
     { // Was not a number, skip it.
       return defval;
     }
@@ -230,3 +230,43 @@ exports.hexToBytes = function(hex) {
 	return bytes;
 }
 
+/**
+ * Convert a binary string into a TypedArray.
+ * 
+ * Inspired by the str2ab() example from:
+ * https://developer.chrome.com/blog/how-to-convert-arraybuffer-to-and-from-string
+ * 
+ * The biggest difference being this version supports specifying the specific
+ * TypedArray class you want to use, and it returns the TypedArray by default
+ * rather than the ArrayBuffer. 
+ * 
+ * To get the ArrayBuffer just use: `str2ta(string).buffer;` 
+ * 
+ * @param {string} str - Binary string to convert.
+ * @param {function} [typeClass=Uint8Array] TypedArray class to use;
+ * MUST be a TypedArray class constructor. Default is `Uint8Array`.
+ * @returns {TypedArray} Will be an instance of `typeClass`.
+ * @throws {TypeError} If invalid arguments were passed.
+ */
+function str2ta(str, typeClass=Uint8Array) 
+{
+  let valid = {
+    str: (typeof str === 'string'),
+    typeClass: (TypedArray.isPrototypeOf(typeClass)),
+  }
+  if (!valid.str || !valid.typeClass) {
+    console.error('str2ab valid:', valid, 'values: ', {str, typeClass});
+    throw new TypeError("invalid arguments");
+  }
+
+  let buf = new ArrayBuffer(str.length*typeClass.BYTES_PER_ELEMENT);
+  let bufView = new typeClass(buf);
+  for (let i = 0, strLen = str.length; i < strLen; i++) 
+  {
+    bufView[i] = str.charCodeAt(i);
+  }
+
+  return bufView;
+}
+
+exports.str2ta = str2ta;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/encode",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "main": "lib/index.js",
   "exports":
   {
@@ -11,6 +11,7 @@
     "./hash": "./lib/hash.js",
     "./hmac": "./lib/hmac.js",
     "./hotp": "./lib/hotp.js",
+    "./pem": "./lib/pem.js",
     "./signature": "./lib/signature.js",
     "./totp": "./lib/totp.js",
     "./util": "./lib/util.js",