@lumjs/encode 1.2.0 → 2.1.0

package/lib/crypto/index.js

@@ -1,171 +0,0 @@
-/**
- * Crypto-JS helpers.
- * 
- * Uses a lot of magic proxy abilities.
- * Look at the `test/020-crypto.js` for examples.
- * 
- * The top-level properties are *case-sensitive*, as
- * is standard in Javascript. In some cases this means
- * there are two names that differ only in case, such as
- * `crypto.hash` (a proxy object returning hashing functions)
- * versus `crypto.HASH` (a proxy object returning object instaces). 
- * 
- * The child properties of any *proxy object* properties
- * are *case-insensitive*. So `crypto.hash.sha256` is the
- * same as `crypto.hash.SHA256`.
- * 
- * @module @lumjs/encode/crypto
- */
-const {def} = require('@lumjs/core/types');
-
-/**
- * A link to the `crypto-js/core` library.
- * 
- * This corresponds to the `CryptoJS` global in the original
- * implementation, and is used by all the other modules
- * in the `crypto-js` collection.
- * 
- * @alias module:@lumjs/encode/crypto.core
- */
-const cc = require('crypto-js/core');
-exports.core = cc;
-
-/**
- * A link to the `crypto-js/core.lib.WordArray` library.
- * 
- * We always load the `lib-typedarray` plugin that allows
- * conversion from `WordArray` objects.
- */
-exports.WordArray = require('crypto-js/lib-typedarrays');
-
-/**
- * Our custom module loader.
- * 
- * Can be used as a `function` itself, but generally one of the
- * child methods is a lot simpler, and works around weird
- * gotchyas in the `crypto-js` library.
- * 
- * All of the *proxy objects* use this as the underlying
- * target object, and each of them corresponds to one of
- * the methods from this.
- * 
- * @see {@link module:@lumjs/encode/crypto/load}
- * @see {@link module:@lumjs/encode/crypto/load.load}
- */
-exports.load = require('./load');
-
-// A list of loader properties to *not* make proxies for.
-const NO_LOAD = ['load'];
-
-// Make proxy objects for the loader properties.
-for (const loader in exports.load)
-{ 
-  if (NO_LOAD.includes(loader)) continue;
-  exports[loader] = new Proxy(exports.load, 
-  {
-    get(load, lib)
-    {
-      return load[loader](lib);
-    }
-  });
-}
-
-/**
- * A proxy object for building a progressive hashing instance.
- * 
- * Any property of this should be the name of a *Hash algorithm*.
- * 
- * Each property is a `function` which takes an optional `object` 
- * parameter called `options`, and will call `load.hash(algorithm, options)`,
- * which will return a progressive hashing instance.
- * 
- * For a non-progressive hashing function, use the lowercase
- * [hash]{@link module:@lumjs/encode/crypto.hash} property instead.
- */
-exports.HASH = new Proxy(exports.load,
-{
-  get(load, lib)
-  {
-    return (options => load.hash(lib, options ?? {}));
-  }
-});
-
-/**
- * A proxy object for building a progressive **HMAC** hashing instance.
- * 
- * Any property of this should be the name of a *Hash algorithm*.
- * 
- * Each property is a `function` which takes a mandatory `string` 
- * parameter called `secret`, and will call `load.hmac(algorithm, secret)`,
- * which will return a progressive HMAC hashing instance.
- * 
- * For a non-progressive HMAC hashing function, use the lowercase
- * [hmac]{@link module:@lumjs/encode/crypto.hmac} property instead.
- */
-exports.HMAC = new Proxy(exports.load,
-{
-  get(load, lib)
-  {
-    return (secret => load.hmac(lib, secret));
-  }
-});
-
-/**
- * A proxy object for loading Hashing functions.
- * 
- * Any property of this should be the name of a *Hash algorithm*,
- * and the property will return the corresponding hashing function.
- * 
- * For a progressive hashing instance, use the uppercase
- * [HASH]{@link module:@lumjs/encode/crypto.HASH} property instead.
- *
- * @name module:@lumjs/encode/crypto.hash
- */
-
-/**
- * A proxy object for loading HMAC hashing functions.
- * 
- * Any property of this should be the name of a *Hash algorithm*,
- * and the property will return the corresponding HMAC hashing function.
- * 
- * For a progressive HMAC hashing instance, use the uppercase
- * [HMAC]{@link module:@lumjs/encode/crypto.HMAC} property instead.
- * 
- * @name module:@lumjs/encode/crypto.hmac
- */
-
-/**
- * A proxy object for loading Cipher libraries.
- *
- * @name module:@lumjs/encode/crypto.cipher
- */
-
-/**
- * A proxy object for loading Algorithm libraries.
- *
- * @name module:@lumjs/encode/crypto.algo
- */
-
-/**
- * A proxy object for loading Encoding libraries.
- *
- * @name module:@lumjs/encode/crypto.enc
- */
-
-/**
- * A proxy object for loading Padding plugins.
- *
- * @name module:@lumjs/encode/crypto.pad
- */
-
-/**
- * A proxy object for loading Mode plugins.
- *
- * @name module:@lumjs/encode/crypto.mode
- */
-
-/**
- * A proxy object for loading Format plugins.
- *
- * @name module:@lumjs/encode/crypto.format
- */

package/lib/crypto/load.js

@@ -1,344 +0,0 @@
-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/safe64/common.js

@@ -1,40 +0,0 @@
-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']);

package/lib/safe64/header.js

@@ -1,142 +0,0 @@
-const {N,S,isObj,needType} = require('@lumjs/core/types');
-const {VERSION,FORMAT,TYPE} = require('./common');
-
-const V = 'SV';
-const F = 'F';
-const T = 'T';
-
-const VL = 2;
-const FL = 1;
-const TL = 1;
-
-/**
- * Safe64 Header functions
- * 
- * @module @lumjs/encode/safe64/header
- */
-
-/**
- * Convert a decimal number to a hexidecimal string.
- * 
- * @param {number} number 
- * @param {number} [len=1] Wanted string length.
- * @returns {string}
- * @alias module:@lumjs/encode/safe64/header.hex
- */
-function hex(number, len=0)
-{
-  needType(N, number);
-  let hex = number.toString(16);
-  return (len > 1 ? hex.padStart(len, '0') : hex);
-}
-
-exports.hex = hex;
-
-/**
- * Convert a hex string to a decimal number.
- * 
- * @param {string} hex 
- * @returns {number}
- * @alias module:@lumjs/encode/safe64/header.dec
- */
-function dec(hex)
-{
-  return parseInt(hex, 16);
-}
-
-exports.dec = dec;
-
-/**
- * Build a Safe64 `v3` header to be prepended to a string.
- * 
- * @param {number} format 
- * @param {number} type 
- * @param {number} [ver=3] 
- * @param {boolean} [full=false] 
- * @returns {string}
- * @alias module:@lumjs/encode/safe64/header.build
- */
-exports.build = function(format, type, ver=VERSION, full=false)
-{
-  needType(N, format, 'format must be a number');
-  needType(N, type, 'type must be a number');
-
-  let h = V + hex(ver, VL);
-
-  if (full || format !== FORMAT.NONE)
-  { // Include a format field.
-    h += F + hex(format, FL);
-    if (full || (type !== TYPE.RAW && format !== FORMAT.PHP))
-    { // Include a type field.
-      h += T + hex(type, TL);
-    }
-  }
-
-  return h;
-}
-
-/**
- * Parse a string, looking for a `v3` header.
- * 
- * @param {string} str - The string to parse.
- * @param {module:@lumjs/encode/safe64~Settings} [settings] Internal use only.
- * @returns {module:@lumjs/encode/safe64~Settings} Settings for the header.
- * 
- * The settings will have a version of `0` if no header was found in the string.
- * 
- * @alias module:@lumjs/encode/safe64/header.parse
- */
-exports.parse = function(str, settings)
-{
-  needType(S, str);
-
-  if (!isObj(settings))
-  {
-    settings = new Settings(FORMAT.NONE, TYPE.RAW);
-  }
-
-  let a = 0;
-  let b = V.length;
-
-  if (str.substring(a, b) === V)
-  { // A version marker was found, continue parsing.
-    a = b;
-    b = a + VL;
-    settings.version = str.substring(a, b);
-
-    a = b;
-    b = a + F.length;
-    if (str.substring(a, b) === F)
-    { // A format tag was found.
-      a = b;
-      b = a + FL;
-      settings.format = dec(str.substring(a, b));
-
-      a = b;
-      b = a + T.length;
-      if (str.substring(a, b) === T)
-      { // A type tag was found.
-        a = b;
-        b = a + TL;
-        settings.type = dec(str.substring(a, b));
-        a = b;
-      }
-    }
-    else 
-    { // No format header means no serialization.
-      settings.format = FORMAT.NONE;
-    }
-  }
-
-  // Okay, now set the string, and if applicable, offset.
-  settings.setValue(str, a);
-
-  return settings;
-}
-
-// Exporting for internal use.
-exports.V  = V;
-exports.VL = VL;
-
-// The Settings object.
-const Settings = require('./settings');