> ## Documentation Index
> Fetch the complete documentation index at: https://encryptd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ResponseField name="version" type="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.
</ResponseField>

<ResponseField name="salt" type="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.
</ResponseField>

<ResponseField name="iv" type="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.
</ResponseField>

<ResponseField name="content" type="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.
</ResponseField>

<ResponseField name="tag" type="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.`
</ResponseField>

***

## JSON example

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

```json .env.enc theme={null}
{
  "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.

<Note>
  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.
</Note>