high-entropy v0.0.5

High-entropy

Sourcing multiple packages for generating high-entropy random bytes.

Multiple Default Local Sources

All entropy sources are combined (concatenated) and then hashed with SHA-512 crypto.randomBytes (native package) uuid/v4

import { HighEntropy } from 'high-entropy';

// get random bytes upto 64 byte (SHA-512 length)
const randomBytes = HighEntropy.localBytes(64);

/**
 * Combine locally generated entropies from many npm packages
 * @param length byte length to generate (default 32 bytes)
 * @param perPackageContributionLength how many bytes to generate from each package
 */
function localBytes(length: number = 32, perPackageContributionLength: number = 256): Buffer

External Entropy Sources

You can also combine local sources with external sources.

(External source url must return base64-encoded bytes array)

import { HighEntropy } from 'high-entropy';

// get random bytes upto 64 byte (SHA-512 length)
const bytes = await HighEntropy.mixedSources(64, [
  'https://my.random.source.domain/rand',
  'https://my.random.source.domain2/rand',
  ...
]);

/**
 * Combine locally generated entropy and remote generated entropy.
 * Resolves to `null` on error.
 * 
 * (This is single-hop: local + extSource1 + extSource2 + ... + extSourceN)
 * 
 * @param length byte length to generate (default 32 bytes)
 * @param sources url list of external sources (http or https), recommended more than 5.
 * @param threshold at least `threshold` % of external sources should response, otherwise resolve null
 * @param perSourceContributionLength how many bytes should each source contribute (default 256 bytes) 
 * @param timeout timeout in miliseconds for http requests to return
 */
 function mixedSources(length: number = 32,
                       sources: string[],
                       threshold: number = 1/2, // half must respond (avoid setting it to 1; source may not always respond)
                       perSourceContributionLength: number = 256,
                       timeout: number = 3000)
                          : Promise<Buffer>