human-readable-hash

Convert any input into memorable word combinations like "blue-fox-cloud" instead of cryptic hash strings.

Table of Contents

1. Installation
2. Quick Start
3. Step-by-Step Guide
4. Security Levels
5. Advanced Usage
6. API Reference
7. CLI Usage
8. Examples

Installation

# Local installation
npm install human-readable-hash

# Global installation (for CLI usage)
npm install -g human-readable-hash

Quick Start

const { hashToWords } = require('human-readable-hash');

// Basic usage
const result = hashToWords('hello world');
console.log(result.words);  // e.g., "blue-fox-cloud"

Step-by-Step Guide

1. Basic Hashing

const { hashToWords } = require('human-readable-hash');

// Generate a 3-word hash (default)
const result = hashToWords('your-input-here');
console.log(result.words);         // e.g., "swift-tiger-moon"
console.log(result.wordArray);     // e.g., ["swift", "tiger", "moon"]
console.log(result.algorithm);     // "sha256" (default algorithm)

2. Choosing Security Level

// Fast but less secure (SHA-1)
const fastHash = hashToWords('data', { securityLevel: 'fast' });

// Balanced security (SHA-256)
const defaultHash = hashToWords('data', { securityLevel: 'default' });

// Maximum security (SHA-512)
const secureHash = hashToWords('data', { securityLevel: 'secure' });

// Legacy compatibility (MD5)
const legacyHash = hashToWords('data', { securityLevel: 'legacy' });

3. Customizing Output

// Change word count (2-5 words)
const fourWords = hashToWords('data', { wordCount: 4 });
// e.g., "bright-hawk-river-moon"

// Change delimiter
const underscored = hashToWords('data', { delimiter: '_' });
// e.g., "bright_hawk_river"

// Get entropy information
const withEntropy = hashToWords('data', { includeEntropy: true });
console.log(withEntropy.entropy);  // e.g., 16.4 (bits of entropy)

4. Error Handling

const { hashToWords, ValidationError } = require('human-readable-hash');

try {
  const result = hashToWords('data', {
    wordCount: 6  // Invalid: must be 2-5
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  }
}

5. Working with Files

const fs = require('fs');
const { hashToWords } = require('human-readable-hash');

// Hash file content
const fileContent = fs.readFileSync('document.pdf');
const result = hashToWords(fileContent, { 
  securityLevel: 'secure',
  wordCount: 4 
});

// Create unique filename
const uniqueName = `document-${result.words}.pdf`;

Security Levels

Choose the appropriate security level for your needs:

| Level | Algorithm | Speed | Security | Use Case | |----------|-----------|--------|----------|----------| | fast | SHA-1 | Fast | Basic | Quick lookups, non-critical data | | default | SHA-256 | Medium | Good | General purpose, most uses | | secure | SHA-512 | Slower | Best | Sensitive data, security critical | | legacy | MD5 | Fast | Basic | Legacy system compatibility |

Advanced Usage

1. Custom Hash Algorithms

// List available algorithms
const { getAvailableAlgorithms } = require('human-readable-hash');
const algorithms = getAvailableAlgorithms();

console.log(algorithms.sha);     // All SHA variants
console.log(algorithms.md);      // All MD variants
console.log(algorithms.other);   // Other algorithms

// Use custom algorithm
const result = hashToWords('data', { algorithm: 'sha3-256' });

2. Minimum Entropy Requirements

const result = hashToWords('data', {
  wordCount: 4,
  minEntropy: 20,
  includeEntropy: true
});

if (result.entropy < 20) {
  console.warn('Low entropy warning');
}

3. Access Wordlists

const { getWordlists } = require('human-readable-hash');
const lists = getWordlists();

console.log('Available adjectives:', lists.adjectives);
console.log('Available nouns:', lists.nouns);

4. Hash Analysis and Comparison

const { 
  analyzeWords, 
  compareInputs, 
  findPossibleWords 
} = require('human-readable-hash');

// Analyze a word combination
const analysis = analyzeWords('bold-rock-sand');
console.log(analysis);
// {
//   words: 'bold-rock-sand',
//   wordArray: ['bold', 'rock', 'sand'],
//   algorithm: 'sha256',
//   analysis: {
//     firstWord: { word: 'bold', type: 'adjective', index: 23, ... },
//     restWords: [
//       { word: 'rock', type: 'noun', index: 12, ... },
//       { word: 'sand', type: 'noun', index: 39, ... }
//     ]
//   }
// }

// Compare two inputs
const comparison = compareInputs('hello world', 'hello wolrd');
console.log(comparison);
// {
//   input1: { value: 'hello world', words: 'bold-rock-sand', rawHash: '...' },
//   input2: { value: 'hello wolrd', words: 'black-spring-week', rawHash: '...' },
//   match: false,
//   algorithm: 'sha256'
// }

// Find words for specific byte pattern
const words = findPossibleWords([23, 12, 39]);
console.log(words);
// {
//   words: 'bold-rock-sand',
//   pattern: [23, 12, 39],
//   wordDetails: [
//     { word: 'bold', type: 'adjective', byteValue: 23, index: 23 },
//     { word: 'rock', type: 'noun', byteValue: 12, index: 12 },
//     { word: 'sand', type: 'noun', byteValue: 39, index: 39 }
//   ]
// }

// Get word list statistics
const { getWordStats } = require('human-readable-hash');
const stats = getWordStats();
console.log(stats);
// {
//   adjectives: { count: 256, examples: ['swift', 'bold', ...] },
//   nouns: { count: 256, examples: ['star', 'rock', ...] },
//   combinations: {
//     twoWords: 16.0,    // bits of entropy
//     threeWords: 24.0,  // bits of entropy
//     fourWords: 32.0,   // bits of entropy
//     fiveWords: 40.0    // bits of entropy
//   }
// }

5. Finding Collisions

const { findCollision } = require('human-readable-hash');

// Check if different input generates same words
const collision = findCollision('bold-rock-sand', 'hello wolrd');
console.log(collision);
// {
//   input: 'hello wolrd',
//   generated: 'black-spring-week',
//   isCollision: false,
//   algorithm: 'sha256',
//   rawHash: '...'
// }

API Reference

hashToWords(input, options?)

Generate a human-readable hash.

Input

• input: String | Buffer - Content to hash

Options

• algorithm: String - Custom hash algorithm
• securityLevel: 'fast' | 'default' | 'secure' | 'legacy'
• delimiter: String - Word separator (default: '-')
• wordCount: Number - Words to generate (2-5, default: 3)
• minEntropy: Number - Minimum required entropy
• includeEntropy: Boolean - Include entropy in result

Returns

Object with:

• words: String - Delimited word combination
• wordArray: String[] - Array of words
• algorithm: String - Hash algorithm used
• entropy: Number - (if includeEntropy: true)

CLI Usage

The CLI tool human-hash provides several features for generating and analyzing human-readable hashes.

Basic Usage

# Generate hash from text
human-hash "hello world"
# Output: bold-rock-sand

# Generate hash from file
human-hash --file document.pdf

# Show raw hash value
human-hash --raw-hash "hello world"
# Output: bold-rock-sand
# Raw Hash: b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

Analysis and Verification

# Parse a word combination
human-hash --parse "bold-rock-sand"
# Shows how the words were generated and byte positions

# Verify if input matches word combination
human-hash --verify "bold-rock-sand" "hello world"

# Verify with raw hash display
human-hash --verify "bold-rock-sand" "hello world" --raw-hash

Options

# Change number of words (2-5)
human-hash -w 4 "hello world"

# Change security level
human-hash -s secure "hello world"    # SHA-512
human-hash -s fast "hello world"      # SHA-1
human-hash -s default "hello world"   # SHA-256 (default)
human-hash -s legacy "hello world"    # MD5

# Change word separator
human-hash -d "_" "hello world"

# Show entropy information
human-hash --entropy "hello world"

# JSON output
human-hash --json "hello world"

# List available hash algorithms
human-hash --list-algorithms

# Verbose output
human-hash -v "hello world"

Help and Information

# Show help
human-hash --help

# Show version
human-hash --version

Common Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --words | -w | Number of words (2-5) | 3 | | --security | -s | Security level (fast, default, secure, legacy) | default | | --delimiter | -d | Word separator | - | | --file | -f | Read from file | | | --raw-hash | | Show raw hash value | false | | --parse | | Analyze word combination | | | --verify | | Verify input against word combination | | | --entropy | | Show entropy information | false | | --json | | Output as JSON | false | | --verbose | -v | Show detailed information | false |

## Examples

### 1. File Naming
```javascript
const { hashToWords } = require('human-readable-hash');

function generateUniqueName(filename) {
  const hash = hashToWords(filename, { wordCount: 2 });
  return `${filename}-${hash.words}`;
}

console.log(generateUniqueName('document.pdf'));
// e.g., "document-blue-fox.pdf"

2. User-Friendly IDs

function generateFriendlyId(userId) {
  return hashToWords(userId, {
    wordCount: 4,
    delimiter: '_',
    securityLevel: 'secure'
  }).words;
}

console.log(generateFriendlyId('user123'));
// e.g., "swift_tiger_moon_star"

3. Content Verification

function verifyContent(content, storedHash) {
  const newHash = hashToWords(content, {
    securityLevel: 'secure',
    wordCount: 4
  }).words;
  
  return newHash === storedHash;
}

4. Secure Token Generation

function generateSecureToken() {
  const random = crypto.randomBytes(32);
  return hashToWords(random, {
    securityLevel: 'secure',
    wordCount: 5,
    minEntropy: 30
  }).words;
}

License

MIT

Author

C Sarath Babu

• Founder of Qubase
• Creator of human-readable-hash
• Making cryptographic hashes more human-friendly

Built with ❤️ at Qubase