Supabase Storage bucket setup with RLS policies
epic-receipt-capture-and-attachment-foundation-task-004 — Configure the Supabase Storage bucket for receipt images using the org/user/claim-scoped path strategy: receipts/{org_id}/{user_id}/{claim_id}/{filename}. Define Row Level Security policies so users can only read and write their own org-scoped paths. Enable bucket-level policies that prevent cross-org access. Document the path convention for downstream consumers.
Acceptance Criteria
Technical Requirements
Implementation Notes
In Supabase RLS for Storage, policies reference the storage.objects table. The path column contains the full object key including bucket name prefix. Use a policy condition like: (storage.foldername(name))[1] = auth.uid()::text is NOT sufficient alone — org scoping requires checking that (storage.foldername(name))[1] matches the user's org_id from their profile or JWT claim. Prefer reading org_id from a server-side user_profiles table (auth.uid() lookup) inside the RLS policy to avoid JWT claim spoofing.
Coordinate with the auth team to ensure org_id is reliably available. For filename, enforce UUID v4 + extension (e.g., 550e8400-e29b-41d4-a716-446655440000.jpg) from the client side to prevent path traversal or conflicting filenames. Document in the migration file that the bucket name 'receipts' is intentionally lowercase and must match exactly in all SDK calls.
Testing Requirements
Manual verification required before any application code is written against this bucket: (1) use the Supabase dashboard Storage explorer to attempt an upload as user-A to user-B's path — confirm it is rejected with a 403; (2) attempt to read user-B's object as user-A — confirm 403; (3) upload a valid JPEG as user-A to their own path — confirm 200; (4) attempt upload of a .pdf file — confirm rejection. Capture screenshots or record the test session as evidence. These manual tests supplement the integration tests in task-015.
Supabase Storage RLS policies using org/user/claim path scoping may not enforce correctly if claim ownership is not present in the JWT or if path segments are constructed differently at upload vs. read time, leading to data leakage or access denial for legitimate users.
Mitigation & Contingency
Mitigation: Define and test RLS policies in isolation before wiring to app code. Write integration tests that assert cross-org and cross-user access is denied. Use service-role key only in edge functions, never in client code.
Contingency: If client-side RLS proves insufficient, route all storage reads through a Supabase Edge Function that validates ownership before generating signed URLs, adding a controlled server-side enforcement layer.
Aggressive image compression may reduce receipt legibility below the threshold required for financial auditing, causing claim rejections or compliance failures despite technically successful uploads.
Mitigation & Contingency
Mitigation: Define minimum legibility requirements with HLF finance team before implementation. Set compression targets conservatively (e.g., max 1MB, min 80% JPEG quality) and validate with sample receipt images. Provide compression statistics in verbose/debug mode.
Contingency: If post-compression quality is disputed by auditors, increase the quality floor at the cost of larger file sizes, and add a manual override allowing users to skip compression for PDFs and high-quality scans.
The Flutter image_picker package behaves differently on iOS 17+ (PHPicker) vs older Android (Intent-based), particularly for file types, permission flows, and PDF selection, which may cause platform-specific failures not caught in development.
Mitigation & Contingency
Mitigation: Test image picker integration on physical devices for both platforms early in the sprint. Pin the image_picker package version and review changelogs before updates. Write widget tests using mock file results for each platform branch.
Contingency: If PHPicker or Android Intent differences cause blocking issues, implement separate platform-specific picker delegates behind the unified interface, allowing platform-specific fixes without breaking the shared API.