🔐 password-obscura

A lightweight NPM package to "visually" obscure passwords or strings using customizable shift-based and symbol-mapping logic. Inspired by Caesar Cipher — reimagined for modern developers with advanced multi-table encryption capabilities.

🔐 What It Does

Instead of strong encryption (which is better handled by libs like bcrypt), this tool is meant for:

• 🔒 Obscuring passwords for display (e.g., showing a fake-but-consistent password to users)
• 🧪 Generating pseudo-random but reversible representations
• 📜 Teaching cryptography basics (Caesar, Atbash, ROT13, Vigenère, etc.)
• 🎨 Creative text transformations with emojis and symbols
• 🔧 Advanced cipher combinations for educational purposes

✅ Use Cases

• 🎮 Fun CLI tools and interactive applications
• 🔐 Password managers showing masked variants
• 🤖 Discord / game bots that hide inputs creatively
• 🎓 Educational demos on encryption basics and cryptography
• 📝 Obfuscating config keys or token snippets in logs
• 🧪 Testing and demonstration of cipher algorithms
• 🎭 Creative text art and visual transformations

🧠 Features

• 7 Cipher Methods: Complete encryption toolkit for various use cases

  • caesar - Classic Caesar cipher with customizable shift
  • rot13 - ROT13 cipher (shift by 13, self-inverse)
  • symbolMap - Replace characters with custom symbols/emojis
  • mirror - Atbash cipher (a ↔ z, b ↔ y, etc.)
  • multiTable - Advanced! Multi-table Caesar with dynamic shift patterns
  • polyalphabetic - Advanced! Keyword-based Vigenère-style cipher
  • advanced - Advanced! Multi-layer cipher with various transformations

• Dynamic Shift Patterns: Five sophisticated pattern algorithms

  • Even-Odd: Alternates between two shift values based on position
  • Fibonacci: Uses Fibonacci sequence for progressive shifts
  • Prime Numbers: Applies prime number sequence for shifts
  • Progressive: Incrementally increases shift value per character
  • Custom Sequences: User-defined shift patterns

• Advanced Capabilities:

  • Multi-table Support: Use different alphabets for enhanced complexity
  • Keyword Ciphers: Polyalphabetic encryption with repeating keywords
  • Layer Combinations: Stack multiple cipher techniques together
  • Perfect Reversibility: All ciphers maintain encode/decode symmetry

• Developer Experience:

  • 🎯 TypeScript First: Full type safety with comprehensive interfaces
  • 🪶 Lightweight: 8.3 kB package size, zero runtime dependencies
  • 🌐 Universal: Works in Node.js and browser environments
  • ⚡ Fast: Optimized algorithms with excellent performance
  • 🛠️ CLI Tool: Complete command-line interface included

📦 Installation

# npm
npm install password-obscura

# yarn
yarn add password-obscura

# pnpm
pnpm add password-obscura

# bun
bun add password-obscura

🧪 API Usage

Basic Examples

import { obscure, reveal } from "password-obscura";

// Caesar-style shift
const hidden = obscure("secret123", { method: "caesar", shift: 3 });
console.log(hidden); // → "vhfuhw123"

const original = reveal(hidden, { method: "caesar", shift: 3 });
console.log(original); // → "secret123"

// ROT13
const rot13Hidden = obscure("hello-world", { method: "rot13" });
console.log(rot13Hidden); // → "uryyb-jbeyq"

// Mirror/Atbash cipher
const mirrored = obscure("hello", { method: "mirror" });
console.log(mirrored); // → "svool"

// Symbol mapping with emojis
const emojiHidden = obscure("abc123", { method: "symbolMap" });
console.log(emojiHidden); // → "🔥⭐🌟🟠🟡🟢"

Advanced Multi-Table Ciphers

import { obscure, reveal, DynamicTableConfig } from "password-obscura";

// Multi-table Caesar with even-odd pattern
const tableConfig: DynamicTableConfig = {
  tables: ["abcdefghijklmnopqrstuvwxyz", "zyxwvutsrqponmlkjihgfedcba"],
  shiftPattern: "even-odd",
  baseShift: 3,
};

const multiResult = obscure("Hello World", {
  method: "multiTable",
  tableConfig,
});
console.log(multiResult); // → "Kaohr Zkuhg"

// Fibonacci shift pattern
const fibConfig: DynamicTableConfig = {
  tables: ["abcdefghijklmnopqrstuvwxyz"],
  shiftPattern: "fibonacci",
  baseShift: 1,
};

const fibResult = obscure("ABCDEFGHIJK", {
  method: "multiTable",
  tableConfig: fibConfig,
});
console.log(fibResult); // → "BCEGJNTCQMV"

// Custom shift sequence
const customConfig: DynamicTableConfig = {
  tables: ["abcdefghijklmnopqrstuvwxyz"],
  shiftPattern: "custom",
  baseShift: 1,
  customShifts: [1, 3, 5, 7, 2, 4, 6, 8],
};

Polyalphabetic Cipher

import { obscure, reveal, PolyalphabeticConfig } from "password-obscura";

const polyConfig: PolyalphabeticConfig = {
  keyword: "SECRET",
};

const polyResult = obscure("Hello World", {
  method: "polyalphabetic",
  polyConfig,
});
console.log(polyResult); // → "Oinus Mstuh"

const decrypted = reveal(polyResult, { method: "polyalphabetic", polyConfig });
console.log(decrypted); // → "Hello World"

Advanced Multi-Layer Cipher

const layers = [
  { type: "shift", config: { shift: 3 } },
  {
    type: "table",
    config: {
      tables: ["abcdefghijklmnopqrstuvwxyz", "zyxwvutsrqponmlkjihgfedcba"],
      shiftPattern: "fibonacci",
      baseShift: 2,
    },
  },
  { type: "reverse" },
];

const advancedResult = obscure("Secret Message", {
  method: "advanced",
  layers,
});
console.log(advancedResult); // → Complex multi-layer transformation

Advanced Symbol Mapping

import { obscure, reveal, SymbolMapConfig } from "password-obscura";

// Custom symbol mapping
const customMap: SymbolMapConfig = {
  a: "🌟",
  b: "🚀",
  c: "💎",
  "1": "⭐",
  "2": "🔥",
  "3": "💫",
};

const customHidden = obscure("abc123", {
  method: "symbolMap",
  symbolMap: customMap,
});
console.log(customHidden); // → "🌟🚀💎⭐🔥💫"

const restored = reveal(customHidden, {
  method: "symbolMap",
  symbolMap: customMap,
});
console.log(restored); // → "abc123"

🛠️ CLI Usage

The package includes a convenient CLI tool:

# Install globally (optional)
npm install -g password-obscura

# Or use with npx
npx password-obscura --help

CLI Examples

# Basic Caesar cipher
$ npx password-obscura encode "hello-world" --method caesar --shift 3
khoor-zruog

$ npx password-obscura decode "khoor-zruog" --method caesar --shift 3
hello-world

# ROT13 (self-inverse)
$ npx password-obscura encode "hello-world" --method rot13
uryyb-jbeyq

# Mirror/Atbash cipher
$ npx password-obscura encode "secret" --method mirror
hvxivg

# Symbol mapping with emojis
$ npx password-obscura encode "abc123" --method symbolMap
🔥⭐🌟🟠🟡🟢

# Advanced multi-table with Fibonacci pattern
$ npx password-obscura encode "Hello World" --method multiTable --pattern fibonacci
Iukpt Fkzll

# Polyalphabetic cipher with keyword
$ npx password-obscura encode "Secret Message" --method polyalphabetic --keyword "CIPHER"
Wmryic Qmtslmi

# Custom shift sequences
$ npx password-obscura encode "test" --method multiTable --pattern custom --custom-shifts "1,3,5,7"
ubxm

# Advanced multi-layer cipher (uses default layers)
$ npx password-obscura encode "Complex Text" --method advanced
txfI fmofhxmC

📖 API Reference

obscure(input: string, options: ObscureOptions): string

Obscures the input string using the specified method.

Parameters:

• input: The string to obscure
• options: Configuration object (see ObscureOptions below)

reveal(input: string, options: ObscureOptions): string

Reveals the obscured string using the same method and options used to obscure it.

Parameters:

• input: The obscured string to reveal
• options: Same configuration object used for obscuring

Types

interface ObscureOptions {
  method:
    | "caesar"
    | "rot13"
    | "symbolMap"
    | "mirror"
    | "multiTable"
    | "polyalphabetic"
    | "advanced";

  // Caesar cipher options
  shift?: number; // default: 3

  // Symbol mapping options
  symbolMap?: SymbolMapConfig;

  // Multi-table cipher options
  tableConfig?: DynamicTableConfig;

  // Polyalphabetic cipher options
  polyConfig?: PolyalphabeticConfig;

  // Advanced cipher options
  layers?: Array<{
    type: "table" | "shift" | "reverse" | "transpose";
    config?: any;
  }>;
}

interface SymbolMapConfig {
  [key: string]: string;
}

interface DynamicTableConfig {
  tables: string[];
  shiftPattern: "even-odd" | "fibonacci" | "prime" | "progressive" | "custom";
  baseShift?: number;
  customShifts?: number[];
}

interface PolyalphabeticConfig {
  keyword: string;
  tables?: string[];
}

Constants

// Pre-defined symbol mapping with emojis for all alphanumeric characters
DEFAULT_SYMBOL_MAP: SymbolMapConfig;

// Four pre-defined alphabet tables for multi-table ciphers
DEFAULT_TABLES: string[];

🔍 Method Details

Basic Cipher Methods

Caesar Cipher

Classic Caesar cipher that shifts letters by a specified amount.

• ✅ Preserves case and non-alphabetic characters
• ✅ Default shift: 3, supports any shift value
• ✅ Mathematically sound with modular arithmetic

ROT13

Special case of Caesar cipher with a shift of 13.

• ✅ Self-inverse (encoding and decoding are the same operation)
• ✅ Commonly used in online forums
• ✅ Fixed 13-character shift for consistency

Symbol Map

Replaces characters with custom symbols or emojis.

• ✅ Includes default emoji mapping for all alphanumeric characters
• ✅ Fully customizable with your own symbol mappings
• ✅ Perfect for creative obfuscation and visual appeal
• ✅ Handles Unicode characters properly

Mirror (Atbash)

Maps each letter to its mirror position in the alphabet (A↔Z, B↔Y, etc.).

• ✅ Self-inverse like ROT13
• ✅ Ancient cipher method with historical significance
• ✅ Case-preserving transformation

Advanced Cipher Methods

Multi-Table Caesar

Uses multiple substitution alphabets with dynamic shift patterns.

• 🚀 5 Shift Patterns: even-odd, fibonacci, prime, progressive, custom
• 🚀 Multiple Tables: Switch between different alphabets per character
• 🚀 Perfect Reversibility: All patterns maintain encode/decode symmetry
• 🚀 Educational Value: Demonstrates polyalphabetic principles

Shift Patterns:

• Even-Odd: position % 2 === 0 ? baseShift : baseShift + 1
• Fibonacci: Uses Fibonacci sequence: 1, 1, 2, 3, 5, 8, 13...
• Prime: Uses prime numbers: 2, 3, 5, 7, 11, 13, 17...
• Progressive: baseShift + (position % 10)
• Custom: User-defined shift sequences

Polyalphabetic Cipher

Keyword-based Vigenère-style encryption.

• 🔑 Keyword Encryption: Uses repeating keyword for shift calculation
• 🔄 Dynamic Shifts: Each keyword character determines shift amount
• 📚 Multiple Tables: Can use different alphabets for enhanced complexity
• 🎓 Classic Algorithm: Implements traditional Vigenère cipher principles

Advanced Multi-Layer Cipher

Combines multiple cipher techniques in sequence.

• 🔗 Layer Composition: Stack multiple transformations
• 🔀 Transformation Types: shift, table, reverse, transpose
• ⚙️ Configurable: Custom layer configurations
• 🔄 Reversible: Applies transformations in reverse order for decoding

Available Layer Types:

• shift: Basic Caesar shift transformation
• table: Multi-table substitution with patterns
• reverse: String reversal transformation
• transpose: Block-based character transposition

⚡ Performance & Compatibility

Performance Benchmarks

Based on 100 iterations with long text strings:

• Caesar: ~34ms (fastest basic cipher)
• ROT13: ~46ms
• Symbol Map: ~37ms
• Mirror: ~19ms (fastest overall)
• Multi-Table: ~42ms (excellent for complexity)
• Polyalphabetic: ~51ms
• Advanced: ~75ms (acceptable for multi-layer)

Compatibility

• ✅ Node.js: v16+ (ESM modules)
• ✅ Browsers: Modern browsers with ES2020 support
• ✅ TypeScript: Full type definitions included
• ✅ Package Size: 8.3 kB (40.4 kB unpacked)
• ✅ Dependencies: Zero runtime dependencies (CLI uses commander)

ESM Module Support

This package uses modern ES modules:

// ✅ Correct import syntax
import { obscure, reveal } from "password-obscura";

// ❌ CommonJS require() not supported
const { obscure } = require("password-obscura"); // Won't work

⚠️ Security Notice

This library is designed for visual obfuscation and educational purposes, not cryptographic security. The transformations are easily reversible and should not be used for protecting sensitive data in production environments.

For actual password hashing and security, use established libraries like:

• bcrypt
• argon2
• scrypt

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone the repository
git clone https://github.com/angga-22/password-obscura.git
cd password-obscura

# Install dependencies
npm install

# Build the project
npm run build

# Run comprehensive test suite
node demo.js

# Test CLI functionality
npx password-obscura encode "test" --method caesar --shift 5

Project Structure

password-obscura/
├── src/
│   ├── index.ts              # Main API entry point
│   └── lib/                  # Cipher implementations
│       ├── caesar.ts         # Basic Caesar cipher
│       ├── rot13.ts          # ROT13 implementation
│       ├── symbolMap.ts      # Symbol/emoji mapping
│       ├── atbash.ts         # Mirror/Atbash cipher
│       └── dynamicCipher.ts  # Advanced multi-table ciphers
├── bin/cli.ts                # Command-line interface
├── demo.js                   # Comprehensive test suite
├── dist/                     # Built output
└── docs/                     # Documentation files

Versioning

This project follows Semantic Versioning. See VERSIONING.md for details about our versioning strategy.

Releases

To create a new release:

# For bug fixes
npm run release:patch

# For new features
npm run release:minor

# For breaking changes
npm run release:major

Or use the release script:

./scripts/release.sh patch

� Troubleshooting & FAQ

Common Issues

Q: "Cannot use import statement outside a module" A: This package uses ESM modules. Ensure your project supports ES modules or use Node.js v16+.

Q: Some characters don't encode/decode properly A: The library is designed for basic Latin characters (a-z, A-Z, 0-9). Special Unicode characters may not be supported in all cipher methods.

Q: Advanced cipher results seem inconsistent A: This is expected! Advanced ciphers use complex algorithms. Ensure you're using the exact same configuration for both encoding and decoding.

Q: CLI command not found A: Either install globally with npm install -g password-obscura or use npx password-obscura prefix.

Getting Help

• 📖 Check the API documentation above
• 🔍 Review the comprehensive test suite for examples
• 🐛 Report issues on GitHub Issues
• 💡 Request features or ask questions in Discussions

�📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by classical cipher techniques and modern developer needs for creative text transformation. Special thanks to:

• 📚 Historical Cryptographers: Caesar, Vigenère, Atbash cipher inventors
• 🎓 Educational Resources: Cryptography textbooks and online courses
• 💻 Open Source Community: TypeScript, Node.js, and npm ecosystem
• 🧪 Testing: Comprehensive validation of all cipher implementations

Built with ❤️ for developers who love creative coding and educational cryptography.