nv-protocol 2.0.2

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 .env files or shell environment variables, nvenv replaces them with secure cryptographic URI placeholders. During outbound network communication, the proxy dynamically substitutes placeholders with real credentials only in volatile memory at the OS socket boundary during TLS handshakes.

This allows applications to execute normally while keeping autonomous AI agents mathematically blind to the underlying credentials.

---

⚡ Quick Start

Install globally using your preferred ecosystem.

Node.js

npm install -g nv-protocol

Python

pip install nv-protocol

Windows (Planned)

Validation Pending

winget install SarveshSonkusre.nv-protocol

---

❓ Why nvenv?

Traditional .env files and shell environment variables inject plaintext secrets directly into:

• process.env
• os.environ

This exposes credentials to:

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

nvenv moves secret injection to the network layer, preventing untrusted processes from ever seeing the real credentials.

---

Security Comparison

Security Vector	Legacy .env / Shell Export	nvenv
Process Environment	❌ Plaintext keys visible	🛡️ Empty placeholders only
Prompt Injection	❌ AI can print secrets	🛡️ Agent never possesses secrets
Dependency Scraping	❌ Malicious packages can read env	🛡️ No credentials available
Authentication Scope	❌ Every process inherits credentials	🛡️ Injected only for authorized outbound requests

---

How It Works

Application
Reads:

Authorization: Bearer nv://STRIPE_KEY

            │
            │ HTTP Request
            ▼

┌──────────────────────────────────┐
│      Local nvenv Proxy           │
├──────────────────────────────────┤
│ • Intercepts outbound request    │
│ • Queries encrypted vault        │
│ • Decrypts secret in memory      │
│ • Replaces placeholder           │
│ • Continues TLS connection       │
└──────────────────────────────────┘
            │
            ▼

api.stripe.com

Receives:

Authorization: Bearer sk_live_xxxxxxxxx

---

Core Security Features

🛡️ Contextual Blindness

Your:

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

contain only placeholders such as

nv://STRIPE_KEY

Secrets never enter the LLM context window.

---

🔐 Hardware-Backed Vault

On Windows, credentials are stored inside

~/.nv/vault.db

using:

• SQLite
• Windows DPAPI encryption

Secrets are cryptographically bound to the current Windows user.

---

🔄 Active TLS Interception

The runtime launches a local loopback MITM proxy that:

• generates certificates dynamically
• intercepts outbound HTTPS
• swaps placeholders
• forwards requests transparently

Applications remain unaware of the substitution.

---

🤖 AI Agent Anti-Scraping Protection

Commands such as

nvenv get STRIPE_KEY

cannot be abused through:

• pipes
• redirected output
• automation

Protections include:

• isatty() verification
• interactive console detection
• low-level keyboard confirmation

Only a real interactive user may reveal secrets.

---

🔑 Git Credential Helper

nvenv integrates with Git using:

credential.helper

GitHub Personal Access Tokens (PATs) are injected directly into Git's authentication pipeline without storing them in:

• .gitconfig
• environment variables
• repository files

---

Installation

1. NPM Distribution

npm install -g nv-protocol

---

2. Python Distribution

pip install nv-protocol

---

3. Source Installation

Clone the repository and install locally.

pip install -e .

This registers the global CLI command:

nvenv

---

Quickstart

Step 1 — Initialize Vault

Create your encrypted credential database.

nvenv init

---

Step 2 — Store Secrets

nvenv set STRIPE_KEY

The CLI securely prompts for the value and prints a placeholder.

---

Step 3 — Replace .env

Instead of:

STRIPE_KEY=sk_live_xxxxxxxxx
DATABASE_URL=postgres://...

Use:

STRIPE_KEY=nv://STRIPE_KEY
DATABASE_URL=nv://DATABASE_URL

---

Step 4 — Run Through nvenv

Instead of launching your application directly, wrap it.

Node.js

nvenv run -- npm run dev

Python

nvenv run -- python main.py

Curl

nvenv run -- curl \
  -H "Authorization: Bearer nv://STRIPE_KEY" \
  https://httpbin.org/headers

Applications receive real credentials transparently while every visible environment still contains only placeholders.

---

Git Integration

Store your GitHub Personal Access Token.

nvenv set GITHUB_TOKEN

Configure Git.

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

Git authentication now occurs using credentials retrieved directly from the secure vault.

No tokens appear inside:

• repository files
• shell history
• environment variables

---

Verification

Run the internal test suite.

python test_nv.py

Tests include:

• ✅ Windows DPAPI encryption
• ✅ Vault CRUD operations
• ✅ Socket payload replacement
• ✅ HTTP interception
• ✅ Placeholder substitution
• ✅ End-to-end runtime verification

---

Example Workflow

Developer

│

├── Stores API Key
│      │
│      ▼
│   nvenv set STRIPE_KEY
│
├── .env
│      │
│      ▼
│ STRIPE_KEY=nv://STRIPE_KEY
│
├── Launch
│      │
│      ▼
│ nvenv run -- npm run dev
│
└──────────────► Local Proxy
                    │
                    ▼
           Placeholder Replacement
                    │
                    ▼
             External API Service

---

Philosophy

Traditional secret managers focus on protecting secrets at rest.

nvenv focuses on protecting secrets during execution, ensuring autonomous AI systems, third-party packages, and prompt injection attacks never gain access to plaintext credentials while applications continue to operate normally.

---

License

Released under the MIT License.