📋 Table of Contents

• Why Envy?
• Features Overview
• Tech Stack
• Installation
• Quick Start
• Command Reference
  • Core Commands
  • Profile Commands
  • Schema Validation
  • Git Hooks
  • Cloud & Team Commands
  • Web Dashboard
• Zero-Knowledge E2EE Architecture
• Anti-Phishing Protection
• Profile Inheritance
• Schema Validation & Type-Safety
• Log Masking
• Envy Blame
• Pre-commit Hook Integration
• Local Web Dashboard
• Use Cases
• Security Best Practices
• File Structure
• FAQ
• Contributing
• License

💡 Why Envy?

Every development team has the same problem: managing secrets is painful. .env files are plaintext, easy to leak, and impossible to share securely. Existing tools either require a third-party SaaS provider that can read your secrets, or they're so complex they need a dedicated DevOps engineer to set up.

Envy is different. It's a CLI-first tool that works like Git — you initialize it in your project directory, encrypt your secrets locally, and sync them with your team through Envy Cloud. The critical difference is that Envy Cloud never sees your secrets. Every piece of sensitive data is encrypted on your machine before it ever leaves, using the same cryptographic primitives used by Signal and 1Password.

Envy replaces:

• Plaintext .env files ❌
• Shared password vaults with copy-paste workflows ❌
• Third-party secret managers that require you to trust their servers ❌

With:

• AES-256-GCM encrypted local storage ✅
• Zero-Knowledge End-to-End Encryption for cloud sync ✅
• A single CLI command (envy run) that injects secrets into memory without ever touching disk ✅

✨ Features Overview

🛠️ Tech Stack

Envy is a full-stack application spanning a Python CLI, a Node.js API, a React web dashboard, and a self-contained local UI — all unified by a Zero-Knowledge cryptographic core.

CLI (Python)

Backend (Node.js)

Frontend (React)

Cryptographic Primitives

Installation

# Install from PyPI
pip install envy-secrets

PyPI: https://pypi.org/project/envy-secrets/

Requirements: Python 3.10+

Development Installation

# Clone the repository
git clone https://github.com/KRISHNA-JAIN15/ENVY.git
cd ENVY

# Create and activate virtual environment
python -m venv venv
.\venv\Scripts\Activate   # Windows
source venv/bin/activate   # Linux/macOS

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Quick Start

# 1. Initialize Envy in your project
envy init

# 2. Add some secrets
envy set DATABASE_URL=postgres://localhost/mydb
envy set API_KEY=sk-1234567890 --expires 30d
envy set PORT=3000 --profile prod

# 3. View your secrets
envy view                          # Active profile (masked)
envy view --profile prod --show    # Show actual values

# 4. Run your app with secrets injected into memory (BEST PRACTICE!)
envy run dev -- npm start
envy run prod -- python app.py

# 5. Open the visual dashboard
envy ui

# 6. Sync with your team via Envy Cloud
envy cloud login
envy cloud push

📖 Command Reference

Core Commands

Profile Commands

Schema Validation

Git Hooks

Cloud & Team Commands

Web Dashboard

🔐 Zero-Knowledge E2EE Architecture

Envy v2 implements a complete Zero-Knowledge End-to-End Encryption system. The server never sees your secrets or your private key. Here is how every layer works:

1. User Account Creation (Key Derivation)

When a user signs up (envy cloud register):

1. The CLI asks for a Master Password.
2. The CLI stretches the password into a 256-bit Account Key using Argon2id — the winner of the Password Hashing Competition and the current gold standard for key derivation.
3. The CLI generates an X25519 asymmetric keypair (a Public Key and a Private Key).
4. The CLI encrypts the Private Key using the Account Key with AES-256-GCM.
5. What is sent to the server: The plaintext Public Key, the encrypted Private Key, and the key salt. The Master Password and Account Key never leave your computer.

2. Project Initialization (envy init)

1. The CLI generates a random 256-bit Project Master Key (symmetric, AES-256-GCM).
2. All local .env variables are encrypted using this Project Master Key.
3. The key is stored locally in .envy/master.key and added to .gitignore.

3. Pushing to the Cloud (envy cloud push)

Instead of decrypting secrets before sending them:

1. The CLI sends the secrets still encrypted with the Project Master Key.
2. To allow the cloud to store the Project Master Key safely, the CLI fetches the user's Public Key from the server.
3. The CLI encrypts the Project Master Key using the user's Public Key (X25519 sealed box).
4. What is sent to the server: The encrypted secrets blob + the encrypted Project Master Key. The server holds your data, but it is mathematically impossible for the server to read it.

4. Team Sharing (Adding a Teammate)

How do you securely share secrets if the server can't read them?

1. Admin runs envy team add teammate@email.com.
2. The CLI fetches the teammate's Public Key from the server.
3. The CLI takes the local Project Master Key and encrypts a copy of it using the teammate's Public Key.
4. The CLI pushes this new wrapped key to the server.
5. When the teammate runs envy cloud clone, they download the encrypted secrets and their specific encrypted copy of the Project Master Key. They decrypt the Project Master Key using their own Private Key, then decrypt the secrets.

Cryptographic Primitives

Note: The React web frontend mirrors the CLI's cryptographic capabilities using the Web Crypto API (AES-256-GCM, PBKDF2) and libsodium-wrappers (X25519). Keys are held in ephemeral memory refs and are never persisted to localStorage or cookies.

🎣 Anti-Phishing Protection

Envy implements 100% phishing-proof authentication using two complementary protocols. No matter how a user logs in, their credentials are mathematically protected from interception.

WebAuthn (Passkeys) — Primary Login

When you run envy cloud login or log in on the web dashboard, Envy uses WebAuthn / FIDO2 Passkeys. Passkeys are cryptographic credentials tied to the exact domain name (envy.com). If a user is tricked into visiting a fake site (envvy.com), the browser physically refuses to authenticate — the attack is impossible at the protocol level.

Supported Authenticators: Apple TouchID, Windows Hello, Microsoft Authenticator, Google Password Manager, 1Password, YubiKey, and any FIDO2-compliant device.

CLI Flow (OAuth PKCE):

1. You run envy cloud login.
2. The CLI spins up a temporary localhost server and opens your browser.
3. You authenticate on the trusted domain via Passkey (biometric scan, QR code, etc.).
4. The browser redirects back to the CLI with the session token.
5. The CLI captures the token and you're logged in — no password was typed.

envy cloud login                  # Opens browser → Passkey authentication

SRP-6a (Secure Remote Password) — Headless Fallback

For environments where a browser cannot be opened (SSH servers, CI/CD pipelines, Docker containers), Envy falls back to SRP-6a — a zero-knowledge proof protocol from RFC 5054.

How it stops phishing: Instead of sending your password to the server, the CLI uses your password to solve a mathematical challenge. Even if you accidentally connect to a malicious server, the server learns absolutely nothing about your password. The CLI also verifies the server's proof (M2) to confirm the server is authentic.

envy cloud login --headless       # SRP challenge-response (no browser needed)

The 2-Step Handshake:

1. Step 1 (Challenge): CLI sends email + ephemeral value A. Server responds with salt + ephemeral value B.
2. Step 2 (Proof): CLI computes proof M1 using the password locally. Server verifies M1 and responds with its own proof M2. CLI verifies M2 to ensure the server is real.

At no point does the password leave the client. The server stores only a mathematical verifier (computed during registration), which cannot be reversed to recover the password.

Vault Decryption (Always Local)

Whether you log in via Passkey or SRP, the server only handles authentication (proving who you are). The actual decryption of your secrets always requires your Master Password locally — the server never has access to it. This is the same security model used by 1Password and Bitwarden.

Implementation Details

CLI Integration

• envy cloud register: Computes the SRP salt and verifier locally (your password is never sent). It generates an X25519 E2EE keypair, encrypts the private key using an Argon2id-derived key, and sends only the verifier and the encrypted key material to the server.
• envy cloud login: Defaults to the OAuth PKCE browser flow for Passkey authentication. The --headless flag triggers the 2-step SRP challenge-response handshake.

Frontend WebAuthn & SRP Integration

• SRP Client (srp.js): A JavaScript SRP-6a client manages SRPSession and generateVerifier to ensure zero-knowledge authentication in the browser.
• API endpoints (api.js): Replaced traditional login with srpChallenge and srpVerify endpoints, and added endpoints for WebAuthn authentication.
• Auth Context (AuthContext.jsx): The register() function computes the SRP verifier locally. The login() function performs the 2-step SRP handshake. New loginWithPasskey() and registerPasskey() functions handle WebAuthn.
• Auth UI: Login.jsx features a two-tab UI: Passkey (default, phishing-proof) and Master Password (SRP, zero-knowledge). Signup.jsx uses SRP registration and clearly indicates that the "password never leaves your device."

🔗 Profile Inheritance

If you have 50 variables in prod and 49 of them are the same in staging, you shouldn't have to duplicate them all. With profile inheritance, you store only the overrides.

How It Works

# Create a staging profile that inherits everything from prod
envy profile create staging --extends prod

# Override just the one key that's different
envy set DATABASE_URL=postgres://staging-db --profile staging

Now staging automatically inherits all 50 keys from prod, and only the DATABASE_URL override is stored in the staging profile. The secrets.json stays small and manageable.

Viewing Inherited Secrets

envy view --profile staging

The table shows a Source column:

• own — the key is defined directly in this profile
• ← prod — the key is inherited from the parent profile

Circular Reference Protection

Envy walks the inheritance chain with cycle detection. If you accidentally create a circular dependency (A extends B, B extends A), it will stop and use only the keys it has already resolved.

🛡️ Schema Validation & Type-Safety

Plain .env files are just dumb strings. Envy lets you define strict rules for your secrets so that mistakes are caught before they reach production.

Setting Up a Schema

Create an envy.schema.json file in your project root:

{
  "variables": {
    "PORT": {
      "type": "integer",
      "required": true
    },
    "DATABASE_URL": {
      "type": "url",
      "required": true
    },
    "STRIPE_KEY": {
      "type": "string",
      "profiles": {
        "dev": { "pattern": "^sk_test_" },
        "prod": { "pattern": "^sk_live_" }
      }
    },
    "LOG_LEVEL": {
      "type": "string",
      "enum": ["debug", "info", "warn", "error"]
    },
    "APP_NAME": {
      "type": "string",
      "minLength": 3,
      "maxLength": 50
    }
  }
}

Supported Validation Rules

What Happens When Validation Fails

$ envy set STRIPE_KEY=sk_test_123 --profile prod
Schema Error: Value for STRIPE_KEY in profile 'prod' must match pattern: ^sk_live_

The CLI blocks the operation and does not save the secret.

CLI Commands

envy schema show        # Display the current schema rules
envy schema init        # Auto-generate a schema from existing secrets
envy schema validate    # Validate all secrets in the active profile

🎭 Log Masking

When you run envy run prod -- npm start, Envy doesn't just inject the secrets — it actively protects them from being leaked in logs.

How It Works

1. The subprocess is launched with stdout and stderr piped through Envy.
2. Two daemon threads read the output line-by-line in real time.
3. Every line is scanned for any secret value (≥ 4 characters long).
4. Matches are replaced with ******** before being printed to your terminal.

Example

# If your app accidentally prints: "Connecting to postgres://admin:s3cret@db:5432"
# You see:                         "Connecting to ********"

Controlling Log Masking

envy run prod -- npm start          # Masking ON (default)
envy run prod --no-mask -- npm start  # Masking OFF

📜 Envy Blame

Just like git blame, Envy Blame shows you exactly who changed a specific secret, when they changed it, and from which source (CLI or web dashboard).

Usage

envy blame DATABASE_URL

Output

┌──────────────────────────────────────────────────────────────┐
│                     📜 Blame: DATABASE_URL                   │
├────────┬──────────┬─────────┬──────┬────────┬───────────────┤
│ Commit │ User     │ Action  │ Env  │ Source │ When          │
├────────┼──────────┼─────────┼──────┼────────┼───────────────┤
│ a3f2c1 │ Krishna  │ updated │ prod │ cli    │ 2 hours ago   │
│ 8b1d4e │ Krishna  │ created │ prod │ web    │ 3 days ago    │
└────────┴──────────┴─────────┴──────┴────────┴───────────────┘

This works by querying the Envy Cloud activity log (activities.js model) for all events related to that specific key. It requires a remote to be configured (envy cloud remote add <slug>).

🪝 Pre-commit Hook Integration

A common failure mode: a developer adds a new package (like Stripe), creates a STRIPE_KEY in their local Envy, writes the code, and pushes — but forgets to run envy cloud push. The CI build breaks for everyone.

Installation

envy hooks install

This creates a script in .git/hooks/pre-commit. Every time a developer runs git commit:

1. The hook checks if .envy/secrets.json has been modified in the staged files.
2. If it has, the hook warns the developer and asks them to push their secrets to the cloud before committing.
3. The commit proceeds, but the developer gets a clear, visible prompt.

Uninstallation

envy hooks uninstall

This cleanly removes only the Envy portion of the pre-commit hook, leaving any other hooks intact.

🖥️ Local Web Dashboard (envy ui)

Managing 100+ environment variables in a terminal can be tedious. The envy ui command launches a beautiful, full-screen dark-mode dashboard on localhost where you can manage everything visually.

How It's Built

The dashboard is completely self-contained inside the Python package. It uses Python's built-in http.server module — zero external web framework dependencies (no Flask, no FastAPI, no npm). The entire HTML, CSS, and JavaScript is embedded as a single inline template in web_ui.py.

Launching the Dashboard

envy ui                    # Launch on port 8888, auto-open browser
envy ui --port 3000        # Use a custom port
envy ui --no-open          # Start without opening browser

Dashboard Features

Security

The server binds exclusively to 127.0.0.1 (localhost). It is not accessible from other machines on the network. All decryption happens server-side in the Python process — the browser receives already-decrypted values over the local loopback interface.

💡 Use Cases

Local Development

# Developer A sets up the project
envy init
envy set DATABASE_URL=postgres://localhost/dev
envy set API_KEY=dev-key-123
envy run dev -- npm start

# Developer B clones and gets secrets
git clone repo && cd repo
envy cloud login
envy cloud clone myproject --env development
envy run dev -- npm start

Multiple Environments with Inheritance

# Set up production with all variables
envy set DATABASE_URL=postgres://prod-db --profile prod
envy set REDIS_URL=redis://prod-cache --profile prod
envy set API_KEY=live-key-prod --profile prod

# Staging inherits everything, only override what's different
envy profile create staging --extends prod
envy set DATABASE_URL=postgres://staging-db --profile staging

# Run in either environment
envy run prod -- python app.py
envy run staging -- python app.py    # Gets prod's REDIS_URL and API_KEY automatically

CI/CD Pipeline

# In your CI/CD pipeline (GitHub Actions, GitLab CI, etc.)
pip install envy-secrets
envy cloud login --email $ENVY_EMAIL --password $ENVY_PASSWORD
envy cloud clone myproject --env production
envy run prod -- npm run build

Secret Rotation with Schema Enforcement

# Set up schema rules
envy schema init

# Set secrets with expiration
envy set API_KEY=old-key --expires 30d

# Check for expiring secrets (great for CI health checks)
envy check    # Returns exit code 1 if issues found

# Rotate the secret
envy set API_KEY=new-key --expires 30d

🔒 Security Best Practices

1. Never commit .envy/master.key — It's automatically added to .gitignore during envy init.
2. Use envy run instead of envy export — Secrets stay in process memory and are never written to a plaintext file on disk.
3. Enable log masking — It's on by default with envy run. Any secret value that leaks into stdout or stderr is replaced with ********.
4. Set expiration dates — envy set KEY=value --expires 30d ensures you rotate secrets regularly.
5. Run envy check in CI — It returns a non-zero exit code if any secrets are expired or stale.
6. Install pre-commit hooks — envy hooks install warns developers when they forget to push new secrets.
7. Use schema validation — Define envy.schema.json to prevent staging keys from accidentally being used in production.

File Structure

your-project/
├── .envy/
│   ├── master.key        # 🔑 AES-256-GCM encryption key (NEVER COMMIT!)
│   └── secrets.json      # 🔒 Encrypted secrets database (safe to commit)
├── envy.schema.json      # 📋 Optional schema validation rules (commit this)
├── .gitignore            # Auto-updated by envy init
└── ...

❓ FAQ

How is this different from dotenv?

dotenv loads plaintext .env files. Envy encrypts secrets at rest with AES-256-GCM, supports multiple profiles, enforces schema validation, syncs via Zero-Knowledge E2EE, masks log output, and provides a visual web dashboard. It's an entire secret management platform, not just a file loader.

Can I use this with my existing .env files?

Yes! Import your existing .env file and Envy will encrypt every variable:

envy import .env

What happens if I lose my master key?

Without .envy/master.key, your local secrets cannot be decrypted. Always back up this file securely. If you use Envy Cloud, your secrets are also stored (encrypted) on the server and can be re-cloned by any team member.

Is it safe to commit .envy/secrets.json?

Yes. The secrets.json file contains only AES-256-GCM encrypted ciphertext. Without the master key, it is computationally infeasible to decrypt.

What encryption does Envy use?

Envy v2 uses AES-256-GCM (symmetric, AEAD), X25519 (asymmetric key exchange, Curve25519), and Argon2id (key derivation). Fernet (AES-128-CBC) was fully removed in v2.0.

Can I use this in production?

Absolutely. Use envy run prod -- your-command to inject secrets directly into your process without writing them to disk. The log masking feature ensures secrets don't leak into stdout/stderr.

Does the web dashboard expose secrets to the network?

No. The envy ui server binds exclusively to 127.0.0.1 (localhost). It is not accessible from any other machine.

Is this compatible with Microsoft Authenticator / YubiKey / TouchID?

Yes, Envy uses standard WebAuthn for hardware-backed keys. It works out-of-the-box with Apple Touch ID, Windows Hello, YubiKeys, and authenticator apps like 1Password and Microsoft Authenticator.

Why make a project "Public" if it only has environment variables?

This is a great question, because exposing actual secrets (like Database URLs or API keys) publicly is incredibly dangerous! However, having a "Public" visibility option for an env manager serves a few very powerful, specific use cases:

• Open Source Templates (.env.example replacement): If you build an open-source project on GitHub, you can create a public Envy project that contains all the keys (and maybe safe default values) but keeps the real secrets blank. Contributors can just run envy pull <project-id> to instantly generate their local .env file with the correct schema, instead of copy-pasting from a .env.example file.
• Public Configuration: Sometimes apps need to share non-sensitive configuration globally (e.g., PUBLIC_API_URL, feature flags, or theme settings). A public project allows client-side apps or community members to fetch this configuration without needing authentication.
• Forking Configurations: Just like you fork a repo on GitHub, developers could "Fork" a public Envy project to instantly get the base configuration for a popular framework (like a Next.js starter kit) copied into their own private workspace.

🤝 Contributing

We welcome contributions! Here's how to get started:

Setting Up

git clone https://github.com/KRISHNA-JAIN15/ENVY.git
cd ENVY
python -m venv venv
source venv/bin/activate        # Linux/macOS
.\venv\Scripts\Activate         # Windows
pip install -e ".[dev]"

Running Tests

pytest

Code Style

black .
ruff check .

Contribution Guidelines

1. Fork the repository and create a feature branch.
2. Make your changes with clear, descriptive commit messages.
3. Add tests for new features.
4. Ensure all tests pass with pytest.
5. Format your code with black and ruff.
6. Submit a pull request with a clear description of what you changed and why.

Report Issues

Found a bug or have a feature request? Open an issue on GitHub.

📄 License

MIT License — see the LICENSE file for details.