Early release (v0.1.4)

Zora generates random keys using Python's cryptographically secure secrets module by default. It supports customizable character sets, charset presets, prefixes, suffixes, grouping, multiple outputs, file output, entropy estimation, and an optional deterministic PRNG mode.

---

Features

• 🔐 Cryptographically secure generation by default
• ⚠️ Optional insecure PRNG mode with --unsafe
• 🎲 Deterministic generation with --seed in unsafe mode
• 🔤 Custom character sets
• 🧩 Composable charset presets such as @letters@digits
• 🔢 Built-in hexadecimal, octal, binary, digit, and symbol presets
• ➕ Add custom characters to presets
• 📏 Configurable key length
• 📦 Generate multiple keys at once
• 🔗 Add prefixes and suffixes
• 📐 Group keys with custom separators
• 💾 Write generated keys to a file
• 📊 Calculate theoretical entropy
• 💪 Estimate key strength from entropy
• ⏱️ Display generation time
• 🤫 Quiet mode for scripting
• 📋 Charset preset listing

Installation

Requirements

pip install zora-cli

Run Zora:

zora 32

Usage

Basic usage:

zora LENGTH [OPTIONS]

For example:

zora 32

Example output:

GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr

Timer: 13ms elapsed
Charset: 52
Entropy: 182.41 bits
Strength: Very strong
Generator: CSPRNG

---

Arguments

length

The length of the random portion of the generated key.

zora 32

The value must be greater than 0.

---

--charset

Select the character set used to generate keys.

zora 32 --charset @digits

By default:

@letters

is used.

Zora supports both predefined charset presets and literal characters.

Presets

Use --charset-list to display all available presets:

zora --charset-list

Currently available presets:

Preset	Characters
@digits	0-9
@letters	a-zA-Z
@lower	a-z
@upper	A-Z
@hex	0-9ABCDEFabcdef
@oct	01234567
@bin	01
@special	all punctuation/symbol characters

---

Combining presets

Presets can be combined:

zora 32 --charset @letters@digits

This creates an alphanumeric character set.

Multiple presets can be combined:

zora 32 --charset @upper@lower@digits

Duplicate characters are automatically removed.

For example:

@letters@upper

does not contain uppercase characters twice.

---

Custom characters

Literal characters can be included alongside presets.

For example:

zora 32 --charset @hexXYZ

This means:

@hex + X + Y + Z

Another example:

zora 32 --charset XYZ@hex

means:

X + Y + Z + @hex

This allows arbitrary character sets without needing to add a new preset.

---

--charset-list

Display the available charset presets:

zora --charset-list

Example:

Available charsets:

  @digits
  @letters
  @lower
  @upper
  @hex
  @oct
  @bin
  @special

Use as:

  zora --charset @digits
  zora --charset @letters@digits
  zora --charset @hexXYZ

---

Multiple keys

Use -n or --count:

zora 32 --count 10

or:

zora 32 -n 10

Zora generates each key independently.

When using the secure default generator, each key is generated using the cryptographically secure random generator.

---

Prefixes and suffixes

Add a prefix:

zora 32 --prefix "AUTH_"

Example:

AUTH_GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr

Add a suffix:

zora 32 --suffix "_KEY"

Both can be used together:

zora 32 --prefix "AUTH_" --suffix "_KEY"

Prefixes and suffixes are not random and therefore do not contribute to the calculated entropy.

---

Grouping

Use --group to insert a separator every N characters.

For example:

zora 32 --group 4

Output:

GxKq-TnJp-YwRz-LhBc-VfQm-NsXe-UaPk-TdWr

The default separator is:

-

Use --sep to change it:

zora 32 --group 4 --sep ":"

Output:

GxKq:TnJp:YwRz:LhBc:VfQm:NsXe:UaPk:TdWr

Grouping only changes the presentation of the key. It does not affect entropy.

---

File output

Use -o or --output to write generated keys to a file:

zora 32 -n 10 --output keys.txt

The generated keys are written one per line.

Example:

GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr
aQmXzPjLtVrNsYkBcWdHgFqAeUxRoZiLp
...

---

Secure generation

Zora uses Python's secrets module by default.

This is the recommended mode when generating authentication tokens, API keys, secrets, or other security-sensitive random values.

zora 32

The output will report:

Generator: CSPRNG

---

Unsafe / PRNG mode

Use:

zora 32 --unsafe

to use Python's normal pseudo-random number generator instead of the cryptographically secure generator.

Zora will display a warning:

Program will output cryptographically insecure keys.

and:

Generator: PRNG

This mode exists primarily for testing, reproducibility, benchmarking, and experimentation.

Do not use --unsafe for real authentication keys or other security-sensitive secrets.

---

Seeds

Seeds are only allowed with --unsafe.

This is intentional.

The following will fail:

zora 32 --seed example

because Zora's secure generator should not be made deterministic through the normal CLI.

Instead:

zora 32 --unsafe --seed example

A seed can be useful for testing reproducibility.

For example:

zora 32 --unsafe --seed test

will produce the same deterministic sequence when run with the same configuration.

When generating multiple keys, the PRNG is seeded once before generation rather than being reseeded for every key.

---

Quiet mode

Use -q or --quiet to suppress non-essential output:

zora 32 --quiet

This is useful when using Zora inside scripts or shell pipelines.

For example:

zora 32 --quiet > key.txt

---

Entropy

Zora calculates the theoretical entropy of the random portion of the key.

The formula is:

$entropy = length \times \log{_2}{(charset size)}$

For example, using 52 possible characters:

$32 \times log{_2}\space 52$

produces approximately:

182.17 bits

The entropy calculation only considers random characters.

Known prefixes, suffixes, and grouping separators do not increase the entropy.

For example:

zora 32 --prefix "AUTH_"

has the same theoretical entropy as:

zora 32

assuming the same charset and length.

---

Strength

Zora provides a simple entropy-based strength classification.

Entropy	Classification
< 40 bits	Very weak
40–59 bits	Weak
60–79 bits	Moderate
80–99 bits	Strong
100+ bits	Very strong

This is a simple classification rather than a formal security guarantee.

A high theoretical entropy value does not make an insecure PRNG cryptographically secure.

For this reason, Zora explicitly identifies the generator as either:

CSPRNG

or:

PRNG

---

Example commands

Basic key

zora 32

Digits only

zora 32 --charset @digits

Lowercase only

zora 32 --charset @lower

Uppercase only

zora 32 --charset @upper

Alphanumeric

zora 32 --charset @letters@digits

Hexadecimal

zora 32 --charset @hex

Hexadecimal plus custom characters

zora 32 --charset @hexXYZ

Uppercase, lowercase and digits

zora 32 --charset @upper@lower@digits

Symbols

zora 32 --charset @special

Group the output

zora 32 --group 4

Custom separator

zora 32 --group 4 --sep ":"

Generate multiple keys

zora 32 -n 10

Save to a file

zora 32 -n 100 -o keys.txt

Prefix

zora 32 --prefix "AUTH_"

Secure generation

zora 32

Reproducible testing

zora 32 --unsafe --seed test

Quiet output

zora 32 --quiet

---

Security

Zora is designed to make secure random generation the default.

The default generator uses Python's secrets module rather than Python's standard random module.

The --unsafe option deliberately switches to a normal pseudo-random number generator.

This distinction is important:

Default
    ↓
secrets
    ↓
CSPRNG
    ↓
Suitable for security-sensitive random values

versus:

--unsafe
    ↓
random
    ↓
PRNG
    ↓
Not suitable for security-sensitive values

Do not use --unsafe generated values for:

• Authentication credentials
• Password reset tokens
• Session tokens
• API secrets
• Encryption keys
• Other security-sensitive secrets

unless you specifically understand the security implications.

---

Important entropy note

The entropy reported by Zora describes the size of the theoretical random output space.

For example, a 32-character key selected uniformly from 62 possible characters has:

$32 \times log{_2}\space 62$

bits of theoretical entropy.

However, entropy alone does not prove that a generator is secure.

For example:

zora 32 --unsafe

can still report a high entropy value because the theoretical output space is large.

The generator is nevertheless explicitly marked:

Generator: PRNG

and the entropy/strength display is visually marked when --unsafe is used.

---

Development

Clone the repository:

git clone https://github.com/zscopuv/Zora.git
cd Zora

Install dependencies:

pip install -r requirements.txt

Run:

zora 32

---

Roadmap

Possible future improvements include:

• More charset presets
• Improved documentation
• Installation through pip
• Packaging with pyproject.toml
• Automated test suite
• Better charset parsing errors
• Configuration files
• Shell completion
• More output formats
• Benchmarking mode
• Cross-platform terminal improvements
• API/library usage
• More extensive security testing

The roadmap is subject to change.

---

Versioning

Zora currently follows semantic versioning:

MAJOR.MINOR.PATCH

For example:

v0.1.0

The 0.x versions indicate that the CLI and features may still change before the first stable 1.0.0 release.

---

Contributing

Contributions, bug reports, feature requests, and suggestions are welcome.

Before submitting a change:

1. Make sure the program still runs.
2. Test the affected CLI options.
3. Avoid breaking existing behavior unless the change is intentional.
4. Update the documentation when adding or changing an option.

---

License

This project is licensed under the MIT License.

See LICENSE for the full license text.

---

Disclaimer

Zora is provided as-is.

While Zora uses a cryptographically secure random generator by default, the security of a system depends on how generated values are stored, transmitted, and used.

Always evaluate the complete security design of the application in which a generated key or token is used.