envsitter/README.md

# envsitter

[![CI](https://github.com/boxpositron/envsitter/actions/workflows/ci.yml/badge.svg)](https://github.com/boxpositron/envsitter/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/envsitter)](https://www.npmjs.com/package/envsitter)

Safely inspect and match `.env` secrets **without ever printing values**.

Docs: https://boxpositron.github.io/envsitter/

`envsitter` is designed for LLM/agent workflows where you want to:

- List keys present in an env source (`.env` file or external provider)
- Compare a key’s value to a candidate value you provide at runtime ("outside-in")
- Do bulk matching (one candidate against many keys, or candidates-by-key)
- Produce deterministic fingerprints for comparisons/auditing
- Ask boolean questions about values (empty/prefix/suffix/regex/type-ish checks) without ever returning the value

Related: https://github.com/boxpositron/envsitter-guard — an OpenCode plugin that blocks agents/tools from reading or editing sensitive `.env*` files (preventing accidental secret leaks), while still allowing safe inspection via EnvSitter-style tools (keys + deterministic fingerprints; never values).

## Security model (what this tool does and does not do)

- Values are read in-process for comparisons, but **never returned** by the library API and **never printed** by the CLI.
- Deterministic matching uses **HMAC-SHA-256** with a local pepper.
  - This avoids publishing raw SHA-256 hashes that are easy to dictionary-guess.
- Candidate secrets should be passed via stdin (`--candidate-stdin`) to avoid shell history.
- File writes keep the target file's permission bits and go through symlinks to the real file; new env files are created with mode `0600`.

Non-goals:

- This tool is not a secret manager.
- This tool does not encrypt or relocate `.env` values; it operates on sources in-place.

## Install

```bash
npm install envsitter
```

Requires Node.js 22 or later.

Or run the CLI without installing globally:

```bash
npx envsitter keys --file .env
```

## Pepper (required for deterministic fingerprints)

`envsitter` uses a local "pepper" as the HMAC key.

Resolution order:

1. `process.env.ENVSITTER_PEPPER` (or `ENV_SITTER_PEPPER`)
2. Pepper file at `.envsitter/pepper` (auto-created if missing)

The pepper file is created with mode `0600` when possible. When envsitter creates `.envsitter/`, it also writes `.envsitter/.gitignore` (`*`), so the pepper stays out of git even if your project's `.gitignore` does not list it. An existing pepper file is never replaced: if it is empty, malformed, or unreadable, envsitter stops with an error instead of generating a new pepper (which would change every fingerprint).

## CLI usage

### Quick reference

| Command | Description |
|---------|-------------|
| `keys` | List all keys in an env file |
| `fingerprint` | Get deterministic fingerprint for a key |
| `match` | Match candidate value(s) against key(s) |
| `match-by-key` | Bulk match candidates by key |
| `scan` | Detect value shapes (JWT, URL, base64) |
| `redact` | Replace secret values in text read from stdin |
| `validate` | Check dotenv syntax |
| `copy` | Copy keys between env files |
| `format` / `reorder` | Sort and organize env files |
| `annotate` | Add comments to keys |
| `add` | Add new key (fails if exists) |
| `set` | Create or update key |
| `unset` | Set key to empty value |
| `delete` | Remove key(s) from file |

### Commands

- `keys --file <path> [--filter-regex <re>]`
- `fingerprint --file <path> --key <KEY>`
- `match --file <path> (--key <KEY> | --keys <K1,K2> | --all-keys) [--op <op>] [--candidate <value> | --candidate-stdin]`
- `match-by-key --file <path> (--candidates-json <json> | --candidates-stdin)`
- `scan --file <path> [--keys-regex <re>] [--detect jwt,url,base64]`
- `redact --file <path> [--all] [--min-length <n>]`
- `validate --file <path>`
- `copy --from <path> --to <path> [--keys <K1,K2>] [--include-regex <re>] [--exclude-regex <re>] [--rename <A=B,C=D>] [--on-conflict error|skip|overwrite] [--write]`
- `format --file <path> [--mode sections|global] [--sort alpha|none] [--write]`
- `reorder --file <path> [--mode sections|global] [--sort alpha|none] [--write]`
- `annotate --file <path> --key <KEY> --comment <text> [--line <n>] [--write]`
- `add --file <path> --key <KEY> [--value <v> | --value-stdin] [--write]`
- `set --file <path> --key <KEY> [--value <v> | --value-stdin] [--write]`
- `unset --file <path> --key <KEY> [--write]`
- `delete --file <path> (--key <KEY> | --keys <K1,K2>) [--write]`

Notes for file operations:

- Commands that modify files (`copy`, `format`/`reorder`, `annotate`, `add`, `set`, `unset`, `delete`) are dry-run unless `--write` is provided.
- These commands never print secret values; output includes keys, booleans, and line numbers only.
- When targeting example files (`.env.example`, `.env.sample`, `.env.template`, `.env.dist`, `.env.default`), a warning is emitted. Use `--no-example-warning` to suppress.
- Non-standard env file names are fully supported (e.g., `api.env`, `database.env`, `config.env.local`).
- Values with special characters (spaces, `#`, quotes, newlines) are automatically double-quoted with proper escaping.

### List keys

```bash
envsitter keys --file .env
```

Filter by key name (regex):

```bash
envsitter keys --file .env --filter-regex "/(KEY|TOKEN|SECRET)/i"
```

### Fingerprint a single key

```bash
envsitter fingerprint --file .env --key OPENAI_API_KEY
```

Outputs JSON containing the key’s fingerprint and metadata (never the value).

### Match a candidate against a single key (recommended via stdin)

```bash
node -e "process.stdout.write('candidate-secret')" \
  | envsitter match --file .env --key OPENAI_API_KEY --candidate-stdin --json
```

Exit codes:

- `0` match found
- `1` no match
- `2` error/usage

### Match operators (for humans)

`envsitter match` supports an `--op` flag.

- Default: `--op is_equal`
- When `--op is_equal` is used, EnvSitter hashes both the candidate and stored value with the local pepper (HMAC-SHA-256) and compares digests using constant-time equality.
- Other operators evaluate against the raw value in-process, but still only return booleans/match results (no values are returned or printed).

Operators:

- `exists`: key is present in the source (no candidate required)
- `is_empty`: value is exactly empty string (no candidate required)
- `is_equal`: deterministic match against a candidate value (candidate required)
- `partial_match_prefix`: `value.startsWith(candidate)` (candidate required)
- `partial_match_suffix`: `value.endsWith(candidate)` (candidate required)
- `partial_match_regex`: regex test against value (candidate required; candidate is a regex like `"/^sk-/"` or a raw regex body)
- `is_number`: value parses as a finite number (no candidate required)
- `is_boolean`: value is `true`/`false` (case-insensitive, whitespace-trimmed) (no candidate required)
- `is_string`: value is neither `is_number` nor `is_boolean` (no candidate required)

Examples:

```bash
# Prefix match
node -e "process.stdout.write('sk-')" \
  | envsitter match --file .env --key OPENAI_API_KEY --op partial_match_prefix --candidate-stdin

# Regex match (regex literal syntax)
node -e "process.stdout.write('/^sk-[a-z]+-/i')" \
  | envsitter match --file .env --key OPENAI_API_KEY --op partial_match_regex --candidate-stdin

# Exists (no candidate)
envsitter match --file .env --key OPENAI_API_KEY --op exists --json
```

### Match one candidate against multiple keys

```bash
node -e "process.stdout.write('candidate-secret')" \
  | envsitter match --file .env --keys OPENAI_API_KEY,ANTHROPIC_API_KEY --candidate-stdin --json
```

### Match one candidate against all keys

```bash
node -e "process.stdout.write('candidate-secret')" \
  | envsitter match --file .env --all-keys --candidate-stdin --json
```

### Match candidates-by-key (bulk assignment)

Provide a JSON object mapping key -> candidate value.

```bash
envsitter match-by-key --file .env \
  --candidates-json '{"OPENAI_API_KEY":"sk-...","ANTHROPIC_API_KEY":"sk-..."}'
```

For safer input, pass the JSON via stdin:

```bash
cat candidates.json | envsitter match-by-key --file .env --candidates-stdin
```

### Scan for value shapes (no values returned)

```bash
envsitter scan --file .env --detect jwt,url,base64
```

Optionally restrict which keys to scan:

```bash
envsitter scan --file .env --keys-regex "/(JWT|URL)/" --detect jwt,url
```

### Redact secret values from text

Replace secret values in any text (logs, command output, support bundles) before sharing it. `redact` reads stdin, writes the text to stdout with each value replaced by `[envsitter: KEY redacted]`, and reports counts per key on stderr (or in the output with `--json`):

```bash
envsitter redact --file .env < app.log > app.redacted.log
envsitter redact --file .env --json < app.log
```

A value is redacted when it is at least 8 characters long, is not a plain number or boolean, and looks secret: its key name contains a word such as `TOKEN`, `SECRET`, `PASSWORD`, or `API_KEY`; it is shaped like a random token; it is a URL with a password (the bare password is redacted too); or it is a PEM block. Ordinary config such as `NODE_ENV=development` is left alone. `--all` redacts every value, and `--min-length <n>` changes the length floor. Encoded or transformed values (base64, split strings) are not detected.

### Validate dotenv syntax

```bash
envsitter validate --file .env
envsitter validate --file .env --json
```

### Copy keys between env files (production → staging)

Dry-run (no file is modified):

```bash
envsitter copy --from .env.production --to .env.staging --keys API_URL,REDIS_URL --json
```

Apply changes:

```bash
envsitter copy --from .env.production --to .env.staging --keys API_URL,REDIS_URL --on-conflict overwrite --write --json
```

Rename while copying:

```bash
envsitter copy --from .env.production --to .env.staging --keys DATABASE_URL --rename DATABASE_URL=STAGING_DATABASE_URL --write
```

### Annotate keys with comments

```bash
envsitter annotate --file .env --key DATABASE_URL --comment "prod only" --write
```

### Reorder/format env files

```bash
envsitter format --file .env --mode sections --sort alpha --write
# alias:
envsitter reorder --file .env --mode sections --sort alpha --write
```

### Add a new key (fails if key exists)

```bash
envsitter add --file .env --key NEW_API_KEY --value "sk-xxx" --write
# or via stdin (recommended to avoid shell history):
node -e "process.stdout.write('sk-xxx')" | envsitter add --file .env --key NEW_API_KEY --value-stdin --write
```

### Set a key (creates or updates)

```bash
envsitter set --file .env --key API_KEY --value "new-value" --write
# or via stdin:
node -e "process.stdout.write('new-value')" | envsitter set --file .env --key API_KEY --value-stdin --write
```

### Unset a key (set to empty value)

```bash
envsitter unset --file .env --key OLD_KEY --write
```

### Delete keys

```bash
# Single key:
envsitter delete --file .env --key DEPRECATED_KEY --write

# Multiple keys:
envsitter delete --file .env --keys OLD_KEY,UNUSED_KEY,LEGACY_KEY --write
```

## Output contract (for LLMs)

General rules:

- Never output secret values; treat all values as sensitive.
- Prefer `--candidate-stdin` over `--candidate` to avoid shell history.
- Exit codes: `0` match found, `1` no match, `2` error/usage.

JSON outputs:

- `keys --json` -> `{ "keys": string[] }`
- `fingerprint` -> `{ "key": string, "algorithm": "hmac-sha256", "fingerprint": string, "length": number, "pepperSource": "env"|"file", "pepperFilePath"?: string }`
- `match --json` (single key) ->
  - default op (not provided): `{ "key": string, "match": boolean }`
  - with `--op`: `{ "key": string, "op": string, "match": boolean }`
- `match --json` (bulk keys / all keys) ->
  - default op (not provided): `{ "matches": Array<{ "key": string, "match": boolean }> }`
  - with `--op`: `{ "op": string, "matches": Array<{ "key": string, "match": boolean }> }`
- `match-by-key --json` -> `{ "matches": Array<{ "key": string, "match": boolean }> }`
- `scan --json` -> `{ "findings": Array<{ "key": string, "detections": Array<"jwt"|"url"|"base64"> }> }`
- `validate --json` -> `{ "file": string, "ok": boolean, "issues": Array<{ "line": number, "column": number, "message": string }> }`
- `copy --json` -> `{ "from": string, "to": string, "onConflict": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": Array<...> }`
- `format --json` / `reorder --json` -> `{ "file": string, "mode": string, "sort": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...> }`
- `annotate --json` -> `{ "file": string, "key": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": { ... } }`
- `add --json` / `set --json` / `unset --json` -> `{ "file": string, "key": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": { "key": string, "action": "added"|"updated"|"unset"|"key_exists"|"not_found"|"no_change", "line"?: number } }`
- `delete --json` -> `{ "file": string, "keys": string[], "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": Array<{ "key": string, "action": "deleted"|"not_found", "line"?: number }> }`

## Library API

### Basic usage

```ts
import { EnvSitter } from 'envsitter';

const es = EnvSitter.fromDotenvFile('.env');

const keys = await es.listKeys();
const fp = await es.fingerprintKey('OPENAI_API_KEY');
const match = await es.matchCandidate('OPENAI_API_KEY', 'candidate-secret');
```

### File operations via the library

```ts
import {
  addEnvFileKey,
  annotateEnvFile,
  copyEnvFileKeys,
  deleteEnvFileKeys,
  formatEnvFile,
  setEnvFileKey,
  unsetEnvFileKey,
  validateEnvFile
} from 'envsitter';

await validateEnvFile('.env');

await copyEnvFileKeys({
  from: '.env.production',
  to: '.env.staging',
  keys: ['API_URL', 'REDIS_URL'],
  onConflict: 'overwrite',
  write: true
});

await annotateEnvFile({ file: '.env', key: 'DATABASE_URL', comment: 'prod only', write: true });
await formatEnvFile({ file: '.env', mode: 'sections', sort: 'alpha', write: true });

// Add a new key (fails if exists)
await addEnvFileKey({ file: '.env', key: 'NEW_KEY', value: 'new_value', write: true });

// Set a key (creates or updates)
await setEnvFileKey({ file: '.env', key: 'API_KEY', value: 'updated_value', write: true });

// Unset a key (set to empty)
await unsetEnvFileKey({ file: '.env', key: 'OLD_KEY', write: true });

// Delete keys
await deleteEnvFileKeys({ file: '.env', keys: ['DEPRECATED', 'UNUSED'], write: true });
```

### Utility functions

```ts
import { isEnvFile, isEnvSitterPepperFile, isExampleEnvFile, isSensitiveEnvFile } from 'envsitter';

// Dotenv-style file names (any directory, POSIX or Windows separators)
isEnvFile('.env.local');               // true
isEnvFile('config.env.local');         // true
isEnvFile('app.env.ts');               // false (source file)

// Detect example/template env files
isExampleEnvFile('.env.example');      // true
isExampleEnvFile('api.env.sample');    // true
isExampleEnvFile('.env');              // false

// Env files that may hold real values (every env file except examples/templates)
isSensitiveEnvFile('.env.production'); // true
isSensitiveEnvFile('.env.example');    // false

// The default pepper location
isEnvSitterPepperFile('.envsitter/pepper'); // true
```

`envsitter-guard` uses `isSensitiveEnvFile` and `isEnvSitterPepperFile` to decide what agents may not read or edit.

### Match operators via the library

```ts
import { EnvSitter } from 'envsitter';
import type { EnvSitterMatcher } from 'envsitter';

const es = EnvSitter.fromDotenvFile('.env');

const matcher: EnvSitterMatcher = { op: 'partial_match_prefix', prefix: 'sk-' };
const ok = await es.matchKey('OPENAI_API_KEY', matcher);
```

### Bulk matching

```ts
import { EnvSitter } from 'envsitter';

const es = EnvSitter.fromDotenvFile('.env');

// One candidate tested against a set of keys
const matches = await es.matchCandidateBulk(['OPENAI_API_KEY', 'ANTHROPIC_API_KEY'], 'candidate-secret');

// One matcher tested against a set of keys
const prefixMatches = await es.matchKeyBulk(['OPENAI_API_KEY', 'ANTHROPIC_API_KEY'], { op: 'partial_match_prefix', prefix: 'sk-' });

// Candidates-by-key
const byKey = await es.matchCandidatesByKey({
  OPENAI_API_KEY: 'sk-...',
  ANTHROPIC_API_KEY: 'sk-...'
});
```

### External sources (hooks)

You can load dotenv-formatted output from another tool/secret provider:

```ts
import { EnvSitter } from 'envsitter';

const es = EnvSitter.fromExternalCommand('my-secret-provider', ['export', '--format=dotenv']);
const keys = await es.listKeys();
```

### Redact secret values

```ts
import { EnvSitter } from 'envsitter';

const redactor = await EnvSitter.fromDotenvFile('.env').redactor();
const { text, redactions } = redactor.redact(logOutput);
// text has each secret value replaced by [envsitter: KEY redacted]; redactions is [{ key, count }]
```

`redactor.keys` lists the keys it covers, and the values never leave the redactor. Options: `{ all?: boolean; minLength?: number }`, with the same rules as the `redact` command.

## Development

```bash
npm install
npm run typecheck
npm test
```

Run a single test file:

```bash
npm run build
node --test dist/test/envsitter.test.js
```

Run a single test by name:

```bash
npm run build
node --test --test-name-pattern "outside-in" dist/test/envsitter.test.js
```

## Releasing

Releases are published by GitHub Actions with npm trusted publishing, so no npm token is stored anywhere and every version ships with a provenance attestation.

1. Bump `version` in `package.json` and replace `(Unreleased)` in the matching `CHANGELOG.md` heading with the release date.
2. Commit, then push a matching tag: `git tag v0.1.0 && git push origin main v0.1.0`.
3. The Release workflow reruns CI, checks that the tag, `package.json`, and the CHANGELOG agree, publishes to npm (prereleases such as `v0.2.0-beta.1` go to the `next` dist-tag), and creates the GitHub Release from the CHANGELOG section.

The docs site in `site/` deploys to GitHub Pages on every push to `main` that changes it.

## License

MIT. See `LICENSE`.