optimise media uploads

Author: dnywh

.env.example

@@ -11,6 +11,7 @@ NEXT_PUBLIC_SITE_URL=http://localhost:3000
 # 5. Paste NEXT_PUBLIC_SUPABASE_ANON_KEY below
 NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331
 NEXT_PUBLIC_SUPABASE_ANON_KEY=
+SUPABASE_SERVICE_ROLE_KEY=
 
 # For contributors: Either follow the below forking instructions or ask the project maintainers for the shared development key
 # For forking: Get your own free API key at https://cloud.maptiler.com/

.gitignore

@@ -15,6 +15,7 @@
 # next.js
 /.next/
 /out/
+peels-org/dist/
 /.swc/
 
 # production

README.md

@@ -82,6 +82,7 @@ For local-first Supabase development:
 3. Run `npm run supabase:env`
 4. Make sure `.env.local` contains the local URL `NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331`
 5. Copy the local `ANON_KEY` value into `NEXT_PUBLIC_SUPABASE_ANON_KEY` in `.env.local`
+6. Copy the local `SERVICE_ROLE_KEY` value into `SUPABASE_SERVICE_ROLE_KEY` in `.env.local`
 
 The repo defaults `NEXT_PUBLIC_SUPABASE_URL` to `http://127.0.0.1:54331` so local development does not need to point at the hosted Peels project. If you already had a `.env.local` from hosted development, update that value manually because copying `.env.example` later may not overwrite your existing file.
 Peels intentionally uses the `54331`-`54334` local port range so it can run alongside other Supabase projects that still use the CLI defaults.
@@ -108,6 +109,7 @@ For how auth/session forwarding, public-page performance, footer locale state, u
    - Run `npm run supabase:env`
    - Confirm `.env.local` uses `NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331`
    - Copy the local `ANON_KEY` into `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+   - Copy the local `SERVICE_ROLE_KEY` into `SUPABASE_SERVICE_ROLE_KEY`
 
 3. Start development:
 
@@ -272,13 +274,15 @@ Before `npm run test:e2e` or `npm run test:e2e:prod`, make sure you are using th
 - Run `npm run supabase:env`
 - Make sure `.env.local` uses `NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331`
 - Copy the local `ANON_KEY` into `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+- Copy the local `SERVICE_ROLE_KEY` into `SUPABASE_SERVICE_ROLE_KEY`
 
 If your `.env.local` was previously set up for the hosted Peels project, update it before running Playwright. A working local test setup looks like:
 
 ```bash
 NEXT_PUBLIC_SITE_URL=http://127.0.0.1:3000
 NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331
 NEXT_PUBLIC_SUPABASE_ANON_KEY=<paste the ANON_KEY from npm run supabase:env>
+SUPABASE_SERVICE_ROLE_KEY=<paste the SERVICE_ROLE_KEY from npm run supabase:env>
 ```
 
 Then run either:

docs/supabase-data-architecture.md

@@ -180,6 +180,31 @@ User-uploaded media lives in public Storage buckets, but the canonical
 references live in `public.profiles.avatar`, `public.listings.avatar`, and
 `public.listings.photos`.
 
+### Media write boundary
+
+Browser clients must not write Storage objects or media reference columns
+directly. Media writes go through `src/app/api/media/upload/route.ts`, which
+authenticates the user, optimises the image, writes the Storage object with the
+service-role client, and then updates the matching profile/listing reference
+after ownership checks.
+
+For new listings, uploads happen before the listing row exists. Those temporary
+uploads are tracked in `public.pending_media_uploads`, keyed by user, bucket,
+kind, and path. The table is server-owned: authenticated clients cannot insert,
+update, or delete rows directly. When the listing is saved, the server action
+validates that every submitted media path belongs to that user's pending upload
+set before attaching it to the new listing.
+
+Direct authenticated writes to `public.profiles.avatar`,
+`public.listings.avatar`, and `public.listings.photos` are revoked. This is
+important because delete routes remove files with the service-role Storage
+client; the app must never treat a client-forged media path as proof of
+ownership.
+
+Listing photo append/remove operations use RPCs so array changes are atomic.
+Those RPCs are service-role only and are called from the media route after the
+route has verified the signed-in user owns the listing.
+
 Listing and account deletion should clean up media through the Edge Functions
 before the database rows are deleted:
 
@@ -192,6 +217,10 @@ Do not add a Postgres Cron job that deletes from `storage.objects`. Supabase
 Storage object deletion must go through the Storage API; deleting rows from
 `storage.objects` only removes metadata and can leave object bytes behind.
 
+Pending uploads are treated as active for one day. After that, abandoned
+new-listing uploads can be reported by the orphan cleanup tooling and removed
+through the Storage API.
+
 For historical orphans, first inspect the read-only helper:
 
 ```sql
@@ -206,7 +235,25 @@ npm run media:cleanup-orphans
 
 For hosted environments, pass the project URL and service-role key explicitly
 and include `--allow-remote`. Deletion requires both `--delete-orphans` and
-`--confirm-delete-orphans`; this keeps the default path inspect-only.
+`--confirm-delete-orphans`, plus an explicit `--before` cutoff; this keeps the
+default path inspect-only and protects in-flight uploads whose database
+references have not been written yet.
+
+Example production dry run:
+
+```sh
+SUPABASE_URL="https://YOUR_PROJECT.supabase.co" \
+SUPABASE_SERVICE_ROLE_KEY="YOUR_SERVICE_ROLE_KEY" \
+npm run media:cleanup-orphans -- --allow-remote --before=2026-05-18
+```
+
+Example production deletion after reviewing the dry-run output:
+
+```sh
+SUPABASE_URL="https://YOUR_PROJECT.supabase.co" \
+SUPABASE_SERVICE_ROLE_KEY="YOUR_SERVICE_ROLE_KEY" \
+npm run media:cleanup-orphans -- --allow-remote --before=2026-05-18 --delete-orphans --confirm-delete-orphans
+```
 
 Storage folder placeholders such as `.emptyFolderPlaceholder` are Supabase
 folder bookkeeping objects, not user media. The helper and cleanup script ignore

docs/supabase-local-first.md

@@ -178,8 +178,9 @@ Use this when setting up Peels on a new machine.
 7. Run `npm run supabase:env`.
 8. Set `NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54331` in `.env.local`.
 9. Copy the printed `ANON_KEY` into `NEXT_PUBLIC_SUPABASE_ANON_KEY` in `.env.local`.
-10. Run `npm run dev`.
-11. Sign in with one of the demo accounts above.
+10. Copy the printed `SERVICE_ROLE_KEY` into `SUPABASE_SERVICE_ROLE_KEY` in `.env.local`.
+11. Run `npm run dev`.
+12. Sign in with one of the demo accounts above.
 
 If the app still shows old environment values, clear the build cache and restart:
 

e2e/listings.spec.ts

@@ -66,6 +66,30 @@ test("listing type chooser routes signed-in hosts to the selected form", async (
   await expect(page.locator("#name")).toBeVisible();
 });
 
+test("listing type chooser hides residential option at the residential limit", async ({
+  page,
+}) => {
+  await signIn(page, {
+    email: DONOR_EMAIL,
+    redirectTo: "/profile/listings/new?type=host",
+  });
+
+  const chooser = page.getByTestId("listing-type-chooser");
+  const communityOption = page.getByTestId("listing-type-option-community");
+  const continueButton = page.getByTestId("listing-type-chooser-submit");
+
+  await expect(chooser).toBeVisible();
+  await expect(page.getByTestId("listing-type-option-residential")).toHaveCount(
+    0
+  );
+  await expect(communityOption).toBeVisible();
+  await communityOption.click();
+  await expect(continueButton).toBeEnabled();
+  await continueButton.click();
+
+  await expect(page).toHaveURL(/\/profile\/listings\/new\/community$/);
+});
+
 test("new listing form shows validation feedback when location is missing", async ({
   page,
 }) => {

e2e/map.spec.ts

@@ -135,6 +135,19 @@ async function zoomInUntilMapPinsAreDetailed(page: Page) {
   await expectMapPinDetailScale(page, 1);
 }
 
+async function focusMapControlByKeyboard(page: Page, testId: string) {
+  for (let i = 0; i < 20; i += 1) {
+    await page.keyboard.press("Tab");
+    const activeTestId = await page.evaluate(() =>
+      document.activeElement?.getAttribute("data-testid")
+    );
+
+    if (activeTestId === testId) return;
+  }
+
+  throw new Error(`Could not focus ${testId} by keyboard`);
+}
+
 test("map mounts when IP location is unavailable and restores the last view", async ({
   page,
 }) => {
@@ -155,6 +168,25 @@ test("map mounts when IP location is unavailable and restores the last view", as
     });
     expect(await readStoredMapView(page)).toBeNull();
 
+    await focusMapControlByKeyboard(page, "map-control-search");
+    await expect(page.getByTestId("map-control-search")).toBeFocused();
+    await expect
+      .poll(() =>
+        page
+          .getByTestId("map-control-search")
+          .evaluate((element) => getComputedStyle(element).boxShadow)
+      )
+      .toContain("inset");
+    await focusMapControlByKeyboard(page, "map-control-zoom-in");
+    await expect(page.getByTestId("map-control-zoom-in")).toBeFocused();
+    await expect
+      .poll(() =>
+        page
+          .getByTestId("map-control-zoom-in")
+          .evaluate((element) => getComputedStyle(element).boxShadow)
+      )
+      .toContain("inset");
+
     await page.getByTestId("map-control-zoom-in").click();
 
     await expect
@@ -264,6 +296,12 @@ test("map search palette flies to a picked geocoding result", async ({
   await page.getByTestId("map-control-search").click();
   const searchInput = page.getByTestId("geocoding-search-input");
   await expect(searchInput).toBeFocused();
+  await expect(page.getByTestId("map-search-close")).toHaveCount(0);
+  await page.keyboard.press("Escape");
+  await expect(page.getByTestId("map-search-dialog")).toBeHidden();
+
+  await page.getByTestId("map-control-search").click();
+  await expect(searchInput).toBeFocused();
   await searchInput.fill("Newtown");
   await expect
     .poll(async () =>