Metadata-Version: 2.4
Name: zora-cli
Version: 0.1.4
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](https://i.ibb.co/21JfnbBZ/zora.jpg)
> **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

```bash
pip install zora-cli
````

Run Zora:

```bash
zora 32
```

# Usage

Basic usage:

```bash
zora LENGTH [OPTIONS]
```

For example:

```bash
zora 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
zora 32
```

The value must be greater than `0`.

---

## `--charset`

Select the character set used to generate keys.

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

```bash
zora 32 --charset @letters@digits
```

This creates an alphanumeric character set.

Multiple presets can be combined:

```bash
zora 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
zora 32 --charset @hexXYZ
```

This means:

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

Another example:

```bash
zora 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
zora --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
zora 32 --count 10
```

or:

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

```bash
zora 32 --prefix "AUTH_"
```

Example:

```text
AUTH_GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr
```

Add a suffix:

```bash
zora 32 --suffix "_KEY"
```

Both can be used together:

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

```bash
zora 32 --group 4
```

Output:

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

The default separator is:

```text
-
```

Use `--sep` to change it:

```bash
zora 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
zora 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
zora 32
```

The output will report:

```text
Generator: CSPRNG
```

---

# Unsafe / PRNG mode

Use:

```bash
zora 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
zora 32 --seed example
```

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

Instead:

```bash
zora 32 --unsafe --seed example
```

A seed can be useful for testing reproducibility.

For example:

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

```bash
zora 32 --quiet
```

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

For example:

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

```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
zora 32 --prefix "AUTH_"
```

has the same theoretical entropy as:

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

```text
CSPRNG
```

or:

```text
PRNG
```

---

# Example commands

### Basic key

```bash
zora 32
```

### Digits only

```bash
zora 32 --charset @digits
```

### Lowercase only

```bash
zora 32 --charset @lower
```

### Uppercase only

```bash
zora 32 --charset @upper
```

### Alphanumeric

```bash
zora 32 --charset @letters@digits
```

### Hexadecimal

```bash
zora 32 --charset @hex
```

### Hexadecimal plus custom characters

```bash
zora 32 --charset @hexXYZ
```

### Uppercase, lowercase and digits

```bash
zora 32 --charset @upper@lower@digits
```

### Symbols

```bash
zora 32 --charset @special
```

### Group the output

```bash
zora 32 --group 4
```

### Custom separator

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

### Generate multiple keys

```bash
zora 32 -n 10
```

### Save to a file

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

### Prefix

```bash
zora 32 --prefix "AUTH_"
```

### Secure generation

```bash
zora 32
```

### Reproducible testing

```bash
zora 32 --unsafe --seed test
```

### Quiet output

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

```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
zora 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
zora 32
```

---

# Roadmap

Possible future improvements include:

* [x] More charset presets
* [x] Improved documentation
* [x] Installation through `pip`
* [x] 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:

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