🔐 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)
- 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

API Usage

$3

``typescript
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"

`

$3

`typescript
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],
};
`

$3

`typescript
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"
`

$3

`typescript
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
`

CLI Usage

The package includes a convenient CLI tool:

`bash


Install globally (optional)

npm install -g password-obscura

Or use with npx

npx password-obscura --help
`

$3

`bash


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

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

$3

Obscures the input string using the specified method.

Parameters:

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

$3

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

$3

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

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

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

// Polyalphabetic cipher options
polyConfig?: PolyalphabeticConfig;

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

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

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

$3

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

Method Details

$3

#### 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

#### 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

$3

#### 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

$3

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)

$3

- 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)

$3

This package uses modern ES modules:

`javascript
// 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.

$3

`bash


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
`

$3

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

$3

To create a new release:

`bash


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:

`bash
./scripts/release.sh patch
`

Troubleshooting & FAQ

$3

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.

$3

- 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 ❤️ by angga saputra for developers who love creative coding and educational cryptography.