incredigo/CLAUDE.md

# incredigo — project directive for Claude sessions

**incredigo** is a local-first, encrypted, RAM-only credential custody tool (Go).
The folder is still named `credrot/`; the module/binary are `incredigo`.

> Read this first, then [`VISION.md`](VISION.md) (who it's for + the mission),
> [`DESIGN.md`](DESIGN.md) (architecture + threat model), [`docs/MARKET.md`](docs/MARKET.md)
> (competitive landscape + positioning) and — if present locally — `docs/ROTATION.md`
> (rotation design; **gitignored**, shared individually, not on the upstream repo).

## Vision — catch vibe-coding security disasters before they happen

The primary user is the **vibe coder**: the fast-moving AI-assisted builder (OpenClaw / Hermes /
Claude-Code / Cursor) who ships in a weekend and accumulates dozens of credentials —
`.env` keys, `sk_live`, `DATABASE_URL`, GitHub PATs, AWS keys, Supabase `service_role` — each
**generated once, pasted in, and never rotated**. incredigo finds that sprawl on the machine,
custodies it in RAM, backs it up, **rotates what's scriptable**, and **guides the human through
the rest** — before a forgotten key becomes a breach. **Secondary user:** the non-technical
password reuser (weak/reused passwords saved in the browser) — same engine, friendlier face, via
the browser worklist + change-URL links.

Tailor every feature to those two. **Do NOT build toward enterprise PAM / machine-identity-at-
scale / compliance-cert / SaaS-hub** territory — that's the incumbents' moat. The target
credential surface (the driver + scanner roadmap) is the **20-credential list in `VISION.md`**.
Full crystallized vision in [`VISION.md`](VISION.md); competitive rationale in
[`docs/MARKET.md`](docs/MARKET.md).

## North-star goal

A user or organization can rotate their credentials with one tool, two modes:

- **Mode A — rotate what's already in gopass.**
- **Mode B — ingest creds first (scanners / `--path` / browser CSV), then rotate.**

Both must run **interactively or fully headless** (`$INCREDIGO_PASSPHRASE`, no TTY):
do the automatable rotations unattended, and emit a guided worklist (+ links) for the
credentials that legitimately require a human. See `docs/ROTATION.md` Part II.

## Where development is (2026-07-14)

> Snapshot: [`docs/STATE-2026-07-14.md`](docs/STATE-2026-07-14.md) · plan:
> [`docs/ROADMAP.md`](docs/ROADMAP.md) · visual map: `incredigo-map.html`.

- **v1 shipped:** discover → migrate → expiry → sealed export/import. 9 scanners
  (aws, env, netrc, ssh, docker, kube, git, tea, file/`--path`); sealers age
  (default), hmac, openssl. 179 tests green, `-race` clean.
- **Rotation: 22 drivers + wired Mode A execute spine.** All drivers self-register;
  `rotate --execute` runs behind `INCREDIGO_ALLOW_EXECUTE=1` **and** the mandatory
  verified-backup gate (`Snapshot`). Proof status is DATA (`internal/rotate/proofs.go`
  mirrored in `docs/ROTATION-PROOFS.md`): **8 LIVE-VM** (postgres, mysql, redis,
  mongo, wireguard, gitea, appsecret, k8s), **14 MOCK-ONLY**, plus a `LIVE-REAL`
  level no driver carries yet. `--execute` enforces a proof gate: only drivers
  with proof ≥ LIVE-VM (`MinExecuteProof`) run; MOCK-ONLY/UNPROVEN are skipped
  unless `--allow-mock-proven` is passed. **No real (host) credential has been
  rotated yet** — every real rotation still requires explicit per-credential
  authorization (safe-candidate ladder, ROADMAP M2).
- **Guided manual layer done:** `internal/links` + `internal/worklist` +
  `internal/tui` → `incredigo worklist` / `incredigo guide` (read-only).
- **Phase B scaffolded, not wired:** 12 pwstore adapters, pwgen, staging;
  `incredigo passwords pw-*` flow incomplete (ROADMAP M4).
- **Known weak spots:** policy 66% / tui 57% coverage; coverage floors reported by
  `make check-cover` but not yet CI-enforced; lab-provision scripts not in repo
  (ROADMAP M0–M1). (sink 30%→85%, cmd 4.3%→34.5%, gitea CI + Makefile added
  2026-07-15.)

## Hard rules (do not violate — this tool holds real credentials)

1. **Backup before rotate, always.** No rotation may run unless `rotate.Snapshot`
   has produced a **verified** sealed backup of the affected entries first. The gate
   aborts the run on any backup/verify failure. This is non-negotiable.
2. **Verify-new-before-revoke-old.** Order: backup → rotate → verify the new secret
   authenticates → store in gopass → re-read → *only then* revoke the old. Never
   `gopass rm` an old value before the new one is proven (SSH/DB = lockout risk).
3. **No plaintext secrets on disk. Ever.** Secrets live only in the memguard vault
   and stream as bytes. Browser passwords → **worklist of non-secret metadata**
   (site, username, change-URL), never a `.txt` password dump. Raw export is a
   loudly-warned, flag-gated opt-in only.
4. **gopass test isolation = `GOPASS_HOMEDIR`, NOT `PASSWORD_STORE_DIR`.** gopass
   ignores `PASSWORD_STORE_DIR`; `gopass init --path …` repoints the user's real
   root mount and breaks their store. Always isolate tests with
   `export GOPASS_HOMEDIR=$(mktemp -d)` + a throwaway `GNUPGHOME`. Better: unit-test
   against a **fake gopass binary** via `sink.Gopass{Bin: …}` (see
   `internal/sink/bundle_test.go`, `internal/rotate/backup_test.go`).
5. **Do no harm / self-owned only.** Browser automation targets **only the user's own
   accounts**, with their authorization. Never bypass MFA/CAPTCHA — hand off to the
   human. Nothing here may resemble credential stuffing or account takeover.
6. **Dry-run by default; destructive steps are opt-in, audited, reversible.** The
   redacted audit log records every action. Computer-use/vision automation must
   inject secrets locally and never stream them into the model loop.
7. **The PGP passphrase is the root of trust.** It unlocks every gopass secret. The
   TUI and docs MUST warn prominently: lose it → everything is unrecoverable;
   leak it → everything is exposed. Tell users to back up the GPG key and use a
   strong passphrase. Treat this warning as a required UX element, not optional.

## Build / test / run

```sh
go build ./...            # green required before commit
go vet ./...
go test ./...             # all packages; -race clean on vault/sink/rotate
go build -o /tmp/incredigo ./cmd/incredigo
```

Never run `incredigo migrate/export/rotate` against the user's **real** gopass to
"test" — use an isolated `GOPASS_HOMEDIR` (rule 4).

## Architecture

```
cmd/incredigo        cobra CLI: scan|migrate|status|export|import|rotate
internal/vault       memguard arena (mlock/DONTDUMP, zeroize, handles)
internal/discover    Scanner registry + one file per source
internal/sink        gopass streaming, bundle framing, Sealer (age/hmac/openssl)
internal/policy      expiry engine
internal/audit       redacted append-only JSONL
internal/rotate      Rotator interface + MANDATORY backup gate (no drivers yet)
```

Extension points stay one-file-each: a Scanner, a Sealer, a Rotator. Drivers and the
backup gate live in Go; the AI router + browser long-tail belong in a skill/MCP layer
on top (do not put an LLM in the deterministic destructive hot path).

## Chosen stack (2026 research, see ROTATION.md §13)

- **TUI:** Charm Bubble Tea + Bubbles + Lipgloss (masked input via `textinput`).
- **Browser automation:** go-rod (default) → playwright-go (reliability) → Anthropic
  Computer Use (vision fallback, secrets kept out of the loop).
- **Per-site links:** `.well-known/change-password` (RFC 8615) + a curated table.

## Conventions

- Match surrounding Go style; comment the *why* for any security-relevant choice.
- New code ships with tests (table-driven scanners; leak-checks asserting no secret
  substring reaches `Identity`/`Meta`/logs).
- Commits: end messages with the `Co-Authored-By: Claude …` trailer. Push only when
  asked. Remote is **gitea only, never GitHub**
  (`https://100.117.177.50:3030/trill-technician/incredigo`).
- Design docs (`docs/ROTATION.md`) are kept local/gitignored by request; `VISION.md`,
  `DESIGN.md`, `README.md`, `docs/MARKET.md`, `docs/SECURITY.md`, `docs/ADDING_A_SCANNER.md`
  are tracked.