zora-cli 0.1.2__py3-none-any.whl

zora_cli-0.1.2.dist-info/METADATA

@@ -0,0 +1,1021 @@
+Metadata-Version: 2.4
+Name: zora-cli
+Version: 0.1.2
+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
+Dynamic: license-file
+
+# ![Logo](zora.jpg)
+> **Early release (`v0.1.2`)**
+
+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.