From 416f25794cfc9c3476c905501a37d0a2c0a37e43 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 27 May 2026 11:06:07 +0000 Subject: [PATCH] Document Hermes Gitea token flow --- docs/hermes-operations.md | 34 ++++++++++++++++++++++++++++ docs/hermes-setup-upgrade-roadmap.md | 19 +++++++++++++--- scripts/gitea-git | 9 ++++++++ scripts/gitea-git-askpass | 17 ++++++++++++++ 4 files changed, 76 insertions(+), 3 deletions(-) create mode 100755 scripts/gitea-git create mode 100755 scripts/gitea-git-askpass diff --git a/docs/hermes-operations.md b/docs/hermes-operations.md index 501e573..59a11f5 100644 --- a/docs/hermes-operations.md +++ b/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. diff --git a/docs/hermes-setup-upgrade-roadmap.md b/docs/hermes-setup-upgrade-roadmap.md index 9942b99..0e9a7fb 100644 --- a/docs/hermes-setup-upgrade-roadmap.md +++ b/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: diff --git a/scripts/gitea-git b/scripts/gitea-git new file mode 100755 index 0000000..2750a0e --- /dev/null +++ b/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 "$@" diff --git a/scripts/gitea-git-askpass b/scripts/gitea-git-askpass new file mode 100755 index 0000000..a63d28f --- /dev/null +++ b/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