supabase-postgres-best-practices/packages/evals/scenarios/storage-rls-user-folders.md

Scenario: storage-rls-user-folders

Summary

The agent must create a SQL migration that sets up Supabase Storage buckets with RLS policies for a user-content application. The migration must configure an avatars bucket (public reads, authenticated uploads restricted to user folders) and a documents bucket (fully private, user-isolated), with proper file type restrictions, storage helper functions in policies, and a file_metadata tracking table secured with RLS.

Real-World Justification

Why this is a common and important workflow:

1. Storage RLS is confusing and under-documented compared to table RLS -- Developers consistently struggle with the distinction between public/private buckets and the RLS policies needed on storage.objects. Multiple GitHub discussions show confusion about which SDK operations map to which SQL operations (INSERT, SELECT, UPDATE, DELETE).

   • Source: https://github.com/orgs/supabase/discussions/37611
   • Source: https://github.com/orgs/supabase/discussions/38700

2. User-folder isolation is the canonical storage security pattern -- The official Supabase docs demonstrate folder-based isolation using storage.foldername(name) and auth.uid()::text, but developers frequently get the casting or array indexing wrong.

   • Source: https://supabase.com/docs/guides/storage/security/access-control

3. Missing file type restrictions leads to security vulnerabilities -- Without allowed_mime_types on the bucket or extension checks in RLS policies, users can upload executable files or oversized payloads. The Supabase security best practices guide calls this out as a common oversight.

   • Source: https://supaexplorer.com/guides/supabase-security-best-practices
   • Source: https://supabase.com/docs/guides/storage/buckets/fundamentals

Skill References Exercised

Which reference files the agent should consult and what each teaches:

Reference File	What It Teaches	What the Agent Should Apply
references/storage-access-control.md	Bucket visibility, RLS on storage.objects, storage helper functions, SDK-to-SQL operation mapping	User-folder policies using storage.foldername(), separate SELECT/INSERT policies
references/db-rls-mandatory.md	RLS must be enabled on all public tables	Enable RLS on the file_metadata tracking table
references/db-rls-common-mistakes.md	Missing TO clause, missing SELECT policy for UPDATE	Use TO authenticated (or TO public for public reads), include SELECT policy
references/db-rls-performance.md	Wrap auth.uid() in SELECT subquery	Use (select auth.uid()) in both storage and table policies
references/db-schema-auth-fk.md	FK to auth.users with ON DELETE CASCADE	file_metadata.user_id references auth.users with cascade
references/db-schema-timestamps.md	Use timestamptz not timestamp	Time columns on file_metadata use timestamptz
references/db-perf-indexes.md	Index columns used in policy lookups	Index user_id on file_metadata
references/db-migrations-idempotent.md	IF NOT EXISTS for safe reruns	Idempotent DDL throughout

Workspace Setup

What the workspace starts with before the agent runs:

• Pre-initialized Supabase project (supabase/config.toml exists)
• Empty supabase/migrations/ directory
• The agent creates migration files within this structure

Agent Task (PROMPT.md draft)

The prompt to give the agent. Written as a developer would ask it:

I need to set up file storage for my app. There are two use cases:

1. Avatars -- Users upload a profile picture. Anyone can view avatars but only the owning user can upload or replace their own. Only allow image files (JPEG, PNG, WebP). Max 2MB.

2. Documents -- Users upload private documents that only they can access. Max 50MB. No file type restriction.

Create a SQL migration that:

• Configures both storage buckets
• Adds RLS policies on storage.objects so each user can only access their own folder (folder name = user ID)
• Creates a file_metadata table to track uploaded files (file name, bucket, size, user reference) with appropriate security

Users are authenticated via Supabase Auth.

Evaluation Criteria

What vitest should assert on the agent's output. Each assertion tests a specific quality signal:

#	Test Name	What It Checks	Quality Dimension
1	migration file exists	A .sql file exists in supabase/migrations/	structure
2	creates avatars bucket	SQL inserts into storage.buckets with id 'avatars' and public = true	correctness
3	creates documents bucket	SQL inserts into storage.buckets with id 'documents' and public = false	correctness
4	avatars bucket has mime type restriction	allowed_mime_types includes image types (jpeg, png, webp)	security
5	avatars bucket has file size limit	file_size_limit set (around 2MB / 2097152 bytes)	security
6	storage policy uses foldername or path for user isolation	Policy references storage.foldername(name) with auth.uid()::text	security
7	storage policy uses TO authenticated	Storage upload/delete policies scoped to TO authenticated	security
8	public read policy for avatars	A SELECT policy on storage.objects for avatars bucket allows public/anon access	correctness
9	documents bucket is fully private	Policies for documents bucket restrict all operations to authenticated owner	security
10	creates file_metadata table	SQL contains CREATE TABLE for file_metadata	correctness
11	file_metadata has FK to auth.users with CASCADE	REFERENCES auth.users with ON DELETE CASCADE	correctness
12	RLS enabled on file_metadata	ALTER TABLE file_metadata ENABLE ROW LEVEL SECURITY	security
13	file_metadata policies use (select auth.uid())	Subselect form in policies	performance
14	uses timestamptz for time columns	No plain timestamp in file_metadata	correctness
15	index on file_metadata user_id	CREATE INDEX on user_id column	performance
16	idempotent DDL	Uses IF NOT EXISTS patterns	idempotency
17	overall quality score	At least 11/15 best-practice signals present	overall

Reasoning

Step-by-step reasoning for why this scenario is well-designed:

1. Baseline differentiator: An agent without the skill would likely: (a) confuse public bucket visibility with unrestricted upload access, (b) write storage policies without using storage.foldername() or get the array indexing wrong, (c) forget to set allowed_mime_types on the bucket itself, (d) omit the TO authenticated clause on storage policies, (e) use bare auth.uid() instead of the subselect form, (f) skip the ::text cast when comparing auth.uid() to folder names. These are all Supabase-specific patterns that require reading the skill references.

2. Skill value: The storage-access-control reference explicitly documents: the public vs private bucket distinction, the storage.foldername() helper function pattern, the SDK-to-SQL operation mapping, and bucket configuration with mime types and size limits. Combined with the database security references (RLS mandatory, common mistakes, performance), this scenario exercises 8 reference files.

3. Testability: Bucket configuration (INSERT INTO storage.buckets), storage helper function usage (storage.foldername), policy clauses (TO authenticated, TO public), mime types, file size limits, and all table-level patterns (RLS, FK, indexes, timestamptz) are reliably detectable via regex on SQL text.

4. Realism: Nearly every Supabase application that handles user-generated content needs avatar uploads and document storage. This is a day-one task for any SaaS product. The GitHub discussions linked above show dozens of developers hitting exactly these issues when setting up storage for the first time.

Difficulty

Rating: MEDIUM

• Without skill: ~30-45% of assertions expected to pass
• With skill: ~85-95% of assertions expected to pass
• pass_threshold: 14