uag-envsec
Standalone Python library and CLI for encrypting environment files, managing the key used to protect them, and encrypting/decrypting text values.
The package imports as uag_envsec; its distribution name is uag-envsec.
It has no dependency on the uagent application. cryptography is required;
python-keyring is optional and only needed when using an OS keyring backend.
Install
python -m pip install .
Install OS-keyring support when desired:
python -m pip install '.[keyring]'
For development and tests:
python -m pip install '.[test]'
python -m pytest
Python API
from uag_envsec import decrypt_text, encrypt_text
ciphertext = encrypt_text("API_TOKEN=example")
plaintext = decrypt_text(ciphertext)
The default key is stored under ~/.uag/uag_envsec_key, or in the OS keyring
when the selected backend and platform allow it. An explicit key_path can be
passed to encrypt_text, decrypt_text, encrypt_file, decrypt_file, and
related functions. encrypt_file() writes <source>.sec by default; the
plaintext source is retained and existing outputs are not overwritten.
CLI
Encrypt a dotenv file to <path>.sec:
uag_envsec .env
Add or update a variable (the value is requested without echo if omitted):
uag_envsec add --file .env.sec --key API_TOKEN
Delete a variable:
uag_envsec delete --file .env.sec --key API_TOKEN
Use --key-file PATH to select an explicit file key. Existing output files are
not overwritten unless --force is supplied. add and delete read either
version and write version 1 by default; use --format-version 0 when the
result must remain readable by an older uag release.
Decrypt an encrypted file
Decrypt to a file without printing plaintext to the terminal:
uag_envsec decrypt --file .env.sec
By default this creates .env.sec.decrypted; use --output to choose another
path. The encrypted source is never replaced. An existing output is refused
unless --force is given. On POSIX systems the plaintext output is created
with owner-only permissions and written atomically.
The library API provides the same operation:
from uag_envsec import decrypt_file
plain_path = decrypt_file(".env.sec")
decrypt_file() returns the output Path, keeps plaintext in memory until
writing, and does not overwrite an existing destination by default.
Inspect an encrypted file
Check the envelope version and verify that the ciphertext authenticates and can be decrypted, without printing plaintext or key material:
uag_envsec inspect --file .env.sec
The command reports the format version, ciphertext size, authentication result, and decryptability. The library API returns the same metadata as a dictionary:
from uag_envsec import inspect_file
metadata = inspect_file(".env.sec")
Ciphertext format versions
- Version 0 is the historical unversioned Base64 ciphertext. Data with no version marker is interpreted as version 0.
- Version 1 uses the
uag-envsec:v1:prefix. The prefix is authenticated as AES-GCM associated data, so removing or changing it causes decryption to fail. This reserves an explicit envelope version for future format evolution.
New encryption writes version 1 by default. Use version 0 explicitly when
creating data for older uag releases, which only understand the historical
unversioned format:
ciphertext = encrypt_text(value, format_version=0)
uag_envsec .env --format-version 0
This library reads both formats. Unknown or malformed version markers are rejected rather than guessed as legacy data.
Migrate an existing encrypted file
Use the migrate command to decrypt an existing ciphertext in memory and
re-encrypt it using another supported envelope version. By default it upgrades
the file to version 1 and writes a new sibling file such as .env.sec.v1; the
source is never overwritten:
uag_envsec migrate --file .env.sec --to 1
Choose another destination with --output. --force permits replacing that
destination, but never replaces the source file.
The same operation is available through the library API:
from uag_envsec import migrate_file, migrate_text
versioned_text = migrate_text(ciphertext, target_version=1)
versioned_path = migrate_file(".env.sec", target_version=1)
migrate_text() returns encrypted text and does not write a plaintext
intermediate file. migrate_file() writes atomically, preserves the source,
and by default names the output <source>.v<target-version>. If a file is
already in the requested format and no output path is specified, it validates
the ciphertext and returns the source path without creating another file.
Rekey an encrypted file
rekey decrypts a file in memory and encrypts it under a different key. The
new key file is explicit and is created if it does not exist. By default the
source remains untouched and the output is <source>.rekeyed:
uag_envsec rekey --file .env.sec --old-key-file ~/.uag/uag_envsec_key --new-key-file ~/.uag/envsec-next.key
If --old-key-file is omitted, the configured default key backend is used.
The output uses version 1 by default; pass --format-version 0 for older uag
compatibility. --force only replaces the output; it never replaces the source.
Keep the new key file safe. Rekeying one file does not change the library's
configured default key or automatically rotate other .env.sec files.
The library provides both text and file APIs:
from uag_envsec import rekey_file, rekey_text
rotated = rekey_text(
ciphertext,
old_key_path="old.key",
new_key_path="new.key",
)
rotated_path = rekey_file(
".env.sec",
old_key_path="old.key",
new_key_path="new.key",
)
rekey_text() requires the new key to exist and never writes plaintext to
disk. rekey_file() also requires an existing new key; the CLI creates it
before calling the API.
Key backend settings
UAGENT_ENVSEC_KEY_BACKEND:auto,file, orkeyring(osis accepted as an alias forkeyring). Linux defaults tofile; other platforms default toauto.UAGENT_KEYRING_TIMEOUT: maximum wait for an OS keyring operation in seconds (default3, clamped to0.1–30).
In auto mode, keyring support is used when available; if the optional package
or a keyring backend is absent, the library uses the key file. Keyring access
errors and timeouts fail closed rather than silently switching key sources
while a request may still complete. The library never installs optional
dependencies implicitly. Select keyring explicitly to require an installed,
functional python-keyring backend.
File-backed keys, including explicit key paths, are created with owner-only
permissions on POSIX systems; existing key files with broader permissions are
restricted before use. The default key path rejects symlinks.
Encrypted CLI outputs are written through unique, owner-only temporary files
and replaced atomically. save_key(overwrite=True) replaces the active master
key but does not re-encrypt existing .env.sec files; retain the old key or
migrate the encrypted data before replacing it.
Compatibility
This extraction preserves the existing uag_envsec Python import name, CLI
command, default key filename, keyring service/account, key-derivation labels,
and version-0 AES-GCM ciphertext format used by the uag application. Existing
keys and .env.sec files remain usable with the same key source.
License
Apache-2.0. See LICENSE.
Metadata
Release files for uag-envsec 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| uag_envsec-0.1.0.tar.gz | 27.7 kB | Without provenance | Details for uag_envsec-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uag_envsec-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for uag_envsec-0.1.0-py3-none-any.whl |
Total release size: 47.5 kB
Release files / uag_envsec-0.1.0.tar.gz
| Download URL | uag_envsec-0.1.0.tar.gz |
|---|---|
| Size | 27.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
66c16275c2959a646e0f7d8cf0d6795ba3922cd4ecb1d30a071041127abfafbb
|
|
BLAKE2b-256 checksum How to use checksums |
9d1069315111a91763b599037ab6756639e25c59ddfab7664da5f0cb1fa6bce4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
Release files / uag_envsec-0.1.0-py3-none-any.whl
| Download URL | uag_envsec-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bd1195c2dc46a9e4d8727d4334959da0fde9c0cfa13b5956880a488a36927e29
|
|
BLAKE2b-256 checksum How to use checksums |
d699ad22d14340564a9c01d8d11b73407b1cfdf58da20744bb7354146cabf44e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.6
|
Security for uag-envsec 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.