Metadata-Version: 2.4
Name: gbkomi
Version: 0.1.2
Summary: Encrypted secret vault for Python projects
Author: gbkomi
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cryptography
Requires-Dist: argon2-cffi

gbkomi
Encrypted secret vault for Python projects with password-based protection.

gbkomi is a small Python package for storing tokens, API keys, and other secrets in an encrypted file instead of plain text .env files.

It uses:

Argon2id for password-based key derivation
AES-256-GCM for authenticated encryption
A simple JSON-based vault file format
This makes secret files much safer if they are copied, leaked, or accessed by someone without the password.

Features
Encrypt secrets into a single vault file
Password prompt from terminal when needed
Non-interactive mode with environment variable password
Configurable maximum number of stored secrets
Integrity protection with AES-GCM
Simple CLI for init, set, get, delete, list, and info
Installation
pip install gbkomi
For development:

bash
git clone https://github.com/yourusername/gbkomi.git
cd gbkomi
pip install -e .
Why use gbkomi instead of .env
A normal .env file stores secrets as plain text.

Example:

env
BOT_TOKEN=123
API_KEY=abc
If the file leaks, the secrets are immediately readable.

With gbkomi, the file contents are encrypted. If someone gets the vault file but does not know the password, they cannot directly read the secrets.

This improves security for local development, backups, copied project folders, and accidental file exposure.

Important security note
gbkomi protects secrets at rest.

That means:

the file on disk is encrypted
the file cannot be read without the password
tampering is detected during decryption
But during program execution, your application still needs the decrypted secret in memory.

So gbkomi is much safer than plain .env for stored files, but it does not fully protect against:

malware on the machine
keyloggers
memory scraping
compromised hosts
Vault structure
The encrypted vault file itself is JSON and contains metadata plus encrypted fields.

Example vault file:

json
{
  "magic": "GBK1",
  "version": 1,
  "salt": "...",
  "nonce": "...",
  "ciphertext": "..."
}
The decrypted plaintext inside the vault looks like this:

json
{
  "_meta": {
"max_secrets": 10
  },
  "secrets": {
"BOT_TOKEN": "123456",
"API_KEY": "abcdef"
  }
}
CLI usage
If the gbkomi command is available in your shell:

bash
gbkomi --help
If not, use:

bash
python -m gbkomi.cli --help
Create a vault
Interactive mode:

bash
python -m gbkomi.cli init secrets.gbkomi
This will:

ask for the password
ask for maximum number of secrets
use 10 if you press Enter without typing a number
Create a vault with a fixed limit:

bash
python -m gbkomi.cli init secrets.gbkomi --max-secrets 20
Non-interactive mode:

bash
export GBKOMI_PASSWORD="your-password"
python -m gbkomi.cli --no-interactive init secrets.gbkomi --max-secrets 20
Add or update a secret
bash
python -m gbkomi.cli set secrets.gbkomi BOT_TOKEN 123456
Read a secret
bash
python -m gbkomi.cli get secrets.gbkomi BOT_TOKEN
Delete a secret
bash
python -m gbkomi.cli delete secrets.gbkomi BOT_TOKEN
List secret names
bash
python -m gbkomi.cli list secrets.gbkomi
Show vault info
bash
python -m gbkomi.cli info secrets.gbkomi
Example output:

text
max_secrets=10
count=2
Password input modes
gbkomi supports two ways to provide the vault password.

1. Interactive terminal prompt
If no environment variable is set, gbkomi asks for the password using a hidden prompt.

This is good for:

local development
manual terminal usage
avoiding hardcoded passwords
2. Environment variable
You can provide the password with an environment variable.

Default variable name:

bash
GBKOMI_PASSWORD
Example:

bash
export GBKOMI_PASSWORD="my-secret-password"
python -m gbkomi.cli --no-interactive list secrets.gbkomi
You can also use another variable name:

bash
export MY_VAULT_PASSWORD="my-secret-password"
python -m gbkomi.cli --env-var MY_VAULT_PASSWORD --no-interactive list secrets.gbkomi
Maximum secret limit
Each vault stores a max_secrets value.

When creating a new vault, you can define how many secret entries it can hold.

If the vault reaches the limit:

adding a new key will fail
updating an existing key will still work
This is useful if you want a small fixed-size vault per bot, per project, or per deployment target.

Python usage
Example:

python
from gbkomi.vault import create_vault, set_secret, get_secret, list_secrets

create_vault("secrets.gbkomi", "mypassword", max_secrets=10)
set_secret("secrets.gbkomi", "mypassword", "BOT_TOKEN", "123456")
token = get_secret("secrets.gbkomi", "mypassword", "BOT_TOKEN")
keys = list_secrets("secrets.gbkomi", "mypassword")

print(token)
print(keys)
Error handling
Typical exceptions:

VaultFormatError
VaultDecryptionError
VaultLimitError
Example:

python
from gbkomi.vault import set_secret
from gbkomi.exceptions import VaultLimitError

try:
set_secret("secrets.gbkomi", "mypassword", "NEW_KEY", "value")
except VaultLimitError as e:
print("Vault is full:", e)
