ADR-0032: Key store defaults outside the repo (XDG); in-repo store is an explicit, gitignored opt-in

• Status: accepted · Date: 2026-07-22 · Deciders: Davor Runje

​

Context

​

Decision drivers

• A stored key must never be committable by default — not “committable unless .gitignore happens to be right.”
• Defense-in-depth: even a correct gitignore entry is one mistake away from a leak; prefer removing the repo from the equation entirely.
• Preserve ADR-0029’s other properties unchanged: os.environ > store > unset precedence, stdin/hidden-prompt-only writes, scoped in-memory env for child processes, plaintext-at-rest honesty.
• Stay light-dependency (ADR-0024) — no new package for this.
• Don’t break an existing in-repo store outright; give it an explicit, documented path back for anyone who wants it (e.g. a shared dev container where $HOME isn’t durable).

​

Considered options

1. Minimal: just add the gitignore line. research-init gitignores .defendable-science/keys.json, store location unchanged.
2. Move the default store outside the repo (XDG config), keep the in-repo path as an explicit opt-in + a runtime guardrail that warns if a resolved store is ever inside a non-gitignored work tree. (chosen)
3. OS secure store (Keychain / libsecret / Credential Manager) now.

​

Decision

• Default store location. defendable_science.core.keys.default_store_path() resolves to $XDG_CONFIG_HOME/defendable-science/keys.json, falling back to ~/.config/defendable-science/keys.json per the XDG Base Directory spec — never inside the consumer repo’s work tree. No dependency added (platformdirs was considered and rejected as unnecessary weight for two environment variables); implemented with stdlib os.environ + Path.home().
• Opt-in override. DEFENDABLE_SCIENCE_KEYS_PATH is an explicit override — set to any path, including the legacy in-repo .defendable-science/keys.json (kept as keys.IN_REPO_STORE_PATH) — for anyone who wants the store to travel with the repo instead of $HOME. research-init continues to gitignore .defendable-science/keys.json, so that opt-in still lands safely.
• Runtime guardrail. keys.store_at_risk(path) reports whether the resolved store sits inside a git work tree (walking up for a .git entry) and is not confirmed ignored (git check-ignore, run in that work tree’s root regardless of the CLI’s actual cwd). keys set calls this before writing and warns — never refuses — when it is true; an inconclusive answer (no git binary, not a git repo at all… i.e. any non-”definitely ignored” result) is treated as at-risk, matching the “no news is not good news for a secret” posture. Warn, not refuse, because: (a) the default path already keeps a fresh setup safe, so this only fires for an explicit opt-in a user made deliberately; (b) it matches the existing convention in this module (keys set on an unrecognised name warns but still stores) — CLAUDE.md’s failure-honesty stance asks for an explicit, actionable signal, not a silent success or a hard stop on a deliberate choice.
• Everything else from ADR-0029 is unchanged: precedence, stdin-only writes, scoped child-process env, plaintext-at-rest disclosure.

​

Consequences

• A fresh research-init + keys set sequence can never produce a committable secret file — git status shows nothing, because the store never entered the work tree.
• An existing consumer repo that already has an in-repo store is unaffected by the code change alone (nothing migrates automatically) but gets a warning the next time it writes if it opts into DEFENDABLE_SCIENCE_KEYS_PATH pointed at an un-ignored location; research-init re-runs will still add the gitignore line as a backstop.
• One more environment variable to document (DEFENDABLE_SCIENCE_KEYS_PATH, alongside the existing DEFENDABLE_SCIENCE_LIVE).
• The guardrail shells out to git check-ignore (a fixed, argument-list subprocess call, no shell) — the same trust boundary already accepted for rclone (ADR-0011) and the --version probes in doctor.
• Tests that exercise the default path must isolate HOME/XDG_CONFIG_HOME (a tests/conftest.py autouse fixture does this for the whole suite) so the suite never touches a real developer’s ~/.config.

​

Rejected alternatives

• Just add the gitignore line (option 1) — the minimal fix the issue proposed, but it is exactly the single point of failure that caused #66 in the first place: it protects only a freshly, correctly scaffolded repo. Implemented anyway as defense-in-depth (research-init still gitignores the in-repo path), just not relied on as the primary control.
• OS secure store now (option 3) — the right at-rest answer eventually, but heavy/platform-specific with a headless/CI fallback to design; already deferred to issue #49 by ADR-0029 and still the better place for it.

​

Links