docs: add project CLAUDE.md — rotation directive + safety guardrails
Operational directive for Claude sessions: the headless two-mode rotation goal, current phase, and the non-negotiable guardrails (backup-before-rotate, verify-before-revoke, no-plaintext-on-disk / browser worklist not dump, GOPASS_HOMEDIR test isolation, self-owned-accounts scope, PGP passphrase = root of trust). Chosen stack: Bubble Tea + go-rod + .well-known/change-password. docs/ROTATION.md Part II (capability matrix, TUI walkthrough, link gen, browser worklist, automation tiers) is updated on disk but stays gitignored (local-only). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
leetcrypt
@@ -0,0 +1,104 @@
|
||||
# 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 [`DESIGN.md`](DESIGN.md) (architecture + threat model) and —
|
||||
> if present locally — `docs/ROTATION.md` (rotation design; **gitignored**, shared
|
||||
> individually, not on the upstream repo).
|
||||
|
||||
## 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-06-15)
|
||||
|
||||
- **v1 shipped:** discover → migrate → expiry → sealed export/import. 8 scanners
|
||||
(aws, env, netrc, ssh, docker, kube, git, file/`--path`); sealers age (default),
|
||||
hmac, openssl. Tests green, `-race` clean.
|
||||
- **Rotation: design + safety-spine only.** `internal/rotate` has the `Rotator`
|
||||
interface, the **mandatory backup gate** (`Snapshot`), and a dry-run `incredigo
|
||||
rotate`. **Zero rotation drivers exist; `--execute` is refused.** Nothing changes a
|
||||
credential at any service yet — keep it that way until explicitly authorized.
|
||||
|
||||
## 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; `DESIGN.md`,
|
||||
`README.md`, `docs/SECURITY.md`, `docs/ADDING_A_SCANNER.md` are tracked.
|
||||
Reference in New Issue
Block a user