awoooi/docs/security/GITEA-AUTHENTICATED-INVENTORY-IMPORT-ACCEPTANCE.md

# Gitea 認證清冊匯入驗收契約

| 項目 | 內容 |
|------|------|
| 日期 | 2026-05-17 |
| 狀態 | 草案，等待脫敏清冊 payload |
| 資料契約 | `docs/schemas/gitea_authenticated_inventory_import_acceptance_v1.schema.json` |
| 快照 | `docs/security/gitea-authenticated-inventory-import-acceptance.snapshot.json` |
| 來源契約 | `gitea_repo_inventory_v1` |
| 上游請求 | `gitea_authenticated_inventory_export_request_v1` |
| 覆蓋 Attestation | `docs/security/GITEA-INVENTORY-COVERAGE-ATTESTATION.md` |
| Attestation response 收件包 | `docs/security/GITEA-INVENTORY-OWNER-ATTESTATION-RESPONSE.md` |
| 模式 | `redacted_payload_acceptance_only` |
| 執行面授權 | `false` |

## 0. 核心結論

S4.6 定義「收到 owner 或 Gitea 管理者提供的脫敏清冊後，怎麼驗收、怎麼拒收、怎麼隔離」。

這不是實際匯入，也不是宣告 Gitea inventory 完成。它只把未來可接受的 payload 形狀、必要欄位、拒收規則、隔離 lane 與允許輸出先固定下來，避免 owner 提供資料時把 token、DB dump、git object 或 repo 操作要求混進來。

S4.7 已補 owner coverage attestation，S4.9 已補 owner response request packet、template status ledger、audit event templates、redaction examples、display sections、collection checks 與收件包：即使 payload 通過 S4.6，也仍需 owner 依 S4.9 request packet 回覆 public-only / local remote gap、org/user endpoint、110 internal adjacent source、canonical owner 與 legacy/inaccessible disposition，且 template status ledger、audit event templates、redaction examples、display sections、collection checks 與 response 驗收通過後，才可把 blocker 往 primary readiness 下一關推進；audit event templates 目前只允許顯示 0 emitted 的脫敏 metadata 模板，redaction examples 只供填寫參考，display sections 只供只讀 UI 顯示，不代表 production ingestion。

## 1. 驗收摘要

| 指標 | 值 |
|------|----|
| 目標契約 | `gitea_repo_inventory_v1.status=ok` |
| 目前 payload 狀態 | `waiting_redacted_payload` |
| 可接受 visibility scope | `authenticated` / `admin_export` |
| 最低 repo count | 2 |
| 本機可見 Gitea unique repos | 4 |
| 需要解釋的缺口 | 3 |
| 已收到 payload | 0 |
| 已接受 payload | 0 |
| 已拒收 payload | 0 |
| 驗收檢查 | 10 |
| 拒收規則 | 10 |
| 敏感 payload 必須隔離 | `true` |
| 允許收集 token value | `false` |
| 允許 DB dump / git object | `false` |
| 允許 repo write / refs sync | `false` |
| 授權切換 GitHub primary | `false` |
| S4.7 owner attestation items | 5 |

## 2. 可接受 Payload 形狀

必須具備 top-level 欄位：

1. `schema_version`。
2. `base_url`。
3. `org`。
4. `visibility_scope`。
5. `token_present`。
6. `status`。
7. `repo_count`。
8. `repos`。
9. `coverage_gap_explanation`。
10. `redaction_attestation`。

每筆 repo 必須具備：

1. `full_name`。
2. `name`。
3. `owner.login`。
4. `private`。
5. `archived`。
6. `empty`。
7. `default_branch`。
8. `clone_url_redacted`。
9. `ssh_url_redacted`。
10. `github_repo_candidate`。

## 3. 必須拒收

1. token value、PAT、cookie、session、CSRF token 或 partial token。
2. webhook secret、repository secret value、runner registration token。
3. deploy key private key 或任何 private key material。
4. Gitea DB dump、完整 git object pack、裸 repo tarball。
5. write-capable token、admin token 或 secret scope token。
6. 建立、刪除、封存或修改 Gitea repo 的要求。
7. 建立 GitHub repo、修改 visibility、sync refs、delete refs、force push 或切 GitHub primary 的要求。
8. 未解釋未認證公開範圍 2 repos 與本機 Gitea 4 unique repos 差異的 payload。
9. 未說明 110 內部相鄰來源 scope 的 payload。
10. 任何不確定是否含敏感值的 payload。

## 4. 隔離 Lane

| 條件 | 隔離 lane |
|------|-----------|
| 出現 token、password、cookie、session、private key、webhook secret 或 runner registration token | `sensitive_value_payload_quarantine` |
| 出現 Gitea DB dump、git object pack、裸 repo tarball 或完整 artifact | `oversized_or_wrong_artifact_quarantine` |
| 欄位不足、repo_count 不一致或 coverage gap 未解釋 | `schema_or_evidence_gap_quarantine` |
| payload 夾帶 repo 建立、refs sync、primary switch 或 workflow / secret 修改要求 | `execution_request_quarantine` |

## 5. 允許輸出

1. 產出或更新脫敏後的 `gitea_repo_inventory_v1.status=ok` snapshot。
2. 更新 `SOURCE-CONTROL-MIGRATION-MATRIX.md` 與 source-control decision table。
3. 更新 `source_control_primary_readiness_gate_v1` 的 Gitea inventory blocker 狀態。
4. 更新 `security_mirror_status_rollup_v1` 與 `docs/LOGBOOK.md`。
5. 對缺口建立人工 owner review lane，不建立 execution action。

## 6. AwoooP 可做

1. 顯示 S4.6 匯入驗收格式。
2. 顯示 payload 驗收 / 拒收 / 隔離規則。
3. 在 owner 提供 payload 後，只做 schema / redaction / coverage gap 檢查。
4. 將敏感或不完整 payload 送進隔離 lane。
5. 將通過驗收的脫敏 metadata 顯示為等待人工 review 的 evidence。

## 7. AwoooP 不可做

1. 不要求使用者貼 token、secret、private key、cookie、session 或 DB dump。
2. 不把 payload 驗收成功當成 GitHub primary 已批准。
3. 不建立 GitHub repo。
4. 不修改 Gitea repo。
5. 不 sync refs。
6. 不新增執行按鈕。

## 8. 階段定位

S4.6 補的是 S4.5 後面的「安全收件規格」。它讓下一個 owner export / admin export 有清楚門檻，但仍然停在框架期。

真正讓 `gitea_repo_inventory_v1.status=ok`，必須等到脫敏 payload 實際產生、通過驗收、經人工 review，並完成 S4.7 owner coverage attestation 後，再另行提交 snapshot。此文件本身不代表 inventory 已完成。