rls-policy

RLS Policy

• NEVER 在 write policy 加 (SELECT auth.role()) = 'service_role' 當 bypass 條件 — Supabase service_role 具備 PostgreSQL BYPASSRLS，本來就略過所有 RLS，policy 內加這條件對 service role 沒有任何實際保護作用，只會讓後續 agent 誤以為 privileged write path 由 policy 控制。privileged 寫入的安全邊界見下方「service_role 與 privileged client isolation」。
• SELECT: TO public for client reads, TO authenticated for server-only
• UPDATE policy 需要搭配 SELECT policy — Postgres RLS 的 UPDATE 必須先 SELECT row，缺少 SELECT policy 會靜默回傳 0 rows（無報錯）
• Storage upsert 需要 INSERT + SELECT + UPDATE 三個 policy — 只有 INSERT 時新上傳正常，但覆蓋（upsert）會靜默失敗
• NEVER use user_metadata（raw_user_meta_data）in RLS policies — 使用者可自行修改，改用 app_metadata
• See supabase-rls skill for policy templates and TO public 陷阱

本檔是 clade 投影，NEVER 就地編輯。專案特化寫進自家 .cursor/rules/local/；要改本檔請回 clade 源檔並 propagate。

GRANT 先於 RLS——table privilege 驗證

PostgreSQL 先檢查 table-level privilege（GRANT）再評估 RLS policy。只建 CREATE POLICY ... TO authenticated 但沒有對應的 GRANT SELECT ON <table> TO authenticated，結果是 42501（permission denied），RLS policy 完全不被評估。

Migration 新增 RLS policy 時 MUST：

1. 同一支 migration 內顯式 GRANT <privilege> ON <table> TO <role>，或
2. 註明 table 已有既存 GRANT（引用授予 GRANT 的 migration 編號）

驗證方式——在 dev DB 查 pg_catalog：

SELECT grantee, privilege_type
FROM information_schema.role_table_grants
WHERE table_schema = '<schema>' AND table_name = '<table>';

若目標 role 不在結果中，RLS policy 寫再多都是死的。

靜默失敗陷阱

• auth.uid() IS NULL 陷阱 — 未認證時 auth.uid() 回傳 null，null = user_id 永遠 false，policy 靜默拒絕。要明確區分「沒登入」與「沒權限」，在 policy 開頭寫 auth.uid() IS NOT NULL AND ...
• DELETE 同理 UPDATE — 沒有 SELECT policy 時 DELETE 也靜默成功但不刪除任何 row
• 缺 TO role 指定的 policy 會對所有 role 執行 — 明確指定 TO authenticated 或 TO public，避免 anon 不必要地觸發 policy 評估
• Views 預設繞過 RLS — CREATE VIEW 必須加 WITH (security_invoker = true)，見 migration.md