Metadata-Version: 2.4
Name: zora-cli
Version: 0.1.3
Summary: Cryptographically secure generator of random keys with tons of options and customizations.
Author: zscopuv
License: ZORA SOURCE-AVAILABLE LICENSE
        Version 1.0
        
        Copyright © 2026 radecekq
        All rights reserved.
        
        1. DEFINITIONS
        
        For the purposes of this License:
        
        "Software" means the Zora software, including its source code, documentation,
        configuration files, assets, and any other materials distributed with the
        Software.
        
        "Original Software" means the Software as distributed by the Copyright Holder.
        
        "Modified Version" means any version of the Software that has been altered,
        adapted, translated, extended, refactored, or otherwise changed from the
        Original Software.
        
        "Copyright Holder" means the individual or entity that owns the copyright in
        the Software.
        
        "User" means any individual or organization obtaining access to the Software.
        
        "Redistribution" means providing, publishing, transmitting, selling,
        licensing, sublicensing, uploading, mirroring, or otherwise making the
        Software or a Modified Version available to any third party.
        
        
        2. GRANT OF RIGHTS
        
        Subject to the terms and conditions of this License, the Copyright Holder
        grants the User a limited, non-exclusive, non-transferable, revocable license
        to:
        
            a. access and inspect the source code of the Software;
        
            b. copy the Software for personal use and development;
        
            c. create private forks of the Software;
        
            d. modify, adapt, extend, or otherwise alter the Software;
        
            e. compile and execute the Software and Modified Versions for personal
               use; and
        
            f. use the Software and Modified Versions for non-commercial purposes.
        
        These permissions do not constitute a transfer of ownership or copyright.
        
        
        3. REDISTRIBUTION PROHIBITED
        
        The User may not, without prior written permission from the Copyright Holder:
        
            a. redistribute the Original Software;
        
            b. redistribute any Modified Version;
        
            c. publish a fork of the Software;
        
            d. publish source code derived from the Software;
        
            e. distribute compiled binaries or executable versions of the Software
               or a Modified Version;
        
            f. upload the Software or a Modified Version to another repository,
               package registry, download service, file-sharing service, or similar
               distribution platform;
        
            g. sell, sublicense, rent, lease, or otherwise transfer the Software or
               a Modified Version to another person or organization; or
        
            h. make the Software or a Modified Version publicly available through
               any medium.
        
        
        4. PRIVATE FORKS
        
        The User may create and maintain private forks of the Software for personal
        development, experimentation, testing, education, or other lawful purposes.
        
        A private fork must not be made available to third parties without the
        express written permission of the Copyright Holder.
        
        Nothing in this section grants permission to publish or redistribute a fork.
        
        
        5. MODIFICATIONS
        
        The User is expressly permitted to modify the Software for private use.
        
        Modifications may include, but are not limited to:
        
            - adding or removing functionality;
            - changing the user interface;
            - changing configuration;
            - fixing bugs;
            - refactoring code;
            - creating experimental features; and
            - adapting the Software for personal environments.
        
        However, the creation of a Modified Version does not grant the User any
        additional right to redistribute that Modified Version.
        
        
        6. COPYRIGHT AND OWNERSHIP
        
        The Software remains the property of the Copyright Holder.
        
        This License does not transfer ownership of the Software, its source code,
        copyright, trademarks, trade names, or other intellectual property rights.
        
        All rights not expressly granted by this License are reserved by the
        Copyright Holder.
        
        
        7. ATTRIBUTION
        
        If the Software or a Modified Version is used privately, the User is
        encouraged to preserve all existing copyright notices, license notices,
        author information, and attribution contained within the Software.
        
        Nothing in this License permits the removal of copyright notices for the
        purpose of claiming ownership of the Original Software.
        
        
        8. COMMERCIAL USE
        
        Commercial use, including incorporation of the Software into a commercial
        product or service, is not permitted unless expressly authorized in writing
        by the Copyright Holder.
        
        The Copyright Holder may grant separate commercial licenses at their
        discretion.
        
        
        9. REQUESTS FOR REDISTRIBUTION
        
        A User wishing to redistribute the Software or a Modified Version may
        contact the Copyright Holder and request explicit permission.
        
        Permission may be granted or denied at the sole discretion of the Copyright
        Holder.
        
        Any permission to redistribute may be subject to additional terms and
        conditions established by the Copyright Holder.
        
        
        10. NO WARRANTY
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, TITLE, OR NON-INFRINGEMENT.
        
        THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
        LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
        OR OTHER DEALINGS IN THE SOFTWARE.
        
        
        11. LIMITATION OF LIABILITY
        
        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE COPYRIGHT HOLDER
        SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL,
        OR EXEMPLARY DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE.
        
        
        12. TERMINATION
        
        This License automatically terminates if the User violates any of its terms.
        
        Upon termination, the User must cease all use of the Software and destroy
        copies of the Software and Modified Versions in their possession or control,
        except where retention is required by applicable law.
        
        Permissions may be reinstated only through explicit written authorization
        from the Copyright Holder.
        
        
        13. SEVERABILITY
        
        If any provision of this License is determined to be invalid or
        unenforceable, the remaining provisions shall remain in full force and
        effect.
        
        
        14. ENTIRE AGREEMENT
        
        This License constitutes the entire agreement concerning the Software and
        supersedes any prior or contemporaneous understanding concerning the rights
        granted under this License.
        
        
        15. RESERVATION OF RIGHTS
        
        The Copyright Holder reserves all rights not expressly granted by this
        License.
        
        No permission should be inferred merely because a particular restriction is
        not explicitly stated.
        
        
        16. LICENSE VERSION
        
        This license is designated:
        
            Zora Source-Available License v1.0
        
        Future versions of this License may be published by the Copyright Holder.
        Unless explicitly stated otherwise, a particular version of the Software
        remains governed by the license version distributed with that version.
        
        
        Copyright © 2026 radecekq
        All rights reserved.
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama==0.4.6
Requires-Dist: packaging>=24.0
Dynamic: license-file

# ![Logo](zora.jpg)
> **Early release (`v0.1.3`)**

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


# Usage

Basic usage:

```bash
python zora.py LENGTH [OPTIONS]
```

For example:

```bash
python zora.py 32
```

Example output:

```text
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.

```bash
python zora.py 32
```

The value must be greater than `0`.

---

## `--charset`

Select the character set used to generate keys.

```bash
python zora.py 32 --charset @digits
```

By default:

```text
@letters
```

is used.

Zora supports both predefined charset presets and literal characters.

### Presets

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

```bash
python zora.py --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:

```bash
python zora.py 32 --charset @letters@digits
```

This creates an alphanumeric character set.

Multiple presets can be combined:

```bash
python zora.py 32 --charset @upper@lower@digits
```

Duplicate characters are automatically removed.

For example:

```text
@letters@upper
```

does not contain uppercase characters twice.

---

## Custom characters

Literal characters can be included alongside presets.

For example:

```bash
python zora.py 32 --charset @hexXYZ
```

This means:

```text
@hex + X + Y + Z
```

Another example:

```bash
python zora.py 32 --charset XYZ@hex
```

means:

```text
X + Y + Z + @hex
```

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

---

# `--charset-list`

Display the available charset presets:

```bash
python zora.py --charset-list
```

Example:

```text
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`:

```bash
python zora.py 32 --count 10
```

or:

```bash
python zora.py 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:

```bash
python zora.py 32 --prefix "AUTH_"
```

Example:

```text
AUTH_GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr
```

Add a suffix:

```bash
python zora.py 32 --suffix "_KEY"
```

Both can be used together:

```bash
python zora.py 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:

```bash
python zora.py 32 --group 4
```

Output:

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

The default separator is:

```text
-
```

Use `--sep` to change it:

```bash
python zora.py 32 --group 4 --sep ":"
```

Output:

```text
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:

```bash
python zora.py 32 -n 10 --output keys.txt
```

The generated keys are written one per line.

Example:

```text
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.

```bash
python zora.py 32
```

The output will report:

```text
Generator: CSPRNG
```

---

# Unsafe / PRNG mode

Use:

```bash
python zora.py 32 --unsafe
```

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

Zora will display a warning:

```text
Program will output cryptographically insecure keys.
```

and:

```text
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:

```bash
python zora.py 32 --seed example
```

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

Instead:

```bash
python zora.py 32 --unsafe --seed example
```

A seed can be useful for testing reproducibility.

For example:

```bash
python zora.py 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:

```bash
python zora.py 32 --quiet
```

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

For example:

```bash
python zora.py 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:

```text
182.17 bits
```

The entropy calculation only considers random characters.

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

For example:

```bash
python zora.py 32 --prefix "AUTH_"
```

has the same theoretical entropy as:

```bash
python zora.py 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:

```text
CSPRNG
```

or:

```text
PRNG
```

---

# Example commands

### Basic key

```bash
python zora.py 32
```

### Digits only

```bash
python zora.py 32 --charset @digits
```

### Lowercase only

```bash
python zora.py 32 --charset @lower
```

### Uppercase only

```bash
python zora.py 32 --charset @upper
```

### Alphanumeric

```bash
python zora.py 32 --charset @letters@digits
```

### Hexadecimal

```bash
python zora.py 32 --charset @hex
```

### Hexadecimal plus custom characters

```bash
python zora.py 32 --charset @hexXYZ
```

### Uppercase, lowercase and digits

```bash
python zora.py 32 --charset @upper@lower@digits
```

### Symbols

```bash
python zora.py 32 --charset @special
```

### Group the output

```bash
python zora.py 32 --group 4
```

### Custom separator

```bash
python zora.py 32 --group 4 --sep ":"
```

### Generate multiple keys

```bash
python zora.py 32 -n 10
```

### Save to a file

```bash
python zora.py 32 -n 100 -o keys.txt
```

### Prefix

```bash
python zora.py 32 --prefix "AUTH_"
```

### Secure generation

```bash
python zora.py 32
```

### Reproducible testing

```bash
python zora.py 32 --unsafe --seed test
```

### Quiet output

```bash
python zora.py 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:

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

versus:

```text
--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:

```bash
python zora.py 32 --unsafe
```

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

The generator is nevertheless explicitly marked:

```text
Generator: PRNG
```

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

---

# Development

Clone the repository:

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

Install dependencies:

```bash
pip install -r requirements.txt
```

Run:

```bash
python zora.py 32
```

---

# Project structure

A minimal installation currently looks like:

```text
Zora/
├── zora.py
├── zora.jpg
├── LICENSE
├── README.md
└── requirements.txt
```

Future versions may introduce a package structure and automated tests.

---

# Roadmap

Possible future improvements include:

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

The roadmap is subject to change.

---

# Versioning

Zora currently follows semantic versioning:

```text
MAJOR.MINOR.PATCH
```

For example:

```text
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`](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.
