@lumjs/encode 1.0.0

package/lib/crypto/load.js

@@ -0,0 +1,344 @@
+const {F,S,isObj} = require('@lumjs/core/types');
+
+/**
+ * Crypto-JS Module Loader
+ * 
+ * Uses some dark magic to normalize any weirdness, bugs, 
+ * or gotchyas in the upsteam library.
+ * 
+ * @module @lumjs/encode/crypto/load
+ */
+
+const cc = require('crypto-js/core');
+
+/**
+ * Load and return a specific `crypto-js` module.
+ * 
+ * This is a wrapper for `require()` that prefixes
+ * the `crypto-js/` package namespace.
+ * 
+ * Generally you should never have to call this manually.
+ * Instead use one of the more specialized methods.
+ * 
+ * Note that **this** is the actual *default export* from
+ * the `load` module, and all the other functions are
+ * child properties of it.
+ * 
+ * @param {string} name - The name of the module.
+ * 
+ * @param {boolean} [toLower=true] Enforce lowercase names?
+ * 
+ * If `true` (the default value), the `name` will be
+ * normalized to *lowercase* as is expected by the library.
+ * 
+ * @returns {(object|function)} The module content.
+ * 
+ * Some `crypto-js` modules return a child `object`, some return
+ * a child `function`, and some return the `crypto-js/core` object.
+ * The wide difference in return values is part of why this
+ * method should not be used directly.
+ * 
+ * @alias module:@lumjs/encode/crypto/load.load
+ */
+function load(name, toLower=true)
+{
+  if (toLower)
+    name = name.toLowerCase();
+  return require('crypto-js/'+name);
+}
+
+// Export the load function, and make all other functions properties of it.
+module.exports = exports = load;
+load.load = load; // Fuckery.
+
+/**
+ * Get a Hashing function or progressive instance.
+ * 
+ * @param {string} name - The name of the algorithm.
+ *
+ * Hashing algorithms supported by `crypto-js`:
+ * 
+ * - MD5
+ * - SHA-1
+ * - SHA-256
+ * - SHA-512
+ * - SHA-224
+ * - SHA-384
+ * - SHA-3
+ * - RIPEMD-160
+ * 
+ * You can omit the `-` characters, and the parameter is
+ * case-insensitive.
+ *
+ * @param {(boolean|object)} [instance=false] Return an instance?
+ * 
+ * If this is `true` we'll return an object instance for
+ * progressive hashing.
+ * 
+ * If this is an `object`, we'll return an object instance, and
+ * this will be passed as the options to the `algo.create()` method.
+ * 
+ * If this is `false` (default), we'll return a hashing function.
+ * 
+ * @returns {(function|object)} Output depends on parameters.
+ */
+exports.hash = function(name, instance=false)
+{
+  if (instance)
+  { // Return a progressive instance.
+    const algo = load.algo(name);
+    const opts = isObj(instance) ? instance : {};
+    return algo.create(opts);
+  }
+  else 
+  { // Return a hashing function.
+    return load(name.replaceAll('-', ''));
+  }  
+}
+
+/**
+ * Get a `HMAC` Hashing function or progressive instance.
+ * 
+ * @param {string} libName - Name of the hashing algorithm to use.
+ *
+ *   See {@link module:@lumjs/encode/crypto/load.hash} for a list.
+ *
+ * @param {string} [passphrase] - A secret passphrase for a hashing instance.
+ * 
+ * If this is specified, we'll return an object instance for
+ * progressive hashing.
+ * 
+ * If this is **not** specified, we'll return a hashing function.
+ * 
+ * @returns {(object|function)} Output depends on parameters.
+ */
+exports.hmac = function(libName, passphrase)
+{
+  if (typeof passphrase === S)
+  { // Return a progressive instance.
+    const algo = load.algo(libName);
+    const hmac = load.algo('HMAC');
+    return hmac.create(algo, passphrase);
+  }
+  else 
+  { // Return a hashing function.
+    return load('hmac-'+libName.replaceAll('-', ''));
+  }
+}
+
+const Ciphers =
+{
+  rc4drop()
+  {
+    load('rc4', false);
+    return cc.RC4Drop;
+  },
+  des()
+  {
+    load('tripledes', false);
+    return cc.DES;
+  }
+}
+
+/**
+ * Get a cipher transcoder.
+ * 
+ * @param {string} name - The name of the algorithm.
+ *
+ * Cipher algorithms supported by `crypto-js`:
+ * 
+ * - AES
+ * - DES
+ * - TripleDES
+ * - Rabbit
+ * - RabbitLegacy
+ * - RC4
+ * - RC4Drop
+ * 
+ * The parameter is case-insensitive.
+ *
+ * @returns {function} The hashing function.
+ */
+exports.cipher = function(name)
+{
+  name = name.replaceAll('-', '').toLowerCase();
+  if (typeof Ciphers[name] === F)
+  { // A custom loader function.
+    return Ciphers[name]();
+  }
+  return load(name, false);
+}
+
+const Algos =
+{
+  RC4DROP()
+  {
+    load('rc4', false);
+    return cc.algo.RC4Drop;
+  },
+  des()
+  {
+    load('tripledes', false);
+    return cc.algo.DES;
+  },
+  TRIPLEDES: 'TripleDES',
+  RABBIT: 'Rabbit',
+  RABBITLEGACY()
+  {
+    load('rabbit-legacy', false);
+    return cc.algo.RabbitLegacy;
+  },
+}
+
+/**
+ * Get an algorithm plugin.
+ *
+ * @param {string} name - The name of the algorithm
+ *
+ * It can be any algorithm supported by either
+ * the [hash()]{@link module:@lumjs/encode/crypto.hash}
+ * or [cipher()]{@link module:@lumjs/encode/crypto.cipher}
+ * as well as standalone algorithms like `PBKDF2`, `HMAC`, `EvpKDF`, etc.
+ *
+ * @returns {object} The algorithm plugin.
+ * 
+ * You'll need to use the `create()` method on the plugin to get
+ * an instance before you can start hashing.
+ * 
+ */
+exports.algo = function(name)
+{
+  name = name.replaceAll('-','').toUpperCase();
+
+  if (typeof Algos[name] === F)
+  { // A custom loader.
+    return Algos[name]();
+  }
+  else if (typeof Algos[name] === S)
+  { // A specific case-sensitive spelling.
+    name = Algos[name];
+  }
+
+  // We make sure the library is loaded.
+  load(name);
+
+  // Now we'll get the object out of the core.
+  return cc.algo[name];
+}
+
+const Encoders =
+{
+  utf16be()
+  {
+    load('enc-utf16', false);
+    return cc.enc.Utf16BE;
+  },
+  utf16le()
+  {
+    load('enc-utf16', false);
+    return cc.enc.Utf16LE;
+  },
+}
+
+/**
+ * Get an encoder plugin.
+ * 
+ * @param {*} name - The name of the encoder.
+ * 
+ * Encoders supported:
+ * 
+ * - Base64
+ * - Base64-URL
+ * - Latin1
+ * - Hex
+ * - UTF-8
+ * - UTF-16
+ * - UTF-16LE
+ * 
+ * You can omit the `-` characters, and the parameter is
+ * case-insensitive.
+ * 
+ * @returns {object} The encoder plugin.
+ */
+exports.enc = function(name)
+{
+  name = name.replaceAll('-','').toLowerCase();
+
+  if (typeof Encoders[name] === F)
+  { // A custom loader.
+    return Encoders[name]();
+  }
+
+  // We make sure the library is loaded.
+  return load('enc-'+name, false);
+}
+
+const Paddings =
+{
+  ansix923()
+  { // This module has a typo in it, correcting that here.
+    load('pad-ansix923', false);
+    return cc.pad.AnsiX923;
+  }
+}
+
+/**
+ * Get a padding plugin.
+ * 
+ * @param {string} name - Name of the plugin.
+ * @returns {object}
+ */
+exports.pad = function(name)
+{
+  name = name.replaceAll('-','').toLowerCase();
+
+  if (typeof Paddings[name] === F)
+  { // A custom loader.
+    return Paddings[name]();
+  }
+
+  return load('pad-'+name, false);
+}
+
+const Modes =
+{
+  CBC()
+  { // Built-in mode, no load required.
+    return cc.mode.CBC;
+  },
+  CTRGLADMAN()
+  { // Filename fuckery.
+    return load('mode-ctr-gladman', false);
+  }
+}
+
+/**
+ * Get a mode plugin.
+ * 
+ * @param {string} name - Name of the plugin.
+ * @returns {object}
+ */
+exports.mode = function(name)
+{
+  name = name.replaceAll('-','').toUpperCase();
+
+  if (typeof Modes[name] === F)
+  { // A custom loader.
+    return Modes[name]();
+  }
+
+  return load('mode-'+name);
+}
+
+/**
+ * Get a format plugin.
+ * 
+ * @param {string} name - Name of the plugin.
+ * @returns {object}
+ */
+exports.format = function(name)
+{
+  return load('format-'+name);
+}
+
+// That's all folks.

package/lib/hash.js

@@ -0,0 +1,244 @@
+const {S,F,isObj,isNil} = require('@lumjs/core/types');
+
+const util   = require('./util');
+const Base91 = require('./base91');
+const Safe64 = require('./safe64');
+const Crypto = require('./crypto');
+const cload  = Crypto.load;
+
+const DEFALGO = 'SHA256';
+
+/**
+ * Hashifier
+ * 
+ * A simple yet flexible class for building cryptographic hashes.
+ * 
+ * @exports module:@lumjs/encode/hash
+ */
+module.exports = class
+{
+  /**
+   * Build a new Hashifier
+   *
+   * @param {(object|string)} [options] Options
+   * 
+   * If this is a `string`, it's assumed to be the `options.algo` option.
+   * 
+   * @param {string} [options.algo="SHA256"] Hashing algorithm
+   *
+   * By default we use "SHA256" for backwards compatibility with my
+   * older libraries and apps. You can set it to any *hashing algorithm*
+   * from the `crypto-js` library (we use our own 
+   * [crypto]{@link module:@lumjs/encode/crypto} helper.)
+   * 
+   * @param {object} [options.safe64] Default options for `safe64()`
+   * 
+   * If specified, this will become the default options for the
+   * [safe64()]{@link module:@lumjs/encode/hash#safe64} method.
+   * 
+   * @param {object} [options.base91] Default options for `base91()`
+   * 
+   * If specified, this will become the default options for the
+   * [base91()]{@link module:@lumjs/encode/hash#base9164} method.
+   *
+   */
+  constructor(options={})
+  {
+    if (typeof options === S)
+    {
+      options = {algo: options};
+    }
+
+    const algo = options.algo ?? DEFALGO;
+
+    this.algoLib = cload.algo(algo);
+    this.hashFunction = cload.hash(algo);
+
+    //console.debug("<hash>", {hash: this, algo, options});
+
+    if (!isObj(this.algoLib) || typeof this.hashFunction !== F)
+    {
+      throw new Error("Invalid hashing algorithm");
+    }
+
+    this.safe64Options = options.safe64 ?? {};
+    this.base91Options = options.base91 ?? {};
+
+  } // construct()
+
+  /**
+   * Get a cryptographic *hash*.
+   * 
+   * If you pass `input`, it will be hashed *immediately* and returned.
+   *
+   * Otherwise, if there is a current *progressive hash* in the process of
+   * being built, it will be *finalized* and returned.
+   *
+   * This will return `undefined` if there is no valid data to be hashed.
+   *
+   * @param {(string|WordArray)} [input] Input to hash immediately.
+   *
+   * @return {WordArray|undefined}
+   */
+  hash(input)
+  {
+    if (isNil(input))
+    { // No input, let's see if we have a progrssive hash being built.
+      if (typeof this.currentHash === 'object')
+      { // Let's return the finalized hash.
+        let value = this.currentHash.finalize();
+        delete this.currentHash;
+        return value;
+      }
+    }
+    else if (typeof input === 'string' || this.valid(hash))
+    { // Input data was passed, let's hash it now.
+      return this.hashFunction(input);
+    }
+  }
+
+  // Not really a useful public method.
+  valid(hash)
+  { // WordArray is not a standard object and doesn't work with instanceof.
+    return (isObj(hash) && typeof hash.toString === 'function');
+  }
+
+  /**
+   * Get hash as a Hex string.
+   *
+   * @param {(string|WordArray)} [input] 
+   * See [hash()]{@link module:@lumjs/encode/hash#hash}
+   * @returns {string}
+   * 
+   * This uses the default `Hex` encoder from `crypto-js` to perform
+   * the hashing, so output is directly as if you'd used that library.
+   */
+  hex(input)
+  {
+    const hash = this.hash(input);
+    if (this.valid(hash)) return hash.toString();
+  }
+
+  /**
+   * Get hash as a Base64-encoded string.
+   *
+   * @param {(string|WordArray)} [input] 
+   * See [hash()]{@link module:@lumjs/encode/hash#hash}
+   * @returns {string}
+   * 
+   * This uses the direct `Base64` encoder from `crypto-js` to perform
+   * the hashing, so output is directly as if you'd used that library.
+   */
+  base64(input)
+  {
+    const hash = this.hash(input);
+    const base64 = Crypto.enc.Base64;
+    if (this.valid(hash)) return hash.toString(base64);
+  }
+
+  /**
+   * Get hash as a Safe64-encoded string.
+   * 
+   * Calls [base64()]{@link module:@lumjs/encode/hash#base64},
+   * then passes the output from that to
+   * [urlize()]{@link module:@lumjs/encode/safe64.urlize} to
+   * convert into the *Safe64* format.
+   *
+   * @param {(string|WordArray)} [input] 
+   * See [hash()]{@link module:@lumjs/encode/hash#hash}
+   * @param {object} [opts]
+   * Options for `urlize()`.
+   * @returns {string}
+   * 
+   * By default it's a raw *Safe64* string with **no** header,
+   * and **no** tildes. The `opts` passed can change the format
+   * by enabling *tildes* or adding a *header*.
+   * 
+   */
+  safe64(input, opts={})
+  {
+    let base64 = this.base64(input); 
+    if (base64)
+      return Safe64.urlize(base64, opts);
+  }
+
+  /**
+   * Get hash as a Base91-encoded string.
+   * 
+   * The `crypto-js` library set currently does not natively support
+   * the `base91` encoding format.
+   * 
+   * So this offers a few different ways to encode `crypto-js` hashes
+   * in `base91` format using our own 
+   * [base91]{@link module:@lumjs/encode/base91} module.
+   *
+   * @param {(string|WordArray)} [input] 
+   * See [hash()]{@link module:@lumjs/encode/hash#hash}
+   * @param {object} [opts] Options for how to encode the hash.
+   * @param {boolean} [opts.words=false] Use `hash.words`?
+   * 
+   * If this is `true`, we will pass the `hash.words` array to
+   * the `base91.encode()` method to encode them.
+   * 
+   * If this is true, then `opts.enc` and `opts.nba` are ignored.
+   * 
+   * @param {object} [opts.enc] The `crypto-js` encoder.
+   * 
+   * That can be any of the `crypto.enc.*` plugins.
+   * If not specified, the default `Hex` encoding format will be used.
+   * 
+   * @param {(boolean|object)} [opts.nba=true] Use `numByteArray()` ?
+   * 
+   * 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()`.
+   * 
+   * If this is an `object`, then the same logic as `true` applies, except this
+   * will be used as the *explicit options* for the `numByteArray()` method.
+   * 
+   * If this is `false` the *hash string* itself will be passed directly to
+   * `base91.encode()` without further encoding.
+   * 
+   * The default value of `true` is provided for backwards compatibility with
+   * the previous version of this library which did not have as many options.
+   * 
+   * @returns {string}
+   */
+  base91(input, opts={})
+  {
+    let hash = this.hash(input);
+    if (this.valid(hash)) 
+      return Base91.encode(util.numByteArray(hash.toString()))
+  }
+
+  /**
+   * Add input to a progressive hash.
+   *
+   * If there is not already a progressive hash being built, we will
+   * create one automatically. Use the `hash()` method with no parameter
+   * to retrieve the finalized hash as a `WordArray` object, or one of
+   * the other convenience methods to return it in a specific string
+   * format.
+   *
+   * @param {string|WordArray} input  A value to add to the hash.
+   *
+   * @return Lum.Hashifier  The current object.
+   */
+  add(input)
+  {
+    if (!isObj(this.currentHash))
+    { // We need to start a new hash.
+      this.currentHash = this.algoLib.create();
+    }
+
+    this.currentHash.update(input);
+    
+    return this;
+  }
+
+  static new(opts={})
+  {
+    return new this(opts);
+  }
+
+} // Hashifier class

package/lib/index.js

@@ -0,0 +1,53 @@
+/**
+ * A full set of encoding utilities.
+ * @module @lumjs/encode
+ */
+
+/**
+ * @name module:@lumjs/encode.ord
+ * @function
+ * @see {@link module:@lumjs/encode/util.ord}
+ */
+
+/**
+ * @name module:@lumjs/encode.numByteArray
+ * @function
+ * @see {@link module:@lumjs/encode/util.numByteArray}
+ */
+
+const {ord, numByteArray} = require('./util');
+
+/**
+ * @see {@link module:@lumjs/encode/base64}
+ * @alias module:@lumjs/encode.Base64
+ */
+const Base64 = require('./base64');
+
+/**
+ * @see {@link module:@lumjs/encode/base91}
+ * @alias module:@lumjs/encode.Base91
+ */
+const Base91 = require('./base91');
+
+/**
+ * @see {@link module:@lumjs/encode/safe64}
+ * @alias module:@lumjs/encode.Safe64
+ */
+const Safe64 = require('./safe64');
+
+/**
+ * @see {@link module:@lumjs/encode/hash}
+ * @alias module:@lumjs/encode.Hash
+ */
+const Hash = require('./hash');
+
+/**
+ * @see {@link module:@lumjs/encode/crypto}
+ * @alias module:@lumjs/encode.Crypto
+ */
+const Crypto = require('./crypto');
+
+module.exports = exports = 
+{
+  ord, numByteArray, Base64, Safe64, Base91, Hash, Crypto,
+}

package/lib/safe64/common.js

@@ -0,0 +1,40 @@
+const Enum = require('@lumjs/core/enum');
+
+/**
+ * The Safe64 version.
+ * @alias module:@lumjs/encode/safe64.VERSION 
+ */
+exports.VERSION = 3;
+
+/**
+ * An `Enum` of serialization formats.
+ * 
+ * | Enum Name | Value | Description | 
+ * | --------- | ----- | ----------- | 
+ * | `NONE` | `0` | No serialization. Used when encoding a string or binary data. |
+ * | `JSON` | `1` | Serialize with `JSON`. The simplest, **default** format. |
+ * | `PHP` | `2` | PHP `serialize()` format. Can store object class information. |
+ * | `UBJSON` | `3` | A binary JSON-like serialization format. |
+ * 
+ * @alias module:@lumjs/encode/safe64.FORMAT
+ */
+exports.FORMAT = Enum(['NONE','JSON','PHP','UBJSON']);
+
+/**
+ * An `Enum` of serialization return types.
+ * 
+ * | Enum Name | Value | Description | 
+ * | --------- | ----- | ----------- |
+ * | `RAW` | `0` | Return the raw string/buffer value. | 
+ * | `ARR_OBJ` | `1` | In PHP, use an *associative array* for objects. |
+ * | `STD_OBJ` | `2` | In PHP, use a *StdClass* instance for objects. |
+ * 
+ * In this Javascript implementation, the `ARR_OBJ` and `STD_OBJ` formats
+ * are treated exactly the same. The differenciation only matters in the
+ * **PHP** implementation of Safe64.
+ * 
+ * If the `FORMAT` is `NONE` or `PHP`, the `TYPE` is ignored entirely.
+ * 
+ * @alias module:@lumjs/encode/safe64.TYPE
+ */
+ exports.TYPE = Enum(['RAW', 'ARR_OBJ', 'STD_OBJ']);