nv-protocol 2.0.4

Context-Isolated Secret Management for Autonomous AI Software Engineering Agents

🔒 nv-protocol (nvenv)

nvenv is a local-first cryptographic proxy designed to decouple raw credentials from the viewable workspace of autonomous AI software engineering agents such as Cursor, Claude Code, Windsurf, and Devin.

Instead of exposing secrets through traditional .env files or shell environment variables, nvenv replaces them with secure cryptographic URI placeholders (nv://KEY_NAME). During outbound network communication, the proxy transparently substitutes placeholders with the real credentials only in volatile memory, immediately before the TLS request leaves the machine.

Applications continue to work normally while autonomous AI agents remain unable to access plaintext credentials.

---

⚡ Quick Start

Install Globally (Recommended)

Node.js

npm install -g nv-protocol

Python

pip install nv-protocol

Windows Package Manager (Coming Soon)

winget install SarveshSonkusre.nv-protocol

Verify installation:

nvenv --help

---

📦 Installation Options

Global Installation

Recommended if you want the nvenv command available everywhere.

npm

npm install -g nv-protocol

PyPI

pip install nv-protocol

---

Local Project Installation (Node.js)

Install only inside the current project.

npm install nv-protocol

Run using:

npx nvenv --help

or from your package scripts.

---

Install From Source

git clone https://github.com/SarveshSonkusre02/nv-protocol.git

cd nv-protocol

pip install -e .

---

✅ Verify Installation

Display the CLI help.

nvenv --help

Expected output:

nvenv (No-View Env) - Context-Isolated Secret Management CLI

Verify installed package.

npm

npm list -g nv-protocol

PyPI

pip show nv-protocol

---

❓ Why nvenv?

Traditional secret management exposes credentials directly inside:

• .env
• process.env
• os.environ
• shell exports

This means secrets become visible to:

• AI coding agents
• Third-party dependencies
• Build systems
• Prompt injection attacks
• Memory scraping tools

nvenv shifts credential injection from the application layer to the network layer, ensuring applications authenticate normally while secrets never become part of the AI-visible execution context.

---

🔒 Security Comparison

Security Vector	Legacy .env / Shell Export	nvenv
Process Environment	❌ Plaintext credentials	✅ Placeholder only
Prompt Injection	❌ Secrets can be printed	✅ AI never receives secrets
Dependency Scraping	❌ Packages can read env vars	✅ No credentials available
Authentication Scope	❌ Shared with every process	✅ Injected only into authorized outbound requests
Secret Lifetime	❌ Entire process lifetime	✅ Exists only during request execution

---

🏗 Architecture

Developer

        │

        ▼

Application
Reads

OPENAI_API_KEY=nv://OPENAI_API_KEY

        │

        ▼

────────────────────────────────────────────

           nvenv Proxy

• Validate destination
• Retrieve encrypted secret
• Decrypt in volatile memory
• Replace placeholder
• Forward TLS request

        │

        ▼

External API

Authorization:
Bearer sk-xxxxxxxxxxxxxxxx

---

🚀 Quick Start

Initialize the Vault

nvenv init

---

Store a Secret

nvenv set OPENAI_API_KEY

---

Replace Your .env

Instead of:

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

Use:

OPENAI_API_KEY=nv://OPENAI_API_KEY

---

Run Your Application

Node.js

nvenv run -- npm run dev

Python

nvenv run -- python app.py

---

List Stored Secrets

nvenv list

---

⚙️ How It Works

Application

Authorization:
Bearer nv://OPENAI_API_KEY

           │

           ▼

┌───────────────────────────────┐
│         nvenv Proxy           │
├───────────────────────────────┤
│ • Intercepts request          │
│ • Reads encrypted vault       │
│ • Decrypts in RAM             │
│ • Replaces placeholder        │
│ • Sends HTTPS request         │
└───────────────────────────────┘

           │

           ▼

api.openai.com

Authorization:
Bearer sk-xxxxxxxxxxxxxxxx

---

🛡 Core Security Features

Context Isolation

Your:

• source code
• .env
• terminal
• logs
• shell variables

contain only placeholders.

OPENAI_API_KEY=nv://OPENAI_API_KEY

Secrets never become visible inside an AI context window.

---

Hardware-Backed Vault

Windows stores credentials inside:

~/.nv/vault.db

using:

• SQLite
• Windows DPAPI encryption

Secrets are cryptographically bound to the current Windows user account.

---

Memory-Only Secret Injection

Credentials are:

• decrypted only when needed
• never stored inside environment variables
• never written to disk
• wiped immediately after request completion

---

HTTPS Proxy Injection

The runtime launches a local HTTPS interception proxy which:

• validates destinations
• decrypts secrets
• replaces placeholders
• forwards encrypted traffic

Applications remain unaware that substitution occurred.

---

AI Agent Protection

Commands such as

nvenv get OPENAI_API_KEY

cannot be abused through:

• redirected output
• pipes
• automated execution
• non-interactive sessions

The CLI verifies that a real interactive user is present before revealing secrets.

---

Git Credential Helper

Store your GitHub Personal Access Token.

nvenv set GITHUB_TOKEN

Configure Git.

git config --local credential.helper "!nvenv git-helper"

Git retrieves credentials directly from the encrypted vault without exposing tokens through:

• environment variables
• shell history
• repository files
• .gitconfig

---

💻 Platform Support

Platform	Status
Windows	✅ Stable
Linux	🚧 In Progress
macOS	🚧 In Progress
npm	✅ Available
PyPI	✅ Available
WinGet	⏳ Pending

---

🧪 Verification

Run the built-in tests.

python test_nv.py

Coverage includes:

• ✅ Vault CRUD
• ✅ Windows DPAPI encryption
• ✅ Placeholder substitution
• ✅ HTTPS interception
• ✅ Runtime injection
• ✅ End-to-end verification

---

📈 Example Workflow

Developer

     │

     ▼

nvenv set OPENAI_API_KEY

     │

     ▼

Encrypted Vault

     │

     ▼

.env

OPENAI_API_KEY=nv://OPENAI_API_KEY

     │

     ▼

nvenv run -- npm run dev

     │

     ▼

Application

     │

     ▼

nvenv Proxy

     │

     ▼

Placeholder Replacement

     │

     ▼

OpenAI API

---

🎯 Philosophy

Traditional secret managers primarily protect credentials at rest.

nvenv focuses on protecting credentials during execution, preventing autonomous AI systems, third-party packages, and prompt injection attacks from ever accessing plaintext secrets while preserving the existing application workflow.

---

🗺 Roadmap

• ✅ npm Distribution
• ✅ PyPI Distribution
• ⏳ WinGet Distribution
• ⏳ Homebrew Formula
• ⏳ Native Linux Secret Backend
• ⏳ Native macOS Keychain Backend
• ⏳ Docker Integration
• ⏳ VS Code Extension

---

📝 Notes

Global npm installation

npm install -g nv-protocol

Installs the nvenv command globally.

---

Local npm installation

npm install nv-protocol

Installs the package only inside the current project.

Use:

npx nvenv

or reference it from your project's scripts.

---

Python installation

pip install nv-protocol

Installs the nvenv command globally into the active Python environment.

---

📄 License

Released under the MIT License.