gitea-token-access/docs/architecture.md

Architecture: Read-Only Token Access for Gitea

Overview

This scheme provides controlled, minimal-privilege access to private Gitea repositories without sharing the owner's credentials.

Components

+-------------------+
|   Owner Account   |   Full admin access to Gitea
|   (e.g. aibot777) |   Owns all repositories
+--------+----------+
         |
         | Creates & manages via Admin API
         v
+-------------------+
|  Reader Account   |   Restricted account ("hobo account")
| (e.g. uclaude-    |   No admin rights
|     reader)       |   Can only access repos where explicitly
+--------+----------+   added as collaborator (read permission)
         |
         | Authenticates via
         v
+-------------------+
|   API Token       |   scope: read:repository
|   (sha1_xxx...)   |   Can only READ repos the reader
+--------+----------+   account has access to
         |
         | Used by
         v
+-------------------+
| Scripts/Installers|   git clone, curl, wget
| CI/CD pipelines   |   Any tool that needs read access
+-------------------+

Access Flow

1. Owner creates the reader account (one-time setup)
2. Owner grants the reader access to specific repos (per-repo)
3. Reader's token is used by automated tools to read those repos
4. If the token leaks — revoke it, rotate, no owner credentials exposed

Security Properties

Property	Status
Owner credentials exposed	No
Token can write to repos	No (read:repository scope)
Token can access admin API	No
Token can access repos not granted	No
Token can be rotated independently	Yes
Access is per-repo granular	Yes

Gitea API Endpoints Used

Action	Method	Endpoint	Auth
Create user	POST	/admin/users	Owner (admin)
Activate user	PATCH	/admin/users/{username}	Owner (admin)
Create token	POST	/users/{username}/tokens	Reader (basic)
Delete token	DELETE	/users/{username}/tokens/{name}	Reader (basic)
Add collaborator	PUT	/repos/{owner}/{repo}/collaborators/{user}	Owner
Remove collaborator	DELETE	/repos/{owner}/{repo}/collaborators/{user}	Owner
List repos	GET	/user/repos	Reader (token)
Get repo	GET	/repos/{owner}/{repo}	Reader (token)
Get raw file	GET	/repos/{owner}/{repo}/raw/{path}	Reader (token)