Document Hermes Gitea token flow

docs/hermes-operations.md

@@ -226,6 +226,40 @@ Restart/reset requirement:
 - CLI session tool changes: start a new session or `/reset`
 - provider auth changes: start a new session after switching models/providers
 
+## Safe local Gitea Git token flow
+
+Root Hermes has a least-privilege local Gitea Git path for repository reads:
+
+- token file: `/root/.gitea_npm_token_home`
+- askpass helper: `/root/.local/bin/gitea-git-askpass`
+- Git wrapper: `/root/.local/bin/gitea-git`
+- default username: `learning_ai_user`
+- local Gitea URL: `http://localhost:3300`
+
+The token value must never be placed in a remote URL, shell history, Git config, docs, logs, or Hermes chat. The wrapper sets `GIT_TERMINAL_PROMPT=0` and `GIT_ASKPASS=/root/.local/bin/gitea-git-askpass`; the askpass helper reads the token from the root-only token file only when Git prompts for a password.
+
+Safe read-only test:
+
+```bash
+/root/.local/bin/gitea-git ls-remote http://localhost:3300/bytelyst/learning_ai_common_plat.git HEAD
+```
+
+Hermes-safe prompt pattern:
+
+```text
+Use the terminal tool only. Run exactly this read-only command and report only whether it succeeded and the first 12 characters of the HEAD hash: /root/.local/bin/gitea-git ls-remote http://localhost:3300/bytelyst/learning_ai_common_plat.git HEAD. Do not print any token, credential, environment variable, or file contents.
+```
+
+Verification recorded on 2026-05-27:
+
+- local Gitea version endpoint returned `1.22.6`
+- token file permissions are root-only
+- profile-read API access returned a scope denial, confirming the token is not broad enough for user-profile reads
+- direct wrapper test returned HEAD `59c4638f85be...`
+- Hermes one-shot test reported success with truncated HEAD `59c4638f85be`
+
+For write operations, create a separate repo-scoped token and store it in a new root-only token file. Do not reuse this read-focused token for broad automation unless the required scope is explicitly reviewed first.
+
 ## Telegram topics and session handling
 
 Root and Uma currently use the standard Telegram gateway session handling. Do not enable or change topic/session behavior without a concrete routing need.

docs/hermes-setup-upgrade-roadmap.md

@@ -8,13 +8,13 @@
 
 ## Completion Status
 
-- **Overall checklist completion:** ~68% (`122/179` checked after the 2026-05-27 dashboard/watchdog/runbook audit).
-- **Credential-independent setup:** materially further along; remaining blockers are mostly provider/search credentials, GitHub/Gitea tokens, Uma backup design, and policy decisions.
+- **Overall checklist completion:** ~68% (`122/179` checked after the 2026-05-27 Gitea/Hermes Git smoke test).
+- **Credential-independent setup:** materially further along; remaining blockers are mostly provider/search credentials, GitHub automation token, Uma backup design, and policy decisions.
 - vijay: percentage is based on literal Markdown checklist boxes, including nested sub-items. It intentionally counts credential-dependent future work as incomplete.
 
 ## Remaining Unchecked Item Classification
 
-- **Needs credentials/API keys:** fallback provider setup, web search/extract backend, GitHub/Gitea automation token, Browserbase/Browser Use, and provider fallback tests.
+- **Needs credentials/API keys:** fallback provider setup, web search/extract backend, GitHub automation token, Browserbase/Browser Use, and provider fallback tests.
 - **Needs explicit policy decision:** Cloudflare Access/basic-auth public fallback, model-routing tiers, local browser automation, vision/image provider choice, `security.redact_secrets`, `privacy.redact_pii`, and credential rotation.
 - **Needs Uma backup design:** Uma/Bheem currently has a clean VM wrapper repo, but not a root-style sanitized Hermes persistent backup/restore workflow.
 - **Needs manual UX validation:** dashboard feature-by-feature checks, Telegram approval prompt flow, and Telegram media/file delivery.
@@ -233,6 +233,8 @@ A healthy ByteLyst Hermes setup should be:
   - [ ] local Chromium/Camofox, or
   - [ ] Browserbase/Browser Use
 - [ ] Configure GitHub/Gitea automation credentials with least privilege.
+  - vijay: root local Gitea read-only Git path is configured with `/root/.local/bin/gitea-git` plus `GIT_ASKPASS`; the token remains in `/root/.gitea_npm_token_home` and was not printed. Verified direct Git and Hermes one-shot read access to `http://localhost:3300/bytelyst/learning_ai_common_plat.git`.
+  - vijay: still unchecked because GitHub automation credentials are separate and have not been provisioned.
 - [ ] Add vision/image capability if screenshots, diagrams, or UI reviews are common.
 - [x] Validate the active Telegram toolset includes the capabilities ByteLyst expects:
   - vijay: `hermes doctor --fix` reported browser, clarify, code_execution, cronjob, terminal, delegation, file, memory, messaging, session_search, skills, todo, tts, vision, video, and related toolsets available; web remains blocked by missing search backend API key.
@@ -362,6 +364,7 @@ A healthy ByteLyst Hermes setup should be:
 - [ ] Keep `privacy.redact_pii` decision documented for gateway sessions.
 - [ ] Rotate old credentials after migration or accidental exposure risk.
 - [ ] Use least-privilege tokens for GitHub/Gitea, web APIs, and provider keys.
+  - vijay: Gitea Git operations now use the narrow local token through `GIT_ASKPASS`; API profile reads are intentionally blocked by token scope. GitHub, web APIs, and provider-key rotation remain pending.
 - [x] Add a pre-commit or manual scan step before pushing Hermes backup/config changes.
   - vijay: added manual scan/review step in practice during root/Uma repo pushes; root backup repo now ignores generated cron outputs that previously carried noisy token-pattern scan results.
 - [x] Keep approval mode at `manual` or `smart` for Telegram-driven work.
@@ -408,6 +411,7 @@ A healthy ByteLyst Hermes setup should be:
   - vijay: documented restore drill and restored root backup into `/tmp/hermes-restore-test-root`.
   - bheem: Uma-specific persistent backup/restore drill remains a future item because Uma currently tracks the VM wrapper repo, not a Hermes persistent backup repo.
 - [ ] Add Gitea/GitHub least-privilege automation credential path.
+  - vijay: Gitea path is complete for root via `/root/.local/bin/gitea-git`; GitHub path remains pending, so this combined item stays unchecked.
 
 ### Medium-Term — This Month
 
@@ -477,6 +481,15 @@ This roadmap is complete when:
 - vijay: updated `docs/hermes-operations.md` with root service commands, Tailscale status, restore rehearsal outcome, and late upgrade notes.
 - bheem: updated `docs/hermes-operations.md` with Uma service commands and shared private-dashboard notes.
 
+### 2026-05-27 — vijay Gitea least-privilege Git path
+
+- vijay: confirmed local Gitea API version `1.22.6` and root-only token-file permissions without printing token values.
+- vijay: verified `/root/.gitea_npm_token_home` does not have broad profile-read scope; `/api/v1/user` returned the expected scope denial instead of user data.
+- vijay: installed `/root/.local/bin/gitea-git-askpass` and `/root/.local/bin/gitea-git` so Hermes/Git can authenticate to local Gitea without embedding tokens in remotes or Git config.
+- vijay: verified direct Git read operation: `gitea-git ls-remote http://localhost:3300/bytelyst/learning_ai_common_plat.git HEAD` returned HEAD `59c4638f85be...`.
+- vijay: verified the same read-only operation through Hermes one-shot; Hermes reported success and only the truncated HEAD hash.
+- vijay: documented the exact safe token flow in `docs/hermes-operations.md`; GitHub automation token remains a separate future credential item.
+
 ## Notes For Future Transcript Pass
 
 When the transcript is available, specifically check whether the video recommends any of the following and update this roadmap accordingly:

scripts/gitea-git

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+
+export GIT_TERMINAL_PROMPT=0
+export GIT_ASKPASS="${GIT_ASKPASS:-/root/.local/bin/gitea-git-askpass}"
+export GITEA_USERNAME="${GITEA_USERNAME:-learning_ai_user}"
+export GITEA_TOKEN_FILE="${GITEA_TOKEN_FILE:-/root/.gitea_npm_token_home}"
+
+exec git "$@"

scripts/gitea-git-askpass

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+
+username="${GITEA_USERNAME:-learning_ai_user}"
+token_file="${GITEA_TOKEN_FILE:-/root/.gitea_npm_token_home}"
+
+case "${1:-}" in
+  *Username*)
+    printf '%s\n' "$username"
+    ;;
+  *Password*)
+    tr -d '\n' < "$token_file"
+    ;;
+  *)
+    exit 1
+    ;;
+esac