awoooi/docs/security/GITEA-READONLY-INVENTORY-APPROVAL-PACKAGE.md

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. 批准後指令

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

替代路徑：

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。