api-patterns

API Patterns

MUST define request/response contracts in shared/schemas/* and derive exported types from the same module MUST use Zod validation for all API inputs — getValidatedQuery(event, schema.parse) / readValidatedBody(event, schema.parse) MUST call requireAuth() or requireRole() before any business logic MUST use getSupabaseWithContext(event) for request-scoped database access

Helper 名依 modules.auth 而異：本檔以 getSupabaseWithContext(event) 為 canonical 名。當 consumer 的 .claude/hub.json modules.auth 是 better-auth 或 nuxt-auth-utils 時，等價 helper 是 getAuthedSupabase(event) —— 那些 auth stack 下 Supabase 不簽 JWT，auth.uid() 恆 null，helper 只驗 session 不做授權，名字必須說實話。兩者回傳形狀相同（{ client, user }）。見 [[auth-data-path-consistency]] § Server 側：RLS policy 的前提條件。 MUST parse outgoing handler payloads with response schema parse() before returning NEVER use getServerSupabaseClient() as the default path in request handlers — reserve it for privileged system tasks MUST log mutations to audit table — 表名與欄位慣例見 db-schema/<variant>/audit-schema.md MUST use unified response format { data, pagination? } NEVER return raw database errors to client — use handleDbError() + createError() with user-friendly message MUST const log = useLogger(event) as first line — see logging.md for evlog patterns

Reference: docs/api/API_DESIGN_GUIDE.md — 完整 API 設計指南含進階模式

本檔為 starter template 的預設規則，複製出去後依專案實際使用調整。

OWASP API Authorization

requireAuth() / requireRole()（垂直權限）不足以擋 OWASP API Top 10 的授權類風險 — 一個 authenticated 使用者仍可能存取別人的物件、寫入不該由 client 設定的欄位、或濫用端點。每個 state-changing / 敏感讀取 endpoint MUST 同時具備 authz + input-shape + abuse-control 三層：

Authz 層

• Object-level authorization（BOLA / IDOR）：MUST 對 request 帶的每個 resource id（:id、body 內 targetId 等）驗證當前使用者是否真的有權存取該筆 row（ownership / tenant / role scope），NEVER 只因為 id 存在就回傳 / 修改。做法：查詢時把 scope 條件放進 WHERE（.eq('tenant_id', user.tenantId) / .eq('owner_id', user.id)），或先 fetch 再比對再操作。BOLA 是最常見的 API 漏洞 — requireAuth() 過了不代表這個 user 能碰這筆 row。
• Property-level authorization（BOPLA / mass assignment）：MUST 用明確的欄位 allowlist 決定使用者能讀 / 寫哪些欄位，NEVER 直接把 readBody() 整包 spread 進 .update() / .insert()（update({ ...body })）。做法：Zod schema 只 .pick() 允許的欄位，或手動列 { title: body.title, note: body.note }。防止使用者偷塞 role / is_admin / tenant_id / price / status 等不該由 client 設定的欄位（mass assignment），也防止 response 回傳不該給該 role 看的欄位（over-exposure）。