RPG - Rust Password Generator

                            :                  .:
                           .%                  -#
           ..:...          =%*+*-          .*#*#*::           .     .     -++.
 -==+++*****###***+=++==++*%@@@@#+++++++++##%%%%***++++++++++=++====+=++++++%@.
 :-=++*##%%@@@@@%%##**+==+++==+==#%@%%%%#+**++**#######*****+========+==+*%%@#
           .:::::.               -::%###:      .*#-                       .::
                                  ..*###.      :#%-
                                    .#%*       .=+.
                                    :#%#
                                     :::
                                     

A fast, secure, and customizable command-line password generator written in Rust.

Features

• ASCII art banner: Displays a stylized RPG launcher banner on execution
• Customizable character sets: Control which types of characters to include (lowercase, uppercase, numerals, symbols)
• Character exclusion: Exclude specific characters or ranges from generated passwords
• Character inclusion: Restrict passwords to only specific character sets
• Pattern-based generation: Generate passwords from patterns (e.g., LLLNNNSSS for 3 lowercase, 3 numeric, 3 symbols)
• Minimum requirements: Enforce minimum counts of capitals, numerals, or symbols
• Reproducible passwords: Use seeds to generate the same passwords repeatedly
• Multiple output formats: Text (default) or JSON with entropy information
• Clipboard integration: Copy passwords directly to clipboard
• Table output: Display multiple passwords in a formatted table
• Quiet mode: Suppress banner and headers for script-friendly output
• Uniform distribution: Passwords are generated with uniform character distribution
• Fast and efficient: Pre-allocated memory and optimized character set building
• Well-tested: Comprehensive unit tests (17+) and integration tests

Installation

From Crates.io

cargo install rpg-util

From Source

git clone https://github.com/robot-accomplice/rpg.git
cd rpg
cargo build --release

The binary will be available at target/release/rpg.

Usage

Basic Usage

Generate 5 passwords with default settings (16 characters, all character types):

rpg 5

Options

• -l, --length <LENGTH>: Set password length (default: 16, max: 10,000)
• -c, --capitals-off: Disable capital letters
• -n, --numerals-off: Disable numerals
• -s, --symbols-off: Disable symbols
• -e, --exclude-chars <CHARS>: Exclude specific characters or ranges (e.g., a-z, 0-9)
• --include-chars <CHARS>: Include only specific characters or ranges (overrides type flags)
• --min-capitals <N>: Minimum number of capital letters required
• --min-numerals <N>: Minimum number of numerals required
• --min-symbols <N>: Minimum number of symbols required
• -t, --table: Display passwords in table format
• -q, --quiet: Suppress banner and header output
• --seed <SEED>: Seed for reproducible password generation
• --format <FORMAT>: Output format: "text" (default) or "json"
• --copy: Copy first password to clipboard
• --pattern <PATTERN>: Generate passwords from a pattern (L=lowercase, U=uppercase, N=numeric, S=symbol)

Examples

Generate 10 passwords of length 20:

rpg 10 --length 20

Generate 5 passwords without capital letters:

rpg 5 --capitals-off

Generate 5 passwords with only alphabetic characters:

rpg 5 --numerals-off --symbols-off

Generate 5 passwords excluding specific characters or ranges:

rpg 5 --exclude-chars a-z          # Exclude all lowercase letters
rpg 5 --exclude-chars 0-9          # Exclude all digits
rpg 5 --exclude-chars a-z,0-9      # Exclude ranges and individual chars
rpg 5 --exclude-chars a,b,c        # Exclude individual characters
rpg 5 --exclude-chars a-c,x,0-2    # Mix of ranges and individual chars

Display passwords in table format:

rpg 10 --table

Generate passwords with custom length and character restrictions:

rpg 8 --length 24 --capitals-off --exclude-chars 0,O,1,l

Generate passwords with minimum requirements:

rpg 5 --length 20 --min-capitals 2 --min-numerals 3 --min-symbols 1

Generate reproducible passwords with seed:

rpg 5 --seed 12345

Output in JSON format:

rpg 3 --format json

Copy first password to clipboard:

rpg 1 --copy

Use only specific characters:

rpg 5 --include-chars a-z,0-9

Generate passwords from a pattern:

rpg 5 --pattern "LLLNNNSSS"  # 3 lowercase, 3 numeric, 3 symbols
rpg 5 --pattern "UUUlllnnn"  # 3 uppercase, 3 lowercase, 3 numeric

Character Sets

The generator uses the following character ranges:

• Lowercase letters: a-z (always included)
• Uppercase letters: A-Z (can be disabled with --capitals-off)
• Numerals: 0-9 (can be disabled with --numerals-off)
• Symbols: All ASCII printable symbols (can be disabled with --symbols-off)
  • !"#$%&'()*+,-./ (33-47)
  • :;<=>?@ (58-64)
  • `[]^_`` (91-96)
  • {|}~ (123-126)

Error Handling

The generator validates inputs and provides clear error messages:

• Invalid password length or count
• All character types disabled
• All characters excluded

Performance

• Pre-allocated memory for efficient generation
• O(1) character exclusion checking using HashSet
• Single character set build for all passwords
• Optimized random sampling
• Benchmarked with criterion for performance tracking

Library Usage

RPG can also be used as a library in your Rust projects:

[dependencies]
rpg-util = "1.1.0"

use rpg_util::{GenerationParams, PasswordArgs, build_char_set, generate_passwords, parse_pattern};
use rand::Rng;

let args = PasswordArgs {
    capitals_off: false,
    numerals_off: false,
    symbols_off: false,
    exclude_chars: vec![],
    include_chars: None,
    min_capitals: None,
    min_numerals: None,
    min_symbols: None,
    pattern: None,
    length: 16,
    password_count: 1,
};

let char_set = build_char_set(&args)?;
let mut rng = rand::rng();

let gen_params = GenerationParams {
    length: 16,
    count: 1,
    min_capitals: None,
    min_numerals: None,
    min_symbols: None,
    pattern: None,
};
let passwords = generate_passwords(&char_set, &gen_params, &mut rng);

// Or use pattern-based generation
let pattern = parse_pattern("LLLNNNSSS")?;
let gen_params = GenerationParams {
    length: 9,
    count: 1,
    min_capitals: None,
    min_numerals: None,
    min_symbols: None,
    pattern: Some(pattern),
};
let passwords = generate_passwords(&char_set, &gen_params, &mut rng);

Testing

Run the test suite:

# Run all tests
cargo test

# Run only unit tests
cargo test --lib

# Run only integration tests
cargo test --test integration_test

# Run with output
cargo test -- --nocapture

Benchmarks

Run performance benchmarks:

cargo bench

This will generate HTML reports in target/criterion/.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

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

Development Setup

1. Clone the repository
2. Run tests: cargo test
3. Run clippy: cargo clippy
4. Format code: cargo fmt

Pre-commit Hooks

Optional pre-commit hooks are available to ensure code quality. See PRE_COMMIT_HOOKS.md for detailed documentation.

Quick setup:

pip install pre-commit
pre-commit install

This will run formatting, linting, and tests before each commit.