specsfy-specialist-supabase

Supabase

适用场景

• 当项目包含 supabase/config.toml、supabase/migrations/ 中的迁移，或使用 @supabase/supabase-js 客户端，且任务涉及 RLS、Auth、Storage、Realtime、Edge Functions 或 Supabase 本地环境（supabase start）时使用。
• 访问策略审查、RLS 策略缺失或错误，或 service_role 暴露不当时也使用。
• 如果只是调整底层 Postgres 的索引、执行计划或隔离级别，且没有 Supabase 上下文，则不要使用；改用 $specsfy-specialist-postgres，并将结果带回用于策略设计。
• 如果审查涉及 JWT、自定义 claims 或数据库以外的授权面，则结合 $specsfy-specialist-application-security 使用。

工作流

1. 确认使用的 SDK（@supabase/supabase-js、ssr、特定框架）、项目、通过 API 暴露的 schema、现有迁移，以及环境策略（本地、预览、生产）。
2. 梳理身份、租户、角色（anon、authenticated、自定义角色），以及每项访问决策所用 claim 的来源（auth.uid()、auth.jwt()、metadata）。
3. 首先在 Postgres 中建模表、函数和视图——REST/GraphQL API 和生成的类型都源自 schema，而不是反过来。
4. 为对象和每种操作（SELECT、INSERT、UPDATE、DELETE）及角色定义权限（GRANT）和 RLS 策略，默认拒绝访问。
5. 实现版本化迁移，并使用各角色的代表性用户进行测试，包括无会话（anon）的情况。
6. 仅在项目实际使用 Auth、Storage、Realtime 或 Edge Functions 时验证这些功能——不要配置应用未暴露的功能面。
7. 在认为项目就绪前，检查生成的 TypeScript 类型、连接池策略（session 或 transaction）、日志以及备份／回滚策略。

模式

• 对所有暴露给 API 的 schema 中的表启用 RLS，并默认拒绝访问——公开 schema 中禁用 RLS 的表，任何发现其名称的 anon 都可以访问。
• 绝不要在客户端（浏览器、移动应用、公开 bundle）中暴露 service_role；它会绕过 RLS，只能用于可信的服务器环境。
• 针对 anon、authenticated 和任何应用角色分别测试每项策略——看似有限制但使用 USING (true) 的策略，等同于没有策略。
• 将以下内容视为关键攻击面：SECURITY DEFINER 函数（以所有者而非调用者的权限运行，因此需要固定的 search_path 和内部验证）、JWT 中的自定义 claims（如果来源不可信，可能被篡改），以及标记为公开的 Storage bucket。
• 在迁移中记录所有 schema 变更（supabase migration new）；在生产环境的 dashboard 中手动编辑会导致历史记录不一致，并破坏 supabase db diff/CI。
• 区分产品授权（此用户可以对这条记录执行什么操作）与身份验证（用户是谁）——RLS 解决前者，Auth 解决后者。
• 根据工作负载和驱动程序，规划采用直接连接（少量持久连接、迁移）、session pool（兼容性广，PREPARE 可用）或 transaction pool（高并发、serverless）。

反模式

• 将 Policy USING (true)/WITH CHECK (true) 作为“临时”方案保留，以便推进开发，却从未在上线前复查——这等同于禁用了 RLS。
• 仅在客户端检查租户/所有权（在前端按 tenant_id 过滤查询），却没有相应的数据库 policy——任何直接调用 API 的请求都能绕过过滤。
• SECURITY DEFINER 函数没有设置 SET search_path = ''/固定 schema——调用方的 search_path 中其他 schema 内的同名对象可以劫持该函数。
• 通过 dashboard 手动在生产环境应用 migration，导致其与版本控制中的历史记录不一致——下一次 db push/db diff 无法协调实际状态。
• 信任 JWT 中的自定义 claim，却不验证其来源（例如，将用户自身可写入的字段用作授权角色）。

验证

• 对每种角色使用真实测试身份，证明允许和拒绝的访问行为，包括缺少会话时（anon）以及来自其他租户的“邻居”。
• 推广前在本地环境运行 supabase db reset/lint/migrations——本地项目应复现生产环境的 schema 和 policies。
• 检查生成的类型（supabase gen types）是否为最新版本、复制/Realtime 是否限制在同一租户模型内、Storage policies 是否按 bucket 设置，以及 Edge Functions 的密钥是否未进入源代码。
• 除了托管备份，还要评估数据恢复和导出能力——测试恢复或完整导出，不要假定自动备份就能保证可接受的 RTO。
• 如果没有进行负向测试（本应失败的访问确实失败），就不要声称某张表“受 RLS 保护”。

相关技能

• $specsfy-specialist-docker 涵盖本地服务和辅助镜像；本技能负责管理 Supabase 平台的托管契约。
• $specsfy-specialist-postgres 用于 Supabase 底层的 schema 建模、索引、查询计划和隔离。
• $specsfy-specialist-application-security 用于 RLS 之外的 JWT、claims 和授权面威胁建模。
• 当同一项目中还有 Laravel 后端使用 Supabase 之外的同一 Postgres 时，使用 $specsfy-specialist-laravel。

更改 RLS、Auth、暴露的 schemas、Storage、Realtime 或连接策略前，请先阅读 references/standards.md。