audit-pattern

Audit Pattern

D-pattern audit 是 clade 對 audit / operation log 的標準治理模式。決策已定： 不採 DB-only、evlog-only、雙寫並行；新建與升級都走 DB transactional outbox canonical、evlog derived stream、DB hash anchor。

Reference: docs/d-pattern-master-plan.md

三段定義

1. DB outbox canonical：audit row 與業務 mutation 必須在同一個 PostgreSQL transaction 內完成。business commit 成功時 audit row 必須存在；business rollback 時 audit row 也 rollback。
2. evlog derived stream：evlog 只從 canonical audit event 衍生，用於 ops、security monitoring、cross-service trace、短 TTL PII envelope。handler 不能只送 fire-and-forget audit event 就宣稱 audit 完成。
3. Hash anchor in DB：prev_hash 與 hash 直接寫在 canonical DB row。Cloudflare Workers 的 node:fs VFS 不是 durable journal，多 instance hash chain 也會 race，所以 hash chain 不依賴 fs journal。

Source-of-truth 規則：任何 audit 問題先查 DB row，evlog 是衍生視圖；evlog miss 是 monitoring 缺口，不改變 canonical audit truth。

MUST

• Audit canonical truth MUST live in DB transactional outbox。
• Audit row MUST 與業務 mutation 在同一個 PostgreSQL transaction 內完成；Supabase JS 多次 .from().insert() 不是 transaction，必要時用 SQL RPC。
• evlog audit events MUST 帶 auditEventId，且該值必須對應 DB canonical row 的 event_id。
• DB row MUST 包含 prev_hash / hash。
• DB row MUST NOT 包含 ip_address / user_agent / device fingerprint 等 PII 欄位。
• Multi-tenant consumer MUST 使用 per-tenant chain；實作可用 PostgreSQL advisory lock per tenant，或用 partition / tenant-scoped chain owner。
• business_keys MUST 只放結構化業務鍵，例如 invoiceId、reportVersion、policyVersion、rowCount。
• business_keys MUST NOT 放 PII、姓名、email、raw LLM prompt、raw request body、大型 payload。
• 拒絕操作（auth 失敗、role 失敗、policy deny、quota deny）MUST 呼叫 auditDeny()。
• requireAuth() / requireRole() / policy helper 若會拒絕使用者，失敗路徑 MUST 自動寫入 auditDeny()，不可要求每個 handler 手寫。
• Audit drain reliability MUST 透過 Postgres outbox dispatcher（claim_audit_outbox_batch + FOR UPDATE SKIP LOCKED + idempotent mark_audit_evlog_drained）；MUST NOT 依 tenant tier 或事件等級降級成 fire-and-forget evlog。Drain 端 MUST 以 auditEventId idempotently 去重（at-least-once 語意）。
• Atomicity 依事件 風險等級 分流，不依商業 tier：高風險 mutation（refund / billing、role / permission、data export、regulated report finalization、AI agent autonomous decision / tool invoke）MUST 用 SQL RPC 包 business mutation + audit insert 同 transaction；一般 CUD 用 helper baseline，但 audit insert MUST 緊接 business write，MUST NOT 先 response 或丟 background promise。
• Outbox dispatcher state MUST 放在 Postgres（evlog_drained_at / attempts / next_attempt_at / lease_until），MUST NOT 用 KV / D1 / Worker memory 作 durability source。LISTEN/NOTIFY、Realtime、Worker memory buffer 只能作 wake-up / best-effort signal，MUST NOT 被當成 durable queue。