Metadata-Version: 2.4
Name: vcrypto
Version: 4.3.1
Summary: Utility to easily store passwords/secrets
Author-email: Arnau Villoro <arnau@villoro.com>
Maintainer-email: Arnau Villoro <arnau@villoro.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=44.0.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: pyyaml>=6.0.2

# **vcrypto - Secure Secrets Management in Python**
vcrypto is a simple and effective utility for securely storing passwords and secrets in Python. It leverages **Fernet encryption** from the [cryptography](https://cryptography.io/en/latest/) module instead of reinventing the wheel.

## **🔒 Why vcrypto?**
Managing secrets in Python, especially in collaborative projects, can be cumbersome. Our approach simplifies it:

👉 **One master private password** (ignored in Git)\
👉 **A structured dictionary file with encrypted secrets**\
👉 **Easily shareable** - only the master password needs to be exchanged once\
👉 **Version-controlled secrets** - since only encrypted values are stored

This package makes it easy to **store and retrieve encrypted secrets** in **JSON** or **YAML** formats.

---

## **📌 Features**
- 🔐 **AES-128 Encryption** (Fernet) for secure storage.
- 📂 **JSON/YAML Support** for structured secret storage.
- 🛠️ **Environment Variable Support** for flexible key management.
- 🔑 **Simple API** for saving and retrieving secrets.

---

## **📝 Installation**
Install via **pip**:
```sh
pip install vcrypto
```

---

## **🚀 Quickstart**
### **1️⃣ Initialize vcrypto**
Before using `vcrypto`, initialize it with:
```python
from vcrypto import init_vcrypto

init_vcrypto(secrets_file="secrets.yaml", environ_var_name="MY_ENV_VAR")
```

> [!TIP]
> You only need to initialize it **once**.

This ensures `vcrypto` knows where to store secrets and how to retrieve the master password.

### **2️⃣ Store and Retrieve Secrets**
#### **Save a Secret**
```python
from vcrypto import save_secret

save_secret("SECRET_TOKEN", "super_secret_value")
```

#### **Retrieve a Secret**
```python
from vcrypto import read_secret

token = read_secret("SECRET_TOKEN")
print(token)  # Output: super_secret_value
```

---

## **⚙️ Customization**
The `init_vcrypto` function allows customization:

| Parameter                 | Description |
|---------------------------|-------------|
| `secrets_file`            | Path to the encrypted secrets file (JSON/YAML) |
| `filename_master_password`| Path to the master password file (optional, defaults to `master.password`) |
| `environ_var_name`        | Name of an environment variable to retrieve the master password |

**Example:**
```python
init_vcrypto(secrets_file="config/secrets.yaml", filename_master_password="config/master.password")
```
This setup stores **both** the `master.password` and `secrets.yaml` in the `config/` folder.

> [!CAUTION]
> The master password file must **never** be committed. The bundled `.gitignore`
> only excludes `*.password`, so if you choose a custom name make sure it is
> covered by your `.gitignore`. Committing the master password alongside the
> encrypted `secrets.yaml` defeats the entire scheme.

---

## **🛠️ Development**
This project uses [`uv`](https://github.com/astral-sh/uv) for dependency management.

### **Install dependencies**
```sh
pip install uv
uv venv
uv install
```

---

## **💜 License**
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

---

## **👤 Author**
- **[Arnau Villoro](https://villoro.com)**

---
