# Gitea Read-only 全量 Inventory Approval Package

| 項目 | 內容 |
|------|------|
| 日期 | 2026-05-17 |
| 狀態 | 草案，等待人工批准 |
| 來源事件 | `gitea_repo_inventory_v1` |
| Approval event | `docs/security/gitea-readonly-inventory-approval.snapshot.json` |
| Redaction checklist | `docs/security/GITEA-ADMIN-EXPORT-REDACTION-CHECKLIST.md` |
| S4.5 export request | `docs/security/GITEA-AUTHENTICATED-INVENTORY-EXPORT-REQUEST.md` |
| S4.6 import acceptance | `docs/security/GITEA-AUTHENTICATED-INVENTORY-IMPORT-ACCEPTANCE.md` |
| S4.7 coverage attestation | `docs/security/GITEA-INVENTORY-COVERAGE-ATTESTATION.md` |
| S4.9 owner response request packet / 收件包 | `docs/security/GITEA-INVENTORY-OWNER-ATTESTATION-RESPONSE.md` |
| 目的 | 補齊 Gitea private/internal server-side repo list |
| 原則 | 低摩擦、只讀、只盤 metadata、不保存 token value、不做同步或主控切換 |

## 0. 為什麼需要 approval

目前已取得 public-only Gitea repo evidence：

1. `users/wooo/repos` 可見 `wooo/awoooi`、`wooo/ewoooc`。
2. `orgs/wooo/repos` 未認證查詢回 404，已保留 blocked evidence。
3. 本機 remote inventory 顯示還有 `clawbot-v5`、`wooo-aiops`、110 internal / GitLab 類 remote 等來源。

因此 public-only evidence 不足以宣告「Gitea 所有專案版本」已盤完。下一步需要統帥或 repo owner 批准其中一條路徑：

1. 提供 Gitea read-only token，僅用環境變數執行一次 inventory。
2. 提供 Gitea 管理介面匯出的 redacted repo list JSON。

此 approval package 的目的不是提高日常開發門檻，而是只保護「會接觸 token 或管理匯出」這一個邊界。取得全量清單後，後續仍先進入 evidence / matrix / draft plan，不直接進入同步或阻擋。

S4.5 已補 `gitea_authenticated_inventory_export_request_v1`，把 read-only token API inventory 與 redacted admin export 的允許欄位、拒收欄位、coverage gap 與驗收 gate 正式文件化。批准前仍不得要求使用者貼 token value。

S4.6 已補 `gitea_authenticated_inventory_import_acceptance_v1`，把 owner / 管理者提供脫敏 payload 後的 schema 檢查、敏感值拒收、coverage gap 驗收與 mirror quarantine lane 正式文件化。payload 驗收通過仍不等於 GitHub primary cutover 被批准。

S4.7 已補 `gitea_inventory_coverage_attestation_v1`，把 public-only / local remote gap、org/user endpoint、110 internal adjacent source、canonical owner 與 legacy/inaccessible repo disposition 的 owner decision 正式文件化。attestation 只做 scope 判定，不等於 repo migration 或 primary cutover approval。

S4.9 已補 `gitea_inventory_owner_attestation_response_v1`，把 AwoooP 可顯示給 owner 的 request packet、template status ledger、audit event templates、redaction examples、display sections、collection checks、owner 回覆 S4.7 五個 items 時的必填欄位、intake preflight checks、outcome lanes、驗收規則與拒收規則正式文件化。request packet 只是填寫提示，template status ledger / audit event templates / redaction examples / display sections / collection checks 只維持 request / received / accepted 分離；audit event templates 目前全為 `template_only_not_emitted`、0 emitted，只定義脫敏 metadata 欄位；redaction examples 只供 owner 參考安全回覆形狀；display sections 只固定只讀 UI 區塊順序；response 通過只代表可更新 read-only matrix / decision table，不等於 read-only inventory 已執行或 AwoooP production ingestion 已啟用。

## 1. 申請批准的動作

| 動作 | 風險 | 批准後允許 | 仍然禁止 |
|------|------|------------|----------|
| `run_gitea_readonly_inventory` | MEDIUM | 使用 read-only token 呼叫 Gitea API 盤 repo metadata | 寫入 Gitea、保存 token、同步 refs、建 repo |
| `import_gitea_admin_export` | MEDIUM | 匯入 redacted JSON，產生 `gitea_repo_inventory_v1.status=ok` evidence | 匯入 secret value、webhook secret、deploy key private key |

## 2. Token 使用邊界

1. Token 只允許放在 `GITEA_READONLY_TOKEN` 環境變數。
2. Token 不得寫入 `.env`、shell history、文件、LOGBOOK、issue、PR、snapshot。
3. 工具輸出只保存 `token_present=true|false`。
4. Token 權限必須只讀，不能有 repo delete、push、admin、secret read/write 權限。
5. 執行後建議撤銷或輪替 token。

## 3. 批准後指令

```bash
python3 scripts/security/gitea-repo-inventory.py \
  --base-url http://192.168.0.110:3001 \
  --org wooo \
  --scope user \
  --token-env GITEA_READONLY_TOKEN \
  --github-owner owenhytsai \
  --output-json docs/security/gitea-repo-inventory.snapshot.json \
  --output-md docs/security/GITEA-REPO-INVENTORY-SNAPSHOT.md
```

替代路徑：

```bash
python3 scripts/security/gitea-repo-inventory.py \
  --base-url http://192.168.0.110:3001 \
  --org wooo \
  --github-owner owenhytsai \
  --input-json /path/to/redacted-gitea-repos.json \
  --output-json docs/security/gitea-repo-inventory.snapshot.json \
  --output-md docs/security/GITEA-REPO-INVENTORY-SNAPSHOT.md
```

## 4. 驗收標準

| Gate | 必須結果 |
|------|----------|
| JSON 可解析 | `docs/security/gitea-repo-inventory.snapshot.json` 通過 parse |
| Schema 欄位 | `schema_version=gitea_repo_inventory_v1` |
| 全量狀態 | `status=ok` |
| 可見範圍 | `visibility_scope=authenticated` 或 `admin_export` |
| 敏感資訊 | 不含 token、password、secret value、private key |
| Redaction checklist | `docs/security/GITEA-ADMIN-EXPORT-REDACTION-CHECKLIST.md` 已通過 |
| Coverage gap | public-only 2 repos 與 local Gitea 4 repos 的差異已解釋 |
| Import acceptance | S4.6 驗收檢查通過；敏感 payload 必須進隔離 |
| Owner attestation response | S4.9 已收到並驗收 S4.7 五個 coverage items 的 owner response |
| 後續動作 | 只更新 matrix / decision table，不同步 refs |

## 5. 批准前不得做

1. 不要求使用者在對話中貼 token value。
2. 不把 token 寫入任何檔案。
3. 不用有寫入權限的 token。
4. 不建立 GitHub repo。
5. 不修改 GitHub repo visibility。
6. 不 push、fetch mirror、sync refs。
7. 不切 GitHub primary。

## 6. AwoooP 消費方式

AwoooP 可以把本 package mirror 成 approval candidate，但只能顯示：

1. requested action。
2. risk。
3. required reviewers。
4. evidence refs。
5. blocked_until_approved。

AwoooP 不得直接要求、保存或傳遞 token value。