# 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) |