lovable-cloud-edge-functions

Edge Function Authentication Framework

Background: see REFERENCES.md for the ES256/HS256 gateway constraint that shapes the tier table below.

Auth tiers

Tier 1: Browser-invoked functions

Functions called from the browser via supabase.functions.invoke().

Setting	Value
verify_jwt	false
In-code auth	User JWT validation (e.g., requireUserJwt() or equivalent)

Why: The browser sends an ES256 user JWT. The gateway cannot verify it. In-code auth is the only access control for these functions — there is no defense-in-depth layer. This makes in-code auth removal especially dangerous for browser-invoked functions.

These patterns were extracted from a production Lovable Cloud project and genericized. Adapt file paths and error-code namespaces for your project.

Your project will have its own auth utility location and naming convention for the user JWT validation helper.

In-code JWT validation must cryptographically verify the token signature (not just decode it) and check the exp claim. Decode-only is not sufficient — the gateway provides no backup for Tier 1.

Tier 2: Service-role / cron / trigger functions

Functions called by pg_cron, pg_net database triggers, or other edge functions using the service role key. Not called by browsers.

Setting	Value
verify_jwt	true
In-code auth	Service-role key validation (e.g., requireServiceRole() or equivalent)

Why: Service-role keys use HS256, which the gateway can verify. Both the gateway and in-code auth enforce access — defense in depth.

Caution: verify_jwt = true accepts any HS256-signed JWT — including anon-role tokens issued to ordinary unauthenticated browsers. In-code auth must verify the role claim equals service_role in the decoded JWT payload (not a caller-supplied header value). Omitting this check allows anon callers to invoke service-role functions.

Tier 3: Webhook functions

Functions called by external services (Stripe, Lovable, etc.) that cannot send a Supabase JWT of any kind.

Setting	Value
verify_jwt	false
In-code auth	Signature verification (Stripe signature, HMAC, etc.)

Why: External callers have no Supabase JWT. The function authenticates the caller by verifying a request signature specific to that service.

Critical: Signature verification must consume the raw request body (await req.arrayBuffer() or await req.text()) before any other body read. Parsing the body as JSON before signature verification corrupts the HMAC check — some implementations then silently fall through to processing the unverified payload.

Tier 4: Intentionally public functions

Functions that are designed to be publicly accessible (e.g., sitemap, health check).

Setting	Value
verify_jwt	false
In-code auth	None — but must not expose secrets or sensitive data

Why: No auth needed by design. The verify_jwt = false setting and absence of in-code auth must be justified with a comment in config.toml and in the function source.

config.toml rules

supabase/config.toml is security-critical infrastructure.

1. Never regenerate, overwrite, or remove entries from config.toml.
2. Every edge function in supabase/functions/ must have an explicit [functions.<name>] section with a verify_jwt setting.
3. Never bulk-flip existing verify_jwt entries. Each function's setting was chosen individually based on its tier. If a single function needs to change, change that one function and document why.
4. When changing a function's verify_jwt setting, verify it matches the correct tier above. Flipping a non-browser function from true to false removes a defense layer and requires justification.

Adding a new edge function

1. Determine the function's tier. If the caller is an external service (not a browser user, not your own cron/trigger, not an explicitly no-auth endpoint like a sitemap or health check) — it is Tier 3, not Tier 4. Both Tier 3 and Tier 4 use verify_jwt = false, so miscategorizing Tier 3 as Tier 4 produces a silently open endpoint. Default to Tier 3 when uncertain about external callers.
2. Add a [functions.<name>] entry to config.toml with the correct verify_jwt setting per the tier table above.
3. Add a comment above the entry if verify_jwt = false, stating which tier applies and why.
4. Add the corresponding in-code auth call for the tier.
5. For browser-invoked functions: in-code auth is the only control. Do not skip it.

In-code auth

Do not remove Authorization header validation or the in-code auth call from edge functions.

For browser-invoked functions (Tier 1), in-code auth is the sole access control — removing it makes the function fully open. This is more critical than for Tier 2 functions, where the gateway provides a backup layer.

For service-role functions (Tier 2), in-code auth is defense-in-depth on top of gateway verification. Both should be present.

Deployment: Lovable does NOT auto-deploy external changes

Edge functions added or modified by Claude Code or engineers are not automatically deployed by Lovable. After merging a PR that adds, modifies, or changes config.toml for edge functions, the user must explicitly ask Lovable to deploy them. This applies to:

• New edge functions (code + config.toml entry)
• Modified edge function code
• verify_jwt changes in config.toml

Tell the user to send Lovable: "Deploy these edge functions: <name1>, <name2>"

Without this step, the function code is in the repo but returns 404 (new functions) or runs with stale code/config (modified functions).