Skip to main content

​
Developer & Contributing Guide

Thank you for contributing to envtrap! This guide covers local repository setup, building the project, running the test suites, and extending the codebase.

​
Local Setup

1

Clone the repository

2

Install dependencies

Install development and build dependencies using pnpm:
3

Build TypeScript and hook assets

Compile the TypeScript source files and copy runtime hook assets into dist/:
4

Run unit tests

Run the complete unit test suite using Node’s native test runner:

​
Architecture & Codebase Layout

envtrap is built strictly according to Clean Architecture & SOLID principles, segregating domain logic from Node.js runtime adapters:

Domain Layer (src/domain)

  • SecretMatcher.ts: Pure substring matching gated by candidate filters.
  • ContentClamp.ts: Prevents memory exhaustion by limiting scan buffers to 1 MB.
  • DedupCache.ts: TTL-based duplicate alert throttling.
  • OutputRedactor.ts: Hash-based string redaction ([REDACTED: SHA256:...]).

MITM TLS Engine (src/mitm)

  • CertificateAuthority.ts: In-memory 2048-bit Root CA generation and per-domain certificate minting.
  • MitmServer.ts: Loopback HTTP server and proxy connection orchestrator.
  • ConnectHandler.ts: HTTPS CONNECT tunnel interception and TLS socket creation.
  • TlsInterceptor.ts: Sliding-window TLS stream scanner.

Runtime Hooks (src/hooks)

  • hooks.mjs: Node.js ESM customization hooks (resolve, load, initialize).
  • virtual/child-process.mjs: Virtual module wrapping node:child_process.
  • virtual/dns.mjs: Virtual module wrapping node:dns.
  • shared.mjs: Stack-trace parsing and caller path exclusion matching.

CLI & Orchestration (src/cli)

  • RunCommandBuilder.ts: Composition root wiring SOLID adapters to ports.
  • ChildProcessManager.ts: Process spawner and standard stream router.
  • HookMessageParser.ts: Decodes out-of-band IPC messages from runtime hooks.
  • ChildEnvBuilder.ts: Sets up child process proxy and CA environment variables.

​
Extending envtrap

​
Adding a Custom Secret Source

To load credentials from a custom store (e.g. AWS Secrets Manager, HashiCorp Vault, Doppler):
  1. Implement the ISecretSource interface located in src/ports/ISecretSource.ts:
  2. Register your implementation inside SecretSourceComposer.

​
Adding a Custom Leak Reporter

To stream leak alerts to a remote observability endpoint (e.g. Datadog, Slack, PagerDuty):
  1. Implement the ILeakReporter interface in src/reporting/ILeakReporter.ts:
  2. Register your reporter with CompositeReporter in RunCommandBuilder.ts.

​
Running Documentation Locally

To test documentation updates locally using Mintlify:
Your local documentation server will be available at http://localhost:3333.