Security Best Practices

Master Key Management

The ENCRYPTION_KEY is the crown jewel of your Envault instance.

• Storage: Never commit this to version control. This is your "Secret Zero" and should be injected at runtime via your infrastructure provider (e.g., Vercel Dashboard, Railway Variables, or Docker .env).
• Rotation: If you suspect the Master Key is compromised, you must immediately rotate it. This involves:
  1. Generating a new key.
  2. Decrypting all Data Keys with the old Master Key.
  3. Re-encrypting all Data Keys with the new Master Key.
  4. Updating the environment variable.

Key Rotation Policies

Envault supports key rotation for Data Keys. This limits the "blast radius" if a single Data Key is compromised. Only the secrets encrypted with that specific Data Key would be at risk, not the entire database.

Transport Security

• All communication between the CLI and the Server occurs over HTTPS.
• We recommend using HSTS (HTTP Strict Transport Security) on your production deployment.

Database Security

• RLS (Row Level Security): We use Supabase RLS to ensure that users can only access data rows they are explicitly permitted to see. Even if the application logic fails, the database layer attempts to prevent unauthorized access.
• Immutable Audit Logs: All administrative actions (mutating secrets, batch reads by machines, project changes) are written to an append-only, immutable audit_logs table. Only Project Owners can query this table via strict RLS policies.
• Ownership Chain of Custody: Ownership transfer emits explicit TRANSFER_REQUESTED, TRANSFER_ACCEPTED, and TRANSFER_REJECTED audit events to preserve legal and operational accountability.
• Data Retention: Audit logs undergo automated cleanup and are strictly retained for a maximum of 7 days to balance visibility with privacy considerations.

Identity Snapshot Retention

For operational continuity, Envault snapshots contributor identity metadata on user-linked secret records.

• Secret creator/updater identity is retained even if the original auth/profile row later disappears.
• Account deletion flows preserve shared data and keep attribution readable via stored metadata snapshots.
• Fallback labels are only used when both live identity lookup and stored snapshot metadata are unavailable.

Authentication Security

• Passkeys (WebAuthn): Envault supports passwordless authentication using WebAuthn. This provides phishing-resistant, biometric login capabilities and significantly improves account security compared to traditional passwords.

Using Passkeys

To start using passkeys, you must first log in using your existing email and password.

1. Navigate to your Settings > Security.
2. Under the Passkeys section, click Register New Passkey.
3. Your browser or operating system will prompt you to authenticate (e.g., using TouchID or Windows Hello).
4. Provide a recognizable name for the passkey (e.g., "MacBook Pro" or "YubiKey").

Once enrolled, you can sign in without a password. On the login screen, enter your email address, click Continue with Passkey, and authenticate using your device.

You can view and delete your registered passkeys from the Settings > Security page. If you delete your last remaining passkey, you will cleanly fall back to your password for future logins.

CLI Security

• Rolling Sessions: For interactive users, the Envault CLI stores long-lived Refresh Tokens securely within the native OS Secure Enclave (e.g., macOS Keychain, Windows Credential Manager) rather than plaintext files. Short-lived Access Tokens (valid for 1 hour) are used for API requests.
• Service Token Guardrails: Headless machine workflows use project-scoped Service Tokens. To prevent devastating local leakages, the CLI enforces strict Context Awareness, actively rejecting any Service Tokens executed on local developer machines unless it verifies it is running in a recognized CI/CD environment.