Development Guide

Set up the envtrap development environment and contribute to the project.

Clone the Repository

git clone https://github.com/Vishal-770/envtrap.git
cd envtrap

Install Dependencies

envtrap uses pnpm workspace features:

pnpm install

Project Structure

The project is structured as a pnpm monorepo:

envtrap/
├── package/          # Core envtrap security agent npm package
│   ├── src/          # TypeScript source code
│   │   ├── index.ts      # CLI entry point: commander commands, secret loader, child spawner
│   │   ├── hooks.mjs     # ESM customization hooks & CommonJS Module.prototype.require patch
│   │   ├── config.ts     # envtrap.json schema validator, loader, and deepMerge logic
│   │   ├── types.ts      # Shared TypeScript interfaces (Secret, LeakEvent, ScanResult, etc.)
│   │   ├── ca.ts         # In-memory 2048-bit RSA Root CA (node-forge), OS trust store inject/remove
│   │   ├── proxy.ts      # MITM TLS HTTP/HTTPS proxy server (127.0.0.1, random port)
│   │   ├── scanner.ts    # Stateful scan engine: 1MB clamp, 1.5s TTL dedup cache, block routing
│   │   ├── fingerprint.ts# looksLikeSecret gate, shannonEntropy, scanContent, formatNetworkContext
│   │   └── reporter.ts   # Terminal output: chalk alerts, run summary, JSONL log writer
│   └── dist/         # Compiled JS and copied ESM hooks
├── test-server/      # Integration test suite (Express web app + mock TLS server)
│   └── test/
│       └── integration.test.js # Comprehensive test runner
├── landing-page/     # Next.js product landing page
└── docs/             # Mintlify documentation (you are here)

Building

To compile the TypeScript package source and copy raw ESM customization hooks to dist:

cd package
pnpm run build

Running Tests

Integration tests verify interceptors under real process spawns, CommonJS imports, ESM loader injections, and network MITM proxied connections.

First, ensure the package is built, then run tests in the test-server folder:

# Build the agent package
cd package && pnpm run build

# Run the integration test suite
cd ../test-server
pnpm test

Running the Landing Page Locally

cd landing-page
pnpm dev

The site will be available at http://localhost:3000.

Running the Docs Locally

Install the Mintlify CLI:

npm install -g mintlify

Then start the dev server from the docs/ directory:

cd docs
mintlify dev

The docs will be available at http://localhost:3000.

Architecture Overview

If you want to contribute to the code:

1. CLI Commands and Spawner: Handle flags and set up proxy/hooks environments in package/src/index.ts.
2. ESM loader/CJS patches: Any changes to intercepted hooks for node:dns or node:child_process go in package/src/hooks.mjs.
3. MITM HTTPS Decryption: The proxy handling and response blocking go in package/src/proxy.ts.
4. Secret Scanning: The candidate filter and entropy logic go in package/src/fingerprint.ts.

Submitting a PR

1. Fork the repository
2. Create a branch: git checkout -b feat/my-feature
3. Make your changes and add tests in test-server/test/integration.test.js
4. Verify tests pass with pnpm test
5. Submit a pull request with a clear description