Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -1020,6 +1020,12 @@ For hosts without hook support, the docs MUST state the protection tier plainly
and its tier; `envseal init --host cursor` on a clean fixture produces a `.cursor/mcp.json` that a
schema test validates.

**Shipped in v0.1.5:** `init` always merges Layer 1 `AGENTS.md`, then writes **every** matching
project host config (not first-wins). Launch is `npx -y @envseal/mcp-server` (`npx.cmd` on
Windows), never a bare `envseal-mcp` on PATH and never `$HOME` MCP. `--host` is a write
escape hatch, not a fake protection tier. Doctor fail-closes when the primary host’s MCP
is unwired. Detection does not inventory IDEs under `$HOME`.

### T10.2 — Spec publication
Copy Part I into `spec/sep-1/SPEC.md` with a conformance section: an implementation is SEP/1
conformant if it implements the seven tools, never returns values, and passes the published
Expand Down
23 changes: 14 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,17 +72,22 @@ For a runnable walk-through of the whole lifecycle (`init` → `ensure --check`

## Connect your agent

Provisioning keys is only half of it: your agent asks for them through the broker, so the host has to be able to start the broker. For Claude Code, create `.mcp.json` at the project root:

```json
{
"mcpServers": {
"envseal-mcp": { "command": "envseal-mcp", "args": [] }
}
}
Provisioning keys is only half of it: your agent asks for them through the broker, so the host has to be able to start the broker.

```bash
npm install -D @envseal/cli
npx envseal init
```

Restart Claude Code afterwards. Copy-pasteable snippets for Cursor, Zed, Codex, Continue and the other hosts are in [docs/hosts/README.md](docs/hosts/README.md); installing the bundled plugin in `plugins/claude-code` on top of the MCP server is what earns tier A.
`init` always merges Layer 1 instructions into project-root `AGENTS.md` (any agent that reads instruction files can then run `envseal ensure` / `envseal run --` instead of asking for a paste). If this repo has project-local host markers (`.cursor/`, `.claude/`, …), or you ran the command from that IDE, it also writes the **project** MCP (or equivalent) config so the agent gets `env_declare` / `env_request` / `env_await` / `env_verify` / `env_use`. A repo used from Cursor and Claude Code gets both `.cursor/mcp.json` and `.mcp.json`. `init` does not scan `$HOME` or wire every IDE on the machine.

Launch is `npx -y @envseal/mcp-server` (`npx.cmd` on Windows). Host MCP launchers do not search `node_modules/.bin`, so a bare `envseal-mcp` command will not start. Project MCP already has the workspace as cwd — `--project` is not baked into committed files.

Do **not** put envseal in `~/.cursor/mcp.json` (or other user-global MCP files) as the default: those processes often start with `cwd` = `$HOME`, and `envseal-mcp` then exits `no project found`. If detection cannot see the IDE (bare terminal on an empty tree), `init` writes `AGENTS.md` only and prints: re-run from the IDE, or `envseal init --host cursor`.

Reload MCP / restart the host, then `envseal doctor`. Doctor fails if an MCP-capable host’s project folder exists but `envseal-mcp` is not actually configured.

Claude Code: `init` = protocol connected (Tier B via `.mcp.json`). Install `plugins/claude-code` for Tier A hooks. Snippets for every host: [docs/hosts/README.md](docs/hosts/README.md).

## Works with any agent

Expand Down
1 change: 1 addition & 0 deletions VERIFICATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,7 @@ what cannot be is listed as a runbook step, not claimed.
| **E9** W4 adversarial battle-test (2026-08-25) | **PASS — 0 Critical open; 4 findings fixed and shipped in v0.1.2; 2 reclassified as correct behavior.** | ~55 scenarios across 9 phases against published v0.1.1 artifacts (`docs/verification/W4-battle-test.md`, probes in `.commandcode/probe-w4-p*.mjs`). Redaction engine unbeaten: raw/stderr/multi-secret/10MB-volume all redacted, audit never holds values, MCP server survived malformed frames + floods with zero failures, plugin deny matrix held incl. traversal paths, host-detection precedence held under fake-HOME. Fixed in v0.1.2 (23bedc0): **F2 High** ensure/set hang forever non-TTY → fail closed exit 4 in ~300ms; **F5 Med** detector missed sk-live-/bare-sk- OpenAI shapes → patterns added; **F1 Med** init laundered hostile pre-existing manifests → guard scan on read path; **F4 Low** missing-manifest run now warns on stderr. F6 (audit recreation) proven correct behavior; F3 (keychain sink) proven probe artifact — set honors declared sink end-to-end. Registry proof: v0.1.2 published with SLSA v1 provenance ([release run](https://github.com/NDilanka/envseal/actions/runs/32756572088)), clean-dir smoke green. Known documented boundaries: grandchild-process stdout not intercepted (broker-spawned direct stdio only); transformed encodings inside child output are out of literal-match scope by design. |
| **E10** External-review fix + same-class audit sweep → v0.1.3 (2026-08-25) | **PASS — reviewer's finding fixed; 2-round audit complete; every finding fixed; released and registry-verified.** | External X review found `env_use` consent bound to displayed argv, not target content. Fixed (3a1d920): every argument naming a readable file SHA-256 fingerprinted before the dialog (fingerprints shown in it) and re-hashed immediately pre-spawn; mismatch → new `SEP_TARGET_CHANGED`, nothing executes, nothing cached. Proven by tests incl. mutation-between-approval-and-spawn refusal and settle-then-reprompt. Same-class audit (2 time-boxed subagents, findings verified against source before fixing) then closed in 711e7ff: hook denylist bypasses (wrapper/path-prefix readers, mid-command `< file` redirects, glob suffixes, printf/declare-p/here-string var leaks — with a fail-open regression caught by a 31-payload probe of the built bundle, now pinned in `.commandcode/probe-audit-fixes.mjs`); detector suppression buckets hardened (digest charset+length floors so `sha256:` labels can't hide sk-keys, SRI-shape required after `integrity=`, data-URI MIME/base64 validation, path bucket needs real path structure, URL bucket refuses credential-shaped query params); consent surfaces unified on shared `core/display.ts` with bidi/unicode-separator escaping (twins byte-identical again), loopback links show destination host, TEST_MODE stub announces every answered key, no-TTY error no longer advertises the ASSUME_YES bypass. Gates: full monorepo suite green, build/typecheck/lint clean on tracked code, plugin contract 165/165, detector 44/44. Release run [32815056545](https://github.com/NDilanka/envseal/actions/runs/32815056545) green incl. publish; all 9 packages live at 0.1.3 with SLSA v1 provenance; clean-machine smoke on the published artifact: install (108 pkgs) → `envseal version 0.1.3` → shipped `core/dist/display.js` present → status shows key present with fingerprint → `env_use` injects and child output returns `«redacted:PROBE_KEY»`, `redactedCount: 1`. |
| **E11** Security hardening review → v0.1.4 (2026-08-25) | **PASS — released and registry-verified.** | Whole-repo review findings landed in [PR #1](https://github.com/NDilanka/envseal/pull/1) (`fa80cff`). Lockstep bump `0.1.3` → `0.1.4`. Release run [32848761172](https://github.com/NDilanka/envseal/actions/runs/32848761172) published all 9 `@envseal/*` packages; `@envseal/cli@0.1.4` is `latest` with SLSA v1 provenance. Residuals unchanged: Darwin keychain argv, hook fail-open default, MCP stdio host-trust. |
| **E12** Init host wiring (T10.1) → v0.1.5 (2026-08-25) | **PASS — implementation + docs; registry pending tag.** | `envseal init` always merges Layer 1 `AGENTS.md` and writes project-scoped MCP (`npx -y @envseal/mcp-server`, `npx.cmd` on Windows) for every matching project marker or `--host`. Does not crawl `$HOME`. Doctor fail-closes on unwired MCP / missing instructions (`agentWiring`). `--host` is a write override, not a fake protection tier. Lockstep bump `0.1.4` → `0.1.5`. Release run TBD until tag `v0.1.5` publishes. |


Launch is authorised only when every row is filled with recorded evidence.
76 changes: 59 additions & 17 deletions docs/cli-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,30 +28,54 @@ The one way to proceed headlessly is `envseal run`'s own confirmation bypass: `-

### `envseal init [--host <name>]`

Initialize `env.schema.jsonc` at the project root.
Initialize `env.schema.jsonc` at the project root, merge Layer 1 `AGENTS.md`,
and write project host config for every matching marker (or `--host`).

**Flags:**
- `--host <name>` — Override host detection. Valid values: `claude-code`, `cursor`, `continue`, `aider`, `windsurf`, `cline`, `zed`, `codex`, `jetbrains`, `goose`, `copilot`, `generic`, `unknown`; anything else is rejected with exit 2. When an override is given, the reported tier is what that host id implies, not evidence about this project — `envseal doctor` reports what is actually detected.
- `--host <name>` — Write this host's project config (comma-separated ok). Valid values: `claude-code`, `cursor`, `continue`, `aider`, `windsurf`, `cline`, `zed`, `codex`, `jetbrains`, `goose`, `copilot`, `generic`, `unknown`, `openhands`; anything else is rejected with exit 2. `--host` selects files to write; `protectionTier` in the output is evidence-based (`detectHost` after write), not a fake tier from the flag. `envseal doctor` reports detected protection.
- `--json` — Output as JSON.
- `--project <path>` — Project root (default: auto-detect).

`init` always merges `plugins/generic/AGENTS.md` into project-root `AGENTS.md`
(create or append; never clobbers unrelated content). It then writes each
matching **project** config (`.cursor/mcp.json`, `.mcp.json`, …) using
`npx -y @envseal/mcp-server` (`npx.cmd` on Windows). It never writes
`~/.cursor/mcp.json` or other `$HOME` configs. With no project markers and no
IDE process env, it writes `AGENTS.md` only.

**JSON output:**
```json
{
"manifestPath": "/path/to/env.schema.jsonc",
"host": "claude-code",
"protectionTier": "C",
"host": "cursor",
"protectionTier": "B",
"requestedHosts": ["cursor"],
"wiredHosts": ["cursor"],
"wiringSource": "flag",
"scanned": 14,
"added": ["OPENAI_API_KEY"],
"updated": [],
"unchanged": [],
"secretKeys": ["OPENAI_API_KEY"],
"configKeys": [],
"entries": 1
"entries": 1,
"agentsMd": { "action": "created", "path": "/path/to/AGENTS.md" },
"hostWiring": [
{ "id": "cursor", "action": "created", "path": "/path/to/.cursor/mcp.json" }
],
"cursorWiring": {
"mcp": "created",
"rules": "created",
"mcpPath": "/path/to/.cursor/mcp.json",
"rulesPath": "/path/to/.cursor/rules/envseal.mdc"
}
}
```

`host` is the detected host id (`"unknown"` when nothing matched); `protectionTier` is `"A"`, `"B"`, or `"C"`; `scanned` is the number of files scanned; `added`/`updated`/`unchanged` list the manifest entries by outcome; `secretKeys`/`configKeys` split the declared keys by their `secret` flag; `entries` is the total entry count.
`host` / `protectionTier` are from detection after write. `wiringSource` is
`"project"` | `"process"` | `"flag"` | `"none"`. `requestedHosts` is present
only when `wiringSource` is `"flag"`. `wiredHosts` / `hostWiring` list what
Layer 2 wrote. On Cursor, `cursorWiring` still reports `{ mcp, rules, mcpPath, rulesPath }` (`created` / `merged` / `unchanged` / `skipped`).

**Exit codes:** Always 0 on success.

Expand Down Expand Up @@ -262,7 +286,9 @@ envseal run -- npm test

### `envseal doctor`

Audit the project configuration. Reports: project root, manifest path, detected host + tier + recommendation, gitignore coverage, file permissions, count of missing required keys.
Audit the project configuration. Reports: project root, manifest path, detected host + tier + recommendation, **agent wiring** (MCP + Layer 1 `AGENTS.md`), gitignore coverage (ignore-rule semantics, not substring match), `.env` tracked/permissions, `hookFailClosed`, count of missing required keys.

Folder presence is not wiring. For the detected **primary** host, doctor checks the project config `init` would have written. An empty `.cursor/mcp.json` `mcpServers` map is unwired (exit 1). Continue and Goose are **not OOTB** (print-only MCP).

With no `env.schema.jsonc` in the project there is nothing to audit: `doctor`
fails with `SEP_NOT_DECLARED` and exit 2 (same as `ensure`) instead of printing
Expand All @@ -275,10 +301,13 @@ an empty bill of health.
**Human output example:**
```
Project root: /Users/alice/myproject
Host: Claude Code (Tier A)
Found .claude/ directory
Tier A host with full protocol + interception hooks. Secrets are maximally protected.
Host: Cursor (Tier B)
Found .cursor/ directory
Tier B host with protocol + advisory guardrails only. ...
Agent wiring: MCP ok, instructions ok
Cursor MCP is wired (project .cursor/mcp.json).
Gitignore covers .env: yes
Hook on internal error: fail-open (default)
Missing required keys: 1
- OPENAI_API_KEY
```
Expand All @@ -289,11 +318,18 @@ Missing required keys: 1
"projectRoot": "/Users/alice/myproject",
"manifestPath": "/Users/alice/myproject/env.schema.jsonc",
"host": {
"id": "claude-code",
"name": "Claude Code",
"tier": "A",
"reason": "Found .claude/ directory",
"recommendation": "Tier A host with full protocol + interception hooks. Secrets are maximally protected."
"id": "cursor",
"name": "Cursor",
"tier": "B",
"reason": "Found .cursor/ directory",
"recommendation": "Tier B host with protocol + advisory guardrails only. ..."
},
"agentWiring": { "mcp": "ok", "instructions": "ok" },
"mcp": {
"wired": true,
"status": "wired",
"message": "Cursor MCP is wired (project .cursor/mcp.json).",
"commandOk": null
},
"gitignore": {
"exists": true,
Expand All @@ -304,14 +340,20 @@ Missing required keys: 1
"isTracked": false,
"permissionsOk": true
},
"hookFailClosed": false,
"missingRequiredCount": 1,
"missingRequired": ["OPENAI_API_KEY"]
}
```

`agentWiring.mcp` is `"ok"` | `"missing"` | `"spawn_failed"`. `instructions` is
`"ok"` | `"missing"`. For MCP-capable hosts the JSON also includes
`mcp: { wired, status, message, commandOk }`. `message` tells the caller to run
`envseal init` (or the exact JSON to merge); it never says to copy from `plugins/`.

**Exit codes:**
- 0 — All checks passed; no missing required keys.
- 1 — One or more required keys are missing.
- 0 — All checks passed; no missing required keys; primary-host MCP wired when required; Layer 1 instructions present.
- 1 — One or more required keys are missing, or the agent is unwired (MCP missing/spawn_failed, missing `AGENTS.md` imperative, or Aider `read:` lists `.env`).

---

Expand Down
Loading
Loading