Prevent Supabase Security Holes: Enforce Role Management and Service Key Usage with CLAUDE.md and Git Hooks

Workflow value: 85/100
Status: active · Freshness: 70/100 · Confidence: 0.90 · Level: intermediate
Categories: Quality Control, Context & Memory, Debugging, Shipping, CLAUDE.md, Hooks
Original source: r/ClaudeCode post/comment

What problem this solves

Preventing common Supabase security vulnerabilities related to misusing user_metadata for roles and exposing SUPABASE_SERVICE_ROLE_KEY in insecure locations.

Summary

This workflow establishes a two-pronged approach to enforce Supabase security best practices: a CLAUDE.md block documents the correct usage of app_metadata for roles and restricts service role key usage to admin API routes, while a pre-commit git hook automatically checks for and prevents the exposure of SUPABASE_SERVICE_ROLE_KEY in unauthorized files.

Why it is useful

This workflow is highly valuable because it addresses critical and common security vulnerabilities in Supabase projects with a concrete, multi-layered solution. It combines documentation (CLAUDE.md) for knowledge transfer and automated enforcement (git hook) to prevent mistakes, making it robust and repeatable. It helps developers avoid pitfalls often found in less secure tutorials and ensures best practices are maintained across a team.

Workflow

1. Create or update a CLAUDE.md block in your project's root or relevant documentation directory.
2. Document within CLAUDE.md that user roles must always reside in Supabase's app_metadata and be set exclusively by a secure server function.
3. Document within CLAUDE.md that the SUPABASE_SERVICE_ROLE_KEY must only be used within server-side route handlers located under app/api/admin/ (or equivalent secure admin directory).
4. Implement a pre-commit git hook in your project (e.g., in .git/hooks/pre-commit or via a husky setup).
5. Configure the git hook to execute a grep command that searches for SUPABASE_SERVICE_ROLE_KEY within all files under the app/ directory.
6. Ensure the grep command explicitly excludes the app/api/admin/ directory from its search.
7. Program the git hook to fail the commit if SUPABASE_SERVICE_ROLE_KEY is detected in any file outside of the designated app/api/admin/ path.

Tools / artifacts

• CLAUDE.md file
• Git pre-commit hook
• grep command
• Supabase app_metadata
• Supabase user_metadata
• SUPABASE_SERVICE_ROLE_KEY environment variable
• app/api/admin/ directory structure (or similar secure server-side directory)

Validation signals

• Explicitly states 'The fix that actually sticks' indicating practical validation.
• Identifies common pitfalls in Supabase tutorials and Stack Overflow answers, highlighting the need for a robust solution.

Limitations

• The exact script for the git hook is not provided, requiring the user to implement it based on the description.
• Assumes familiarity with git hooks and basic shell scripting (e.g., grep).
• The CLAUDE.md content is described conceptually rather than provided as a direct example.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.