docs: correct git-sync secret-exposure model (gitignore is the boundary, not folder scope)

The prior model claimed git-sync's add-set is scoped to the configured
`folders` (pages/config/themes), so accounts/ and user/env/ were "safe by
construction." That was wrong: prod auto-commit 9337003 pushed the whole
user/env/<host>/config tree (JWT secret, CSRF salt, git-sync token + webhook
secret), accounts/mischa.yaml, and system.yaml to Gitea — all outside the
configured folders. git-sync stages everything under user/ not gitignored;
.gitignore is the only reliable exclusion.

- Rewrite the architecture-patterns doc around the corrected predicate and
  document the incident + remediation (gitignore /env/, rotate token+webhook).
- Correct git-sync-notes.md: env/ is NOT safe on folder scope; drop the
  "never reaches Gitea" claim; fix the secret-files table intro + add /env/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Np4cMQLF77i664CAQXySzU
This commit is contained in:
2026-07-05 10:19:54 +02:00
co-authored by Claude Opus 4.8
parent e0e2e1e7b5
commit 6dc6af6359
3 changed files with 267 additions and 12 deletions
+23 -12
View File
@@ -16,12 +16,17 @@ user/config/plugins/git-sync.yaml ← NOT here
Why this matters:
- **Server-only, not synced, not committed.** `user/env/` is outside the
content repo's tracked folders (`pages`/`config`/`accounts`/`themes`) and is
not one of git-sync's synced folders (`pages`/`config`/`themes`). So config
saved via Admin *on the server* never reaches Gitea or local. This is ideal
for the git-sync token (it stays server-only) but means **prod Admin config
edits silently diverge** — author durable config in the repo, not prod Admin.
- **⚠️ `user/env/` is NOT safe unless gitignored — it is NOT scoped out by the
`folders` setting.** An earlier version of this note claimed `user/env/`
"never reaches Gitea" because it is outside git-sync's synced folders. **That
is wrong and caused a live secret leak (2026-07-05).** git-sync's auto-commit
stages files *outside* the configured `folders`; on prod it pushed the whole
`user/env/intotheeast.com/config/` tree — JWT secret, CSRF salt, **and the
git-sync token + webhook secret** — to Gitea. The fix was to **gitignore
`/env/`** (commit `6e8eadb`). So: prod Admin config edits stay server-only
*only because `/env/` is now gitignored*, not because of folder scope. Author
durable config in the repo, not prod Admin. Full analysis:
`docs/solutions/architecture-patterns/git-sync-secret-exposure-and-tracked-file-boomerang.md`.
- **Look in both places.** When inspecting/toggling server config, check
`user/config/plugins/<name>.yaml` **and**
`user/env/<host>/config/plugins/<name>.yaml` (env wins).
@@ -48,19 +53,25 @@ If you see the comma-string form on an older version, fix it by editing
`git-sync.yaml` directly (at whichever path it lives — see above); do not
re-save folders via the Admin UI on the buggy version.
## Per-install / secret files — must be gitignored (never synced)
## Per-install / secret files — must be gitignored (gitignore is the boundary)
git-sync syncs the `config/` folder, so any per-install or secret file tracked
there would get pushed to Gitea and pollute every environment. Keep these out
of the content repo (all in `user/.gitignore`):
git-sync's auto-commit stages **everything under `user/` that is not
gitignored** — the `folders` setting does *not* scope the commit add-set (a
2026-07-05 leak proved this by pushing `user/env/**`, outside the configured
folders). So `.gitignore` — not folder scope — is the only thing keeping a
per-install or secret file off Gitea. Keep all of these gitignored in
`user/.gitignore`:
| File | Why |
| Path | Why |
|---|---|
| `env/` | **whole per-host env tree** — holds the live git-sync token, JWT secret, CSRF salt + all server-side Admin config. Gitignored + untracked 2026-07-05 (commit `6e8eadb`) after it leaked to Gitea. NOT safe on folder scope alone. |
| `config/plugins/git-sync.yaml` | encrypted token; server-specific (also lives at env path on prod) |
| `config/plugins/api-private.php` | API JWT secret |
| `config/security.yaml` | Grav nonces/salts (legacy location) |
| `config/versions.yaml` | per-install Grav schema-migration state — differs per env (dev 2.0.4, prod 2.0.7); Grav regenerates it. Untracked 2026-07-04. |
| `config/security-private.php` | **TODO:** committed salt secret; should be gitignored like `api-private.php` (deferred — untracking resets server sessions) |
| `config/security-private.php` | CSRF/nonce + admin rate-limit signing salt; gitignored + untracked 2026-07-05 (commit 2840018). Each env keeps its own; untracking regenerates prod's salt (one-time admin re-login). |
> **Why a key inside a *tracked* config file (e.g. `popularity.salt` in `api.yaml`) can't just be stripped** — it regenerates at runtime and boomerangs back via git-sync's `git add -A`. See `docs/solutions/architecture-patterns/git-sync-secret-exposure-and-tracked-file-boomerang.md` for the full round-trippable-set model.
## git-sync config summary (prod, 2026-07-04)