EnvPayload Encrypted File Type Reference for encryptd

Reference for the EnvPayload TypeScript type used by encryptd. Covers all five fields, hex sizes, and how the type flows through the API and CLI.

EnvPayload is the TypeScript type that represents an encrypted .env.enc file. Every call to encryptEnv() returns an EnvPayload, every call to decryptEnv() accepts one as its first argument, and the secure-env encrypt and secure-env decrypt CLI commands read and write the same structure serialized as JSON on disk. All binary fields salt, IV, ciphertext, and authentication tag are stored as lowercase hexadecimal strings so the file is human-readable and safely embeds in version control workflows.

---

Fields

The table below summarizes all five fields in an EnvPayload.

Field	Type	Size	Description
version	number	—	Schema version integer. Currently always 1. Used to detect and handle format migrations in future releases.
salt	string	16 bytes (32 hex chars)	Random salt generated per encryption. Fed into PBKDF2-HMAC-SHA256 alongside your passphrase to derive the 256-bit AES key. Never reused across encryptions.
iv	string	12 bytes (24 hex chars)	Random nonce (initialization vector) generated per encryption. Used as the AES-256-GCM nonce. 96 bits is the NIST-recommended nonce length for GCM.
content	string	variable	Hex-encoded AES-256-GCM ciphertext. Length depends on the length of the original plaintext.
tag	string	16 bytes (32 hex chars)	GCM authentication tag. Verified during decryption before any plaintext is returned. A mismatch causes an immediate error.

---

Field reference

version · number

Schema version integer, currently always 1. encryptd checks this field when decrypting so it can apply the correct decryption logic if the format ever changes. Files encrypted today will remain decryptable after any future format migration.

salt · string

32-character lowercase hex string representing the 16 random bytes generated by OsRng at encryption time. The salt is stored here so decryption can re-derive the exact same AES key via PBKDF2-HMAC-SHA256 (100,000 iterations) without storing any key material on disk.

iv · string

24-character lowercase hex string representing the 12-byte (96-bit) AES-GCM nonce generated by OsRng at encryption time. Because a fresh nonce is generated on every encryption, two encryptions of the same plaintext with the same passphrase will always produce different iv and content values.

content · string

Variable-length lowercase hex string containing the AES-256-GCM ciphertext. The byte length of the original plaintext and the byte length of the ciphertext are identical AES-GCM is a stream cipher mode and does not add padding.

tag · string

32-character lowercase hex string representing the 16-byte GCM authentication tag. The tag is computed over the ciphertext during encryption and re-verified in a single atomic operation during decryption. If verification fails due to a wrong passphrase or any modification to the file decryption halts immediately with [RustLib] Decryption failed. Wrong key or tampered file.

---

JSON example

After running secure-env encrypt, your .env.enc file looks like this:

.env.enc

{
  "version": 1,
  "salt": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "iv": "0123456789abcdef01234567",
  "content": "deadbeefcafebabe...",
  "tag": "cafebabe0123456789abcdef01234567"
}

---

How EnvPayload flows through the library

EnvPayload is the central data type that connects every part of encryptd:

• encryptEnv(plainText, passphrase) returns an EnvPayload. You can serialize it to disk with JSON.stringify or pass it directly to decryptEnv().
• decryptEnv(payload, passphrase) accepts an EnvPayload as its first argument. All four binary fields (salt, iv, content, tag) must be present and valid hexadecimal; malformed hex causes an immediate descriptive error.
• secure-env encrypt writes a JSON-serialized EnvPayload to the output file.
• secure-env decrypt reads a JSON-serialized EnvPayload from the input file and deserializes it before passing it to the Rust decryption layer.
• config() reads and deserializes the EnvPayload internally; you never interact with it directly when using this high-level function.

All binary fields are hex-encoded strings, not raw bytes or Base64. This makes the .env.enc file easy to inspect, diff, and store in version control without binary noise.