Skip to main content

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, or keyring (os is accepted as an alias for keyring). Linux defaults to file; other platforms default to auto.
  • UAGENT_KEYRING_TIMEOUT: maximum wait for an OS keyring operation in seconds (default 3, clamped to 0.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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uag-envsec 0.1.1
File Size Uploaded Provenance Actions
uag_envsec-0.1.1.tar.gz 31.7 kB Without provenance Details for uag_envsec-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for uag-envsec 0.1.1
File Interpreter ABI Platform Actions
uag_envsec-0.1.1-py3-none-any.whl Python 3 none any Details for uag_envsec-0.1.1-py3-none-any.whl

Total release size: 51.5 kB

Release files / uag_envsec-0.1.1.tar.gz

Download URL uag_envsec-0.1.1.tar.gz
Size 31.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9b611b51e4688a5272fe0bff0bfa7f0ac95ca16068197099606f219eaec38434
BLAKE2b-256 checksum
How to use checksums
61b10cd19b0708fdc3399a5d8d7689a088323630dd80806a67e204d4f10afb42
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Release files / uag_envsec-0.1.1-py3-none-any.whl

Download URL uag_envsec-0.1.1-py3-none-any.whl
Size 19.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08ed90fb5213481eed66b3530bb29fafe54ac1c960409ca4dd05fe5d3a8d8131
BLAKE2b-256 checksum
How to use checksums
adc7de66f032eb36c704b85781ad154f58ce41e92e245f4272bd7cd9ec745ad8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for uag-envsec 0.1.1

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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page