gbkomi 0.1.1

Encrypted secret vault for Python projects

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)