Relay · Governance
資料生命週期與稽核
Relay 將 conversation history、user offboarding、tenant shutdown 與 operational audit 視為不同操作，每種操作都有各自的保證。本頁所有 endpoint 都需要 deployment admin token。
Message lifecycle
| 操作 | 立即結果 | 後續清理 |
|---|---|---|
| Retract | 保留 message row 與 channel seq、清除 body，並發出 msg:retracted | 不會排入 retention hard deletion |
| Admin delete | 保留 row 與 seq、清除 body、從一般 read 與 search 隱藏 message、tombstone 關聯 attachment，並發出 msg:deleted | 超過 deleted_message_days 後 hard-delete message row |
| Message audit | 在 tenant schema 內記錄 send、edit、retract 與 delete event | Deleted message row 清除後仍保留 audit row |
Retract 是 sender 可使用的 conversation action，不代表資料抹除。Administrative deletion 才是 data-governance path：
DELETE /api/admin/messages/{message_id}?tenant_id={tenant_id}
X-Admin-Token: <admin-token>Delete transaction 會一起清除 message body、tombstone 關聯 attachment、記錄 audit event，並寫入 durable post-commit effect。Object deletion 會非同步執行，也能獨立 retry。
Per-tenant retention
讀取目前 policy：
GET /api/admin/tenants/{tenant_id}/data_retention
X-Admin-Token: <admin-token>完整取代 policy：
PUT /api/admin/tenants/{tenant_id}/data_retention
X-Admin-Token: <admin-token>
Content-Type: application/json
{
"deleted_message_days": 30,
"post_commit_handoff_days": 7,
"host_webhook_dead_letter_days": 14,
"user_export_days": 1
}四個 value 都必須是正整數。以上是目前 default，deployment 可以設定不同的 default。這份 policy 控制 soft-deleted message、terminal post-commit handoff、webhook dead letter，以及 export row 與 file 的排程清理。
Retention worker 以非同步方式執行。設定天數代表 cleanup threshold，不代表每一份資料會在指定秒數精確消失。Operator 必須監控 worker 與 object-deletion queue。
匯出 user data
Export 是非同步 admin operation：
POST /api/admin/users/{user_id}/exports?tenant_id={tenant_id}
X-Admin-Token: <admin-token>Response 會回傳 status 為 queued 的 job_id。接著以相同 tenant scope 輪詢：
GET /api/admin/user_exports/{job_id}?tenant_id={tenant_id}
X-Admin-Token: <admin-token>完成的 job 會包含短效、由 application 簽章的 download_url 與 expires_at。Download response 是 JSON，並帶有 Cache-Control: no-store, private。過期的 download 回傳 410；不存在的 job 或無效 token 回傳 404。
匯出格式 v1 只包含對話核心資料：channel、message、membership、reaction、read cursor 與 external identity。這個格式版本與尚未版本化的 server API 無關。它不代表能匯出 host 業務資料、webhook history、operational handoff，或 Activity 與 Govern 擁有的資料。
刪除 user
DELETE /api/admin/users/{user_id}?tenant_id={tenant_id}
X-Admin-Token: <admin-token>User deletion 會在單一 database transaction 內完成。Relay 會：
- 將歷史 message 的 sender 與 audit actor 改成該 tenant 的 tombstone user；
- 刪除 membership、reaction、read cursor 與 external identity；
- tombstone 該 user 上傳的 attachment，並排入 object deletion；
- 刪除可歸屬於該 user 的 post-commit handoff 與 webhook dead letter。
歷史 message body 仍會保留，讓 shared conversation 保持原有 sequence 與 context。沒有 principal user 的 channel-level infrastructure row 不會被 user deletion 移除，會交由 retention 或 tenant removal 處理。
停用 tenant
POST /api/admin/tenants/{tenant_id}/disable
X-Admin-Token: <admin-token>Disable 會立即生效，且可安全重複呼叫。設定 disabled_at 後，新的 JWT verification 與 host credential sync 都會 fail closed。這個操作不會刪除 tenant schema 或仍在 retention 期限內的 operational data。
Relay 內部已有 hard-delete operation，依序停用流量、清除 public-schema artifact、刪除 tenant schema，最後刪除 tenant registry row。但它刻意沒有公開 HTTP endpoint，也不是目前支援的 operator command。Customer-facing tenant erasure workflow、completion receipt 與 recovery window 仍屬於 product work。
Audit surface
Control-plane event：
GET /api/admin/tenant_audit_events?tenant_id={tenant_id}&event=user_deleted&limit=50
X-Admin-Token: <admin-token>Message lifecycle event：
GET /api/admin/message_audit_events?tenant_id={tenant_id}&message_id={message_id}&limit=50
X-Admin-Token: <admin-token>兩個 endpoint 都以新到舊排序，並將 limit 限制在 1 到 200 之間，目前沒有 cursor pagination。Tenant audit row 包含 tenant_id、event、source_ip、user_agent 與 occurred_at。Message audit row 包含 message_id、actor_id、event、source、request metadata 與 occurred_at。
Evidence boundary
Relay audit record 能證明 Relay 接受並記錄了一次 transport 或 control-plane action。它不能證明 host 的 business authorization、message content 是否正確、是否經過 human review，或另一個 system 是否完成 execution。
目前的 audit table 是可查詢記錄，不是 tamper-evident ledger。它沒有 hash chain、external witness、immutable archive、export signature，也沒有公開的 message audit retention policy。如果 compliance program 需要這些性質，host 必須將 event 匯出至自己的 evidence system，或等待更完整的 Relay audit contract。