🛡️ envguard

Zero-Trust environment variable validation, AST-level framework leak prevention, Shannon Entropy secret scanning, and environment drift detection for modern full-stack architectures.

Scan and validate your repository instantly with zero dependencies or configuration:

# Zero-install check (runs AST scanner, client-leak guard, and entropy analysis)
npx envguard check

(Alternatively via scoped package: npx @latrye/envguard check)

# npm
npm install -D @latrye/envguard

# pnpm
pnpm add -D @latrye/envguard

# yarn
yarn add -D @latrye/envguard

envguard is the enterprise-grade Zero-Trust environment variable validation and secret intelligence engine. It combines TypeScript Compiler API AST traversal, Character-Set Normalized Shannon Entropy classifier, framework-aware client-side leak prevention (Next.js, Vite, Remix, Nuxt, SvelteKit), Language Server Protocol (LSP) in-IDE diagnostics, and resilient Vault synchronization with circuit breakers.

EnvGuard provides a first-class editor extension (packages/vscode-extension/) bringing real-time zero-trust security feedback directly into your coding workflow:

• 🔍 Real-Time In-IDE Diagnostics: Instant red squiggly underlines on client-side secret leaks ('use client', Vite src/, Nuxt pages/), unquoted values, or missing variables across .env, .ts, .tsx, .vue, and .svelte files.
• 💡 One-Click Quick-Fix Actions:
  • Automatically add required prefixes (NEXT_PUBLIC_, VITE_, NUXT_PUBLIC_, PUBLIC_) to variables used in client bundles.
  • Automatically append undocumented variables to .env.example with type annotations and safe placeholders.
  • Move hardcoded secrets directly into .env.
• 💬 Hover Tooltips with Type & Entropy Intelligence: Hover over any process.env.VARIABLE to view inferred semantic type, required/optional status, default value, and Shannon entropy rating.
• 📊 Status Bar Health Monitor: Live widget displaying workspace environment synchronization health ($(shield) EnvGuard: OK or $(error) EnvGuard: 2 errors).

Install the extension from the VS Code Marketplace or build locally:

npm run package:extension
code --install-extension vscode-envguard.vsix

EnvGuard performs pre-compile AST boundary analysis before JavaScript code ever reaches bundling, packaging, or deployment:

flowchart TD
    subgraph SOURCETREE["📁 Source Code & Configuration Tree"]
        SRC["Codebase (.ts, .tsx, .vue, .svelte, .py, .go)"]
        ENV[".env / .env.production"]
        EXAMPLE[".env.example (Typed Schema)"]
        VAULT["Cloud Secrets Vault (AWS / Vault / Doppler)"]
    end

    subgraph ENGINE["🛡️ EnvGuard Core Security Engine"]
        direction TB
        AST["1. TypeScript Compiler API AST Scanner<br/><i>(Direct, Destructured, Aliased, Dynamic Keys)</i>"]
        BOUND["2. Framework Boundary Leak Guard<br/><i>('use client', VITE_, PUBLIC_, Nuxt, Remix)</i>"]
        ENTROPY["3. Charset-Normalized Shannon Entropy<br/><i>(Composite Confidence Scoring + Negative Corpus)</i>"]
        DRIFT["4. Environment Drift Watchdog<br/><i>(Runtime process.env vs Schema Divergence)</i>"]
        RESILIENCE["5. Resilient Sync & Circuit Breaker<br/><i>(Exponential Backoff + In-Memory Masking)</i>"]
    end

    subgraph OUTPUTS["📊 Enterprise Reports & Integrations"]
        SARIF["SARIF 2.1.0 (GitHub Code Scanning Tab)"]
        LSP["Language Server Protocol (VSCode / Cursor Extension)"]
        CLI_OUT["Terminal UI / GitHub PR Review Comment"]
        SYNC_OUT[".env.example Auto-Synchronizer & Formatter"]
    end

    SRC --> AST
    AST --> BOUND
    ENV --> ENTROPY
    EXAMPLE --> DRIFT
    VAULT --> RESILIENCE

    BOUND --> SARIF
    ENTROPY --> SARIF
    DRIFT --> CLI_OUT
    BOUND --> LSP
    ENTROPY --> LSP
    DRIFT --> LSP
    RESILIENCE --> SYNC_OUT
    BOUND --> CLI_OUT
    ENTROPY --> CLI_OUT

Add EnvGuard to your GitHub Actions workflow to upload real-time security alerts directly to the GitHub Security -> Code Scanning (SARIF) dashboard:

name: Security & Environment Scan
on: [push, pull_request]

jobs:
  envguard-security:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx @latrye/envguard --format sarif > envguard.sarif || true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: envguard.sarif

Block committed secrets and framework leaks before they leave local machines:

# Install native Git pre-commit hook in 1 click
npx @latrye/envguard hook install

Or configure inside .pre-commit-config.yaml:

repos:
  - repo: https://github.com/latryee/envguard
    rev: v1.0.0
    hooks:
      - id: envguard
        args: ["--staged", "--strict"]

EnvGuard traverses the official TypeScript Compiler API AST to trace static, destructured, aliased, and dynamic variable accesses:

// 1. Direct access
const secret = process.env.STRIPE_SECRET_KEY;

// 2. Destructured access & nested destructuring
const { DB_PASS: password, nested: { DEEP_KEY } } = process.env;

// 3. Aliased environment wrappers
const env = process.env;
const apiKey = env.OPENAI_API_KEY;

// 4. Computed / Dynamic keys
const dynamicToken = process.env['AUTH_' + mode];

• Next.js: Detects client components marked with 'use client' or inside components//hooks/. Blocks private variables lacking the NEXT_PUBLIC_ prefix.
• Vite: Blocks non-VITE_ server secrets in src/**/*.{tsx,jsx,vue,svelte} client bundles.
• Remix: Blocks private server secrets in .client.tsx and route client bundles lacking REMIX_PUBLIC_ or PUBLIC_.
• Nuxt: Enforces NUXT_PUBLIC_ prefix rules for pages and components outside server/.
• SvelteKit: Enforces PUBLIC_ prefixes across src/routes/ and client $lib endpoints.

EnvGuard calculates Character-Set Normalized Shannon Entropy:

$$H = -\sum_{i=1}^n P(x_i) \log_2(P(x_i))$$

$$H_{\text{normalized}} = \frac{H}{\log_2(|\Sigma_{\text{detected}}|)}$$

• Detected Character Sets: Hex ($|\Sigma|=16$, $H_{\max}=4.0$), Alphanumeric ($|\Sigma|=62$, $H_{\max}\approx 5.95$), Base64 ($|\Sigma|=64$, $H_{\max}=6.0$), ASCII ($|\Sigma|=256$, $H_{\max}=8.0$).
• Composite Confidence Scoring (0.0 to 1.0):
  1. High-precision rule matchers (AWS, OpenAI, Anthropic, GCP, Stripe, GitHub, Slack, SSH Keys).
  2. Character-set normalized entropy verification.
  3. Semantic variable naming heuristics (*_KEY, *_SECRET, *_AUTH, *_TOKEN, *_PASS, *_PRIVATE).
  4. Negative-Corpus Whitelist: Filters out UUIDs, pure Git commit SHA hashes, build asset chunk filenames (chunk-*.js), URLs, and dummy test tokens to maintain a 0.00% False-Positive Rate.

import { watchEnvironmentDrift, formatDriftReport, ResilientExecutor } from '@latrye/envguard';

// 1. Live Environment Drift Watchdog
const report = watchEnvironmentDrift({
  runtimeEnv: process.env,
  exampleContent: fs.readFileSync('.env.example', 'utf8'),
  strict: true
});

console.log(formatDriftReport(report, 'markdown'));

• Resilient Circuit Breaker: Exponential backoff with Full Jitter ($T = \text{random}(0, \min(T_{\max}, T_{\text{initial}} \times 2^{\text{attempt}}))$) across AWS Secrets Manager, HashiCorp Vault, and Doppler.
• Strict In-Memory Masking: Automatically redacts sensitive tokens, keys, and credentials from logs, stack traces, and unhandled exception dumps.

EnvGuard generates standard OASIS SARIF 2.1.0 and Language Server Protocol (LSP) diagnostic items for instant editor squiggly feedback:

import { computeEnvDiff, generateLspDiagnostics } from '@latrye/envguard';

const diff = computeEnvDiff({ envAst, exampleAst, codeKeys });
const lspMap = generateLspDiagnostics(diff);

// Dispatch diagnostics to IDE language server client
for (const [uri, diagnostics] of lspMap.entries()) {
  connection.sendDiagnostics({ uri, diagnostics });
}

Replace dotenv with envguard for zero-overhead loading, variable expansion, and startup type enforcement:

import { loadEnv } from '@latrye/envguard';

// Automatically loads .env, expands ${PORT} variables, and validates types against .env.example
loadEnv({ strict: true });

# CommonJS
node -r @latrye/envguard/register app.js

# ES Modules
node --import @latrye/envguard/register app.js

MIT © latrye