EnvPayload Encrypted File Type Reference for encryptd

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.

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.

​Fields

​Field reference

​JSON example

​How EnvPayload flows through the library

Fields

Field reference

JSON example

How EnvPayload flows through the library