From cfed6ef7bb37d3deaefd602b5eec403ee2abebd2 Mon Sep 17 00:00:00 2001 From: Frank Date: Fri, 9 Oct 2026 13:21:34 -0700 Subject: [PATCH] docs(gitea): document client token handling; move the token out of remote URLs New tools/gitea/client-access.md: the credential file (~/.config/secrets/gitea, 0600) behind a global 'store --file' helper, the git 2.56 credential-store trap (the key=value block shape parses to an empty get; the file must be one http://user:token@host:port URL per line), the GIT_TERMINAL_PROMPT=0 verification loop, the lfs.locksverify key that silences the URL echo, and the rotation procedure. Cross-linked from the gitea index and management pages. Both workstation remotes are now bare URLs; the token lives in one file. --- omp-docs/log.md | 9 +++ omp-docs/tools/gitea/client-access.md | 98 +++++++++++++++++++++++++++ omp-docs/tools/gitea/index.md | 3 + omp-docs/tools/gitea/management.md | 1 + 4 files changed, 111 insertions(+) create mode 100644 omp-docs/tools/gitea/client-access.md diff --git a/omp-docs/log.md b/omp-docs/log.md index de6bbdc..bd8feca 100644 --- a/omp-docs/log.md +++ b/omp-docs/log.md @@ -11,6 +11,15 @@ timestamp: 2026-08-28 # Bundle Change Log +## 2026-10-09 — Gitea token moved out of every remote URL + +Both workstation clones (`~/.omp` → `dank/command-center`, `~/Projects/serverAppConfig` → `dank/serverAppConfigs`) carried the Gitea HTTP token inside `remote.origin.url`, so it sat in `.git/config`, was printed by `git remote -v`, and was echoed verbatim by the git-lfs lock warning on every push. + +* **Cutover**: remotes are now bare (`http://192.168.0.143:3000/dank/.git`); the credential lives in `~/.config/secrets/gitea` (0600) behind a **global** helper — `git config --global credential.helper 'store --file ~/.config/secrets/gitea'` — so every repo on the host authenticates from one file. `lfs.…info/lfs.locksverify true` set on `~/.omp` to silence the warning that leaked the URL. +* **The trap (git 2.56.0, measured)**: `git credential-store` will not parse the `protocol=`/`host=`/`password=` block shape that `git credential fill` accepts on stdin and that the man page shows for `~/.git-credentials`. It returns an empty `get`, and git falls through to askpass: `could not read Username for …`. The store file must be one URL per line, port included: `http://dank:@192.168.0.143:3000`. +* **Verified** with prompts disabled (`GIT_TERMINAL_PROMPT=0`): `git credential-store get` returns the credential, `ls-remote` reads, `push --dry-run` says `Everything up-to-date` on both repos, `git remote get-url origin` contains no `@`, and a grep for the token across `~/.gitconfig`, both `.git/config` files, and the shell rc files returns nothing. +* **Doc**: new [[client-access|client-access]] (`tools/gitea/client-access.md`) — credential file layout, the store-format trap, the verification loop, LFS lock warning, rotation procedure. Cross-linked from the gitea index and management pages. + ## 2026-10-09 — Working tree reconciled: callsign renames, Dankclaw compaction, gitignore quarantine A 200-entry dirty tree (116 deleted, 73 untracked, 11 modified) sat uncommitted across several sessions. Committed as seven atomic units; nothing discarded. diff --git a/omp-docs/tools/gitea/client-access.md b/omp-docs/tools/gitea/client-access.md new file mode 100644 index 0000000..40f2ac4 --- /dev/null +++ b/omp-docs/tools/gitea/client-access.md @@ -0,0 +1,98 @@ +--- +type: reference +title: Gitea Client Access +description: Token-based HTTP access from client workstations — the credential store layout, the git 2.56 store-format trap, and the verification loop. +tags: + - gitea + - git + - secrets +verified: 2026-10-09 +--- + +# Gitea Client Access + +Clients (workstations, agent hosts) reach Gitea over plain HTTP on the LAN: +`http://192.168.0.143:3000/dank/.git`. Authentication is a Gitea HTTP token sent as +the password for user `dank`. SSH is available on `:2222` (see +[[architecture|architecture]]); HTTP + token is what the agent hosts use. + +## The law: the token never enters a URL, a config file, or a shell rc + +A remote URL of the shape `http://dank:@host/org.git` stores the credential in +`.git/config`, which is copied by every clone, printed by `git remote -v`, and echoed by +the LFS lock warning during `git push`. Keep the URL bare: + +``` +http://192.168.0.143:3000/dank/command-center.git +``` + +The credential lives in one file, mode 0600, outside every repository: + +| Item | Value | +|---|---| +| Credential file | `~/.config/secrets/gitea` (0600, dir 0700) | +| Helper (global) | `git config --global credential.helper 'store --file ~/.config/secrets/gitea'` | +| Scope | every repo on the host that talks to `192.168.0.143:3000` | + +## The git 2.56 store-format trap + +`git credential fill` **reads** `protocol=`/`host=`/`username=`/`password=` blocks on +stdin, and the man page shows the same shape for `~/.git-credentials`. `git +credential-store` (git 2.56.0, verified) does **not** parse that shape in the file: a +key=value block yields a silent empty `get`, so git falls through to askpass and dies with +`could not read Username`. Write the file as one URL per line: + +``` +http://dank:@192.168.0.143:3000 +``` + +The host line must carry the port (`192.168.0.143:3000`) — git keys the lookup on +`protocol` + `host:port`. + +Verify the file answers before trusting it, with prompts disabled so a failure is loud +rather than a hang: + +``` +printf 'protocol=http\nhost=192.168.0.143:3000\n\n' | git credential-store --file ~/.config/secrets/gitea get +``` + +Two lines come back (`username=`, `password=`). Silence means the format is wrong. + +## Verification loop + +Run every step with `GIT_TERMINAL_PROMPT=0`; anything that needs the token from a file the +helper cannot read fails immediately instead of blocking on a prompt. + +``` +GIT_TERMINAL_PROMPT=0 git ls-remote --heads origin main # read auth +GIT_TERMINAL_PROMPT=0 git push --dry-run origin main # write auth +git remote get-url origin # no '@' present +grep -rl '' ~/.gitconfig */.git/config # no plaintext copies +``` + +## LFS lock warning + +`git push` on a repo with git-lfs prints `Locking support detected on remote … info/lfs.locksverify true` +and echoes the remote URL — one more place a URL-embedded token leaks. Silence it per +repo with the bare URL: + +``` +git config lfs.http://192.168.0.143:3000/dank/.git/info/lfs.locksverify true +``` + +## Rotating the token + +Rotate in the Gitea UI (Settings → Applications), then rewrite only the credential file: + +``` +umask 077 && printf 'http://dank:%s@192.168.0.143:3000\n' '' > ~/.config/secrets/gitea +``` + +Nothing else changes: no remote URL, no rc file, no repository. The old token remains valid +until it is deleted in the UI, so delete it there as part of the rotation. + +## See Also + +- [[index|index]] — Gitea on dankclaw +- [[management|management]] — server-side operations +- [[architecture|architecture]] — ports (3000 HTTP, 2222 SSH) and the Caddy front diff --git a/omp-docs/tools/gitea/index.md b/omp-docs/tools/gitea/index.md index ef9c019..bd640fc 100644 --- a/omp-docs/tools/gitea/index.md +++ b/omp-docs/tools/gitea/index.md @@ -55,6 +55,7 @@ The quadlet files, Caddyfile, and `.env.example` are tracked in the `serverAppCo - [[architecture|architecture]] — network topology and ports - [[management|management]] — operations, upgrades, backups, incident log +- [[client-access|client-access]] — client-side tokens, the credential store, and the git 2.56 store-format trap - [[data-persistence|data-persistence]] — volumes and backup strategy - [[containers|containers]] — quadlet reference @@ -63,3 +64,5 @@ The quadlet files, Caddyfile, and `.env.example` are tracked in the `serverAppCo * [Gitea Data Persistence](data-persistence.md) — Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw. * [Gitea Management](management.md) — Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw. + + * [Gitea Client Access](client-access.md) — Token-based HTTP access from client workstations, credential store layout, and verification. diff --git a/omp-docs/tools/gitea/management.md b/omp-docs/tools/gitea/management.md index 9734f1c..5d577b5 100644 --- a/omp-docs/tools/gitea/management.md +++ b/omp-docs/tools/gitea/management.md @@ -101,6 +101,7 @@ Verify the fix on the next host reboot. ## See Also - ](index.md) — index +- [[client-access|client-access]] — how client hosts authenticate (token + credential store) - [[architecture|architecture]] — network topology - [[data-persistence|data-persistence]] — backups - [[containers|containers]] — quadlet reference