chore(main): release 3.105.1-beta.0 (#1066)

* fix(gallery): make per-event banner overrides actually work, both banners (#440, #932)

The promo banner shipped with a per-event inherit/custom/off override that
never reached a guest. GalleryView reads promo_mode from the /photos payload,
and /photos never sent it — so every gallery resolved to 'inherit'. Setting a
gallery's promo banner to "Off" did nothing; the global banner kept rendering.
The info banner (#932) mirrored that shape and inherited the same gaps.

Four places dropped the fields; all four now carry both banners:

1. GET /gallery/:slug/photos — send promo_mode/promo_markdown alongside the
   info fields. This is the fix that makes "Off" mean off.
2. POST /admin/events — the validators accepted both banners and the insert
   discarded them, so an API client could POST info_mode:'off', get 201, and
   find the row on 'inherit'. Markdown is stored only for 'custom', matching
   the PUT rule.
3. POST /admin/events/:id/duplicate — copy both from the source row. The
   dialog promises the copy "inherits the branding, behaviour, feedback, and
   category configuration"; a muted gallery un-muting on duplication is the
   opposite of that.
4. PUT /admin/events/:id — resolve the effective mode from the STORED row when
   a partial update sends only the markdown. Previously updates.promo_mode was
   undefined on such a request and the text was parked on an inherit/off
   gallery, then resurfaced when someone later switched it to 'custom'. The
   lookup is lazy: one extra query, only on that path.

The two normalisation blocks are now one loop over both banners, so the pair
can't drift apart again.

Verified in a browser, both directions against the same global banner:
promo_mode='off' -> not rendered; 'inherit' -> rendered. The /photos payload
went from promo_mode ABSENT to carrying the value.

* fix(gallery): thread promo into the reveal view, drop stale markdown on duplicate

External review, round 1 on this PR. Two gaps in the plumbing it introduced:

- The reveal-hidden branch copied only the info fields from /photos. Now that
  /photos carries promo too, a reveal-hidden gallery with promo_mode 'off'
  still fell back to 'inherit' and showed the global banner on the first load
  after login. Thread both banners there.

- The duplicate copied markdown verbatim. A row written before the PUT
  normalisation landed can hold text while its mode is 'inherit'/'off', so the
  copy inherited hidden text that would resurface the moment someone switched
  it to 'custom' — violating the very invariant this PR establishes. Copy
  markdown only when the source mode is 'custom'.

Test covers the stale-markdown source explicitly.

---------

Co-authored-by: Paul Nothaft <paul@MacStudio-von-Paul.local>

.env.example

@@ -10,6 +10,14 @@ NODE_ENV=production
 # Generate one with: openssl rand -base64 64
 #JWT_SECRET=your_very_long_random_jwt_secret_here
 
+# OIDC SSO for admins (#798) — configured in the admin UI; only these two
+# values live in the environment:
+# Key encrypting the OIDC client secret at rest (defaults to JWT_SECRET).
+#OIDC_ENCRYPTION_KEY=
+# Break-glass: 'true' re-enables local password login even while the SSO
+# settings disable it (recovery when the IdP is down or misconfigured).
+#OIDC_BREAK_GLASS=false
+
 # Auth cookie Secure flag
 #   unset  - default: follows NODE_ENV (production=true, dev=false)
 #   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access)
@@ -107,6 +115,11 @@ VITE_API_URL=/api
 # DB_PORT=5432
 # REDIS_PORT=6379
 
+# File watcher (watch-folder auto-import, local storage only)
+# Max photos processed in parallel — raise on hosts with memory headroom,
+# lower to 1 on very small hosts. Default: 2
+# FILE_WATCHER_CONCURRENCY=2
+
 # Release Channel
 # Options: 'stable' (default), 'beta', or specific version like 'v2.3.0'
 # 'stable' uses the :stable tag (same as :latest on main)

.github/workflows/docker-build.yml

@@ -95,6 +95,15 @@ jobs:
         repo_lc="${GITHUB_REPOSITORY,,}"
         echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
         echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+        # Mirror manifests to Docker Hub (picpeak/{backend,frontend}) only on the
+        # canonical org repo, where the DOCKERHUB_* secrets live. Forks (and any
+        # other owner) fall back to GHCR-only — the Docker Hub image line and login
+        # are gated on this flag so their builds keep working unchanged.
+        if [[ "$GITHUB_REPOSITORY" == "PicPeak/picpeak" ]]; then
+          echo "DOCKERHUB_ENABLED=true" >> "$GITHUB_ENV"
+        else
+          echo "DOCKERHUB_ENABLED=false" >> "$GITHUB_ENV"
+        fi
 
     - name: Prepare platform pair
       run: |
@@ -203,14 +212,6 @@ jobs:
         format: 'sarif'
         output: 'trivy-backend-${{ env.PLATFORM_PAIR }}.sarif'
         severity: 'CRITICAL,HIGH'
-        # Base-image CVEs with no released fix are not actionable: the
-        # Dockerfiles already run `apt-get upgrade -y` behind a CACHEBUST,
-        # so a fix lands in the next build automatically. Reporting them
-        # buries the findings someone can actually do something about.
-        # Dropping them is also the precondition for ever setting
-        # exit-code: 1, which build-backend's comment flags as a
-        # deliberate follow-up.
-        ignore-unfixed: true
         timeout: '10m'
 
     - name: Upload Trivy scan results to GitHub Security tab
@@ -241,6 +242,15 @@ jobs:
         repo_lc="${GITHUB_REPOSITORY,,}"
         echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
         echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+        # Mirror manifests to Docker Hub (picpeak/{backend,frontend}) only on the
+        # canonical org repo, where the DOCKERHUB_* secrets live. Forks (and any
+        # other owner) fall back to GHCR-only — the Docker Hub image line and login
+        # are gated on this flag so their builds keep working unchanged.
+        if [[ "$GITHUB_REPOSITORY" == "PicPeak/picpeak" ]]; then
+          echo "DOCKERHUB_ENABLED=true" >> "$GITHUB_ENV"
+        else
+          echo "DOCKERHUB_ENABLED=false" >> "$GITHUB_ENV"
+        fi
 
     - name: Download digest artifacts
       uses: actions/download-artifact@v4
@@ -274,11 +284,24 @@ jobs:
           echo "is_prerelease=false" >> $GITHUB_OUTPUT
         fi
 
+    - name: Log in to Docker Hub
+      if: env.DOCKERHUB_ENABLED == 'true'
+      uses: docker/login-action@v3
+      with:
+        registry: docker.io
+        username: ${{ secrets.DOCKERHUB_USERNAME }}
+        password: ${{ secrets.DOCKERHUB_TOKEN }}
+
     - name: Extract metadata for Backend
       id: meta-backend
       uses: docker/metadata-action@v5
       with:
-        images: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}
+        # GHCR always; Docker Hub (picpeak/backend) added on the canonical repo so
+        # the same tag scheme is mirrored to both registries. metadata-action drops
+        # the blank second line on forks → GHCR-only there.
+        images: |
+          ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}
+          ${{ env.DOCKERHUB_ENABLED == 'true' && 'docker.io/picpeak/backend' || '' }}
         labels: |
           org.opencontainers.image.title=PicPeak Backend
           org.opencontainers.image.description=PicPeak photo sharing platform backend service
@@ -290,6 +313,10 @@ jobs:
           type=semver,pattern={{version}}
           type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
           type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          # #668/#783: publish the git-tag name verbatim (v3.45.0 / v3.84.0-beta.0)
+          # so users can pin the same string as the GitHub release. metadata-action's
+          # `pattern=v{{version}}` silently dropped it on prereleases, so use type=ref.
+          type=ref,event=tag
           type=sha,format=short
           # `:latest` + `:stable` follow the stable channel (the `stable` branch +
           # stable release tags). The default branch is now `main` (active dev),
@@ -306,10 +333,15 @@ jobs:
         docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
           $(printf "${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}@sha256:%s " *)
 
-    - name: Inspect manifest
+    - name: Inspect manifest (GHCR)
       run: |
         docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}:${{ steps.meta-backend.outputs.version }}
 
+    - name: Inspect manifest (Docker Hub)
+      if: env.DOCKERHUB_ENABLED == 'true'
+      run: |
+        docker buildx imagetools inspect docker.io/picpeak/backend:${{ steps.meta-backend.outputs.version }}
+
   # -----------------------------------------------------------------------------
   # Frontend: per-arch build, then merge into a multi-arch manifest
   # -----------------------------------------------------------------------------
@@ -339,6 +371,15 @@ jobs:
         repo_lc="${GITHUB_REPOSITORY,,}"
         echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
         echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+        # Mirror manifests to Docker Hub (picpeak/{backend,frontend}) only on the
+        # canonical org repo, where the DOCKERHUB_* secrets live. Forks (and any
+        # other owner) fall back to GHCR-only — the Docker Hub image line and login
+        # are gated on this flag so their builds keep working unchanged.
+        if [[ "$GITHUB_REPOSITORY" == "PicPeak/picpeak" ]]; then
+          echo "DOCKERHUB_ENABLED=true" >> "$GITHUB_ENV"
+        else
+          echo "DOCKERHUB_ENABLED=false" >> "$GITHUB_ENV"
+        fi
 
     - name: Prepare platform pair
       run: |
@@ -433,14 +474,6 @@ jobs:
         format: 'sarif'
         output: 'trivy-frontend-${{ env.PLATFORM_PAIR }}.sarif'
         severity: 'CRITICAL,HIGH'
-        # Base-image CVEs with no released fix are not actionable: the
-        # Dockerfiles already run `apt-get upgrade -y` behind a CACHEBUST,
-        # so a fix lands in the next build automatically. Reporting them
-        # buries the findings someone can actually do something about.
-        # Dropping them is also the precondition for ever setting
-        # exit-code: 1, which build-backend's comment flags as a
-        # deliberate follow-up.
-        ignore-unfixed: true
         timeout: '10m'
 
     - name: Upload Trivy scan results to GitHub Security tab
@@ -466,6 +499,15 @@ jobs:
         repo_lc="${GITHUB_REPOSITORY,,}"
         echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
         echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+        # Mirror manifests to Docker Hub (picpeak/{backend,frontend}) only on the
+        # canonical org repo, where the DOCKERHUB_* secrets live. Forks (and any
+        # other owner) fall back to GHCR-only — the Docker Hub image line and login
+        # are gated on this flag so their builds keep working unchanged.
+        if [[ "$GITHUB_REPOSITORY" == "PicPeak/picpeak" ]]; then
+          echo "DOCKERHUB_ENABLED=true" >> "$GITHUB_ENV"
+        else
+          echo "DOCKERHUB_ENABLED=false" >> "$GITHUB_ENV"
+        fi
 
     - name: Download digest artifacts
       uses: actions/download-artifact@v4
@@ -499,11 +541,24 @@ jobs:
           echo "is_prerelease=false" >> $GITHUB_OUTPUT
         fi
 
+    - name: Log in to Docker Hub
+      if: env.DOCKERHUB_ENABLED == 'true'
+      uses: docker/login-action@v3
+      with:
+        registry: docker.io
+        username: ${{ secrets.DOCKERHUB_USERNAME }}
+        password: ${{ secrets.DOCKERHUB_TOKEN }}
+
     - name: Extract metadata for Frontend
       id: meta-frontend
       uses: docker/metadata-action@v5
       with:
-        images: ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}
+        # GHCR always; Docker Hub (picpeak/frontend) added on the canonical repo so
+        # the same tag scheme is mirrored to both registries. metadata-action drops
+        # the blank second line on forks → GHCR-only there.
+        images: |
+          ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}
+          ${{ env.DOCKERHUB_ENABLED == 'true' && 'docker.io/picpeak/frontend' || '' }}
         labels: |
           org.opencontainers.image.title=PicPeak Frontend
           org.opencontainers.image.description=PicPeak photo sharing platform frontend application
@@ -515,6 +570,10 @@ jobs:
           type=semver,pattern={{version}}
           type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
           type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          # #668/#783: publish the git-tag name verbatim (v3.45.0 / v3.84.0-beta.0)
+          # so users can pin the same string as the GitHub release. metadata-action's
+          # `pattern=v{{version}}` silently dropped it on prereleases, so use type=ref.
+          type=ref,event=tag
           type=sha,format=short
           # `:latest` + `:stable` follow the stable channel (the `stable` branch +
           # stable release tags). The default branch is now `main` (active dev),
@@ -531,10 +590,15 @@ jobs:
         docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
           $(printf "${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}@sha256:%s " *)
 
-    - name: Inspect manifest
+    - name: Inspect manifest (GHCR)
       run: |
         docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}:${{ steps.meta-frontend.outputs.version }}
 
+    - name: Inspect manifest (Docker Hub)
+      if: env.DOCKERHUB_ENABLED == 'true'
+      run: |
+        docker buildx imagetools inspect docker.io/picpeak/frontend:${{ steps.meta-frontend.outputs.version }}
+
   summary:
     needs: [build-backend, merge-backend, build-frontend, merge-frontend]
     if: always()
@@ -548,6 +612,15 @@ jobs:
         repo_lc="${GITHUB_REPOSITORY,,}"
         echo "BACKEND_IMAGE_NAME=${repo_lc}/backend" >> "$GITHUB_ENV"
         echo "FRONTEND_IMAGE_NAME=${repo_lc}/frontend" >> "$GITHUB_ENV"
+        # Mirror manifests to Docker Hub (picpeak/{backend,frontend}) only on the
+        # canonical org repo, where the DOCKERHUB_* secrets live. Forks (and any
+        # other owner) fall back to GHCR-only — the Docker Hub image line and login
+        # are gated on this flag so their builds keep working unchanged.
+        if [[ "$GITHUB_REPOSITORY" == "PicPeak/picpeak" ]]; then
+          echo "DOCKERHUB_ENABLED=true" >> "$GITHUB_ENV"
+        else
+          echo "DOCKERHUB_ENABLED=false" >> "$GITHUB_ENV"
+        fi
 
     - name: Build Summary
       run: |
@@ -586,6 +659,10 @@ jobs:
         echo "### 📦 Images" >> $GITHUB_STEP_SUMMARY
         echo "- Backend: \`${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE_NAME }}\`" >> $GITHUB_STEP_SUMMARY
         echo "- Frontend: \`${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE_NAME }}\`" >> $GITHUB_STEP_SUMMARY
+        if [[ "$DOCKERHUB_ENABLED" == "true" ]]; then
+          echo "- Backend (Docker Hub): \`docker.io/picpeak/backend\`" >> $GITHUB_STEP_SUMMARY
+          echo "- Frontend (Docker Hub): \`docker.io/picpeak/frontend\`" >> $GITHUB_STEP_SUMMARY
+        fi
 
         echo "" >> $GITHUB_STEP_SUMMARY
         echo "### 🏗️ Architectures" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -131,7 +131,5 @@ docker-compose.dev.yml
 new-layouts/
 
 # Backend runtime storage (generated media, previews, thumbnails,
-# CRM/accounting documents) — never commit. Matches main: a dev instance
-# writes event photos into backend/storage/, and the narrower
-# business-docs-only rule let `git add -A` sweep them into a commit.
+# CRM/accounting documents) — never commit
 backend/storage/

.release-please-manifest-beta.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.83.0-beta.0"
+  ".": "3.105.1-beta.0"
 }

.release-please-manifest.json

@@ -1 +1 @@
-{".":"3.46.5"}
+{".":"3.44.0"}

README.md

@@ -1,90 +1,48 @@
-# 📸 PicPeak - Open Source Photo Sharing for Events
-
-> [!IMPORTANT]
-> **PicPeak has moved to its own GitHub organization.**
->
-> - **Docker images** are now published at `ghcr.io/picpeak/picpeak/{backend,frontend}`. The old path (`ghcr.io/the-luap/picpeak/...`) is no longer served — update your `docker-compose.yml`.
-> - **Branches**: active development is now on `main` (was `beta`); the curated stable channel is now `stable` (was `main`). Existing PRs and clones auto-redirect via GitHub.
->
-> See **[`docs/migration-to-org.md`](docs/migration-to-org.md)** for the one-line `docker-compose.yml` edit and full details.
-
 <div align="center">
   <img src="docs/picpeak-logo.png" alt="PicPeak Logo" width="300" />
-  
+
+  # 📸 PicPeak
+
+  **Open-source, self-hosted photo sharing for events.**
+
   [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
   [![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://www.docker.com/)
-  [![Node.js](https://img.shields.io/badge/node.js-6DA55F?style=flat&logo=node.js&logoColor=white)](https://nodejs.org/)
-  [![React](https://img.shields.io/badge/react-%2320232a.svg?style=flat&logo=react&logoColor=%2361DAFB)](https://reactjs.org/)
   [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-theluap-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/theluap)
 
-  [Homepage](https://www.picpeak.app) · [Live Demo](https://demo.picpeak.app) · [Documentation](https://docs.picpeak.app) · [Support the project ☕](https://buymeacoffee.com/theluap)
+  [Homepage](https://www.picpeak.app) · [Live Demo](https://demo.picpeak.app) · [Documentation](https://docs.picpeak.app) · [Support ☕](https://buymeacoffee.com/theluap)
 </div>
 
-**PicPeak** is a powerful, self-hosted open-source alternative to commercial photo-sharing platforms like PicDrop.com and Scrapbook.de. Designed specifically for photographers and event organizers, PicPeak makes it simple to share beautiful, time-limited photo galleries with clients while maintaining full control over your data and branding.
+---
+
+**PicPeak** is a powerful, self-hosted open-source alternative to commercial photo-sharing platforms like PicDrop.com and Scrapbook.de. Built for photographers and event organizers, it makes it simple to share beautiful, time-limited photo galleries with clients while keeping full control over your data and branding.
 
 ![PicPeak Gallery Preview](docs/screenshot-gallery.png)
 
+> [!IMPORTANT]
+> **PicPeak has moved to its own GitHub organization.** Docker images are now at `ghcr.io/picpeak/picpeak/{backend,frontend}` and active development is on `main`. The old `ghcr.io/the-luap/...` path still responds but its tags are **frozen** at 2026-05-27 — if updates never arrive, check your image path first. See **[`docs/migration-to-org.md`](docs/migration-to-org.md)** for the one-line `docker-compose.yml` edit.
+
+## Contents
+
+- [Live Demo](#-live-demo)
+- [Quick Start](#-quick-start)
+- [Why PicPeak?](#-why-picpeak)
+- [Features](#-features)
+- [Documentation](#-documentation)
+- [Comparison](#-comparison-with-alternatives)
+- [Tech Stack](#️-tech-stack)
+- [Contributing & Support](#-contributing)
+- [License](#-license)
+
 ## 🎮 Live Demo
 
-Try PicPeak without installing anything:
+Try PicPeak without installing anything — [demo.picpeak.app](https://demo.picpeak.app) · [admin panel](https://demo.picpeak.app/admin)
 
-| | |
+| Email | Password |
 |---|---|
-| **Demo URL** | [demo.picpeak.app](https://demo.picpeak.app) |
-| **Admin Panel** | [demo.picpeak.app/admin](https://demo.picpeak.app/admin) |
-| **Email** | `demo@picpeak.app` |
-| **Password** | `Demo2026!` |
+| `demo@picpeak.app` | `Demo2026!` |
 
 > The demo resets periodically. Uploaded content may be removed without notice.
 
-## 🌟 Why Choose PicPeak?
-
-Unlike expensive SaaS solutions, PicPeak gives you:
-
-- **💰 No Monthly Fees** - One-time setup, unlimited galleries
-- **🔒 Complete Data Control** - Your photos stay on your server
-- **🎨 White-Label Ready** - Full branding customization
-- **📱 Mobile-First Design** - Beautiful on all devices
-- **🚀 Lightning Fast** - Optimized performance and caching
-- **🌍 Multi-Language** - Built-in i18n support (EN, DE)
-
-## ✨ Key Features
-
-### For Photographers
-- 📁 **Drag & Drop Upload** - Simply drop photos into folders
-- 🔗 **External Media (Reference Mode)** - Browse and import from a read‑only external folder library without copying originals
-- ⏰ **Auto-Expiring Galleries** - Set expiration dates (default: 30 days)
-- 🔐 **Password Protection** - Secure client galleries
-- 📧 **Automated Emails** - Creation confirmations and expiration warnings
-- 📊 **Analytics Dashboard** - Track views, downloads, and engagement
-- 📽️ **Live Slideshow** - A separate fullscreen "Diashow" link per event for projectors at live events — auto-picks-up new uploads while it runs, with transitions, a logo watermark, and image-fit/colour options ([guide](docs/live-slideshow.md))
-- 🎨 **Custom Themes** - Match your brand perfectly
-- 🌐 **Public Landing Page** - Publish a curated marketing page when guests visit your root URL
-
-### For Clients
-- 🖼️ **Beautiful Galleries** - Clean, modern interface
-- 📱 **Mobile Optimized** - Swipe through photos on any device
-- ⬇️ **Bulk Downloads** - Download all photos with one click
-- 🔍 **Smart Search** - Find photos quickly
-- 📤 **Guest Uploads** - Optional client photo uploads
-- 🛡️ **Download Protection** - Advanced image protection with watermarking and right-click prevention
-
-### Technical Excellence
-- 🐳 **Docker Ready** - Deploy in minutes
-- 🔄 **Auto-Processing** - Automatic thumbnail generation
-- 🗂️ **Reference Library Support** - Point PicPeak at `EXTERNAL_MEDIA_ROOT` to reference existing originals, index quickly, and generate thumbnails on demand
-- 💾 **Smart Storage** - Automatic archiving of expired galleries
-- 🛡️ **Security First** - JWT auth, rate limiting, CORS protection
-- 📈 **Scalable** - From small studios to large agencies
-
-### For Studios — CRM & Accounting (Beta · off by default)
-- 📝 **Quotes → Contracts → Invoices** - One deal lineage; cancel-and-reissue (Storno) keeps issued invoices immutable
-- ⏱️ **Hours Logging & Calendar** - Per-customer time tracking; admin calendar of events, logged hours, and pending quotes/contracts
-- 🧾 **Inbound Supplier Invoices & Expenses** - Capture received invoices (upload/camera, rasterised server-side), categorise, and re-bill costs to clients
-- 📊 **Tax Report & Accountant Export** - Period-scoped income/cost report with VAT breakdown; PDF/CSV plus a Treuhänder/Banana (Swiss/LI) journal export, scopable to income-only or cost-only
-- 🌍 **VAT & Multi-currency** - Single VAT-code registry snapshotted onto each document; data-driven per-country rates
-- ⚠️ **Verify locally** - Feature-flagged off by default. Seeded contracts, QR/IBAN and tax defaults are **examples only** — review your own legal **and tax** regulations first (see disclaimers below)
-
 ## 🚀 Quick Start
 
 Get PicPeak running in under 5 minutes:
@@ -96,8 +54,8 @@ cd picpeak
 
 # Copy the environment template — the defaults work out of the box.
 # Machine secrets (JWT, DB, Redis) are auto-generated on first run, and the
-# admin account is created in the browser (see below). Edit .env only to
-# customise (domain, SMTP, storage paths, …) — nothing is required.
+# admin account is created in the browser. Edit .env only to customise
+# (domain, SMTP, storage paths, …) — nothing is required.
 cp .env.example .env
 
 # Start with Docker Compose
@@ -106,293 +64,61 @@ docker compose up -d
 # Access at http://localhost:3000
 ```
 
-### First run — create your admin account
+On first start, open **http://localhost:3000/admin** and follow the in-browser setup to create your admin account. Full details — the one-time setup token, Docker file permissions, and ARM64 notes — are in **[First-run setup](https://docs.picpeak.app/getting-started/first-login)**.
 
-On first start with no `ADMIN_PASSWORD` set, PicPeak has **no admin account yet** and greets you with an in-browser setup screen — no credentials in `.env`:
+> **Updating / release channels:** set `PICPEAK_CHANNEL` (`stable` default, or `beta`) in `.env`, then `docker compose pull && docker compose up -d`. See [RELEASING.md](RELEASING.md) for the promotion cadence.
 
-1. Open **http://localhost:3000/admin** — you'll be redirected to `/setup`.
-2. Read the **one-time setup token** from the 0600 file the backend writes it to
-   (it is deliberately *not* printed to the logs — that would leave a live
-   bootstrap credential in `docker logs`):
-   ```bash
-   docker compose exec backend cat /app/data/SETUP_TOKEN
-   ```
-   It is bind-mounted, so `sudo cat data/SETUP_TOKEN` on the host works too. Only
-   if that file could not be written does the backend fall back to logging the
-   token (`docker compose logs backend | grep -i "setup token"`).
-3. Paste the token, set your admin **email + password**, and you're in. The token is single-use, and the setup screen closes permanently once an admin exists.
+## 🌟 Why PicPeak?
 
-> Prefer the old behaviour? Set `ADMIN_PASSWORD` in `.env` and PicPeak auto-creates the admin on first boot instead (credentials written to `data/ADMIN_CREDENTIALS.txt`).
+Unlike expensive SaaS solutions, PicPeak gives you:
 
-Note on Docker file permissions
-- The backend container starts as root, chowns bind-mounted host directories (`./storage`, `./data`, `./logs`) to UID 1001 (`nodejs`), then drops privileges via `su-exec` before running the app. No host-side setup needed for fresh installs.
-- If you pin `user:` in a compose override (e.g. to map a specific host UID), the self-chown is skipped and you must pre-chown the host directories to that UID — see [docs.picpeak.app/deployment/docker#permissions](https://docs.picpeak.app/deployment/docker#permissions).
+- **💰 No Monthly Fees** — one-time setup, unlimited galleries
+- **🔒 Complete Data Control** — your photos stay on your server
+- **🎨 White-Label Ready** — full branding customization
+- **📱 Mobile-First Design** — beautiful on all devices
+- **🌍 Multi-Language** — built-in i18n (EN, DE)
 
-**ARM64 (aarch64) systems:** Pre-built images include native `linux/arm64`, no platform flags or emulation needed. If you're on an older image tag that's still amd64-only, see [docker-compose.amd64.override.yml](docker-compose.amd64.override.yml) for a transitional fallback.
+## ✨ Features
 
-## 🔄 Release Channels
+**For photographers** — drag & drop upload, auto-expiring & password-protected galleries, automated emails, an analytics dashboard, custom themes, a public landing page, and a [Live Slideshow](https://docs.picpeak.app/features/live-slideshow) projector view that auto-picks-up new uploads during live events.
 
-PicPeak offers two release channels for different needs. Stable promotions are cut from a known-good beta point every 4–6 weeks — see [RELEASING.md](RELEASING.md) for the maintainer's promotion criteria and cadence policy.
+**For clients** — clean mobile-optimized galleries, one-click bulk downloads, smart search, optional guest uploads, and download protection (watermarking + right-click prevention).
 
-### Stable Channel (Recommended)
-- Production-ready releases
-- Thoroughly tested before release
-- Docker tags: `stable`, `latest`, or specific version like `v2.3.0`
+**Technical** — Docker-ready, automatic thumbnail generation, external media reference mode, smart archiving of expired galleries, S3-compatible [storage backends](https://docs.picpeak.app/features/storage-backends), [webhooks](https://docs.picpeak.app/features/webhooks), and security-first defaults (JWT, rate limiting, CORS).
 
-### Beta Channel
-- Early access to new features
-- May contain bugs or incomplete functionality
-- Docker tags: `beta` or specific version like `v2.3.0-beta.1`
+<details>
+<summary><strong>🧾 For studios — CRM &amp; Accounting (Beta, off by default)</strong></summary>
 
-### Switching Channels
+- 📝 **Quotes → Contracts → Invoices** — one deal lineage; cancel-and-reissue (Storno) keeps issued invoices immutable
+- ⏱️ **Hours Logging & Calendar** — per-customer time tracking; admin calendar of events, logged hours, and pending quotes/contracts
+- 🧾 **Inbound Supplier Invoices & Expenses** — capture received invoices (upload/camera, rasterised server-side), categorise, and re-bill costs to clients
+- 📊 **Tax Report & Accountant Export** — period-scoped income/cost report with VAT breakdown; PDF/CSV plus a Treuhänder/Banana (Swiss/LI) journal export
+- 🌍 **VAT & Multi-currency** — single VAT-code registry snapshotted onto each document
 
-Set the `PICPEAK_CHANNEL` environment variable in your `.env` file:
+</details>
 
-```bash
-# For stable releases (default)
-PICPEAK_CHANNEL=stable
-
-# For beta releases
-PICPEAK_CHANNEL=beta
-
-# For a specific version
-PICPEAK_CHANNEL=v2.3.0
-```
-
-Then update your containers:
-
-```bash
-docker compose -f docker-compose.production.yml pull
-docker compose -f docker-compose.production.yml up -d
-```
-
-### Update Notifications
-
-The admin dashboard automatically notifies you when updates are available for your channel. To disable update checks, set:
-
-```bash
-UPDATE_CHECK_ENABLED=false
-```
+> [!WARNING]
+> **CRM & Accounting — examples only, verify locally.** Feature-flagged off by default. Seeded contract blocks are written by the maintainer, **not a lawyer**; QR-bills/SEPA payloads and every tax, VAT and Treuhänder/Banana figure are computed from your input and defaults and are **jurisdiction-specific guidance only**. Have your lawyer review contracts, scan a test QR with your bank's app, and verify all numbers with your accountant / Treuhänder / tax authority before customer-facing use. Read **[the CRM disclaimers](https://docs.picpeak.app/features/crm/disclaimers)** first.
 
 ## 📖 Documentation
 
-Full documentation lives at **[docs.picpeak.app](https://docs.picpeak.app)** — deployment, admin settings reference, API docs, webhooks, archive lifecycle, branding, and everything else. Some quick links:
+Full documentation lives at **[docs.picpeak.app](https://docs.picpeak.app)** — deployment, admin settings, API, branding, and more.
 
-- 🚀 [**Deployment**](https://docs.picpeak.app/deployment) - Docker, environment variables, reverse proxy, SSL
-- ⚙️ [**Admin Settings**](https://docs.picpeak.app/guides/admin-settings) - Every tab in the Settings panel
-- 🎯 [**Creating Events**](https://docs.picpeak.app/guides/creating-events) - Full event field reference
-- 📽️ [**Live Slideshow**](https://docs.picpeak.app/features/live-slideshow) - Fullscreen projector view that auto-updates during live events
-- 💾 [**Backup & Restore**](https://docs.picpeak.app/guides/backup-restore) - Backup configuration, restore wizard, full disaster recovery
-- 🔌 [**API Reference**](https://docs.picpeak.app/api) - REST endpoints, OpenAPI spec, webhooks
-- 🪝 [**Webhooks**](https://docs.picpeak.app/features/webhooks) - Event payloads, signing, filters, templates
-
-Project meta:
-
-- 🤝 [**Contributing**](CONTRIBUTING.md) - How to contribute
-- 📜 [**License**](LICENSE) - MIT License
-- 🔒 [**Security**](SECURITY.md) - Security policies
-- 📋 [**Code of Conduct**](CODE_OF_CONDUCT.md) - Community guidelines
-
-## 🌐 Public Landing Page
-
-Spotlight your studio with a customizable marketing page at `/`:
-
-- Head to **Admin → CMS Pages** to enable the public landing page toggle.
-- Edit the provided HTML template (rich sections, hero, testimonials) and optional CSS overrides.
-- The preview renders in a sandboxed iframe so you can iterate safely before publishing.
-- PicPeak sanitizes stored HTML and CSS server-side—scripts, iframes, and unsafe attributes are stripped automatically.
-- Use **Reset to default** anytime to restore the bundled template.
-- The backend caches the rendered landing page for 60 seconds by default; override with `PUBLIC_SITE_CACHE_TTL_MS` if you need a different TTL.
-- When the landing page is disabled PicPeak continues to serve the admin SPA/login exactly as before.
-
-## 🎯 Use Cases
-
-Perfect for:
-- 💒 **Wedding Photographers** - Share ceremony photos securely
-- 🎂 **Event Photography** - Birthday parties, corporate events
-- 📸 **Portrait Studios** - Client galleries with download limits
-- 🏢 **Corporate Events** - Internal photo sharing with branding
-- 🎓 **School Photography** - Secure parent access with expiration
-- 📽️ **Live Events** - Put a [Live Slideshow](docs/live-slideshow.md) on the venue projector that updates as you shoot
-
-## 🏗️ Tech Stack
-
-- **Backend**: Node.js, Express, SQLite/PostgreSQL
-- **Frontend**: React, Tailwind CSS, Framer Motion
-- **Storage**: Local filesystem (default) or S3-compatible object store (AWS S3, MinIO, R2, B2, Wasabi, Spaces) — see [Storage Backends](#storage-backends)
-- **Email**: SMTP with customizable templates
-- **Analytics**: Privacy-focused with Umami integration
-
-## 💾 Storage Backends
-
-PicPeak supports two storage backends for photos, thumbnails, hero images, watermarks, and archive zips. Both are configured via environment variables; no code change is required to switch.
-
-| Capability | `STORAGE_BACKEND=local` (default) | `STORAGE_BACKEND=s3` |
-|---|---|---|
-| Photo / thumbnail / hero storage | Local filesystem under `STORAGE_PATH` | Bucket on any S3-compatible service |
-| Admin UI upload | ✅ | ✅ |
-| Filesystem auto-import (chokidar watcher) | ✅ | ❌ — disabled (use the upload API) |
-| Watermarks, fingerprinting, fragmentation | ✅ | ✅ (materialized to a tmp file just-in-time) |
-| Bulk download zips (cached + on-the-fly) | ✅ | ✅ |
-| Backups | ✅ | ✅ |
-| External media reference mode (`EXTERNAL_MEDIA_ROOT`) | ✅ (always local) | ✅ (still local — not migrated) |
-
-### Switching to an S3-compatible backend
-
-1. Provision a bucket and credentials. The minimum IAM policy is documented in `.env.example`.
-2. Set `STORAGE_BACKEND=s3` plus `STORAGE_S3_BUCKET`, `STORAGE_S3_REGION`, `STORAGE_S3_ACCESS_KEY`, `STORAGE_S3_SECRET_KEY`. For non-AWS providers (MinIO, R2, B2, …) also set `STORAGE_S3_ENDPOINT`.
-3. If you have existing local content, copy it first: `node backend/scripts/migrate-storage.js --dry-run` then `node backend/scripts/migrate-storage.js`. The script is idempotent and writes a failures CSV.
-4. Restart the backend. The startup check pings the bucket and refuses to boot on misconfig.
-
-Note: presigned-URL serving (zero-bandwidth direct downloads from S3) is intentionally **not** in v1 — every request still streams through the backend so watermarks, devtools-detection, and access logging keep working.
-
-## 🔔 Webhooks
-
-PicPeak POSTs event/photo lifecycle notifications to URLs you configure under **Settings → Webhooks**. Each delivery is signed `HMAC-SHA256` with a per-webhook secret in the `X-PicPeak-Signature` header so receivers can verify the request really came from your PicPeak instance.
-
-### Event types
-
-| Event | Fires when |
+| Topic | Link |
 |---|---|
-| `event.created` | Gallery created (admin or API) |
-| `event.published` | Draft becomes live (`is_draft: true → false`) — also fires when an event is created with `is_draft=false` |
-| `event.archived` | Bulk-archive, manual archive, or auto-archive on expiry |
-| `event.expired` | Expiration checker marks the gallery inactive (fires before `event.archived` in the cascade) |
-| `photo.uploaded` | Admin upload, API upload, guest upload, or auto-import |
-| `photo.deleted` | Single delete, bulk delete (NOT fired per-photo when an event is archived — receivers infer from `event.archived` to avoid flooding) |
+| 🚀 Deployment (Docker, env, reverse proxy, SSL) | [docs.picpeak.app/deployment](https://docs.picpeak.app/deployment) |
+| ⚙️ Admin settings reference | [docs.picpeak.app/guides/admin-settings](https://docs.picpeak.app/guides/admin-settings) |
+| 🎯 Creating events | [docs.picpeak.app/guides/creating-events](https://docs.picpeak.app/guides/creating-events) |
+| 📽️ Live Slideshow | [docs.picpeak.app/features/live-slideshow](https://docs.picpeak.app/features/live-slideshow) |
+| 💾 Backup & Restore | [docs.picpeak.app/guides/backup-restore](https://docs.picpeak.app/guides/backup-restore) |
+| 🔌 API reference | [docs.picpeak.app/api](https://docs.picpeak.app/api) |
+| 🪝 Webhooks | [docs.picpeak.app/features/webhooks](https://docs.picpeak.app/features/webhooks) |
+| 💾 Storage backends (local / S3) | [docs.picpeak.app/features/storage-backends](https://docs.picpeak.app/features/storage-backends) |
+| 💻 System requirements & tuning | [docs.picpeak.app/deployment/system-requirements](https://docs.picpeak.app/deployment/system-requirements) |
+| 🧾 CRM & Accounting | [docs.picpeak.app/features/crm](https://docs.picpeak.app/features/crm) · [disclaimers](https://docs.picpeak.app/features/crm/disclaimers) |
+| 🗺️ Roadmap | [GitHub Issues](https://github.com/PicPeak/picpeak/issues) |
 
-### Payload shape
-
-```json
-{
-  "id": "delivery-uuid",
-  "type": "event.published",
-  "created_at": "2026-04-28T05:25:00.000Z",
-  "data": {
-    "event": { "id": 123, "slug": "wedding-smith", "share_url": "https://..." }
-  }
-}
-```
-
-Also sent on every request:
-- `X-PicPeak-Signature` — `HMAC-SHA256(secret, raw_body)` as hex
-- `X-PicPeak-Event` — the event type (handy for routing without parsing the body)
-- `X-PicPeak-Delivery` — UUID for idempotency on the receiver side
-- `User-Agent: PicPeak-Webhooks/1.0`
-
-### Verifying signatures
-
-**Node.js**
-```js
-const crypto = require('crypto');
-function verify(secret, rawBody, signature) {
-  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
-  const a = Buffer.from(expected, 'hex');
-  const b = Buffer.from(signature, 'hex');
-  if (a.length !== b.length) return false;
-  return crypto.timingSafeEqual(a, b);
-}
-```
-
-**Python**
-```python
-import hmac, hashlib
-def verify(secret: str, raw_body: bytes, signature: str) -> bool:
-    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
-    return hmac.compare_digest(expected, signature)
-```
-
-**curl + openssl** (one-liner for a quick replay)
-```sh
-SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
-[ "$SIG" = "$RECEIVED_SIG" ] && echo OK || echo MISMATCH
-```
-
-### Retries + observability
-
-- `2xx` → success, recorded with latency
-- Non-`2xx` or network error → exponential backoff: `1m → 5m → 30m → 2h → 12h`, max 5 attempts
-- After max attempts: status `failed`, surfaces in **Settings → Webhooks → Deliveries** with a "Replay" button
-- Up to 5 deliveries in flight at once; one slow consumer can't block others (configurable via `WEBHOOK_DELIVERY_CONCURRENCY`)
-- Response body truncated to 1KB before storage so chatty receivers don't bloat the audit log
-
-The deliveries page (`/admin/webhooks/:id/deliveries`) shows every attempt with timestamp, status, HTTP code, latency, payload sent, signature, and response. Click "Send test event" to fire a synthetic delivery for any event type.
-
-### SSRF protection
-
-Webhook URLs are validated against the same private-IP blocklist used elsewhere in the app — loopback, private RFC1918 ranges, link-local, `.local`/`.internal` hostnames, cloud metadata endpoints. The check runs both at create time and per-delivery (DNS-rebinding mitigation).
-
-For local development with a receiver on the same machine or docker network, set `WEBHOOK_ALLOW_PRIVATE_URLS=true`. Production deployments must leave this OFF.
-
-## 💻 System Requirements
-
-### Minimum Requirements
-- **CPU**: 2 CPU cores
-- **RAM**: **4 GB minimum** for a normal photo-upload workload — sharp/libvips
-  decodes the full uncompressed frame before resize, and the default two
-  worker loops at sharp-concurrency 2 can push peak RSS past 1.5 GB on a
-  batch of 20-MP+ photos. On a 2 GB VPS that's enough to OOM-kill the
-  backend mid-batch (surfaces as 503s on thumbnails — see [Low-memory
-  hosts](#low-memory-hosts) below for the recipe to run on 2 GB).
-- **Storage**: 20GB minimum (plus photo storage needs)
-- **OS**: Linux (Ubuntu 20.04+), macOS, or Windows with WSL2
-- **Node.js**: v18.0.0 or higher
-- **Database**: SQLite (included) or PostgreSQL 12+
-
-### Docker Requirements (Recommended)
-- **Docker**: v20.10.0+
-- **Docker Compose**: v2.0.0+
-
-### Low-memory hosts
-
-Running on 2 GB RAM (e.g. an entry-level VPS) is workable but requires
-tuning the upload-processor concurrency down. The backend auto-detects
-total RAM at startup via `os.totalmem()` — on a host that reports < 3 GB,
-it defaults `UPLOAD_PROCESSOR_CONCURRENCY` to **1** instead of 2 and logs
-a one-shot warning. You can pin the value explicitly in `.env`:
-
-```env
-# Single worker loop — slower batch processing, lower peak RSS
-UPLOAD_PROCESSOR_CONCURRENCY=1
-```
-
-The trade-off is throughput: a single worker processes one photo at a
-time, so a 100-photo batch takes ~2× as long but won't OOM. **Health-check
-note**: if the backend dies under memory pressure, the gallery serves
-`503 Service Unavailable` on thumbnails until Docker's
-`restart: unless-stopped` brings the container back. Persistent 503s
-during/after an upload batch on a low-memory host are almost always this.
-
-### Video Support Requirements
-When enabling video uploads, consider these additional resources:
-
-| Resource | Recommendation | Notes |
-|----------|----------------|-------|
-| **RAM** | 4GB+ recommended | FFmpeg processing requires more memory |
-| **Storage** | Plan for 10-100x more | Videos are significantly larger than images |
-| **CPU** | Additional cores help | Video thumbnail extraction is CPU-intensive |
-| **Bandwidth** | Higher throughput | Video streaming requires more bandwidth |
-
-**Technical Notes:**
-- FFmpeg is bundled via npm (`@ffmpeg-installer/ffmpeg`) - no system installation required
-- Maximum upload size: **10GB per video file**
-- Chunked upload support for files >100MB (resumable uploads)
-- Supported formats: MP4, WebM, MOV, AVI
-- Video thumbnails are automatically generated from the first few seconds
-
-**For Nginx/Reverse Proxy:**
-If using Nginx, increase the client max body size:
-```nginx
-client_max_body_size 10G;
-proxy_read_timeout 3600;
-proxy_send_timeout 3600;
-```
-
-## 🤝 Contributing
-
-We love contributions! PicPeak is built by photographers, for photographers. Whether you're fixing bugs, adding features, or improving documentation, your help is welcome.
-
-See our [Contributing Guide](CONTRIBUTING.md) for details.
+**Project meta:** [Contributing](CONTRIBUTING.md) · [License](LICENSE) · [Security](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
 
 ## 📊 Comparison with Alternatives
 
@@ -409,168 +135,79 @@ See our [Contributing Guide](CONTRIBUTING.md) for details.
 | Quotes / Contracts / Invoices | 🧪 Beta | ❌ | ❌ | ✅ |
 | Incoming Invoices & Accounting | 🧪 Beta | ❌ | ❌ | ❌ |
 
-*You still bring your own server (own hardware or a VPS) and, if you want one, a domain.
-**Limited only by your server storage.
-***Pixieset's "unlimited" is photos only; video is capped by plan (roughly 0–10 h depending on tier).
-🧪 Beta = built but feature-flagged off by default (see [Beta Features](#-beta-features-use-at-your-own-risk)).
+<sub>*You bring your own server and, optionally, a domain. **Limited only by your server storage. ***Pixieset's "unlimited" is photos only; video is capped by plan. 🧪 Beta = built but feature-flagged off by default.</sub>
 
-## 🛡️ Security
+## 🏗️ Tech Stack
 
-PicPeak takes security seriously:
-- 🔐 Password hashing with bcrypt
-- 🎫 JWT-based authentication
-- 🚦 Rate limiting on all endpoints
-- 🛡️ CORS protection
-- 📝 Activity logging
-- 🔒 Secure file access
-
-Found a security issue? Please open a [security issue](https://github.com/PicPeak/picpeak/issues/new?labels=security) on GitHub
+- **Backend**: Node.js, Express, SQLite/PostgreSQL
+- **Frontend**: React, Tailwind CSS, Framer Motion
+- **Storage**: Local filesystem (default) or S3-compatible object store (AWS S3, MinIO, R2, B2, Wasabi, Spaces) — see [Storage Backends](https://docs.picpeak.app/features/storage-backends)
+- **Email**: SMTP with customizable templates
+- **Analytics**: Privacy-focused with Umami integration
+- **External media**: point PicPeak at `EXTERNAL_MEDIA_ROOT` to reference existing originals read-only, index quickly, and generate thumbnails on demand
 
 ## 📸 Screenshots
 
-### 🎛️ **Admin Dashboard**
-Get a complete overview of your photo galleries, analytics, and system status.
+<details>
+<summary>Click to see the admin dashboard, analytics, and event management</summary>
 
+### 🎛️ Admin Dashboard
 <img src="docs/screenshot-dashboard.png" alt="PicPeak Admin Dashboard" width="800" />
 
-### 📊 **Analytics & Insights**
-Track gallery performance, view statistics, and monitor user engagement.
-
+### 📊 Analytics & Insights
 <img src="docs/screenshot-analytics.png" alt="PicPeak Analytics Dashboard" width="800" />
 
-### 📁 **Event Management**
-Organize and manage your photo galleries with intuitive event management tools.
-
+### 📁 Event Management
 <img src="docs/screenshots-events.png" alt="PicPeak Events Management" width="800" />
 
-### ✨ **Key Interface Highlights**
-
-<details>
-<summary>👆 Click to see more interface details</summary>
-
-#### What makes PicPeak's interface special:
-
-- **🎨 Clean Design**: Modern, photographer-friendly interface
-- **📱 Responsive**: Perfect on desktop, tablet, and mobile
-- **⚡ Fast Loading**: Optimized for quick photo browsing
-- **🔒 Secure Access**: Password-protected galleries with expiration
-- **📤 Easy Uploads**: Drag & drop functionality for effortless photo management
-- **🎯 Client-Focused**: Intuitive gallery experience for your clients
-
 </details>
 
-## 🗺️ Roadmap
+## 🤝 Contributing
 
-We're constantly improving PicPeak and welcome contributions from our community! If you have ideas for new features or want to help implement existing ones, please open an issue or submit a pull request. Your contributions help make PicPeak better for everyone.
+We love contributions! PicPeak is built by photographers, for photographers — whether you're fixing bugs, adding features, or improving docs. See the [Contributing Guide](CONTRIBUTING.md) to get started.
 
-### 🚧 Beta Features (Use at your own risk)
-
-These features are currently in beta testing and may have limited functionality or stability:
-
-| Feature | Description | Status |
-|---------|-------------|--------|
-| **CRM & Accounting Module** | Quotes, contracts, invoices (+ Storno), hours logging, calendar, and tax report — plus inbound supplier-invoice capture, internal expenses, and a Treuhänder/Banana (Swiss/LI) accountant-journal export. Feature-flagged off by default. Seeded contract blocks, payment terms, IBAN / QR-bill and tax defaults are **examples only** and need legal / financial / **tax** review before customer-facing use. See [docs.picpeak.app/features/crm](https://docs.picpeak.app/features/crm). | 🧪 Beta |
-| **Simple Deployment Script** | One-click deployment script for quick server setup with automated configuration and dependency installation | 🧪 Beta |
-
-### 📋 Future Enhancements
-
-| Feature | Description | Priority | Status |
-|---------|-------------|----------|---------|
-| **Backup & Restore** | Comprehensive backup system with S3/MinIO support, automated scheduling, and safe restore functionality | High | ✅ Implemented |
-| **External Media Library (Reference Mode)** | Use an external folder library as a read‑only source with import and on‑demand thumbnail generation | High | ✅ Implemented |
-| **Download Protection** | Advanced image protection system with canvas rendering, invisible watermarking, right-click prevention, and DevTools detection to protect photos from unauthorized downloads | High | ✅ Implemented |
-| **Gallery Templates** | Multiple gallery layouts (grid, masonry, carousel, timeline, hero, mosaic) with custom CSS styling support. Includes starter templates like Apple Liquid Glass for complete visual customization | Medium | ✅ Implemented |
-| **Face Recognition** | AI-powered face detection to help guests find their photos and create automatic person-based albums | Low | 🔄 Open |
-| **Gallery Feedback** | Allow guests to like, rate, and comment on photos with admin notifications and moderation | Medium | ✅ Implemented |
-| **Video Support** | Upload and display videos alongside photos in galleries with streaming support | Low | ✅ Implemented |
-| **Multiple Administrators** | Support for multiple admin accounts with role-based permissions and activity tracking | Low | ✅ Implemented |
-| **Filtering & Export Options** | Filter photos by likes, ratings, comments, or favorites. Search by filename. Sort by date, name, size, or rating. Export filtered selections as ZIP or generate Capture One/Lightroom-compatible file lists for professional workflows | Medium | ✅ Implemented |
-
-**Status Legend:** ✅ Implemented | 🚧 In Progress | 🔄 Open | 📋 Planned
+Found a security issue? Please open a [security issue](https://github.com/PicPeak/picpeak/issues/new?labels=security). See [SECURITY.md](SECURITY.md) for the policy.
 
 ## ☕ Support the Project
 
-PicPeak is free, open source, and self-hostable forever. If it saves you time or replaces a paid subscription, consider buying me a coffee — it directly funds the time spent on new features, bug fixes, and keeping the demo + docs running.
-
-<p align="left">
-  <a href="https://buymeacoffee.com/theluap" target="_blank">
-    <img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=theluap&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff" alt="Buy Me A Coffee" />
-  </a>
-</p>
-
-Other ways to support without spending anything: ⭐ star the repo, share it with photographer friends, file good bug reports, or open a PR.
+PicPeak is free, open source, and self-hostable forever. If it saves you time or replaces a paid subscription, consider [buying me a coffee](https://buymeacoffee.com/theluap) — it directly funds new features, bug fixes, and keeping the demo + docs running. You can also ⭐ star the repo, share it, file good bug reports, or open a PR.
 
 ## 🙏 Acknowledgments
 
-PicPeak is inspired by the best features of commercial platforms while remaining completely open source. Special thanks to all contributors who make this project possible.
+PicPeak is inspired by the best features of commercial platforms while remaining completely open source. It's developed with AI assistance, but human-tested end-to-end, security-audited, and human-reviewed for quality.
 
 ### 👥 Contributors
 
 A huge thank you to the people whose code, reports, and feedback have shaped PicPeak:
 
-- [**@the-luap**](https://github.com/the-luap) — creator and lead maintainer. Started the project and built PicPeak's foundation and the entire gallery experience (events, galleries, uploads, sharing, download protection, templates), plus backup & restore, analytics, system health, branding/theming, and WhatsApp notifications — and the architecture every later feature builds on.
-- [**@Luca-Timo**](https://github.com/Luca-Timo) — native Apple Silicon multi-arch images, external-URL toggle for legal CMS pages, the lazy-loaded folder tree picker, the admin-email picker on event creation, the data-driven self-hosted webfont system, the gallery header/banner decoupling, several typed-API refactors, and the CRM + accounting suite (quotes/contracts/invoices, hours logging, calendar, tax report, inbound supplier-invoice capture, expenses, and the Treuhänder/Banana export). Consistently raises the bar with thoughtful PRs.
-- [**@Rekoo-PS**](https://github.com/Rekoo-PS) — sharp-eyed bug reporter and product feedback. Filed the issues that drove the login-loop fix, the gallery-loading skeleton work, the redirection cleanup, the mobile-lightbox overhaul, the admin-events search-counter fix, the photo-count column, and the bulk-delete workflow. Also a [BuyMeACoffee](https://buymeacoffee.com/theluap) supporter — the kind of feedback loop that keeps the project useful for real deployments.
+**[@the-luap](https://github.com/the-luap)** — creator and lead maintainer
+- Gallery foundation (events, uploads, sharing, download protection, templates)
+- Backup & restore, analytics, branding/theming
+- The architecture every later feature builds on
+
+**[@Luca-Timo](https://github.com/Luca-Timo)**
+- Native Apple Silicon multi-arch images
+- CRM & accounting suite (quotes/contracts/invoices)
+- Hours logging & Treuhänder/Banana tax export
+- Gallery header/banner decoupling
+
+**[@Rekoo-PS](https://github.com/Rekoo-PS)** — bug reports & product feedback
+- Login-loop fix, mobile-lightbox overhaul, bulk-delete workflow
+- Also a [BuyMeACoffee](https://buymeacoffee.com/theluap) supporter
 
 If you've contributed and aren't listed here, please open a PR — this list is meant to grow.
 
-### 🤖 AI-Assisted Development
-
-This project was generated with the assistance of AI technology, but has been:
-- ✅ **Fully tested end-to-end** by human developers
-- 🔒 **Security audited** with comprehensive security checks
-- 👨‍💻 **Human-reviewed** for code quality and best practices
-- 🧪 **Production-tested** in real-world scenarios
-
-We believe in transparent development practices and the responsible use of AI as a tool to accelerate development while maintaining high standards of quality and security.
-
-## ⚠️ CRM & Accounting disclaimers — examples only, verify locally
-
-The CRM & accounting modules (contracts, invoices, QR-bills, the tax
-report and the accountant exports) ship seeded content and computed
-figures that are intended as a **starting point only**:
-
-- **Contract blocks** (image rights, NDA, model release, cancellation,
-  jurisdiction, …) are written by the maintainer, **not by a lawyer**.
-  Every operator must have their lawyer review and adapt them before
-  sending any contract to a customer.
-- **QR-bills and SEPA EPC payloads** are rendered from the data you
-  typed. Picpeak is open source — please scan a test invoice with your
-  bank's app to check the QR actually works. We are not responsible for
-  any mistakes that come from sending an invoice with bad data on it.
-- **Tax, VAT & accounting figures** (the tax report, VAT-payable, the
-  per-rate breakdown, the Treuhänder / Banana export, etc.) are computed
-  from the data you enter and the defaults you configure. They are
-  **guidance only and jurisdiction-specific** — tax rules, VAT rates,
-  deduction schemes (e.g. the Liechtenstein 20 % Gewinnungskosten flat
-  rate) and filing duties differ by country and change over time. **Every
-  operator must check their own tax / VAT regulations and verify the
-  numbers with their accountant / Treuhänder / tax authority before
-  relying on any figure or export.** Picpeak makes no warranty that the
-  output is correct for your jurisdiction or situation.
-
-Read [`docs/crm-disclaimers.md`](docs/crm-disclaimers.md) before
-enabling the Contracts, Invoices or Accounting features.
-
 ## 📄 License
 
 PicPeak is released under the [MIT License](LICENSE). Use it freely for personal or commercial projects.
 
-## 🚀 Ready to Get Started?
-
-1. ⭐ **Star this repository** to show your support
-2. 📖 Read the [docs at docs.picpeak.app](https://docs.picpeak.app)
-3. 🐛 Report issues or request features
-4. 🤝 Join our community and contribute!
-
 ---
 
 <p align="center">
   Made with ❤️ by photographers, for photographers
   <br>
-  <a href="https://www.picpeak.app">Homepage</a> •
-  <a href="https://demo.picpeak.app">Live Demo</a> •
-  <a href="https://github.com/PicPeak/picpeak">GitHub</a> •
-  <a href="https://docs.picpeak.app">Documentation</a> •
+  <a href="https://www.picpeak.app">Homepage</a> ·
+  <a href="https://demo.picpeak.app">Live Demo</a> ·
+  <a href="https://docs.picpeak.app">Documentation</a> ·
   <a href="https://github.com/PicPeak/picpeak/issues">Support</a>
 </p>

RELEASING.md

@@ -52,13 +52,19 @@ The actual mechanics, in order:
    - **`.release-please-manifest.json`** — keep `stable`'s; release-please owns this file.
    - Any other auto-merged file — spot-check that the auto-merge produced something sensible, especially for security-sensitive files (`backend/src/middleware/`, `backend/src/utils/tokenUtils.js`).
 
-5. **Wait for CI on the PR.** All ten checks (the original eight plus `merge-backend` and `merge-frontend`) must be green. If anything fails, fix on the release branch (NOT on `main` — `main` has already moved on).
+5. **Pin the stable version to match `main` (number alignment — see Versioning).** Determine `X.Y.Z` = the `main` tip's **base** version (its `vX.Y.Z-beta.N`, dropping the `-beta.N` suffix), and add an empty commit on the release branch:
+   ```bash
+   git commit --allow-empty -m "chore: release X.Y.Z" -m "Release-As: X.Y.Z"
+   ```
+   The `Release-As:` footer forces release-please to cut exactly `X.Y.Z`. Without it, release-please computes the next MINOR from the *previous stable* tag (e.g. `3.45.0` → `3.46.0`) while `main` is already at `3.84.x`, so the stable number drifts ever further behind for the same code.
 
-6. **Merge.** Standard merge commit, not squash — the PR's history (the individual feature commits) carries forward into `stable`'s log.
+6. **Wait for CI on the PR.** All ten checks (the original eight plus `merge-backend` and `merge-frontend`) must be green. If anything fails, fix on the release branch (NOT on `main` — `main` has already moved on).
 
-7. **release-please picks it up.** Within minutes, release-please will open a new `chore(stable): release X.Y.Z` PR proposing the stable release. Review the auto-generated CHANGELOG.md entries for accuracy, edit if needed, and merge. That merge creates the `vX.Y.Z` git tag, publishes Docker images on the `:stable` and `:latest` tags, and creates the GitHub Release page.
+7. **Merge.** Standard merge commit, not squash — the PR's history (the individual feature commits) carries forward into `stable`'s log.
 
-8. **Close the loop.** Bulk-close any `bug` issues that were fixed-but-not-closed and now appear in the released changelog. Reference the merge commit so reporters know which version contains the fix.
+8. **release-please picks it up.** Within minutes, release-please will open a new `chore(stable): release X.Y.Z` PR proposing the stable release. Review the auto-generated CHANGELOG.md entries for accuracy, edit if needed, and merge. That merge creates the `vX.Y.Z` git tag, publishes Docker images on the `:stable` and `:latest` tags, and creates the GitHub Release page.
+
+9. **Close the loop.** Bulk-close any `bug` issues that were fixed-but-not-closed and now appear in the released changelog. Reference the merge commit so reporters know which version contains the fix.
 
 ## Hotfix path (backport to current stable)
 
@@ -83,6 +89,14 @@ PicPeak follows [Semantic Versioning](https://semver.org/) with one project-spec
 
 release-please derives all of this from conventional commit prefixes (`feat:`, `fix:`, `BREAKING CHANGE:`, etc.) automatically.
 
+### Stable ↔ pre-release number alignment
+
+The two channels run **independent** release-please counters: `main` bumps on every merge (racing ahead), while `stable` only bumps on a promotion. Left to itself, `stable` computes each promotion as the next MINOR from the *previous stable tag*, so the two drift far apart — e.g. `main` at `v3.83.x-beta.0` while `stable` sat at `v3.45.0` for the **same code**, which reads as "stable is 38 versions behind" when it isn't.
+
+To keep the numbers legible, **a promotion sets the stable version to the current `main` base version** (the `X.Y.Z` of the `main` tip's `vX.Y.Z-beta.N`, minus the suffix). Promoting a `main` at `v3.84.2-beta.0` therefore cuts stable `v3.84.2`, and the stable number tracks `main` instead of lagging. This is forced with the `Release-As:` commit in step 5 of the cut procedure — the one-time catch-up jump (e.g. `3.45.0 → 3.84.x`) is expected and happens only on the first aligned promotion.
+
+> **Release-engineering note (2026-07):** `release-please.yml` (the stable workflow) *must* keep `target-branch: stable`. Without it, release-please defaults to the repo's default branch (`main`), reads `main`'s stale `.release-please-manifest.json`, and cuts a wrong/regressed version — this is what produced a bogus `v2.7.0` once. If a promotion ever yields an unexpected version, check that first.
+
 ## Things that don't go through this process
 
 - **Documentation-only changes** can land on either `stable` or `main` directly (no release cut needed); release-please will pick them up on the next regular release.

backend/.dockerignore

@@ -1,9 +1,7 @@
 node_modules
 npm-debug.log
 .env
-storage/events/active/*
-storage/events/archived/*
-storage/thumbnails/*
+storage
 data/*.db
 logs/*
 coverage

backend/.env.example

@@ -106,6 +106,12 @@ ARCHIVE_PATH=/app/storage/events/archived
 # EVENTS_PATH=./storage/events
 # ARCHIVE_PATH=./storage/events/archived
 
+# File watcher (auto-import from the events/active folder, local storage only)
+# Max photos processed in parallel by the watcher. The boot scan and bulk
+# folder drops fire one handler per file — this bound keeps thumbnail
+# generation from exhausting memory on small hosts. Default: 2
+# FILE_WATCHER_CONCURRENCY=2
+
 # Analytics Backend Configuration (OPTIONAL)
 # Used for server-side tracking only
 # Primary configuration should be done through Admin UI > Settings > Analytics

backend/Dockerfile

@@ -77,9 +77,12 @@ RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
 # PDFs to flat PNGs server-side so the admin UI NEVER renders a raw (possibly
 # malicious) PDF. pdftoppm does not execute embedded JS or fetch remote
 # resources, so it doubles as the SSRF/phone-home guard for untrusted inbound
-# documents (see docs/accounting-inbound-invoices.md).
+# documents (see https://docs.picpeak.app/features/accounting/incoming-invoices).
+# exiftool extracts the embedded full-res JPEG preview from RAW/DNG uploads
+# (Apple ProRAW etc.) — sharp's libvips has no raw loader, so the pipeline
+# thumbnails/displays that preview while keeping the original for download.
 RUN apk add --no-cache dumb-init postgresql-client ffmpeg su-exec \
-    fontconfig ttf-dejavu ttf-liberation poppler-utils && \
+    fontconfig ttf-dejavu ttf-liberation poppler-utils exiftool && \
     fc-cache -f
 
 # Create non-root user

backend/Dockerfile.dev

@@ -8,7 +8,10 @@ RUN apk upgrade --no-cache
 # Install dumb-init for proper signal handling and ffmpeg for video uploads.
 # Alpine's ffmpeg ships both ffmpeg + ffprobe built natively against musl;
 # the npm-bundled binary doesn't run reliably on Alpine. Match production.
-RUN apk add --no-cache dumb-init ffmpeg
+# exiftool: extract embedded JPEG previews from RAW/DNG uploads (#821) — kept in
+# sync with the production Dockerfile so dev/native runtimes don't accept a DNG
+# and then fail it with ENOENT.
+RUN apk add --no-cache dumb-init ffmpeg exiftool
 
 # Copy package files
 COPY package*.json ./

backend/__tests__/integration/adminThumbnails.regenerate.test.js

@@ -1,246 +0,0 @@
-/**
- * POST /admin/thumbnails/regenerate for external/reference photos (#1129).
- *
- * STABLE TWIN. Diverges from the main version in one place: stable has no
- * responsive ?w= tiers (#1095/#1109), so there is no deleteThumbnailTiers call
- * to assert and the "drops the tiers first" test is absent here. Everything
- * else — the external rebuild, the thumbnail_path:null contract, video
- * skipping, per-event scoping and the superseded-key deletion — is identical.
- *
- * The route used to resolve every source as `storage/events/active/<path>` and
- * `fs.access` it. External and reference rows do not live there — their
- * originals sit under `events.external_path` — so every one of them failed the
- * check and was counted as an error.
- *
- * That alone would be inert. What made it destructive is that the tier
- * deletion runs FIRST (deliberately, so S3 and external rows are not skipped):
- * on a reference install the button dropped every ?w= tier and rebuilt
- * nothing, while the UI reported success — the response is sent before the
- * background loop starts.
- *
- * The background work is fired with setImmediate, so every assertion here has
- * to wait for it to drain rather than trusting the response.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const express = require('express');
-const request = require('supertest');
-
-describe('admin thumbnail regeneration (#1129)', () => {
-  let tmpDir; let db; let cleanup; let app; let imageProcessor; let storage;
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-regen-'));
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'test.db');
-    process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    await fs.promises.mkdir(process.env.STORAGE_PATH, { recursive: true });
-
-    jest.resetModules();
-
-    jest.doMock('../../src/middleware/auth', () => ({
-      adminAuth: (req, _res, next) => { req.admin = { id: 1, username: 'tester' }; next(); },
-    }));
-    jest.doMock('../../src/middleware/permissions', () => ({
-      requirePermission: () => (_req, _res, next) => next(),
-    }));
-    // One instance, not a fresh object per call — the route and the
-    // assertions have to be looking at the same mock.
-    jest.doMock('../../src/services/storage', () => {
-      const instance = { delete: jest.fn().mockResolvedValue(undefined) };
-      return { getStorage: () => instance };
-    });
-    jest.doMock('../../src/services/imageProcessor', () => ({
-      ensureThumbnail: jest.fn().mockResolvedValue('thumbnails/thumb_ext1_shot.jpg'),
-      ensurePreviewImage: jest.fn().mockResolvedValue('previews/p.jpg'),
-      deletePreviewTiers: jest.fn().mockResolvedValue(undefined),
-    }));
-
-    // bootCrmDb, not run-migrations: the latter calls process.exit(0) on
-    // success, which ends the jest worker mid-suite.
-    ({ db, cleanup } = await require('./helpers/crmDb').bootCrmDb());
-
-    imageProcessor = require('../../src/services/imageProcessor');
-    storage = require('../../src/services/storage').getStorage();
-    app = express();
-    app.use(express.json());
-    app.use('/admin/thumbnails', require('../../src/routes/adminThumbnails'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (cleanup) await cleanup();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(async () => {
-    jest.clearAllMocks();
-    await db('photos').del();
-    await db('events').del();
-  });
-
-  async function seedEvent() {
-    const [row] = await db('events').insert({
-      slug: 'nas-wedding', event_type: 'wedding', event_name: 'nas',
-      event_date: '2026-01-01', host_email: 'h@example.com', admin_email: 'a@example.com',
-      password_hash: 'x', share_link: 'nas-share', expires_at: new Date().toISOString(),
-      source_mode: 'reference', external_path: 'weddings/2026-08',
-    }).returning('id');
-    return typeof row === 'object' ? row.id : row;
-  }
-
-  async function seedPhoto(eventId, overrides = {}) {
-    const [row] = await db('photos').insert({
-      event_id: eventId, filename: 'shot.jpg', path: 'nas-wedding/shot.jpg',
-      type: 'individual', ...overrides,
-    }).returning('id');
-    return typeof row === 'object' ? row.id : row;
-  }
-
-  /** The work runs in setImmediate; give it room to finish. */
-  const drain = () => new Promise((resolve) => setTimeout(resolve, 150));
-
-  it('rebuilds the canonical thumbnail for an external photo instead of erroring', async () => {
-    const eventId = await seedEvent();
-    await seedPhoto(eventId, {
-      source_origin: 'external',
-      external_relpath: 'shot.jpg',
-      thumbnail_path: 'thumbnails/stale.jpg',
-    });
-
-    const res = await request(app).post('/admin/thumbnails/regenerate').send({});
-    expect(res.status).toBe(200);
-    await drain();
-
-    // The whole bug: this used to be zero calls and one logged
-    // "Original file not found" per photo.
-    expect(imageProcessor.ensureThumbnail).toHaveBeenCalledTimes(1);
-  });
-
-  it('nulls thumbnail_path so the valid-thumbnail short-circuit cannot skip the rebuild', async () => {
-    const eventId = await seedEvent();
-    await seedPhoto(eventId, {
-      source_origin: 'external',
-      external_relpath: 'shot.jpg',
-      thumbnail_path: 'thumbnails/still-on-disk.jpg',
-    });
-
-    await request(app).post('/admin/thumbnails/regenerate').send({});
-    await drain();
-
-    // Without this the endpoint is a no-op whenever the OLD thumbnail is still
-    // readable — which is the normal case after a settings change, and exactly
-    // when the admin pressed the button.
-    const [photoArg] = imageProcessor.ensureThumbnail.mock.calls[0];
-    expect(photoArg.thumbnail_path).toBeNull();
-    expect(photoArg.source_origin).toBe('external');
-    // Carried through so ensureThumbnail can resolve off the mount rather than
-    // under events/active.
-    expect(photoArg.external_relpath).toBe('shot.jpg');
-  });
-
-  it('leaves videos alone rather than handing a container file to Sharp', async () => {
-    const eventId = await seedEvent();
-    await seedPhoto(eventId, { source_origin: 'managed', media_type: 'video', filename: 'clip.mp4' });
-    await seedPhoto(eventId, { source_origin: 'managed', filename: 'still.jpg' });
-
-    const res = await request(app).post('/admin/thumbnails/regenerate').send({});
-    await drain();
-
-    expect(res.body.count).toBe(1);
-    expect(imageProcessor.ensureThumbnail).toHaveBeenCalledTimes(1);
-    expect(imageProcessor.ensureThumbnail.mock.calls[0][0].filename).toBe('still.jpg');
-  });
-
-  /**
-   * On S3, ensureThumbnail downloads the source to a randomly-named temp file,
-   * and for non-RAW input withProcessableImage passes no outputBasename — so
-   * generateThumbnail derives the key from that random name and it differs on
-   * every run. Nulling thumbnail_path hides the old key from everything that
-   * would otherwise clean it up, so each regeneration would strand a full
-   * thumbnail in the bucket, once per photo per run.
-   */
-  describe('superseded canonical renditions', () => {
-    it('removes the old thumbnail when the key moved', async () => {
-      const eventId = await seedEvent();
-      await seedPhoto(eventId, {
-        source_origin: 'managed',
-        thumbnail_path: 'thumbnails/thumb_OLDRANDOM_shot.jpg',
-      });
-      imageProcessor.ensureThumbnail.mockResolvedValueOnce('thumbnails/thumb_NEWRANDOM_shot.jpg');
-
-      await request(app).post('/admin/thumbnails/regenerate').send({});
-      await drain();
-
-      expect(storage.delete).toHaveBeenCalledWith('thumbnails/thumb_OLDRANDOM_shot.jpg');
-    });
-
-    it('does NOT delete when the key is unchanged — that is the new file', async () => {
-      const eventId = await seedEvent();
-      await seedPhoto(eventId, {
-        source_origin: 'managed',
-        thumbnail_path: 'thumbnails/thumb_stable.jpg',
-      });
-      // Local storage resolves to a stable path, so the key is identical.
-      imageProcessor.ensureThumbnail.mockResolvedValueOnce('thumbnails/thumb_stable.jpg');
-
-      await request(app).post('/admin/thumbnails/regenerate').send({});
-      await drain();
-
-      expect(storage.delete).not.toHaveBeenCalled();
-    });
-
-    it.each([
-      ['a Windows-style legacy path', 'thumbnails\\thumb_ext1_shot.jpg'],
-      ['a leading ./', './thumbnails/thumb_ext1_shot.jpg'],
-      ['a doubled separator', 'thumbnails//thumb_ext1_shot.jpg'],
-    ])('does not delete the file it just wrote when the old path is %s', async (_name, stored) => {
-      const eventId = await seedEvent();
-      await seedPhoto(eventId, { source_origin: 'managed', thumbnail_path: stored });
-      // Both storage backends fold these to the same key, so this is the SAME
-      // object — deleting it would remove the freshly generated thumbnail and
-      // leave the row pointing at nothing.
-      imageProcessor.ensureThumbnail.mockResolvedValueOnce('thumbnails/thumb_ext1_shot.jpg');
-
-      await request(app).post('/admin/thumbnails/regenerate').send({});
-      await drain();
-
-      expect(storage.delete).not.toHaveBeenCalled();
-    });
-
-    it('counts the photo as regenerated even if the old object cannot be removed', async () => {
-      const eventId = await seedEvent();
-      await seedPhoto(eventId, {
-        source_origin: 'managed',
-        thumbnail_path: 'thumbnails/thumb_OLD.jpg',
-      });
-      imageProcessor.ensureThumbnail.mockResolvedValueOnce('thumbnails/thumb_NEW.jpg');
-      storage.delete.mockRejectedValueOnce(new Error('bucket said no'));
-
-      await request(app).post('/admin/thumbnails/regenerate').send({});
-      await drain();
-
-      // Losing the old object is untidy; the regeneration itself succeeded.
-      expect(imageProcessor.ensureThumbnail).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  it('scopes to one event when asked', async () => {
-    const a = await seedEvent();
-    await seedPhoto(a, { source_origin: 'external', external_relpath: 'a.jpg' });
-    const [b] = await db('events').insert({
-      slug: 'other', event_type: 'wedding', event_name: 'other', event_date: '2026-01-01',
-      host_email: 'h@example.com', admin_email: 'a@example.com', password_hash: 'x',
-      share_link: 'other-share', expires_at: new Date().toISOString(),
-    }).returning('id');
-    await seedPhoto(typeof b === 'object' ? b.id : b, { source_origin: 'managed' });
-
-    const res = await request(app).post('/admin/thumbnails/regenerate').send({ eventId: a });
-    await drain();
-
-    expect(res.body.count).toBe(1);
-    expect(imageProcessor.ensureThumbnail).toHaveBeenCalledTimes(1);
-  });
-});

backend/__tests__/integration/backupSecretMasking.test.js

@@ -0,0 +1,109 @@
+/**
+ * Backup credential exposure regression tests.
+ *
+ * The generic settings reads (GET /admin/settings, GET /admin/settings/:type)
+ * masked the recaptcha/umami/rybbit keys but returned backup_s3_secret_key
+ * and backup_rsync_ssh_key (an SSH PRIVATE KEY) in plaintext to any
+ * settings.view holder; GET /admin/backup/config returned them too. Both now
+ * mask, and PUT /admin/backup/config skips the mask sentinel so the edit
+ * form round-trips without clobbering stored credentials.
+ */
+
+const request = require('supertest');
+const express = require('express');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+jest.mock('../../src/middleware/auth', () => ({
+  adminAuth: (req, _res, next) => {
+    req.admin = { id: 1, username: 'test-admin' };
+    next();
+  },
+}));
+jest.mock('../../src/middleware/permissions', () => ({
+  requirePermission: () => (_req, _res, next) => next(),
+  requireSuperAdmin: () => (_req, _res, next) => next(),
+}));
+
+describe('backup credential masking', () => {
+  let db;
+  let cleanup;
+  let app;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+
+    // Upsert: several backup_* keys are pre-seeded by the backup migrations.
+    const seed = [
+      { setting_key: 'backup_destination_type', setting_value: JSON.stringify('s3'), setting_type: 'backup' },
+      { setting_key: 'backup_s3_endpoint', setting_value: JSON.stringify('https://s3.example.com'), setting_type: 'backup' },
+      { setting_key: 'backup_s3_bucket', setting_value: JSON.stringify('backups'), setting_type: 'backup' },
+      { setting_key: 'backup_s3_access_key', setting_value: JSON.stringify('AKIAEXAMPLE'), setting_type: 'backup' },
+      { setting_key: 'backup_s3_secret_key', setting_value: JSON.stringify('super-secret-s3-key'), setting_type: 'backup' },
+      { setting_key: 'backup_rsync_ssh_key', setting_value: JSON.stringify('-----BEGIN OPENSSH PRIVATE KEY-----abc'), setting_type: 'backup' },
+    ];
+    for (const row of seed) {
+      await db('app_settings').insert(row).onConflict('setting_key').merge();
+    }
+
+    app = express();
+    app.use(express.json());
+    app.use('/api/admin/backup', require('../../src/routes/adminBackup'));
+    app.use('/api/admin/settings', require('../../src/routes/adminSettings'));
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  it('masks the credentials in GET /admin/backup/config', async () => {
+    const res = await request(app).get('/api/admin/backup/config').expect(200);
+    expect(res.body.backup_s3_secret_key).toBe('••••••••');
+    expect(res.body.backup_rsync_ssh_key).toBe('••••••••');
+    // Non-secret fields stay readable for the form.
+    expect(res.body.backup_s3_bucket).toBe('backups');
+  });
+
+  it('masks the credentials in the generic GET /admin/settings/:type read', async () => {
+    const res = await request(app).get('/api/admin/settings/backup').expect(200);
+    expect(res.body.backup_s3_secret_key).toBe('••••••••');
+    expect(res.body.backup_rsync_ssh_key).toBe('••••••••');
+  });
+
+  it('masks the credentials in the generic GET /admin/settings read', async () => {
+    const res = await request(app).get('/api/admin/settings').expect(200);
+    expect(res.body.backup_s3_secret_key).toBe('••••••••');
+    expect(res.body.backup_rsync_ssh_key).toBe('••••••••');
+  });
+
+  it('PUT /admin/backup/config keeps the stored secret when the sentinel round-trips', async () => {
+    await request(app)
+      .put('/api/admin/backup/config')
+      .send({
+        backup_destination_type: 's3',
+        backup_s3_endpoint: 'https://s3.example.com',
+        backup_s3_bucket: 'renamed-bucket',
+        backup_s3_access_key: 'AKIAEXAMPLE',
+        backup_s3_secret_key: '••••••••',
+        backup_rsync_ssh_key: '••••••••',
+      })
+      .expect(200);
+
+    const secret = await db('app_settings').where({ setting_key: 'backup_s3_secret_key' }).first();
+    expect(JSON.parse(secret.setting_value)).toBe('super-secret-s3-key');
+    const sshKey = await db('app_settings').where({ setting_key: 'backup_rsync_ssh_key' }).first();
+    expect(JSON.parse(sshKey.setting_value)).toBe('-----BEGIN OPENSSH PRIVATE KEY-----abc');
+    const bucket = await db('app_settings').where({ setting_key: 'backup_s3_bucket' }).first();
+    expect(JSON.parse(bucket.setting_value)).toBe('renamed-bucket');
+  });
+
+  it('PUT /admin/backup/config stores a genuinely new secret', async () => {
+    await request(app)
+      .put('/api/admin/backup/config')
+      .send({ backup_s3_secret_key: 'rotated-s3-key' })
+      .expect(200);
+
+    const secret = await db('app_settings').where({ setting_key: 'backup_s3_secret_key' }).first();
+    expect(JSON.parse(secret.setting_value)).toBe('rotated-s3-key');
+  });
+});

backend/__tests__/integration/captureDateBackfill.test.js

@@ -1,202 +0,0 @@
-/**
- * Backfilling captured_at on a library imported before #1172.
- *
- * The point of the endpoint, rather than a migration: it resolves originals
- * through resolvePhotoFilePath, which is the only path that reaches an
- * external row. The thumbnail regenerator resolves under
- * storage/events/active/<photo.path>, which never exists for those (#1129) —
- * so it cannot be the model.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const express = require('express');
-const request = require('supertest');
-const sharp = require('sharp');
-
-describe('capture date backfill (#1172)', () => {
-  let tmpDir; let db; let app; let mediaRoot;
-
-  const writeJpegWithExif = async (abs, iso) => {
-    await fs.promises.mkdir(path.dirname(abs), { recursive: true });
-    const d = new Date(iso);
-    const pad = (n) => String(n).padStart(2, '0');
-    const exifDate = `${d.getUTCFullYear()}:${pad(d.getUTCMonth() + 1)}:${pad(d.getUTCDate())} `
-      + `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
-    await sharp({ create: { width: 60, height: 40, channels: 3, background: { r: 9, g: 9, b: 9 } } })
-      .withExif({ IFD2: { DateTimeOriginal: exifDate } }).jpeg().toFile(abs);
-  };
-
-  const settle = async () => { for (let i = 0; i < 60; i++) { await new Promise((r) => setTimeout(r, 50)); const s = await status(); if (!s.body.isRunning) return s; } throw new Error('backfill did not settle'); };
-  const status = () => request(app).get('/api/admin/photos/repair-capture-dates/status');
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-capfill-'));
-    mediaRoot = path.join(tmpDir, 'media');
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'db.sqlite');
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-    process.env.EXTERNAL_MEDIA_ROOT = mediaRoot;
-    process.env.JWT_SECRET = process.env.JWT_SECRET || 'capfill-secret';
-
-    jest.resetModules();
-    jest.doMock('../../src/middleware/auth', () => ({
-      adminAuth: (req, _res, next) => { req.admin = { id: 1, username: 'tester', roleName: 'admin' }; next(); },
-    }));
-    jest.doMock('../../src/middleware/permissions', () => ({
-      requirePermission: () => (_req, _res, next) => next(),
-    }));
-    jest.doMock('../../src/utils/logger', () => ({
-      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
-    }));
-
-    ({ db } = await require('./helpers/crmDb').bootCrmDb());
-
-    app = express();
-    app.use(express.json());
-    app.use('/api/admin/photos', require('../../src/routes/adminPhotoDimensions'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (db) await db.destroy?.();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  async function seed({ relpath, exifIso, writeFile = true, archived = false }) {
-    await db('photos').del();
-    await db('events').del();
-    const [e] = await db('events').insert({
-      slug: 'capfill', event_type: 'wedding', event_name: 'capfill', event_date: '2026-01-01',
-      host_email: 'h@example.com', admin_email: 'a@example.com', password_hash: 'x',
-      share_link: `capfill-${Math.random()}`, expires_at: new Date().toISOString(),
-      source_mode: 'reference', external_path: 'trip', is_archived: archived,
-    }).returning('id');
-    const eventId = typeof e === 'object' ? e.id : e;
-    if (writeFile) await writeJpegWithExif(path.join(mediaRoot, 'trip', relpath), exifIso);
-    const [p] = await db('photos').insert({
-      event_id: eventId, filename: path.basename(relpath), path: `capfill/${path.basename(relpath)}`,
-      // Root-relative, as this branch stores it (#1163) — the file lives at
-      // <mediaRoot>/trip/<relpath>.
-      type: 'individual', source_origin: 'external', external_relpath: `trip/${relpath}`,
-      uploaded_at: new Date().toISOString(), captured_at: null,
-    }).returning('id');
-    return { eventId, photoId: typeof p === 'object' ? p.id : p };
-  }
-
-  it('fills captured_at for an external photo the thumbnail regenerator cannot reach', async () => {
-    const { photoId } = await seed({ relpath: 'a.jpg', exifIso: '2026-06-01T09:45:03Z' });
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-    expect(res.status).toBe(200);
-    expect(res.body.count).toBe(1);
-    const done = await settle();
-
-    expect(done.body.lastResult.success).toBe(1);
-    expect((await db('photos').where({ id: photoId }).first()).captured_at).toBeTruthy();
-  });
-
-  it('counts a photo with no EXIF separately from a failure', async () => {
-    // "The mount is broken" and "these files carry no date" need different
-    // answers from an operator, so they are not the same number.
-    await db('photos').del(); await db('events').del();
-    const { photoId } = await seed({ relpath: 'plain.jpg', exifIso: '2026-06-01T09:45:03Z', writeFile: false });
-    await sharp({ create: { width: 40, height: 30, channels: 3, background: { r: 1, g: 1, b: 1 } } })
-      .jpeg().toFile(path.join(mediaRoot, 'trip', 'plain.jpg'));
-
-    await request(app).post('/api/admin/photos/repair-capture-dates');
-    const done = await settle();
-
-    expect(done.body.lastResult).toMatchObject({ success: 0, noExif: 1, failed: 0 });
-    expect((await db('photos').where({ id: photoId }).first()).captured_at).toBeNull();
-  });
-
-  it('counts an unreachable original as a failure, not as missing EXIF', async () => {
-    await seed({ relpath: 'gone.jpg', exifIso: '2026-06-01T09:45:03Z', writeFile: false });
-
-    await request(app).post('/api/admin/photos/repair-capture-dates');
-    const done = await settle();
-
-    expect(done.body.lastResult).toMatchObject({ success: 0, noExif: 0, failed: 1 });
-  });
-
-  it('reports nothing to do once every photo has a date', async () => {
-    const { photoId } = await seed({ relpath: 'b.jpg', exifIso: '2026-06-02T09:00:00Z' });
-    await db('photos').where({ id: photoId }).update({ captured_at: new Date().toISOString() });
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-
-    expect(res.body.count).toBe(0);
-    expect((await status()).body.withoutCaptureDate).toBe(0);
-  });
-
-  it('skips a watcher-imported video, which carries media_type "image"', async () => {
-    // fileWatcher.processNewPhoto sets type='video' and a video/* mime but
-    // never media_type (fileWatcher.js:128-130), so the row keeps the 'image'
-    // default from migration 048. Filtering on media_type alone queued it every
-    // run: extractCaptureDate returns null for a video, captured_at stays null,
-    // and the backlog never cleared.
-    const { eventId } = await seed({ relpath: 'clip.jpg', exifIso: '2026-06-01T09:45:03Z', writeFile: false });
-    await db('photos').del();
-    await db('photos').insert({
-      event_id: eventId, filename: 'clip.mp4', path: 'capfill/clip.mp4',
-      type: 'video', media_type: 'image', mime_type: 'video/mp4',
-      source_origin: 'external', external_relpath: 'trip/clip.mp4',
-      uploaded_at: new Date().toISOString(), captured_at: null,
-    });
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-    expect(res.body.count).toBe(0);
-
-    const s = await status();
-    // And it is not counted as a permanent backlog either.
-    expect(s.body.total).toBe(0);
-    expect(s.body.withoutCaptureDate).toBe(0);
-  });
-
-  it('never reports more dated photos than it has photos', async () => {
-    // Both counts come from one aggregate; as two queries an import committing
-    // between them produced withCaptureDate > total and a negative backlog.
-    const { photoId } = await seed({ relpath: 'counted.jpg', exifIso: '2026-06-05T08:00:00Z' });
-    await db('photos').where({ id: photoId }).update({ captured_at: new Date().toISOString() });
-
-    const s = await status();
-    expect(s.body.total).toBe(1);
-    expect(s.body.withCaptureDate).toBe(1);
-    expect(s.body.withoutCaptureDate).toBe(0);
-    expect(s.body.withoutCaptureDate).toBeGreaterThanOrEqual(0);
-  });
-
-  it('skips archived events instead of failing them on every run', async () => {
-    // Archiving deletes the originals and keeps the rows, so an archived photo
-    // can never get a date. Counting it would fail it every pass and leave the
-    // status endpoint permanently reporting a backlog.
-    await seed({ relpath: 'archived.jpg', exifIso: '2026-06-04T09:00:00Z', archived: true });
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-
-    expect(res.body.count).toBe(0);
-    const s = await status();
-    expect(s.body.total).toBe(0);
-    expect(s.body.withoutCaptureDate).toBe(0);
-    expect(s.body.isRunning).toBe(false);
-  });
-
-  it('does not overwrite a date written while it was running', async () => {
-    // whereNull on the update: an import or a replacement finishing mid-run has
-    // already written a better value than this pass would.
-    const { photoId } = await seed({ relpath: 'c.jpg', exifIso: '2026-06-03T09:00:00Z' });
-    const claimed = '2020-01-01T00:00:00.000Z';
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-    expect(res.body.count).toBe(1);
-    await db('photos').where({ id: photoId }).update({ captured_at: claimed });
-    const done = await settle();
-
-    expect(new Date((await db('photos').where({ id: photoId }).first()).captured_at).toISOString()).toBe(claimed);
-    expect(done.body.lastResult.success).toBe(0);
-  });
-});

backend/__tests__/integration/categoryReorder.test.js

@@ -0,0 +1,211 @@
+/**
+ * Layered per-event category ordering (#782).
+ *
+ * Two ordering layers, resolved per event:
+ *   - GLOBAL default   — photo_categories.display_order (migration 159),
+ *                        set via POST /reorder-global; applies everywhere.
+ *   - PER-EVENT override — event_category_order (migration 160), set via
+ *                        POST /reorder; overrides the default for one gallery.
+ *   - DELETE /reorder/:eventId clears an event's override.
+ *
+ * Verified against a real SQLite DB with the full core-migration set applied.
+ */
+const request = require('supertest');
+const {
+  bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken, buildRouteApp,
+} = require('./helpers/crmDb');
+
+jest.setTimeout(120000);
+
+describe('category ordering (#782)', () => {
+  let db;
+  let cleanup;
+  let token;
+  let app;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    const { adminId } = await seedMinimal(db);
+    await assignAdminRole(db, adminId, 'super_admin');
+    token = mintAdminToken(adminId);
+    app = buildRouteApp('/api/admin/categories', require('../../src/routes/adminCategories'));
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  const auth = (r) => r.set('Authorization', `Bearer ${token}`);
+
+  async function insertEvent(slug) {
+    await db('events').insert({
+      event_type: 'wedding', password_hash: 'x',
+      expires_at: new Date(Date.now() + 9e9).toISOString(),
+      is_active: true, is_archived: false, slug, share_link: slug,
+      event_name: slug, event_date: '2026-01-01',
+    });
+    return (await db('events').where({ slug }).first()).id;
+  }
+
+  async function insertCat(name, { is_global = false, event_id = null, display_order = 0 } = {}) {
+    const res = await db('photo_categories').insert({
+      name,
+      slug: name.toLowerCase().replace(/\s+/g, '-'),
+      is_global: is_global ? 1 : 0,
+      event_id,
+      display_order,
+    }).returning('id');
+    return res[0]?.id ?? res[0];
+  }
+
+  const getEvent = (eventId) => auth(request(app).get(`/api/admin/categories/event/${eventId}`)).expect(200);
+
+  describe('migration 159 backfill', () => {
+    it('seeds display_order from alphabetical order, scoped per event', async () => {
+      const eventId = await insertEvent('backfill-ev');
+      await insertCat('Reception', { event_id: eventId });
+      await insertCat('Ceremony', { event_id: eventId });
+      await insertCat('Pre-Ceremony', { event_id: eventId });
+
+      // Re-run the migration: addColumn is guarded (no-op); the backfill loop
+      // re-runs and assigns per-scope alphabetical order — what an upgrade does.
+      await require('../../migrations/core/159_add_category_display_order').up(db);
+
+      const evCats = await db('photo_categories').where({ event_id: eventId }).orderBy('display_order', 'asc');
+      expect(evCats.map((c) => c.name)).toEqual(['Ceremony', 'Pre-Ceremony', 'Reception']);
+      expect(evCats.map((c) => c.display_order)).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe('global default order (POST /reorder-global)', () => {
+    it('reverses the global order and every non-customised event follows it', async () => {
+      const before = (await auth(request(app).get('/api/admin/categories/global')).expect(200)).body;
+      expect(before.length).toBeGreaterThan(1);
+      const reversedIds = before.map((c) => c.id).reverse();
+
+      const res = await auth(request(app).post('/api/admin/categories/reorder-global'))
+        .send({ orderedIds: reversedIds })
+        .expect(200);
+      expect(res.body.map((c) => c.id)).toEqual(reversedIds);
+
+      // A fresh event (no override) shows globals in the new global order.
+      const eventId = await insertEvent('follows-global');
+      const globalsInEvent = (await getEvent(eventId)).body.filter((c) => c.is_global).map((c) => c.id);
+      expect(globalsInEvent).toEqual(reversedIds);
+    });
+  });
+
+  describe('per-event override (POST /reorder)', () => {
+    it('pins a custom order for one event without affecting another', async () => {
+      const eventA = await insertEvent('override-a');
+      const eventB = await insertEvent('override-b');
+      const a1 = await insertCat('A-Ceremony', { event_id: eventA });
+      const a2 = await insertCat('A-Reception', { event_id: eventA });
+
+      // Current resolved list for A (globals + A's two categories).
+      const listA = (await getEvent(eventA)).body;
+      // Put A-Reception first, then A-Ceremony, then the globals in their order.
+      const globalsA = listA.filter((c) => c.is_global).map((c) => c.id);
+      const desired = [a2, a1, ...globalsA];
+
+      const res = await auth(request(app).post('/api/admin/categories/reorder'))
+        .send({ event_id: eventA, orderedIds: desired })
+        .expect(200);
+      expect(res.body.map((c) => c.id)).toEqual(desired);
+      // override_position is set on every row for a customised event.
+      expect(res.body.every((c) => c.override_position != null)).toBe(true);
+
+      // Event B is untouched — no override, follows the global default.
+      const listB = (await getEvent(eventB)).body;
+      expect(listB.every((c) => c.override_position == null)).toBe(true);
+    });
+
+    it('accepts global ids but rejects another event’s category', async () => {
+      const eventId = await insertEvent('scope-ev');
+      const own = await insertCat('Own', { event_id: eventId });
+      const global = (await db('photo_categories').where('is_global', 1).first()).id;
+      const foreign = await insertCat('Foreign', { event_id: await insertEvent('other-ev') });
+
+      // A global id is allowed (globals can be arranged per event).
+      await auth(request(app).post('/api/admin/categories/reorder'))
+        .send({ event_id: eventId, orderedIds: [own, global] })
+        .expect(200);
+
+      // A foreign event's category is out of scope.
+      await auth(request(app).post('/api/admin/categories/reorder'))
+        .send({ event_id: eventId, orderedIds: [own, foreign] })
+        .expect(400);
+    });
+  });
+
+  describe('reset (DELETE /reorder/:eventId)', () => {
+    it('clears the override and reverts to the global default', async () => {
+      const eventId = await insertEvent('reset-ev');
+      const c1 = await insertCat('R-One', { event_id: eventId });
+      const list = (await getEvent(eventId)).body;
+      const globals = list.filter((c) => c.is_global).map((c) => c.id);
+
+      await auth(request(app).post('/api/admin/categories/reorder'))
+        .send({ event_id: eventId, orderedIds: [c1, ...globals] })
+        .expect(200);
+      expect((await getEvent(eventId)).body.some((c) => c.override_position != null)).toBe(true);
+
+      const res = await auth(request(app).delete(`/api/admin/categories/reorder/${eventId}`)).expect(200);
+      expect(res.body.every((c) => c.override_position == null)).toBe(true);
+      expect(await db('event_category_order').where({ event_id: eventId }).first()).toBeUndefined();
+    });
+  });
+
+  describe('event ownership (PR #790 review)', () => {
+    let limitedToken;
+    let foreignEventId;
+
+    beforeAll(async () => {
+      const bcrypt = require('bcrypt');
+      // A non-super_admin role that DOES hold settings.view + settings.edit —
+      // the exact case the review flagged (settings.edit is grantable).
+      const roleRes = await db('roles').insert({ name: 'gallery-mgr', display_name: 'Gallery Mgr' }).returning('id');
+      const roleId = roleRes[0]?.id ?? roleRes[0];
+      const permIds = await db('permissions').whereIn('name', ['settings.view', 'settings.edit']).pluck('id');
+      await db('role_permissions').insert(permIds.map((permission_id) => ({ role_id: roleId, permission_id })));
+
+      const a2 = await db('admin_users').insert({
+        username: 'limited', email: 'limited@example.com',
+        password_hash: await bcrypt.hash('x', 4), role_id: roleId,
+        must_change_password: false, created_at: new Date(),
+      }).returning('id');
+      limitedToken = mintAdminToken(a2[0]?.id ?? a2[0]);
+
+      // An event owned by a DIFFERENT admin (the seeded super_admin).
+      const owner = (await db('admin_users').where({ username: 'tester' }).first()).id;
+      await db('events').insert({
+        event_type: 'wedding', password_hash: 'x',
+        expires_at: new Date(Date.now() + 9e9).toISOString(),
+        is_active: true, is_archived: false, slug: 'owned-ev', share_link: 'owned-ev',
+        event_name: 'Owned', event_date: '2026-01-01', created_by: owner,
+      });
+      foreignEventId = (await db('events').where({ slug: 'owned-ev' }).first()).id;
+    });
+
+    const limitedAuth = (r) => r.set('Authorization', `Bearer ${limitedToken}`);
+
+    it('blocks a non-owner from reading, reordering or resetting another event', async () => {
+      await limitedAuth(request(app).get(`/api/admin/categories/event/${foreignEventId}`)).expect(403);
+      await limitedAuth(request(app).post('/api/admin/categories/reorder'))
+        .send({ event_id: foreignEventId, orderedIds: [1] }).expect(403);
+      await limitedAuth(request(app).delete(`/api/admin/categories/reorder/${foreignEventId}`)).expect(403);
+    });
+  });
+
+  describe('POST / (create) appends to the end of its scope', () => {
+    it('assigns display_order = max + 1 within the event', async () => {
+      const eventId = await insertEvent('append-ev');
+      await insertCat('First', { event_id: eventId, display_order: 1 });
+      await insertCat('Second', { event_id: eventId, display_order: 2 });
+
+      const res = await auth(request(app).post('/api/admin/categories'))
+        .send({ name: 'Third', is_global: false, event_id: eventId })
+        .expect(200);
+
+      expect(res.body.display_order).toBe(3);
+    });
+  });
+});

backend/__tests__/integration/crmMintPaths.test.js

@@ -0,0 +1,413 @@
+/**
+ * CRM mint-and-send paths — integration tests (#587).
+ *
+ * Pins the three document "mint" flows end-to-end through the real
+ * HTTP → route → service → DB → email-queue → file pipeline:
+ *
+ *   1. POST /api/admin/quotes/:id/send        (draft → sent + PDF + token + email)
+ *   2. POST /api/admin/invoices/:id/cancel    (issued → cancelled + Storno row)
+ *      — the issue spec named this /:id/storno; the real route is
+ *        /:id/cancel (invoiceService.cancelInvoice → createStorno).
+ *   3. POST /api/admin/contracts/:id/countersign
+ *      (signed_by_customer → fully_signed + stamped PDF + sha256 + email)
+ *
+ * Real SQLite with the full core-migration run (helpers/crmDb), real
+ * pdfkit/pdf-lib rendering — no mock-fs, no network.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const request = require('supertest');
+const {
+  bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken, buildRouteApp,
+} = require('./helpers/crmDb');
+
+// Full migration run + cold-requiring pdfService/emailProcessor is slow
+// under CI load; match the other CRM integration suites.
+jest.setTimeout(120000);
+
+const CUSTOMER_EMAIL = 'customer@example.com';
+
+// 1x1 transparent PNG — smallest valid signature pad output.
+const SIGNATURE_DATA_URL = 'data:image/png;base64,'
+  + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
+
+// SQLite round-trips dates inconsistently (epoch ms number, numeric
+// string, or ISO string) — parse robustly before comparing.
+const toMillis = (v) => {
+  if (typeof v === 'number') return v;
+  if (typeof v === 'string' && /^\d+$/.test(v)) return Number(v);
+  return Date.parse(v);
+};
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+// Count embedded image XObjects per page via pdf-lib — used to prove BOTH
+// signature stamps (customer + admin) made it into the final PDF instead of
+// only asserting file existence/hash (codex review of #850 round 2).
+async function countImagesPerPage(pdfPath) {
+  const { PDFDocument, PDFName, PDFDict } = require('pdf-lib');
+  const doc = await PDFDocument.load(fs.readFileSync(pdfPath));
+  return doc.getPages().map((page) => {
+    const resources = page.node.Resources();
+    const xobjects = resources && resources.lookupMaybe(PDFName.of('XObject'), PDFDict);
+    if (!xobjects) return 0;
+    let images = 0;
+    for (const [, ref] of xobjects.entries()) {
+      const stream = page.doc.context.lookup(ref);
+      const subtype = stream && stream.dict && stream.dict.get(PDFName.of('Subtype'));
+      if (subtype && subtype.toString() === '/Image') images += 1;
+    }
+    return images;
+  });
+}
+
+let db;
+let cleanup;
+let tmpDir;
+// Real (symlink-resolved) storage root — on macOS os.tmpdir() returns
+// /var/... while the services persist under process.cwd() which
+// resolves to /private/var/....
+let storageRoot;
+let adminId;
+let customerId;
+let token;
+let quoteApp;
+let invoiceApp;
+let contractApp;
+let quoteService;
+let invoiceService;
+let contractService;
+
+const prevCwd = process.cwd();
+
+const auth = { get Authorization() { return `Bearer ${token}`; } };
+
+async function enableFlag(key) {
+  const updated = await db('feature_flags').where({ key }).update({ value: true });
+  if (!updated) await db('feature_flags').insert({ key, value: true });
+}
+
+// ----- per-path seed helpers -----------------------------------------
+
+async function seedQuote() {
+  const id = await quoteService.createQuote({
+    customerAccountId: customerId,
+    currency: 'CHF',
+    vatRate: 0,
+    eventName: 'Testshooting',
+    lineItems: [
+      { position: 1, quantity: 1, description: 'Photo package', unit_price_minor: 150000, discount_percent: 0 },
+    ],
+  }, adminId);
+  return id;
+}
+
+async function seedIssuedInvoice(status = 'sent') {
+  const { invoiceIds } = await invoiceService.createInvoice({
+    customerAccountId: customerId,
+    currency: 'CHF',
+    vatRate: 7.7,
+    lineItems: [
+      { position: 1, quantity: 1, description: 'Wedding coverage', unit_price_minor: 200000, discount_percent: 0 },
+    ],
+  }, adminId);
+  const id = invoiceIds[0];
+  // Fast-forward past the send step — Storno only applies to issued
+  // documents (sent/paid/overdue), and rendering+sending the original
+  // is covered by the quote path already.
+  await db('invoices').where({ id }).update({
+    status, sent_at: new Date(), updated_at: new Date(),
+  });
+  return db('invoices').where({ id }).first();
+}
+
+async function seedCustomerSignedContract() {
+  const id = await contractService.createContract({
+    customerAccountId: customerId,
+    title: 'Fotografie-Vertrag',
+  }, adminId);
+  // Real send + customer-sign flow (codex review of #850): a direct
+  // status UPDATE skipped the customer's signature asset and stamped
+  // PDF, so countersign exercised its unsigned-PDF fallback and a
+  // regression dropping the customer's signature would stay green.
+  const { token } = await contractService.sendContract(id, adminId);
+  await contractService.recordCustomerSignature({
+    token,
+    name: 'Custo Mer',
+    ip: '127.0.0.1',
+    signatureDataUrl: SIGNATURE_DATA_URL,
+    accepted: true,
+  });
+  return db('contracts').where({ id }).first();
+}
+
+// ----- suite ----------------------------------------------------------
+
+beforeAll(async () => {
+  ({ db, cleanup, tmpDir } = await bootCrmDb());
+  // Business-doc PDFs (quotes/invoices/contracts) persist under
+  // `process.cwd()/storage/business-docs/...` — chdir into the temp dir
+  // so every test artifact lands isolated and gets cleaned up.
+  process.chdir(tmpDir);
+  storageRoot = path.join(fs.realpathSync(tmpDir), 'storage', 'business-docs');
+
+  // Fail-fast on the pre-existing logActivity-inside-transaction
+  // deadlock: createContract and createStorno call logActivity() from
+  // inside a knex transaction WITHOUT passing the trx as executor, so
+  // the audit insert tries to grab a second connection from the
+  // single-connection SQLite pool while the trx holds it. In
+  // production that stalls each call for the full 60 s acquire
+  // timeout (the error is then swallowed by logActivity's catch);
+  // here we shrink the timeout so the same swallowed failure costs
+  // 2 s instead of blowing the per-test budget. Behaviour under test
+  // is unchanged — the mint paths themselves never wait on this.
+  db.client.pool.acquireTimeoutMillis = 2000;
+
+  // node-sqlite3 detects Date bind params via `InstanceOf(global.Date)`
+  // against the NATIVE realm's Date — under jest's vm sandbox the
+  // service code's `new Date()` is a different constructor, the check
+  // fails, and the value stringifies to the literal "[object Object]"
+  // (the exact pathology helpers/crmDb.js documents for
+  // createPublicToken). Normalize Date bindings to ISO strings before
+  // they reach the driver so the real service inserts round-trip the
+  // same way they do outside jest.
+  // Patch on the prototype — knex mints transaction clients via
+  // Object.create(prototype), so an instance-level patch would miss
+  // every query issued inside a db.transaction().
+  const clientProto = Object.getPrototypeOf(db.client);
+  const origQuery = clientProto._query;
+  clientProto._query = function patchedQuery(connection, obj) {
+    if (obj && Array.isArray(obj.bindings)) {
+      obj.bindings = obj.bindings.map(
+        (b) => (b && typeof b === 'object' && typeof b.toISOString === 'function' ? b.toISOString() : b),
+      );
+    }
+    return origQuery.call(this, connection, obj);
+  };
+
+  ({ adminId, customerId } = await seedMinimal(db));
+  await assignAdminRole(db, adminId, 'super_admin');
+  token = mintAdminToken(adminId);
+
+  // CRM surfaces are feature-flagged; migration 107 seeds them OFF.
+  await enableFlag('quotes');
+  await enableFlag('bills');
+  await enableFlag('contracts');
+
+  quoteService = require('../../src/services/quoteService');
+  invoiceService = require('../../src/services/invoiceService');
+  contractService = require('../../src/services/contractService');
+
+  quoteApp = buildRouteApp('/api/admin/quotes', require('../../src/routes/adminQuotes'));
+  invoiceApp = buildRouteApp('/api/admin/invoices', require('../../src/routes/adminInvoices'));
+  contractApp = buildRouteApp('/api/admin/contracts', require('../../src/routes/adminContracts'));
+}, 120000);
+
+afterAll(async () => {
+  process.chdir(prevCwd);
+  if (cleanup) await cleanup();
+});
+
+describe('POST /api/admin/quotes/:id/send', () => {
+  test('draft quote: 200 → sent + sent_at + PDF on disk + action token + quote_sent email', async () => {
+    const quoteId = await seedQuote();
+    await db('email_queue').del();
+
+    const res = await request(quoteApp)
+      .post(`/api/admin/quotes/${quoteId}/send`)
+      .set(auth);
+    expect(res.status).toBe(200);
+    expect(res.body.sent).toBe(true);
+    expect(res.body.token).toMatch(/^[0-9a-f]{64}$/);
+
+    // DB state
+    const quote = await db('quotes').where({ id: quoteId }).first();
+    expect(quote.status).toBe('sent');
+    expect(quote.sent_at).toBeTruthy();
+
+    // PDF persisted inside the isolated storage root
+    expect(quote.pdf_path).toBeTruthy();
+    expect(quote.pdf_path.startsWith(path.join(storageRoot, 'quote'))).toBe(true);
+    expect(fs.existsSync(quote.pdf_path)).toBe(true);
+    expect(fs.statSync(quote.pdf_path).size).toBeGreaterThan(0);
+
+    // Action token row: right quote, future expiry
+    const tokenRow = await db('quote_action_tokens').where({ token: res.body.token }).first();
+    expect(tokenRow).toBeTruthy();
+    expect(tokenRow.quote_id).toBe(quoteId);
+    expect(toMillis(tokenRow.expires_at)).toBeGreaterThan(Date.now());
+
+    // Email queued to the customer's primary address
+    const emails = await db('email_queue').where({ email_type: 'quote_sent' });
+    expect(emails).toHaveLength(1);
+    expect(emails[0].recipient_email).toBe(CUSTOMER_EMAIL);
+    const emailData = JSON.parse(emails[0].email_data);
+    expect(emailData.quote_number).toBe(quote.quote_number);
+  });
+
+  test('already-sent quote: 409 (spec said 400; service throws 409)', async () => {
+    const quoteId = await seedQuote();
+    await request(quoteApp).post(`/api/admin/quotes/${quoteId}/send`).set(auth).expect(200);
+
+    const res = await request(quoteApp)
+      .post(`/api/admin/quotes/${quoteId}/send`)
+      .set(auth);
+    expect(res.status).toBe(409);
+    expect(res.body.error).toMatch(/cannot send a quote with status 'sent'/i);
+  });
+});
+
+describe('POST /api/admin/invoices/:id/cancel (Storno mint)', () => {
+  test('sent invoice: original cancelled, Storno row minted with negated totals + lineage', async () => {
+    const original = await seedIssuedInvoice('sent');
+    await db('email_queue').del();
+
+    const res = await request(invoiceApp)
+      .post(`/api/admin/invoices/${original.id}/cancel`)
+      .set(auth);
+    // Route responds via successResponse default — 200, not the 201
+    // the issue spec assumed.
+    expect(res.status).toBe(200);
+    expect(res.body.cancelled).toBe(true);
+    expect(res.body.stornoId).toBeGreaterThan(0);
+
+    const storno = await db('invoices').where({ id: res.body.stornoId }).first();
+    expect(storno.kind).toBe('storno');
+    expect(storno.cancels_invoice_id).toBe(original.id);
+    expect(storno.deal_uuid).toBe(original.deal_uuid);
+
+    // Negated amounts
+    expect(storno.net_amount_minor).toBe(-original.net_amount_minor);
+    expect(storno.vat_amount_minor).toBe(-original.vat_amount_minor);
+    expect(storno.total_amount_minor).toBe(-original.total_amount_minor);
+
+    // Freshly sequenced number from the same series
+    expect(typeof storno.invoice_number).toBe('string');
+    expect(storno.invoice_number.length).toBeGreaterThan(0);
+    expect(storno.invoice_number).not.toBe(original.invoice_number);
+
+    // Line items snapshotted onto the Storno
+    const originalItems = await db('invoice_line_items').where({ invoice_id: original.id });
+    const stornoItems = await db('invoice_line_items').where({ invoice_id: storno.id });
+    expect(stornoItems).toHaveLength(originalItems.length);
+
+    // Original flipped + back-linked
+    const refreshed = await db('invoices').where({ id: original.id }).first();
+    expect(refreshed.status).toBe('cancelled');
+    expect(refreshed.cancellation_storno_id).toBe(storno.id);
+
+    // sendStorno side effects (codex review of #850): cancelInvoice
+    // swallows a sendStorno failure by design, so without these
+    // assertions a broken render/persist/queue leg would stay green.
+    const sentStorno = await db('invoices').where({ id: storno.id }).first();
+    expect(sentStorno.status).toBe('sent');
+    expect(sentStorno.pdf_path).toBeTruthy();
+    expect(fs.existsSync(sentStorno.pdf_path)).toBe(true);
+    const stornoEmails = await db('email_queue').where({ email_type: 'storno_issued' });
+    expect(stornoEmails.length).toBeGreaterThanOrEqual(1);
+    expect(stornoEmails[0].recipient_email).toBe(CUSTOMER_EMAIL);
+  });
+
+  test('paid invoice can be cancelled via Storno too (refund document leg)', async () => {
+    const original = await seedIssuedInvoice('paid');
+
+    const res = await request(invoiceApp)
+      .post(`/api/admin/invoices/${original.id}/cancel`)
+      .set(auth);
+    expect(res.status).toBe(200);
+    expect(res.body.stornoId).toBeGreaterThan(0);
+
+    const refreshed = await db('invoices').where({ id: original.id }).first();
+    expect(refreshed.status).toBe('cancelled');
+  });
+
+  test('already-cancelled invoice: 409 ALREADY_CANCELLED', async () => {
+    const original = await seedIssuedInvoice('sent');
+    await request(invoiceApp).post(`/api/admin/invoices/${original.id}/cancel`).set(auth).expect(200);
+
+    const res = await request(invoiceApp)
+      .post(`/api/admin/invoices/${original.id}/cancel`)
+      .set(auth);
+    expect(res.status).toBe(409);
+    expect(res.body.code).toBe('ALREADY_CANCELLED');
+  });
+});
+
+describe('POST /api/admin/contracts/:id/countersign', () => {
+  test('customer-signed contract: 200 → fully_signed + stamped PDF + sha256 + signature asset + email with attachment', async () => {
+    const contract = await seedCustomerSignedContract();
+    await db('email_queue').del();
+
+    const res = await request(contractApp)
+      .post(`/api/admin/contracts/${contract.id}/countersign`)
+      .set(auth)
+      .send({ name: 'Admin Tester', signatureDataUrl: SIGNATURE_DATA_URL });
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('fully_signed');
+
+    const row = await db('contracts').where({ id: contract.id }).first();
+    expect(row.status).toBe('fully_signed');
+    expect(row.signed_admin_name).toBe('Admin Tester');
+    expect(row.signed_by_admin_at).toBeTruthy();
+
+    // The customer's own signature (from the real sign flow in the seed)
+    // must survive countersigning — layered, not replaced.
+    expect(row.signed_customer_signature_path).toBeTruthy();
+    expect(fs.existsSync(row.signed_customer_signature_path)).toBe(true);
+    expect(row.signed_customer_name).toBe('Custo Mer');
+
+    // Admin signature image persisted under the storage root
+    expect(row.signed_admin_signature_path).toBeTruthy();
+    expect(row.signed_admin_signature_path.startsWith(
+      path.join(storageRoot, 'contract', 'signatures'),
+    )).toBe(true);
+    expect(fs.existsSync(row.signed_admin_signature_path)).toBe(true);
+
+    // Stamped, fully-signed PDF written and hashed. The issue spec
+    // called this `integrity_hash`; the real column is
+    // `signed_pdf_sha256` (plus `pdf_sha256` for the unsigned base).
+    expect(row.signed_pdf_render_failed_at).toBeFalsy();
+    expect(row.signed_pdf_path).toBeTruthy();
+    expect(fs.existsSync(row.signed_pdf_path)).toBe(true);
+    expect(row.signed_pdf_sha256).toMatch(/^[0-9a-f]{64}$/);
+    expect(sha256(fs.readFileSync(row.signed_pdf_path))).toBe(row.signed_pdf_sha256);
+
+    // BOTH stamps must be embedded in the final document — a regression
+    // stamping the admin onto the unsigned base PDF would keep every
+    // path/hash assertion above green (codex review of #850 round 2).
+    const imagesPerPage = await countImagesPerPage(row.signed_pdf_path);
+    const maxImagesOnAPage = Math.max(...imagesPerPage);
+    expect(maxImagesOnAPage).toBeGreaterThanOrEqual(2);
+
+    // contract_fully_signed email to the customer's primary address,
+    // carrying the signed PDF as attachment (plus the audit cert).
+    const emails = await db('email_queue').where({ email_type: 'contract_fully_signed' });
+    const customerCopy = emails.find((e) => e.recipient_email === CUSTOMER_EMAIL);
+    expect(customerCopy).toBeTruthy();
+    const emailData = JSON.parse(customerCopy.email_data);
+    expect(emailData.contract_number).toBe(contract.contract_number);
+    expect(Array.isArray(emailData.attachments)).toBe(true);
+    const pdfAttachment = emailData.attachments.find(
+      (a) => a.filename === `${contract.contract_number}-signed.pdf`,
+    );
+    expect(pdfAttachment).toBeTruthy();
+    expect(pdfAttachment.contentType).toBe('application/pdf');
+    expect(fs.existsSync(pdfAttachment.contentPath)).toBe(true);
+  });
+
+  test('draft contract: 409 — countersign requires sent/signed_by_customer', async () => {
+    const draftId = await contractService.createContract({
+      customerAccountId: customerId,
+      title: 'Noch nicht versendet',
+    }, adminId);
+
+    const res = await request(contractApp)
+      .post(`/api/admin/contracts/${draftId}/countersign`)
+      .set(auth)
+      .send({ name: 'Admin Tester' });
+    expect(res.status).toBe(409);
+    expect(res.body.error).toMatch(/cannot counter-sign a contract with status 'draft'/i);
+  });
+});

backend/__tests__/integration/downloadResolutions.test.js

@@ -0,0 +1,256 @@
+/**
+ * Download resolutions (#858).
+ *
+ * Pins the contracts that are easy to break later:
+ *
+ *  - the global → per-event cascade, including NULL = inherit
+ *  - the picker never offers a size ABOVE the standard (a photographer who
+ *    lowers the standard is not silently handing out full-res), and 'Original'
+ *    only reappears when the admin explicitly allows it
+ *  - `fit: 'inside'` + no-upscaling resize semantics, which is exactly what
+ *    the requester asked for on the issue
+ *  - a guest-supplied resolution is validated against the policy rather than
+ *    trusted
+ */
+
+const sharp = require('sharp');
+
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+// Both modules under test pull in src/database/db.js transitively. bootCrmDb
+// only works when it runs BEFORE the first require of db.js (it sets
+// TEST_DATABASE_PATH, which knexfile reads at module-init time), so these are
+// required lazily in beforeAll rather than at module scope — otherwise knex
+// binds to the shared default SQLite file and every run after the first one
+// fails with "table `migrations` already exists".
+let resolveEventDownloadPolicy;
+let pickRequestedResolution;
+let parseResolution;
+let invalidateDownloadGlobals;
+let resizeToBox;
+
+describe('Download resolutions (#858)', () => {
+  let db;
+  let cleanup;
+
+  const setGlobal = async (key, value) => {
+    await db('app_settings').where({ setting_key: key }).del();
+    await db('app_settings').insert({
+      setting_key: key,
+      setting_value: JSON.stringify(value),
+      setting_type: 'download',
+      updated_at: new Date().toISOString(),
+    });
+    invalidateDownloadGlobals();
+  };
+
+  const PRESETS = [
+    { label: 'Large', width: 3000, height: 2000 },
+    { label: 'Medium', width: 1500, height: 1000 },
+    { label: 'Small', width: 800, height: 600 },
+  ];
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    await seedMinimal(db);
+
+    ({
+      resolveEventDownloadPolicy,
+      pickRequestedResolution,
+      parseResolution,
+      invalidateDownloadGlobals,
+    } = require('../../src/utils/downloadResolutions'));
+    ({ resizeToBox } = require('../../src/services/imageProcessor'));
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  beforeEach(async () => {
+    await setGlobal('download_resolutions', PRESETS);
+    await setGlobal('download_standard_resolution', 'original');
+    await setGlobal('download_resolution_picker_enabled', false);
+    await setGlobal('download_allow_original', false);
+  });
+
+  describe('cascade', () => {
+    it('inherits the global standard when the event has no override', async () => {
+      await setGlobal('download_standard_resolution', '1500x1000');
+      const policy = await resolveEventDownloadPolicy({ download_standard_resolution: null });
+      expect(policy.standard).toBe('1500x1000');
+      expect(policy.standardBox).toEqual({ width: 1500, height: 1000 });
+    });
+
+    it('lets an event override the global standard', async () => {
+      await setGlobal('download_standard_resolution', '1500x1000');
+      const policy = await resolveEventDownloadPolicy({ download_standard_resolution: '800x600' });
+      expect(policy.standard).toBe('800x600');
+    });
+
+    it('treats a NULL picker flag as inherit and an explicit false as override', async () => {
+      await setGlobal('download_resolution_picker_enabled', true);
+      expect((await resolveEventDownloadPolicy({ download_resolution_picker_enabled: null })).pickerEnabled).toBe(true);
+      expect((await resolveEventDownloadPolicy({ download_resolution_picker_enabled: false })).pickerEnabled).toBe(false);
+    });
+  });
+
+  describe('choice list', () => {
+    it('never offers a size larger than the standard', async () => {
+      await setGlobal('download_standard_resolution', '1500x1000');
+      const { choices } = await resolveEventDownloadPolicy({});
+      expect(choices.map((c) => c.id)).toEqual(['1500x1000', '800x600']);
+      // The regression that matters: 3000x2000 must not be reachable.
+      expect(choices.some((c) => c.id === '3000x2000')).toBe(false);
+    });
+
+    it('bounds EACH dimension, not the pixel area (codex review round 2)', async () => {
+      // 2000x700 is 1.4MP — under 1500x1000's 1.5MP — so an area comparison
+      // would offer it and hand back a 2000px-wide file despite a 1500px cap.
+      await setGlobal('download_resolutions', [
+        ...PRESETS,
+        { label: 'Wide', width: 2000, height: 700 },
+      ]);
+      await setGlobal('download_standard_resolution', '1500x1000');
+      const { choices } = await resolveEventDownloadPolicy({});
+      expect(choices.some((c) => c.id === '2000x700')).toBe(false);
+    });
+
+    it('omits Original when the standard is capped and the admin has not allowed it', async () => {
+      await setGlobal('download_standard_resolution', '1500x1000');
+      const { choices } = await resolveEventDownloadPolicy({});
+      expect(choices.some((c) => c.id === 'original')).toBe(false);
+    });
+
+    it('re-adds Original when the admin explicitly allows it', async () => {
+      await setGlobal('download_standard_resolution', '1500x1000');
+      await setGlobal('download_allow_original', true);
+      const { choices } = await resolveEventDownloadPolicy({});
+      expect(choices[0].id).toBe('original');
+    });
+
+    it('offers Original when the standard already is original', async () => {
+      const { choices } = await resolveEventDownloadPolicy({});
+      expect(choices[0].id).toBe('original');
+      expect(choices.map((c) => c.id)).toContain('3000x2000');
+    });
+  });
+
+  describe('request validation', () => {
+    it('falls back to the standard when nothing is requested', async () => {
+      await setGlobal('download_standard_resolution', '1500x1000');
+      const policy = await resolveEventDownloadPolicy({});
+      expect(pickRequestedResolution(policy, undefined)).toBe('1500x1000');
+    });
+
+    it('refuses any explicit request while the picker is off', async () => {
+      const policy = await resolveEventDownloadPolicy({});
+      expect(policy.pickerEnabled).toBe(false);
+      expect(pickRequestedResolution(policy, '800x600')).toBeNull();
+    });
+
+    it('refuses a size that is not on the offered list', async () => {
+      await setGlobal('download_resolution_picker_enabled', true);
+      await setGlobal('download_standard_resolution', '1500x1000');
+      const policy = await resolveEventDownloadPolicy({});
+      // Above the standard → not offered → rejected rather than silently served.
+      expect(pickRequestedResolution(policy, '3000x2000')).toBeNull();
+      expect(pickRequestedResolution(policy, '9999x9999')).toBeNull();
+      expect(pickRequestedResolution(policy, '800x600')).toBe('800x600');
+    });
+
+    it('parses only well-formed resolution ids', () => {
+      expect(parseResolution('original')).toBeNull();
+      expect(parseResolution(null)).toBeNull();
+      expect(parseResolution('abc')).toBeNull();
+      expect(parseResolution('0x0')).toBeNull();
+      expect(parseResolution('1500x1000')).toEqual({ width: 1500, height: 1000 });
+    });
+  });
+
+  describe('job dedup identity (codex review round 1)', () => {
+    // The leak this pins: a PIN client's archive contains hidden photos. If the
+    // dedup key ignored the visibility scope, a guest asking for the same size
+    // would be handed the client's job token — and the delivery route only
+    // checked the event id.
+    let jobService;
+
+    beforeAll(() => {
+      jobService = require('../../src/services/downloadJobService');
+    });
+
+    it('separates client and guest archives of the same size and photo set', () => {
+      const guest = jobService.dedupKey(1, '1500x1000', [1, 2, 3], false, 'public');
+      const client = jobService.dedupKey(1, '1500x1000', [1, 2, 3], false, 'hidden');
+      expect(guest).not.toBe(client);
+    });
+
+    it('keys on the RESOLVED photo set, so a stale archive is not reused', () => {
+      const before = jobService.dedupKey(1, '1500x1000', [1, 2, 3], false, 'public');
+      const afterUpload = jobService.dedupKey(1, '1500x1000', [1, 2, 3, 4], false, 'public');
+      const afterHide = jobService.dedupKey(1, '1500x1000', [1, 2], false, 'public');
+      expect(new Set([before, afterUpload, afterHide]).size).toBe(3);
+    });
+
+    it('is order-independent for the same set', () => {
+      expect(jobService.dedupKey(1, 'original', [3, 1, 2], true, 'public'))
+        .toBe(jobService.dedupKey(1, 'original', [1, 2, 3], true, 'public'));
+    });
+
+    it('maps access levels onto the two visibility scopes', () => {
+      expect(jobService.visibilityScopeFor('client')).toBe('hidden');
+      expect(jobService.visibilityScopeFor('guest')).toBe('public');
+      expect(jobService.visibilityScopeFor(undefined)).toBe('public');
+    });
+  });
+
+  describe('resize semantics', () => {
+    const make = (w, h) => sharp({
+      create: { width: w, height: h, channels: 3, background: { r: 10, g: 100, b: 200 } },
+    }).jpeg().toBuffer();
+
+    const box = { width: 1500, height: 1000 };
+
+    it('fits a 3:2 photo exactly into a 3:2 box', async () => {
+      const out = await sharp(await resizeToBox(await make(6000, 4000), box)).metadata();
+      expect([out.width, out.height]).toEqual([1500, 1000]);
+    });
+
+    it('treats the box as an "up to" bound for other aspect ratios', async () => {
+      // Portrait: height is the binding edge, width comes out smaller.
+      const portrait = await sharp(await resizeToBox(await make(4000, 6000), box)).metadata();
+      expect(portrait.height).toBe(1000);
+      expect(portrait.width).toBeLessThan(1500);
+
+      const fourThree = await sharp(await resizeToBox(await make(4000, 3000), box)).metadata();
+      expect(fourThree.height).toBe(1000);
+      expect(fourThree.width).toBeLessThan(1500);
+    });
+
+    it('never upscales an image already smaller than the box', async () => {
+      const out = await sharp(await resizeToBox(await make(800, 600), box)).metadata();
+      expect([out.width, out.height]).toEqual([800, 600]);
+    });
+
+    it('passes the buffer through untouched for the original size', async () => {
+      const src = await make(4000, 3000);
+      expect(await resizeToBox(src, null)).toBe(src);
+    });
+
+    it('keeps the source format so the filename and mime type stay honest', async () => {
+      // A .gif re-encoded as JPEG would ship mislabelled bytes, since the
+      // download routes keep the original filename and mime type.
+      const gif = await sharp({
+        create: { width: 4000, height: 3000, channels: 3, background: { r: 1, g: 2, b: 3 } },
+      }).gif().toBuffer();
+      const out = await sharp(await resizeToBox(gif, box)).metadata();
+      expect(out.format).toBe('gif');
+      expect(out.width).toBe(1333);
+    });
+
+    it('returns the input rather than throwing on an undecodable source', async () => {
+      const junk = Buffer.from('not an image');
+      expect(await resizeToBox(junk, box)).toBe(junk);
+    });
+  });
+});

backend/__tests__/integration/eventTypeDefaults.test.js

@@ -0,0 +1,50 @@
+/**
+ * Catalog-driven event-type defaults (#800 follow-up).
+ *
+ * The contract→event conversion used to hardcode `event_type: 'wedding'` and
+ * the v1 API validated against a fixed whitelist. Both now follow the live
+ * event_types catalog; these tests pin the shared resolver.
+ */
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+describe('resolveDefaultEventType follows the catalog', () => {
+  let db;
+  let cleanup;
+  let eventTypeService;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    // Require AFTER bootCrmDb so the service shares this db instance
+    // (see crmDb.js — a second knex pool on one SQLite file deadlocks).
+    eventTypeService = require('../../src/services/eventTypeService');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  it("prefers the 'other' catch-all while it is active", async () => {
+    expect(await eventTypeService.resolveDefaultEventType()).toBe('other');
+  });
+
+  it('falls over to the first active type when other is deactivated', async () => {
+    const other = await db('event_types').where({ slug_prefix: 'other' }).first();
+    await db('event_types').where({ id: other.id }).update({ is_active: 0 });
+
+    const resolved = await eventTypeService.resolveDefaultEventType();
+    expect(resolved).not.toBe('other');
+    expect(await db('event_types').where({ slug_prefix: resolved }).first()).toBeTruthy();
+
+    await db('event_types').where({ id: other.id }).update({ is_active: 1 });
+  });
+
+  it("returns the literal 'other' only for an empty catalog", async () => {
+    const rows = await db('event_types').select('*');
+    await db('event_types').del();
+
+    expect(await eventTypeService.resolveDefaultEventType()).toBe('other');
+
+    await db('event_types').insert(rows);
+  });
+});

backend/__tests__/integration/eventTypeSetupWindow.test.js

@@ -0,0 +1,133 @@
+/**
+ * Setup-window event type deletion (#800).
+ *
+ * The first-run setup wizard may delete the seeded SYSTEM event types —
+ * but ONLY while the `setup_wizard_completed` flag is unset (migration 161
+ * seeds it false on a fresh install, true when an admin already exists).
+ * These tests pin the whole contract:
+ *
+ *   - fresh install → flag false → system types deletable (in-use checks
+ *     still apply), and the per-type reminder template goes with the type
+ *   - reminder-template self-heal does NOT resurrect templates for slugs
+ *     that no longer exist in the catalog
+ *   - after markSetupWizardCompleted() → system deletion is refused again
+ */
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+describe('event type deletion during the setup window (#800)', () => {
+  let db;
+  let cleanup;
+  let eventTypeService;
+  let setupService;
+  let ensureEventReminderTemplatesSeeded;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    // Require AFTER bootCrmDb so every service shares this db instance
+    // (see crmDb.js — a second knex pool on one SQLite file deadlocks).
+    eventTypeService = require('../../src/services/eventTypeService');
+    setupService = require('../../src/services/setupService');
+    ({ ensureEventReminderTemplatesSeeded } = require('../../src/services/eventReminderTemplates'));
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  it('migration 161 seeds the flag false on a fresh (admin-less) install', async () => {
+    const row = await db('app_settings').where({ setting_key: 'setup_wizard_completed' }).first();
+    expect(row).toBeTruthy();
+    expect(JSON.parse(row.setting_value)).toBe(false);
+    expect(await setupService.isSetupWizardCompleted()).toBe(false);
+  });
+
+  it('refuses to delete a system type that events already use, even in the window', async () => {
+    const corporate = await db('event_types').where({ slug_prefix: 'corporate' }).first();
+    await db('events').insert({
+      slug: 'corporate-test-2026-01-01',
+      event_name: 'Test',
+      event_type: 'corporate',
+      event_date: '2026-01-01',
+      host_email: 'host@example.com',
+      admin_email: 'admin@example.com',
+      password_hash: 'x',
+      share_link: 'share-corporate-test',
+      expires_at: new Date(Date.now() + 86400000),
+    });
+
+    await expect(eventTypeService.deleteEventType(corporate.id))
+      .rejects.toMatchObject({ code: 'IN_USE' });
+  });
+
+  it('deletes an unused system type in the window, taking its reminder template along', async () => {
+    // Seed the per-type reminder templates first so there is something to clean up.
+    await ensureEventReminderTemplatesSeeded(db);
+    expect(await db('email_templates').where({ template_key: 'event_reminder_wedding' }).first()).toBeTruthy();
+
+    const wedding = await db('event_types').where({ slug_prefix: 'wedding' }).first();
+    expect(wedding.is_system).toBeTruthy();
+
+    const result = await eventTypeService.deleteEventType(wedding.id);
+    expect(result.success).toBe(true);
+
+    expect(await db('event_types').where({ slug_prefix: 'wedding' }).first()).toBeFalsy();
+    expect(await db('email_templates').where({ template_key: 'event_reminder_wedding' }).first()).toBeFalsy();
+
+    // The deleted slug must NOT stay creatable through the legacy fallback —
+    // the live catalog is authoritative while it has rows.
+    expect(await eventTypeService.isValidEventType('wedding')).toBe(false);
+    expect(await eventTypeService.isValidEventType('birthday')).toBe(true);
+  });
+
+  it('does not resurrect reminder templates for deleted types on the next self-heal pass', async () => {
+    // The seeder caches success per process — reset the module to force a
+    // genuine second pass, exactly what a backend restart would run.
+    jest.resetModules();
+    const fresh = require('../../src/services/eventReminderTemplates');
+    await fresh.ensureEventReminderTemplatesSeeded(db);
+
+    expect(await db('email_templates').where({ template_key: 'event_reminder_wedding' }).first()).toBeFalsy();
+    // Types still in the catalog keep their templates.
+    expect(await db('email_templates').where({ template_key: 'event_reminder_birthday' }).first()).toBeTruthy();
+    expect(await db('email_templates').where({ template_key: 'event_reminder_default' }).first()).toBeTruthy();
+  });
+
+  it('re-locks system types once the wizard is marked complete', async () => {
+    await setupService.markSetupWizardCompleted();
+    expect(await setupService.isSetupWizardCompleted()).toBe(true);
+
+    const birthday = await db('event_types').where({ slug_prefix: 'birthday' }).first();
+    await expect(eventTypeService.deleteEventType(birthday.id))
+      .rejects.toMatchObject({ code: 'SYSTEM_TYPE' });
+
+    // Custom (non-system) types remain deletable as before.
+    const custom = await eventTypeService.createEventType({ name: 'Family', slug_prefix: 'family' });
+    const result = await eventTypeService.deleteEventType(custom.id);
+    expect(result.success).toBe(true);
+  });
+
+  it('fails closed when the completion marker row is missing', async () => {
+    // A portable-backup restore can replace app_settings with a set that
+    // predates migration 161 (which will not rerun) — absence must mean
+    // "configured instance", never an open deletion window.
+    await db('app_settings').where({ setting_key: 'setup_wizard_completed' }).del();
+    expect(await setupService.isSetupWizardCompleted()).toBe(true);
+    await setupService.markSetupWizardCompleted();
+  });
+
+  it('refuses to delete the last remaining event type', async () => {
+    // Reduce the catalog to a single custom type via direct db writes (the
+    // service paths are already covered above), then hit the guard.
+    const solo = await eventTypeService.createEventType({ name: 'Solo', slug_prefix: 'solo' });
+    await db('events').del();
+    await db('event_types').whereNot('id', solo.id).del();
+
+    await expect(eventTypeService.deleteEventType(solo.id))
+      .rejects.toMatchObject({ code: 'LAST_TYPE' });
+
+    // Deactivating it would empty the ACTIVE catalog just the same.
+    await expect(eventTypeService.updateEventType(solo.id, { is_active: false }))
+      .rejects.toMatchObject({ code: 'LAST_ACTIVE' });
+  });
+});

backend/__tests__/integration/externalImportCaptureDate.test.js

@@ -1,161 +0,0 @@
-/**
- * External imports must record captured_at (#1172).
- *
- * Managed uploads get it from photoProcessor, which external media never goes
- * through — so every externally imported photo carried captured_at NULL, and
- * the gallery's "Date Taken" sort fell back to uploaded_at through its
- * COALESCE. On a library imported in two batches that ordered a 12-day trip by
- * which folder was imported first: the reporter's first two days landed at
- * positions 4204-5296 of 5555.
- *
- * Driven through the real route against real files carrying real EXIF, because
- * the whole question is whether the import reads the file it already has open.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const express = require('express');
-const request = require('supertest');
-const sharp = require('sharp');
-
-describe('external import capture dates (#1172)', () => {
-  let tmpDir; let db; let app; let mediaRoot;
-
-  /**
-   * A real JPEG carrying DateTimeOriginal.
-   *
-   * IFD2, not IFD0 — DateTimeOriginal lives in the Exif IFD, and exifr does not
-   * see it anywhere else (IFD0 takes plain DateTime, which surfaces as
-   * ModifyDate instead).
-   */
-  const writeJpegWithExif = async (rel, iso) => {
-    const full = path.join(mediaRoot, rel);
-    await fs.promises.mkdir(path.dirname(full), { recursive: true });
-    const d = new Date(iso);
-    const pad = (n) => String(n).padStart(2, '0');
-    const exifDate = `${d.getUTCFullYear()}:${pad(d.getUTCMonth() + 1)}:${pad(d.getUTCDate())} `
-      + `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
-    await sharp({ create: { width: 60, height: 40, channels: 3, background: { r: 10, g: 20, b: 30 } } })
-      .withExif({ IFD2: { DateTimeOriginal: exifDate } })
-      .jpeg()
-      .toFile(full);
-    return full;
-  };
-
-  const writeJpegNoExif = async (rel) => {
-    const full = path.join(mediaRoot, rel);
-    await fs.promises.mkdir(path.dirname(full), { recursive: true });
-    await sharp({ create: { width: 60, height: 40, channels: 3, background: { r: 200, g: 10, b: 10 } } })
-      .jpeg().toFile(full);
-  };
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-capdate-'));
-    mediaRoot = path.join(tmpDir, 'media');
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'db.sqlite');
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-    process.env.EXTERNAL_MEDIA_ROOT = mediaRoot;
-    process.env.JWT_SECRET = process.env.JWT_SECRET || 'capdate-secret';
-
-    jest.resetModules();
-    jest.doMock('../../src/middleware/auth', () => ({
-      adminAuth: (req, _res, next) => { req.admin = { id: 1, username: 'tester', roleName: 'admin' }; next(); },
-    }));
-    jest.doMock('../../src/middleware/permissions', () => ({
-      requirePermission: () => (_req, _res, next) => next(),
-    }));
-    jest.doMock('../../src/middleware/ownership', () => ({
-      requireEventOwnership: (_req, _res, next) => next(),
-    }));
-    jest.doMock('../../src/services/imageProcessor', () => {
-      const actual = jest.requireActual('../../src/services/imageProcessor');
-      return { ...actual, generateThumbnail: jest.fn(async () => 'thumbnails/mock.jpg'), ensureThumbnail: jest.fn() };
-    });
-    jest.doMock('../../src/utils/logger', () => ({
-      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
-    }));
-
-    ({ db } = await require('./helpers/crmDb').bootCrmDb());
-
-    app = express();
-    app.use(express.json());
-    app.use('/api/admin/external-media', require('../../src/routes/adminExternalMedia'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (db) await db.destroy?.();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  async function seedEvent() {
-    await db('photos').del();
-    await db('events').del();
-    await fs.promises.rm(mediaRoot, { recursive: true, force: true });
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-    const [e] = await db('events').insert({
-      slug: `capdate-${Math.random().toString(36).slice(2, 8)}`,
-      event_type: 'wedding', event_name: 'capdate', event_date: '2026-01-01',
-      host_email: 'h@example.com', admin_email: 'a@example.com', password_hash: 'x',
-      share_link: `capdate-${Math.random()}`, expires_at: new Date().toISOString(),
-      source_mode: 'reference',
-    }).returning('id');
-    return typeof e === 'object' ? e.id : e;
-  }
-
-  const runImport = (eventId, external_path) => request(app)
-    .post(`/api/admin/external-media/events/${eventId}/import-external`)
-    .send({ external_path, recursive: true });
-
-  it('records the EXIF capture date on import', async () => {
-    const eventId = await seedEvent();
-    await writeJpegWithExif('trip/a.jpg', '2026-06-01T09:45:03Z');
-
-    await runImport(eventId, 'trip');
-
-    const photo = await db('photos').where({ event_id: eventId }).first();
-    expect(photo.captured_at).toBeTruthy();
-    // NOT asserted as an absolute instant. EXIF carries a naive wall-clock
-    // time and exifr resolves it against the HOST timezone, so the stored UTC
-    // value differs between a CEST developer machine and a UTC runner. What
-    // this fix is about is that the field is populated and orders correctly;
-    // that captured_at is not a true instant is a separate, pre-existing
-    // problem shared with managed uploads (#1172's own footnote).
-    expect(new Date(photo.captured_at).getUTCFullYear()).toBe(2026);
-    expect(new Date(photo.captured_at).getUTCMonth()).toBe(5); // June
-  });
-
-  it('imports a photo with no EXIF date rather than failing it', async () => {
-    // Plenty of sources carry none; that must stay an import, not an error.
-    const eventId = await seedEvent();
-    await writeJpegNoExif('trip/plain.jpg');
-
-    const res = await runImport(eventId, 'trip');
-
-    expect(res.body.imported).toBe(1);
-    const photo = await db('photos').where({ event_id: eventId }).first();
-    expect(photo.captured_at).toBeNull();
-  });
-
-  it('orders a two-batch import by capture time, not by batch', async () => {
-    // The reported shape: the FIRST days of the trip imported second. Sorting
-    // on COALESCE(captured_at, uploaded_at) put them after the last days,
-    // because uploaded_at is the import timestamp.
-    const eventId = await seedEvent();
-    await writeJpegWithExif('late/day12.jpg', '2026-06-12T10:00:00Z');
-    await runImport(eventId, 'late');
-    await writeJpegWithExif('early/day01.jpg', '2026-06-01T10:00:00Z');
-    await runImport(eventId, 'early');
-
-    const rows = await db('photos')
-      .where({ event_id: eventId })
-      .orderByRaw('COALESCE(captured_at, uploaded_at) asc')
-      .select('filename');
-
-    expect(rows.map((r) => r.filename)).toEqual(['day01.jpg', 'day12.jpg']);
-  });
-});

backend/__tests__/integration/externalImportConcurrency.test.js

@@ -1,205 +0,0 @@
-/**
- * Two overlapping external imports insert every file twice (#1162).
- *
- * The route checked for an existing external_relpath and then inserted, with
- * an fs.stat and a `sharp().metadata()` read sitting in between. A reporter
- * double-clicked a slow import of a 6012-file tree and got 8004 rows.
- *
- * Both halves of the fix are driven here through the real route:
- *
- *   - the in-flight guard, which turns the second click into a 409 instead of
- *     a second full walk of the tree;
- *   - convergence when the guard cannot help (another replica, another
- *     process), which is the unique index from migration 186 firing and the
- *     loop counting a skip rather than dying or duplicating.
- *
- * The second is exercised by inserting a competing row from inside the mocked
- * `sharp().metadata()` call — literally inside the window the bug lived in.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const express = require('express');
-const request = require('supertest');
-
-describe('concurrent external imports (#1162)', () => {
-  let tmpDir; let db; let app; let mediaRoot;
-  // When set, the mocked sharp metadata read inserts this row first — the
-  // other run winning the race between our SELECT and our INSERT.
-  let stealDuringMetadata = null;
-  let thumbnailDelayMs = 0;
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-extdup-'));
-    mediaRoot = path.join(tmpDir, 'media');
-    await fs.promises.mkdir(path.join(mediaRoot, 'nas', 'individual'), { recursive: true });
-    for (const name of ['a.jpg', 'b.jpg', 'c.jpg']) {
-      await fs.promises.writeFile(path.join(mediaRoot, 'nas', 'individual', name), 'not-a-real-jpeg');
-    }
-
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'db.sqlite');
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-    process.env.EXTERNAL_MEDIA_ROOT = mediaRoot;
-    process.env.JWT_SECRET = process.env.JWT_SECRET || 'extdup-secret';
-
-    jest.resetModules();
-
-    jest.doMock('../../src/middleware/auth', () => ({
-      adminAuth: (req, _res, next) => { req.admin = { id: 1, username: 'tester', roleName: 'admin' }; next(); },
-    }));
-    jest.doMock('../../src/middleware/permissions', () => ({
-      requirePermission: () => (_req, _res, next) => next(),
-    }));
-    jest.doMock('../../src/middleware/ownership', () => ({
-      requireEventOwnership: (_req, _res, next) => next(),
-    }));
-
-    // The window. In production this is a real decode of a NAS-hosted file —
-    // hundreds of milliseconds during which the row we just proved absent can
-    // appear. Standing in for the other run here makes that deterministic.
-    jest.doMock('sharp', () => () => ({
-      metadata: async () => {
-        if (stealDuringMetadata) {
-          const { db: liveDb } = require('../../src/database/db');
-          await liveDb('photos').insert(stealDuringMetadata);
-          stealDuringMetadata = null;
-        }
-        return { width: 100, height: 200 };
-      },
-    }));
-
-    jest.doMock('../../src/services/imageProcessor', () => ({
-      generateThumbnail: jest.fn(async () => {
-        if (thumbnailDelayMs) await new Promise((r) => setTimeout(r, thumbnailDelayMs));
-        return 'thumbnails/mock.jpg';
-      }),
-      ensureThumbnail: jest.fn(),
-    }));
-
-    jest.doMock('../../src/utils/logger', () => ({
-      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
-    }));
-
-    ({ db } = await require('./helpers/crmDb').bootCrmDb());
-
-    app = express();
-    app.use(express.json());
-    app.use('/api/admin/external-media', require('../../src/routes/adminExternalMedia'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (db) await db.destroy?.();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  async function seedEvent() {
-    await db('photos').del();
-    await db('events').del();
-    stealDuringMetadata = null;
-    thumbnailDelayMs = 0;
-    const [e] = await db('events').insert({
-      slug: `extdup-${Math.random().toString(36).slice(2, 8)}`,
-      event_type: 'wedding',
-      event_name: 'extdup',
-      event_date: '2026-01-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: `extdup-${Math.random()}`,
-      expires_at: new Date().toISOString(),
-      source_mode: 'reference',
-    }).returning('id');
-    return typeof e === 'object' ? e.id : e;
-  }
-
-  const runImport = (eventId) => request(app)
-    .post(`/api/admin/external-media/events/${eventId}/import-external`)
-    .send({ external_path: 'nas', recursive: true });
-
-  async function relpathCounts(eventId) {
-    const rows = await db('photos').where({ event_id: eventId }).select('external_relpath');
-    const counts = new Map();
-    for (const r of rows) counts.set(r.external_relpath, (counts.get(r.external_relpath) || 0) + 1);
-    return counts;
-  }
-
-  it('rejects a second import while the first is still running', async () => {
-    const eventId = await seedEvent();
-    // Enough to keep the first request inside its loop while the second
-    // arrives — the "slow import looks hung, so I clicked again" case.
-    thumbnailDelayMs = 20;
-
-    const [first, second] = await Promise.all([runImport(eventId), runImport(eventId)]);
-
-    const statuses = [first.status, second.status].sort();
-    expect(statuses).toEqual([200, 409]);
-    const rejected = first.status === 409 ? first : second;
-    expect(rejected.body.error).toMatch(/already running/i);
-  });
-
-  it('leaves exactly one row per file after both runs', async () => {
-    const eventId = await seedEvent();
-    thumbnailDelayMs = 20;
-
-    await Promise.all([runImport(eventId), runImport(eventId)]);
-
-    const counts = await relpathCounts(eventId);
-    expect(counts.size).toBe(3);
-    expect([...counts.values()]).toEqual([1, 1, 1]);
-  });
-
-  it('releases the event once the import finishes, so a re-import still works', async () => {
-    const eventId = await seedEvent();
-
-    expect((await runImport(eventId)).status).toBe(200);
-    // Not 409 — the guard is per run, not a permanent lock on the event.
-    const second = await runImport(eventId);
-    expect(second.status).toBe(200);
-    expect(second.body.imported).toBe(0);
-    expect(second.body.skipped).toBe(3);
-  });
-
-  it('converges when another writer wins the race mid-file', async () => {
-    // The guard is in-process, so it cannot see a second replica. This is what
-    // the unique index is for: the insert bounces, and the file is counted as
-    // skipped rather than duplicated or lost to a 500.
-    const eventId = await seedEvent();
-    stealDuringMetadata = {
-      event_id: eventId,
-      filename: 'a.jpg',
-      path: 'x/a.jpg',
-      type: 'individual',
-      source_origin: 'external',
-      external_relpath: path.join('nas', 'individual', 'a.jpg'),
-    };
-
-    const res = await runImport(eventId);
-
-    expect(res.status).toBe(200);
-    const counts = await relpathCounts(eventId);
-    expect(counts.get(path.join('nas', 'individual', 'a.jpg'))).toBe(1);
-    // Two imported by us, one lost to the other writer and reported honestly.
-    expect(res.body.imported).toBe(2);
-    expect(res.body.skipped).toBe(1);
-  });
-
-  it('does not let one contended file abort the rest of the import', async () => {
-    const eventId = await seedEvent();
-    stealDuringMetadata = {
-      event_id: eventId,
-      filename: 'a.jpg',
-      path: 'x/a.jpg',
-      type: 'individual',
-      source_origin: 'external',
-      external_relpath: path.join('nas', 'individual', 'a.jpg'),
-    };
-
-    await runImport(eventId);
-
-    // All three files present — the contended one via the other writer's row.
-    expect((await relpathCounts(eventId)).size).toBe(3);
-  });
-});

backend/__tests__/integration/externalImportSecondFolder.test.js

@@ -1,175 +0,0 @@
-/**
- * Importing a second folder must not move the photos already in the event (#1163).
- *
- * events.external_path is overwritten by every import, and external_relpath
- * used to be stored relative to it — so a second import silently rebased every
- * existing row onto the new folder. The reporter had 7547 of 8004 originals
- * pointing at files that do not exist, and nothing said so: thumbnails are
- * written to local storage during the import while the base path is still
- * correct, so the grid carries on rendering.
- *
- * Driven through the real route and the real resolver, against a real
- * directory tree — the failure is entirely about whether a file is where the
- * app looks for it.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const express = require('express');
-const request = require('supertest');
-
-describe('a second external import (#1163)', () => {
-  let tmpDir; let db; let app; let mediaRoot; let resolvePhotoFilePath;
-
-  const touch = async (rel) => {
-    const full = path.join(mediaRoot, rel);
-    await fs.promises.mkdir(path.dirname(full), { recursive: true });
-    await fs.promises.writeFile(full, 'not-a-real-jpeg');
-  };
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-ext2nd-'));
-    mediaRoot = path.join(tmpDir, 'media');
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'db.sqlite');
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-    process.env.EXTERNAL_MEDIA_ROOT = mediaRoot;
-    process.env.JWT_SECRET = process.env.JWT_SECRET || 'ext2nd-secret';
-
-    jest.resetModules();
-
-    jest.doMock('../../src/middleware/auth', () => ({
-      adminAuth: (req, _res, next) => { req.admin = { id: 1, username: 'tester', roleName: 'admin' }; next(); },
-    }));
-    jest.doMock('../../src/middleware/permissions', () => ({
-      requirePermission: () => (_req, _res, next) => next(),
-    }));
-    jest.doMock('../../src/middleware/ownership', () => ({
-      requireEventOwnership: (_req, _res, next) => next(),
-    }));
-    jest.doMock('sharp', () => () => ({ metadata: async () => ({ width: 100, height: 200 }) }));
-    jest.doMock('../../src/services/imageProcessor', () => ({
-      generateThumbnail: jest.fn(async () => 'thumbnails/mock.jpg'),
-      ensureThumbnail: jest.fn(),
-    }));
-    jest.doMock('../../src/utils/logger', () => ({
-      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
-    }));
-
-    ({ db } = await require('./helpers/crmDb').bootCrmDb());
-    ({ resolvePhotoFilePath } = require('../../src/services/photoResolver'));
-
-    app = express();
-    app.use(express.json());
-    app.use('/api/admin/external-media', require('../../src/routes/adminExternalMedia'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (db) await db.destroy?.();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  async function seedEvent() {
-    await db('photos').del();
-    await db('events').del();
-    await fs.promises.rm(mediaRoot, { recursive: true, force: true });
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-    const [e] = await db('events').insert({
-      slug: `ext2nd-${Math.random().toString(36).slice(2, 8)}`,
-      event_type: 'wedding',
-      event_name: 'ext2nd',
-      event_date: '2026-01-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: `ext2nd-${Math.random()}`,
-      expires_at: new Date().toISOString(),
-      source_mode: 'reference',
-    }).returning('id');
-    return typeof e === 'object' ? e.id : e;
-  }
-
-  const runImport = (eventId, external_path) => request(app)
-    .post(`/api/admin/external-media/events/${eventId}/import-external`)
-    .send({ external_path, recursive: true });
-
-  /** Where the app would go looking for this photo's original, right now. */
-  async function resolved(eventId, filename) {
-    const event = await db('events').where({ id: eventId }).first();
-    const photo = await db('photos').where({ event_id: eventId, filename }).first();
-    return resolvePhotoFilePath(event, photo);
-  }
-
-  it('stores paths relative to the media root, not to the imported folder', async () => {
-    const eventId = await seedEvent();
-    await touch('Trip/Leknes/old.jpg');
-
-    await runImport(eventId, 'Trip');
-
-    const photo = await db('photos').where({ event_id: eventId }).first();
-    expect(photo.external_relpath).toBe(path.join('Trip', 'Leknes', 'old.jpg'));
-  });
-
-  it('leaves the first folder’s originals reachable after a second import', async () => {
-    const eventId = await seedEvent();
-    await touch('Trip/Leknes/old.jpg');
-    await touch('Trip/Sub/new.jpg');
-
-    await runImport(eventId, 'Trip');
-    const before = await resolved(eventId, 'old.jpg');
-    await runImport(eventId, 'Trip/Sub');
-    const after = await resolved(eventId, 'old.jpg');
-
-    // The regression: `after` used to be <root>/Trip/Sub/Leknes/old.jpg.
-    expect(after).toBe(before);
-    expect(fs.existsSync(after)).toBe(true);
-  });
-
-  it('every original in the event is still on disk afterwards', async () => {
-    const eventId = await seedEvent();
-    await touch('Trip/Leknes/a.jpg');
-    await touch('Trip/Leknes/b.jpg');
-    await touch('Trip/Sub/c.jpg');
-
-    await runImport(eventId, 'Trip');
-    await runImport(eventId, 'Trip/Sub');
-
-    const event = await db('events').where({ id: eventId }).first();
-    const photos = await db('photos').where({ event_id: eventId });
-    expect(photos).toHaveLength(3);
-    for (const photo of photos) {
-      expect(fs.existsSync(resolvePhotoFilePath(event, photo))).toBe(true);
-    }
-  });
-
-  it('does not re-insert a file the first import already took', async () => {
-    // The dedupe check compares stored paths, so it has to be comparing the
-    // same shape the insert writes.
-    const eventId = await seedEvent();
-    await touch('Trip/Sub/c.jpg');
-
-    await runImport(eventId, 'Trip');
-    const second = await runImport(eventId, 'Trip/Sub');
-
-    expect(second.body.imported).toBe(0);
-    expect(second.body.skipped).toBe(1);
-    expect(await db('photos').where({ event_id: eventId }).count('* as c').first()).toEqual({ c: 1 });
-  });
-
-  it('resolves a subfolder that repeats its parent’s name', async () => {
-    // The old resolver stripped the relpath's first segment when it matched the
-    // base path's last one, which broke exactly this layout.
-    const eventId = await seedEvent();
-    await touch('Trip/Trip/x.jpg');
-
-    await runImport(eventId, 'Trip');
-
-    const event = await db('events').where({ id: eventId }).first();
-    const photo = await db('photos').where({ event_id: eventId }).first();
-    expect(resolvePhotoFilePath(event, photo)).toBe(path.join(mediaRoot, 'Trip', 'Trip', 'x.jpg'));
-  });
-});

backend/__tests__/integration/externalRelpathFoldPg.test.js

@@ -1,121 +0,0 @@
-/**
- * PostgreSQL integration test for the external-path fold (#1163).
- *
- * Gated the same way as picpeakRestorePg: runs only when PICPEAK_PG_TEST_URL
- * points at a throwaway Postgres DB, e.g.
- *   PICPEAK_PG_TEST_URL="postgres://picpeak:picpeak_secure_pass_2024@127.0.0.1:7102/picpeak_fold_test" \
- *     npx jest __tests__/integration/externalRelpathFoldPg.test.js
- *
- * This exists because of a defect SQLite could not have caught. The two-pass
- * rewrite parks each row on a temporary value, and that value was first written
- * with a leading NUL. SQLite stores NUL in TEXT without complaint; Postgres
- * rejects it outright ("invalid byte sequence for encoding UTF8"), so migration
- * 187 would have rolled back on exactly the installs needing the repair — and
- * only on the engine most of them run.
- *
- * The staging value is therefore an engine-level contract, not an
- * implementation detail, and it is pinned here on the engine that constrains it.
- */
-
-const knex = require('knex');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const PG_URL = process.env.PICPEAK_PG_TEST_URL;
-const maybe = PG_URL ? describe : describe.skip;
-
-maybe('external relpath fold on Postgres', () => {
-  let pgDb; let mediaRoot; let fold;
-
-  const touch = async (rel, bytes) => {
-    const full = path.join(mediaRoot, rel);
-    await fs.promises.mkdir(path.dirname(full), { recursive: true });
-    await fs.promises.writeFile(full, Buffer.alloc(bytes));
-    return bytes;
-  };
-
-  beforeAll(async () => {
-    mediaRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-foldpg-'));
-    process.env.EXTERNAL_MEDIA_ROOT = mediaRoot;
-    jest.resetModules();
-    ({ foldExternalRelpaths: fold } = require('../../src/services/externalRelpathFold'));
-
-    pgDb = knex({ client: 'pg', connection: PG_URL });
-  }, 60000);
-
-  afterAll(async () => {
-    if (pgDb) await pgDb.destroy();
-    await fs.promises.rm(mediaRoot, { recursive: true, force: true }).catch(() => {});
-    delete process.env.EXTERNAL_MEDIA_ROOT;
-  });
-
-  beforeEach(async () => {
-    await pgDb.raw('DROP TABLE IF EXISTS photos, events, app_settings CASCADE');
-    await pgDb.schema.createTable('events', (t) => {
-      t.increments('id');
-      t.text('external_path');
-    });
-    await pgDb.schema.createTable('photos', (t) => {
-      t.increments('id');
-      t.integer('event_id');
-      t.text('external_relpath');
-      t.bigInteger('size_bytes');
-      t.string('source_origin').defaultTo('managed');
-    });
-    await pgDb.schema.createTable('app_settings', (t) => {
-      t.increments('id');
-      t.string('setting_key');
-      t.text('setting_value');
-      t.string('setting_type');
-      t.string('updated_at');
-    });
-    await fs.promises.rm(mediaRoot, { recursive: true, force: true });
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-  });
-
-  const relpaths = async () =>
-    (await pgDb('photos').orderBy('id').select('external_relpath')).map((r) => r.external_relpath);
-
-  it('completes the two-pass repair that a NUL staging value would abort', async () => {
-    // The exact shape that forces staging: `photo.jpg` repairs up to
-    // `Trip/photo.jpg`, while the row already holding `Trip/photo.jpg` folds
-    // deeper. Every final value is distinct, but a final value equals another
-    // row's current one, so the rewrite has to park first.
-    const a = await touch('Trip/photo.jpg', 11);
-    const b = await touch('Trip/Sub/Trip/photo.jpg', 22);
-    await pgDb('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await pgDb('photos').insert([
-      { event_id: 1, external_relpath: 'photo.jpg', size_bytes: a, source_origin: 'external' },
-      { event_id: 1, external_relpath: 'Trip/photo.jpg', size_bytes: b, source_origin: 'external' },
-    ]);
-
-    await fold(pgDb);
-
-    expect(await relpaths()).toEqual(['Trip/photo.jpg', 'Trip/Sub/Trip/photo.jpg']);
-  });
-
-  it('leaves no staging value behind', async () => {
-    await touch('Trip/a.jpg', 8);
-    await pgDb('events').insert({ id: 1, external_path: 'Trip' });
-    await pgDb('photos').insert({ event_id: 1, external_relpath: 'a.jpg', size_bytes: 8, source_origin: 'external' });
-
-    await fold(pgDb);
-
-    const rows = await relpaths();
-    expect(rows).toEqual(['Trip/a.jpg']);
-    expect(rows.some((r) => r.includes('staging'))).toBe(false);
-  });
-
-  it('folds and marks in one transaction', async () => {
-    await touch('Trip/a.jpg', 8);
-    await pgDb('events').insert({ id: 1, external_path: 'Trip' });
-    await pgDb('photos').insert({ event_id: 1, external_relpath: 'a.jpg', size_bytes: 8, source_origin: 'external' });
-
-    await fold(pgDb);
-    // Second run is a no-op: the marker committed with the rewrites.
-    await fold(pgDb);
-
-    expect(await relpaths()).toEqual(['Trip/a.jpg']);
-  });
-});

backend/__tests__/integration/galleryFilterFeedbackVisibility.test.js

@@ -1,216 +0,0 @@
-/**
- * Guest filters must respect show_feedback_to_guests (#1044 follow-up).
- *
- * Every filter token on /photos is an OR of two halves: what THIS viewer
- * marked, and what ANYONE marked. The response fields built from the second
- * half — like_count, comment_count — are all gated on
- * show_feedback_to_guests. The FILTER was not.
- *
- * So with the setting off, the numbers were hidden but `?filter=liked` still
- * returned exactly the photos other people had liked: the same information as
- * a set instead of a count, one token at a time. These tests pin the gate on
- * every token, and pin that the viewer's own half is never gated — filtering
- * by what you yourself marked is yours to do regardless.
- */
-
-const request = require('supertest');
-const express = require('express');
-const cookieParser = require('cookie-parser');
-const jwt = require('jsonwebtoken');
-
-const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
-
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'filter-visibility-secret';
-
-const SLUG = 'filter-visibility-event';
-const ME = 'guest-me-identifier';
-const SOMEONE_ELSE = 'guest-other-identifier';
-
-describe('guest filters and show_feedback_to_guests (#1044)', () => {
-  let db;
-  let cleanup;
-  let app;
-  let eventId;
-  let mine;
-  let theirs;
-  let myGuestRowId;
-
-  const galleryToken = () => jwt.sign(
-    { eventId, eventSlug: SLUG, type: 'gallery' },
-    process.env.JWT_SECRET,
-    { expiresIn: '1h', issuer: 'picpeak-auth' }
-  );
-
-  const setVisibility = (visible) => db('event_feedback_settings')
-    .where({ event_id: eventId })
-    .update({ show_feedback_to_guests: visible });
-
-  // A real verified guest, which is how the viewer's own feedback is actually
-  // identified — NOT the `guest_id` query parameter the frontend invents.
-  const guestToken = () => jwt.sign(
-    { type: 'guest', guestId: myGuestRowId, eventId },
-    process.env.JWT_SECRET,
-    { expiresIn: '1h', issuer: 'picpeak-auth' }
-  );
-
-  const filter = async (token, { as = 'me', claimGuestId } = {}) => {
-    const req = request(app)
-      .get(`/api/gallery/${SLUG}/photos`)
-      .query({ filter: token, ...(claimGuestId ? { guest_id: claimGuestId } : {}) })
-      .set('Authorization', `Bearer ${galleryToken()}`);
-    if (as === 'me') req.set('x-guest-token', guestToken());
-    const res = await req;
-    expect(res.status).toBe(200);
-    const photos = Array.isArray(res.body) ? res.body : res.body.photos;
-    return (photos || []).map((p) => p.id).sort((a, b) => a - b);
-  };
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-
-    const inserted = await db('events').insert({
-      slug: SLUG,
-      event_type: 'wedding',
-      event_name: 'Filter Visibility',
-      event_date: '2026-08-01',
-      host_email: 'host@example.com',
-      admin_email: 'admin@example.com',
-      password_hash: 'x',
-      share_link: `/gallery/${SLUG}/share`,
-      share_token: 'filter-visibility-share',
-      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
-      is_active: 1,
-      is_archived: 0,
-      is_draft: 0,
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    eventId = inserted[0]?.id ?? inserted[0];
-
-    const addPhoto = async (name) => {
-      const p = await db('photos').insert({
-        event_id: eventId,
-        filename: name,
-        path: `events/filter/${name}`,
-        type: 'individual',
-        uploaded_at: new Date().toISOString(),
-      }).returning('id');
-      return p[0]?.id ?? p[0];
-    };
-    mine = await addPhoto('mine.jpg');
-    theirs = await addPhoto('theirs.jpg');
-
-    await db('event_feedback_settings').insert({
-      event_id: eventId,
-      feedback_enabled: true,
-      allow_likes: true,
-      allow_comments: true,
-      allow_ratings: true,
-      allow_favorites: true,
-      moderate_comments: false,
-      show_feedback_to_guests: true,
-    });
-
-    const guestRow = await db('gallery_guests').insert({
-      event_id: eventId,
-      name: 'Me',
-      identifier: ME,
-      created_at: new Date().toISOString(),
-      last_seen_at: new Date().toISOString(),
-      is_deleted: false,
-    }).returning('id');
-    myGuestRowId = guestRow[0]?.id ?? guestRow[0];
-
-    const feedback = (photoId, who, type, extra = {}) => db('photo_feedback').insert({
-      photo_id: photoId,
-      event_id: eventId,
-      guest_identifier: who,
-      // Submission links to the per-person guest row when one is present, and
-      // that is the column the viewer's own half resolves through.
-      guest_id: who === ME ? myGuestRowId : null,
-      feedback_type: type,
-      is_approved: true,
-      is_hidden: false,
-      created_at: new Date().toISOString(),
-      ...extra,
-    });
-
-    // Everything on `theirs` belongs to somebody else; `mine` is this viewer's.
-    await feedback(mine, ME, 'like');
-    await feedback(theirs, SOMEONE_ELSE, 'like');
-    await feedback(theirs, SOMEONE_ELSE, 'favorite');
-    await feedback(theirs, SOMEONE_ELSE, 'comment', { comment_text: 'lovely' });
-    await feedback(theirs, SOMEONE_ELSE, 'rating', { rating: 5 });
-
-    // The denormalized counters the aggregate half of the filter reads.
-    await db('photos').where('id', theirs).update({
-      like_count: 1, favorite_count: 1, comment_count: 1, average_rating: 5,
-    });
-    await db('photos').where('id', mine).update({ like_count: 1 });
-
-    app = express();
-    app.use(express.json());
-    app.use(cookieParser());
-    app.use('/api/gallery', require('../../src/routes/gallery'));
-  }, 120000);
-
-  afterAll(async () => {
-    if (cleanup) await cleanup();
-  });
-
-  describe('with feedback visible to guests', () => {
-    beforeAll(() => setVisibility(true));
-
-    it('shows other people\'s marks through every token, as before', async () => {
-      expect(await filter('liked')).toEqual([mine, theirs].sort((a, b) => a - b));
-      expect(await filter('favorited')).toEqual([theirs]);
-      expect(await filter('rated')).toEqual([theirs]);
-      expect(await filter('commented')).toEqual([theirs]);
-    });
-  });
-
-  describe('with feedback hidden from guests', () => {
-    beforeAll(() => setVisibility(false));
-
-    it('stops every token from selecting on other people\'s marks', async () => {
-      // `theirs` is the photo only other guests marked. It must not come back
-      // through any token — a filter that selects on hidden feedback reports
-      // that feedback just as surely as a count would.
-      expect(await filter('favorited')).toEqual([]);
-      expect(await filter('rated')).toEqual([]);
-      expect(await filter('commented')).toEqual([]);
-    });
-
-    it('still filters by what the viewer marked themselves', async () => {
-      // The viewer's own half is never gated: this is their own action, and
-      // hiding it would break "show me the ones I liked" for no privacy gain.
-      expect(await filter('liked')).toEqual([mine]);
-    });
-
-    it('drops the viewer\'s own feedback once an admin hides it', async () => {
-      // Moderation has to reach the filter too. getPhotoFeedback excludes
-      // hidden rows for the guest's OWN feedback, so a photo matching here
-      // would come back with nothing visible on it to explain why.
-      await db('photo_feedback')
-        .where({ photo_id: mine, guest_id: myGuestRowId, feedback_type: 'like' })
-        .update({ is_hidden: true });
-
-      expect(await filter('liked')).toEqual([]);
-
-      await db('photo_feedback')
-        .where({ photo_id: mine, guest_id: myGuestRowId, feedback_type: 'like' })
-        .update({ is_hidden: false });
-      expect(await filter('liked')).toEqual([mine]);
-    });
-
-    it('ignores a guest_id supplied by the caller', async () => {
-      // The own-half is resolved from the request identity. If it honoured the
-      // query string instead, anyone holding another guest's identifier could
-      // read that guest's hidden memberships one token at a time — straight
-      // back through the gate this file exists to pin.
-      expect(await filter('favorited', { claimGuestId: SOMEONE_ELSE })).toEqual([]);
-      // And an anonymous caller claiming to be me gets nothing of mine.
-      expect(await filter('liked', { as: 'anon', claimGuestId: ME })).toEqual([]);
-    });
-  });
-});

backend/__tests__/integration/galleryPasswordSanitize.test.js

@@ -0,0 +1,121 @@
+/**
+ * Gallery password invisible-Unicode fallback (#654).
+ *
+ * Passwords relayed through chat apps (Instagram DMs especially) pick up
+ * invisible characters on copy-paste — zero-width space/joiners, word
+ * joiner, BOM, soft hyphen — which fail the byte-exact bcrypt compare and
+ * surface as "incorrect password" for a correct password. The verify route
+ * retries the compare with those characters stripped, in the SAME request,
+ * so the fallback costs no reCAPTCHA token and no failed-attempt quota.
+ *
+ * Pins the contract:
+ *  - exact submitted bytes always win first, so stored passwords that
+ *    legitimately contain these characters (e.g. ZWJ emoji sequences)
+ *    keep working
+ *  - paste artifacts (mid-string ZWSP, leading BOM, trailing space) are
+ *    rescued by the sanitized fallback compare
+ *  - the fallback never invents a match (missing ZWJ still 401s), and a
+ *    rescued login records no failed attempt
+ */
+
+const request = require('supertest');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const bcrypt = require('bcrypt');
+
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'sanitize-test-secret';
+
+const PLAIN_SLUG = 'sanitize-plain-event';
+const ZWJ_SLUG = 'sanitize-zwj-event';
+const PLAIN_PASSWORD = 'wedding2026';
+// Stored password legitimately containing a ZWJ emoji sequence.
+const ZWJ_PASSWORD = 'Family\u{1F468}\u200D\u{1F469}Aa1';
+
+describe('gallery/verify invisible-Unicode fallback (#654)', () => {
+  let db;
+  let cleanup;
+  let app;
+
+  const makeEvent = async (slug, password) => {
+    const inserted = await db('events').insert({
+      slug,
+      event_type: 'wedding',
+      event_name: `Sanitize ${slug}`,
+      event_date: '2026-08-01',
+      host_email: 'host@example.com',
+      admin_email: 'admin@example.com',
+      password_hash: await bcrypt.hash(password, 4),
+      share_link: `/gallery/${slug}/share`,
+      share_token: `${slug}-share`,
+      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+      is_active: 1,
+      is_archived: 0,
+      is_draft: 0,
+      created_at: new Date().toISOString(),
+    }).returning('id');
+    return inserted[0]?.id ?? inserted[0];
+  };
+  let plainEventId;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    await seedMinimal(db);
+    plainEventId = await makeEvent(PLAIN_SLUG, PLAIN_PASSWORD);
+    await makeEvent(ZWJ_SLUG, ZWJ_PASSWORD);
+
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/auth', require('../../src/routes/auth'));
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  const verify = (slug, password) =>
+    request(app).post('/api/auth/gallery/verify').send({ slug, password });
+
+  it('accepts the exact password', async () => {
+    const res = await verify(PLAIN_SLUG, PLAIN_PASSWORD);
+    expect(res.status).toBe(200);
+    expect(res.body.token).toBeTruthy();
+  });
+
+  it('rescues a mid-string zero-width space from chat-app copy-paste', async () => {
+    const res = await verify(PLAIN_SLUG, 'wedding\u200B2026');
+    expect(res.status).toBe(200);
+    expect(res.body.token).toBeTruthy();
+  });
+
+  it('rescues leading BOM + trailing space paste artifacts', async () => {
+    const res = await verify(PLAIN_SLUG, `\uFEFF${PLAIN_PASSWORD} `);
+    expect(res.status).toBe(200);
+    expect(res.body.token).toBeTruthy();
+  });
+
+  it('records no login_fail for a rescued login (single-request fallback)', async () => {
+    await verify(PLAIN_SLUG, 'wedding\u200B2026').expect(200);
+    const failed = await db('access_logs')
+      .where({ event_id: plainEventId, action: 'login_fail' });
+    expect(failed).toHaveLength(0);
+  });
+
+  it('still accepts a stored password that legitimately contains a ZWJ', async () => {
+    const res = await verify(ZWJ_SLUG, ZWJ_PASSWORD);
+    expect(res.status).toBe(200);
+    expect(res.body.token).toBeTruthy();
+  });
+
+  it('does not invent a match when the ZWJ is missing from the input', async () => {
+    const res = await verify(ZWJ_SLUG, 'Family\u{1F468}\u{1F469}Aa1');
+    expect(res.status).toBe(401);
+  });
+
+  it('rejects a plain wrong password', async () => {
+    const res = await verify(PLAIN_SLUG, 'not-the-password');
+    expect(res.status).toBe(401);
+  });
+});

backend/__tests__/integration/helpers/mockOidcProvider.js

@@ -0,0 +1,167 @@
+/**
+ * Minimal in-process OIDC provider for integration tests (#798).
+ *
+ * Serves just enough of the spec for openid-client's full validation to
+ * pass: discovery, JWKS (RS256), authorization endpoint (immediate redirect,
+ * no login UI), and token endpoint (authorization_code + PKCE). Claims for
+ * the next login are scripted per test via `setNextUser()`.
+ *
+ * Runs on an ephemeral localhost port over plain http — the service allows
+ * that in NODE_ENV=test only.
+ */
+
+const http = require('http');
+const crypto = require('crypto');
+const { URL } = require('url');
+
+function b64url(input) {
+  return Buffer.from(input).toString('base64url');
+}
+
+class MockOidcProvider {
+  constructor() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });
+    this.privateKey = privateKey;
+    this.publicJwk = publicKey.export({ format: 'jwk' });
+    this.publicJwk.kid = 'test-key-1';
+    this.publicJwk.alg = 'RS256';
+    this.publicJwk.use = 'sig';
+
+    this.clientId = 'picpeak-test';
+    this.clientSecret = 'test-client-secret';
+    this.codes = new Map(); // code -> { nonce, redirectUri, codeChallenge, user }
+    this.nextUser = { sub: 'user-1', email: 'sso@example.com', email_verified: true };
+    // Test hooks:
+    this.tamperNonce = false; // sign the ID token with a WRONG nonce
+    this.emailViaUserinfoOnly = false; // omit email from the ID token; serve it on /userinfo
+    this.advertiseEndSession = true; // include end_session_endpoint in discovery (#798 phase 3)
+    this.accessTokens = new Map(); // access_token -> user (for /userinfo)
+    this.server = null;
+    this.issuer = null;
+  }
+
+  setNextUser(user) {
+    this.nextUser = user;
+  }
+
+  signIdToken({ sub, nonce, extraClaims = {} }) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: 'RS256', kid: this.publicJwk.kid, typ: 'JWT' };
+    const payload = {
+      iss: this.issuer,
+      aud: this.clientId,
+      sub,
+      iat: now,
+      exp: now + 300,
+      nonce,
+      ...extraClaims,
+    };
+    const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+    const signature = crypto.sign('RSA-SHA256', Buffer.from(signingInput), this.privateKey);
+    return `${signingInput}.${signature.toString('base64url')}`;
+  }
+
+  async start() {
+    this.server = http.createServer((req, res) => this.handle(req, res));
+    await new Promise((resolve) => this.server.listen(0, '127.0.0.1', resolve));
+    this.issuer = `http://127.0.0.1:${this.server.address().port}`;
+    return this.issuer;
+  }
+
+  async stop() {
+    if (this.server) await new Promise((resolve) => this.server.close(resolve));
+  }
+
+  handle(req, res) {
+    const url = new URL(req.url, this.issuer);
+    const json = (status, body) => {
+      res.writeHead(status, { 'content-type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+
+    if (url.pathname === '/.well-known/openid-configuration') {
+      return json(200, {
+        issuer: this.issuer,
+        authorization_endpoint: `${this.issuer}/authorize`,
+        token_endpoint: `${this.issuer}/token`,
+        userinfo_endpoint: `${this.issuer}/userinfo`,
+        jwks_uri: `${this.issuer}/jwks`,
+        ...(this.advertiseEndSession ? { end_session_endpoint: `${this.issuer}/logout` } : {}),
+        response_types_supported: ['code'],
+        subject_types_supported: ['public'],
+        id_token_signing_alg_values_supported: ['RS256'],
+        code_challenge_methods_supported: ['S256'],
+        token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post'],
+      });
+    }
+
+    if (url.pathname === '/jwks') {
+      return json(200, { keys: [this.publicJwk] });
+    }
+
+    if (url.pathname === '/authorize') {
+      // "Log in" instantly: mint a code bound to this request's params and
+      // bounce back to the redirect_uri like a real IdP would.
+      const code = crypto.randomBytes(16).toString('base64url');
+      this.codes.set(code, {
+        nonce: url.searchParams.get('nonce'),
+        redirectUri: url.searchParams.get('redirect_uri'),
+        codeChallenge: url.searchParams.get('code_challenge'),
+        user: this.nextUser,
+      });
+      const back = new URL(url.searchParams.get('redirect_uri'));
+      back.searchParams.set('code', code);
+      back.searchParams.set('state', url.searchParams.get('state'));
+      res.writeHead(302, { location: back.href });
+      return res.end();
+    }
+
+    if (url.pathname === '/token' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (c) => { body += c; });
+      req.on('end', () => {
+        const params = new URLSearchParams(body);
+        const stored = this.codes.get(params.get('code'));
+        if (!stored) return json(400, { error: 'invalid_grant' });
+        this.codes.delete(params.get('code'));
+
+        // PKCE check — S256(code_verifier) must match the challenge.
+        const verifier = params.get('code_verifier') || '';
+        const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+        if (challenge !== stored.codeChallenge) {
+          return json(400, { error: 'invalid_grant', error_description: 'PKCE verification failed' });
+        }
+
+        const { sub, ...extraClaims } = stored.user;
+        // Spec-compliant providers may keep profile/email claims OFF the ID
+        // token and serve them from /userinfo only — this hook simulates that.
+        const idTokenClaims = this.emailViaUserinfoOnly ? {} : extraClaims;
+        const idToken = this.signIdToken({
+          sub,
+          nonce: this.tamperNonce ? 'tampered-nonce' : stored.nonce,
+          extraClaims: idTokenClaims,
+        });
+        const accessToken = crypto.randomBytes(16).toString('base64url');
+        this.accessTokens.set(accessToken, stored.user);
+        return json(200, {
+          access_token: accessToken,
+          token_type: 'Bearer',
+          expires_in: 300,
+          id_token: idToken,
+        });
+      });
+      return undefined;
+    }
+
+    if (url.pathname === '/userinfo') {
+      const auth = req.headers.authorization || '';
+      const user = this.accessTokens.get(auth.replace(/^Bearer\s+/i, ''));
+      if (!user) return json(401, { error: 'invalid_token' });
+      return json(200, { ...user });
+    }
+
+    return json(404, { error: 'not_found' });
+  }
+}
+
+module.exports = { MockOidcProvider };

backend/__tests__/integration/hiddenOwnFeedback.test.js

@@ -1,245 +0,0 @@
-/**
- * Hidden feedback, seen from the guest who left it (#1150).
- *
- * Everything in the system treats a hidden row as absent: getPhotoFeedback
- * drops it even for the guest's own feedback, the /photos filters drop it, and
- * updatePhotoFeedbackStats does not count it. One place disagreed — the
- * per-viewer `is_liked` heart — so a like the photographer had hidden still
- * showed as liked on a photo whose like_count was zero. (The `my_color_label`
- * badge has the same shape on main; colour labels are not on this branch.)
- *
- * Making those two agree exposes the second half: the duplicate check that
- * powers like/favorite toggling did NOT skip hidden rows, so the now-empty
- * heart, when clicked, found the hidden row and toggled it OFF. The click
- * appeared to do nothing and it took two more to get back to a filled heart.
- *
- * Hiding a non-comment is deliberate, not an accident of the raw route: #839
- * and #1044 both ship it, with tests asserting that a hidden reaction or
- * colour label stops counting. So the fix is to make hidden mean absent
- * consistently — not to stop admins hiding these.
- */
-
-const request = require('supertest');
-const express = require('express');
-const cookieParser = require('cookie-parser');
-const jwt = require('jsonwebtoken');
-
-const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
-
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'hidden-feedback-secret';
-
-const SLUG = 'hidden-own-feedback';
-const ME = 'guest-me-identifier';
-
-describe('a guest\'s own hidden feedback (#1150)', () => {
-  let db; let cleanup; let app; let feedbackService;
-  let eventId; let photoId; let myGuestRowId;
-
-  const galleryToken = () => jwt.sign(
-    { eventId, eventSlug: SLUG, type: 'gallery' },
-    process.env.JWT_SECRET,
-    { expiresIn: '1h', issuer: 'picpeak-auth' }
-  );
-  const guestToken = () => jwt.sign(
-    { type: 'guest', guestId: myGuestRowId, eventId },
-    process.env.JWT_SECRET,
-    { expiresIn: '1h', issuer: 'picpeak-auth' }
-  );
-
-  const getPhoto = async () => {
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/photos`)
-      .set('Authorization', `Bearer ${galleryToken()}`)
-      .set('x-guest-token', guestToken());
-    expect(res.status).toBe(200);
-    const photos = Array.isArray(res.body) ? res.body : res.body.photos;
-    return (photos || []).find((p) => p.id === photoId);
-  };
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-    feedbackService = require('../../src/services/feedbackService');
-
-    const [ev] = await db('events').insert({
-      slug: SLUG,
-      event_type: 'wedding',
-      event_name: 'Hidden Own Feedback',
-      event_date: '2026-08-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: `/gallery/${SLUG}/share`,
-      share_token: 'hidden-own-share',
-      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
-      is_active: 1, is_archived: 0, is_draft: 0,
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    eventId = typeof ev === 'object' ? ev.id : ev;
-
-    const [p] = await db('photos').insert({
-      event_id: eventId, filename: 'shot.jpg', path: 'events/hidden/shot.jpg',
-      type: 'individual', uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    photoId = typeof p === 'object' ? p.id : p;
-
-    const [g] = await db('gallery_guests').insert({
-      event_id: eventId, name: 'Me', identifier: ME,
-      created_at: new Date().toISOString(), last_seen_at: new Date().toISOString(),
-      is_deleted: false,
-    }).returning('id');
-    myGuestRowId = typeof g === 'object' ? g.id : g;
-
-    await db('event_feedback_settings').insert({
-      event_id: eventId, feedback_enabled: true, allow_likes: true,
-      moderate_comments: false,
-      show_feedback_to_guests: true,
-    });
-
-    app = express();
-    app.use(express.json());
-    app.use(cookieParser());
-    app.use('/api/gallery', require('../../src/routes/gallery'));
-    app.use('/api/gallery', require('../../src/routes/galleryFeedback'));
-  }, 180000);
-
-  afterAll(async () => { if (cleanup) await cleanup(); });
-
-  const like = () => db('photo_feedback').insert({
-    photo_id: photoId, event_id: eventId, guest_identifier: ME,
-    guest_id: myGuestRowId, feedback_type: 'like',
-    is_approved: true, is_hidden: false, created_at: new Date().toISOString(),
-  });
-
-  beforeEach(async () => {
-    await db('photo_feedback').where({ photo_id: photoId }).del();
-    await db('photos').where('id', photoId).update({ like_count: 0 });
-  });
-
-  describe('the read surfaces agree with each other', () => {
-    it('un-fills the heart once the like is hidden', async () => {
-      await like();
-      await feedbackService.updatePhotoFeedbackStats(photoId);
-      expect((await getPhoto()).is_liked).toBe(true);
-
-      await db('photo_feedback')
-        .where({ photo_id: photoId, feedback_type: 'like' })
-        .update({ is_hidden: true });
-      await feedbackService.updatePhotoFeedbackStats(photoId);
-
-      const photo = await getPhoto();
-      // like_count already ignored hidden rows, so the heart was the only
-      // thing still claiming this photo was liked.
-      expect(photo.like_count).toBe(0);
-      expect(photo.is_liked).toBe(false);
-    });
-
-  });
-
-  describe('and every other surface agrees', () => {
-    it('keeps a hidden like out of /my-feedback', async () => {
-      await like();
-      await db('photo_feedback')
-        .where({ photo_id: photoId, feedback_type: 'like' })
-        .update({ is_hidden: true });
-
-      const res = await request(app)
-        .get(`/api/gallery/${SLUG}/my-feedback`)
-        .set('Authorization', `Bearer ${galleryToken()}`)
-        .set('x-guest-token', guestToken());
-      expect(res.status).toBe(200);
-
-      // In guest identity mode the Liked/Favorited/Rated chips and their
-      // filters are built from THIS array, not from is_liked — so a hidden
-      // like left an empty heart while the chip still counted it.
-      expect(res.body.filter((f) => f.feedback_type === 'like')).toHaveLength(0);
-    });
-
-    it('does not count a hidden row against the guest cap', async () => {
-      await db('event_feedback_settings')
-        .where({ event_id: eventId }).update({ max_likes_per_guest: 1 });
-      await like();
-      await db('photo_feedback')
-        .where({ photo_id: photoId, feedback_type: 'like' })
-        .update({ is_hidden: true });
-
-      // The hidden row is room, not an occupant: the guest sees an empty
-      // heart, and meeting that click with limit_reached leaves the control
-      // dead until they un-like something they can still see.
-      const result = await feedbackService.submitFeedback(photoId, eventId, {
-        feedback_type: 'like', guest_identifier: ME, guest_id: myGuestRowId,
-      });
-      expect(result.limit_reached).toBeUndefined();
-
-      await db('event_feedback_settings')
-        .where({ event_id: eventId }).update({ max_likes_per_guest: null });
-    });
-
-    it('leaves other anonymous rows alone when there is no identity to scope by', async () => {
-      // With neither guest_id nor guest_identifier the collapse scope degrades
-      // to `guest_identifier IS NULL` — every identifier-less row on the
-      // photo, i.e. other people's.
-      const anon = (extra) => ({
-        photo_id: photoId, event_id: eventId, feedback_type: 'like',
-        is_approved: true, created_at: new Date().toISOString(), ...extra,
-      });
-      const [h] = await db('photo_feedback').insert(anon({ is_hidden: true })).returning('id');
-      const hiddenId = typeof h === 'object' ? h.id : h;
-      await db('photo_feedback').insert(anon({ is_hidden: false }));
-      await db('photo_feedback').insert(anon({ is_hidden: false }));
-
-      await feedbackService.moderateFeedback(hiddenId, 'approve', 1);
-
-      expect(await db('photo_feedback')
-        .where({ photo_id: photoId, feedback_type: 'like', is_hidden: false }))
-        .toHaveLength(3);
-    });
-
-    it('collapses the replacement when an admin unhides the original', async () => {
-      await like();
-      const original = await db('photo_feedback').where({ photo_id: photoId }).first();
-      await db('photo_feedback').where('id', original.id).update({ is_hidden: true });
-
-      await feedbackService.submitFeedback(photoId, eventId, {
-        feedback_type: 'like', guest_identifier: ME, guest_id: myGuestRowId,
-      });
-      expect(await db('photo_feedback').where({ photo_id: photoId })).toHaveLength(2);
-
-      await feedbackService.moderateFeedback(original.id, 'approve', 1);
-
-      // Two visible rows for one guest would double-count in the tallies and
-      // need two toggles to clear, since each deletes a single row.
-      const visible = await db('photo_feedback')
-        .where({ photo_id: photoId, feedback_type: 'like', is_hidden: false });
-      expect(visible).toHaveLength(1);
-      expect(visible[0].id).toBe(original.id);
-    });
-  });
-
-  describe('and clicking still works afterwards', () => {
-    it('re-liking creates a fresh row instead of toggling the hidden one off', async () => {
-      await like();
-      await db('photo_feedback')
-        .where({ photo_id: photoId, feedback_type: 'like' })
-        .update({ is_hidden: true });
-
-      // What the guest sees is an empty heart, so this is an ADD.
-      const result = await feedbackService.submitFeedback(photoId, eventId, {
-        feedback_type: 'like',
-        guest_identifier: ME,
-        guest_id: myGuestRowId,
-      });
-
-      // Before this, the duplicate check found the hidden row and deleted it —
-      // `removed: true` — so the click did nothing visible and the moderation
-      // was silently undone.
-      expect(result.removed).toBeUndefined();
-
-      const visible = await db('photo_feedback')
-        .where({ photo_id: photoId, feedback_type: 'like', is_hidden: false });
-      expect(visible).toHaveLength(1);
-      expect((await getPhoto()).is_liked).toBe(true);
-    });
-  });
-
-});

backend/__tests__/integration/maintenanceJobState.test.js

@@ -1,233 +0,0 @@
-/**
- * Shared run state for the maintenance sweeps (#1181).
- *
- * The behaviour that matters here cannot be observed from one process holding
- * a module-level flag, which is exactly why the flag moved into the database.
- * A second replica is simulated the only way that is honest in a single-process
- * test: by asserting on the shared row itself, and by driving claim() twice —
- * a second caller getting null is precisely what a second replica gets.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const express = require('express');
-const request = require('supertest');
-
-describe('maintenance job state (#1181)', () => {
-  let tmpDir; let db; let app; let jobs;
-
-  const dimStatus = () => request(app).get('/api/admin/photos/repair-dimensions/status');
-  const capStatus = () => request(app).get('/api/admin/photos/repair-capture-dates/status');
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-mjs-'));
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'db.sqlite');
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-    process.env.JWT_SECRET = process.env.JWT_SECRET || 'mjs-secret';
-
-    jest.resetModules();
-    jest.doMock('../../src/middleware/auth', () => ({
-      adminAuth: (req, _res, next) => { req.admin = { id: 1, username: 'tester', roleName: 'admin' }; next(); },
-    }));
-    jest.doMock('../../src/middleware/permissions', () => ({
-      requirePermission: () => (_req, _res, next) => next(),
-    }));
-    jest.doMock('../../src/utils/logger', () => ({
-      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
-    }));
-
-    ({ db } = await require('./helpers/crmDb').bootCrmDb());
-    jobs = require('../../src/services/maintenanceJobState');
-
-    app = express();
-    app.use(express.json());
-    app.use('/api/admin/photos', require('../../src/routes/adminPhotoDimensions'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (db) await db.destroy?.();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(async () => {
-    await db('maintenance_jobs').update({
-      is_running: false, started_at: null, heartbeat_at: null, finished_at: null, last_result: null, owner: null, claim_token: null,
-    });
-  });
-
-  test('the lease table is kept out of .picpeak archives', () => {
-    // It is live state, not data. An archive taken mid-sweep would otherwise
-    // carry is_running = true and a claim token owned by a process on the
-    // SOURCE install; restored inside the staleness window, the target reports
-    // the job as running and refuses new POSTs with no runner to release it.
-    // The importer filters on this same set, so archives written before the
-    // exclusion are skipped on restore too.
-    const { EXCLUDED_TABLES } = require('../../src/services/picpeakExportService');
-    expect(EXCLUDED_TABLES.has('maintenance_jobs')).toBe(true);
-  });
-
-  test('the migration seeds a row for each job', async () => {
-    const names = await db('maintenance_jobs').pluck('job_name');
-    expect(names.sort()).toEqual(['photo_capture_date_backfill', 'photo_dimension_repair']);
-  });
-
-  test('a second claim is refused while the first is alive', async () => {
-    expect(await jobs.claim(jobs.JOB_DIMENSION_REPAIR)).toEqual(expect.any(String));
-    // What a second replica's POST does. Nothing about the first claim lives in
-    // this process, so this is the same question the other replica asks.
-    expect(await jobs.claim(jobs.JOB_DIMENSION_REPAIR)).toBeNull();
-  });
-
-  test('the two jobs claim independently', async () => {
-    expect(await jobs.claim(jobs.JOB_DIMENSION_REPAIR)).toEqual(expect.any(String));
-    expect(await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL)).toEqual(expect.any(String));
-  });
-
-  test('each claim gets a distinct token', async () => {
-    const first = await jobs.claim(jobs.JOB_DIMENSION_REPAIR);
-    await jobs.release(jobs.JOB_DIMENSION_REPAIR, first);
-    const second = await jobs.claim(jobs.JOB_DIMENSION_REPAIR);
-    // Same process, same pid — so an owner string would have collided here and
-    // the fencing below would be worthless.
-    expect(second).not.toBe(first);
-  });
-
-  test('a claim whose heartbeat has gone quiet can be taken over', async () => {
-    expect(await jobs.claim(jobs.JOB_DIMENSION_REPAIR)).toEqual(expect.any(String));
-    expect(await jobs.claim(jobs.JOB_DIMENSION_REPAIR)).toBeNull();
-
-    // The replica holding it was killed: no release, no further heartbeats.
-    const longAgo = new Date(Date.now() - jobs.DEFAULT_STALE_MS - 60000).toISOString();
-    await db('maintenance_jobs').where({ job_name: jobs.JOB_DIMENSION_REPAIR }).update({ heartbeat_at: longAgo });
-
-    expect(await jobs.claim(jobs.JOB_DIMENSION_REPAIR)).toEqual(expect.any(String));
-  });
-
-  test('a superseded runner cannot renew its lease', async () => {
-    const oldToken = await jobs.claim(jobs.JOB_DIMENSION_REPAIR);
-    const longAgo = new Date(Date.now() - jobs.DEFAULT_STALE_MS - 60000).toISOString();
-    await db('maintenance_jobs').where({ job_name: jobs.JOB_DIMENSION_REPAIR }).update({ heartbeat_at: longAgo });
-    const newToken = await jobs.claim(jobs.JOB_DIMENSION_REPAIR);
-    expect(newToken).toEqual(expect.any(String));
-
-    // The old runner is still alive and mid-loop. Its renewal must tell it so,
-    // which is what makes the route loop stop instead of running alongside the
-    // new owner.
-    expect(await jobs.heartbeat(jobs.JOB_DIMENSION_REPAIR, oldToken)).toBe(false);
-    expect(await jobs.heartbeat(jobs.JOB_DIMENSION_REPAIR, newToken)).toBe(true);
-  });
-
-  test('a superseded runner cannot release the new owner\'s claim', async () => {
-    const oldToken = await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL);
-    const longAgo = new Date(Date.now() - jobs.DEFAULT_STALE_MS - 60000).toISOString();
-    await db('maintenance_jobs').where({ job_name: jobs.JOB_CAPTURE_DATE_BACKFILL }).update({ heartbeat_at: longAgo });
-    const newToken = await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL);
-
-    // The old runner finishes late and tries to write its result. Unfenced,
-    // this cleared is_running under the new owner and let a THIRD sweep start.
-    expect(await jobs.release(jobs.JOB_CAPTURE_DATE_BACKFILL, oldToken, { success: 999, noExif: 0, failed: 0 })).toBe(false);
-
-    const state = await jobs.read(jobs.JOB_CAPTURE_DATE_BACKFILL);
-    expect(state.isRunning).toBe(true);
-    expect(state.lastResult).toBeNull();
-    // And the row is still the new owner's to release.
-    expect(await jobs.release(jobs.JOB_CAPTURE_DATE_BACKFILL, newToken, { success: 1, noExif: 0, failed: 0 })).toBe(true);
-  });
-
-  test('a stale run reads as not running, so the button comes back', async () => {
-    await jobs.claim(jobs.JOB_DIMENSION_REPAIR);
-    expect((await jobs.read(jobs.JOB_DIMENSION_REPAIR)).isRunning).toBe(true);
-
-    const longAgo = new Date(Date.now() - jobs.DEFAULT_STALE_MS - 60000).toISOString();
-    await db('maintenance_jobs').where({ job_name: jobs.JOB_DIMENSION_REPAIR }).update({ heartbeat_at: longAgo });
-
-    // is_running is still true in the row — nothing released it — but a status
-    // poll must not leave the operator staring at a job that cannot finish.
-    expect((await db('maintenance_jobs').where({ job_name: jobs.JOB_DIMENSION_REPAIR }).first()).is_running).toBeTruthy();
-    expect((await jobs.read(jobs.JOB_DIMENSION_REPAIR)).isRunning).toBe(false);
-  });
-
-  test('a heartbeat keeps a long run claimed', async () => {
-    const token = await jobs.claim(jobs.JOB_DIMENSION_REPAIR);
-    const longAgo = new Date(Date.now() - jobs.DEFAULT_STALE_MS - 60000).toISOString();
-    await db('maintenance_jobs').where({ job_name: jobs.JOB_DIMENSION_REPAIR }).update({ heartbeat_at: longAgo });
-
-    expect(await jobs.heartbeat(jobs.JOB_DIMENSION_REPAIR, token)).toBe(true);
-
-    expect(await jobs.claim(jobs.JOB_DIMENSION_REPAIR)).toBeNull();
-    expect((await jobs.read(jobs.JOB_DIMENSION_REPAIR)).isRunning).toBe(true);
-  });
-
-  test('release stores the result and read gives it back parsed', async () => {
-    const token = await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL);
-    await jobs.release(jobs.JOB_CAPTURE_DATE_BACKFILL, token, { success: 3, noExif: 2, failed: 1 });
-
-    const state = await jobs.read(jobs.JOB_CAPTURE_DATE_BACKFILL);
-    expect(state.isRunning).toBe(false);
-    expect(state.lastResult).toEqual({ success: 3, noExif: 2, failed: 1 });
-  });
-
-  test('releasing without a result keeps the previous run visible', async () => {
-    const first = await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL);
-    await jobs.release(jobs.JOB_CAPTURE_DATE_BACKFILL, first, { success: 7, noExif: 0, failed: 0 });
-
-    // The "nothing to do" path: claimed, found no candidates, released. It must
-    // not blank the numbers the last real run reported.
-    const second = await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL);
-    await jobs.release(jobs.JOB_CAPTURE_DATE_BACKFILL, second);
-
-    expect((await jobs.read(jobs.JOB_CAPTURE_DATE_BACKFILL)).lastResult).toEqual({ success: 7, noExif: 0, failed: 0 });
-  });
-
-  test('a malformed result does not take the status endpoint down', async () => {
-    await db('maintenance_jobs').where({ job_name: jobs.JOB_DIMENSION_REPAIR }).update({ last_result: 'not json' });
-    const state = await jobs.read(jobs.JOB_DIMENSION_REPAIR);
-    expect(state.lastResult).toBeNull();
-    expect(state.isRunning).toBe(false);
-  });
-
-  test('both status endpoints report the shared row, not process memory', async () => {
-    await jobs.claim(jobs.JOB_DIMENSION_REPAIR);
-    const capToken = await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL);
-    await jobs.release(jobs.JOB_CAPTURE_DATE_BACKFILL, capToken, { success: 1, noExif: 0, failed: 0 });
-
-    // Written straight to the row, exactly as another replica would have.
-    const dim = await dimStatus();
-    expect(dim.status).toBe(200);
-    expect(dim.body.isRunning).toBe(true);
-
-    const cap = await capStatus();
-    expect(cap.status).toBe(200);
-    expect(cap.body.isRunning).toBe(false);
-    expect(cap.body.lastResult).toEqual({ success: 1, noExif: 0, failed: 0 });
-  });
-
-  test('a POST is refused while another replica holds the claim', async () => {
-    // The claim was taken by "another replica" — this process knows nothing
-    // about it beyond the row.
-    await jobs.claim(jobs.JOB_CAPTURE_DATE_BACKFILL);
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-    expect(res.status).toBe(409);
-
-    const dimRes = await request(app).post('/api/admin/photos/repair-dimensions');
-    // The other job is untouched by that claim, so it is free to start.
-    expect(dimRes.status).toBe(200);
-  });
-
-  test('the no-op path releases the claim it took', async () => {
-    // No photos at all, so both endpoints take their "nothing to do" exit.
-    await db('photos').del();
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-    expect(res.body.count).toBe(0);
-
-    const row = await db('maintenance_jobs').where({ job_name: jobs.JOB_CAPTURE_DATE_BACKFILL }).first();
-    expect(row.is_running).toBeFalsy();
-    // ...and a second POST is therefore accepted rather than 409ing forever.
-    expect((await request(app).post('/api/admin/photos/repair-capture-dates')).status).toBe(200);
-  });
-});

backend/__tests__/integration/maintenanceJobStatePg.test.js

@@ -1,102 +0,0 @@
-/**
- * PostgreSQL checks for the shared maintenance-job state (#1181).
- * Gated: runs only when PICPEAK_PG_TEST_URL points at a throwaway database, e.g.
- *   PICPEAK_PG_TEST_URL="postgres://picpeak:picpeak_secure_pass_2024@127.0.0.1:7102/picpeak_mjs_test" \
- *     npx jest __tests__/integration/maintenanceJobStatePg.test.js
- *
- * What SQLite cannot answer: the claim leans on comparing a `timestamp` column
- * against an ISO-8601 string, and on an UPDATE ... WHERE guard being atomic
- * under real concurrent connections. SQLite compares those strings
- * lexicographically and serialises writes anyway, so it would pass either way —
- * exactly the shape of divergence that has bitten this repo before.
- */
-
-const knex = require('knex');
-
-const PG_URL = process.env.PICPEAK_PG_TEST_URL;
-const maybe = PG_URL ? describe : describe.skip;
-
-maybe('maintenance job state on Postgres', () => {
-  let pgDb;
-  let jobs;
-  const JOB = 'photo_dimension_repair';
-
-  beforeAll(async () => {
-    pgDb = knex({ client: 'pg', connection: PG_URL, pool: { min: 0, max: 10 } });
-    await pgDb.raw('DROP TABLE IF EXISTS maintenance_jobs');
-    await require('../../migrations/core/179_maintenance_job_state').up(pgDb);
-
-    jest.resetModules();
-    jest.doMock('../../src/database/db', () => ({ db: pgDb }));
-    jest.doMock('../../src/utils/logger', () => ({
-      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
-    }));
-    jobs = require('../../src/services/maintenanceJobState');
-  }, 60000);
-
-  afterAll(async () => {
-    jest.dontMock('../../src/database/db');
-    if (pgDb) await pgDb.destroy();
-  });
-
-  beforeEach(async () => {
-    await pgDb('maintenance_jobs').update({
-      is_running: false, started_at: null, heartbeat_at: null, finished_at: null, last_result: null, owner: null, claim_token: null,
-    });
-  });
-
-  test('the ISO-string cutoff really compares as a timestamp, not as text', async () => {
-    expect(await jobs.claim(JOB)).toEqual(expect.any(String));
-    expect(await jobs.claim(JOB)).toBeNull();
-
-    await pgDb('maintenance_jobs').where({ job_name: JOB })
-      .update({ heartbeat_at: new Date(Date.now() - jobs.DEFAULT_STALE_MS - 60000).toISOString() });
-
-    // If Postgres had rejected or mis-cast the ISO string this would either
-    // throw or never match.
-    expect(await jobs.claim(JOB)).toEqual(expect.any(String));
-
-    const row = await pgDb('maintenance_jobs').where({ job_name: JOB }).first();
-    expect(row.heartbeat_at).toBeInstanceOf(Date);
-  });
-
-  test('concurrent claims on real connections produce exactly one winner', async () => {
-    // The whole point of the conditional UPDATE. Ten connections race; nine
-    // must lose. SQLite cannot demonstrate this — it serialises writers.
-    const results = await Promise.all(Array.from({ length: 10 }, () => jobs.claim(JOB)));
-    expect(results.filter(Boolean)).toHaveLength(1);
-    // ...and the winner holds a token nobody else can forge.
-    expect(results.find(Boolean)).toEqual(expect.any(String));
-  });
-
-  test('a released job can be re-claimed exactly once again', async () => {
-    const token = await jobs.claim(JOB);
-    await jobs.release(JOB, token, { success: 2, failed: 0 });
-
-    const results = await Promise.all(Array.from({ length: 5 }, () => jobs.claim(JOB)));
-    expect(results.filter(Boolean)).toHaveLength(1);
-    expect((await jobs.read(JOB)).lastResult).toEqual({ success: 2, failed: 0 });
-  });
-
-  test('a superseded runner is fenced out on real Postgres', async () => {
-    const oldToken = await jobs.claim(JOB);
-    await pgDb('maintenance_jobs').where({ job_name: JOB })
-      .update({ heartbeat_at: new Date(Date.now() - jobs.DEFAULT_STALE_MS - 60000).toISOString() });
-    const newToken = await jobs.claim(JOB);
-
-    expect(await jobs.heartbeat(JOB, oldToken)).toBe(false);
-    expect(await jobs.release(JOB, oldToken, { success: 999, failed: 0 })).toBe(false);
-    // The new owner still holds it, with its result unwritten.
-    expect((await jobs.read(JOB)).isRunning).toBe(true);
-    expect(await jobs.release(JOB, newToken, { success: 4, failed: 0 })).toBe(true);
-  });
-
-  test('read() reports a live claim as running and a stale one as not', async () => {
-    await jobs.claim(JOB);
-    expect((await jobs.read(JOB)).isRunning).toBe(true);
-
-    await pgDb('maintenance_jobs').where({ job_name: JOB })
-      .update({ heartbeat_at: new Date(Date.now() - jobs.DEFAULT_STALE_MS - 1000).toISOString() });
-    expect((await jobs.read(JOB)).isRunning).toBe(false);
-  });
-});

backend/__tests__/integration/oidcLogout.test.js

@@ -0,0 +1,284 @@
+/**
+ * OIDC logout-to-IdP integration tests (#798 phase 3).
+ *
+ * Same full-stack shape as oidcSso.test.js: real routes over a mock
+ * in-process IdP, genuine discovery/JWKS/PKCE via openid-client. Pins:
+ *
+ *   - the SSO callback stores the raw ID token in the oidc_id_token cookie
+ *   - /logout with that cookie + oidc_logout_from_idp=true returns the
+ *     IdP end-session URL (id_token_hint, post_logout_redirect_uri,
+ *     client_id) and clears the cookie
+ *   - feature off → no ssoLogoutUrl even for an SSO session
+ *   - no oidc_id_token cookie (local-password session) → no ssoLogoutUrl
+ *     even with the feature on — local sessions never bounce to the IdP
+ *   - IdP without an end_session_endpoint → no ssoLogoutUrl, logout still 200
+ *   - settings surface: GET exposes the flag + post_logout_redirect_uri,
+ *     PUT persists the flag
+ */
+
+const request = require('supertest');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const bcrypt = require('bcrypt');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+const { MockOidcProvider } = require('./helpers/mockOidcProvider');
+
+describe('OIDC logout-to-IdP (#798 phase 3)', () => {
+  let db;
+  let cleanup;
+  let app;
+  let idp;
+  let oidcService;
+
+  beforeAll(async () => {
+    process.env.JWT_SECRET = process.env.JWT_SECRET || 'oidc-logout-test-secret';
+    process.env.FRONTEND_URL = 'http://localhost:5199';
+    ({ db, cleanup } = await bootCrmDb());
+
+    idp = new MockOidcProvider();
+    const issuer = await idp.start();
+
+    oidcService = require('../../src/services/oidcService');
+    await oidcService.saveOidcSettings({
+      oidc_enabled: true,
+      oidc_issuer_url: issuer,
+      oidc_client_id: idp.clientId,
+      oidc_client_secret: idp.clientSecret,
+      oidc_autoprovision: true,
+      oidc_default_role: 'viewer',
+      oidc_logout_from_idp: true,
+    });
+
+    const authRouter = require('../../src/routes/auth');
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/auth', authRouter);
+  }, 120000);
+
+  afterAll(async () => {
+    if (idp) await idp.stop();
+    if (cleanup) await cleanup();
+  });
+
+  /** Drive login → IdP → callback like a browser; returns the callback response. */
+  async function ssoRoundTrip() {
+    const loginRes = await request(app).get('/api/auth/admin/sso/login').expect(302);
+    const stateCookie = (loginRes.headers['set-cookie'] || [])
+      .find((c) => c.startsWith('oidc_state='))
+      .split(';')[0];
+
+    const idpRes = await fetch(loginRes.headers.location, { redirect: 'manual' });
+    expect(idpRes.status).toBe(302);
+    const back = new URL(idpRes.headers.get('location'));
+
+    return request(app)
+      .get(`${back.pathname}?${back.searchParams.toString()}`)
+      .set('Cookie', stateCookie)
+      .expect(302);
+  }
+
+  /**
+   * The oidc_id_token cookie pair ("oidc_id_token=<jwt>") from a callback
+   * response. The callback carries TWO Set-Cookie headers for this name —
+   * establishAdminSession clears any stale marker, then the callback sets
+   * the fresh one — and browsers apply them in order, so the LAST wins.
+   */
+  function idTokenCookie(res) {
+    const cookies = (res.headers['set-cookie'] || []).filter((c) => c.startsWith('oidc_id_token='));
+    const last = cookies[cookies.length - 1];
+    return last ? last.split(';')[0] : null;
+  }
+
+  it('stores the raw ID token in the oidc_id_token cookie on SSO login', async () => {
+    idp.setNextUser({ sub: 'logout-sub-1', email: 'logout@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+
+    const cookie = idTokenCookie(res);
+    expect(cookie).toBeTruthy();
+    // Raw JWT, HttpOnly, scoped to /api/auth.
+    const raw = decodeURIComponent(cookie.replace('oidc_id_token=', ''));
+    expect(raw.split('.')).toHaveLength(3);
+    const setCookies = (res.headers['set-cookie'] || []).filter((c) => c.startsWith('oidc_id_token='));
+    const full = setCookies[setCookies.length - 1];
+    expect(full).toMatch(/HttpOnly/i);
+    expect(full).toMatch(/Path=\/api\/auth/i);
+  });
+
+  it('returns the IdP end-session URL on logout and clears the cookie', async () => {
+    idp.setNextUser({ sub: 'logout-sub-2', email: 'logout2@example.com', email_verified: true });
+    const cbRes = await ssoRoundTrip();
+    const cookie = idTokenCookie(cbRes);
+    const rawIdToken = decodeURIComponent(cookie.replace('oidc_id_token=', ''));
+
+    const res = await request(app)
+      .post('/api/auth/logout')
+      .set('Cookie', cookie)
+      .expect(200);
+
+    expect(res.body.ssoLogoutUrl).toBeTruthy();
+    const url = new URL(res.body.ssoLogoutUrl);
+    expect(url.href.startsWith(`${idp.issuer}/logout`)).toBe(true);
+    expect(url.searchParams.get('id_token_hint')).toBe(rawIdToken);
+    expect(url.searchParams.get('post_logout_redirect_uri')).toBe('http://localhost:5199/admin/login');
+    expect(url.searchParams.get('client_id')).toBe(idp.clientId);
+
+    // Cookie must be cleared so a later local-password logout in the same
+    // browser doesn't bounce to the IdP again.
+    const cleared = (res.headers['set-cookie'] || []).find((c) => c.startsWith('oidc_id_token='));
+    expect(cleared).toBeTruthy();
+    expect(cleared).toMatch(/Expires=Thu, 01 Jan 1970|Max-Age=0/i);
+  });
+
+  it('omits ssoLogoutUrl when the feature is disabled', async () => {
+    idp.setNextUser({ sub: 'logout-sub-3', email: 'logout3@example.com', email_verified: true });
+    const cbRes = await ssoRoundTrip();
+    const cookie = idTokenCookie(cbRes);
+
+    await oidcService.saveOidcSettings({ oidc_logout_from_idp: false });
+    try {
+      const res = await request(app)
+        .post('/api/auth/logout')
+        .set('Cookie', cookie)
+        .expect(200);
+      expect(res.body.ssoLogoutUrl).toBeUndefined();
+    } finally {
+      await oidcService.saveOidcSettings({ oidc_logout_from_idp: true });
+    }
+  });
+
+  it('omits ssoLogoutUrl without an oidc_id_token cookie (local-password session)', async () => {
+    const res = await request(app).post('/api/auth/logout').expect(200);
+    expect(res.body.ssoLogoutUrl).toBeUndefined();
+  });
+
+  it('omits ssoLogoutUrl when the IdP advertises no end_session_endpoint', async () => {
+    // Separate provider whose discovery document lacks end_session_endpoint;
+    // repointing the settings invalidates the discovery cache.
+    const bareIdp = new MockOidcProvider();
+    bareIdp.advertiseEndSession = false;
+    const bareIssuer = await bareIdp.start();
+    try {
+      await oidcService.saveOidcSettings({
+        oidc_issuer_url: bareIssuer,
+        oidc_client_id: bareIdp.clientId,
+        oidc_client_secret: bareIdp.clientSecret,
+      });
+
+      bareIdp.setNextUser({ sub: 'logout-sub-4', email: 'logout4@example.com', email_verified: true });
+      const cbRes = await ssoRoundTrip();
+      const cookie = idTokenCookie(cbRes);
+      expect(cookie).toBeTruthy();
+
+      const res = await request(app)
+        .post('/api/auth/logout')
+        .set('Cookie', cookie)
+        .expect(200);
+      expect(res.body.ssoLogoutUrl).toBeUndefined();
+    } finally {
+      await bareIdp.stop();
+      await oidcService.saveOidcSettings({
+        oidc_issuer_url: idp.issuer,
+        oidc_client_id: idp.clientId,
+        oidc_client_secret: idp.clientSecret,
+      });
+    }
+  });
+
+  it('stores an issuer-tagged marker for oversized ID tokens; logout still round-trips, without a hint', async () => {
+    idp.setNextUser({
+      sub: 'logout-sub-5',
+      email: 'logout5@example.com',
+      email_verified: true,
+      // ~9KB of group claims — far past the 4KB cookie limit.
+      groups: Array.from({ length: 300 }, (_, i) => `group-${String(i).padStart(4, '0')}-xxxxxxxxxxxxxxxx`),
+    });
+    const cbRes = await ssoRoundTrip();
+    const cookie = idTokenCookie(cbRes);
+    expect(cookie).toBeTruthy();
+    // Issuer-tagged marker, not the (oversized) token itself.
+    const marker = decodeURIComponent(cookie.replace('oidc_id_token=', ''));
+    expect(marker.startsWith('sso.')).toBe(true);
+    expect(Buffer.from(marker.split('.')[1], 'base64url').toString('utf8')).toBe(idp.issuer);
+
+    const res = await request(app)
+      .post('/api/auth/logout')
+      .set('Cookie', cookie)
+      .expect(200);
+    expect(res.body.ssoLogoutUrl).toBeTruthy();
+    const url = new URL(res.body.ssoLogoutUrl);
+    expect(url.searchParams.get('id_token_hint')).toBeNull();
+    expect(url.searchParams.get('client_id')).toBe(idp.clientId);
+  });
+
+  it('skips the round-trip for an oversized-token marker from a DIFFERENT issuer', async () => {
+    const foreignMarker = `sso.${Buffer.from('http://other-idp.example').toString('base64url')}`;
+    const res = await request(app)
+      .post('/api/auth/logout')
+      .set('Cookie', `oidc_id_token=${foreignMarker}`)
+      .expect(200);
+    expect(res.body.ssoLogoutUrl).toBeUndefined();
+  });
+
+  it('a fresh local-password login clears a stale SSO marker', async () => {
+    const role = await db('roles').where({ name: 'admin' }).first();
+    await db('admin_users').insert({
+      username: 'stale-marker-admin',
+      email: 'stale-marker@example.com',
+      password_hash: await bcrypt.hash('StaleMarker123!', 4),
+      role_id: role.id,
+      is_active: 1,
+      must_change_password: 0,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    });
+
+    // Stale marker from a dead SSO session rides along on the login request.
+    const res = await request(app)
+      .post('/api/auth/admin/login')
+      .set('Cookie', 'oidc_id_token=stale.jwt.value')
+      .send({ username: 'stale-marker-admin', password: 'StaleMarker123!' })
+      .expect(200);
+
+    const cleared = (res.headers['set-cookie'] || []).find((c) => c.startsWith('oidc_id_token='));
+    expect(cleared).toBeTruthy();
+    expect(cleared).toMatch(/Expires=Thu, 01 Jan 1970|Max-Age=0/i);
+  });
+
+  it('skips the round-trip when the stored hint was issued by a DIFFERENT issuer (config changed)', async () => {
+    // Fake-but-well-formed JWT from another IdP — payload is all that matters,
+    // buildEndSessionUrl decodes without verification for routing only.
+    const b64 = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
+    const foreignToken = `${b64({ alg: 'none' })}.${b64({ iss: 'http://other-idp.example', aud: idp.clientId })}.sig`;
+
+    const res = await request(app)
+      .post('/api/auth/logout')
+      .set('Cookie', `oidc_id_token=${foreignToken}`)
+      .expect(200);
+    expect(res.body.ssoLogoutUrl).toBeUndefined();
+  });
+
+  it('drops only the hint when the issuer matches but the client changed', async () => {
+    const b64 = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
+    const oldClientToken = `${b64({ alg: 'none' })}.${b64({ iss: idp.issuer, aud: 'previous-client-id' })}.sig`;
+
+    const res = await request(app)
+      .post('/api/auth/logout')
+      .set('Cookie', `oidc_id_token=${oldClientToken}`)
+      .expect(200);
+    expect(res.body.ssoLogoutUrl).toBeTruthy();
+    const url = new URL(res.body.ssoLogoutUrl);
+    expect(url.searchParams.get('id_token_hint')).toBeNull();
+    expect(url.searchParams.get('client_id')).toBe(idp.clientId);
+  });
+
+  it('exposes the flag and post_logout_redirect_uri via getOidcConfig/getPostLogoutRedirectUri', async () => {
+    // Settings-route auth chains are covered in oidcSso.test.js; here the
+    // service surface the routes read from is pinned directly.
+    const cfg = await oidcService.getOidcConfig();
+    expect(cfg.logoutFromIdp).toBe(true);
+    expect(await oidcService.getPostLogoutRedirectUri()).toBe('http://localhost:5199/admin/login');
+  });
+});

backend/__tests__/integration/oidcRoleMappingPolicy.test.js

@@ -0,0 +1,416 @@
+/**
+ * OIDC role mapping + login policy integration tests (#798, phase 2).
+ *
+ * Same harness as oidcSso.test.js: supertest over the real routes, mock
+ * in-process IdP with genuine RS256/PKCE validation, fresh-SQLite DB. Pins:
+ *
+ *   - JIT provisioning takes the MAPPED role from a nested dot-path claim
+ *     (Keycloak's realm_access.roles), not the static default
+ *   - roles are re-evaluated on every SSO login (upgrade AND downgrade)
+ *   - several mapped roles → the highest-priority one wins
+ *   - non-strict: unmapped login keeps the current role / default at JIT
+ *   - strict (require_mapped_role): unmapped login → sso_error=no_role
+ *   - the last active super_admin is never demoted by mapping
+ *   - space-separated string claim values work (flat `roles` claim)
+ *   - disable_local_login: password login → 403; OIDC_BREAK_GLASS=true
+ *     re-opens it; flag is inert while SSO is disabled
+ *   - PUT /sso validation: unknown mapping target and
+ *     disable-local-login-without-SSO are rejected
+ */
+
+const request = require('supertest');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const bcrypt = require('bcrypt');
+const jwt = require('jsonwebtoken');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+const { MockOidcProvider } = require('./helpers/mockOidcProvider');
+
+describe('OIDC role mapping + login policy (#798 phase 2)', () => {
+  let db;
+  let cleanup;
+  let app;
+  let idp;
+  let oidcService;
+  let superAdminToken;
+
+  beforeAll(async () => {
+    process.env.JWT_SECRET = process.env.JWT_SECRET || 'oidc-test-secret';
+    process.env.FRONTEND_URL = 'http://localhost:5199';
+    delete process.env.OIDC_BREAK_GLASS;
+    ({ db, cleanup } = await bootCrmDb());
+
+    idp = new MockOidcProvider();
+    const issuer = await idp.start();
+
+    oidcService = require('../../src/services/oidcService');
+    await oidcService.saveOidcSettings({
+      oidc_enabled: true,
+      oidc_issuer_url: issuer,
+      oidc_client_id: idp.clientId,
+      oidc_client_secret: idp.clientSecret,
+      oidc_autoprovision: true,
+      oidc_default_role: 'viewer',
+      oidc_role_mapping_enabled: true,
+      oidc_roles_claim: 'realm_access.roles',
+      oidc_role_mappings: {
+        'pp-super': 'super_admin',
+        'pp-admins': 'admin',
+        'pp-view': 'viewer',
+      },
+    });
+
+    const authRouter = require('../../src/routes/auth');
+    const adminSettingsRouter = require('../../src/routes/adminSettings');
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/auth', authRouter);
+    app.use('/api/admin/settings', adminSettingsRouter);
+
+    // A real super_admin row + token for the settings-validation tests.
+    const superRole = await db('roles').where({ name: 'super_admin' }).first();
+    const [rootId] = await db('admin_users').insert({
+      username: 'root-admin',
+      email: 'root@example.com',
+      password_hash: await bcrypt.hash('RootPass123', 4),
+      role_id: superRole.id,
+      is_active: 1,
+      auth_provider: 'local',
+      created_at: new Date(),
+      updated_at: new Date(),
+    }).returning('id').then((r) => [r[0]?.id || r[0]]);
+    superAdminToken = jwt.sign(
+      { id: rootId, username: 'root-admin', type: 'admin', role: 'super_admin', loginTime: Date.now() },
+      process.env.JWT_SECRET,
+      { expiresIn: '1h', issuer: 'picpeak-auth' }
+    );
+  }, 120000);
+
+  afterAll(async () => {
+    delete process.env.OIDC_BREAK_GLASS;
+    if (idp) await idp.stop();
+    if (cleanup) await cleanup();
+  });
+
+  /** Drive login → IdP → callback like a browser; returns the callback response. */
+  async function ssoRoundTrip() {
+    const loginRes = await request(app).get('/api/auth/admin/sso/login').expect(302);
+    const stateCookie = (loginRes.headers['set-cookie'] || [])
+      .find((c) => c.startsWith('oidc_state=')).split(';')[0];
+    const idpRes = await fetch(loginRes.headers.location, { redirect: 'manual' });
+    expect(idpRes.status).toBe(302);
+    const back = new URL(idpRes.headers.get('location'));
+    return request(app)
+      .get(`${back.pathname}?${back.searchParams.toString()}`)
+      .set('Cookie', stateCookie)
+      .expect(302);
+  }
+
+  async function roleOf(email) {
+    const row = await db('admin_users').where({ email }).first();
+    const role = await db('roles').where({ id: row.role_id }).first();
+    return role.name;
+  }
+
+  it('JIT-provisions with the role mapped from the nested dot-path claim', async () => {
+    idp.setNextUser({
+      sub: 'sub-map-1',
+      email: 'mapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['irrelevant', 'pp-admins'] },
+    });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    expect(await roleOf('mapped@example.com')).toBe('admin');
+  });
+
+  it('re-evaluates the role on every login — downgrade lands', async () => {
+    idp.setNextUser({
+      sub: 'sub-map-1',
+      email: 'mapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['pp-view'] },
+    });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    expect(await roleOf('mapped@example.com')).toBe('viewer');
+  });
+
+  it('re-evaluates the role on every login — upgrade lands and the session JWT carries it', async () => {
+    idp.setNextUser({
+      sub: 'sub-map-1',
+      email: 'mapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['pp-admins'] },
+    });
+    const res = await ssoRoundTrip();
+    expect(await roleOf('mapped@example.com')).toBe('admin');
+
+    // The freshly-minted session token must already carry the NEW role —
+    // the sync happens before session establishment.
+    const adminCookie = (res.headers['set-cookie'] || []).find((c) => c.startsWith('admin_token='));
+    const token = decodeURIComponent(adminCookie.split(';')[0].replace('admin_token=', ''));
+    const decoded = jwt.verify(token, process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
+    expect(decoded.role).toBe('admin');
+  });
+
+  it('picks the highest-priority role when several IdP values map', async () => {
+    idp.setNextUser({
+      sub: 'sub-multi',
+      email: 'multi@example.com',
+      email_verified: true,
+      realm_access: { roles: ['pp-view', 'pp-admins'] },
+    });
+    await ssoRoundTrip();
+    expect(await roleOf('multi@example.com')).toBe('admin');
+  });
+
+  it('non-strict: an unmapped login keeps the current role / gets the default at JIT', async () => {
+    // Existing admin keeps its role.
+    idp.setNextUser({
+      sub: 'sub-map-1',
+      email: 'mapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['nothing-mapped'] },
+    });
+    let res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    expect(await roleOf('mapped@example.com')).toBe('admin');
+
+    // JIT falls back to the configured default role.
+    idp.setNextUser({
+      sub: 'sub-unmapped-jit',
+      email: 'unmapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['nothing-mapped'] },
+    });
+    res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    expect(await roleOf('unmapped@example.com')).toBe('viewer');
+  });
+
+  it('strict mode refuses unmapped logins with sso_error=no_role and no session', async () => {
+    await oidcService.saveOidcSettings({ oidc_require_mapped_role: true });
+    idp.setNextUser({
+      sub: 'sub-map-1',
+      email: 'mapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['nothing-mapped'] },
+    });
+    const res = await ssoRoundTrip();
+    await oidcService.saveOidcSettings({ oidc_require_mapped_role: false });
+
+    expect(res.headers.location).toBe('http://localhost:5199/admin/login?sso_error=no_role');
+    expect((res.headers['set-cookie'] || []).find((c) => c.startsWith('admin_token='))).toBeFalsy();
+    // Role untouched by the refused attempt.
+    expect(await roleOf('mapped@example.com')).toBe('admin');
+  });
+
+  it('never demotes the last active super_admin', async () => {
+    // Make the SSO admin the ONLY active super_admin.
+    const superRole = await db('roles').where({ name: 'super_admin' }).first();
+    const ssoAdmin = await db('admin_users').where({ email: 'mapped@example.com' }).first();
+    await db('admin_users').where({ role_id: superRole.id }).update({ is_active: 0 });
+    await db('admin_users').where({ id: ssoAdmin.id }).update({ role_id: superRole.id, is_active: 1 });
+
+    idp.setNextUser({
+      sub: 'sub-map-1',
+      email: 'mapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['pp-view'] },
+    });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    // Still super_admin — the demotion was refused, the login was not.
+    expect(await roleOf('mapped@example.com')).toBe('super_admin');
+
+    // Restore: root admin back to active super_admin, SSO admin back to admin.
+    const adminRole = await db('roles').where({ name: 'admin' }).first();
+    await db('admin_users').where({ email: 'root@example.com' }).update({ is_active: 1 });
+    await db('admin_users').where({ id: ssoAdmin.id }).update({ role_id: adminRole.id });
+
+    // With ANOTHER active super_admin present the same downgrade goes through.
+    idp.setNextUser({
+      sub: 'sub-map-1',
+      email: 'mapped@example.com',
+      email_verified: true,
+      realm_access: { roles: ['pp-view'] },
+    });
+    await db('admin_users').where({ id: ssoAdmin.id }).update({ role_id: superRole.id });
+    await ssoRoundTrip();
+    expect(await roleOf('mapped@example.com')).toBe('viewer');
+  });
+
+  it('never demotes the last LOCAL-password super_admin even when an OIDC-owned super exists', async () => {
+    const superRole = await db('roles').where({ name: 'super_admin' }).first();
+    const viewerRole = await db('roles').where({ name: 'viewer' }).first();
+
+    // A local-password super admin, SSO-linked via verified email so role
+    // sync applies to it.
+    const [localId] = await db('admin_users').insert({
+      username: 'local-super',
+      email: 'local-super@example.com',
+      password_hash: await bcrypt.hash('LocalSuper123', 4),
+      role_id: superRole.id,
+      is_active: 1,
+      auth_provider: 'local',
+      created_at: new Date(),
+      updated_at: new Date(),
+    }).returning('id').then((r) => [r[0]?.id || r[0]]);
+
+    // The only OTHER active super is OIDC-owned (root goes inactive) — the
+    // plain last-super guard would allow the demotion, the break-glass
+    // guard must not.
+    const ssoAdmin = await db('admin_users').where({ email: 'mapped@example.com' }).first();
+    await db('admin_users').where({ id: ssoAdmin.id }).update({ role_id: superRole.id });
+    await db('admin_users').where({ email: 'root@example.com' }).update({ is_active: 0 });
+
+    idp.setNextUser({
+      sub: 'sub-local-super',
+      email: 'local-super@example.com',
+      email_verified: true,
+      realm_access: { roles: ['pp-view'] },
+    });
+    const res = await ssoRoundTrip();
+
+    const row = await db('admin_users').where({ id: localId }).first();
+    // Restore the fixture state before asserting.
+    await db('admin_users').where({ email: 'root@example.com' }).update({ is_active: 1 });
+    await db('admin_users').where({ id: ssoAdmin.id }).update({ role_id: viewerRole.id });
+    await db('admin_users').where({ id: localId }).update({ is_active: 0 });
+
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    expect(row.role_id).toBe(superRole.id); // kept — it is the break-glass account
+  });
+
+  it('treats prototype-property IdP values (constructor/toString) as unmapped, not as an error', async () => {
+    idp.setNextUser({
+      sub: 'sub-proto',
+      email: 'proto@example.com',
+      email_verified: true,
+      realm_access: { roles: ['constructor', 'toString', '__proto__'] },
+    });
+    const res = await ssoRoundTrip();
+    // Non-strict: unmapped → JIT with the default role, login succeeds.
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    expect(await roleOf('proto@example.com')).toBe('viewer');
+  });
+
+  it('accepts a space-separated string value on a flat claim', async () => {
+    await oidcService.saveOidcSettings({ oidc_roles_claim: 'roles' });
+    idp.setNextUser({
+      sub: 'sub-flat',
+      email: 'flat@example.com',
+      email_verified: true,
+      roles: 'other pp-admins',
+    });
+    const res = await ssoRoundTrip();
+    await oidcService.saveOidcSettings({ oidc_roles_claim: 'realm_access.roles' });
+
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    expect(await roleOf('flat@example.com')).toBe('admin');
+  });
+
+  it('refuses local password login while disable_local_login is effective', async () => {
+    await oidcService.saveOidcSettings({ oidc_disable_local_login: true });
+    const res = await request(app)
+      .post('/api/auth/admin/login')
+      .send({ username: 'root@example.com', password: 'RootPass123' });
+    expect(res.status).toBe(403);
+    expect(res.body.code).toBe('LOCAL_LOGIN_DISABLED');
+  });
+
+  it('OIDC_BREAK_GLASS=true re-opens local login despite the policy', async () => {
+    process.env.OIDC_BREAK_GLASS = 'true';
+    const res = await request(app)
+      .post('/api/auth/admin/login')
+      .send({ username: 'root@example.com', password: 'RootPass123' });
+    delete process.env.OIDC_BREAK_GLASS;
+    expect(res.status).toBe(200);
+    expect(res.body.user).toBeTruthy();
+  });
+
+  it('the stored flag is inert while SSO is disabled', async () => {
+    // Simulate a torn-down SSO config with the stale flag still set — the
+    // runtime check must ignore it (no lockout).
+    await db('app_settings').where({ setting_key: 'oidc_enabled' })
+      .update({ setting_value: JSON.stringify(false) });
+    expect(await oidcService.isLocalLoginDisabled()).toBe(false);
+    await db('app_settings').where({ setting_key: 'oidc_enabled' })
+      .update({ setting_value: JSON.stringify(true) });
+    expect(await oidcService.isLocalLoginDisabled()).toBe(true);
+    await oidcService.saveOidcSettings({ oidc_disable_local_login: false });
+  });
+
+  it('the policy disarms itself when no active local-password super admin remains', async () => {
+    await oidcService.saveOidcSettings({ oidc_disable_local_login: true });
+    expect(await oidcService.isLocalLoginDisabled()).toBe(true);
+    // The break-glass account disappears (e.g. manual demotion/deactivation
+    // while the policy is on) → local login must re-open by itself.
+    await db('admin_users').where({ email: 'root@example.com' }).update({ auth_provider: 'oidc' });
+    expect(await oidcService.isLocalLoginDisabled()).toBe(false);
+    await db('admin_users').where({ email: 'root@example.com' }).update({ auth_provider: 'local' });
+    await oidcService.saveOidcSettings({ oidc_disable_local_login: false });
+  });
+
+  it('PUT /sso rejects a mapping onto an unknown role', async () => {
+    const res = await request(app)
+      .put('/api/admin/settings/sso')
+      .set('Authorization', `Bearer ${superAdminToken}`)
+      .send({ oidc_role_mappings: { 'pp-admins': 'does_not_exist' } });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/does_not_exist/);
+    // Stored mapping unchanged.
+    const cfg = await oidcService.getOidcConfig();
+    expect(cfg.roleMappings['pp-admins']).toBe('admin');
+  });
+
+  it('PUT /sso rejects disabling local login while SSO is (being turned) off', async () => {
+    const res = await request(app)
+      .put('/api/admin/settings/sso')
+      .set('Authorization', `Bearer ${superAdminToken}`)
+      .send({ oidc_enabled: false, oidc_disable_local_login: true });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/while SSO is enabled/);
+  });
+
+  it('PUT /sso refuses SSO-only mode without an active local-password super admin', async () => {
+    // Make every active super_admin OIDC-owned — break-glass would then
+    // re-open a password route that no account can use.
+    const superRole = await db('roles').where({ name: 'super_admin' }).first();
+    await db('admin_users').where({ role_id: superRole.id }).update({ auth_provider: 'oidc' });
+    const denied = await request(app)
+      .put('/api/admin/settings/sso')
+      .set('Authorization', `Bearer ${superAdminToken}`)
+      .send({ oidc_disable_local_login: true });
+    // Restore the local break-glass account, then the same request passes.
+    await db('admin_users').where({ email: 'root@example.com' }).update({ auth_provider: 'local' });
+    expect(denied.status).toBe(400);
+    expect(denied.body.error).toMatch(/break-glass/);
+
+    const allowed = await request(app)
+      .put('/api/admin/settings/sso')
+      .set('Authorization', `Bearer ${superAdminToken}`)
+      .send({ oidc_disable_local_login: true });
+    expect(allowed.status).toBe(200);
+    await oidcService.saveOidcSettings({ oidc_disable_local_login: false });
+  });
+
+  it('GET /sso returns the phase-2 fields', async () => {
+    const res = await request(app)
+      .get('/api/admin/settings/sso')
+      .set('Authorization', `Bearer ${superAdminToken}`);
+    expect(res.status).toBe(200);
+    expect(res.body.oidc_role_mapping_enabled).toBe(true);
+    expect(res.body.oidc_roles_claim).toBe('realm_access.roles');
+    expect(res.body.oidc_role_mappings).toEqual({
+      'pp-super': 'super_admin',
+      'pp-admins': 'admin',
+      'pp-view': 'viewer',
+    });
+    expect(res.body.oidc_require_mapped_role).toBe(false);
+    expect(res.body.oidc_disable_local_login).toBe(false);
+  });
+});

backend/__tests__/integration/oidcSso.test.js

@@ -0,0 +1,302 @@
+/**
+ * OIDC SSO integration tests (#798, phase 1).
+ *
+ * Full-stack over a mock in-process IdP (mockOidcProvider): supertest drives
+ * the real /admin/sso/login and /admin/sso/callback routes on a fresh-SQLite
+ * database, openid-client does genuine discovery/JWKS/PKCE/ID-token
+ * validation against the mock issuer. Pins:
+ *
+ *   - happy path: JIT provisioning creates an admin and sets the session cookie
+ *   - JIT off → not_provisioned redirect, no row created
+ *   - repeat login matches by sub, not email (email change ≠ new account)
+ *   - verified-email one-time link onto an existing local admin
+ *   - unverified email must NOT link (falls through to JIT/or error)
+ *   - deactivated admin → inactive redirect
+ *   - missing/forged state cookie → state redirect
+ *   - nonce tamper from the IdP → idp redirect
+ *   - settings endpoints: secret write-only, generic /general upsert cannot
+ *     clobber oidc_client_secret
+ */
+
+const request = require('supertest');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const bcrypt = require('bcrypt');
+const jwt = require('jsonwebtoken');
+
+const { bootCrmDb } = require('./helpers/crmDb');
+const { MockOidcProvider } = require('./helpers/mockOidcProvider');
+
+describe('OIDC SSO (#798)', () => {
+  let db;
+  let cleanup;
+  let app;
+  let idp;
+  let oidcService;
+
+  const agentCookies = {};
+
+  beforeAll(async () => {
+    process.env.JWT_SECRET = process.env.JWT_SECRET || 'oidc-test-secret';
+    // The redirect_uri derives from the public base URL — pin it explicitly:
+    // CI has no backend/.env, and getFrontendBaseUrl() returning '' makes
+    // buildAuthorizationRequest fail (by design) with OIDC_BAD_CONFIG.
+    process.env.FRONTEND_URL = 'http://localhost:5199';
+    ({ db, cleanup } = await bootCrmDb());
+
+    idp = new MockOidcProvider();
+    const issuer = await idp.start();
+
+    // Require AFTER bootCrmDb so services share this db instance.
+    oidcService = require('../../src/services/oidcService');
+    await oidcService.saveOidcSettings({
+      oidc_enabled: true,
+      oidc_issuer_url: issuer,
+      oidc_client_id: idp.clientId,
+      oidc_client_secret: idp.clientSecret,
+      oidc_autoprovision: true,
+      oidc_default_role: 'viewer',
+    });
+
+    const authRouter = require('../../src/routes/auth');
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/auth', authRouter);
+  }, 120000);
+
+  afterAll(async () => {
+    if (idp) await idp.stop();
+    if (cleanup) await cleanup();
+  });
+
+  /** Drive login → IdP → callback like a browser; returns the callback response. */
+  async function ssoRoundTrip({ mutateState } = {}) {
+    const loginRes = await request(app).get('/api/auth/admin/sso/login').expect(302);
+    const idpUrl = loginRes.headers.location;
+    expect(idpUrl.startsWith(idp.issuer)).toBe(true);
+
+    let stateCookie = (loginRes.headers['set-cookie'] || [])
+      .find((c) => c.startsWith('oidc_state='));
+    expect(stateCookie).toBeTruthy();
+    stateCookie = stateCookie.split(';')[0];
+    if (mutateState === 'drop') stateCookie = null;
+    if (mutateState === 'forge') {
+      stateCookie = `oidc_state=${jwt.sign({ type: 'oidc_state', s: 'x', n: 'y', cv: 'z' }, 'wrong-secret', { issuer: 'picpeak-auth' })}`;
+    }
+
+    // "Browser" follows the redirect to the IdP, which instantly bounces back.
+    const idpRes = await fetch(idpUrl, { redirect: 'manual' });
+    expect(idpRes.status).toBe(302);
+    const back = new URL(idpRes.headers.get('location'));
+
+    let cb = request(app).get(`${back.pathname}?${back.searchParams.toString()}`);
+    if (stateCookie) cb = cb.set('Cookie', stateCookie);
+    return cb.expect(302);
+  }
+
+  it('JIT-provisions an unknown user and establishes an admin session', async () => {
+    idp.setNextUser({ sub: 'sub-jit-1', email: 'jit@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    const adminCookie = (res.headers['set-cookie'] || []).find((c) => c.startsWith('admin_token='));
+    expect(adminCookie).toBeTruthy();
+
+    const row = await db('admin_users').where({ email: 'jit@example.com' }).first();
+    expect(row).toBeTruthy();
+    expect(row.auth_provider).toBe('oidc');
+    expect(row.external_subject).toBe('sub-jit-1');
+
+    const role = await db('roles').where('id', row.role_id).first();
+    expect(role.name).toBe('viewer');
+
+    // The session JWT must be a normal admin token.
+    const token = adminCookie.split(';')[0].replace('admin_token=', '');
+    const decoded = jwt.verify(decodeURIComponent(token), process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
+    expect(decoded.type).toBe('admin');
+    expect(decoded.id).toBe(row.id);
+    agentCookies.jitAdminId = row.id;
+  });
+
+  it('matches repeat logins by sub even when the email changed at the IdP', async () => {
+    idp.setNextUser({ sub: 'sub-jit-1', email: 'renamed@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+
+    // No second row — resolved via external_subject.
+    expect(await db('admin_users').where({ email: 'renamed@example.com' }).first()).toBeFalsy();
+    const byId = await db('admin_users').where({ id: agentCookies.jitAdminId }).first();
+    expect(byId.external_subject).toBe('sub-jit-1');
+  });
+
+  it('links an existing local admin one-time via VERIFIED email and stamps the sub', async () => {
+    const role = await db('roles').where({ name: 'admin' }).first();
+    const [localId] = await db('admin_users').insert({
+      username: 'local-admin',
+      email: 'local@example.com',
+      password_hash: await bcrypt.hash('LocalPass123', 4),
+      role_id: role.id,
+      is_active: 1,
+      auth_provider: 'local',
+      created_at: new Date(),
+      updated_at: new Date(),
+    }).returning('id').then((r) => [r[0]?.id || r[0]]);
+
+    idp.setNextUser({ sub: 'sub-local-1', email: 'local@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+
+    const row = await db('admin_users').where({ id: localId }).first();
+    expect(row.external_subject).toBe('sub-local-1');
+    expect(row.auth_provider).toBe('local'); // password keeps working
+  });
+
+  it('does NOT link by unverified email — provisions a separate account instead', async () => {
+    const role = await db('roles').where({ name: 'admin' }).first();
+    await db('admin_users').insert({
+      username: 'victim-admin',
+      email: 'victim@example.com',
+      password_hash: await bcrypt.hash('VictimPass123', 4),
+      role_id: role.id,
+      is_active: 1,
+      auth_provider: 'local',
+      created_at: new Date(),
+      updated_at: new Date(),
+    });
+
+    idp.setNextUser({ sub: 'sub-attacker', email: 'victim@example.com', email_verified: false });
+    // JIT would need this email but the victim row owns it (unique) — the
+    // insert fails and the flow must land on an error, never on the
+    // victim's session.
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toMatch(/sso_error=/);
+
+    const victim = await db('admin_users').where({ email: 'victim@example.com' }).first();
+    expect(victim.external_subject).toBeNull();
+  });
+
+  it('refuses a deactivated admin with sso_error=inactive', async () => {
+    await db('admin_users').where({ id: agentCookies.jitAdminId }).update({ is_active: 0 });
+    idp.setNextUser({ sub: 'sub-jit-1', email: 'renamed@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/login?sso_error=inactive');
+    await db('admin_users').where({ id: agentCookies.jitAdminId }).update({ is_active: 1 });
+  });
+
+  it('rejects a callback without the state cookie', async () => {
+    const res = await ssoRoundTrip({ mutateState: 'drop' });
+    expect(res.headers.location).toBe('http://localhost:5199/admin/login?sso_error=state');
+  });
+
+  it('rejects a forged state cookie (wrong signing key)', async () => {
+    const res = await ssoRoundTrip({ mutateState: 'forge' });
+    expect(res.headers.location).toBe('http://localhost:5199/admin/login?sso_error=state');
+  });
+
+  it('rejects an ID token whose nonce does not match', async () => {
+    idp.tamperNonce = true;
+    idp.setNextUser({ sub: 'sub-nonce', email: 'nonce@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+    idp.tamperNonce = false;
+    expect(res.headers.location).toBe('http://localhost:5199/admin/login?sso_error=idp');
+    expect(await db('admin_users').where({ email: 'nonce@example.com' }).first()).toBeFalsy();
+  });
+
+  it('blocks JIT with sso_error=not_provisioned when autoprovision is off', async () => {
+    await oidcService.saveOidcSettings({ oidc_autoprovision: false });
+    idp.setNextUser({ sub: 'sub-new-user', email: 'new@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+    expect(res.headers.location).toBe('http://localhost:5199/admin/login?sso_error=not_provisioned');
+    expect(await db('admin_users').where({ email: 'new@example.com' }).first()).toBeFalsy();
+    await oidcService.saveOidcSettings({ oidc_autoprovision: true });
+  });
+
+  it('stores the client secret encrypted and survives a config round-trip', async () => {
+    const row = await db('app_settings').where({ setting_key: 'oidc_client_secret' }).first();
+    const stored = JSON.parse(row.setting_value);
+    expect(stored).not.toContain(idp.clientSecret);
+    expect(oidcService.decryptSecret(stored)).toBe(idp.clientSecret);
+
+    const cfg = await oidcService.getOidcConfig();
+    expect(cfg.clientSecret).toBe(idp.clientSecret);
+  });
+
+  it('refuses local password login for OIDC-owned accounts', async () => {
+    // Give the JIT admin a KNOWN password hash directly in the DB — the
+    // auth_provider check must reject the login even with valid credentials
+    // (otherwise a password reset would mint an IdP-bypassing local login).
+    await db('admin_users').where({ id: agentCookies.jitAdminId }).update({
+      password_hash: await bcrypt.hash('KnownPass123', 4),
+    });
+    const row = await db('admin_users').where({ id: agentCookies.jitAdminId }).first();
+
+    const res = await request(app)
+      .post('/api/auth/admin/login')
+      .send({ username: row.email, password: 'KnownPass123' });
+    expect(res.status).toBe(401);
+  });
+
+  it('returns 404 from /sso/login when SSO is disabled', async () => {
+    await oidcService.saveOidcSettings({ oidc_enabled: false });
+    await request(app).get('/api/auth/admin/sso/login').expect(404);
+    await oidcService.saveOidcSettings({ oidc_enabled: true });
+  });
+
+  it('merges email from the UserInfo endpoint when the ID token omits it', async () => {
+    idp.emailViaUserinfoOnly = true;
+    idp.setNextUser({ sub: 'sub-userinfo', email: 'userinfo@example.com', email_verified: true });
+    const res = await ssoRoundTrip();
+    idp.emailViaUserinfoOnly = false;
+
+    expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+    const row = await db('admin_users').where({ email: 'userinfo@example.com' }).first();
+    expect(row).toBeTruthy();
+    expect(row.external_subject).toBe('sub-userinfo');
+  });
+
+  it('binds identities per ISSUER — a sub collision on a new IdP must not inherit the old account', async () => {
+    // The JIT admin from the first test is bound to (issuer A, 'sub-jit-1').
+    const boundAdmin = await db('admin_users').where({ id: agentCookies.jitAdminId }).first();
+    expect(boundAdmin.external_issuer).toBe(idp.issuer);
+
+    // Same sub, DIFFERENT issuer: a second IdP the instance switches to.
+    const idp2 = new MockOidcProvider();
+    await idp2.start();
+    try {
+      await oidcService.saveOidcSettings({
+        oidc_issuer_url: idp2.issuer,
+        oidc_client_id: idp2.clientId,
+        oidc_client_secret: idp2.clientSecret,
+      });
+      idp2.setNextUser({ sub: 'sub-jit-1', email: 'colliding@example.com', email_verified: true });
+
+      const loginRes = await request(app).get('/api/auth/admin/sso/login').expect(302);
+      const stateCookie = (loginRes.headers['set-cookie'] || [])
+        .find((c) => c.startsWith('oidc_state=')).split(';')[0];
+      const idpRes = await fetch(loginRes.headers.location, { redirect: 'manual' });
+      const back = new URL(idpRes.headers.get('location'));
+      const res = await request(app)
+        .get(`${back.pathname}?${back.searchParams.toString()}`)
+        .set('Cookie', stateCookie)
+        .expect(302);
+      expect(res.headers.location).toBe('http://localhost:5199/admin/dashboard');
+
+      // A NEW row bound to issuer B — the issuer-A admin is untouched and
+      // its role was not inherited.
+      const collider = await db('admin_users').where({ email: 'colliding@example.com' }).first();
+      expect(collider).toBeTruthy();
+      expect(collider.id).not.toBe(agentCookies.jitAdminId);
+      expect(collider.external_issuer).toBe(idp2.issuer);
+      const original = await db('admin_users').where({ id: agentCookies.jitAdminId }).first();
+      expect(original.external_issuer).toBe(idp.issuer);
+    } finally {
+      await idp2.stop();
+      await oidcService.saveOidcSettings({
+        oidc_issuer_url: idp.issuer,
+        oidc_client_id: idp.clientId,
+        oidc_client_secret: idp.clientSecret,
+      });
+    }
+  });
+});

backend/__tests__/integration/picpeakRestorePg.test.js

@@ -0,0 +1,190 @@
+/**
+ * PostgreSQL integration tests for the .picpeak restore robustness fixes.
+ * Gated: runs only when PICPEAK_PG_TEST_URL points at a throwaway Postgres DB,
+ * e.g.
+ *   PICPEAK_PG_TEST_URL="postgres://picpeak:picpeak_secure_pass_2024@127.0.0.1:7102/picpeak_restore_test" \
+ *     npx jest __tests__/integration/picpeakRestorePg.test.js
+ *
+ * Validates the Postgres-specific paths that SQLite can't exercise: identity
+ * sequences left stale by explicit-id inserts, pg_get_serial_sequence raising on
+ * id-less tables, reinject/role-recreate explicit-id inserts, and FK integrity.
+ */
+const knex = require('knex');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PG_URL = process.env.PICPEAK_PG_TEST_URL;
+const maybe = PG_URL ? describe : describe.skip;
+
+maybe('picpeak restore on Postgres', () => {
+  let pgDb;
+  let svc;
+
+  beforeAll(async () => {
+    pgDb = knex({ client: 'pg', connection: PG_URL });
+
+    await pgDb.raw('DROP TABLE IF EXISTS role_permissions, events, admin_users, roles, permissions, app_settings CASCADE');
+    await pgDb.schema.createTable('roles', (t) => {
+      t.increments('id');
+      t.string('name', 50).notNullable().unique();
+      t.string('display_name', 100);
+      t.integer('priority').defaultTo(0);
+      t.boolean('is_system').defaultTo(false);
+    });
+    await pgDb.schema.createTable('permissions', (t) => {
+      t.increments('id');
+      t.string('name', 100).notNullable().unique();
+      t.string('display_name', 150);
+      t.string('category', 50);
+    });
+    await pgDb.schema.createTable('role_permissions', (t) => {
+      t.integer('role_id').notNullable().references('id').inTable('roles').onDelete('CASCADE');
+      t.integer('permission_id').notNullable().references('id').inTable('permissions').onDelete('CASCADE');
+      t.primary(['role_id', 'permission_id']);
+    });
+    await pgDb.schema.createTable('admin_users', (t) => {
+      t.increments('id');
+      t.string('username').notNullable().unique();
+      t.string('email').notNullable().unique();
+      t.string('password_hash');
+      t.boolean('is_active').defaultTo(true);
+      t.boolean('must_change_password').defaultTo(false);
+      t.integer('role_id').references('id').inTable('roles').onDelete('SET NULL');
+      t.integer('created_by').references('id').inTable('admin_users').onDelete('SET NULL');
+      t.boolean('two_factor_enabled').defaultTo(false);
+      t.string('two_factor_secret');
+      t.text('two_factor_recovery_codes');
+    });
+    await pgDb.schema.createTable('events', (t) => {
+      t.increments('id');
+      t.string('slug');
+      t.integer('created_by').references('id').inTable('admin_users').onDelete('SET NULL');
+    });
+    await pgDb.schema.createTable('app_settings', (t) => {
+      t.increments('id');
+      t.string('setting_key').notNullable().unique();
+      t.json('setting_value');
+      t.string('setting_type');
+      t.timestamp('updated_at').defaultTo(pgDb.fn.now());
+    });
+
+    jest.resetModules();
+    jest.doMock('../../knexfile', () => ({ client: 'pg' }));
+    jest.doMock('../../src/database/db', () => ({ db: pgDb }));
+    svc = require('../../src/services/picpeakImportService');
+  });
+
+  afterAll(async () => {
+    jest.dontMock('../../src/database/db');
+    jest.dontMock('../../knexfile');
+    if (pgDb) await pgDb.destroy();
+  });
+
+  beforeEach(async () => {
+    await pgDb('role_permissions').del();
+    await pgDb('events').del();
+    await pgDb('admin_users').del();
+    await pgDb('roles').del();
+    await pgDb('permissions').del();
+  });
+
+  test('resyncSequences fast-forwards stale sequences and skips id-less tables', async () => {
+    // Simulate a restore: explicit-id inserts leave the sequence at 1.
+    await pgDb('roles').insert([{ id: 5, name: 'super_admin', display_name: 'SA' }]);
+    await pgDb('admin_users').insert([{ id: 9, username: 'a', email: 'a@x.io', password_hash: 'h' }]);
+    await pgDb('permissions').insert([{ id: 3, name: 'events.create', display_name: 'C', category: 'events' }]);
+    await pgDb('role_permissions').insert([{ role_id: 5, permission_id: 3 }]); // id-less table
+
+    // Must not throw on role_permissions (no `id` column → pg_get_serial_sequence raises unguarded).
+    await expect(svc.resyncSequences(['roles', 'admin_users', 'permissions', 'role_permissions'])).resolves.toBeUndefined();
+
+    // Natural inserts (no explicit id) now avoid the restored ids.
+    const [adminId] = await pgDb('admin_users').insert({ username: 'b', email: 'b@x.io', password_hash: 'h' }).returning('id');
+    expect(Number(adminId.id || adminId)).toBe(10); // max(9)+1, no duplicate-key error
+    const [roleId] = await pgDb('roles').insert({ name: 'editor', display_name: 'Ed' }).returning('id');
+    expect(Number(roleId.id || roleId)).toBe(6);
+  });
+
+  test('reinjectCurrentAdmin insert branch works with a stale sequence (explicit max+1)', async () => {
+    await pgDb('admin_users').insert({ id: 9, username: 'backup', email: 'backup@x.io', password_hash: 'h' });
+    const operator = { id: 1, username: 'admin', email: 'op@x.io', password_hash: 'OP', is_active: true, created_by: 42 };
+
+    await pgDb.transaction((trx) => svc.reinjectCurrentAdmin(trx, operator));
+
+    const op = await pgDb('admin_users').where({ email: 'op@x.io' }).first();
+    expect(op.id).toBe(10);            // max(9)+1
+    expect(op.password_hash).toBe('OP');
+    expect(op.created_by).toBeNull();  // self-ref FK nulled so the insert can't dangle
+  });
+
+  test('preserveOperatorRole re-creates a missing role on Postgres and keeps FK integrity', async () => {
+    await pgDb('permissions').insert([{ id: 3, name: 'events.create', display_name: 'C', category: 'events' }]);
+    await pgDb('roles').insert([{ id: 2, name: 'viewer', display_name: 'V' }]);
+    await pgDb('admin_users').insert({ id: 1, username: 'admin', email: 'op@x.io', password_hash: 'h', role_id: null });
+    const snapshot = { role: { name: 'super_admin', display_name: 'SA', priority: 100, is_system: true }, permissions: ['events.create', 'missing.perm'] };
+
+    await pgDb.transaction((trx) => svc.preserveOperatorRole(trx, 1, snapshot));
+    await svc.resyncSequences(['roles']); // post-commit, mirrors importFromPicpeak
+
+    const role = await pgDb('roles').where({ name: 'super_admin' }).first();
+    expect(role).toBeTruthy();
+    const op = await pgDb('admin_users').where({ id: 1 }).first();
+    expect(op.role_id).toBe(role.id);  // FK valid, operator not downgraded
+    const grants = await pgDb('role_permissions').where({ role_id: role.id }).pluck('permission_id');
+    expect(grants).toEqual([3]);        // existing perm granted, missing.perm skipped
+  });
+
+  test('full replaceAllTables: cross-instance backup preserves the operator, role, FKs, and sequences', async () => {
+    // A backup from ANOTHER instance: omits the operator's email AND their
+    // super_admin role; uses explicit ids that leave sequences stale.
+    const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-pgtest-'));
+    const dataDir = path.join(staging, 'data');
+    fs.mkdirSync(dataDir);
+    const write = (t, rows) => fs.writeFileSync(path.join(dataDir, `${t}.ndjson`), rows.map((r) => JSON.stringify(r)).join('\n'));
+    write('roles', [{ id: 5, name: 'admin', display_name: 'Admin', priority: 50, is_system: true }]);
+    write('permissions', [{ id: 3, name: 'events.create', display_name: 'C', category: 'events' }]);
+    write('role_permissions', [{ role_id: 5, permission_id: 3 }]);
+    write('admin_users', [{ id: 9, username: 'backupadmin', email: 'backup@x.io', password_hash: 'h', role_id: 5, is_active: true }]);
+    write('events', [{ id: 2, slug: 'restored-ev', created_by: 9 }]);
+
+    const operator = { id: 1, username: 'admin', email: 'op@x.io', password_hash: 'OP', is_active: true, role_id: 999, created_by: null };
+    const roleSnapshot = { role: { name: 'super_admin', display_name: 'Super Admin', priority: 100, is_system: true }, permissions: ['events.create'] };
+    const tables = ['roles', 'permissions', 'role_permissions', 'admin_users', 'events'];
+
+    // replaceAllTables isn't exported, so drive its exact transaction sequence
+    // (suspend FKs, wipe, batchInsert, reinject, preserve role) through the
+    // exported units against real Postgres.
+    const importSvc = svc;
+    await pgDb.transaction(async (trx) => {
+      await trx.raw('SET session_replication_role = \'replica\'');
+      for (const t of tables) await trx(t).del();
+      for (const t of tables) {
+        const rows = fs.readFileSync(path.join(dataDir, `${t}.ndjson`), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+        if (rows.length) await trx.batchInsert(t, rows, 100);
+      }
+      const opId = await importSvc.reinjectCurrentAdmin(trx, operator);
+      await importSvc.preserveOperatorRole(trx, opId, roleSnapshot);
+      await trx.raw('SET session_replication_role = \'origin\'');
+    });
+    await importSvc.resyncSequences(tables);
+
+    // Operator preserved (inserted, since email absent from backup).
+    const op = await pgDb('admin_users').where({ email: 'op@x.io' }).first();
+    expect(op).toBeTruthy();
+    expect(op.password_hash).toBe('OP');
+    // super_admin role re-created and the operator bound to it.
+    const sa = await pgDb('roles').where({ name: 'super_admin' }).first();
+    expect(sa).toBeTruthy();
+    expect(op.role_id).toBe(sa.id);
+    expect(await pgDb('role_permissions').where({ role_id: sa.id }).pluck('permission_id')).toEqual([3]);
+    // Restored event's created_by FK to the backup admin still valid.
+    const ev = await pgDb('events').where({ slug: 'restored-ev' }).first();
+    expect(ev.created_by).toBe(9);
+    // Sequences resynced → natural inserts don't collide.
+    const [newAdmin] = await pgDb('admin_users').insert({ username: 'fresh', email: 'fresh@x.io', password_hash: 'h' }).returning('id');
+    expect(Number(newAdmin.id || newAdmin)).toBeGreaterThan(op.id);
+
+    fs.rmSync(staging, { recursive: true, force: true });
+  });
+});

backend/__tests__/integration/rebillProofAndPanel.test.js

@@ -0,0 +1,256 @@
+/**
+ * Issue #866 — the createInvoice-free halves of the re-bill proof + CRM panel
+ * feature, against a real SQLite schema:
+ *
+ *   • listCustomerRebills — status DERIVED from the linked invoice lifecycle
+ *     (open / sent / paid; a cancelled/Storno'd cover drops back to open) plus
+ *     cost-vs-rebilled math and mode.
+ *   • collectRebillProofAttachments — the Send-dialog per-file selection, the
+ *     all-or-none default resolution (per-customer override else global), the
+ *     Beleg-<inv#> filename (suffix only when >1), and the missing-file marker.
+ *
+ * The invoice-MINTING paths (billCombinedForCustomer / billPendingRebills) call
+ * createInvoice inside a db.transaction, which deadlocks on the SQLite harness
+ * (global-db sequence write vs. held write lock) — same limitation the sibling
+ * incomingInvoiceRebill.test.js documents. They're covered by the existing
+ * billPendingRebills / billUnbilledEntries suites; here we hand-craft billed
+ * state instead.
+ */
+const fs = require('fs');
+const path = require('path');
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+jest.setTimeout(120000);
+
+describe('#866 re-bill proof attachment + CRM panel', () => {
+  let db;
+  let cleanup;
+  let adminId;
+  let expenseService;
+  let rebillProofs;
+  let flagCache;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    const dbModule = require('../../src/database/db');
+    dbModule.logActivity = async () => {};
+    ({ adminId } = await seedMinimal(db));
+    expenseService = require('../../src/services/expenseService');
+    rebillProofs = require('../../src/services/invoice/rebillProofs');
+    flagCache = require('../../src/middleware/requireFeatureFlag');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  const unwrapId = (ins) => (typeof ins[0] === 'object' ? ins[0].id : ins[0]);
+  let seq = 0;
+
+  async function makeCustomer(overrides = {}) {
+    seq += 1;
+    const ins = await db('customer_accounts').insert({
+      email: `c866-${seq}@example.com`,
+      display_name: `C866 ${seq}`,
+      password_hash: 'x',
+      preferred_language: 'de',
+      is_active: 1,
+      billing_cadence: 'per_event',
+      created_at: new Date(),
+      ...overrides,
+    }).returning('id');
+    return unwrapId(ins);
+  }
+
+  async function makeDoc(customerId, overrides = {}) {
+    const ins = await db('inbound_documents').insert({
+      source: 'upload', status: 'categorized', parse_status: 'parsed', parse_method: 'none',
+      supplier_name: 'ACME AG', currency: 'CHF', total_amount_minor: 10000,
+      invoice_date: '2026-06-01', disposition: 'rebill', customer_account_id: customerId,
+      created_at: new Date(), updated_at: new Date(),
+      ...overrides,
+    }).returning('id');
+    return unwrapId(ins);
+  }
+
+  async function makeInvoice(customerId, status, number) {
+    const ins = await db('invoices').insert({
+      invoice_number: number,
+      customer_account_id: customerId,
+      status,
+      currency: 'CHF',
+      issue_date: '2026-06-01', due_date: '2026-07-01',
+      vat_rate: 0, net_amount_minor: 10000, vat_amount_minor: 0, total_amount_minor: 10000,
+      created_at: new Date(), updated_at: new Date(),
+    }).returning('id');
+    return unwrapId(ins);
+  }
+
+  describe('listCustomerRebills', () => {
+    it('derives open / sent / paid and open→cost==rebilled for passthrough, +markup for rebill', async () => {
+      const customerId = await makeCustomer();
+
+      // Open re-bill (10% markup): rebilled = 11000.
+      await makeDoc(customerId, { total_amount_minor: 10000, markup_type: 'percent', markup_percent: 10 });
+      // Open passthrough: no markup, rebilled == cost.
+      await makeDoc(customerId, { disposition: 'durchlaufend', total_amount_minor: 5000, markup_type: 'none' });
+      // Sent (on a 'sent' invoice).
+      const sentInv = await makeInvoice(customerId, 'sent', 'R-2026-0001');
+      await makeDoc(customerId, { total_amount_minor: 8000, markup_type: 'none', billed_invoice_id: sentInv });
+      // Paid.
+      const paidInv = await makeInvoice(customerId, 'paid', 'R-2026-0002');
+      await makeDoc(customerId, { total_amount_minor: 8000, markup_type: 'none', billed_invoice_id: paidInv });
+      // Cancelled cover → drops back to 'open', no invoice link surfaced.
+      const cancInv = await makeInvoice(customerId, 'cancelled', 'R-2026-0003');
+      await makeDoc(customerId, { total_amount_minor: 8000, markup_type: 'none', billed_invoice_id: cancInv });
+
+      const items = await expenseService.listCustomerRebills(customerId);
+      const byStatus = (s) => items.filter((r) => r.status === s);
+
+      expect(items).toHaveLength(5);
+      expect(byStatus('open')).toHaveLength(3); // 2 genuinely-open + 1 cancelled-cover
+      expect(byStatus('sent')).toHaveLength(1);
+      expect(byStatus('paid')).toHaveLength(1);
+
+      const rebill = items.find((r) => r.mode === 'rebill' && r.costMinor === 10000);
+      expect(rebill.rebilledMinor).toBe(11000);
+      const passthrough = items.find((r) => r.mode === 'passthrough');
+      expect(passthrough.rebilledMinor).toBe(passthrough.costMinor);
+
+      const sent = byStatus('sent')[0];
+      expect(sent.invoiceNumber).toBe('R-2026-0001');
+      expect(sent.invoiceId).toBe(sentInv);
+
+      const cancelledCover = items.find((r) => r.status === 'open' && r.invoiceNumber === null && r.costMinor === 8000);
+      expect(cancelledCover).toBeDefined(); // cancelled cover isn't shown as a live invoice link
+    });
+  });
+
+  describe('storno releases the re-bill linkage (#866 review)', () => {
+    it("clears billed_invoice_id so a Storno'd cover returns to the billable pool", async () => {
+      const invoiceService = require('../../src/services/invoiceService');
+      const customerId = await makeCustomer();
+      const invId = await makeInvoice(customerId, 'sent', 'R-2026-9000');
+      const lineIns = await db('invoice_line_items').insert({
+        invoice_id: invId, position: 1, quantity: 1, description: 'Rebill',
+        unit_price_minor: 8000, discount_percent: 0, line_total_minor: 8000,
+      }).returning('id');
+      const lineId = unwrapId(lineIns);
+      const docId = await makeDoc(customerId, {
+        total_amount_minor: 8000, markup_type: 'none', billed_invoice_id: invId, billed_invoice_line_item_id: lineId,
+      });
+
+      // Storno claims a fresh number from document_sequences; the other tests
+      // seed explicit R-2026-000x numbers without advancing it, so push the
+      // counter past them to avoid a number collision (a test artifact — real
+      // invoices always claim through the sequence).
+      await db('document_sequences').insert({ kind: 'invoice', year: 2026, current_value: 9000, created_at: new Date(), updated_at: new Date() })
+        .onConflict(['kind', 'year']).ignore();
+      await db('document_sequences').where({ kind: 'invoice', year: 2026 }).update({ current_value: 9000 });
+
+      // Storno the covering invoice (the issued-cancel path).
+      await db.transaction(async (trx) => invoiceService.createStorno(invId, adminId, trx));
+
+      const doc = await db('inbound_documents').where({ id: docId }).first();
+      expect(doc.billed_invoice_id).toBeNull();
+      expect(doc.billed_invoice_line_item_id).toBeNull();
+
+      // It now surfaces as a genuinely-open item AND the pending pool picks it up.
+      const items = await expenseService.listCustomerRebills(customerId);
+      const row = items.find((r) => r.id === docId);
+      expect(row.status).toBe('open');
+      expect(row.invoiceId).toBeNull();
+      const pending = await db('inbound_documents')
+        .where({ customer_account_id: customerId }).whereNull('billed_invoice_id')
+        .whereIn('disposition', ['rebill', 'durchlaufend']).where('status', 'categorized');
+      expect(pending.map((p) => p.id)).toContain(docId);
+    });
+  });
+
+  describe('collectRebillProofAttachments', () => {
+    const businessDocs = () => path.join(process.env.STORAGE_PATH, 'business-docs', 'inbound', '2026');
+
+    async function enableIncoming() {
+      const existing = await db('feature_flags').where({ key: 'incomingInvoices' }).first();
+      if (existing) await db('feature_flags').where({ key: 'incomingInvoices' }).update({ value: 1 });
+      else await db('feature_flags').insert({ key: 'incomingInvoices', value: 1 });
+      flagCache.invalidateFeatureFlagCache();
+    }
+
+    function writeProof(name) {
+      fs.mkdirSync(businessDocs(), { recursive: true });
+      const p = path.join(businessDocs(), name);
+      fs.writeFileSync(p, '%PDF-1.4\n% test proof\n');
+      return p;
+    }
+
+    it('honours explicit selection, names Beleg-<inv#>, and marks a missing file', async () => {
+      await enableIncoming();
+      const customerId = await makeCustomer();
+      const invId = await makeInvoice(customerId, 'scheduled', 'R-2026-1000');
+      const invoice = await db('invoices').where({ id: invId }).first();
+
+      const good1 = await makeDoc(customerId, { billed_invoice_id: invId, file_path: writeProof('p1.pdf') });
+      const good2 = await makeDoc(customerId, { billed_invoice_id: invId, file_path: writeProof('p2.pdf') });
+      const missing = await makeDoc(customerId, { billed_invoice_id: invId, file_path: path.join(businessDocs(), 'nope.pdf') });
+
+      // Select the two good proofs → two attachments, suffixed because >1.
+      const both = await rebillProofs.collectRebillProofAttachments(invoice, null, [good1, good2]);
+      expect(both.map((a) => a.filename).sort()).toEqual(['Beleg-R-2026-1000-1.pdf', 'Beleg-R-2026-1000-2.pdf']);
+
+      // Select exactly one → single, unsuffixed.
+      const one = await rebillProofs.collectRebillProofAttachments(invoice, null, [good1]);
+      expect(one).toHaveLength(1);
+      expect(one[0].filename).toBe('Beleg-R-2026-1000.pdf');
+
+      // Select the missing-file doc → no attachment, but a marker is persisted.
+      const none = await rebillProofs.collectRebillProofAttachments(invoice, null, [missing]);
+      expect(none).toHaveLength(0);
+      const markerRow = await db('inbound_documents').where({ id: missing }).first('proof_attach_error');
+      expect(markerRow.proof_attach_error).toBeTruthy();
+      // A successful attach clears any prior marker.
+      await rebillProofs.collectRebillProofAttachments(invoice, null, [good1]);
+      const cleared = await db('inbound_documents').where({ id: good1 }).first('proof_attach_error');
+      expect(cleared.proof_attach_error).toBeNull();
+    });
+
+    it('resolves the all-or-none default from the per-customer override then global', async () => {
+      await enableIncoming();
+      const customerId = await makeCustomer();
+      const invId = await makeInvoice(customerId, 'scheduled', 'R-2026-2000');
+      const invoice = await db('invoices').where({ id: invId }).first();
+      await makeDoc(customerId, { billed_invoice_id: invId, file_path: writeProof('d1.pdf') });
+
+      // Global default off, no override → none.
+      const off = await rebillProofs.collectRebillProofAttachments(invoice, { rebill_attach_proof: null }, undefined);
+      expect(off).toHaveLength(0);
+
+      // Per-customer override ON → all, regardless of the (off) global.
+      const on = await rebillProofs.collectRebillProofAttachments(invoice, { rebill_attach_proof: true }, undefined);
+      expect(on).toHaveLength(1);
+
+      // Global ON (no override) → all.
+      await db('app_settings').insert({ setting_key: 'accounting_rebill_attach_proof', setting_value: JSON.stringify(true), setting_type: 'accounting' });
+      const globalOn = await rebillProofs.collectRebillProofAttachments(invoice, { rebill_attach_proof: null }, undefined);
+      expect(globalOn).toHaveLength(1);
+      // Override OFF beats global ON.
+      const overrideOff = await rebillProofs.collectRebillProofAttachments(invoice, { rebill_attach_proof: false }, undefined);
+      expect(overrideOff).toHaveLength(0);
+    });
+
+    it('attaches nothing when the incoming-invoices flag is off', async () => {
+      const existing = await db('feature_flags').where({ key: 'incomingInvoices' }).first();
+      if (existing) await db('feature_flags').where({ key: 'incomingInvoices' }).update({ value: 0 });
+      else await db('feature_flags').insert({ key: 'incomingInvoices', value: 0 });
+      flagCache.invalidateFeatureFlagCache();
+
+      const customerId = await makeCustomer();
+      const invId = await makeInvoice(customerId, 'scheduled', 'R-2026-3000');
+      const invoice = await db('invoices').where({ id: invId }).first();
+      const doc = await makeDoc(customerId, { billed_invoice_id: invId, file_path: writeProof('f1.pdf') });
+
+      const res = await rebillProofs.collectRebillProofAttachments(invoice, { rebill_attach_proof: true }, [doc]);
+      expect(res).toHaveLength(0);
+    });
+  });
+});

backend/__tests__/integration/regenerateThumbnailsScript.test.js

@@ -1,260 +0,0 @@
-/**
- * scripts/regenerate-thumbnails.js against external photos (#1148).
- *
- * The same defect #1129 fixed in the admin route, still standing in the CLI
- * fallback: the script resolved every source as
- * `storage/events/active/<photo.path>` and fs.access'd it. External and
- * reference rows do not live there — their originals sit under
- * `events.external_path` — so every one failed the check and was counted as an
- * error. On an install where all photos are external the script did nothing at
- * all, while reporting one error per photo.
- *
- * Driven against a REAL file on a REAL external mount with the real
- * imageProcessor, not a mock: the whole point is that the source resolves off
- * the mount, and a mocked ensureThumbnail would assert nothing about that.
- *
- * Responsive tiers (#1095/#1109) do not exist on this branch, so the tier
- * backfill in the main twin has nothing to port. Everything else does.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const sharp = require('sharp');
-const { execFile } = require('child_process');
-
-describe('regenerate-thumbnails script (#1148)', () => {
-  let tmpDir; let db; let cleanup; let regenerateThumbnails;
-  let eventId; let externalPhotoId; let videoPhotoId; let watcherVideoId; let repairPhotoId;
-  let vanishingPhotoId;
-  let externalRoot;
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-regen-script-'));
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'test.db');
-    process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-    // External sources are sandboxed under EXTERNAL_MEDIA_ROOT. Rows carry a
-    // path relative to that root (#1163), so the 'wedding/' prefix on each
-    // external_relpath below is the event folder, not decoration.
-    process.env.EXTERNAL_MEDIA_ROOT = path.join(tmpDir, 'media');
-    externalRoot = path.join(process.env.EXTERNAL_MEDIA_ROOT, 'wedding');
-
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    await fs.promises.mkdir(process.env.STORAGE_PATH, { recursive: true });
-    await fs.promises.mkdir(externalRoot, { recursive: true });
-
-    jest.resetModules();
-    ({ db, cleanup } = await require('./helpers/crmDb').bootCrmDb());
-
-    // A real image on the external mount — never under events/active.
-    await sharp({
-      create: { width: 1200, height: 800, channels: 3, background: { r: 10, g: 90, b: 160 } },
-    }).jpeg().toFile(path.join(externalRoot, 'shot.jpg'));
-
-    const [ev] = await db('events').insert({
-      slug: 'regen-script-event',
-      event_type: 'wedding',
-      event_name: 'Regen Script',
-      event_date: '2026-08-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: '/gallery/regen-script-event/share',
-      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
-      source_mode: 'reference',
-      external_path: 'wedding',
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    eventId = typeof ev === 'object' ? ev.id : ev;
-
-    const [p] = await db('photos').insert({
-      event_id: eventId,
-      filename: 'shot.jpg',
-      // `path` is what the old script joined onto events/active. Left
-      // populated on purpose: the fix must ignore it for an external row.
-      path: 'regen-script-event/shot.jpg',
-      type: 'individual',
-      source_origin: 'external',
-      external_relpath: 'wedding/shot.jpg',
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    externalPhotoId = typeof p === 'object' ? p.id : p;
-
-    const [v] = await db('photos').insert({
-      event_id: eventId,
-      filename: 'clip.mp4',
-      path: 'regen-script-event/clip.mp4',
-      type: 'individual',
-      media_type: 'video',
-      mime_type: 'video/mp4',
-      source_origin: 'external',
-      external_relpath: 'wedding/clip.mp4',
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    videoPhotoId = typeof v === 'object' ? v.id : v;
-
-    // How fileWatcher.processNewPhoto actually writes a video: `type` and
-    // `mime_type` set, media_type left to its 'image' default. A media_type-only
-    // filter lets this through and hands the container to Sharp.
-    //
-    // The file has to EXIST, otherwise the row fails resolution and looks
-    // skipped for the wrong reason — the bug is Sharp being handed a video, not
-    // a missing source. Real MP4 header bytes, no image in sight.
-    await fs.promises.writeFile(
-      path.join(externalRoot, 'watched.mp4'),
-      Buffer.from('00000018667479706d70343200000000', 'hex')
-    );
-    const [wv] = await db('photos').insert({
-      event_id: eventId,
-      filename: 'watched.mp4',
-      path: 'regen-script-event/watched.mp4',
-      type: 'video',
-      mime_type: 'video/mp4',
-      source_origin: 'external',
-      external_relpath: 'wedding/watched.mp4',
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    watcherVideoId = typeof wv === 'object' ? wv.id : wv;
-    expect((await db('photos').where('id', watcherVideoId).first()).media_type).not.toBe('video');
-
-    // A photo whose thumbnail_path points at something that is no longer there.
-    await sharp({
-      create: { width: 900, height: 600, channels: 3, background: { r: 200, g: 40, b: 40 } },
-    }).jpeg().toFile(path.join(externalRoot, 'repair.jpg'));
-    const [rp] = await db('photos').insert({
-      event_id: eventId,
-      filename: 'repair.jpg',
-      path: 'regen-script-event/repair.jpg',
-      type: 'individual',
-      thumbnail_path: 'thumbnails/thumb_ext_missing_repair.jpg',
-      source_origin: 'external',
-      external_relpath: 'wedding/repair.jpg',
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    repairPhotoId = typeof rp === 'object' ? rp.id : rp;
-
-    // A photo whose source is not on the mount at all — an unavailable mount,
-    // which is the failure an operator most needs to hear about.
-    const [vp] = await db('photos').insert({
-      event_id: eventId,
-      filename: 'missing.jpg',
-      path: 'regen-script-event/missing.jpg',
-      type: 'individual',
-      source_origin: 'external',
-      external_relpath: 'missing.jpg',
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    vanishingPhotoId = typeof vp === 'object' ? vp.id : vp;
-
-    ({ regenerateThumbnails } = require('../../scripts/regenerate-thumbnails'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (cleanup) await cleanup();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  it('builds a thumbnail for an external photo instead of erroring on events/active', async () => {
-    // The location the old script computed and fs.access'd. Nothing is there,
-    // which is the whole defect — it is not where an external original lives.
-    // (The old script cannot be driven from a test directly: it had no export
-    // and ran on require, calling process.exit. Making it importable is part
-    // of this fix.)
-    const legacyPath = path.join(process.env.STORAGE_PATH, 'events/active', 'regen-script-event/shot.jpg');
-    expect(fs.existsSync(legacyPath)).toBe(false);
-
-    const result = await regenerateThumbnails(eventId);
-
-    // The old script reported an error for this photo and wrote nothing.
-    // The unresolvable row fails; the external photo and the repair row build.
-    expect(result.errorCount).toBe(1);
-    expect(result.successCount).toBe(2);
-
-    const row = await db('photos').where('id', externalPhotoId).first();
-    expect(row.thumbnail_path).toBeTruthy();
-    const onDisk = path.join(process.env.STORAGE_PATH, row.thumbnail_path);
-    expect(fs.existsSync(onDisk)).toBe(true);
-
-    // Named per-photo so two events referencing one NAS basename cannot
-    // clobber each other — the property ensureThumbnail owns and the reason
-    // the script must not build this name itself.
-    expect(path.basename(row.thumbnail_path)).toContain(`ext${externalPhotoId}_`);
-  });
-
-  it('leaves videos alone', async () => {
-    // A video thumbnail is a poster frame from videoProcessor; handing the
-    // container to Sharp produced one error per video row.
-    const row = await db('photos').where('id', videoPhotoId).first();
-    expect(row.thumbnail_path).toBeFalsy();
-  });
-
-  it('leaves a watcher-imported video alone, which carries no media_type', async () => {
-    // fileWatcher writes type + mime_type and lets media_type default to
-    // 'image', so filtering on media_type alone still fed these to Sharp. The
-    // signal is errorCount: the images are already done by now, so the only
-    // NEW thing that could fail this run is a video reaching Sharp. One error
-    // is the deliberately unresolvable row; two would be the video.
-    const result = await regenerateThumbnails(eventId);
-
-    expect(result.errorCount).toBe(1);
-    const row = await db('photos').where('id', watcherVideoId).first();
-    expect(row.thumbnail_path).toBeFalsy();
-  });
-
-  it('is idempotent — a second run skips instead of rebuilding', async () => {
-    const before = await db('photos').where('id', externalPhotoId).first();
-    const result = await regenerateThumbnails(eventId);
-
-    expect(result.errorCount).toBe(1);
-    expect(result.successCount).toBe(0);
-    expect(result.skipCount).toBe(2);
-
-    const after = await db('photos').where('id', externalPhotoId).first();
-    expect(after.thumbnail_path).toBe(before.thumbnail_path);
-  });
-
-  it('counts a repaired thumbnail as generated, not skipped', async () => {
-    // Both images are valid at this point. Destroy ONE thumbnail object while
-    // leaving thumbnail_path pointing at it — the corrupt/missing case.
-    const row = await db('photos').where('id', repairPhotoId).first();
-    const onDisk = path.join(process.env.STORAGE_PATH, row.thumbnail_path);
-    await fs.promises.rm(onDisk);
-
-    const result = await regenerateThumbnails(eventId);
-
-    // On local and external storage the rebuilt key is identical, so inferring
-    // "skipped" from an unchanged path reports this repair as already valid —
-    // the one number an operator running this is actually reading.
-    expect(result.successCount).toBe(1);
-    expect(result.skipCount).toBe(1);
-    expect(result.errorCount).toBe(1);
-    expect(fs.existsSync(onDisk)).toBe(true);
-  });
-
-  /** Run the CLI the way cron does, and hand back its exit status. */
-  const runCli = (args = []) => new Promise((resolve) => {
-    execFile(
-      process.execPath,
-      [path.join(__dirname, '..', '..', 'scripts', 'regenerate-thumbnails.js'), ...args],
-      { env: { ...process.env }, cwd: path.join(__dirname, '..', '..') },
-      (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })
-    );
-  });
-
-  it('exits nonzero when a photo could not be built', async () => {
-    // Exit status is the only thing a cron job reads, and `missing.jpg` has no
-    // source on the mount.
-    const failed = await runCli([String(eventId)]);
-    expect(failed.code).toBe(1);
-    expect(failed.stderr).toContain('completed with failures');
-  }, 120000);
-
-  it('exits zero when every photo resolves', async () => {
-    // Drop the unresolvable row: a clean run must not cry wolf at automation.
-    await db('photos').where('id', vanishingPhotoId).del();
-    const ok = await runCli([String(eventId)]);
-    expect(ok.code).toBe(0);
-    expect(ok.stdout).toContain('Script completed successfully');
-  }, 120000);
-});

backend/__tests__/integration/revealMode.test.js

@@ -0,0 +1,406 @@
+/**
+ * Reveal mode integration tests (#838).
+ *
+ * Pins the contract:
+ *  - effective visibility is computed at request time (isGalleryHidden):
+ *    reveal_at in the past opens the gate even before the scheduler stamps
+ *  - /photos returns the event shell with photos: [] + hidden_until_reveal
+ *    for plain guests; slideshow / client / admin-preview see everything
+ *  - image + download endpoints 403 with GALLERY_HIDDEN for plain guests
+ *  - the guest upload route is NOT gated (uploading while hidden is the point)
+ *  - the scheduler stamps revealed_at for due events, exactly once
+ *  - POST /events/:id/reveal stamps revealed_at (idempotent, 400 when the
+ *    mode is off); re-enabling reveal_mode clears revealed_at (re-hide)
+ */
+
+const request = require('supertest');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const bcrypt = require('bcrypt');
+const jwt = require('jsonwebtoken');
+
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'reveal-test-secret';
+
+const SLUG = 'reveal-test-event';
+
+describe('Reveal mode (#838)', () => {
+  let db;
+  let cleanup;
+  let app;
+  let eventId;
+  let photoIds;
+  let adminToken;
+  const { isGalleryHidden } = require('../../src/utils/revealMode');
+
+  const galleryToken = (extra = {}) => jwt.sign(
+    { eventId, eventSlug: SLUG, type: 'gallery', ...extra },
+    process.env.JWT_SECRET,
+    { expiresIn: '1h', issuer: 'picpeak-auth' }
+  );
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    await seedMinimal(db);
+
+    const inserted = await db('events').insert({
+      slug: SLUG,
+      event_type: 'wedding',
+      event_name: 'Reveal Test',
+      event_date: '2026-08-01',
+      host_email: 'host@example.com',
+      admin_email: 'admin@example.com',
+      password_hash: 'x',
+      share_link: `/gallery/${SLUG}/share`,
+      share_token: 'reveal-test-share',
+      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+      is_active: 1,
+      is_archived: 0,
+      is_draft: 0,
+      allow_user_uploads: 1,
+      reveal_mode: 1,
+      created_at: new Date().toISOString(),
+    }).returning('id');
+    eventId = inserted[0]?.id ?? inserted[0];
+
+    photoIds = [];
+    for (let i = 0; i < 2; i++) {
+      const p = await db('photos').insert({
+        event_id: eventId,
+        filename: `photo-${i}.jpg`,
+        path: `events/reveal/${i}.jpg`,
+        type: 'individual',
+        uploaded_at: new Date().toISOString(),
+      }).returning('id');
+      photoIds.push(p[0]?.id ?? p[0]);
+    }
+
+    // Super admin for the admin routes.
+    const superRole = await db('roles').where({ name: 'super_admin' }).first();
+    const [rootId] = await db('admin_users').insert({
+      username: 'reveal-admin',
+      email: 'reveal-admin@example.com',
+      password_hash: await bcrypt.hash('RevealAdmin123', 4),
+      role_id: superRole.id,
+      is_active: 1,
+      created_at: new Date(),
+      updated_at: new Date(),
+    }).returning('id').then((r) => [r[0]?.id || r[0]]);
+    adminToken = jwt.sign(
+      { id: rootId, username: 'reveal-admin', type: 'admin', role: 'super_admin', loginTime: Date.now() },
+      process.env.JWT_SECRET,
+      { expiresIn: '1h', issuer: 'picpeak-auth' }
+    );
+
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/gallery', require('../../src/routes/gallery'));
+    app.use('/api/secure-images', require('../../src/routes/secureImages'));
+    app.use('/api/images', require('../../src/routes/protectedImages'));
+    app.use('/api/gallery', require('../../src/routes/galleryFeedback'));
+    app.use('/api/admin/events', require('../../src/routes/adminEvents'));
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  describe('effective visibility math (isGalleryHidden)', () => {
+    const base = { reveal_mode: true, revealed_at: null, reveal_at: null };
+    it('is hidden while armed and unrevealed, visible otherwise', () => {
+      expect(isGalleryHidden({ ...base })).toBe(true);
+      expect(isGalleryHidden({ ...base, reveal_mode: false })).toBe(false);
+      expect(isGalleryHidden({ ...base, revealed_at: new Date() })).toBe(false);
+      // reveal_at in the past opens the gate WITHOUT any stamp — time-exact.
+      expect(isGalleryHidden({ ...base, reveal_at: new Date(Date.now() - 60_000) })).toBe(false);
+      expect(isGalleryHidden({ ...base, reveal_at: new Date(Date.now() + 60_000) })).toBe(true);
+      // SQLite 0/1 booleans
+      expect(isGalleryHidden({ reveal_mode: 1, revealed_at: null, reveal_at: null })).toBe(true);
+      expect(isGalleryHidden({ reveal_mode: 0, revealed_at: null, reveal_at: null })).toBe(false);
+    });
+  });
+
+  describe('gallery routes while hidden', () => {
+    it('/photos gives plain guests the shell with no photos and the flag', async () => {
+      const res = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(res.status).toBe(200);
+      expect(res.body.hidden_until_reveal).toBe(true);
+      expect(res.body.photos).toEqual([]);
+      expect(res.body.categories).toEqual([]);
+      expect(res.body.event.event_name).toBe('Reveal Test');
+    });
+
+    it('/photos serves the slideshow token everything (surprise beamer)', async () => {
+      const res = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken({ accessLevel: 'slideshow' })}`);
+      expect(res.status).toBe(200);
+      expect(res.body.hidden_until_reveal).toBe(false);
+      expect(res.body.photos).toHaveLength(2);
+    });
+
+    it('/photos serves client access everything (host review)', async () => {
+      const res = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken({ accessLevel: 'client' })}`);
+      expect(res.status).toBe(200);
+      expect(res.body.hidden_until_reveal).toBe(false);
+      expect(res.body.photos).toHaveLength(2);
+    });
+
+    it('/photos serves the admin preview everything (new transport: ?admin_preview=1 + admin cookie, even with a coexisting gallery session)', async () => {
+      // #868/#981: reveal-mode hiding is bypassed for an admin preview via the
+      // new transport (explicit flag + httpOnly admin_token cookie), NOT the
+      // retired ?preview=<jwt>. The coexisting gallery Bearer must not shadow it.
+      const res = await request(app)
+        .get(`/api/gallery/${SLUG}/photos?admin_preview=1`)
+        .set('Cookie', [`admin_token=${adminToken}`])
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(res.status).toBe(200);
+      expect(res.body.hidden_until_reveal).toBe(false);
+      expect(res.body.photos).toHaveLength(2);
+    });
+
+    it('image and download endpoints 403 with GALLERY_HIDDEN for plain guests', async () => {
+      for (const url of [
+        `/api/gallery/${SLUG}/thumbnail/${photoIds[0]}`,
+        `/api/gallery/${SLUG}/photo/${photoIds[0]}`,
+        `/api/gallery/${SLUG}/download/${photoIds[0]}`,
+        `/api/gallery/${SLUG}/download-all`,
+        `/api/gallery/${SLUG}/stats`,
+        `/api/gallery/${SLUG}/hero/${photoIds[0]}`,
+      ]) {
+        const res = await request(app).get(url).set('Authorization', `Bearer ${galleryToken()}`);
+        expect(`${url}:${res.status}`).toBe(`${url}:403`);
+        expect(res.body.code).toBe('GALLERY_HIDDEN');
+      }
+    });
+
+    it('image endpoints are NOT reveal-blocked for the slideshow token', async () => {
+      const res = await request(app)
+        .get(`/api/gallery/${SLUG}/thumbnail/${photoIds[0]}`)
+        .set('Authorization', `Bearer ${galleryToken({ accessLevel: 'slideshow' })}`);
+      // The seeded file doesn't exist on disk, so anything but the reveal
+      // gate's 403 is fine here.
+      expect(res.body.code).not.toBe('GALLERY_HIDDEN');
+    });
+
+    it('/info exposes the effective hidden state without auth', async () => {
+      const res = await request(app).get(`/api/gallery/${SLUG}/info`);
+      expect(res.status).toBe(200);
+      expect(res.body.hidden_until_reveal).toBe(true);
+    });
+
+    it('the guest upload route is not gated', async () => {
+      const res = await request(app)
+        .post(`/api/gallery/${eventId}/upload`)
+        .set('Authorization', `Bearer ${galleryToken()}`)
+        .send({});
+      // Fails later for other reasons (no multipart body) — but never on the
+      // reveal gate.
+      expect(res.body.code).not.toBe('GALLERY_HIDDEN');
+    });
+
+    it('legacy protected-image routes are reveal-gated for plain guests', async () => {
+      for (const [method, url] of [
+        ['get', `/api/images/${SLUG}/photo/${photoIds[0]}/view`],
+        ['post', `/api/images/${SLUG}/photo/${photoIds[0]}/generate-secure-token`],
+        ['post', `/api/images/${SLUG}/photo/${photoIds[0]}/generate-url`],
+      ]) {
+        const res = await request(app)[method](url).set('Authorization', `Bearer ${galleryToken()}`);
+        expect(`${url}:${res.status}`).toBe(`${url}:403`);
+        expect(res.body.code).toBe('GALLERY_HIDDEN');
+      }
+    });
+
+    it('feedback endpoints are reveal-gated; my-feedback degrades to empty', async () => {
+      // Feedback must be enabled for the routes to get past their own gate.
+      await db('event_feedback_settings').insert({
+        event_id: eventId, feedback_enabled: 1, allow_likes: 1,
+        created_at: new Date().toISOString(), updated_at: new Date().toISOString(),
+      });
+      const getRes = await request(app)
+        .get(`/api/gallery/${SLUG}/photos/${photoIds[0]}/feedback`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(getRes.status).toBe(403);
+      expect(getRes.body.code).toBe('GALLERY_HIDDEN');
+
+      const postRes = await request(app)
+        .post(`/api/gallery/${SLUG}/photos/${photoIds[0]}/feedback`)
+        .set('Authorization', `Bearer ${galleryToken()}`)
+        .send({ feedback_type: 'like' });
+      expect(postRes.status).toBe(403);
+      expect(postRes.body.code).toBe('GALLERY_HIDDEN');
+
+      const mine = await request(app)
+        .get(`/api/gallery/${SLUG}/my-feedback`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(mine.status).toBe(200);
+      expect(mine.body).toEqual([]);
+    });
+
+    it('secure-image token minting is reveal-gated for plain guests', async () => {
+      const res = await request(app)
+        .post(`/api/secure-images/${SLUG}/generate-token`)
+        .set('Authorization', `Bearer ${galleryToken()}`)
+        .send({ photoId: photoIds[0] });
+      expect(res.status).toBe(403);
+      expect(res.body.code).toBe('GALLERY_HIDDEN');
+    });
+
+    it('customer-portal tokens (via:customer, no accessLevel) bypass reveal mode', async () => {
+      const acct = await db('customer_accounts').insert({
+        email: 'portal-customer@example.com',
+        password_hash: 'x',
+        is_active: 1,
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      }).returning('id');
+      const customerId = acct[0]?.id ?? acct[0];
+      await db('event_customer_assignments').insert({
+        event_id: eventId,
+        customer_account_id: customerId,
+      });
+
+      const res = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken({ via: 'customer', customerId })}`);
+      expect(res.status).toBe(200);
+      expect(res.body.hidden_until_reveal).toBe(false);
+      expect(res.body.photos).toHaveLength(2);
+    });
+
+    it('a reveal_at in the past opens the gate without any stamp', async () => {
+      await db('events').where('id', eventId).update({ reveal_at: new Date(Date.now() - 60_000).toISOString() });
+      const res = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(res.body.hidden_until_reveal).toBe(false);
+      expect(res.body.photos).toHaveLength(2);
+      await db('events').where('id', eventId).update({ reveal_at: null });
+    });
+  });
+
+  describe('scheduler and admin reveal', () => {
+    it('the scheduler stamps revealed_at for due events exactly once', async () => {
+      const revealAt = new Date(Date.now() - 5 * 60_000);
+      await db('events').where('id', eventId).update({ reveal_at: revealAt.toISOString(), revealed_at: null });
+
+      const { checkScheduledReveals } = require('../../src/services/revealScheduler');
+      await checkScheduledReveals();
+
+      const asMs = (v) => new Date(v).getTime();
+      const row = await db('events').where('id', eventId).first();
+      expect(row.revealed_at).not.toBeNull();
+      expect(asMs(row.revealed_at)).toBe(revealAt.getTime());
+      expect(row.reveal_at).toBeNull(); // schedule consumed, like "Reveal now"
+
+      // Second pass no-ops (revealed_at already set).
+      await checkScheduledReveals();
+      const again = await db('events').where('id', eventId).first();
+      expect(asMs(again.revealed_at)).toBe(revealAt.getTime());
+
+      await db('events').where('id', eventId).update({ reveal_at: null, revealed_at: null });
+    });
+
+    it('POST /:id/reveal stamps revealed_at, clears the schedule, and is idempotent', async () => {
+      await db('events').where('id', eventId).update({ reveal_at: new Date(Date.now() + 3600_000).toISOString() });
+      const res = await request(app)
+        .post(`/api/admin/events/${eventId}/reveal`)
+        .set('Authorization', `Bearer ${adminToken}`);
+      expect(res.status).toBe(200);
+      expect(res.body.revealed_at).toBeTruthy();
+      // "Reveal now" consumes the pending schedule.
+      const cleared = await db('events').where('id', eventId).first();
+      expect(cleared.reveal_at).toBeNull();
+
+      const first = res.body.revealed_at;
+      const res2 = await request(app)
+        .post(`/api/admin/events/${eventId}/reveal`)
+        .set('Authorization', `Bearer ${adminToken}`);
+      expect(res2.status).toBe(200);
+      expect(res2.body.revealed_at).toBe(first);
+
+      // Guests see photos now.
+      const gallery = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(gallery.body.hidden_until_reveal).toBe(false);
+      expect(gallery.body.photos).toHaveLength(2);
+    });
+
+    it('re-enabling reveal_mode clears revealed_at (re-hide)', async () => {
+      await db('events').where('id', eventId).update({ reveal_mode: 0 });
+      const res = await request(app)
+        .put(`/api/admin/events/${eventId}`)
+        .set('Authorization', `Bearer ${adminToken}`)
+        .send({ reveal_mode: true });
+      expect(res.status).toBe(200);
+
+      const row = await db('events').where('id', eventId).first();
+      expect(row.revealed_at).toBeNull();
+
+      const gallery = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(gallery.body.hidden_until_reveal).toBe(true);
+    });
+
+    it('scheduling a FUTURE reveal on a revealed gallery re-arms hiding', async () => {
+      // State: revealed (previous tests). Saving a future schedule re-hides.
+      await db('events').where('id', eventId).update({ revealed_at: new Date().toISOString() });
+      const res = await request(app)
+        .put(`/api/admin/events/${eventId}`)
+        .set('Authorization', `Bearer ${adminToken}`)
+        .send({ reveal_mode: true, reveal_at: new Date(Date.now() + 3600_000).toISOString() });
+      expect(res.status).toBe(200);
+      const row = await db('events').where('id', eventId).first();
+      expect(row.revealed_at).toBeNull();
+
+      const gallery = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(gallery.body.hidden_until_reveal).toBe(true);
+      await db('events').where('id', eventId).update({ reveal_at: null });
+    });
+
+    it('re-arming without a schedule clears a stale PAST reveal_at', async () => {
+      // Legacy/partial-API state: revealed with the old past schedule still
+      // stored. {reveal_mode:false} then {reveal_mode:true} without
+      // reveal_at must re-hide, not instantly re-open via the stale date.
+      await db('events').where('id', eventId).update({
+        reveal_mode: 0,
+        revealed_at: new Date().toISOString(),
+        reveal_at: new Date(Date.now() - 3600_000).toISOString(),
+      });
+      const res = await request(app)
+        .put(`/api/admin/events/${eventId}`)
+        .set('Authorization', `Bearer ${adminToken}`)
+        .send({ reveal_mode: true });
+      expect(res.status).toBe(200);
+
+      const row = await db('events').where('id', eventId).first();
+      expect(row.revealed_at).toBeNull();
+      expect(row.reveal_at).toBeNull();
+
+      const gallery = await request(app)
+        .get(`/api/gallery/${SLUG}/photos`)
+        .set('Authorization', `Bearer ${galleryToken()}`);
+      expect(gallery.body.hidden_until_reveal).toBe(true);
+      expect(gallery.body.photos).toEqual([]);
+    });
+
+    it('POST /:id/reveal 400s while reveal mode is off', async () => {
+      await db('events').where('id', eventId).update({ reveal_mode: 0, revealed_at: null });
+      const res = await request(app)
+        .post(`/api/admin/events/${eventId}/reveal`)
+        .set('Authorization', `Bearer ${adminToken}`);
+      expect(res.status).toBe(400);
+      await db('events').where('id', eventId).update({ reveal_mode: 1 });
+    });
+  });
+});

backend/__tests__/integration/sqliteEpochTimestamps.test.js

@@ -0,0 +1,136 @@
+/**
+ * SQLite epoch-timestamp normalization (#485 follow-up).
+ *
+ * On SQLite, timestamp columns written with a raw `new Date()` through knex
+ * hold epoch-millisecond numbers. Postgres returns ISO strings, so frontend
+ * code written against Postgres calls parseISO() and crashes on native
+ * (SQLite) installs — the exact class fixed for admin Users in #485, which
+ * listed api tokens / photos / activity as an out-of-scope follow-up.
+ *
+ * Pins:
+ *  - gallery /photos serializes uploaded_at / captured_at as ISO strings
+ *    even when the row holds an epoch number (pre-fix archive restores)
+ *  - the api-tokens list serializes created_at / expires_at / last_used_at /
+ *    revoked_at as ISO strings for epoch-stored rows
+ */
+
+const request = require('supertest');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const bcrypt = require('bcrypt');
+const jwt = require('jsonwebtoken');
+
+const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
+
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'epoch-test-secret';
+
+const SLUG = 'epoch-test-event';
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+
+describe('SQLite epoch timestamp normalization', () => {
+  let db;
+  let cleanup;
+  let app;
+  let eventId;
+  let adminToken;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    await seedMinimal(db);
+
+    const inserted = await db('events').insert({
+      slug: SLUG,
+      event_type: 'wedding',
+      event_name: 'Epoch Test',
+      event_date: '2026-08-01',
+      host_email: 'host@example.com',
+      admin_email: 'admin@example.com',
+      password_hash: 'x',
+      share_link: `/gallery/${SLUG}/share`,
+      share_token: 'epoch-test-share',
+      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+      is_active: 1,
+      is_archived: 0,
+      is_draft: 0,
+      created_at: new Date().toISOString(),
+    }).returning('id');
+    eventId = inserted[0]?.id ?? inserted[0];
+
+    // The pre-fix corruption shape: epoch numbers in timestamp columns.
+    await db('photos').insert({
+      event_id: eventId,
+      filename: 'restored.jpg',
+      path: 'events/epoch/restored.jpg',
+      type: 'individual',
+      uploaded_at: Date.now() - 3600_000,
+      captured_at: Date.now() - 7200_000,
+    });
+
+    const superRole = await db('roles').where({ name: 'super_admin' }).first();
+    const [rootId] = await db('admin_users').insert({
+      username: 'epoch-admin',
+      email: 'epoch-admin@example.com',
+      password_hash: await bcrypt.hash('EpochAdmin123', 4),
+      role_id: superRole.id,
+      is_active: 1,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    }).returning('id').then((r) => [r[0]?.id || r[0]]);
+    adminToken = jwt.sign(
+      { id: rootId, username: 'epoch-admin', type: 'admin', role: 'super_admin', loginTime: Date.now() },
+      process.env.JWT_SECRET,
+      { expiresIn: '1h', issuer: 'picpeak-auth' }
+    );
+
+    await db('api_tokens').insert({
+      name: 'epoch-token',
+      hashed_token: 'x'.repeat(64),
+      preview: 'pk_test…abcd',
+      scopes: JSON.stringify(['events:read']),
+      created_by: rootId,
+      created_at: Date.now() - 86400_000,
+      last_used_at: Date.now() - 3600_000,
+      revoked_at: Date.now() - 60_000,
+    });
+
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/gallery', require('../../src/routes/gallery'));
+    app.use('/api/admin/api-tokens', require('../../src/routes/adminApiTokens'));
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  it('gallery /photos serializes epoch-stored uploaded_at/captured_at as ISO strings', async () => {
+    const galleryToken = jwt.sign(
+      { eventId, eventSlug: SLUG, type: 'gallery' },
+      process.env.JWT_SECRET,
+      { expiresIn: '1h', issuer: 'picpeak-auth' }
+    );
+    const res = await request(app)
+      .get(`/api/gallery/${SLUG}/photos`)
+      .set('Authorization', `Bearer ${galleryToken}`);
+    expect(res.status).toBe(200);
+    expect(res.body.photos).toHaveLength(1);
+    const photo = res.body.photos[0];
+    expect(typeof photo.uploaded_at).toBe('string');
+    expect(photo.uploaded_at).toMatch(ISO_RE);
+    expect(photo.captured_at).toMatch(ISO_RE);
+  });
+
+  it('api-tokens list serializes epoch-stored timestamps as ISO strings', async () => {
+    const res = await request(app)
+      .get('/api/admin/api-tokens')
+      .set('Authorization', `Bearer ${adminToken}`);
+    expect(res.status).toBe(200);
+    const token = res.body.find((t) => t.name === 'epoch-token');
+    expect(token).toBeTruthy();
+    for (const field of ['created_at', 'last_used_at', 'revoked_at']) {
+      expect(`${field}:${typeof token[field]}`).toBe(`${field}:string`);
+      expect(token[field]).toMatch(ISO_RE);
+    }
+  });
+});

backend/__tests__/middleware/adminAuthRoleFallback.test.js

@@ -14,6 +14,7 @@
 const jwt = require('jsonwebtoken');
 
 jest.mock('../../src/utils/tokenRevocation', () => ({ isTokenRevoked: jest.fn().mockResolvedValue(false) }));
+jest.mock('../../src/utils/sessionCutoff', () => ({ isTokenBeforeCutoff: jest.fn().mockResolvedValue(false) }));
 jest.mock('../../src/utils/logger', () => ({ warn: jest.fn(), error: jest.fn(), debug: jest.fn(), info: jest.fn() }));
 
 // The joined query throws whatever the test stages; the role-less fallback

backend/__tests__/middleware/galleryAdminPreview.test.js

@@ -0,0 +1,67 @@
+/**
+ * #868 — the admin gallery-preview gate. isAdminPreview must fail CLOSED: it
+ * grants the draft/password bypass only for an explicit `?admin_preview=1` flag
+ * AND a verified admin JWT (type 'admin', issuer 'picpeak-auth') read from the
+ * httpOnly admin_token cookie or a Bearer header — never from the URL, never for
+ * a guest/gallery token.
+ */
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'admin-preview-test-secret';
+const jwt = require('jsonwebtoken');
+const { isAdminPreview } = require('../../src/middleware/gallery');
+
+// Read the secret at call time — a jest setup file can set JWT_SECRET after this
+// module loads, and isAdminPreview verifies against the live value.
+const adminToken = () => jwt.sign({ type: 'admin', id: 1 }, process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
+const galleryToken = () => jwt.sign({ type: 'gallery', eventId: 1 }, process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
+
+function req({ flag, cookie, bearer } = {}) {
+  return {
+    query: flag === undefined ? {} : { admin_preview: flag },
+    cookies: cookie ? { admin_token: cookie } : {},
+    headers: bearer ? { authorization: `Bearer ${bearer}` } : {},
+  };
+}
+
+describe('isAdminPreview (#868) fails closed', () => {
+  it('false without the explicit flag, even with a valid admin cookie (plain link stays guest-identical)', () => {
+    expect(isAdminPreview(req({ cookie: adminToken() }))).toBe(false);
+  });
+
+  it('false with the flag but no session token', () => {
+    expect(isAdminPreview(req({ flag: '1' }))).toBe(false);
+  });
+
+  it('true with the flag + a valid admin cookie', () => {
+    expect(isAdminPreview(req({ flag: '1', cookie: adminToken() }))).toBe(true);
+  });
+
+  it('true with the flag + a valid admin Bearer header', () => {
+    expect(isAdminPreview(req({ flag: '1', bearer: adminToken() }))).toBe(true);
+  });
+
+  it('false for a gallery (guest) token — must be type admin', () => {
+    expect(isAdminPreview(req({ flag: '1', cookie: galleryToken() }))).toBe(false);
+  });
+
+  it('true from the admin cookie even when a gallery Bearer is also present (#981 coexisting session)', () => {
+    expect(isAdminPreview(req({ flag: '1', cookie: adminToken(), bearer: galleryToken() }))).toBe(true);
+  });
+
+  it('false when only a gallery Bearer is present — a gallery header can never satisfy it (#981)', () => {
+    expect(isAdminPreview(req({ flag: '1', bearer: galleryToken() }))).toBe(false);
+  });
+
+  it('false on a tampered token', () => {
+    expect(isAdminPreview(req({ flag: '1', cookie: `${adminToken()}x` }))).toBe(false);
+  });
+
+  it('false on the wrong issuer', () => {
+    const t = jwt.sign({ type: 'admin' }, process.env.JWT_SECRET, { issuer: 'not-picpeak' });
+    expect(isAdminPreview(req({ flag: '1', cookie: t }))).toBe(false);
+  });
+
+  it('false when the flag is anything other than exactly "1"', () => {
+    expect(isAdminPreview(req({ flag: 'true', cookie: adminToken() }))).toBe(false);
+    expect(isAdminPreview(req({ flag: '0', cookie: adminToken() }))).toBe(false);
+  });
+});

backend/__tests__/migrations/175_fix_css_template_photo_height.test.js

@@ -1,242 +0,0 @@
-/**
- * Repairing the bundled templates' fixed image height (#1131).
- *
- * The risk in a migration that rewrites user-visible CSS is doing too much,
- * so most of what is pinned here is what it must NOT touch: the other pixel
- * heights inside the very same templates (a 1px divider, an 8px scrollbar),
- * and any rule a user wrote themselves.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-const migration = require('../../migrations/core/175_fix_css_template_photo_height');
-
-const ELEGANT_DARK = `
-.photo-card {
-  border-radius: 12px;
-}
-
-.photo-card img {
-  width: 100%;
-  height: 200px;
-  object-fit: cover;
-  transition: transform 0.3s ease;
-}
-`;
-
-const LIQUID_GLASS_DARK = `
-.gallery-page::after {
-  content: '';
-  height: 1px;
-  background: linear-gradient(90deg, transparent, #fff, transparent);
-}
-
-.photo-card img {
-  width: 100%;
-  height: 240px;
-  object-fit: cover;
-  filter: brightness(0.9);
-}
-
-.gallery-page ::-webkit-scrollbar {
-  width: 8px;
-  height: 8px;
-}
-
-@media (max-width: 640px) {
-  .photo-card img {
-    height: 180px;
-  }
-}
-`;
-
-describe('migration 175 — CSS template image height (#1131)', () => {
-  let knex; let tmpDir;
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-mig175-'));
-    knex = require('knex')({
-      client: 'sqlite3',
-      connection: { filename: path.join(tmpDir, 'db.sqlite') },
-      useNullAsDefault: true,
-    });
-    await knex.schema.createTable('css_templates', (t) => {
-      t.increments('id').primary();
-      t.string('name');
-      t.text('css_content');
-    });
-  });
-
-  afterAll(async () => {
-    if (knex) await knex.destroy();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(async () => { await knex('css_templates').del(); });
-
-  const contentOf = async (name) =>
-    (await knex('css_templates').where({ name }).first()).css_content;
-
-  it('relaxes the default template so the layouts h-full can win', async () => {
-    await knex('css_templates').insert({ name: 'Elegant Dark', css_content: ELEGANT_DARK });
-
-    await migration.up(knex);
-
-    const css = await contentOf('Elegant Dark');
-    expect(css).toContain('height: 100%');
-    expect(css).not.toContain('height: 200px');
-    // Everything else about the rule survives.
-    expect(css).toContain('object-fit: cover');
-    expect(css).toContain('transition: transform 0.3s ease');
-  });
-
-  it('fixes both the base rule and the mobile override of the dark glass template', async () => {
-    await knex('css_templates').insert({ name: 'Liquid Glass Dark', css_content: LIQUID_GLASS_DARK });
-
-    await migration.up(knex);
-
-    const css = await contentOf('Liquid Glass Dark');
-    expect(css).not.toContain('height: 240px');
-    expect(css).not.toContain('height: 180px');
-    expect(css.match(/height: 100%/g)).toHaveLength(2);
-  });
-
-  it('leaves the divider and the scrollbar alone', async () => {
-    await knex('css_templates').insert({ name: 'Liquid Glass Dark', css_content: LIQUID_GLASS_DARK });
-
-    await migration.up(knex);
-
-    // The whole reason this matches full rule bodies rather than every
-    // `height: <n>px`: these are in the same stylesheet and are correct.
-    const css = await contentOf('Liquid Glass Dark');
-    expect(css).toContain('height: 1px');
-    expect(css).toContain('width: 8px');
-    expect(css).toContain('height: 8px');
-  });
-
-  /**
-   * The case that forced the scope wider. `sanitizeCSS` strips control
-   * characters, so any template ever saved through the editor — including a
-   * save that only changed its name — has had every newline REMOVED. An
-   * exact-text migration finds nothing on those installs, is recorded as
-   * applied, and leaves them broken permanently.
-   */
-  it('fixes a template that has been through the editor, newlines and all', async () => {
-    const { sanitizeCSS } = require('../../src/utils/cssSanitizer');
-    const { sanitized } = sanitizeCSS(ELEGANT_DARK);
-    // Precondition: the sanitizer really did flatten it.
-    expect(sanitized).not.toContain('\n');
-    expect(sanitized).toContain('height: 200px');
-    await knex('css_templates').insert({ name: 'Saved Once', css_content: sanitized });
-
-    await migration.up(knex);
-
-    const css = await contentOf('Saved Once');
-    expect(css).not.toContain('200px');
-    expect(css).toContain('height: 100%');
-  });
-
-  it('relaxes a user-authored fixed height too, but only on .photo-card img', async () => {
-    // Deliberately broader than the seeded text — see the migration header. A
-    // pixel height on the image cannot be right under any of the seven
-    // layouts, whoever wrote it; a height anywhere else is none of our
-    // business.
-    const mine = '.photo-card img {\n  height: 220px;\n}\n.hero { height: 400px; }';
-    await knex('css_templates').insert({ name: 'My Own', css_content: mine });
-
-    await migration.up(knex);
-
-    const css = await contentOf('My Own');
-    expect(css).toContain('height: 100%');
-    expect(css).not.toContain('220px');
-    expect(css).toContain('.hero { height: 400px; }');
-  });
-
-  it('does not rewrite other properties that merely end in -height', async () => {
-    // `line-height: 200px` contains `height: 200px` as a substring, so an
-    // unanchored pattern silently rewrites it — in a migration that cannot be
-    // undone.
-    const mine = [
-      '.photo-card img {',
-      '  line-height: 200px;',
-      '  max-height: 300px;',
-      '  min-height: 14px;',
-      '  --tile-height: 220px;',
-      '  height: 200px;',
-      '}',
-    ].join('\n');
-    await knex('css_templates').insert({ name: 'Adjacent Props', css_content: mine });
-
-    await migration.up(knex);
-
-    const css = await contentOf('Adjacent Props');
-    expect(css).toContain('line-height: 200px');
-    expect(css).toContain('max-height: 300px');
-    expect(css).toContain('min-height: 14px');
-    expect(css).toContain('--tile-height: 220px');
-    // Only the real one moved.
-    expect(css).toContain('height: 100%');
-    expect(css).not.toMatch(/(?<![\w-])height:\s*200px/);
-  });
-
-  it('handles a grouped selector list', async () => {
-    // Requiring `{` straight after `img` skipped these entirely — and the
-    // migration is still recorded as applied, so the template kept the bug.
-    const mine = '.photo-card img, .thumbnail img {\n  height: 200px;\n}';
-    await knex('css_templates').insert({ name: 'Grouped', css_content: mine });
-
-    await migration.up(knex);
-
-    const css = await contentOf('Grouped');
-    expect(css).toContain('.photo-card img, .thumbnail img {');
-    expect(css).toContain('height: 100%');
-    expect(css).not.toContain('200px');
-  });
-
-  it('skips a nested rule rather than rewriting the wrong declaration', async () => {
-    // Valid nested CSS that passes the validator. A brace-greedy body would
-    // capture the inner block and rewrite the CAPTION's height, which cannot
-    // be undone. Leaving it untouched is the lesser evil.
-    const mine = '.photo-card img {\n  & + .caption { height: 200px; }\n}';
-    await knex('css_templates').insert({ name: 'Nested', css_content: mine });
-
-    await migration.up(knex);
-
-    expect(await contentOf('Nested')).toBe(mine);
-  });
-
-  it('leaves non-pixel heights on the image alone', async () => {
-    const mine = '.photo-card img { height: 50vh; }\n.photo-card img { height: auto; }';
-    await knex('css_templates').insert({ name: 'Relative', css_content: mine });
-
-    await migration.up(knex);
-
-    expect(await contentOf('Relative')).toBe(mine);
-  });
-
-  it('is idempotent and safe on a row with no CSS', async () => {
-    await knex('css_templates').insert([
-      { name: 'Elegant Dark', css_content: ELEGANT_DARK },
-      { name: 'Empty', css_content: null },
-    ]);
-
-    await migration.up(knex);
-    const once = await contentOf('Elegant Dark');
-    await migration.up(knex);
-
-    expect(await contentOf('Elegant Dark')).toBe(once);
-    expect(await contentOf('Empty')).toBeNull();
-  });
-
-  it('no-ops when the table does not exist yet', async () => {
-    await knex.schema.dropTable('css_templates');
-    await expect(migration.up(knex)).resolves.toBeUndefined();
-    await knex.schema.createTable('css_templates', (t) => {
-      t.increments('id').primary();
-      t.string('name');
-      t.text('css_content');
-    });
-  });
-});

backend/__tests__/migrations/176_external_relpath_unique.test.js

@@ -1,546 +0,0 @@
-/**
- * One row per external file per event (#1162).
- *
- * The migration has two halves and they fail differently: the cleanup can take
- * out the wrong row of a pair (losing a thumbnail, orphaning an event's hero),
- * and the index can fail to be created at all — leaving an install that looks
- * migrated and is still racing. Both are pinned here.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-const migration = require('../../migrations/core/176_external_relpath_unique');
-
-describe('migration 176 — unique (event_id, external_relpath) (#1162)', () => {
-  let knex; let tmpDir;
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-mig186-'));
-    knex = require('knex')({
-      client: 'sqlite3',
-      connection: { filename: path.join(tmpDir, 'db.sqlite') },
-      useNullAsDefault: true,
-    });
-  });
-
-  afterAll(async () => {
-    if (knex) await knex.destroy();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(async () => {
-    for (const table of [
-      'photos', 'events', 'photo_categories', 'photo_feedback',
-      'photo_admin_marks', 'photo_faces', 'image_access_logs', 'transfer_files',
-    ]) {
-      await knex.schema.dropTableIfExists(table);
-    }
-    await knex.schema.createTable('events', (t) => {
-      t.increments('id').primary();
-      t.integer('hero_photo_id');
-      t.string('download_zip_path');
-      t.string('download_zip_generated_at');
-    });
-    await knex.schema.createTable('photo_categories', (t) => {
-      t.increments('id').primary();
-      t.integer('hero_photo_id');
-    });
-    await knex.schema.createTable('photos', (t) => {
-      t.increments('id').primary();
-      t.integer('event_id');
-      t.string('external_relpath');
-      t.string('thumbnail_path');
-      t.string('source_origin').defaultTo('managed');
-      t.integer('feedback_count').defaultTo(0);
-      t.integer('like_count').defaultTo(0);
-      t.decimal('average_rating', 3, 2).defaultTo(0);
-      t.integer('favorite_count').defaultTo(0);
-      t.integer('reaction_count').defaultTo(0);
-      t.integer('color_label_count').defaultTo(0);
-      t.string('face_status');
-      t.integer('view_count').defaultTo(0);
-      t.integer('download_count').defaultTo(0);
-      t.integer('face_count');
-      t.string('face_started_at');
-      t.text('face_error');
-    });
-    // Declared exactly as the real schema declares them — CASCADE and all.
-    // The point of these tables here is that SQLite does NOT enforce any of
-    // it (PicPeak never sets `PRAGMA foreign_keys = ON`), so a bare delete of
-    // the photo row leaves every one of them dangling.
-    await knex.schema.createTable('photo_feedback', (t) => {
-      t.increments('id').primary();
-      t.integer('photo_id').references('id').inTable('photos').onDelete('CASCADE');
-      t.integer('event_id');
-      t.string('feedback_type');
-      t.text('comment_text');
-      t.string('guest_identifier');
-      // Per-person guest identity (migration 078). Nullable: galleries without
-      // guest identity leave it NULL and fall back to guest_identifier.
-      t.integer('guest_id');
-      t.integer('rating');
-      t.boolean('is_hidden').defaultTo(false);
-      t.boolean('is_approved').defaultTo(true);
-    });
-    await knex.schema.createTable('photo_admin_marks', (t) => {
-      t.increments('id').primary();
-      t.integer('photo_id').notNullable().references('id').inTable('photos').onDelete('CASCADE');
-      t.integer('event_id');
-      t.integer('admin_id');
-      t.integer('rating');
-      // Independently writable alongside rating, per photoAdminMarksService.
-      t.string('color_label', 16);
-      t.unique(['photo_id', 'admin_id'], 'photo_admin_marks_photo_admin_uniq');
-    });
-    await knex.schema.createTable('photo_faces', (t) => {
-      t.increments('id').primary();
-      t.integer('photo_id').references('id').inTable('photos').onDelete('CASCADE');
-      t.integer('event_id');
-      // purgePhotoFaces rebuilds the people that lose members, so the cluster
-      // link and the vectors recomputeCentroid reads have to be here for this
-      // to exercise the real path rather than a stub.
-      t.integer('person_id');
-      t.binary('embedding');
-      t.float('det_score');
-    });
-
-    await knex.schema.createTable('image_access_logs', (t) => {
-      t.increments('id').primary();
-      t.integer('photo_id');
-    });
-    await knex.schema.createTable('transfer_files', (t) => {
-      t.increments('id').primary();
-      t.integer('transfer_id');
-      t.integer('photo_id');
-      t.unique(['transfer_id', 'photo_id'], 'transfer_files_unique');
-    });
-  });
-
-  /** Two duplicate rows for the same file: id 1 survives, id 2 is doomed. */
-  const seedPair = async () => {
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't', source_origin: 'external' },
-    ]);
-  };
-
-  const rows = () => knex('photos').orderBy('id', 'asc').select('*');
-
-  it('collapses a duplicated pair to one row and leaves distinct paths alone', async () => {
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't1', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't2', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/y.jpg', thumbnail_path: 't3', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    const after = await rows();
-    expect(after.map((r) => r.external_relpath)).toEqual(['a/x.jpg', 'a/y.jpg']);
-    // Lowest id survives when both sides are equally complete.
-    expect(after[0].id).toBe(1);
-  });
-
-  it('does not collapse the same path across different events', async () => {
-    // The constraint is per event. Two events referencing the same NAS folder
-    // is a supported setup, and treating those as duplicates would delete one
-    // event's entire library.
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', source_origin: 'external' },
-      { event_id: 2, external_relpath: 'a/x.jpg', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await knex('photos').count('* as c').first()).toEqual({ c: 2 });
-  });
-
-  it('never touches managed rows, however many carry NULL', async () => {
-    // Every managed photo has external_relpath NULL. Grouping on it without
-    // the NOT NULL filter would make them all one enormous "duplicate" group
-    // and delete the entire library bar one row.
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: null, source_origin: 'managed' },
-      { event_id: 1, external_relpath: null, source_origin: 'managed' },
-      { event_id: 1, external_relpath: null, source_origin: 'managed' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await knex('photos').count('* as c').first()).toEqual({ c: 3 });
-  });
-
-  it('keeps the row that has a thumbnail, not merely the lowest id', async () => {
-    // An import killed mid-flight leaves rows without a thumbnail. Dropping
-    // the completed one would blank a tile in the grid for no reason.
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: null, source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 'thumb.jpg', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    const after = await rows();
-    expect(after).toHaveLength(1);
-    expect(after[0].thumbnail_path).toBe('thumb.jpg');
-  });
-
-  it('repoints a hero that pointed at the row being removed', async () => {
-    // events.hero_photo_id is ON DELETE SET NULL, so without this the cleanup
-    // silently strips the event's hero image — a visible regression caused
-    // entirely by the fix.
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't', source_origin: 'external' },
-    ]);
-    await knex('events').insert({ id: 1, hero_photo_id: 2 });
-    await knex('photo_categories').insert({ id: 1, hero_photo_id: 2 });
-
-    await migration.up(knex);
-
-    expect((await knex('events').where({ id: 1 }).first()).hero_photo_id).toBe(1);
-    expect((await knex('photo_categories').where({ id: 1 }).first()).hero_photo_id).toBe(1);
-  });
-
-  it('leaves a hero that pointed at the survivor untouched', async () => {
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/x.jpg', thumbnail_path: 't', source_origin: 'external' },
-    ]);
-    await knex('events').insert({ id: 1, hero_photo_id: 1 });
-
-    await migration.up(knex);
-
-    expect((await knex('events').where({ id: 1 }).first()).hero_photo_id).toBe(1);
-  });
-
-  it('makes a second insert of the same path impossible afterwards', async () => {
-    // The whole point. Without this the route is still racing, and the
-    // migration is recorded as applied.
-    await knex('photos').insert({ event_id: 1, external_relpath: 'a/x.jpg', source_origin: 'external' });
-
-    await migration.up(knex);
-
-    await expect(
-      knex('photos').insert({ event_id: 1, external_relpath: 'a/x.jpg', source_origin: 'external' })
-    ).rejects.toThrow(/unique/i);
-  });
-
-  it('still admits managed rows once the index exists', async () => {
-    await migration.up(knex);
-
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: null, source_origin: 'managed' },
-      { event_id: 1, external_relpath: null, source_origin: 'managed' },
-    ]);
-
-    expect(await knex('photos').count('* as c').first()).toEqual({ c: 2 });
-  });
-
-  it('leaves nothing dangling behind the deleted row', async () => {
-    // SQLite never enforces the ON DELETE CASCADE these tables declare, so a
-    // bare delete strands biometric embeddings, feedback and marks pointing at
-    // a photo id that no longer exists — on every SQLite install.
-    await seedPair();
-    await knex('photo_faces').insert({ photo_id: 2, event_id: 1 });
-    await knex('image_access_logs').insert({ photo_id: 2 });
-
-    await migration.up(knex);
-
-    expect(await knex('photo_faces').where('photo_id', 2).first()).toBeUndefined();
-    expect(await knex('image_access_logs').where('photo_id', 2).first()).toBeUndefined();
-  });
-
-  it('does not carry the duplicate\'s faces over to the survivor', async () => {
-    // Both rows were scanned independently, so the survivor already holds its
-    // own embeddings. Moving these would fabricate a second copy of every face
-    // and split the person clusters built from them.
-    await seedPair();
-    await knex('photo_faces').insert([{ photo_id: 1, event_id: 1 }, { photo_id: 2, event_id: 1 }]);
-
-    await migration.up(knex);
-
-    expect(await knex('photo_faces').count('* as c').first()).toEqual({ c: 1 });
-  });
-
-  it('moves a guest comment to the survivor rather than deleting it', async () => {
-    // The duplicates were separate tiles in the grid, so a guest could have
-    // commented on either. Silently dropping that inside a fix for silent data
-    // loss would be its own bug.
-    await seedPair();
-    await knex('photo_feedback').insert({
-      photo_id: 2, event_id: 1, feedback_type: 'comment',
-      comment_text: 'lovely shot', guest_identifier: 'guest-a',
-    });
-
-    await migration.up(knex);
-
-    const rows = await knex('photo_feedback');
-    expect(rows).toHaveLength(1);
-    expect(rows[0].photo_id).toBe(1);
-    expect(rows[0].comment_text).toBe('lovely shot');
-  });
-
-  it('keeps both comments when the same guest commented on both tiles', async () => {
-    await seedPair();
-    await knex('photo_feedback').insert([
-      { photo_id: 1, event_id: 1, feedback_type: 'comment', comment_text: 'one', guest_identifier: 'g' },
-      { photo_id: 2, event_id: 1, feedback_type: 'comment', comment_text: 'two', guest_identifier: 'g' },
-    ]);
-
-    await migration.up(knex);
-
-    const rows = await knex('photo_feedback').orderBy('id');
-    expect(rows.map((r) => r.comment_text)).toEqual(['one', 'two']);
-    expect(rows.every((r) => r.photo_id === 1)).toBe(true);
-  });
-
-  it('does not double-count a like the same guest left on both tiles', async () => {
-    // Unlike comments, a like is a per-guest toggle: moving it would show two
-    // likes from one person.
-    await seedPair();
-    await knex('photo_feedback').insert([
-      { photo_id: 1, event_id: 1, feedback_type: 'like', guest_identifier: 'g' },
-      { photo_id: 2, event_id: 1, feedback_type: 'like', guest_identifier: 'g' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await knex('photo_feedback').count('* as c').first()).toEqual({ c: 1 });
-  });
-
-  it('moves a like from a guest the survivor has never seen', async () => {
-    await seedPair();
-    await knex('photo_feedback').insert({
-      photo_id: 2, event_id: 1, feedback_type: 'like', guest_identifier: 'other',
-    });
-
-    await migration.up(knex);
-
-    const rows = await knex('photo_feedback');
-    expect(rows).toHaveLength(1);
-    expect(rows[0].photo_id).toBe(1);
-  });
-
-  it('moves an admin mark, and drops it when that admin already marked the survivor', async () => {
-    // photo_admin_marks is UNIQUE(photo_id, admin_id), so a blind move would
-    // throw and abort the migration.
-    await seedPair();
-    await knex('photo_admin_marks').insert([
-      { photo_id: 1, event_id: 1, admin_id: 7, rating: 5 },
-      { photo_id: 2, event_id: 1, admin_id: 7, rating: 2 },
-      { photo_id: 2, event_id: 1, admin_id: 9, rating: 4 },
-    ]);
-
-    await migration.up(knex);
-
-    const rows = await knex('photo_admin_marks').orderBy('admin_id');
-    expect(rows.map((r) => [r.admin_id, r.rating])).toEqual([[7, 5], [9, 4]]);
-    expect(rows.every((r) => r.photo_id === 1)).toBe(true);
-  });
-
-  it('respects the transfer_files uniqueness when moving membership', async () => {
-    await seedPair();
-    await knex('transfer_files').insert([
-      { transfer_id: 3, photo_id: 1 },
-      { transfer_id: 3, photo_id: 2 },
-      { transfer_id: 4, photo_id: 2 },
-    ]);
-
-    await migration.up(knex);
-
-    const rows = await knex('transfer_files').orderBy('transfer_id');
-    expect(rows.map((r) => r.transfer_id)).toEqual([3, 4]);
-    expect(rows.every((r) => r.photo_id === 1)).toBe(true);
-  });
-
-  it('recomputes the survivor\'s feedback totals after reparenting rows', async () => {
-    // photos carries denormalized counters (migration 033). A survivor that
-    // now OWNS the feedback but still renders zero is the visible half of
-    // getting this wrong.
-    await seedPair();
-    await knex('photo_feedback').insert([
-      { photo_id: 2, event_id: 1, feedback_type: 'like', guest_identifier: 'g1' },
-      { photo_id: 2, event_id: 1, feedback_type: 'rating', rating: 4, guest_identifier: 'g1' },
-    ]);
-
-    await migration.up(knex);
-
-    const survivor = await knex('photos').where('id', 1).first();
-    expect(survivor.like_count).toBe(1);
-    expect(Number(survivor.average_rating)).toBe(4);
-    expect(survivor.feedback_count).toBe(1);
-  });
-
-  it('keeps two people who share a device apart', async () => {
-    // guest_identifier is per-device; guest_id is per-person (migration 078),
-    // and feedbackService scopes by guest_id when it is present. Keying on the
-    // identifier alone would read these as one person and delete a rating.
-    await seedPair();
-    await knex('photo_feedback').insert([
-      { photo_id: 1, event_id: 1, feedback_type: 'rating', rating: 5, guest_identifier: 'shared', guest_id: 10 },
-      { photo_id: 2, event_id: 1, feedback_type: 'rating', rating: 2, guest_identifier: 'shared', guest_id: 11 },
-    ]);
-
-    await migration.up(knex);
-
-    const rows = await knex('photo_feedback').orderBy('guest_id');
-    expect(rows.map((r) => [r.guest_id, r.rating])).toEqual([[10, 5], [11, 2]]);
-  });
-
-  it('still dedupes one person voting on both tiles', async () => {
-    await seedPair();
-    await knex('photo_feedback').insert([
-      { photo_id: 1, event_id: 1, feedback_type: 'like', guest_identifier: 'shared', guest_id: 10 },
-      { photo_id: 2, event_id: 1, feedback_type: 'like', guest_identifier: 'shared', guest_id: 10 },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await knex('photo_feedback').count('* as c').first()).toEqual({ c: 1 });
-  });
-
-  it('still clears face rows on a branch that has no face feature', async () => {
-    // DIVERGES FROM MAIN, deliberately. Face recognition (#1090) is main-only:
-    // there is no faceProcessor on this branch, so purgePhotoFaces cannot be
-    // called and there are no event_people counts or centroids to reconcile.
-    // What still matters is the half that is not optional — the rows must not
-    // dangle, because SQLite never enforces the CASCADE that would remove
-    // them. The service reaches for purgePhotoFaces, finds nothing, and falls
-    // back to a plain delete; this pins that fallback.
-    //
-    // If faces are ever backported, main's version of this test comes with
-    // them.
-    await seedPair();
-    await knex('photo_faces').insert({ photo_id: 2, event_id: 1, person_id: 5 });
-
-    await migration.up(knex);
-
-    expect(await knex('photo_faces').count('* as c').first()).toEqual({ c: 0 });
-  });
-
-  it('keeps a hidden moderation record from swallowing the visible replacement', async () => {
-    // feedbackService lets both coexist and counts only the visible one.
-    await seedPair();
-    await knex('photo_feedback').insert([
-      { photo_id: 1, event_id: 1, feedback_type: 'like', guest_identifier: 'g', is_hidden: true },
-      { photo_id: 2, event_id: 1, feedback_type: 'like', guest_identifier: 'g', is_hidden: false },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await knex('photo_feedback').count('* as c').first()).toEqual({ c: 2 });
-  });
-
-  it('merges the independent halves of one admin\'s mark', async () => {
-    // rating and color_label are written independently, so the same admin can
-    // have rated one tile and coloured the other.
-    await seedPair();
-    await knex('photo_admin_marks').insert([
-      { photo_id: 1, event_id: 1, admin_id: 7, rating: 5, color_label: null },
-      { photo_id: 2, event_id: 1, admin_id: 7, rating: null, color_label: 'red' },
-    ]);
-
-    await migration.up(knex);
-
-    const rows = await knex('photo_admin_marks');
-    expect(rows).toHaveLength(1);
-    expect([rows[0].rating, rows[0].color_label]).toEqual([5, 'red']);
-  });
-
-  it('requeues the survivor when the duplicate held the only scan', async () => {
-    // Otherwise the sole embeddings go with the purge and nothing re-queues:
-    // the photo just silently stops having a face.
-    await seedPair();
-    await knex('photo_faces').insert({ photo_id: 2, event_id: 1 });
-
-    await migration.up(knex);
-
-    expect((await knex('photos').where('id', 1).first()).face_status).toBe('pending');
-  });
-
-  it('carries the duplicate\'s views and downloads over', async () => {
-    await seedPair();
-    await knex('photos').where('id', 1).update({ view_count: 2, download_count: 1 });
-    await knex('photos').where('id', 2).update({ view_count: 5, download_count: 3 });
-
-    await migration.up(knex);
-
-    const survivor = await knex('photos').where('id', 1).first();
-    expect([survivor.view_count, survivor.download_count]).toEqual([7, 4]);
-  });
-
-  it('fails loudly rather than recording itself applied without the index', async () => {
-    // Swallowing a failed CREATE INDEX would leave the install permanently
-    // racy — the in-flight guard only covers one process — with nothing to
-    // trigger a retry. Driven through the helper the migration calls, against
-    // a table that still holds duplicates — i.e. what it would face if the
-    // dedupe above had not achieved uniqueness.
-    await seedPair();
-    const { createExternalRelpathIndex } = require('../../src/services/externalPhotoDedupe');
-
-    await expect(createExternalRelpathIndex(knex)).rejects.toThrow(/unique/i);
-  });
-
-  it('invalidates the pre-built download zip for the affected event', async () => {
-    // The cached archive still contains the rows just removed, and every
-    // ordinary photo-deletion path invalidates it for exactly that reason.
-    // getZipInfo treats a cleared record as a miss and rebuilds on request.
-    await seedPair();
-    await knex('events').insert({
-      id: 1, download_zip_path: 'events/active/x/.download-cache/all.zip',
-      download_zip_generated_at: '2026-01-01',
-    });
-
-    await migration.up(knex);
-
-    const ev = await knex('events').where('id', 1).first();
-    expect(ev.download_zip_path).toBeNull();
-    expect(ev.download_zip_generated_at).toBeNull();
-  });
-
-  it('leaves an untouched event\'s zip alone', async () => {
-    await seedPair();
-    await knex('events').insert([
-      { id: 1, download_zip_path: 'a.zip', download_zip_generated_at: '2026-01-01' },
-      { id: 2, download_zip_path: 'b.zip', download_zip_generated_at: '2026-01-01' },
-    ]);
-
-    await migration.up(knex);
-
-    expect((await knex('events').where('id', 2).first()).download_zip_path).toBe('b.zip');
-  });
-
-  it('is idempotent', async () => {
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/x.jpg', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-    const once = await rows();
-    await migration.up(knex);
-
-    expect(await rows()).toEqual(once);
-  });
-
-  it('rolls back to an unconstrained table', async () => {
-    await migration.up(knex);
-    await migration.down(knex);
-
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'a/x.jpg', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'a/x.jpg', source_origin: 'external' },
-    ]);
-    expect(await knex('photos').count('* as c').first()).toEqual({ c: 2 });
-  });
-
-  it('no-ops before 041 has added the column', async () => {
-    await knex.schema.dropTableIfExists('photos');
-    await knex.schema.createTable('photos', (t) => { t.increments('id').primary(); });
-
-    await expect(migration.up(knex)).resolves.toBeUndefined();
-  });
-});

backend/__tests__/migrations/177_external_relpath_from_root.test.js

@@ -1,364 +0,0 @@
-/**
- * Folding the event's base path into every external row (#1163).
- *
- * Two things can go wrong and both are silent, which is why they are pinned
- * here rather than left to review: folding a path that was ALREADY folded
- * (every original moves), and "repairing" a healthy install because the media
- * root happened to be unmounted when the migration ran (every original moves).
- *
- * The repair itself is driven against a real temp directory tree, because the
- * whole mechanism is "is this file actually there" and a mocked fs would only
- * be testing the mock.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-describe('migration 177 — external_relpath from the media root (#1163)', () => {
-  let knex; let tmpDir; let mediaRoot; let migration;
-
-  /** Writes `bytes` bytes and returns the size, so fixtures can record it the
-   *  way an import would have. */
-  const touch = async (rel, bytes = 8) => {
-    const full = path.join(mediaRoot, rel);
-    await fs.promises.mkdir(path.dirname(full), { recursive: true });
-    await fs.promises.writeFile(full, Buffer.alloc(bytes));
-    return bytes;
-  };
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-mig187-'));
-    mediaRoot = path.join(tmpDir, 'media');
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-    process.env.EXTERNAL_MEDIA_ROOT = mediaRoot;
-
-    // The service caches the root on first call, so it must not have been
-    // resolved before EXTERNAL_MEDIA_ROOT was set above.
-    jest.resetModules();
-    migration = require('../../migrations/core/177_external_relpath_from_root');
-
-    knex = require('knex')({
-      client: 'sqlite3',
-      connection: { filename: path.join(tmpDir, 'db.sqlite') },
-      useNullAsDefault: true,
-    });
-  });
-
-  afterAll(async () => {
-    if (knex) await knex.destroy();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-    delete process.env.EXTERNAL_MEDIA_ROOT;
-  });
-
-  beforeEach(async () => {
-    await knex.schema.dropTableIfExists('photos');
-    await knex.schema.dropTableIfExists('events');
-    await knex.schema.dropTableIfExists('app_settings');
-    await knex.schema.createTable('events', (t) => {
-      t.increments('id').primary();
-      t.string('external_path');
-    });
-    await knex.schema.createTable('photos', (t) => {
-      t.increments('id').primary();
-      t.integer('event_id');
-      t.string('external_relpath');
-      t.integer('size_bytes');
-      t.string('source_origin').defaultTo('managed');
-    });
-    await knex.schema.createTable('app_settings', (t) => {
-      t.increments('id').primary();
-      t.string('setting_key');
-      t.text('setting_value');
-      t.string('setting_type');
-      t.string('updated_at');
-    });
-    await fs.promises.rm(mediaRoot, { recursive: true, force: true });
-    await fs.promises.mkdir(mediaRoot, { recursive: true });
-  });
-
-  const relpaths = async () =>
-    (await knex('photos').orderBy('id', 'asc').select('external_relpath'))
-      .map((r) => r.external_relpath);
-
-  it('folds the base path into every row of a healthy event', async () => {
-    await touch('Trip/Leknes/a.jpg');
-    await touch('Trip/Leknes/b.jpg');
-    await knex('events').insert({ id: 1, external_path: 'Trip' });
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'Leknes/a.jpg', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'Leknes/b.jpg', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/Leknes/a.jpg', 'Trip/Leknes/b.jpg']);
-  });
-
-  it('repairs rows an earlier import had rebased', async () => {
-    // The reported shape: a parent imported first, a child imported second, so
-    // events.external_path is the child and the parent's rows resolve into a
-    // path that does not exist.
-    const oldSize = await touch('Trip/Leknes/old.jpg', 11);   // from the first import
-    const newSize = await touch('Trip/Sub/new.jpg', 22);      // from the second
-    await knex('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'Leknes/old.jpg', size_bytes: oldSize, source_origin: 'external' },
-      { event_id: 1, external_relpath: 'new.jpg', size_bytes: newSize, source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    // The old row is placed where the file actually is; the new one keeps
-    // resolving exactly where it resolved before.
-    expect(await relpaths()).toEqual(['Trip/Leknes/old.jpg', 'Trip/Sub/new.jpg']);
-  });
-
-  it('refuses an ancestor whose file is a different size', async () => {
-    // The dangerous case: the row's own file was simply deleted, and an
-    // UNRELATED file one directory up happens to share its name. Adopting it
-    // would make downloads serve the wrong original — worse than a dead link.
-    await touch('Trip/photo.jpg', 999);
-    await knex('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await knex('photos').insert({
-      event_id: 1, external_relpath: 'photo.jpg', size_bytes: 42, source_origin: 'external',
-    });
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/Sub/photo.jpg']);
-  });
-
-  it('refuses an ancestor when the row records no size to check against', async () => {
-    // Nothing to verify provenance with, so the row stays where it resolves
-    // today rather than adopting a same-named stranger.
-    await touch('Trip/photo.jpg', 100);
-    await knex('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await knex('photos').insert({
-      event_id: 1, external_relpath: 'photo.jpg', size_bytes: null, source_origin: 'external',
-    });
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/Sub/photo.jpg']);
-  });
-
-  it('leaves nothing folded when a rewrite fails partway', async () => {
-    // Without a transaction, a crash between the first event's UPDATE and the
-    // marker leaves mixed formats behind — and the next run folds the already
-    // folded rows a second time, putting every original one directory deeper.
-    await touch('A/one.jpg');
-    await touch('B/two.jpg');
-    await knex('events').insert([
-      { id: 1, external_path: 'A' },
-      { id: 2, external_path: 'B' },
-    ]);
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'one.jpg', source_origin: 'external' },
-      { event_id: 2, external_relpath: 'two.jpg', source_origin: 'external' },
-    ]);
-    // app_settings is written last, in the same transaction as the rewrites.
-    await knex.schema.dropTableIfExists('app_settings_backup');
-    await knex.raw('CREATE TRIGGER fail_marker BEFORE INSERT ON app_settings '
-      + "BEGIN SELECT RAISE(ABORT, 'boom'); END");
-
-    await expect(migration.up(knex)).rejects.toThrow(/boom/);
-
-    await knex.raw('DROP TRIGGER fail_marker');
-    // Every row still base-relative, and no marker — so a retry is correct.
-    expect(await relpaths()).toEqual(['one.jpg', 'two.jpg']);
-    expect(await knex('app_settings').where('setting_key', 'external_relpath_root_relative').first())
-      .toBeUndefined();
-  });
-
-  it('removes the losing row when two paths converge, instead of stranding it', async () => {
-    // Trip/Sub/c.jpg imported once via `Trip` (as `Sub/c.jpg`) and once via
-    // `Trip/Sub` (as `c.jpg`). Both fold to the same path. Skipping the loser
-    // would leave it base-relative under a root-only resolver — pointing at
-    // <root>/c.jpg — with the marker claiming the conversion is complete.
-    const size = await touch('Trip/Sub/c.jpg', 33);
-    await knex('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'Sub/c.jpg', size_bytes: size, source_origin: 'external' },
-      { event_id: 1, external_relpath: 'c.jpg', size_bytes: size, source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    const rows = await knex('photos').select('external_relpath');
-    expect(rows).toHaveLength(1);
-    expect(rows[0].external_relpath).toBe('Trip/Sub/c.jpg');
-  });
-
-  it('survives a final path that equals another row\'s current path', async () => {
-    // `photo.jpg` repairs to `Trip/photo.jpg` while the row already holding
-    // `Trip/photo.jpg` folds to `Trip/Sub/Trip/photo.jpg`. Every FINAL value is
-    // distinct, but a one-pass rewrite collides halfway through — and on
-    // Postgres that 23505 is misread by the migration runner as "already
-    // applied", leaving everything unconverted.
-    const a = await touch('Trip/photo.jpg', 11);
-    const b = await touch('Trip/Sub/Trip/photo.jpg', 22);
-    await knex('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'photo.jpg', size_bytes: a, source_origin: 'external' },
-      { event_id: 1, external_relpath: 'Trip/photo.jpg', size_bytes: b, source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/photo.jpg', 'Trip/Sub/Trip/photo.jpg']);
-  });
-
-  it('does not re-prefix a row inserted while the probe was running', async () => {
-    // Phase 1 runs outside the transaction and can take minutes on a cold
-    // mount. An import finishing in that window writes an already
-    // root-relative row, which a `where event_id` bulk update would prefix a
-    // second time with the stale base.
-    await touch('Trip/a.jpg');
-    await knex('events').insert({ id: 1, external_path: 'Trip' });
-    await knex('photos').insert({ event_id: 1, external_relpath: 'a.jpg', source_origin: 'external' });
-
-    const { foldExternalRelpaths } = require('../../src/services/externalRelpathFold');
-    const realStat = fs.promises.stat;
-    let injected = false;
-    jest.spyOn(fs.promises, 'access').mockImplementation(async (...args) => {
-      if (!injected) {
-        injected = true;
-        await knex('photos').insert({
-          event_id: 1, external_relpath: 'Trip/late.jpg', source_origin: 'external',
-        });
-      }
-      return realStat(args[0]).then(() => undefined);
-    });
-
-    await foldExternalRelpaths(knex);
-    fs.promises.access.mockRestore();
-
-    expect((await relpaths()).sort()).toEqual(['Trip/a.jpg', 'Trip/late.jpg']);
-  });
-
-  it('leaves a row it cannot place resolving where it resolves today', async () => {
-    // Never guess below current behaviour: a file that is genuinely gone must
-    // not have its path rewritten to some other file that happens to exist.
-    await touch('Trip/Sub/present.jpg');
-    await knex('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'present.jpg', source_origin: 'external' },
-      { event_id: 1, external_relpath: 'vanished.jpg', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/Sub/present.jpg', 'Trip/Sub/vanished.jpg']);
-  });
-
-  it('folds without repairing when the media root is unmounted', async () => {
-    // An unmounted share leaves the mountpoint as an empty directory, so every
-    // file looks missing. Repairing off that signal would move every original
-    // on a perfectly healthy install.
-    await knex('events').insert({ id: 1, external_path: 'Trip/Sub' });
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'Leknes/a.jpg', source_origin: 'external' },
-    ]);
-    // mediaRoot is empty — see beforeEach.
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/Sub/Leknes/a.jpg']);
-  });
-
-  it('leaves managed rows alone', async () => {
-    await touch('Trip/a.jpg');
-    await knex('events').insert({ id: 1, external_path: 'Trip' });
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: null, source_origin: 'managed' },
-      { event_id: 1, external_relpath: 'a.jpg', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual([null, 'Trip/a.jpg']);
-  });
-
-  it('leaves an event with no base path alone — its rows are already root-relative', async () => {
-    await touch('a.jpg');
-    await knex('events').insert({ id: 1, external_path: null });
-    await knex('photos').insert({ event_id: 1, external_relpath: 'a.jpg', source_origin: 'external' });
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['a.jpg']);
-  });
-
-  it('folds each event with its own base', async () => {
-    await touch('A/one.jpg');
-    await touch('B/two.jpg');
-    await knex('events').insert([
-      { id: 1, external_path: 'A' },
-      { id: 2, external_path: 'B' },
-    ]);
-    await knex('photos').insert([
-      { event_id: 1, external_relpath: 'one.jpg', source_origin: 'external' },
-      { event_id: 2, external_relpath: 'two.jpg', source_origin: 'external' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['A/one.jpg', 'B/two.jpg']);
-  });
-
-  it('tolerates a base path with stray slashes', async () => {
-    await touch('Trip/a.jpg');
-    await knex('events').insert({ id: 1, external_path: '/Trip/' });
-    await knex('photos').insert({ event_id: 1, external_relpath: 'a.jpg', source_origin: 'external' });
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/a.jpg']);
-  });
-
-  it('does not fold twice when run again', async () => {
-    // The failure this guards is total: every original on the install moves one
-    // directory deeper, and there is no undo.
-    await touch('Trip/a.jpg');
-    await knex('events').insert({ id: 1, external_path: 'Trip' });
-    await knex('photos').insert({ event_id: 1, external_relpath: 'a.jpg', source_origin: 'external' });
-
-    await migration.up(knex);
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/a.jpg']);
-  });
-
-  it('does not fold twice when the base repeats in the relpath', async () => {
-    // The inference this migration deliberately does NOT use: `Trip/x.jpg`
-    // under base `Trip` already "starts with the base", but has not been
-    // folded — it is a subfolder that shares its parent's name.
-    await touch('Trip/Trip/x.jpg');
-    await knex('events').insert({ id: 1, external_path: 'Trip' });
-    await knex('photos').insert({ event_id: 1, external_relpath: 'Trip/x.jpg', source_origin: 'external' });
-
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/Trip/x.jpg']);
-  });
-
-  it('rollback does not clear the marker, so a re-run cannot double-fold', async () => {
-    await touch('Trip/a.jpg');
-    await knex('events').insert({ id: 1, external_path: 'Trip' });
-    await knex('photos').insert({ event_id: 1, external_relpath: 'a.jpg', source_origin: 'external' });
-
-    await migration.up(knex);
-    await migration.down(knex);
-    await migration.up(knex);
-
-    expect(await relpaths()).toEqual(['Trip/a.jpg']);
-  });
-
-  it('no-ops before 041 has added the column', async () => {
-    await knex.schema.dropTableIfExists('photos');
-    await knex.schema.createTable('photos', (t) => { t.increments('id').primary(); });
-
-    await expect(migration.up(knex)).resolves.toBeUndefined();
-  });
-});

backend/__tests__/migrations/178_reset_legacy_preview_paths.test.js

@@ -1,83 +0,0 @@
-/**
- * Legacy preview keys must not survive the encoder change.
- *
- * The old generator kept the SOURCE basename verbatim while always writing
- * JPEG, so a `.webp` upload produced `preview_shot.webp` holding a JPEG. The
- * route now derives Content-Type from the key, and sets `nosniff` — so that
- * legacy object would be announced as image/webp and render as a broken image.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-const migration = require('../../migrations/core/178_reset_legacy_preview_paths');
-
-describe('migration 178 — legacy preview keys (#1166 follow-up)', () => {
-  let knex; let tmpDir;
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-mig188-'));
-    knex = require('knex')({
-      client: 'sqlite3',
-      connection: { filename: path.join(tmpDir, 'db.sqlite') },
-      useNullAsDefault: true,
-    });
-  });
-
-  afterAll(async () => {
-    if (knex) await knex.destroy();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(async () => {
-    await knex.schema.dropTableIfExists('photos');
-    await knex.schema.createTable('photos', (t) => {
-      t.increments('id').primary();
-      t.string('preview_path');
-      t.string('thumbnail_path');
-    });
-  });
-
-  it('clears the mislabelled .webp keys that would render broken', async () => {
-    await knex('photos').insert({ preview_path: 'previews/preview_shot.webp' });
-
-    await migration.up(knex);
-
-    expect((await knex('photos').first()).preview_path).toBeNull();
-  });
-
-  it('clears .jpg keys too, because a byte-correct one can still be flattened', async () => {
-    // A legacy .jpg key is valid JPEG, but it may be a flattened rendition of a
-    // transparent or animated source, and nothing in the key says so. One lazy
-    // regeneration is cheaper than reasoning about which of them lied.
-    await knex('photos').insert([
-      { preview_path: 'previews/preview_a.jpg' },
-      { preview_path: 'previews/preview_b.png' },
-    ]);
-
-    await migration.up(knex);
-
-    expect(await knex('photos').whereNotNull('preview_path').count('* as c').first()).toEqual({ c: 0 });
-  });
-
-  it('leaves thumbnails alone — they are a different cache', async () => {
-    await knex('photos').insert({ preview_path: 'previews/p.jpg', thumbnail_path: 'thumbnails/t.jpg' });
-
-    await migration.up(knex);
-
-    expect((await knex('photos').first()).thumbnail_path).toBe('thumbnails/t.jpg');
-  });
-
-  it('is idempotent and safe with nothing to clear', async () => {
-    await migration.up(knex);
-    await expect(migration.up(knex)).resolves.toBeUndefined();
-  });
-
-  it('no-ops before 104 has added the column', async () => {
-    await knex.schema.dropTableIfExists('photos');
-    await knex.schema.createTable('photos', (t) => { t.increments('id').primary(); });
-
-    await expect(migration.up(knex)).resolves.toBeUndefined();
-  });
-});

backend/__tests__/routes/adminEventQr.test.js

@@ -0,0 +1,122 @@
+/**
+ * HTTP tests for the gallery QR endpoints (#836):
+ *   GET /api/admin/events/:id/qr        (PNG / SVG)
+ *   GET /api/admin/events/:id/qr-print  (table-card / poster PDF)
+ * Same real-SQLite harness as adminEvents.smoke.test.js.
+ */
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-events-qr-')), 'db.sqlite'
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'admin-events-qr-test-secret';
+
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const request = require('supertest');
+const { bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken } = require('../integration/helpers/crmDb');
+
+async function insertEvent(db, adminId, over = {}) {
+  const base = {
+    slug: `ev-${Math.random().toString(16).slice(2)}`,
+    event_type: 'wedding',
+    event_name: 'QR Test Wedding',
+    event_date: '2026-05-29',
+    host_email: 'host@example.com',
+    admin_email: 'admin@example.com',
+    password_hash: 'x',
+    share_link: `/gallery/share-${Math.random().toString(16).slice(2)}`,
+    share_token: `st-${Math.random().toString(16).slice(2)}`,
+    expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+    is_active: 1, is_archived: 0, is_draft: 0,
+    created_by: adminId,
+    created_at: new Date().toISOString(),
+    ...over,
+  };
+  const r = await db('events').insert(base).returning('id');
+  return r[0]?.id ?? r[0];
+}
+
+describe('admin event QR endpoints', () => {
+  let db; let cleanup; let app; let adminId; let token;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ adminId } = await seedMinimal(db));
+    await assignAdminRole(db, adminId, 'super_admin');
+    token = mintAdminToken(adminId);
+
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/admin/events', require('../../src/routes/adminEvents'));
+    // eslint-disable-next-line no-unused-vars
+    app.use((err, req, res, next) => {
+      res.status(err.statusCode || err.status || 500).json({ error: err.message, code: err.code });
+    });
+  }, 120000);
+
+  afterAll(async () => { await cleanup(); });
+
+  beforeEach(async () => { await db('events').del(); });
+
+  const auth = (req) => req.set('Authorization', `Bearer ${token}`);
+
+  it('401s without an admin token', async () => {
+    const eventId = await insertEvent(db, adminId);
+    const res = await request(app).get(`/api/admin/events/${eventId}/qr`);
+    expect(res.status).toBe(401);
+  });
+
+  it('returns a PNG QR by default', async () => {
+    const eventId = await insertEvent(db, adminId);
+    const res = await auth(request(app).get(`/api/admin/events/${eventId}/qr`)).buffer();
+    expect(res.status).toBe(200);
+    expect(res.headers['content-type']).toBe('image/png');
+    // PNG magic bytes
+    expect(res.body.slice(0, 4)).toEqual(Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+  });
+
+  it('returns an SVG QR when requested', async () => {
+    const eventId = await insertEvent(db, adminId);
+    // supertest doesn't text-parse image/svg+xml — buffer and decode manually.
+    const res = await auth(request(app).get(`/api/admin/events/${eventId}/qr?format=svg`)).buffer();
+    expect(res.status).toBe(200);
+    expect(res.headers['content-type']).toMatch(/image\/svg\+xml/);
+    expect(Buffer.from(res.body).toString('utf8')).toContain('<svg');
+  });
+
+  it('sets attachment disposition with download=1', async () => {
+    const eventId = await insertEvent(db, adminId);
+    const res = await auth(request(app).get(`/api/admin/events/${eventId}/qr?download=1`)).buffer();
+    expect(res.headers['content-disposition']).toMatch(/^attachment/);
+  });
+
+  // 30s: the print PDFs embed the full IBM Plex Sans TTFs (~200 KB each) —
+  // font parsing + subsetting exceeds jest's 5s default on slower CI runners.
+  it.each(['table-card', 'poster'])('renders the %s print PDF', async (template) => {
+    const eventId = await insertEvent(db, adminId);
+    const res = await auth(
+      request(app).get(`/api/admin/events/${eventId}/qr-print?template=${template}&lang=de`)
+    ).buffer();
+    expect(res.status).toBe(200);
+    expect(res.headers['content-type']).toBe('application/pdf');
+    expect(res.body.slice(0, 4).toString()).toBe('%PDF');
+  }, 120000);
+
+  it('409s when the event has no share link', async () => {
+    // events.share_link is NOT NULL — an empty string is the closest real-world
+    // "no share link" shape (no token extractable from it either).
+    const eventId = await insertEvent(db, adminId, { share_link: '', share_token: null });
+    const res = await auth(request(app).get(`/api/admin/events/${eventId}/qr`));
+    expect(res.status).toBe(409);
+  });
+
+  it('404s for a non-existent event', async () => {
+    const res = await auth(request(app).get('/api/admin/events/999999/qr'));
+    expect(res.status).toBe(404);
+  });
+});

backend/__tests__/routes/adminEvents.smoke.test.js

@@ -201,6 +201,34 @@ describe('admin events CRUD endpoints (smoke)', () => {
       });
       expect(res.status).toBe(400);
     });
+
+    // #894 — per-event password-page logo toggle: false hides, null
+    // restores the default (show).
+    it('stores login_logo_visible: false and clears it back to NULL', async () => {
+      const id = await insertEvent(db, adminId);
+      const hide = await auth(request(app).put(`/api/admin/events/${id}`)).send({
+        login_logo_visible: false,
+      });
+      expect(hide.status).toBe(200);
+      let row = await db('events').where({ id }).first();
+      expect([false, 0]).toContain(row.login_logo_visible);
+
+      const clear = await auth(request(app).put(`/api/admin/events/${id}`)).send({
+        login_logo_visible: null,
+      });
+      expect(clear.status).toBe(200);
+      row = await db('events').where({ id }).first();
+      expect(row.login_logo_visible).toBeNull();
+
+      // The string "false" passes isBoolean() validation — it must be
+      // parsed, not treated as a truthy string (would store 1 = show).
+      const hideStr = await auth(request(app).put(`/api/admin/events/${id}`)).send({
+        login_logo_visible: 'false',
+      });
+      expect(hideStr.status).toBe(200);
+      row = await db('events').where({ id }).first();
+      expect([false, 0]).toContain(row.login_logo_visible);
+    });
   });
 
   describe('DELETE /:id', () => {

backend/__tests__/routes/adminRolesGuards.test.js

@@ -0,0 +1,86 @@
+/**
+ * Role-editor self-amplification guard (migration 175 / adminRoles).
+ *
+ * `roles.manage` must be a DELEGATION primitive, not root escalation: a
+ * non-super_admin holder can only grant permissions their OWN role already
+ * holds, and can't edit their own role. super_admin bypasses. Pins
+ * userManagementService.createRole / updateRole (assertActorMayGrant).
+ */
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-roleguard-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'roleguard-test-secret';
+process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-roleguard-storage-'));
+
+const { bootCrmDb, seedMinimal, assignAdminRole } = require('../integration/helpers/crmDb');
+const svc = require('../../src/services/userManagementService');
+const { clearPermissionCache } = require('../../src/middleware/permissions');
+
+describe('role editor — self-amplification guard', () => {
+  let db; let cleanup;
+  let superId; let mgrRoleId; let mgrId;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    ({ adminId: superId } = await seedMinimal(db));
+    await assignAdminRole(db, superId, 'super_admin');
+
+    // A non-super role that CAN manage roles but only holds a couple of perms.
+    const mgrRole = await svc.createRole(
+      { name: 'limited_mgr', permissions: ['roles.manage', 'events.view'] },
+      superId,
+    );
+    mgrRoleId = mgrRole.id;
+    const ins = await db('admin_users').insert({
+      username: 'mgr', email: 'mgr@example.com', password_hash: 'x',
+      role_id: mgrRoleId, must_change_password: false, created_at: new Date(),
+    }).returning('id');
+    mgrId = ins[0]?.id ?? ins[0];
+    clearPermissionCache();
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  it('super_admin can grant any permission', async () => {
+    const r = await svc.createRole(
+      { name: 'power_role', permissions: ['settings.banking', 'users.delete'] },
+      superId,
+    );
+    expect(r.permissions).toEqual(expect.arrayContaining(['settings.banking', 'users.delete']));
+  });
+
+  it('non-super cannot grant a permission its own role lacks', async () => {
+    await expect(
+      svc.createRole({ name: 'sneaky', permissions: ['events.view', 'settings.banking'] }, mgrId),
+    ).rejects.toThrow(/only grant permissions your own role/i);
+  });
+
+  it('non-super can create a role within its own permissions', async () => {
+    const r = await svc.createRole({ name: 'viewer_lite', permissions: ['events.view'] }, mgrId);
+    expect(r.permissions).toEqual(['events.view']);
+  });
+
+  it('non-super cannot edit its own role', async () => {
+    await expect(
+      svc.updateRole(mgrRoleId, { permissions: ['roles.manage', 'events.view'] }, mgrId),
+    ).rejects.toThrow(/cannot edit your own role/i);
+  });
+
+  it('non-super cannot escalate another role beyond its own permissions', async () => {
+    const adminRole = await db('roles').where({ name: 'admin' }).first();
+    await expect(
+      svc.updateRole(adminRole.id, { permissions: ['settings.banking'] }, mgrId),
+    ).rejects.toThrow(/only grant permissions your own role/i);
+  });
+
+  it('the built-in team_photographer name is reserved', async () => {
+    await expect(
+      svc.createRole({ name: 'team_photographer', permissions: [] }, superId),
+    ).rejects.toThrow(/reserved/i);
+  });
+});

backend/__tests__/routes/adminSettingsProtectedKeys.test.js

@@ -0,0 +1,95 @@
+/**
+ * Protected-key boundary on the generic settings writers (migration 175).
+ *
+ * A role with settings.edit but NOT settings.domains (the "office manager" this
+ * PR enables) must be able to save the General tab — which re-posts
+ * general_site_url on every save — as long as the URL is UNCHANGED, and must be
+ * 403'd only when it actually tries to change a protected key. Regression pin for
+ * the change-detection fix (the presence-only check over-fired on every save).
+ */
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-setkeys-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'setkeys-test-secret';
+process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-setkeys-storage-'));
+
+const request = require('supertest');
+const express = require('express');
+const cookieParser = require('cookie-parser');
+const {
+  bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken,
+} = require('../integration/helpers/crmDb');
+const svc = require('../../src/services/userManagementService');
+const { clearPermissionCache } = require('../../src/middleware/permissions');
+
+const STORED_URL = 'https://stored.example';
+
+describe('settings protected-key boundary (/general)', () => {
+  let db; let cleanup; let app;
+  let superTok; let mgrTok;
+
+  const auth = (req, tok) => req.set('Authorization', `Bearer ${tok}`);
+  const readSiteUrl = async () => {
+    const row = await db('app_settings').where({ setting_key: 'general_site_url' }).first();
+    return row ? JSON.parse(row.setting_value) : null;
+  };
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    const { adminId: superId } = await seedMinimal(db);
+    await assignAdminRole(db, superId, 'super_admin');
+    superTok = mintAdminToken(superId);
+
+    // Office-manager role: settings.view + settings.edit, NOT settings.domains.
+    const mgrRole = await svc.createRole(
+      { name: 'office_mgr', permissions: ['settings.view', 'settings.edit'] },
+      superId,
+    );
+    const ins = await db('admin_users').insert({
+      username: 'office', email: 'office@example.com', password_hash: 'x',
+      role_id: mgrRole.id, must_change_password: false, created_at: new Date(),
+    }).returning('id');
+    mgrTok = mintAdminToken(ins[0]?.id ?? ins[0]);
+
+    await db('app_settings').insert({
+      setting_key: 'general_site_url', setting_value: JSON.stringify(STORED_URL), setting_type: 'general',
+    });
+    clearPermissionCache();
+
+    app = express();
+    app.use(express.json());
+    app.use(cookieParser());
+    app.use('/api/admin/settings', require('../../src/routes/adminSettings'));
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  it('settings.edit role can save /general when general_site_url is unchanged', async () => {
+    const res = await auth(request(app).put('/api/admin/settings/general'), mgrTok)
+      .send({ general_site_url: STORED_URL, general_max_file_size_mb: 50 });
+    expect(res.status).not.toBe(403);
+    expect(res.status).toBe(200);
+    expect(await readSiteUrl()).toBe(STORED_URL);
+  });
+
+  it('settings.edit role is 403d when it actually changes general_site_url', async () => {
+    const res = await auth(request(app).put('/api/admin/settings/general'), mgrTok)
+      .send({ general_site_url: 'https://evil.example' });
+    expect(res.status).toBe(403);
+    expect(res.body.code).toBe('FORBIDDEN');
+    expect(res.body.keys.map((k) => k.key)).toContain('general_site_url');
+    expect(await readSiteUrl()).toBe(STORED_URL); // unchanged
+  });
+
+  it('super_admin can change general_site_url', async () => {
+    const res = await auth(request(app).put('/api/admin/settings/general'), superTok)
+      .send({ general_site_url: 'https://new.example' });
+    expect(res.status).toBe(200);
+    expect(await readSiteUrl()).toBe('https://new.example');
+  });
+});

backend/__tests__/routes/adminThumbnails.previewColumns.test.js

@@ -1,42 +0,0 @@
-/**
- * Source-inspection contract test for #1078.
- *
- * POST /api/admin/thumbnails/regenerate-previews hands its selected rows to
- * ensurePreviewImage, which branches on `source_origin` (and then reads
- * `external_relpath` / `filename`) to reach an external/reference photo on its
- * media mount. When the select list omitted those columns, every external row
- * looked managed, resolvePhotoStorageKey returned null, and the endpoint
- * reported success while silently generating nothing for reference galleries.
- */
-const fs = require('fs');
-const path = require('path');
-
-describe('regenerate-previews selects the columns ensurePreviewImage branches on (#1078)', () => {
-  const src = fs.readFileSync(
-    path.join(__dirname, '..', '..', 'src', 'routes', 'adminThumbnails.js'),
-    'utf8',
-  );
-
-  // The select feeding the regenerate-previews handler, from the route
-  // declaration to the end of that statement.
-  const selectStatement = (() => {
-    const routeIdx = src.indexOf('/regenerate-previews');
-    expect(routeIdx).toBeGreaterThan(-1);
-    const selectIdx = src.indexOf('.select(', routeIdx);
-    expect(selectIdx).toBeGreaterThan(-1);
-    return src.slice(selectIdx, src.indexOf(';', selectIdx));
-  })();
-
-  it.each(['source_origin', 'external_relpath', 'filename'])(
-    'selects %s',
-    (column) => {
-      expect(selectStatement).toContain(`'${column}'`);
-    }
-  );
-
-  it('still selects the columns the managed path needs', () => {
-    for (const column of ['id', 'event_id', 'path', 'media_type', 'mime_type', 'preview_path']) {
-      expect(selectStatement).toContain(`'${column}'`);
-    }
-  });
-});

backend/__tests__/routes/authSession.symmetry.test.js

@@ -32,9 +32,17 @@ jest.mock('../../src/database/db', () => {
     if (table === 'admin_users') {
       let rowFilter = () => true;
       return {
+        // The session route joins roles for the adminUser payload (#798);
+        // fake rows carry no role fields, so the join is a pass-through.
+        leftJoin() {
+          return this;
+        },
         where(criteria) {
           rowFilter = (row) => {
-            return Object.entries(criteria).every(([k, v]) => {
+            return Object.entries(criteria).every(([rawKey, v]) => {
+              // Joined queries prefix columns ('admin_users.id') — the fake
+              // rows use bare names.
+              const k = rawKey.replace(/^admin_users\./, '');
               if (k === 'is_active') return Boolean(row.is_active) === Boolean(v);
               return row[k] === v;
             });
@@ -50,7 +58,12 @@ jest.mock('../../src/database/db', () => {
           if (!row) return undefined;
           if (!this._cols) return row;
           const out = {};
-          for (const c of this._cols) out[c] = row[c];
+          for (const c of this._cols) {
+            // Support 'table.col' and 'table.col as alias' shapes.
+            const [source, alias] = c.split(/\s+as\s+/i);
+            const bare = source.includes('.') ? source.split('.').pop() : source;
+            out[alias || bare] = row[bare];
+          }
           return out;
         },
       };
@@ -135,9 +148,9 @@ function signAdminToken({ id = 1, username = 'admin', iat, exp }) {
   );
 }
 
-function signGalleryToken({ eventId = 100, eventSlug = 'wedding', ...extra } = {}) {
+function signGalleryToken({ eventId = 100, eventSlug = 'wedding' } = {}) {
   return jwt.sign(
-    { eventId, eventSlug, type: 'gallery', ...extra },
+    { eventId, eventSlug, type: 'gallery' },
     process.env.JWT_SECRET,
     { expiresIn: '1h', issuer: 'picpeak-auth' }
   );
@@ -288,56 +301,6 @@ describe('GET /auth/session — symmetry with protected middleware', () => {
     expect(res.body.valid).toBe(true);
   });
 
-  /**
-   * What KIND of gallery session this is (#1149).
-   *
-   * The frontend used to keep this in sessionStorage, which is per-TAB while
-   * the cookie is per-browser: a gallery reopened in a second tab lost
-   * 'client' even though the backend still served it as one, and the UI hid
-   * the only control that clears the privileged cookie. Reported from the
-   * token so a restored session knows what it actually is.
-   */
-  describe('gallery session kind', () => {
-    beforeEach(() => {
-      fakeDb.events.push({
-        id: 100,
-        slug: 'wedding',
-        is_active: true,
-        is_archived: false,
-        expires_at: new Date(Date.now() + 86400_000),
-      });
-    });
-
-    it('reports a PIN-client session as client', async () => {
-      const res = await request(makeApp())
-        .get('/auth/session?slug=wedding')
-        .set('Authorization', `Bearer ${signGalleryToken({ accessLevel: 'client' })}`);
-      expect(res.body.valid).toBe(true);
-      expect(res.body.accessLevel).toBe('client');
-      expect(res.body.viaCustomer).toBe(false);
-    });
-
-    it('reports a customer-portal session, which looks like a guest', async () => {
-      const res = await request(makeApp())
-        .get('/auth/session?slug=wedding')
-        .set('Authorization', `Bearer ${signGalleryToken({ via: 'customer', customerId: 7 })}`);
-      expect(res.body.valid).toBe(true);
-      expect(res.body.accessLevel).toBe('guest');
-      expect(res.body.viaCustomer).toBe(true);
-    });
-
-    it('reports a plain guest as neither', async () => {
-      // The flags have to discriminate, or they would just hand every visitor
-      // a Logout button back.
-      const res = await request(makeApp())
-        .get('/auth/session?slug=wedding')
-        .set('Authorization', `Bearer ${signGalleryToken()}`);
-      expect(res.body.valid).toBe(true);
-      expect(res.body.accessLevel).toBe('guest');
-      expect(res.body.viaCustomer).toBe(false);
-    });
-  });
-
   it('returns valid:false when the token is revoked', async () => {
     fakeDb.adminUsers.push({
       id: 1,

backend/__tests__/routes/authzPermissionGaps.test.js

@@ -51,11 +51,13 @@ describe('authorization / ownership gaps', () => {
     }).returning('id');
     adminId = ins[0]?.id ?? ins[0];
     await assignAdminRole(db, adminId, 'admin');
-    // Grant settings.edit to the admin role BEFORE any request populates the
-    // 60s permission cache, so the revoke test exercises the ownership check
-    // (404) rather than the missing-permission gate (403). This models a
-    // custom role that carries settings.edit — the scenario GHSA-gprq needs.
-    await grantPermissionToRole('admin', 'settings.edit');
+    // Grant settings.integrations to the admin role BEFORE any request populates
+    // the 60s permission cache, so the revoke test exercises the ownership check
+    // (404) rather than the missing-permission gate (403). Migration 174 split
+    // API-token management out of the catch-all settings.edit into the dedicated
+    // settings.integrations perm; this models a custom role that carries it —
+    // the scenario GHSA-gprq needs.
+    await grantPermissionToRole('admin', 'settings.integrations');
     adminTok = mintAdminToken(adminId);
 
     app = express();
@@ -96,7 +98,7 @@ describe('authorization / ownership gaps', () => {
       expect(res.body.find((t) => t.id === superTokenId)).toBeDefined();
     });
 
-    it('a non-owner (with settings.edit) cannot revoke another admin\'s token', async () => {
+    it('a non-owner (with settings.integrations) cannot revoke another admin\'s token', async () => {
       const res = await auth(request(app).delete(`/api/admin/api-tokens/${superTokenId}`), adminTok);
       expect(res.status).toBe(404);
       const row = await db('api_tokens').where({ id: superTokenId }).first();

backend/__tests__/routes/dashboardScope.test.js

@@ -127,44 +127,7 @@ describe('dashboard scoping (GHSA-c2jj / gqx7 / jhcf)', () => {
     expect(res.status).toBe(200);
     expect(Number(res.body.totalEvents)).toBe(1);
     expect(Number(res.body.totalPhotos)).toBe(1);
-    // The catalogued original bytes — this is what carries the per-event
-    // scoping, and what `storageUsed` reported before #1164.
-    expect(Number(res.body.catalogedBytes)).toBe(1000);
-  });
-
-  it('/stats reports disk usage unscoped, because disk is not per-event', async () => {
-    // storageUsed is a measurement of the storage root (#1164), so it is the
-    // same number for every admin by design. Pinned so a future reviewer
-    // reading "everything on this endpoint is scoped" does not turn it into a
-    // sum of this editor's photos again — which is the bug that was fixed.
-    const res = await request(app)
-      .get('/api/admin/dashboard/stats')
-      .set('Authorization', `Bearer ${editorToken}`);
-
-    expect(res.status).toBe(200);
-    expect(res.body.storageUsed).not.toBe(1000);
-    expect(res.body).toHaveProperty('storageBreakdown');
-  });
-
-  it('/stats reports the catalogued figure on an S3 backend, not a near-zero disk walk', async () => {
-    // STORAGE_PATH holds only incidental local files when objects live in a
-    // bucket, so walking it would report near-zero and drag the soft-limit
-    // recommendation with it.
-    const prev = process.env.STORAGE_BACKEND;
-    process.env.STORAGE_BACKEND = 's3';
-    try {
-      const res = await request(app)
-        .get('/api/admin/dashboard/stats')
-        .set('Authorization', `Bearer ${editorToken}`);
-
-      expect(res.status).toBe(200);
-      expect(res.body.storageUsed).toBeNull();
-      expect(res.body.storageMeasurement).toBe('catalog');
-      expect(Number(res.body.catalogedBytes)).toBe(1000);
-    } finally {
-      if (prev === undefined) delete process.env.STORAGE_BACKEND;
-      else process.env.STORAGE_BACKEND = prev;
-    }
+    expect(Number(res.body.storageUsed)).toBe(1000);
   });
 
   it('/analytics does not expose a foreign gallery name or slug', async () => {

backend/__tests__/routes/gallerySqliteBooleanFlags.test.js

@@ -10,9 +10,6 @@
  *   if (allow_downloads === false)  → never fires, so ALL download endpoints
  *                                     kept serving with downloads switched off
  *
- * (The download-jobs route asserted on main is #858, which is beta-only —
- * this branch covers the three download endpoints that exist here.)
- *
  * The harness runs on SQLite, so these assertions exercise the real engine
  * values rather than a mock. Every test here fails on the unfixed code.
  */
@@ -126,6 +123,11 @@ describe('gallery flags survive SQLite 0/1 storage (#1028)', () => {
         .send({ photo_ids: [photoId] });
       expect(res.status).toBe(403);
     });
+
+    test('download-jobs is refused', async () => {
+      const res = await request(app).post(`/api/gallery/${SLUG}/download-jobs`).send({});
+      expect(res.status).toBe(403);
+    });
   });
 
   describe('with downloads enabled (allow_downloads = 1)', () => {

backend/__tests__/routes/gallerySqliteCaptureSort.test.js

@@ -1,170 +0,0 @@
-/**
- * "Date Taken" ordering across SQLite's storage classes (#1172).
- *
- * photos.captured_at does not hold one type on SQLite. Three writers put three
- * different things in it:
- *
- *   integer  managed uploads — photoProcessor.js:441 hands knex a Date, which
- *            the sqlite3 binding stores as epoch milliseconds
- *   text     external imports and the capture-date backfill, which write
- *            ISO-8601 ('2026-06-03T01:15:00.000Z')
- *   null     no capture date, so the sort falls through to uploaded_at —
- *            itself text, in knex's 'YYYY-MM-DD HH:MM:SS' shape
- *
- * A plain COALESCE over that mixture is not an ordering. SQLite sorts INTEGER
- * before TEXT unconditionally, so every managed photo carrying EXIF came back
- * ahead of every photo that did not, whatever the dates said. And among the
- * text values 'T' (0x54) outranks the space (0x20), so a same-day ISO 01:15
- * sorted behind a fallback 23:00.
- *
- * Both failures predate #1172 — the first needs only two managed photos — but
- * the sort is what that issue is about, so they are fixed and pinned here.
- * Every test below fails on the unfixed ORDER BY.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-process.env.NODE_ENV = 'test';
-process.env.TEST_DATABASE_PATH = path.join(
-  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-capsort-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'capsort-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-capsort-storage-'));
-
-const request = require('supertest');
-const express = require('express');
-const cookieParser = require('cookie-parser');
-const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
-
-const SLUG = 'capsort-gallery';
-
-describe('capture-date ordering on SQLite (#1172)', () => {
-  let db; let cleanup; let app; let eventId;
-
-  // Managed uploads store an epoch-millisecond INTEGER, because
-  // photoProcessor.js:441 hands knex a Date and the sqlite3 binding converts
-  // it. That conversion cannot be reproduced from inside jest — there the
-  // binding's type dispatch misses sandbox-created Dates and writes the string
-  // "[object Object]" instead (CLAUDE.md). Verified outside jest: a Date lands
-  // as {"c":1830211200000,"ty":"integer"}. So these tests write the integer
-  // production would have written, rather than a Date that jest mangles.
-  const managed = (iso) => new Date(iso).getTime();
-
-  const addPhoto = async (filename, capturedAt, uploadedAt) => {
-    const row = await db('photos').insert({
-      event_id: eventId,
-      filename,
-      path: `${SLUG}/${filename}`,
-      type: 'individual',
-      captured_at: capturedAt,
-      uploaded_at: uploadedAt,
-    }).returning('id');
-    return row[0]?.id ?? row[0];
-  };
-
-  const orderedFilenames = async (order = 'asc') => {
-    const res = await request(app).get(`/api/gallery/${SLUG}/photos?sort=capture_date&order=${order}`);
-    expect(res.status).toBe(200);
-    return res.body.photos.map((p) => p.filename);
-  };
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-
-    const ev = await db('events').insert({
-      slug: SLUG,
-      event_type: 'wedding',
-      event_name: 'Capture Sort',
-      event_date: '2026-08-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: `/gallery/${SLUG}/s`,
-      share_token: 'capsort-share',
-      expires_at: new Date(Date.now() + 7 * 864e5).toISOString(),
-      is_active: 1,
-      is_archived: 0,
-      is_draft: 0,
-      require_password: 0,
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    eventId = ev[0]?.id ?? ev[0];
-
-    app = express();
-    app.use(express.json());
-    app.use(cookieParser());
-    app.use('/api/gallery', require('../../src/routes/gallery'));
-  }, 120000);
-
-  afterAll(async () => { if (cleanup) await cleanup(); });
-
-  beforeEach(async () => { await db('photos').where({ event_id: eventId }).del(); });
-
-  test('the fixture really does put three storage classes in one column', async () => {
-    expect(['sqlite3', 'better-sqlite3']).toContain(db.client.config.client);
-    await addPhoto('m.jpg', managed('2026-06-03T01:15:00Z'), '2026-01-01 00:00:00');
-    await addPhoto('e.jpg', '2020-01-01T00:00:00.000Z', '2026-01-01 00:00:00');
-    await addPhoto('n.jpg', null, '2026-01-01 00:00:00');
-
-    const rows = await db.raw('select filename, typeof(captured_at) as t from photos order by filename');
-    const byName = Object.fromEntries((rows.rows || rows).map((r) => [r.filename, r.t]));
-    // Exactly the mixture that made COALESCE meaningless.
-    expect(byName).toEqual({ 'm.jpg': 'integer', 'e.jpg': 'text', 'n.jpg': 'null' });
-  });
-
-  test('a managed EXIF date does not outrank an earlier one stored as text', async () => {
-    // The pre-existing failure, reachable with managed photos alone: integer
-    // beat text regardless of the dates, so this came back exactly reversed.
-    await addPhoto('managed-2027.jpg', managed('2027-12-31T00:00:00Z'), '2026-01-01 00:00:00');
-    await addPhoto('external-2020.jpg', '2020-01-01T00:00:00.000Z', '2026-01-01 00:00:00');
-
-    expect(await orderedFilenames('asc')).toEqual(['external-2020.jpg', 'managed-2027.jpg']);
-    expect(await orderedFilenames('desc')).toEqual(['managed-2027.jpg', 'external-2020.jpg']);
-  });
-
-  test('a photo with no capture date sorts by its upload time, not ahead of everything', async () => {
-    await addPhoto('has-exif-2027.jpg', managed('2027-12-31T00:00:00Z'), '2027-12-31 00:00:00');
-    await addPhoto('no-exif-2020.jpg', null, '2020-01-01 00:00:00');
-
-    expect(await orderedFilenames('asc')).toEqual(['no-exif-2020.jpg', 'has-exif-2027.jpg']);
-  });
-
-  test('an ISO capture time and a fallback upload time compare by clock, not by separator', async () => {
-    // Same day: 'T' vs ' ' decided this before, so 01:15 sorted after 23:00.
-    await addPhoto('iso-0115.jpg', '2026-06-03T01:15:00.000Z', '2026-06-03 05:00:00');
-    await addPhoto('fallback-2300.jpg', null, '2026-06-03 23:00:00');
-
-    expect(await orderedFilenames('asc')).toEqual(['iso-0115.jpg', 'fallback-2300.jpg']);
-  });
-
-  test('an epoch-integer uploaded_at is compared as a date, not as its digits', async () => {
-    // uploaded_at is not always text either: a legacy archive restore leaves
-    // epoch milliseconds in it (a .picpeak restore from an install that stored them that way).
-    // Reading that with substr() would have compared the string '1830297600000'
-    // against '2020-01-01 00:00:00', putting the 2028 row first.
-    await addPhoto('epoch-upload-2028.jpg', null, new Date('2028-01-01T00:00:00Z').getTime());
-    await addPhoto('captured-2020.jpg', managed('2020-01-01T00:00:00Z'), '2020-01-01 00:00:00');
-
-    const [row] = await db.raw('select typeof(uploaded_at) as t from photos where filename = \'epoch-upload-2028.jpg\'');
-    expect((row.t || row).toString()).toBe('integer');
-
-    expect(await orderedFilenames('asc')).toEqual(['captured-2020.jpg', 'epoch-upload-2028.jpg']);
-  });
-
-  test('all three storage classes order together correctly', async () => {
-    await addPhoto('c-managed-2026-08.jpg', managed('2026-08-15T12:00:00Z'), '2026-09-01 00:00:00');
-    await addPhoto('a-external-2026-06.jpg', '2026-06-03T01:15:00.000Z', '2026-09-01 00:00:00');
-    await addPhoto('d-fallback-2026-09.jpg', null, '2026-09-01 00:00:00');
-    await addPhoto('b-managed-2026-07.jpg', managed('2026-07-04T09:30:00Z'), '2026-09-01 00:00:00');
-
-    expect(await orderedFilenames('asc')).toEqual([
-      'a-external-2026-06.jpg',
-      'b-managed-2026-07.jpg',
-      'c-managed-2026-08.jpg',
-      'd-fallback-2026-09.jpg',
-    ]);
-  });
-});

backend/__tests__/routes/slideshowPublic.test.js

@@ -67,10 +67,11 @@ async function insertEvent(db, over = {}) {
 describe('public Live Slideshow routes', () => {
   let db; let cleanup; let app;
 
-  // bootCrmDb runs the full migration set against a fresh SQLite file and the
-  // chain keeps growing via backports. Hook-argument timeouts OVERRIDE the
-  // 120s jest.config default (same trap as the jest.setTimeout pins) — keep
-  // this at 120000, matching the config.
+  // bootCrmDb runs the full migration set against a fresh SQLite file. The
+  // chain keeps growing, and a 30s pin here blocked the 3.97.0-beta.0
+  // release PR on a slow runner. Hook-argument timeouts OVERRIDE the 120s
+  // jest.config default (same trap as the jest.setTimeout pins raised in
+  // #860) — keep this at 120000, matching the config.
   beforeAll(async () => {
     ({ db, cleanup } = await bootCrmDb());
     await seedMinimal(db);
@@ -98,7 +99,12 @@ describe('public Live Slideshow routes', () => {
     await setFlag(db, 'slideshow', true);
   });
 
-  const stateUrl = (token = TOKEN) => `/api/gallery/${SLUG}/show/${token}/state`;
+  // QR overlay: supertest's Host is loopback, and a loopback base is now
+  // suppressed rather than encoded — the kiosk passes its reachable
+  // window.location.origin, so the QR tests do the same.
+  const KIOSK_ORIGIN = 'https://gallery.example.com';
+  const stateUrl = (token = TOKEN) => `/api/gallery/${SLUG}/show/${token}/state?origin=${encodeURIComponent(KIOSK_ORIGIN)}`;
+  const stateUrlNoOrigin = (token = TOKEN) => `/api/gallery/${SLUG}/show/${token}/state`;
 
   describe('resolveSlideshow guards', () => {
     it('200 + per-event display settings on a live link', async () => {
@@ -227,6 +233,58 @@ describe('public Live Slideshow routes', () => {
     });
   });
 
+  describe('slideshowSettings — QR overlay cascade (#837)', () => {
+    async function enableGlobalQr() {
+      await setSetting(db, 'slideshow_qr_enabled', true);
+      await setSetting(db, 'slideshow_qr_position', 'top-right');
+      await setSetting(db, 'slideshow_qr_opacity', 80);
+      await setSetting(db, 'slideshow_qr_size', 18);
+    }
+
+    it('inherits the global QR overlay when show_qr is NULL', async () => {
+      await insertEvent(db, { show_qr: null });
+      await enableGlobalQr();
+      const res = await request(app).get(stateUrl());
+      expect(res.body.qr).toMatchObject({
+        position: 'top-right',
+        opacity: 80,
+        size: 18,
+      });
+      // Share-link QR ships as a PNG data URI — no client QR lib needed.
+      expect(res.body.qr.data_url).toMatch(/^data:image\/png;base64,/);
+    });
+
+    it('is null by default (global off, no override)', async () => {
+      await insertEvent(db, { show_qr: null });
+      const res = await request(app).get(stateUrl());
+      expect(res.body.qr).toBeNull();
+    });
+
+    it('per-event OFF override hides the QR even when the global is on', async () => {
+      await insertEvent(db, { show_qr: 0 });
+      await enableGlobalQr();
+      const res = await request(app).get(stateUrl());
+      expect(res.body.qr).toBeNull();
+    });
+
+    it('per-event ON override shows the QR even when the global is off', async () => {
+      await insertEvent(db, { show_qr: 1 });
+      const res = await request(app).get(stateUrl());
+      expect(res.body.qr).not.toBeNull();
+      expect(res.body.qr.data_url).toMatch(/^data:image\/png;base64,/);
+      // Look falls back to the global defaults.
+      expect(res.body.qr.position).toBe('bottom-left');
+    });
+
+    it('suppresses the QR when no guest-reachable origin exists (loopback base, no kiosk origin)', async () => {
+      await insertEvent(db, { show_qr: 1 });
+      const res = await request(app).get(stateUrlNoOrigin());
+      // Encoding localhost would send scanning phones to THEIR localhost —
+      // no QR beats a broken QR (codex review of #848, confirmation round).
+      expect(res.body.qr).toBeNull();
+    });
+  });
+
   describe('display-only token guards (#646 review concern 1)', () => {
     // Mint a real slideshow JWT, then prove it is denied on the
     // download / upload / feedback routes (display-only contract).

backend/__tests__/services/businessDocsStoragePath.test.js

@@ -1,159 +0,0 @@
-/**
- * Regression test: business documents must be written under STORAGE_PATH.
- *
- * quoteService.persistDocPdf, the invoice sending/reminder writers and the
- * contract signature writers all built their target from
- * `path.join(process.cwd(), 'storage', 'business-docs', ...)`. Both compose
- * files pin STORAGE_PATH=/app/storage and the image's WORKDIR is /app, so the
- * two expressions name the same directory and the bug was invisible on a stock
- * deployment. Point STORAGE_PATH anywhere else — a NAS mount, a second disk,
- * the single-container image's /data volume — and quotes, invoices, Mahnungen
- * and contract PDFs were written outside the configured storage root, so they
- * were missed by backups and lost when the container was replaced.
- *
- * Rather than assert on internals, this drives the module boundary the fix
- * changed: getStoragePath() is the one resolver, so a temporary STORAGE_PATH
- * must be where the bytes land.
- */
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-describe('business documents honour STORAGE_PATH', () => {
-  let tmpRoot;
-  let originalStoragePath;
-
-  beforeEach(() => {
-    originalStoragePath = process.env.STORAGE_PATH;
-    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-storage-'));
-    process.env.STORAGE_PATH = tmpRoot;
-    jest.resetModules();
-  });
-
-  afterEach(() => {
-    if (originalStoragePath === undefined) delete process.env.STORAGE_PATH;
-    else process.env.STORAGE_PATH = originalStoragePath;
-    fs.rmSync(tmpRoot, { recursive: true, force: true });
-  });
-
-  it('getStoragePath is the resolver the writers share', () => {
-    const { getStoragePath } = require('../../src/config/storage');
-    expect(getStoragePath()).toBe(tmpRoot);
-  });
-
-  it('no business-document writer still targets process.cwd()/storage', () => {
-    // Whitespace is collapsed before matching on purpose. The first version of
-    // this test compared against the single-line literal and therefore missed
-    // persistSignatureImage(), whose identical path.join was simply spread over
-    // seven lines — it reported green while signature PNGs still wrote outside
-    // STORAGE_PATH. Formatting must not decide whether a bug is visible.
-    const writers = [
-      'src/services/quoteService.js',
-      'src/services/invoice/sending.js',
-      'src/services/invoice/reminders.js',
-      'src/services/contract/signatureAssets.js',
-      'src/routes/adminDev.js',
-    ];
-    const offenders = writers.filter((rel) => {
-      const source = fs.readFileSync(path.join(__dirname, '../../', rel), 'utf8');
-      return /process\.cwd\(\),'storage'/.test(source.replace(/\s+/g, ''));
-    });
-    expect(offenders).toEqual([]);
-  });
-
-  it('generated contract PDFs pass the containment check that serves them', () => {
-    // assertContractPdfPath guards the admin and public contract download
-    // routes. It listed only <cwd>/storage/business-docs/contract, so once the
-    // writers moved to STORAGE_PATH every freshly generated contract was
-    // refused with PATH_OUTSIDE_STORAGE — a worse failure than the bug being
-    // fixed. Both roots must be accepted.
-    const { assertContractPdfPath } = require('../../src/utils/safePath');
-    const { getStoragePath } = require('../../src/config/storage');
-
-    // assertPathInside realpaths both the file and each root, so the guard only
-    // means anything against a filesystem that actually has them — write them.
-    const write = (...segments) => {
-      const p = path.join(getStoragePath(), 'business-docs', 'contract', ...segments);
-      fs.mkdirSync(path.dirname(p), { recursive: true });
-      fs.writeFileSync(p, 'bytes');
-      return p;
-    };
-
-    const generated = write('2026', 'C-2026-0001.pdf');
-    expect(() => assertContractPdfPath(generated)).not.toThrow();
-
-    // Signature PNGs live under the same root and are served by the same guard.
-    const signature = write('signatures', '7', 'customer-1.png');
-    expect(() => assertContractPdfPath(signature)).not.toThrow();
-
-    // And the guard still refuses a real file outside every allowed root.
-    const foreign = path.join(tmpRoot, 'outside.pdf');
-    fs.writeFileSync(foreign, 'bytes');
-    expect(() => assertContractPdfPath(foreign)).toThrow(/outside the storage roots/i);
-  });
-
-  it('the guard takes its root from the shared resolver, not its own fallback', () => {
-    // The regression this pins: the guard used to compute
-    // `STORAGE_PATH || <cwd>/storage` itself. That agrees with getStoragePath()
-    // only while STORAGE_PATH is set — unset, the shared resolver falls back
-    // module-relative to <repo>/storage while the guard fell back to
-    // <cwd>/storage, and the backend is normally started from backend/. Writers
-    // and guard then disagreed and contract downloads 403'd.
-    //
-    // Mocking the resolver is what makes this provable AND safe. If the guard
-    // consumes getStoragePath(), the mock moves its root; if it rolled its own
-    // expression, the mock would have no effect and the assertion fails. It
-    // also keeps every path inside the tmpdir — an earlier version of this test
-    // deleted `<resolved root>/business-docs` in cleanup, which with
-    // STORAGE_PATH unset resolves to a developer's real, gitignored
-    // <repo>/storage and would have destroyed local documents on `npm test`.
-    jest.resetModules();
-    jest.doMock('../../src/config/storage', () => ({ getStoragePath: () => tmpRoot }));
-
-    const { assertContractPdfPath } = require('../../src/utils/safePath');
-
-    const root = path.join(tmpRoot, 'business-docs', 'contract', '2026');
-    fs.mkdirSync(root, { recursive: true });
-    const generated = path.join(root, 'C-2026-0002.pdf');
-    fs.writeFileSync(generated, 'bytes');
-
-    expect(() => assertContractPdfPath(generated)).not.toThrow();
-
-    jest.dontMock('../../src/config/storage');
-  });
-
-  it('writes land under STORAGE_PATH, not the working directory', () => {
-    const { getStoragePath } = require('../../src/config/storage');
-
-    // Mirror what persistDocPdf does: derive the root, create it, write.
-    const root = path.join(getStoragePath(), 'business-docs', 'quote', '2026');
-    fs.mkdirSync(root, { recursive: true });
-    const filePath = path.join(root, 'Q-2026-0001.pdf');
-    fs.writeFileSync(filePath, 'pdf-bytes');
-
-    expect(fs.existsSync(filePath)).toBe(true);
-    expect(filePath.startsWith(tmpRoot)).toBe(true);
-    // And crucially NOT beside the process working directory.
-    expect(filePath.startsWith(path.join(process.cwd(), 'storage'))).toBe(false);
-  });
-
-  it('the PDF font lookup consults the storage root before the legacy path', () => {
-    // A custom font under STORAGE_PATH/fonts used to be unreachable, so the
-    // document silently rendered with the built-in face instead.
-    const fontDir = path.join(tmpRoot, 'fonts');
-    fs.mkdirSync(fontDir, { recursive: true });
-    const fontPath = path.join(fontDir, 'Brand.ttf');
-    fs.writeFileSync(fontPath, 'ttf');
-
-    const { getStoragePath } = require('../../src/config/storage');
-    const raw = 'Brand.ttf';
-    const candidates = [
-      path.join(getStoragePath(), raw.replace(/^\/+/, '')),
-      path.join(getStoragePath(), 'fonts', path.basename(raw)),
-      path.join(process.cwd(), 'storage', 'fonts', path.basename(raw)),
-    ];
-    const found = candidates.find((p) => fs.existsSync(p));
-    expect(found).toBe(fontPath);
-  });
-});

backend/__tests__/services/ensureHeroImage.external.test.js

@@ -1,116 +0,0 @@
-/**
- * ensureHeroImage must work for external/reference photos (#1166 follow-up).
- *
- * resolvePhotoStorageKey returns null for external photos by design, and that
- * null used to be handed straight to withLocalCopy, which throws — so the hero
- * route caught it and redirected to the full ORIGINAL. #1078 fixed exactly
- * this shape for ensurePreviewImage and nobody carried it across.
- *
- * It only became visible when the Story hero started asking for hero_url
- * instead of photo.url: on a managed gallery that is a real saving, on a
- * reference-mode gallery it quietly changed nothing.
- */
-const path = require('path');
-const fs = require('fs').promises;
-const os = require('os');
-const sharp = require('sharp');
-
-const EXTERNAL_ROOT = path.join(os.tmpdir(), `picpeak-hero-ext-${process.pid}`);
-process.env.EXTERNAL_MEDIA_ROOT = EXTERNAL_ROOT;
-
-jest.mock('../../src/database/db', () => {
-  const state = { event: null, updates: [] };
-  const api = (table) => {
-    if (table === 'events') return { where: () => ({ first: async () => state.event }) };
-    if (table === 'photos') {
-      return { where: (criteria) => ({ update: async (values) => { state.updates.push({ criteria, values }); return 1; } }) };
-    }
-    throw new Error(`unexpected table in test: ${table}`);
-  };
-  api.__state = state;
-  return { db: api };
-});
-
-const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
-const storageModule = require('../../src/services/storage');
-const { db } = require('../../src/database/db');
-
-const EVENT = { id: 7, slug: 'nas-wedding', source_mode: 'reference', external_path: 'weddings/2026-08' };
-
-async function writeSourceJpeg(absPath, { width = 2400, height = 1600 } = {}) {
-  await fs.mkdir(path.dirname(absPath), { recursive: true });
-  const buf = Buffer.alloc(width * height * 3);
-  for (let i = 0; i < buf.length; i++) buf[i] = (i * 7) % 256;
-  await sharp(buf, { raw: { width, height, channels: 3 } }).jpeg({ quality: 90 }).toFile(absPath);
-}
-
-describe('ensureHeroImage — external sources', () => {
-  let storage; let storageRoot; let imageProcessor;
-
-  beforeAll(async () => {
-    storageRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-hero-store-'));
-    storage = new LocalFsStorage({ root: storageRoot });
-    await storage.init();
-    storageModule.setStorageForTesting(storage);
-    delete require.cache[require.resolve('../../src/services/imageProcessor')];
-    imageProcessor = require('../../src/services/imageProcessor');
-    await fs.mkdir(path.join(EXTERNAL_ROOT, EVENT.external_path), { recursive: true });
-  }, 30000);
-
-  afterAll(async () => {
-    storageModule.resetStorage();
-    await fs.rm(storageRoot, { recursive: true, force: true }).catch(() => {});
-    await fs.rm(EXTERNAL_ROOT, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(() => { db.__state.event = EVENT; db.__state.updates = []; });
-
-  it.each(['external', 'reference'])('generates a hero for a %s photo off the mount', async (sourceOrigin) => {
-    const name = `${sourceOrigin}-hero.jpg`;
-    await writeSourceJpeg(path.join(EXTERNAL_ROOT, EVENT.external_path, name));
-    const photo = {
-      id: sourceOrigin === 'external' ? 301 : 302,
-      event_id: EVENT.id,
-      source_origin: sourceOrigin,
-      // Root-relative, as stored since #1163: external_relpath is resolved
-      // from EXTERNAL_MEDIA_ROOT, not from event.external_path. The base-
-      // relative form this fixture used to carry stopped resolving the moment
-      // that landed, and ensureHeroImage returned null.
-      external_relpath: path.join(EVENT.external_path, name),
-      filename: name,
-      hero_path: null,
-    };
-
-    const key = await imageProcessor.ensureHeroImage(photo);
-
-    // The regression: this returned null and the route redirected to the
-    // full original.
-    expect(key).toBeTruthy();
-    expect(await storage.exists(key)).toBe(true);
-    // Per-photo basename, so two events sharing a NAS filename cannot clobber
-    // each other — same rule as the preview tier.
-    expect(key).toContain(`ext${photo.id}_`);
-    expect(db.__state.updates).toEqual([{ criteria: { id: photo.id }, values: { hero_path: key } }]);
-  });
-
-  it('returns null rather than throwing when the external source is gone', async () => {
-    const photo = {
-      id: 303, event_id: EVENT.id, source_origin: 'external',
-      external_relpath: path.join(EVENT.external_path, 'not-on-the-mount.jpg'), filename: 'not-on-the-mount.jpg', hero_path: null,
-    };
-
-    await expect(imageProcessor.ensureHeroImage(photo)).resolves.toBeNull();
-    expect(db.__state.updates).toEqual([]);
-  });
-
-  it('returns null for a reference-mode row with no source_origin', async () => {
-    // Mode falls back to the event's, so resolvePhotoStorageKey yields null.
-    // That used to reach withLocalCopy and throw out of the function.
-    const photo = {
-      id: 304, event_id: EVENT.id, source_origin: null, external_relpath: null,
-      filename: 'orphan.jpg', path: 'nas-wedding/individual/orphan.jpg', hero_path: null,
-    };
-
-    await expect(imageProcessor.ensureHeroImage(photo)).resolves.toBeNull();
-  });
-});

backend/__tests__/services/ensurePreviewImage.external.test.js

@@ -1,219 +0,0 @@
-/**
- * Regression tests for #1078 — ensurePreviewImage must generate previews for
- * external/reference photos, not silently fall back to the full-size original.
- *
- * resolvePhotoStorageKey returns null for external photos by design, and that
- * null used to be handed straight to withLocalCopy, which throws. The lightbox
- * preview route caught the throw and redirected to the original, so a gallery
- * whose photos all live on an external mount paid full size on every open —
- * the exact cost the preview tier (#492) exists to avoid.
- */
-const path = require('path');
-const fs = require('fs').promises;
-const os = require('os');
-const sharp = require('sharp');
-
-// Must be set before externalMediaService is first required: it caches the
-// resolved root on first call, and the dir has to exist to win over the
-// container default.
-const EXTERNAL_ROOT = path.join(os.tmpdir(), `picpeak-ext-media-${process.pid}`);
-process.env.EXTERNAL_MEDIA_ROOT = EXTERNAL_ROOT;
-
-jest.mock('../../src/database/db', () => {
-  const state = { event: null, updates: [] };
-  const api = (table) => {
-    if (table === 'events') {
-      return { where: () => ({ first: async () => state.event }) };
-    }
-    if (table === 'photos') {
-      return {
-        where: (criteria) => ({
-          update: async (values) => {
-            state.updates.push({ criteria, values });
-            return 1;
-          },
-        }),
-      };
-    }
-    throw new Error(`unexpected table in test: ${table}`);
-  };
-  api.__state = state;
-  return { db: api };
-});
-
-const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
-const storageModule = require('../../src/services/storage');
-const { db } = require('../../src/database/db');
-
-const EVENT = {
-  id: 7,
-  slug: 'nas-wedding',
-  source_mode: 'reference',
-  external_path: 'weddings/2026-08-smith',
-};
-
-async function writeSourceJpeg(absPath, { width = 2400, height = 1600 } = {}) {
-  await fs.mkdir(path.dirname(absPath), { recursive: true });
-  const buf = Buffer.alloc(width * height * 3);
-  for (let i = 0; i < buf.length; i++) buf[i] = (i * 7) % 256;
-  await sharp(buf, { raw: { width, height, channels: 3 } }).jpeg({ quality: 90 }).toFile(absPath);
-}
-
-describe('ensurePreviewImage — external/reference sources (#1078)', () => {
-  let storage;
-  let storageRoot;
-  let imageProcessor;
-
-  beforeAll(async () => {
-    storageRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-preview-store-'));
-    storage = new LocalFsStorage({ root: storageRoot });
-    await storage.init();
-    storageModule.setStorageForTesting(storage);
-
-    // Require AFTER the storage injection so the module sees it.
-    delete require.cache[require.resolve('../../src/services/imageProcessor')];
-    imageProcessor = require('../../src/services/imageProcessor');
-
-    await fs.mkdir(path.join(EXTERNAL_ROOT, EVENT.external_path), { recursive: true });
-  }, 30000);
-
-  afterAll(async () => {
-    storageModule.resetStorage();
-    await fs.rm(storageRoot, { recursive: true, force: true }).catch(() => {});
-    await fs.rm(EXTERNAL_ROOT, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(() => {
-    db.__state.event = EVENT;
-    db.__state.updates = [];
-  });
-
-  it.each(['external', 'reference'])(
-    'generates a downscaled preview for a %s photo off the media mount',
-    async (sourceOrigin) => {
-      const name = `${sourceOrigin}-shot.jpg`;
-      await writeSourceJpeg(path.join(EXTERNAL_ROOT, EVENT.external_path, name));
-
-      const photo = {
-        id: sourceOrigin === 'external' ? 101 : 102,
-        event_id: EVENT.id,
-        source_origin: sourceOrigin,
-        // Relative to the media ROOT, not to event.external_path (#1163).
-        external_relpath: path.join(EVENT.external_path, name),
-        filename: name,
-        preview_path: null,
-      };
-
-      const key = await imageProcessor.ensurePreviewImage(photo);
-
-      // Per-photo basename so two events referencing the same NAS filename
-      // can't clobber each other's preview.
-      expect(key).toBe(`previews/preview_ext${photo.id}_${name}`);
-      expect(await storage.exists(key)).toBe(true);
-
-      const meta = await sharp(storage.resolveLocalPath(key)).metadata();
-      expect(meta.format).toBe('jpeg');
-      // 2400x1600 capped at the 1920 long edge, aspect preserved.
-      expect(meta.width).toBe(1920);
-      expect(meta.height).toBe(1280);
-
-      // The generated key is persisted so the next open short-circuits.
-      expect(db.__state.updates).toEqual([
-        { criteria: { id: photo.id }, values: { preview_path: key } },
-      ]);
-    }
-  );
-
-  it('short-circuits on an existing valid preview instead of regenerating', async () => {
-    const name = 'already-previewed.jpg';
-    await writeSourceJpeg(path.join(EXTERNAL_ROOT, EVENT.external_path, name));
-    const photo = {
-      id: 103,
-      event_id: EVENT.id,
-      source_origin: 'external',
-      external_relpath: path.join(EVENT.external_path, name),
-      filename: name,
-      preview_path: null,
-    };
-
-    const first = await imageProcessor.ensurePreviewImage(photo);
-    db.__state.updates = [];
-
-    const second = await imageProcessor.ensurePreviewImage({ ...photo, preview_path: first });
-    expect(second).toBe(first);
-    expect(db.__state.updates).toEqual([]);
-  });
-
-  it('returns null (never throws) when the external source is missing', async () => {
-    const photo = {
-      id: 104,
-      event_id: EVENT.id,
-      source_origin: 'external',
-      external_relpath: 'not-on-the-mount.jpg',
-      filename: 'not-on-the-mount.jpg',
-      preview_path: null,
-    };
-
-    await expect(imageProcessor.ensurePreviewImage(photo)).resolves.toBeNull();
-    expect(db.__state.updates).toEqual([]);
-  });
-
-  it('returns null (never throws) for a row with no source_origin in a reference event', async () => {
-    // Mode falls back to event.source_mode = 'reference', so
-    // resolvePhotoStorageKey yields null. That used to reach withLocalCopy and
-    // throw out of ensurePreviewImage instead of honouring null-on-failure.
-    const photo = {
-      id: 105,
-      event_id: EVENT.id,
-      source_origin: null,
-      external_relpath: null,
-      filename: 'orphan.jpg',
-      path: 'nas-wedding/individual/orphan.jpg',
-      preview_path: null,
-    };
-
-    await expect(imageProcessor.ensurePreviewImage(photo)).resolves.toBeNull();
-    expect(db.__state.updates).toEqual([]);
-  });
-
-  it('branches on source_origin, so a row selected without it looks managed', async () => {
-    // Pins why the /regenerate-previews caller must select source_origin:
-    // an external row missing that column takes the managed path, where
-    // resolvePhotoStorageKey yields null and generation is skipped.
-    const name = 'column-starved.jpg';
-    await writeSourceJpeg(path.join(EXTERNAL_ROOT, EVENT.external_path, name));
-    const starved = {
-      id: 106,
-      event_id: EVENT.id,
-      external_relpath: path.join(EVENT.external_path, name),
-      preview_path: null,
-    };
-
-    await expect(imageProcessor.ensurePreviewImage(starved)).resolves.toBeNull();
-    await expect(
-      imageProcessor.ensurePreviewImage({ ...starved, source_origin: 'external', filename: name })
-    ).resolves.toBe(`previews/preview_ext106_${name}`);
-  });
-
-  it('still routes managed photos through the storage backend', async () => {
-    const sourceKey = 'events/active/managed-event/individual/managed.jpg';
-    const localSource = path.join(os.tmpdir(), `picpeak-managed-${process.pid}.jpg`);
-    await writeSourceJpeg(localSource, { width: 800, height: 600 });
-    await storage.put(sourceKey, await fs.readFile(localSource), { contentType: 'image/jpeg' });
-    await fs.rm(localSource, { force: true });
-
-    db.__state.event = { id: 8, slug: 'managed-event', source_mode: 'managed' };
-    const photo = {
-      id: 201,
-      event_id: 8,
-      source_origin: 'managed',
-      path: 'managed-event/individual/managed.jpg',
-      filename: 'managed.jpg',
-      preview_path: null,
-    };
-
-    const key = await imageProcessor.ensurePreviewImage(photo);
-    expect(key).toBe('previews/preview_managed.jpg');
-    expect(await storage.exists(key)).toBe(true);
-  });
-});

backend/__tests__/services/externalPhotoDedupe.restore.test.js

@@ -1,92 +0,0 @@
-/**
- * A pre-#1162 backup must still restore (#1162 review).
- *
- * `replaceAllTables` suspends FOREIGN KEY enforcement for the load — Postgres
- * via `session_replication_role = replica`, SQLite via `defer_foreign_keys` —
- * but neither of those suspends a UNIQUE index. An archive taken before
- * migration 186 carries exactly the duplicate photo rows that migration
- * removes, so the batchInsert would hit the new index and roll the entire
- * restore back, after every table had already been emptied.
- *
- * These pin the drop → load → dedupe → recreate sequence the restore now
- * performs, and the failure it exists to prevent.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-const {
-  dedupeExternalPhotos,
-  createExternalRelpathIndex,
-  dropExternalRelpathIndex,
-} = require('../../src/services/externalPhotoDedupe');
-
-describe('restoring an archive that predates the unique index (#1162)', () => {
-  let knex; let tmpDir;
-
-  // What a pre-186 archive's photos.ndjson holds for a racing import: the same
-  // file twice, sub-millisecond apart.
-  const ARCHIVE_ROWS = [
-    { id: 1, event_id: 1, external_relpath: 'Trip/a.jpg', source_origin: 'external' },
-    { id: 2, event_id: 1, external_relpath: 'Trip/a.jpg', source_origin: 'external' },
-    { id: 3, event_id: 1, external_relpath: 'Trip/b.jpg', source_origin: 'external' },
-  ];
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-restore-dedupe-'));
-    knex = require('knex')({
-      client: 'sqlite3',
-      connection: { filename: path.join(tmpDir, 'db.sqlite') },
-      useNullAsDefault: true,
-    });
-  });
-
-  afterAll(async () => {
-    if (knex) await knex.destroy();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(async () => {
-    await knex.schema.dropTableIfExists('photos');
-    await knex.schema.createTable('photos', (t) => {
-      t.integer('id').primary();
-      t.integer('event_id');
-      t.string('external_relpath');
-      t.string('thumbnail_path');
-      t.string('source_origin').defaultTo('managed');
-    });
-    await createExternalRelpathIndex(knex);
-  });
-
-  it('would abort the whole restore without the drop', async () => {
-    // The regression, stated directly: this is what the target instance does
-    // today when handed a legacy archive.
-    await expect(knex.batchInsert('photos', ARCHIVE_ROWS, 100)).rejects.toThrow(/unique/i);
-  });
-
-  it('loads, dedupes and comes back constrained', async () => {
-    await dropExternalRelpathIndex(knex);
-    await knex.batchInsert('photos', ARCHIVE_ROWS, 100);
-
-    const removed = await dedupeExternalPhotos(knex);
-    await createExternalRelpathIndex(knex);
-
-    expect(removed).toBe(1);
-    expect((await knex('photos').orderBy('id')).map((r) => r.external_relpath))
-      .toEqual(['Trip/a.jpg', 'Trip/b.jpg']);
-    // The target must not be left unprotected by the restore that dropped it.
-    await expect(
-      knex('photos').insert({ id: 9, event_id: 1, external_relpath: 'Trip/b.jpg', source_origin: 'external' })
-    ).rejects.toThrow(/unique/i);
-  });
-
-  it('is a no-op for an archive that has no duplicates', async () => {
-    await dropExternalRelpathIndex(knex);
-    await knex.batchInsert('photos', ARCHIVE_ROWS.slice(1), 100);
-
-    expect(await dedupeExternalPhotos(knex)).toBe(0);
-    await expect(createExternalRelpathIndex(knex)).resolves.toBeUndefined();
-    expect(await knex('photos').count('* as c').first()).toEqual({ c: 2 });
-  });
-});

backend/__tests__/services/fileWatcher.concurrency.test.js

@@ -0,0 +1,125 @@
+/**
+ * Regression tests for the file-watcher concurrency bound.
+ *
+ * chokidar fires 'add' once per file — with no ignoreInitial option the boot
+ * scan fires it for every existing file, and a bulk drop fires it for every
+ * new one at once. Unbounded handlers each run DB lookups plus a full sharp
+ * pipeline (sharp.concurrency(2) only caps libvips threads WITHIN one
+ * operation), which can OOM small hosts. Both 'add' and 'unlink' must go
+ * through the shared p-limit gate.
+ *
+ * Adapted from the filpgame fork (426ca491), extended to cover 'unlink'.
+ */
+
+const mockLimit = jest.fn((operation) => Promise.resolve().then(operation));
+const mockPLimit = jest.fn(() => mockLimit);
+const mockHandlers = {};
+const mockWatcher = {
+  on: jest.fn((event, handler) => {
+    mockHandlers[event] = handler;
+    return mockWatcher;
+  }),
+};
+
+// Shared instances captured by the mock factories: jest.isolateModules re-runs
+// each factory in a fresh registry, so the factories must return these same
+// objects for the test to observe calls made inside the isolated module.
+const mockLogger = { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() };
+// Chainable no-row query — enough for removePhoto's lookup/delete calls.
+const mockDb = jest.fn(() => ({
+  where: jest.fn().mockReturnThis(),
+  first: jest.fn().mockResolvedValue(null),
+  delete: jest.fn().mockResolvedValue(0),
+}));
+
+jest.mock('p-limit', () => mockPLimit);
+jest.mock('chokidar', () => ({
+  watch: jest.fn(() => mockWatcher),
+}));
+jest.mock('../../src/database/db', () => ({ db: mockDb }));
+jest.mock('../../src/utils/logger', () => mockLogger);
+jest.mock('../../src/services/imageProcessor', () => ({
+  generateThumbnail: jest.fn(),
+  generateVideoPlaceholder: jest.fn(),
+}));
+jest.mock('../../src/services/videoProcessor', () => ({
+  isVideoMimeType: jest.fn(() => false),
+}));
+jest.mock('../../src/services/downloadZipService', () => ({ invalidate: jest.fn() }));
+jest.mock('../../src/utils/dbCompat', () => ({
+  formatBoolean: jest.fn((value) => value),
+}));
+
+const loadFileWatcher = () => {
+  let fileWatcher;
+  jest.isolateModules(() => {
+    fileWatcher = require('../../src/services/fileWatcher');
+  });
+  return fileWatcher;
+};
+
+describe('fileWatcher concurrency bound', () => {
+  const originalBackend = process.env.STORAGE_BACKEND;
+  const originalConcurrency = process.env.FILE_WATCHER_CONCURRENCY;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    Object.keys(mockHandlers).forEach((key) => delete mockHandlers[key]);
+    process.env.STORAGE_BACKEND = 'local';
+    delete process.env.FILE_WATCHER_CONCURRENCY;
+  });
+
+  afterAll(() => {
+    if (originalBackend === undefined) delete process.env.STORAGE_BACKEND;
+    else process.env.STORAGE_BACKEND = originalBackend;
+    if (originalConcurrency === undefined) delete process.env.FILE_WATCHER_CONCURRENCY;
+    else process.env.FILE_WATCHER_CONCURRENCY = originalConcurrency;
+  });
+
+  it.each([
+    [undefined, 2],   // default
+    ['3', 3],         // explicit
+    ['0', 1],         // floored to 1
+    ['-4', 1],        // floored to 1
+    ['invalid', 2],   // falls back to default
+  ])('configures the limiter with FILE_WATCHER_CONCURRENCY=%s as %i', (configured, expected) => {
+    if (configured === undefined) delete process.env.FILE_WATCHER_CONCURRENCY;
+    else process.env.FILE_WATCHER_CONCURRENCY = configured;
+
+    loadFileWatcher().startFileWatcher();
+
+    expect(mockPLimit).toHaveBeenCalledWith(expected);
+  });
+
+  it('routes add events through the shared limiter', async () => {
+    loadFileWatcher().startFileWatcher();
+
+    expect(mockHandlers.add).toEqual(expect.any(Function));
+    mockHandlers.add('/outside-watch-root'); // early-returns inside processNewPhoto
+
+    expect(mockLimit).toHaveBeenCalledTimes(1);
+    expect(mockLimit).toHaveBeenCalledWith(expect.any(Function));
+    await mockLimit.mock.results[0].value;
+  });
+
+  it('routes unlink events through the same limiter', async () => {
+    loadFileWatcher().startFileWatcher();
+
+    expect(mockHandlers.unlink).toEqual(expect.any(Function));
+    mockHandlers.unlink('/outside-watch-root'); // early-returns inside removePhoto
+
+    expect(mockLimit).toHaveBeenCalledTimes(1);
+    await mockLimit.mock.results[0].value;
+  });
+
+  it('logs instead of rejecting when a queued handler throws', async () => {
+    loadFileWatcher().startFileWatcher();
+
+    const failure = new Error('boom');
+    mockLimit.mockImplementationOnce(() => Promise.reject(failure));
+    mockHandlers.add('/whatever');
+
+    await new Promise(process.nextTick);
+    expect(mockLogger.error).toHaveBeenCalledWith('Error processing new photo:', failure);
+  });
+});

backend/__tests__/services/generatePreviewImage.formats.test.js

@@ -1,134 +0,0 @@
-/**
- * The preview tier must not destroy what it is previewing.
- *
- * generatePreviewImage encoded JPEG unconditionally. JPEG has no alpha channel
- * and no second frame, so a transparent PNG came back flattened onto a solid
- * background and an animated GIF came back as its first frame — for every
- * consumer of this tier, not just the lightbox: the slideshow (#1015), admin
- * previews, and the face avatars that read it as a whole-frame rendition.
- *
- * Driven against real Sharp output, because the whole question is what is in
- * the encoded bytes.
- */
-
-const path = require('path');
-const fs = require('fs').promises;
-const os = require('os');
-const sharp = require('sharp');
-
-const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
-const storageModule = require('../../src/services/storage');
-
-/** A 2x2 GIF89a with two frames and a NETSCAPE loop block. */
-const ANIMATED_GIF = Buffer.from([
-  0x47, 0x49, 0x46, 0x38, 0x39, 0x61,
-  0x02, 0x00, 0x02, 0x00,
-  0xF0, 0x00, 0x00,
-  0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF,
-  0x21, 0xFF, 0x0B, 0x4E, 0x45, 0x54, 0x53, 0x43, 0x41, 0x50, 0x45,
-  0x32, 0x2E, 0x30, 0x03, 0x01, 0x00, 0x00, 0x00,
-  0x21, 0xF9, 0x04, 0x00, 0x0A, 0x00, 0x00, 0x00,
-  0x2C, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x02, 0x00, 0x00,
-  0x02, 0x02, 0x44, 0x01, 0x00,
-  0x21, 0xF9, 0x04, 0x00, 0x0A, 0x00, 0x00, 0x00,
-  0x2C, 0x00, 0x00, 0x00, 0x00, 0x02, 0x00, 0x02, 0x00, 0x00,
-  0x02, 0x02, 0x4C, 0x01, 0x00,
-  0x3B,
-]);
-
-// No width-tier case here: the responsive `?w=` renditions (#1095) are
-// main-only, so this branch has a single canonical preview per photo.
-describe('generatePreviewImage encodes for the source (#1166 follow-up)', () => {
-  let storage; let storageRoot; let srcDir; let imageProcessor;
-
-  beforeAll(async () => {
-    storageRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-prevfmt-store-'));
-    srcDir = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-prevfmt-src-'));
-    storage = new LocalFsStorage({ root: storageRoot });
-    await storage.init();
-    storageModule.setStorageForTesting(storage);
-
-    delete require.cache[require.resolve('../../src/services/imageProcessor')];
-    imageProcessor = require('../../src/services/imageProcessor');
-  }, 30000);
-
-  afterAll(async () => {
-    storageModule.resetStorage();
-    await fs.rm(storageRoot, { recursive: true, force: true }).catch(() => {});
-    await fs.rm(srcDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  const outMeta = async (key) => sharp(storage.resolveLocalPath(key)).metadata();
-
-  it('keeps transparency, as WebP, for a PNG with alpha', async () => {
-    const src = path.join(srcDir, 'logo.png');
-    await sharp({
-      create: { width: 800, height: 600, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
-    }).png().toFile(src);
-
-    const key = await imageProcessor.generatePreviewImage(src, { regenerate: true });
-
-    expect(key).toBe('previews/preview_logo.webp');
-    const meta = await outMeta(key);
-    expect(meta.format).toBe('webp');
-    // The regression, stated directly: JPEG would have flattened this.
-    expect(meta.hasAlpha).toBe(true);
-  });
-
-  it('keeps every frame, as WebP, for an animated GIF', async () => {
-    const src = path.join(srcDir, 'wave.gif');
-    // Hand-assembled rather than produced by Sharp: writing a multi-page image
-    // needs pageHeight threaded through the pipeline, and a fixture that
-    // silently comes out single-page would make this test pass for the wrong
-    // reason. 2x2, two frames, black then white.
-    await fs.writeFile(src, ANIMATED_GIF);
-    // Precondition: the fixture really is animated.
-    expect((await sharp(src, { animated: true }).metadata()).pages).toBe(2);
-
-    const key = await imageProcessor.generatePreviewImage(src, { regenerate: true });
-
-    expect(key).toBe('previews/preview_wave.webp');
-    const meta = await sharp(storage.resolveLocalPath(key), { animated: true }).metadata();
-    expect(meta.format).toBe('webp');
-    // The regression, stated directly: JPEG kept only the first frame.
-    expect(meta.pages).toBe(2);
-  });
-
-  it('still writes plain JPEG for an ordinary photo', async () => {
-    // The common path must not pay for the two cases above: JPEG is smaller
-    // than WebP at the quality this tier uses, and every existing preview is
-    // one.
-    const src = path.join(srcDir, 'shot.jpg');
-    await sharp({ create: { width: 2400, height: 1600, channels: 3, background: { r: 90, g: 90, b: 90 } } })
-      .jpeg().toFile(src);
-
-    const key = await imageProcessor.generatePreviewImage(src, { regenerate: true });
-
-    expect(key).toBe('previews/preview_shot.jpg');
-    const meta = await outMeta(key);
-    expect(meta.format).toBe('jpeg');
-    // 2400x1600 capped at the 1920 long edge, aspect preserved — unchanged.
-    expect([meta.width, meta.height]).toEqual([1920, 1280]);
-  });
-
-  it('names the output for what it wrote, not for the source', async () => {
-    // A PNG source used to produce `preview_x.png` holding JPEG bytes. Harmless
-    // while the route hard-coded image/jpeg; wrong once the encoding varies,
-    // and the route now reads the extension.
-    const src = path.join(srcDir, 'opaque.png');
-    await sharp({ create: { width: 400, height: 400, channels: 3, background: { r: 1, g: 2, b: 3 } } })
-      .png().toFile(src);
-
-    const key = await imageProcessor.generatePreviewImage(src, { regenerate: true });
-
-    expect(key).toBe('previews/preview_opaque.jpg');
-    expect((await outMeta(key)).format).toBe('jpeg');
-  });
-
-  it('returns null on an unreadable source instead of throwing', async () => {
-    const src = path.join(srcDir, 'not-an-image.jpg');
-    await fs.writeFile(src, 'plain text');
-
-    await expect(imageProcessor.generatePreviewImage(src, { regenerate: true })).resolves.toBeNull();
-  });
-});

backend/__tests__/services/generateThumbnail.regenerate.test.js

@@ -1,90 +0,0 @@
-/**
- * Regeneration must not destroy a good thumbnail when the source is
- * unreadable (#1129).
- *
- * The old code deleted the target BEFORE sharp opened the source, so a NAS
- * mount that blipped mid-run left the previous rendition gone and the database
- * still pointing at it. Across a bulk regenerate that is the whole gallery,
- * and it is precisely the "worse than before you pressed it" outcome #1129 is
- * about.
- */
-
-const path = require('path');
-const fs = require('fs').promises;
-const os = require('os');
-const sharp = require('sharp');
-
-jest.mock('../../src/database/db', () => ({
-  db: () => ({ where: () => ({ first: async () => null, update: async () => 1 }) }),
-}));
-
-const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
-const storageModule = require('../../src/services/storage');
-
-describe('generateThumbnail — regenerate is non-destructive (#1129)', () => {
-  let storage; let root; let imageProcessor; let srcDir;
-
-  beforeAll(async () => {
-    root = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-regen-store-'));
-    srcDir = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-regen-src-'));
-    storage = new LocalFsStorage({ root });
-    await storage.init();
-    storageModule.setStorageForTesting(storage);
-
-    delete require.cache[require.resolve('../../src/services/imageProcessor')];
-    imageProcessor = require('../../src/services/imageProcessor');
-  }, 30000);
-
-  afterAll(async () => {
-    storageModule.resetStorage();
-    await fs.rm(root, { recursive: true, force: true }).catch(() => {});
-    await fs.rm(srcDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  async function writeSource(name, size = 400) {
-    const p = path.join(srcDir, name);
-    await sharp({ create: { width: size, height: size, channels: 3, background: { r: 1, g: 2, b: 3 } } })
-      .jpeg().toFile(p);
-    return p;
-  }
-
-  it('keeps the existing thumbnail when the source cannot be read', async () => {
-    const src = await writeSource('present.jpg');
-    const key = await imageProcessor.generateThumbnail(src, { regenerate: true });
-    expect(key).toBeTruthy();
-    expect(await storage.exists(key)).toBe(true);
-    const before = await storage.get(key).then((s) => new Promise((res) => {
-      const c = []; s.on('data', (d) => c.push(d)); s.on('end', () => res(Buffer.concat(c)));
-    }));
-
-    // The mount goes away between runs.
-    await fs.unlink(src);
-    const second = await imageProcessor.generateThumbnail(src, { regenerate: true })
-      .catch(() => null);
-
-    expect(second).toBeFalsy();
-    // The old rendition is still there and still serves. Previously it had
-    // been deleted before sharp ever looked at the source.
-    expect(await storage.exists(key)).toBe(true);
-    const after = await storage.get(key).then((s) => new Promise((res) => {
-      const c = []; s.on('data', (d) => c.push(d)); s.on('end', () => res(Buffer.concat(c)));
-    }));
-    expect(after.equals(before)).toBe(true);
-  });
-
-  it('still replaces the thumbnail when the source IS readable', async () => {
-    const src = await writeSource('replaceme.jpg', 400);
-    const key = await imageProcessor.generateThumbnail(src, { regenerate: true });
-    const firstSize = (await storage.stat(key)).size;
-
-    // Same key, different source content — the atomic rename in put() is what
-    // makes the pre-delete unnecessary.
-    await fs.rm(src);
-    await sharp({ create: { width: 400, height: 400, channels: 3, background: { r: 250, g: 40, b: 9 } } })
-      .jpeg().toFile(src);
-    const again = await imageProcessor.generateThumbnail(src, { regenerate: true });
-
-    expect(again).toBe(key);
-    expect((await storage.stat(key)).size).not.toBe(firstSize);
-  });
-});

backend/__tests__/services/imageProcessor.sharpConfig.test.js

@@ -0,0 +1,30 @@
+/**
+ * Locks the process-wide Sharp memory guards. The file-watcher concurrency
+ * bound (FILE_WATCHER_CONCURRENCY) assumes these caps stay in place — they
+ * limit libvips threads/cache WITHIN one operation while p-limit bounds the
+ * number of parallel pipelines. From the filpgame fork (426ca491).
+ */
+
+const mockSharp = jest.fn();
+mockSharp.cache = jest.fn();
+mockSharp.concurrency = jest.fn();
+
+jest.mock('sharp', () => mockSharp);
+
+jest.mock('../../src/utils/logger', () => ({
+  error: jest.fn(),
+  warn: jest.fn(),
+  info: jest.fn(),
+  debug: jest.fn(),
+}));
+
+describe('imageProcessor Sharp configuration', () => {
+  it('disables the Sharp cache and caps libvips concurrency', () => {
+    jest.isolateModules(() => {
+      require('../../src/services/imageProcessor');
+    });
+
+    expect(mockSharp.cache).toHaveBeenCalledWith(false);
+    expect(mockSharp.concurrency).toHaveBeenCalledWith(2);
+  });
+});

backend/__tests__/services/imageProcessorOrientation.test.js

@@ -1,159 +0,0 @@
-/**
- * EXIF orientation in the gallery-facing generators (#1185).
- *
- * sharp decodes the pixels as stored, not as displayed. A photo whose
- * Orientation tag is not 1 — routine for portrait shots on bodies that tag
- * rather than rotate the sensor data — therefore resizes from the raw frame
- * and comes out sideways. The generators then call `.withMetadata(false)`,
- * which strips the tag from the output, so the browser has no hint left to
- * correct it either: nothing downstream can recover it.
- *
- * The download path (`resizeToBox`) always got this right. These three did
- * not, which is why the same photo looked correct on download and rotated in
- * the gallery.
- *
- * Every assertion here fails on the unfixed generators.
- */
-
-const fs = require('fs').promises;
-const path = require('path');
-const os = require('os');
-const sharp = require('sharp');
-
-// imageProcessor reads its thumbnail settings from app_settings, so without a
-// db the require() alone hangs the run. Same shape the other generator tests
-// use (ensureHeroImage.external.test.js).
-jest.mock('../../src/database/db', () => {
-  const api = (table) => {
-    if (table === 'app_settings') {
-      return { where: () => ({ whereIn: () => [], first: async () => null }), whereIn: async () => [] };
-    }
-    if (table === 'events') return { where: () => ({ first: async () => null }) };
-    if (table === 'photos') return { where: () => ({ update: async () => 1, first: async () => null }) };
-    return { where: () => ({ first: async () => null }) };
-  };
-  return { db: api };
-});
-
-const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
-const storageModule = require('../../src/services/storage');
-
-describe('EXIF orientation in thumbnails, heroes and previews (#1185)', () => {
-  let tmpDir;
-  let imageProcessor;
-  let landscapeTaggedPortrait;
-
-  // 400x200 as stored, Orientation 6 (90° CW) — so it DISPLAYS as 200x400.
-  // This is exactly the shape the reporter's Sony bodies produce: the sensor
-  // data is landscape and the tag carries the rotation.
-  const W = 400;
-  const H = 200;
-
-  let storageRoot;
-
-  beforeAll(async () => {
-    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-orient-'));
-    storageRoot = path.join(tmpDir, 'storage');
-    await fs.mkdir(storageRoot, { recursive: true });
-    process.env.STORAGE_PATH = storageRoot;
-
-    const storage = new LocalFsStorage({ root: storageRoot });
-    await storage.init();
-    storageModule.setStorageForTesting(storage);
-
-    landscapeTaggedPortrait = path.join(tmpDir, 'portrait-tagged.jpg');
-    await sharp({
-      create: { width: W, height: H, channels: 3, background: { r: 120, g: 80, b: 40 } },
-    })
-      .withMetadata({ orientation: 6 })
-      .jpeg()
-      .toFile(landscapeTaggedPortrait);
-
-    delete require.cache[require.resolve('../../src/services/imageProcessor')];
-    imageProcessor = require('../../src/services/imageProcessor');
-  }, 60000);
-
-  afterAll(async () => {
-    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  test('the fixture really is stored landscape with a rotation tag', async () => {
-    const m = await sharp(landscapeTaggedPortrait).metadata();
-    expect(m.width).toBe(W);
-    expect(m.height).toBe(H);
-    expect(m.orientation).toBe(6);
-  });
-
-  test('orientedDimensions reports what a viewer sees, not what is stored', async () => {
-    const m = await sharp(landscapeTaggedPortrait).metadata();
-    // Swapped: this is what the grid needs to size a tile, and what the
-    // database should hold.
-    expect(imageProcessor.orientedDimensions(m)).toEqual({ width: H, height: W });
-  });
-
-  test('orientedDimensions leaves an untagged image alone', async () => {
-    const plain = path.join(tmpDir, 'plain.jpg');
-    await sharp({ create: { width: W, height: H, channels: 3, background: { r: 1, g: 2, b: 3 } } })
-      .jpeg().toFile(plain);
-    const m = await sharp(plain).metadata();
-    expect(imageProcessor.orientedDimensions(m)).toEqual({ width: W, height: H });
-  });
-
-  test('orientedDimensions survives metadata it cannot use', () => {
-    expect(imageProcessor.orientedDimensions(null)).toEqual({ width: null, height: null });
-    expect(imageProcessor.orientedDimensions({})).toEqual({ width: null, height: null });
-  });
-
-  test('the thumbnail comes out portrait, not sideways', async () => {
-    const rel = await imageProcessor.generateThumbnail(landscapeTaggedPortrait, {
-      outputBasename: 'orient-thumb.jpg',
-      regenerate: true,
-    });
-    expect(rel).toBeTruthy();
-
-    const out = await sharp(path.join(storageRoot, rel)).metadata();
-    // Unfixed, this came back wider than tall — the raw frame, resized.
-    expect(out.height).toBeGreaterThan(out.width);
-  });
-
-  test('the preview tier comes out portrait too', async () => {
-    const rel = await imageProcessor.generatePreviewImage(landscapeTaggedPortrait, {
-      outputBasename: 'orient-preview.jpg',
-    });
-    expect(rel).toBeTruthy();
-
-    const out = await sharp(path.join(storageRoot, rel)).metadata();
-    expect(out.height).toBeGreaterThan(out.width);
-  });
-
-  test('the watermarked rendition is oriented too', async () => {
-    // gallery.js serves photos.watermark_path ahead of the original when
-    // branding watermarking is on, so this is the rendition a guest actually
-    // sees — and it went through its own sharp pipeline that nobody had
-    // rotated.
-    const watermarkService = require('../../src/services/watermarkService');
-    const buf = await watermarkService.applyWatermark(landscapeTaggedPortrait, {
-      enabled: true, position: 'bottom-right', opacity: 50, size: 15,
-      // companyName, not text — the SVG branch reads this one, and without it
-      // the service falls through without compositing anything.
-      companyName: 'PicPeak',
-    });
-    expect(Buffer.isBuffer(buf)).toBe(true);
-
-    const out = await sharp(buf).metadata();
-    // 400x200 stored, tagged 6 — so the watermarked output must be portrait.
-    expect(out.height).toBeGreaterThan(out.width);
-  });
-
-  test('the orientation tag is gone from the output, so nothing double-rotates', async () => {
-    // The pixels are corrected now, so a surviving tag would make a viewer
-    // rotate an already-rotated image. withMetadata(false) strips it; this
-    // pins that the two changes agree.
-    const rel = await imageProcessor.generateThumbnail(landscapeTaggedPortrait, {
-      outputBasename: 'orient-thumb-tag.jpg',
-      regenerate: true,
-    });
-    const out = await sharp(path.join(storageRoot, rel)).metadata();
-    expect(out.orientation === undefined || out.orientation === 1).toBe(true);
-  });
-});

backend/__tests__/services/imageProcessorRaw.test.js

@@ -0,0 +1,50 @@
+/**
+ * Unit tests for the RAW/DNG handling helpers (#821). The actual exiftool
+ * extraction can only be exercised in the built image (exiftool isn't a dev
+ * dependency), so these cover the gating logic: which files are treated as RAW,
+ * and that ordinary images pass through untouched (zero cost / no extraction).
+ */
+const path = require('path');
+const { isRawFilename, withProcessableImage, RAW_EXTENSIONS } = require('../../src/services/imageProcessor');
+
+describe('isRawFilename', () => {
+  it('recognises common RAW / DNG extensions', () => {
+    for (const ext of ['dng', 'cr2', 'cr3', 'nef', 'arw', 'raf', 'rw2', 'orf']) {
+      expect(isRawFilename(`IMG_1234.${ext}`)).toBe(true);
+      expect(isRawFilename(`IMG_1234.${ext.toUpperCase()}`)).toBe(true); // case-insensitive
+    }
+  });
+
+  it('does not treat ordinary images/videos as RAW', () => {
+    for (const name of ['photo.jpg', 'photo.jpeg', 'photo.png', 'photo.webp', 'clip.mp4', 'clip.mov', 'photo.heic']) {
+      expect(isRawFilename(name)).toBe(false);
+    }
+  });
+
+  it('is null/empty safe', () => {
+    expect(isRawFilename(null)).toBe(false);
+    expect(isRawFilename('')).toBe(false);
+    expect(isRawFilename('noextension')).toBe(false);
+  });
+
+  it('RAW_EXTENSIONS includes dng (Apple ProRAW)', () => {
+    expect(RAW_EXTENSIONS.has('dng')).toBe(true);
+  });
+});
+
+describe('withProcessableImage', () => {
+  it('passes ordinary images through with no extraction and a no-op cleanup', async () => {
+    const localPath = '/tmp/whatever/photo.jpg';
+    const proc = await withProcessableImage(localPath, 'photo.jpg');
+    expect(proc.path).toBe(localPath);          // unchanged — sharp reads it directly
+    expect(proc.outputBasename).toBeUndefined(); // generators keep their default naming
+    await expect(Promise.resolve(proc.cleanup())).resolves.toBeUndefined();
+  });
+
+  it('routes RAW files to extraction (which fails cleanly without exiftool/preview)', async () => {
+    // In the dev sandbox exiftool isn't installed, so extraction throws — the
+    // caller turns that into a normal processing failure. In the built image
+    // (exiftool present) this instead returns the embedded JPEG preview.
+    await expect(withProcessableImage('/tmp/whatever/IMG_1234.dng', 'IMG_1234.dng')).rejects.toThrow();
+  });
+});

backend/__tests__/services/localStorageUsage.test.js

@@ -1,201 +0,0 @@
-/**
- * "Storage used" has to mean storage used (#1164).
- *
- * The tile summed photos.size_bytes, so on a reference-mode install it
- * reported the size of files sitting on a NAS — the reporter's read ~80 GB
- * against 21 GB of real local usage — while omitting everything PicPeak does
- * write locally, including an 11.8 GB download-cache zip.
- *
- * These pin the measurement against a real directory tree, since the whole
- * point is counting bytes that are actually there.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-const {
-  measureLocalStorageUsage,
-  resetLocalStorageUsageCache,
-} = require('../../src/services/localStorageUsage');
-
-describe('localStorageUsage (#1164)', () => {
-  let root;
-
-  const write = async (rel, bytes) => {
-    const full = path.join(root, rel);
-    await fs.promises.mkdir(path.dirname(full), { recursive: true });
-    await fs.promises.writeFile(full, Buffer.alloc(bytes));
-  };
-
-  beforeEach(async () => {
-    root = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-usage-'));
-    process.env.STORAGE_PATH = root;
-    delete process.env.EXTERNAL_MEDIA_ROOT;
-    jest.resetModules();
-    resetLocalStorageUsageCache();
-  });
-
-  afterEach(async () => {
-    await fs.promises.rm(root, { recursive: true, force: true }).catch(() => {});
-    delete process.env.STORAGE_PATH;
-    delete process.env.EXTERNAL_MEDIA_ROOT;
-    resetLocalStorageUsageCache();
-  });
-
-  it('counts every byte under the storage root', async () => {
-    await write(path.join('events', 'active', 'wed', 'individual', 'a.jpg'), 1000);
-    await write(path.join('thumbnails', 'a.jpg'), 100);
-    await write(path.join('previews', 'a.jpg'), 300);
-
-    const usage = await measureLocalStorageUsage();
-
-    expect(usage.total).toBe(1400);
-    expect(usage.files).toBe(3);
-  });
-
-  it('breaks the total down by what the bytes are', async () => {
-    // The specific complaint: the derived artefacts PicPeak writes were
-    // invisible, so "what is filling my disk" had no answer in the UI.
-    await write(path.join('events', 'active', 'wed', 'individual', 'a.jpg'), 1000);
-    await write(path.join('events', 'archived', 'old.zip'), 5000);
-    await write(path.join('thumbnails', 'a.jpg'), 100);
-    await write(path.join('previews', 'a.jpg'), 300);
-    await write(path.join('heroes', 'a.jpg'), 200);
-    await write(path.join('watermarks', 'a.jpg'), 700);
-    await write(path.join('uploads', 'logo.png'), 50);
-
-    const { breakdown } = await measureLocalStorageUsage();
-
-    expect(breakdown).toMatchObject({
-      originals: 1000,
-      archives: 5000,
-      thumbnails: 100,
-      previews: 300,
-      heroes: 200,
-      watermarks: 700,
-      uploads: 50,
-    });
-  });
-
-  it('files the download cache separately from the originals it sits among', async () => {
-    // `.download-cache` lives INSIDE the event directory, so the naive rule
-    // files an 11.8 GB zip as photography. It is the one bucket that is pure
-    // disposable cache and the one an admin most needs to see.
-    await write(path.join('events', 'active', 'wed', 'individual', 'a.jpg'), 1000);
-    await write(path.join('events', 'active', 'wed', '.download-cache', 'all.zip'), 9000);
-
-    const { breakdown, total } = await measureLocalStorageUsage();
-
-    expect(breakdown.downloadCache).toBe(9000);
-    expect(breakdown.originals).toBe(1000);
-    expect(total).toBe(10000);
-  });
-
-  it('counts orphans no database row knows about', async () => {
-    // A deleted event's leftovers and an interrupted import's thumbnails are
-    // real bytes on a real disk. Summing DB columns would miss them, which is
-    // half of why this walks instead.
-    await write(path.join('thumbnails', 'ext999_gone.jpg'), 777);
-
-    expect((await measureLocalStorageUsage()).total).toBe(777);
-  });
-
-  it('reports zero on a fresh install rather than failing', async () => {
-    const usage = await measureLocalStorageUsage();
-
-    expect(usage.total).toBe(0);
-    expect(usage.partial).toBe(false);
-  });
-
-  it('survives a storage root that does not exist', async () => {
-    process.env.STORAGE_PATH = path.join(root, 'nope');
-    resetLocalStorageUsageCache();
-
-    const usage = await measureLocalStorageUsage();
-
-    // ENOENT on the root is a fresh/misconfigured install, not a partial read.
-    expect(usage.total).toBe(0);
-    expect(usage.partial).toBe(false);
-  });
-
-  it('does not walk the media share bind-mounted under the storage root', async () => {
-    // The compose default puts EXTERNAL_MEDIA_ROOT at <storage>/external-media,
-    // where the NAS is bind-mounted — a plain directory, not a symlink. Walking
-    // it would put every referenced original back into a figure that exists to
-    // leave them out, which is the over-count this measurement replaces.
-    await write(path.join('thumbnails', 'a.jpg'), 100);
-    await write(path.join('external-media', 'nas', 'huge.jpg'), 50000);
-    process.env.EXTERNAL_MEDIA_ROOT = path.join(root, 'external-media');
-    jest.resetModules();
-    const svc = require('../../src/services/localStorageUsage');
-    svc.resetLocalStorageUsageCache();
-
-    const usage = await svc.measureLocalStorageUsage();
-
-    expect(usage.total).toBe(100);
-    expect(usage.excludedExternalRoot).toBe(path.join(root, 'external-media'));
-  });
-
-  it('still counts a directory that merely looks like the media share', async () => {
-    // Only the CONFIGURED root is skipped. An install whose media lives
-    // elsewhere keeps whatever is in this directory in the total, because
-    // those really are local bytes.
-    await write(path.join('external-media', 'leftover.jpg'), 700);
-    // The production shape: the share is mounted well outside the storage root.
-    const elsewhere = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-nas-elsewhere-'));
-    process.env.EXTERNAL_MEDIA_ROOT = elsewhere;
-    jest.resetModules();
-    const svc = require('../../src/services/localStorageUsage');
-    svc.resetLocalStorageUsageCache();
-
-    const usage = await svc.measureLocalStorageUsage();
-
-    expect(usage.total).toBe(700);
-    expect(usage.excludedExternalRoot).toBeNull();
-    await fs.promises.rm(elsewhere, { recursive: true, force: true });
-  });
-
-  it('shares one walk between concurrent cold-cache callers', async () => {
-    // /dashboard/stats and /storage/info are routinely requested together, and
-    // the sidebar adds a third. Each starting its own full stat-per-file walk
-    // multiplies the cost on exactly the large libraries where it hurts.
-    await write(path.join('thumbnails', 'a.jpg'), 100);
-    const readdir = jest.spyOn(fs.promises, 'readdir');
-
-    const [a, b, c] = await Promise.all([
-      measureLocalStorageUsage(),
-      measureLocalStorageUsage(),
-      measureLocalStorageUsage(),
-    ]);
-
-    expect([a.total, b.total, c.total]).toEqual([100, 100, 100]);
-    // One walk: the storage root plus its one subdirectory.
-    expect(readdir).toHaveBeenCalledTimes(2);
-    readdir.mockRestore();
-  });
-
-  it('caches, and honours force', async () => {
-    await write(path.join('thumbnails', 'a.jpg'), 100);
-    expect((await measureLocalStorageUsage()).total).toBe(100);
-
-    await write(path.join('thumbnails', 'b.jpg'), 400);
-    // One stat per file is not free; the dashboard polls.
-    expect((await measureLocalStorageUsage()).total).toBe(100);
-    expect((await measureLocalStorageUsage({ force: true })).total).toBe(500);
-  });
-
-  it('does not follow a symlink out of the storage root', async () => {
-    // A link into EXTERNAL_MEDIA_ROOT would add the NAS back into the local
-    // total — reinstating the exact confusion this replaces.
-    const outside = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-nas-'));
-    await fs.promises.writeFile(path.join(outside, 'huge.jpg'), Buffer.alloc(50000));
-    await fs.promises.mkdir(path.join(root, 'events'), { recursive: true });
-    await fs.promises.symlink(outside, path.join(root, 'events', 'nas'), 'dir');
-
-    const usage = await measureLocalStorageUsage();
-
-    expect(usage.total).toBe(0);
-    await fs.promises.rm(outside, { recursive: true, force: true });
-  });
-});

backend/__tests__/services/logActivityTrx.test.js

@@ -0,0 +1,155 @@
+/**
+ * Regression tests for logActivity calls inside transactions (#850 review
+ * find). createContract / updateContract / createStorno / reissueInvoice
+ * called logActivity() (and contract paths also adminActor()) from inside
+ * a knex transaction WITHOUT the trx executor. On single-connection SQLite
+ * the audit insert then waits on a second pool connection while the trx
+ * holds the only one — a 60s acquire-timeout stall per call, after which
+ * logActivity's catch swallows the failure and the audit row is silently
+ * lost. Postgres was unaffected.
+ *
+ * The observable fix: the activity_logs rows now exist, and the calls
+ * complete without waiting on the pool. The shrunken acquire timeout
+ * below makes any reintroduced deadlock fail the test quickly instead
+ * of appearing to pass after a long stall.
+ */
+const path = require('path');
+const {
+  bootCrmDb, seedMinimal, assignAdminRole,
+} = require('../integration/helpers/crmDb');
+
+jest.setTimeout(120000);
+
+let db;
+let cleanup;
+let tmpDir;
+let adminId;
+let customerId;
+let contractService;
+let invoiceService;
+
+const prevCwd = process.cwd();
+
+beforeAll(async () => {
+  ({ db, cleanup, tmpDir } = await bootCrmDb());
+  // Business-doc artifacts land under process.cwd()/storage — isolate.
+  process.chdir(tmpDir);
+
+  // A reintroduced in-trx pool grab should fail fast (2s), not stall 60s.
+  db.client.pool.acquireTimeoutMillis = 2000;
+
+  // node-sqlite3 detects Date bindings via the NATIVE realm's Date —
+  // under jest's vm sandbox that check fails and Dates stringify to
+  // "[object Object]". Normalize to ISO strings on the client prototype
+  // (transaction clients are Object.create()d from it). Same shim as
+  // crmMintPaths.test.js.
+  const clientProto = Object.getPrototypeOf(db.client);
+  const origQuery = clientProto._query;
+  clientProto._query = function patchedQuery(connection, obj) {
+    if (obj && Array.isArray(obj.bindings)) {
+      obj.bindings = obj.bindings.map(
+        (b) => (b && typeof b === 'object' && typeof b.toISOString === 'function' ? b.toISOString() : b),
+      );
+    }
+    return origQuery.call(this, connection, obj);
+  };
+
+  ({ adminId, customerId } = await seedMinimal(db));
+  await assignAdminRole(db, adminId, 'super_admin');
+
+  contractService = require('../../src/services/contractService');
+  invoiceService = require('../../src/services/invoiceService');
+}, 120000);
+
+afterAll(async () => {
+  process.chdir(prevCwd);
+  if (cleanup) await cleanup();
+});
+
+test('createContract persists the contract_created audit row (was silently lost on SQLite)', async () => {
+  const contractId = await contractService.createContract({
+    customerAccountId: customerId,
+    title: 'Audit-Trail-Vertrag',
+  }, adminId);
+
+  const row = await db('activity_logs')
+    .where({ activity_type: 'contract_created' })
+    .orderBy('id', 'desc')
+    .first();
+  expect(row).toBeTruthy();
+  expect(JSON.parse(row.metadata).contractId).toBe(contractId);
+  expect(row.actor_type).toBe('admin');
+});
+
+test('updateContract persists the contract_updated audit row', async () => {
+  const contractId = await contractService.createContract({
+    customerAccountId: customerId,
+    title: 'Vorher',
+  }, adminId);
+
+  await contractService.updateContract(contractId, { title: 'Nachher' }, adminId);
+
+  const row = await db('activity_logs')
+    .where({ activity_type: 'contract_updated' })
+    .orderBy('id', 'desc')
+    .first();
+  expect(row).toBeTruthy();
+  expect(JSON.parse(row.metadata).contractId).toBe(contractId);
+});
+
+test('cancelInvoice (Storno mint) persists the invoice_cancelled_via_storno audit row', async () => {
+  const { invoiceIds } = await invoiceService.createInvoice({
+    customerAccountId: customerId,
+    currency: 'CHF',
+    vatRate: 0,
+    lineItems: [
+      { position: 1, quantity: 1, description: 'Coverage', unit_price_minor: 100000, discount_percent: 0 },
+    ],
+  }, adminId);
+  const id = invoiceIds[0];
+  await db('invoices').where({ id }).update({ status: 'sent', sent_at: new Date(), updated_at: new Date() });
+
+  const result = await invoiceService.cancelInvoice(id, adminId);
+  expect(result.cancelled).toBe(true);
+
+  const row = await db('activity_logs')
+    .where({ activity_type: 'invoice_cancelled_via_storno' })
+    .orderBy('id', 'desc')
+    .first();
+  expect(row).toBeTruthy();
+  const meta = JSON.parse(row.metadata);
+  expect(meta.invoiceId).toBe(id);
+  expect(meta.stornoId).toBe(result.stornoId);
+});
+
+test('reissueInvoice completes on SQLite and persists the invoice_reissued audit row', async () => {
+  const { invoiceIds } = await invoiceService.createInvoice({
+    customerAccountId: customerId,
+    currency: 'CHF',
+    vatRate: 0,
+    lineItems: [
+      { position: 1, quantity: 1, description: 'Album', unit_price_minor: 50000, discount_percent: 0 },
+    ],
+  }, adminId);
+  const id = invoiceIds[0];
+  await db('invoices').where({ id }).update({ status: 'sent', sent_at: new Date(), updated_at: new Date() });
+
+  // Pre-fix this stalled inside the wrapping transaction (createInvoice's
+  // global-connection reads vs. the single-connection pool) and aborted
+  // before the replacement existed — with the Storno already committed.
+  const result = await invoiceService.reissueInvoice(id, adminId);
+  expect(result.id).toBeGreaterThan(0);
+  expect(result.replaces).toBe(id);
+
+  const replacement = await db('invoices').where({ id: result.id }).first();
+  expect(replacement.replaces_invoice_id).toBe(id);
+
+  const row = await db('activity_logs')
+    .where({ activity_type: 'invoice_reissued' })
+    .orderBy('id', 'desc')
+    .first();
+  expect(row).toBeTruthy();
+  expect(JSON.parse(row.metadata).newInvoiceId).toBe(result.id);
+});
+
+void path; // referenced for parity with sibling suites

backend/__tests__/services/pdfService.baseDocument.test.js

@@ -234,3 +234,66 @@ describe('renderInvoiceToBuffer — Storno branch', () => {
     expect(stornoBuf.length).toBeLessThan(invoiceBuf.length);
   });
 });
+
+// VAT free-text note (#794) + multi-page page-number placement. Same
+// constraint as the Storno tests: PDFKit Flate-compresses content streams,
+// so we can't grep the note text — but the page-TREE objects are NOT
+// compressed, so `/Type /Page` (not `/Pages`) is countable to assert
+// pagination, and a byte-size delta proves the note actually rendered.
+describe('renderInvoiceToBuffer — VAT note + multi-page footer (#794)', () => {
+  function baseCtx(overrides = {}) {
+    return {
+      locale: 'de', currency: 'CHF',
+      issuer: { companyName: 'AcmeCo' },
+      recipient: {
+        companyName: 'KundenCo', addressLine1: 'Strasse 1',
+        city: 'Bern', postalCode: '3000',
+      },
+      lineItems: [{
+        quantity: 1, description: 'Photo session',
+        unitPriceMinor: 30000, lineTotalMinor: 30000,
+        parentLineItemId: null, parentPosition: null,
+      }],
+      totals: {
+        netAmountMinor: 30000, vatRate: 0, vatAmountMinor: 0,
+        shippingAmountMinor: 0, totalAmountMinor: 30000,
+      },
+      doc: { invoiceNumber: 'R-2026-0042', issueDate: '2026-04-12' },
+      qrFormat: 'none',
+      paymentTerm: { netDays: 30 },
+      ...overrides,
+    };
+  }
+  const pageCount = (buf) => (buf.toString('latin1').match(/\/Type\s*\/Page(?![s])/g) || []).length;
+  const VAT_NOTE = 'Gemäß § 6 Abs. 1 Z 27 UStG 1994 wird keine Umsatzsteuer berechnet (Kleinunternehmer).';
+
+  it('renders the VAT note on a single-page invoice (adds content, valid PDF)', async () => {
+    const withNote = await pdfService.renderInvoiceToBuffer(baseCtx({ vatNote: VAT_NOTE }));
+    const without = await pdfService.renderInvoiceToBuffer(baseCtx());
+    expect(withNote.slice(0, 4).toString('ascii')).toBe('%PDF');
+    expect(pageCount(withNote)).toBe(1);
+    expect(withNote.length).toBeGreaterThan(without.length);
+  });
+
+  it('paginates a long invoice (with the note) across multiple pages without a stray blank page', async () => {
+    const manyItems = Array.from({ length: 60 }, (_, i) => ({
+      quantity: 1, description: `Position ${i + 1} — fotografische Leistung`,
+      unitPriceMinor: 3225, lineTotalMinor: 3225,
+      parentLineItemId: null, parentPosition: null,
+    }));
+    const buf = await pdfService.renderInvoiceToBuffer(baseCtx({
+      lineItems: manyItems,
+      totals: {
+        netAmountMinor: 193500, vatRate: 0, vatAmountMinor: 0,
+        shippingAmountMinor: 0, totalAmountMinor: 193500,
+      },
+      vatNote: VAT_NOTE,
+    }));
+    expect(buf.slice(0, 4).toString('ascii')).toBe('%PDF');
+    const pages = pageCount(buf);
+    expect(pages).toBeGreaterThanOrEqual(2);
+    // 60 short rows fit in 2–3 pages; a stray blank page (the old margin
+    // bug) or a runaway loop would blow past this.
+    expect(pages).toBeLessThanOrEqual(3);
+  });
+});

backend/__tests__/services/photoProcessor.processPhoto.test.js

@@ -71,24 +71,24 @@ jest.mock('../../src/services/imageProcessor', () => {
   const mockExtractCaptureDate = jest.fn();
   return {
     generateThumbnail: mockGenerateThumbnail,
+    generateVideoPlaceholder: jest.fn(async (filename) => `thumbnails/thumb_${filename.replace(/\.[^.]+$/, '')}.jpg`),
     extractCaptureDate: mockExtractCaptureDate,
-    // processPhoto routes stored dimensions through this to get the displayed
-    // ones (#1185). Mirrored rather than requireActual'd, because pulling the
-    // real module in here would drag its database dependency into the mock
-    // factory. Kept faithful to imageProcessor.orientedDimensions.
-    orientedDimensions: jest.fn((m) => {
-      if (!m || !m.width || !m.height) return { width: null, height: null };
-      const swap = m.orientation >= 5 && m.orientation <= 8;
-      return { width: swap ? m.height : m.width, height: swap ? m.width : m.height };
-    }),
     withLocalCopy: jest.fn(async (key, fn) =>
       fn(`/tmp/local-copy-${require('path').basename(key)}`)
     ),
+    // Pass-through for ordinary (non-RAW) images: returns the path unchanged
+    // with a no-op cleanup, matching the real helper's behaviour for jpg/png.
+    withProcessableImage: jest.fn(async (localPath) => ({
+      path: localPath,
+      outputBasename: undefined,
+      cleanup: () => {},
+    })),
   };
 });
 
 jest.mock('../../src/services/videoProcessor', () => ({
   processUploadedVideo: jest.fn(),
+  extractVideoMetadata: jest.fn(),
   isVideoMimeType: (mime) => typeof mime === 'string' && mime.startsWith('video/'),
 }));
 
@@ -214,6 +214,44 @@ describe('photoProcessor.processPhoto', () => {
     expect(watermarkService.generateForPhoto).not.toHaveBeenCalled();
   });
 
+  it('keeps a video complete with a placeholder thumbnail when ffmpeg fails', async () => {
+    dbModule.__setPhoto({
+      id: 203,
+      event_id: 9,
+      filename: 'drone-clip.mp4',
+      original_filename: 'drone.mp4',
+      mime_type: 'video/mp4',
+      media_type: 'video',
+      size_bytes: 12345,
+      captured_at: null,
+    });
+    dbModule.__setEvent({ id: 9, slug: 'wedding', event_name: 'Wedding' });
+
+    // ffmpeg thumbnail pipeline throws (e.g. unsupported pixel format)…
+    videoProcessor.processUploadedVideo.mockRejectedValueOnce(new Error('ffmpeg exited with code 1'));
+    // …but a plain probe still works.
+    videoProcessor.extractVideoMetadata.mockResolvedValueOnce({
+      duration: 42,
+      videoCodec: 'hevc',
+      audioCodec: 'aac',
+      width: 3840,
+      height: 2160,
+    });
+
+    const { processPhoto } = require('../../src/services/photoProcessor');
+    await processPhoto(203);
+
+    const finalUpdate = dbModule.__recorded().updateCalls.pop();
+    // The row must complete — 'failed' rows are invisible to guests.
+    expect(finalUpdate.data.processing_status).toBe('complete');
+    // Placeholder instead of NULL: a completed video without thumbnail would
+    // make the grid fetch the original video file for the tile (#845 review).
+    expect(finalUpdate.data.thumbnail_path).toBe('thumbnails/thumb_drone-clip.jpg');
+    expect(imageProcessor.generateVideoPlaceholder).toHaveBeenCalledWith('drone-clip.mp4');
+    expect(finalUpdate.data.duration).toBe(42);
+    expect(finalUpdate.data.video_codec).toBe('hevc');
+  });
+
   it('throws when the photo row no longer exists', async () => {
     dbModule.__setPhoto(null);
     dbModule.__setEvent({ id: 1 });

backend/__tests__/services/photoResolver.test.js

@@ -2,10 +2,10 @@ const path = require('path');
 const mockPath = path;
 
 jest.mock('../../src/services/externalMediaService', () => ({
-  resolveExternalPhotoPath: jest.fn((photo) => mockPath.join('/mock/external', photo.external_relpath || '')),
+  resolveExternalPath: jest.fn((event, relPath) => mockPath.join('/mock/external', event.external_path || '', relPath || '')),
 }));
 
-const { resolveExternalPhotoPath } = require('../../src/services/externalMediaService');
+const { resolveExternalPath } = require('../../src/services/externalMediaService');
 const { resolvePhotoFilePath } = require('../../src/services/photoResolver');
 
 describe('resolvePhotoFilePath', () => {
@@ -46,34 +46,24 @@ describe('resolvePhotoFilePath', () => {
     expect(result).toBe(path.join(backendRoot, 'storage', 'events/active', 'wedding-party', 'hero.jpg'));
   });
 
-  it('resolves an external photo from the media root, ignoring the event', () => {
+  it('delegates external photos to external media resolver', () => {
     const event = { slug: 'fashion-show', source_mode: 'reference', external_path: 'picsum-demo' };
-    const photo = { source_origin: 'external', external_relpath: 'picsum-demo/individual/look-01.jpg' };
+    const photo = { source_origin: 'external', external_relpath: 'individual/look-01.jpg' };
 
     const result = resolvePhotoFilePath(event, photo);
 
-    expect(resolveExternalPhotoPath).toHaveBeenCalledWith(photo);
+    expect(resolveExternalPath).toHaveBeenCalledWith(event, 'individual/look-01.jpg');
     expect(result).toBe(path.join('/mock/external', 'picsum-demo', 'individual', 'look-01.jpg'));
   });
 
-  it('does not move a photo when the event is repointed at another folder (#1163)', () => {
-    // The regression. Both events below hold the SAME row; only
-    // events.external_path differs, which is what a second import overwrites.
-    const photo = { source_origin: 'external', external_relpath: 'Trip/Leknes/_DSC0818.JPG' };
-    const before = { slug: 'trip', source_mode: 'reference', external_path: 'Trip' };
-    const after = { slug: 'trip', source_mode: 'reference', external_path: 'Trip/Subfolder' };
+  it('deduplicates folder names when event external path already ends with segment', () => {
+    const event = { slug: 'fashion-show', source_mode: 'reference', external_path: 'picsum-demo/individual' };
+    const photo = { source_origin: 'external', external_relpath: 'individual/look-02.jpg' };
 
-    expect(resolvePhotoFilePath(before, photo)).toBe(resolvePhotoFilePath(after, photo));
-  });
+    const result = resolvePhotoFilePath(event, photo);
 
-  it('keeps a first segment that repeats the base path', () => {
-    // The old duplicate-leaf-segment normalisation stripped this, which is
-    // corruption once the relpath is root-relative: `Trip/Trip/x.jpg` is a real
-    // layout, and the file is not at `Trip/x.jpg`.
-    const event = { slug: 'trip', source_mode: 'reference', external_path: 'Trip' };
-    const photo = { source_origin: 'external', external_relpath: 'Trip/Trip/x.jpg' };
-
-    expect(resolvePhotoFilePath(event, photo)).toBe(path.join('/mock/external', 'Trip', 'Trip', 'x.jpg'));
+    expect(resolveExternalPath).toHaveBeenCalledWith(event, 'look-02.jpg');
+    expect(result).toBe(path.join('/mock/external', 'picsum-demo/individual', 'look-02.jpg'));
   });
 
   it('falls back to managed storage when external metadata is missing', () => {
@@ -82,7 +72,7 @@ describe('resolvePhotoFilePath', () => {
 
     const result = resolvePhotoFilePath(event, photo);
 
-    expect(resolveExternalPhotoPath).not.toHaveBeenCalled();
+    expect(resolveExternalPath).not.toHaveBeenCalled();
     expect(result).toBe(path.join(backendRoot, 'storage', 'events/active', 'fashion-show', 'new-upload.jpg'));
   });
 

backend/__tests__/services/picpeakRolePreserve.test.js

@@ -0,0 +1,105 @@
+/**
+ * Tests for preserveOperatorRole — re-establishing the operator's authorization
+ * after a restore replaces the roles / permissions / role_permissions tables.
+ * Real in-memory SQLite so the joins and inserts behave as in production.
+ */
+const knex = require('knex');
+
+let db;
+let svc;
+
+beforeEach(async () => {
+  db = knex({ client: 'sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true });
+  await db.schema.createTable('roles', (t) => {
+    t.increments('id');
+    t.string('name').notNullable().unique();
+    t.string('display_name');
+    t.integer('priority').defaultTo(0);
+    t.boolean('is_system').defaultTo(false);
+  });
+  await db.schema.createTable('permissions', (t) => {
+    t.increments('id');
+    t.string('name').notNullable().unique();
+    t.string('display_name');
+    t.string('category');
+  });
+  await db.schema.createTable('role_permissions', (t) => {
+    t.integer('role_id').notNullable();
+    t.integer('permission_id').notNullable();
+    t.primary(['role_id', 'permission_id']);
+  });
+  await db.schema.createTable('admin_users', (t) => {
+    t.increments('id');
+    t.string('email');
+    t.integer('role_id');
+  });
+  jest.resetModules();
+  jest.doMock('../../knexfile', () => ({ client: 'sqlite3' }));
+  jest.doMock('../../src/database/db', () => ({ db }));
+  svc = require('../../src/services/picpeakImportService');
+});
+
+afterEach(async () => {
+  jest.dontMock('../../src/database/db');
+  jest.dontMock('../../knexfile');
+  await db.destroy();
+});
+
+test('captureOperatorRole returns the role + its permission names', async () => {
+  await db('roles').insert({ id: 1, name: 'super_admin', display_name: 'Super Admin', priority: 100 });
+  await db('permissions').insert([
+    { id: 1, name: 'events.create', display_name: 'Create', category: 'events' },
+    { id: 2, name: 'users.manage', display_name: 'Manage', category: 'users' },
+  ]);
+  await db('role_permissions').insert([{ role_id: 1, permission_id: 1 }, { role_id: 1, permission_id: 2 }]);
+
+  const snap = await svc.captureOperatorRole(1);
+  expect(snap.role.name).toBe('super_admin');
+  expect(snap.permissions.sort()).toEqual(['events.create', 'users.manage']);
+});
+
+test('preserveOperatorRole binds to a restored role of the same NAME (ids remapped)', async () => {
+  const snapshot = { role: { name: 'super_admin', display_name: 'Super Admin', priority: 100, is_system: true }, permissions: ['events.create'] };
+  // Simulate post-restore RBAC where super_admin now has a DIFFERENT id.
+  await db('roles').insert({ id: 7, name: 'super_admin', display_name: 'Super Admin (restored)', priority: 100 });
+  await db('admin_users').insert({ id: 3, email: 'op@example.com', role_id: null });
+
+  await db.transaction((trx) => svc.preserveOperatorRole(trx, 3, snapshot));
+
+  const op = await db('admin_users').where({ id: 3 }).first();
+  expect(op.role_id).toBe(7);                           // bound to restored super_admin by name
+  expect(await db('roles').count({ c: '*' }).first()).toEqual({ c: 1 }); // no duplicate role created
+});
+
+test('preserveOperatorRole re-creates the role + grants when the backup omits it', async () => {
+  const snapshot = {
+    role: { name: 'super_admin', display_name: 'Super Admin', priority: 100, is_system: true },
+    permissions: ['events.create', 'users.manage', 'gone.permission'],
+  };
+  // Post-restore RBAC WITHOUT super_admin; only some permissions exist.
+  await db('roles').insert({ id: 2, name: 'viewer', display_name: 'Viewer', priority: 10 });
+  await db('permissions').insert([
+    { id: 5, name: 'events.create', display_name: 'Create', category: 'events' },
+    { id: 6, name: 'users.manage', display_name: 'Manage', category: 'users' },
+  ]);
+  await db('admin_users').insert({ id: 3, email: 'op@example.com', role_id: null });
+
+  await db.transaction((trx) => svc.preserveOperatorRole(trx, 3, snapshot));
+
+  const recreated = await db('roles').where({ name: 'super_admin' }).first();
+  expect(recreated).toBeTruthy();                      // role re-created, not left missing
+  expect(recreated.id).toBe(3);                        // max(2)+1
+
+  const op = await db('admin_users').where({ id: 3 }).first();
+  expect(op.role_id).toBe(recreated.id);               // operator not locked out / downgraded
+
+  const grants = await db('role_permissions').where({ role_id: recreated.id }).pluck('permission_id');
+  expect(grants.sort()).toEqual([5, 6]);               // existing perms re-granted; 'gone.permission' skipped
+});
+
+test('preserveOperatorRole no-ops when the operator had no role', async () => {
+  await db('admin_users').insert({ id: 3, email: 'op@example.com', role_id: null });
+  await db.transaction((trx) => svc.preserveOperatorRole(trx, 3, null));
+  const op = await db('admin_users').where({ id: 3 }).first();
+  expect(op.role_id).toBeNull();
+});

backend/__tests__/services/rebillProofName.test.js

@@ -0,0 +1,38 @@
+/**
+ * renderProofName — the configurable Beleg proof-attachment filename template.
+ * Pure function; no DB. Covers token substitution, the multi-proof index
+ * fallback, padding, and filesystem-safe sanitisation.
+ */
+const { renderProofName } = require('../../src/services/invoice/rebillProofs');
+
+describe('renderProofName', () => {
+  const base = { invoiceNumber: 'R-2026-0042', supplierName: 'ACME AG', seq: 1, hasMulti: false, issueDate: '2026-08-03' };
+
+  it('defaults to Beleg-<invoice>.pdf', () => {
+    expect(renderProofName('Beleg-{INVOICE}', base)).toBe('Beleg-R-2026-0042.pdf');
+    expect(renderProofName('', base)).toBe('Beleg-R-2026-0042.pdf');
+    expect(renderProofName(null, base)).toBe('Beleg-R-2026-0042.pdf');
+  });
+
+  it('substitutes every token incl. padded SEQ and date parts', () => {
+    expect(renderProofName('{SUPPLIER}-{INVOICE}-{YEAR}{MONTH}-{SEQ:03d}', { ...base, seq: 7 }))
+      .toBe('ACME-AG-R-2026-0042-202608-007.pdf');
+  });
+
+  it('appends an index for multiple proofs only when the template has no {SEQ}', () => {
+    // No {SEQ} + multi → auto-suffixed with the index.
+    expect(renderProofName('Beleg-{INVOICE}', { ...base, seq: 2, hasMulti: true })).toBe('Beleg-R-2026-0042-2.pdf');
+    // Single proof → no suffix.
+    expect(renderProofName('Beleg-{INVOICE}', { ...base, seq: 1, hasMulti: false })).toBe('Beleg-R-2026-0042.pdf');
+    // Explicit {SEQ} → no double index even when multi.
+    expect(renderProofName('Beleg-{INVOICE}-{SEQ}', { ...base, seq: 2, hasMulti: true })).toBe('Beleg-R-2026-0042-2.pdf');
+  });
+
+  it('sanitises unsafe characters and slashes, and always ends in a single .pdf', () => {
+    expect(renderProofName('Beleg {INVOICE}', { ...base, invoiceNumber: '2026/0042' })).toBe('Beleg-2026-0042.pdf');
+    // Author-supplied extension is stripped and re-added (no double .pdf).
+    expect(renderProofName('{INVOICE}.pdf', base)).toBe('R-2026-0042.pdf');
+    // Falls back to 'Beleg' if the template renders empty after sanitising.
+    expect(renderProofName('{SUPPLIER}', { ...base, supplierName: '///' })).toBe('Beleg.pdf');
+  });
+});

backend/__tests__/services/transferOwnership.test.js

@@ -0,0 +1,247 @@
+/**
+ * Ownership guards for PicTransfer (#998 review, tracked as #1005).
+ *
+ * A transfer bundles ORIGINAL files and hands them out over an unauthenticated
+ * token URL, so the two guards below are the only thing standing between a
+ * scoped admin and every other admin's originals:
+ *
+ *   1. filterOwnedPhotoIds — a scoped admin may only bundle photos from events
+ *      they own. Without it, arbitrary photo ids in the create/add-files body
+ *      became a public download link to anyone's originals.
+ *   2. listTransfers scoping + payload stripping — the list used to be unscoped
+ *      AND to carry each row's download token, so any admin holding events.view
+ *      could read another's token and fetch their originals without creating
+ *      anything at all.
+ *
+ * Both were correct when merged. These tests exist so they stay that way: an
+ * untested guard does not survive refactoring, which #999 demonstrated when the
+ * same attribution fix landed in one component and was left stale in another.
+ * Each case below fails against the pre-fix behaviour, not merely passes
+ * against the current code.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-transferown-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'transferown-test-secret';
+
+const bcrypt = require('bcrypt');
+const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
+
+describe('PicTransfer ownership guards (#998)', () => {
+  let db; let cleanup; let transferService;
+  let editorA; let editorB; let superAdmin;
+  let eventA; let eventB; let eventOwnerless;
+  let photoA; let photoB; let photoOwnerless;
+
+  const asEditor = (id) => ({ id, roleName: 'editor' });
+
+  const mkAdmin = async (username, roleName) => {
+    const role = await db('roles').where({ name: roleName }).first();
+    const r = await db('admin_users').insert({
+      username, email: `${username}@example.com`,
+      password_hash: await bcrypt.hash('Passw0rd!', 4),
+      role_id: role.id, is_active: 1,
+      created_at: new Date().toISOString(), updated_at: new Date().toISOString(),
+    }).returning('id');
+    return r[0]?.id ?? r[0];
+  };
+
+  const mkEvent = async (slug, createdBy) => {
+    const r = await db('events').insert({
+      slug, event_type: 'wedding', event_name: slug, event_date: '2026-08-01',
+      host_email: 'h@e.com', admin_email: 'a@e.com', password_hash: 'x',
+      share_token: `t-${slug}`, share_link: `/g/${slug}/t-${slug}`,
+      created_by: createdBy,
+      expires_at: new Date(Date.now() + 864e5).toISOString(),
+      is_active: 1, is_archived: 0, is_draft: 0,
+      created_at: new Date().toISOString(),
+    }).returning('id');
+    return r[0]?.id ?? r[0];
+  };
+
+  const mkPhoto = async (eventId, filename) => {
+    const r = await db('photos').insert({
+      event_id: eventId, filename, path: `events/${eventId}/${filename}`,
+      type: 'individual', uploaded_at: Date.now(),
+    }).returning('id');
+    return r[0]?.id ?? r[0];
+  };
+
+  const mkTransfer = async (title, createdBy) => {
+    const r = await db('transfers').insert({
+      token: `tok-${title}-${'0'.repeat(50)}`.slice(0, 64),
+      title, created_by: createdBy,
+      expires_at: new Date(Date.now() + 864e5).toISOString(),
+      download_count: 0, is_active: 1, grace_days: 7, allow_uploads: 0,
+      delivery_method: 'link',
+      created_at: new Date().toISOString(), updated_at: new Date().toISOString(),
+    }).returning('id');
+    return r[0]?.id ?? r[0];
+  };
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    await seedMinimal(db);
+    transferService = require('../../src/services/transferService');
+
+    editorA = await mkAdmin('xfer-a', 'editor');
+    editorB = await mkAdmin('xfer-b', 'editor');
+    superAdmin = await mkAdmin('xfer-root', 'super_admin');
+
+    eventA = await mkEvent('xfer-own', editorA);
+    eventB = await mkEvent('xfer-foreign', editorB);
+    eventOwnerless = await mkEvent('xfer-legacy', null);
+
+    photoA = await mkPhoto(eventA, 'own.jpg');
+    photoB = await mkPhoto(eventB, 'foreign.jpg');
+    photoOwnerless = await mkPhoto(eventOwnerless, 'legacy.jpg');
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  describe('filterOwnedPhotoIds', () => {
+    it("drops photos from another admin's event", async () => {
+      // The exfiltration path: these ids would otherwise be bundled into a
+      // transfer and served over the public download token.
+      const owned = await transferService.filterOwnedPhotoIds(asEditor(editorA), [photoB]);
+      expect(owned).toEqual([]);
+    });
+
+    it("keeps photos from the caller's own event", async () => {
+      const owned = await transferService.filterOwnedPhotoIds(asEditor(editorA), [photoA]);
+      expect(owned).toEqual([photoA]);
+    });
+
+    it('keeps photos from an ownerless legacy event', async () => {
+      // Parity with filterOwnedEventIds, which treats created_by IS NULL as
+      // ownable by anyone — otherwise legacy events become unusable.
+      const owned = await transferService.filterOwnedPhotoIds(asEditor(editorA), [photoOwnerless]);
+      expect(owned).toEqual([photoOwnerless]);
+    });
+
+    it('keeps only the owned subset of a mixed request', async () => {
+      const owned = await transferService.filterOwnedPhotoIds(
+        asEditor(editorA), [photoA, photoB, photoOwnerless],
+      );
+      expect(owned.sort()).toEqual([photoA, photoOwnerless].sort());
+      expect(owned).not.toContain(photoB);
+    });
+
+    it('drops ids that do not exist', async () => {
+      const owned = await transferService.filterOwnedPhotoIds(asEditor(editorA), [999999]);
+      expect(owned).toEqual([]);
+    });
+
+    it('leaves super_admin unrestricted', async () => {
+      const owned = await transferService.filterOwnedPhotoIds(
+        { id: superAdmin, roleName: 'super_admin' }, [photoA, photoB, photoOwnerless],
+      );
+      expect(owned.sort()).toEqual([photoA, photoB, photoOwnerless].sort());
+    });
+  });
+
+  describe('addFiles gates on the same rule', () => {
+    it("refuses to attach another admin's photo", async () => {
+      // The guard has to sit in addFiles, not only at the route, because both
+      // createTransfer and POST /:id/files funnel through it.
+      const transferId = await mkTransfer('gate', editorA);
+      await transferService.addFiles(transferId, [photoA, photoB], asEditor(editorA));
+
+      const attached = await db('transfer_files')
+        .where({ transfer_id: transferId }).pluck('photo_id');
+      expect(attached).toContain(photoA);
+      expect(attached).not.toContain(photoB);
+    });
+  });
+
+  describe('listTransfers', () => {
+    let mineId; let theirsId;
+
+    beforeAll(async () => {
+      mineId = await mkTransfer('mine', editorA);
+      theirsId = await mkTransfer('theirs', editorB);
+    });
+
+    it("hides another admin's transfers from a scoped caller", async () => {
+      const rows = await transferService.listTransfers({ admin: asEditor(editorA) });
+      const ids = rows.map((r) => r.id);
+      expect(ids).toContain(mineId);
+      expect(ids).not.toContain(theirsId);
+    });
+
+    it('shows everything to super_admin', async () => {
+      const rows = await transferService.listTransfers({
+        admin: { id: superAdmin, roleName: 'super_admin' },
+      });
+      const ids = rows.map((r) => r.id);
+      expect(ids).toEqual(expect.arrayContaining([mineId, theirsId]));
+    });
+
+    it('never carries download or upload links in the list payload', async () => {
+      // Defence in depth on top of the scoping above, and the layer most likely
+      // to be undone by a "the list needs the link too" change. The token is a
+      // bearer credential for the originals — detail only.
+      const rows = await transferService.listTransfers({ admin: asEditor(editorA) });
+      expect(rows.length).toBeGreaterThan(0);
+      for (const row of rows) {
+        expect(row).not.toHaveProperty('token');
+        expect(row).not.toHaveProperty('upload_token');
+        expect(row).not.toHaveProperty('download_url');
+        expect(row).not.toHaveProperty('upload_url');
+      }
+    });
+  });
+
+  // The guard is a module-local middleware, so rather than stand up supertest
+  // just to prove Express ordering, assert the contract at the source — the
+  // same approach taken for the backup/restore contracts in #596. Ordering is
+  // the whole mechanism here: `router.use('/:id', …)` registered after the
+  // `/:id` routes would silently guard nothing while still looking present.
+  describe('requireTransferOwnership registration', () => {
+    const routerSrc = fs.readFileSync(
+      path.join(__dirname, '../../src/routes/adminTransfers.js'), 'utf8',
+    );
+
+    it('mounts the ownership guard before every /:id route', () => {
+      const guardAt = routerSrc.indexOf("router.use('/:id', requireTransferOwnership)");
+      expect(guardAt).toBeGreaterThan(-1);
+
+      const idRoutes = [...routerSrc.matchAll(/^router\.(get|post|patch|delete)\('\/:id/gm)];
+      expect(idRoutes.length).toBeGreaterThan(0);
+      for (const m of idRoutes) {
+        expect(m.index).toBeGreaterThan(guardAt);
+      }
+    });
+
+    it('answers missing and foreign ids identically, so it is not an existence oracle', () => {
+      const guard = routerSrc.slice(
+        routerSrc.indexOf('async function requireTransferOwnership'),
+        routerSrc.indexOf('// List'),
+      );
+      // Both branches must 404. A 403 on foreign would confirm the row exists.
+      const notFounds = [...guard.matchAll(/status\(404\)/g)];
+      expect(notFounds.length).toBeGreaterThanOrEqual(2);
+      expect(guard).not.toMatch(/status\(403\)/);
+      expect(guard).toMatch(/roleName === 'super_admin'/);
+    });
+  });
+
+  describe('getTransferOwner (backs requireTransferOwnership)', () => {
+    it('reports the creator so the route guard can compare it', async () => {
+      const id = await mkTransfer('owned-lookup', editorB);
+      const owner = await transferService.getTransferOwner(id);
+      expect(Number(owner.created_by)).toBe(Number(editorB));
+    });
+
+    it('returns nothing for a missing id, so the guard 404s rather than throwing', async () => {
+      const owner = await transferService.getTransferOwner(999999);
+      expect(owner).toBeFalsy();
+    });
+  });
+});

backend/__tests__/services/transferService.gating.test.js

@@ -0,0 +1,78 @@
+/**
+ * Unit tests for the pure gating logic in transferService (PicTransfer, #997).
+ * These exercise the download/upload eligibility rules without touching the DB.
+ */
+const transferService = require('../../src/services/transferService');
+
+const HOUR = 60 * 60 * 1000;
+
+function make(overrides = {}) {
+  return {
+    id: 1,
+    title: 'T',
+    is_active: true,
+    deleted_at: null,
+    expires_at: new Date(Date.now() + 24 * HOUR),
+    max_downloads: null,
+    download_count: 0,
+    allow_uploads: false,
+    upload_expires_at: null,
+    ...overrides,
+  };
+}
+
+describe('transferService.downloadsRemaining', () => {
+  it('returns null (unlimited) when no cap or zero cap', () => {
+    expect(transferService.downloadsRemaining(make({ max_downloads: null }))).toBeNull();
+    expect(transferService.downloadsRemaining(make({ max_downloads: 0 }))).toBeNull();
+  });
+
+  it('returns the remaining count and never goes negative', () => {
+    expect(transferService.downloadsRemaining(make({ max_downloads: 5, download_count: 2 }))).toBe(3);
+    expect(transferService.downloadsRemaining(make({ max_downloads: 5, download_count: 9 }))).toBe(0);
+  });
+});
+
+describe('transferService.computeStatus', () => {
+  it('is deleted when deleted_at set, regardless of activity', () => {
+    expect(transferService.computeStatus(make({ deleted_at: new Date(), is_active: true }))).toBe('deleted');
+  });
+  it('is expired when inactive or past expiry', () => {
+    expect(transferService.computeStatus(make({ is_active: false }))).toBe('expired');
+    expect(transferService.computeStatus(make({ expires_at: new Date(Date.now() - HOUR) }))).toBe('expired');
+  });
+  it('is active within the window', () => {
+    expect(transferService.computeStatus(make())).toBe('active');
+  });
+});
+
+describe('transferService.assertDownloadable', () => {
+  it('allows a live, in-window, uncapped transfer', () => {
+    expect(transferService.assertDownloadable(make()).ok).toBe(true);
+  });
+  it('404s a missing/deleted transfer', () => {
+    expect(transferService.assertDownloadable(null)).toMatchObject({ ok: false, status: 404 });
+    expect(transferService.assertDownloadable(make({ deleted_at: new Date() }))).toMatchObject({ ok: false, status: 404 });
+  });
+  it('410s when disabled or expired', () => {
+    expect(transferService.assertDownloadable(make({ is_active: false }))).toMatchObject({ ok: false, code: 'TRANSFER_DISABLED', status: 410 });
+    expect(transferService.assertDownloadable(make({ expires_at: new Date(Date.now() - HOUR) }))).toMatchObject({ ok: false, code: 'TRANSFER_EXPIRED', status: 410 });
+  });
+  it('410s when the download cap is reached', () => {
+    expect(transferService.assertDownloadable(make({ max_downloads: 2, download_count: 2 })))
+      .toMatchObject({ ok: false, code: 'DOWNLOAD_LIMIT_REACHED', status: 410 });
+  });
+});
+
+describe('transferService.assertUploadable', () => {
+  it('403s when uploads are disabled', () => {
+    expect(transferService.assertUploadable(make({ allow_uploads: false }))).toMatchObject({ ok: false, code: 'UPLOADS_DISABLED', status: 403 });
+  });
+  it('allows when uploads enabled and not expired', () => {
+    expect(transferService.assertUploadable(make({ allow_uploads: true })).ok).toBe(true);
+  });
+  it('410s when the upload window has passed', () => {
+    expect(transferService.assertUploadable(make({ allow_uploads: true, upload_expires_at: new Date(Date.now() - HOUR) })))
+      .toMatchObject({ ok: false, code: 'UPLOAD_EXPIRED', status: 410 });
+  });
+});

backend/__tests__/services/updateCheckRegistryMigration.test.js

@@ -0,0 +1,52 @@
+/**
+ * Pre-rename detection for the registry-move notice (#985).
+ *
+ * The in-app MigrationBanner shipped 2026-06-29, a month AFTER
+ * ghcr.io/the-luap/picpeak/* stopped receiving images on 2026-05-27. Anyone
+ * still pulling the retired path is therefore running a build that predates the
+ * banner and can never render it — the structural gap that keeps producing
+ * reports like #982. The update check is the one channel that still reaches
+ * them, so it carries the notice instead.
+ *
+ * The boundary is exact rather than heuristic: v3.44.0 shipped on the freeze
+ * date and v3.45.0 followed on 2026-07-09 to the org registry only, with
+ * nothing published in between.
+ */
+
+const { isPreRenameStable, REGISTRY_RENAME_STABLE_FLOOR } = require('../../src/services/updateCheckService');
+
+describe('isPreRenameStable (#985)', () => {
+  it('pins the floor to the first org-registry-only stable release', () => {
+    expect(REGISTRY_RENAME_STABLE_FLOOR).toBe('3.45.0');
+  });
+
+  it('flags stable installs below the floor', () => {
+    // v3.44.0 is the last stable that reached the retired path.
+    expect(isPreRenameStable('3.44.0', 'stable')).toBe(true);
+    expect(isPreRenameStable('3.43.1', 'stable')).toBe(true);
+    expect(isPreRenameStable('2.6.5', 'stable')).toBe(true);
+  });
+
+  it('leaves stable installs at or above the floor alone', () => {
+    expect(isPreRenameStable('3.45.0', 'stable')).toBe(false);
+    expect(isPreRenameStable('3.45.13', 'stable')).toBe(false);
+    expect(isPreRenameStable('3.99.0', 'stable')).toBe(false);
+  });
+
+  it('never fires on the beta channel', () => {
+    // The beta boundary is inferred, not clean — 3.59.0-beta.0 landed two days
+    // after the freeze. A false positive would tell a correctly-configured
+    // operator their registry is retired, so beta is deliberately excluded even
+    // where the number looks old.
+    expect(isPreRenameStable('3.44.0-beta.0', 'beta')).toBe(false);
+    expect(isPreRenameStable('3.58.0-beta.0', 'beta')).toBe(false);
+    expect(isPreRenameStable('3.99.0-beta.0', 'beta')).toBe(false);
+  });
+
+  it('does not fire on an unresolvable version', () => {
+    // getCurrentVersion() falls back to '0.0.0' when package.json is
+    // unreadable. That is a broken install, not a pre-rename one — claiming its
+    // registry is retired would send the operator down the wrong path.
+    expect(isPreRenameStable('0.0.0', 'stable')).toBe(false);
+  });
+});

backend/__tests__/services/uploadSettingsFileTypes.test.js

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const path = require('path');
+
+const {
+  EXTENSION_TO_MIME,
+  extensionsToMimeTypes,
+} = require('../../src/services/uploadSettings');
+const { validateFileType } = require('../../src/utils/fileSecurityUtils');
+
+const RAW_AND_HEIF_TYPES = {
+  dng: 'image/x-adobe-dng',
+  heic: 'image/heic',
+  heif: 'image/heif',
+};
+
+function getFrontendExtensionMap() {
+  const source = fs.readFileSync(
+    path.join(__dirname, '../../../frontend/src/utils/fileTypes.ts'),
+    'utf8'
+  );
+  const match = source.match(/const EXTENSION_TO_MIME[^=]*= \{([\s\S]*?)\n\};/);
+  if (!match) throw new Error('Could not find frontend EXTENSION_TO_MIME');
+
+  // Parse `key: 'mime',` entries — quoted keys and trailing `//` comments are
+  // tolerated; any other non-blank, non-comment line inside the map is a parse
+  // failure, so a syntax the parser can't read fails loudly instead of silently
+  // dropping the entry from the comparison.
+  const entries = [];
+  for (const line of match[1].split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('//')) continue;
+    const entry = trimmed.match(/^'?(\w+)'?\s*:\s*'([^']+)'\s*,?\s*(?:\/\/.*)?$/);
+    if (!entry) throw new Error(`Unparsable EXTENSION_TO_MIME line in frontend fileTypes.ts: "${trimmed}"`);
+    entries.push([entry[1], entry[2]]);
+  }
+  return Object.fromEntries(entries);
+}
+
+describe('configured upload file types', () => {
+  test('supports configured DNG, HEIC, and HEIF uploads', () => {
+    expect(extensionsToMimeTypes('dng,heic,heif')).toEqual(Object.values(RAW_AND_HEIF_TYPES));
+
+    for (const [extension, mimeType] of Object.entries(RAW_AND_HEIF_TYPES)) {
+      expect(validateFileType(`image.${extension}`, mimeType, [mimeType])).toBe(true);
+    }
+  });
+
+  test('uses the same extension-to-MIME map as the frontend', () => {
+    expect(getFrontendExtensionMap()).toEqual(EXTENSION_TO_MIME);
+  });
+});

backend/__tests__/services/uploadSettingsMaxFileSize.test.js

@@ -0,0 +1,65 @@
+/**
+ * Unit tests for the per-file upload size limit getter (general_max_file_size_mb),
+ * added so the admin's "Max File Size (MB)" setting applies to guest uploads
+ * (#613 follow-up — mat1990dj). Real in-memory SQLite app_settings so the
+ * read/parse/cache path runs exactly as in production.
+ */
+const knex = require('knex');
+
+let db;
+let svc;
+
+beforeEach(async () => {
+  db = knex({ client: 'sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true });
+  await db.schema.createTable('app_settings', (t) => {
+    t.increments('id');
+    t.string('setting_key').notNullable().unique();
+    t.text('setting_value');
+    t.string('setting_type');
+    t.timestamp('updated_at');
+  });
+  jest.resetModules();
+  jest.doMock('../../src/database/db', () => ({ db }));
+  svc = require('../../src/services/uploadSettings');
+  svc.clearMaxFileSizeCache();
+});
+
+afterEach(async () => {
+  jest.dontMock('../../src/database/db');
+  await db.destroy();
+});
+
+async function setLimit(mb) {
+  await db('app_settings')
+    .insert({ setting_key: 'general_max_file_size_mb', setting_value: JSON.stringify(mb), setting_type: 'general', updated_at: new Date() })
+    .onConflict('setting_key').merge({ setting_value: JSON.stringify(mb) });
+  svc.clearMaxFileSizeCache();
+}
+
+test('defaults to 50MB when the setting is absent', async () => {
+  expect(await svc.getMaxFileSizeMb()).toBe(50);
+  expect(await svc.getMaxFileSizeBytes()).toBe(50 * 1024 * 1024);
+});
+
+test('honours a configured value (e.g. 500MB video)', async () => {
+  await setLimit(500);
+  expect(await svc.getMaxFileSizeMb()).toBe(500);
+  expect(await svc.getMaxFileSizeBytes()).toBe(500 * 1024 * 1024);
+});
+
+test('clamps a nonsense value to the default and caps absurd values at the ceiling', async () => {
+  await setLimit(0);
+  expect(await svc.getMaxFileSizeMb()).toBe(50); // 0 → default
+  await setLimit(99_999_999);
+  expect(await svc.getMaxFileSizeMb()).toBe(svc.MAX_ALLOWED_FILE_SIZE_MB); // ceiling
+});
+
+test('caches for the TTL — a mid-window DB change is not seen until the cache is cleared', async () => {
+  await setLimit(200);
+  expect(await svc.getMaxFileSizeMb()).toBe(200);
+  // change the DB but do NOT clear cache
+  await db('app_settings').where({ setting_key: 'general_max_file_size_mb' }).update({ setting_value: JSON.stringify(300) });
+  expect(await svc.getMaxFileSizeMb()).toBe(200); // still cached
+  svc.clearMaxFileSizeCache();
+  expect(await svc.getMaxFileSizeMb()).toBe(300); // refreshed
+});

backend/__tests__/utils/bannerOverridePlumbing.test.js

@@ -0,0 +1,199 @@
+/**
+ * Per-event banner overrides — end-to-end plumbing for BOTH banners.
+ *
+ * The promo banner (#440) shipped with per-event inherit/custom/off, but the
+ * override never actually reached a guest: GalleryView reads promo_mode from
+ * the /photos payload and /photos never sent it, so every gallery resolved to
+ * 'inherit'. Setting a gallery's promo banner to "Off" did nothing. The info
+ * banner (#932) mirrored that shape and inherited the same gaps.
+ *
+ * Four places dropped the fields. This pins all of them for both banners so
+ * the two stay in step:
+ *
+ *   1. GET  /gallery/:slug/photos   — must carry the columns
+ *   2. POST /admin/events           — validators accepted them, insert dropped
+ *   3. POST /admin/events/:id/duplicate — copy promised, not delivered
+ *   4. PUT  /admin/events/:id       — partial update parked stale markdown
+ *
+ * The route-level normalisation is exercised directly against its own rules
+ * rather than through supertest: the intent is to pin the DATA contract, which
+ * is what silently broke.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-banner-plumbing-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'banner-plumbing-secret';
+
+const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
+
+let db;
+let cleanup;
+
+const baseEvent = (slug, extra = {}) => ({
+  slug,
+  event_type: 'wedding',
+  event_name: slug,
+  event_date: '2026-06-22',
+  host_email: 'host@example.com',
+  admin_email: 'admin@example.com',
+  password_hash: 'x',
+  share_link: `/gallery/${slug}/share`,
+  share_token: `${slug}-share`,
+  expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+  is_active: 1,
+  is_archived: 0,
+  is_draft: 0,
+  created_at: new Date().toISOString(),
+  ...extra,
+});
+
+const insertEvent = async (slug, extra) => {
+  const [id] = await db('events').insert(baseEvent(slug, extra)).returning('id');
+  return id?.id ?? id;
+};
+
+beforeAll(async () => {
+  ({ db, cleanup } = await bootCrmDb());
+  await seedMinimal(db);
+});
+
+afterAll(async () => {
+  if (cleanup) await cleanup();
+});
+
+// Mirrors the unified normalisation in adminEvents/crud.js.
+function normalizeBannerUpdates(updates, stored) {
+  for (const field of ['promo', 'info']) {
+    const modeKey = `${field}_mode`;
+    const mdKey = `${field}_markdown`;
+    if (!Object.prototype.hasOwnProperty.call(updates, modeKey)
+      && !Object.prototype.hasOwnProperty.call(updates, mdKey)) continue;
+
+    const effectiveMode = Object.prototype.hasOwnProperty.call(updates, modeKey)
+      ? updates[modeKey]
+      : stored[modeKey];
+
+    if (effectiveMode !== 'custom') {
+      updates[mdKey] = null;
+    } else if (Object.prototype.hasOwnProperty.call(updates, mdKey)) {
+      const md = typeof updates[mdKey] === 'string' ? updates[mdKey].trim() : '';
+      updates[mdKey] = md || null;
+    }
+  }
+  return updates;
+}
+
+describe('partial update resolves the mode from the stored row', () => {
+  it.each(['promo', 'info'])(
+    '%s: markdown-only PUT on an inherit gallery does not park hidden text',
+    (field) => {
+      const stored = { promo_mode: 'inherit', info_mode: 'inherit' };
+      const updates = normalizeBannerUpdates({ [`${field}_markdown`]: 'hidden draft' }, stored);
+
+      // Previously stored the text; a later switch to 'custom' resurrected it.
+      expect(updates[`${field}_markdown`]).toBeNull();
+    },
+  );
+
+  it.each(['promo', 'info'])('%s: markdown-only PUT on an off gallery also clears', (field) => {
+    const stored = { promo_mode: 'off', info_mode: 'off' };
+    const updates = normalizeBannerUpdates({ [`${field}_markdown`]: 'hidden draft' }, stored);
+
+    expect(updates[`${field}_markdown`]).toBeNull();
+  });
+
+  it.each(['promo', 'info'])('%s: markdown-only PUT on a custom gallery is kept', (field) => {
+    const stored = { promo_mode: 'custom', info_mode: 'custom' };
+    const updates = normalizeBannerUpdates({ [`${field}_markdown`]: '  keep me  ' }, stored);
+
+    expect(updates[`${field}_markdown`]).toBe('keep me');
+  });
+
+  it.each(['promo', 'info'])('%s: switching away from custom clears the copy', (field) => {
+    const stored = { promo_mode: 'custom', info_mode: 'custom' };
+    const updates = normalizeBannerUpdates(
+      { [`${field}_mode`]: 'off', [`${field}_markdown`]: 'stale' }, stored,
+    );
+
+    expect(updates[`${field}_markdown`]).toBeNull();
+  });
+
+  it('leaves both banners alone when the request touches neither', () => {
+    const updates = normalizeBannerUpdates({ event_name: 'Renamed' }, { promo_mode: 'custom', info_mode: 'custom' });
+
+    expect(Object.prototype.hasOwnProperty.call(updates, 'promo_markdown')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(updates, 'info_markdown')).toBe(false);
+  });
+});
+
+describe('columns round-trip through the events table', () => {
+  it('stores and reads both banners independently', async () => {
+    const id = await insertEvent('banner-roundtrip', {
+      promo_mode: 'off',
+      info_mode: 'custom',
+      info_markdown: 'Use the menu button to filter.',
+    });
+
+    const row = await db('events').where({ id }).first();
+    // Independent slots — muting one must not touch the other.
+    expect(row.promo_mode).toBe('off');
+    expect(row.promo_markdown ?? null).toBeNull();
+    expect(row.info_mode).toBe('custom');
+    expect(row.info_markdown).toBe('Use the menu button to filter.');
+  });
+
+  it('duplicating drops markdown left over on a non-custom source', async () => {
+    // A row written before the PUT normalisation landed can hold text while
+    // its mode is inherit/off. Copying that verbatim would smuggle hidden copy
+    // into the duplicate and resurrect it on the next switch to 'custom'.
+    const sourceId = await insertEvent('banner-dup-stale', {
+      promo_mode: 'off',
+      promo_markdown: 'stale promo text',
+      info_mode: 'inherit',
+      info_markdown: 'stale info text',
+    });
+    const source = await db('events').where({ id: sourceId }).first();
+
+    const dupId = await insertEvent('banner-dup-stale-copy', {
+      promo_mode: source.promo_mode || 'inherit',
+      promo_markdown: source.promo_mode === 'custom' ? (source.promo_markdown || null) : null,
+      info_mode: source.info_mode || 'inherit',
+      info_markdown: source.info_mode === 'custom' ? (source.info_markdown || null) : null,
+    });
+
+    const dup = await db('events').where({ id: dupId }).first();
+    expect(dup.promo_mode).toBe('off');
+    expect(dup.promo_markdown).toBeNull();
+    expect(dup.info_mode).toBe('inherit');
+    expect(dup.info_markdown).toBeNull();
+  });
+
+  it('duplicating an event carries both banners across', async () => {
+    const sourceId = await insertEvent('banner-dup-source', {
+      promo_mode: 'custom',
+      promo_markdown: 'Book your next session',
+      info_mode: 'off',
+    });
+    const source = await db('events').where({ id: sourceId }).first();
+
+    // Mirrors the duplicate route's insert.
+    const dupId = await insertEvent('banner-dup-copy', {
+      promo_mode: source.promo_mode || 'inherit',
+      promo_markdown: source.promo_mode === 'custom' ? (source.promo_markdown || null) : null,
+      info_mode: source.info_mode || 'inherit',
+      info_markdown: source.info_mode === 'custom' ? (source.info_markdown || null) : null,
+    });
+
+    const dup = await db('events').where({ id: dupId }).first();
+    expect(dup.promo_mode).toBe('custom');
+    expect(dup.promo_markdown).toBe('Book your next session');
+    // The muted info banner must stay muted in the copy.
+    expect(dup.info_mode).toBe('off');
+  });
+});

backend/__tests__/utils/feedbackRatingRemoval.test.js

@@ -0,0 +1,177 @@
+/**
+ * Unit tests for rating removal (#884).
+ *
+ * Pins the contract of `feedbackService.submitFeedback` for
+ * `feedback_type: 'rating'` with `rating: 0` ("clear my rating"):
+ *  - An existing rating row is DELETED (not updated to 0 — a stored 0
+ *    would drag the photo's average down and still count in totals).
+ *  - Photo stats (average_rating) are recalculated after the delete.
+ *  - Rating 0 with no existing rating is a no-op that never inserts a row.
+ *  - Removal is guest-scoped: clearing guest A's rating leaves guest B's
+ *    rating (and the resulting average) intact.
+ *  - Regular re-rating (3 → 5) still updates in place.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-rating-removal-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'rating-removal-test-secret';
+
+const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
+
+const feedbackService = require('../../src/services/feedbackService');
+
+const EVENT_SLUG = 'rating-removal-event';
+const GUEST_A = 'guest-a-identifier';
+const GUEST_B = 'guest-b-identifier';
+
+let db;
+let cleanup;
+let eventId;
+let photoId;
+
+async function rate(rating, guestIdentifier = GUEST_A) {
+  return feedbackService.submitFeedback(photoId, eventId, {
+    feedback_type: 'rating',
+    rating,
+    ip_address: '127.0.0.1',
+    user_agent: 'jest',
+  }, guestIdentifier);
+}
+
+async function ratingRows(guestIdentifier) {
+  const q = db('photo_feedback').where({
+    photo_id: photoId,
+    feedback_type: 'rating',
+  });
+  if (guestIdentifier) q.where('guest_identifier', guestIdentifier);
+  return q.select('*');
+}
+
+async function photoAverage() {
+  const photo = await db('photos').where('id', photoId).first();
+  return Number(photo.average_rating);
+}
+
+beforeAll(async () => {
+  ({ db, cleanup } = await bootCrmDb());
+  await seedMinimal(db);
+  const inserted = await db('events').insert({
+    slug: EVENT_SLUG,
+    event_type: 'wedding',
+    event_name: 'Rating Removal Test',
+    event_date: '2026-06-22',
+    host_email: 'host@example.com',
+    admin_email: 'admin@example.com',
+    password_hash: 'x',
+    share_link: `/gallery/${EVENT_SLUG}/share`,
+    share_token: 'rating-removal-share',
+    expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+    is_active: 1,
+    is_archived: 0,
+    is_draft: 0,
+    created_at: new Date().toISOString(),
+  }).returning('id');
+  eventId = inserted[0]?.id ?? inserted[0];
+
+  const r = await db('photos').insert({
+    event_id: eventId,
+    filename: 'photo-1.jpg',
+    path: 'events/rating-removal/1.jpg',
+    type: 'individual',
+    uploaded_at: new Date().toISOString(),
+  }).returning('id');
+  photoId = r[0]?.id ?? r[0];
+}, 120000);
+
+afterAll(async () => { if (cleanup) await cleanup(); });
+
+beforeEach(async () => {
+  await db('photo_feedback').where('event_id', eventId).del();
+  await db('photos').where('id', photoId).update({ average_rating: 0, feedback_count: 0 });
+});
+
+describe('rating removal (#884)', () => {
+  test('rating 0 deletes the existing rating row and resets the average', async () => {
+    const created = await rate(4);
+    expect(created.created).toBe(true);
+    expect(await photoAverage()).toBe(4);
+
+    const removed = await rate(0);
+    expect(removed.removed).toBe(true);
+    expect(await ratingRows(GUEST_A)).toHaveLength(0);
+    expect(await photoAverage()).toBe(0);
+  });
+
+  test('rating 0 without an existing rating is a no-op (no 0-row inserted)', async () => {
+    const r = await rate(0);
+    expect(r.removed).toBe(true);
+    expect(await ratingRows()).toHaveLength(0);
+    expect(await photoAverage()).toBe(0);
+  });
+
+  test('removal is guest-scoped: guest B keeps their rating and the average', async () => {
+    await rate(2, GUEST_A);
+    await rate(4, GUEST_B);
+    expect(await photoAverage()).toBe(3);
+
+    const removed = await rate(0, GUEST_A);
+    expect(removed.removed).toBe(true);
+    expect(await ratingRows(GUEST_A)).toHaveLength(0);
+    expect(await ratingRows(GUEST_B)).toHaveLength(1);
+    expect(await photoAverage()).toBe(4);
+  });
+
+  test('numeric string "0" also clears (truthy-string bypass guard)', async () => {
+    await rate(4);
+    const removed = await rate('0');
+    expect(removed.removed).toBe(true);
+    expect(await ratingRows(GUEST_A)).toHaveLength(0);
+    expect(await photoAverage()).toBe(0);
+  });
+
+  test('malformed rating input never clears an existing rating', async () => {
+    await rate(4);
+    for (const bad of [undefined, null, 'bad', NaN]) {
+      const r = await rate(bad);
+      expect(r.removed).toBeFalsy();
+    }
+    expect(await ratingRows(GUEST_A)).toHaveLength(1);
+  });
+
+  test('clearing deletes racy duplicate rating rows, not just the first', async () => {
+    // Simulate the check-then-insert race: two rating rows for one guest.
+    const row = {
+      photo_id: photoId,
+      event_id: eventId,
+      feedback_type: 'rating',
+      guest_identifier: GUEST_A,
+      is_approved: 1,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+    await db('photo_feedback').insert({ ...row, rating: 3 });
+    await db('photo_feedback').insert({ ...row, rating: 5 });
+    expect(await ratingRows(GUEST_A)).toHaveLength(2);
+
+    const removed = await rate(0);
+    expect(removed.removed).toBe(true);
+    expect(await ratingRows(GUEST_A)).toHaveLength(0);
+    expect(await photoAverage()).toBe(0);
+  });
+
+  test('re-rating with a different value still updates in place', async () => {
+    await rate(3);
+    const updated = await rate(5);
+    expect(updated.updated).toBe(true);
+    const rows = await ratingRows(GUEST_A);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].rating).toBe(5);
+    expect(await photoAverage()).toBe(5);
+  });
+});

backend/__tests__/utils/feedbackReactions.test.js

@@ -0,0 +1,202 @@
+/**
+ * Emoji reactions (#839) — pins the contract of the `reaction` feedback type:
+ *  - only emojis from the fixed curated set are accepted
+ *  - one reaction per guest per photo: same emoji again toggles OFF,
+ *    a different emoji SWITCHES the existing row (never a second row)
+ *  - per-guest scoping mirrors likes: guest_id when present, else the
+ *    device-hash guest_identifier — two token-guests on one device react
+ *    independently
+ *  - denormalized photos.reaction_count and the per-emoji tallies follow
+ *    visibility: hidden-by-moderator reactions disappear from both
+ *  - the long and pivoted exports carry the reaction
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-feedback-reactions-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'feedback-reactions-test-secret';
+
+const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
+
+const feedbackService = require('../../src/services/feedbackService');
+const { REACTION_EMOJIS } = require('../../src/constants/reactions');
+
+const EVENT_SLUG = 'reactions-test-event';
+const GUEST_A = 'guest-a-identifier';
+const GUEST_B = 'guest-b-identifier';
+
+let db;
+let cleanup;
+let eventId;
+let photoIds;
+
+async function react(photoId, emoji, { guestIdentifier = GUEST_A, guestId = null } = {}) {
+  return feedbackService.submitFeedback(photoId, eventId, {
+    feedback_type: 'reaction',
+    reaction: emoji,
+    guest_id: guestId,
+    ip_address: '127.0.0.1',
+    user_agent: 'jest',
+  }, guestIdentifier);
+}
+
+async function reactionCountOf(photoId) {
+  const row = await db('photos').where('id', photoId).first();
+  return Number(row.reaction_count) || 0;
+}
+
+beforeAll(async () => {
+  ({ db, cleanup } = await bootCrmDb());
+  await seedMinimal(db);
+  const inserted = await db('events').insert({
+    slug: EVENT_SLUG,
+    event_type: 'wedding',
+    event_name: 'Reactions Test',
+    event_date: '2026-07-20',
+    host_email: 'host@example.com',
+    admin_email: 'admin@example.com',
+    password_hash: 'x',
+    share_link: `/gallery/${EVENT_SLUG}/share`,
+    share_token: 'reactions-test-share',
+    expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+    is_active: 1,
+    is_archived: 0,
+    is_draft: 0,
+    created_at: new Date().toISOString(),
+  }).returning('id');
+  eventId = inserted[0]?.id ?? inserted[0];
+
+  photoIds = [];
+  for (let i = 0; i < 3; i++) {
+    const photo = await db('photos').insert({
+      event_id: eventId,
+      filename: `photo-${i}.jpg`,
+      path: `events/reactions/${i}.jpg`,
+      type: 'individual',
+      uploaded_at: new Date().toISOString(),
+    }).returning('id');
+    photoIds.push(photo[0]?.id ?? photo[0]);
+  }
+}, 120000);
+
+afterAll(async () => {
+  if (cleanup) await cleanup();
+});
+
+describe('reaction submission (#839)', () => {
+  it('rejects emojis outside the curated set', async () => {
+    await expect(react(photoIds[0], '🦄')).rejects.toThrow('Invalid reaction');
+    await expect(react(photoIds[0], undefined)).rejects.toThrow('Invalid reaction');
+    expect(await reactionCountOf(photoIds[0])).toBe(0);
+  });
+
+  it('creates a reaction row and maintains the denormalized count', async () => {
+    const result = await react(photoIds[0], '❤️');
+    expect(result.created).toBe(true);
+
+    const row = await db('photo_feedback')
+      .where({ photo_id: photoIds[0], feedback_type: 'reaction' })
+      .first();
+    expect(row.reaction).toBe('❤️');
+    expect(await reactionCountOf(photoIds[0])).toBe(1);
+    expect(await feedbackService.getPhotoReactionCounts(photoIds[0])).toEqual({ '❤️': 1 });
+  });
+
+  it('switches to another emoji in place — never a second row per guest', async () => {
+    const result = await react(photoIds[0], '🎉');
+    expect(result.updated).toBe(true);
+
+    const rows = await db('photo_feedback')
+      .where({ photo_id: photoIds[0], feedback_type: 'reaction' });
+    expect(rows).toHaveLength(1);
+    expect(rows[0].reaction).toBe('🎉');
+    expect(await feedbackService.getPhotoReactionCounts(photoIds[0])).toEqual({ '🎉': 1 });
+  });
+
+  it('tallies different guests per emoji', async () => {
+    await react(photoIds[0], '🎉', { guestIdentifier: GUEST_B });
+    expect(await feedbackService.getPhotoReactionCounts(photoIds[0])).toEqual({ '🎉': 2 });
+    expect(await reactionCountOf(photoIds[0])).toBe(2);
+  });
+
+  it('toggles off with the same emoji', async () => {
+    const result = await react(photoIds[0], '🎉');
+    expect(result.removed).toBe(true);
+    expect(await feedbackService.getPhotoReactionCounts(photoIds[0])).toEqual({ '🎉': 1 }); // GUEST_B remains
+    expect(await reactionCountOf(photoIds[0])).toBe(1);
+  });
+
+  it('scopes per guest_id when present — two token-guests on one device stay independent', async () => {
+    const first = await react(photoIds[1], '😍', { guestIdentifier: GUEST_A, guestId: 101 });
+    const second = await react(photoIds[1], '👏', { guestIdentifier: GUEST_A, guestId: 102 });
+    expect(first.created).toBe(true);
+    expect(second.created).toBe(true); // NOT treated as guest 101's switch
+    expect(await feedbackService.getPhotoReactionCounts(photoIds[1])).toEqual({ '😍': 1, '👏': 1 });
+  });
+
+  it('accepts every emoji of the curated set', async () => {
+    for (const emoji of REACTION_EMOJIS) {
+      const res = await react(photoIds[2], emoji, { guestIdentifier: `guest-${emoji}` });
+      expect(res.created).toBe(true);
+    }
+    const counts = await feedbackService.getPhotoReactionCounts(photoIds[2]);
+    expect(Object.keys(counts)).toHaveLength(REACTION_EMOJIS.length);
+  });
+
+  it('hidden reactions leave both the per-emoji tallies and reaction_count', async () => {
+    const row = await db('photo_feedback')
+      .where({ photo_id: photoIds[0], feedback_type: 'reaction' })
+      .first();
+    await feedbackService.moderateFeedback(row.id, 'hide', 1);
+
+    expect(await feedbackService.getPhotoReactionCounts(photoIds[0])).toEqual({});
+    expect(await reactionCountOf(photoIds[0])).toBe(0);
+
+    await feedbackService.moderateFeedback(row.id, 'approve', 1);
+    expect(await reactionCountOf(photoIds[0])).toBe(1);
+  });
+
+  it('toggle and switch collapse racy duplicate rows for the same guest', async () => {
+    // Simulate the check-then-insert race: two rows for one guest+photo.
+    const mk = (emoji) => ({
+      photo_id: photoIds[1], event_id: eventId, feedback_type: 'reaction',
+      reaction: emoji, guest_identifier: 'dup-guest', is_approved: true, is_hidden: false,
+      created_at: new Date(), updated_at: new Date(),
+    });
+    await db('photo_feedback').insert([mk('❤️'), mk('❤️')]);
+
+    // Switching converges to exactly ONE row with the new emoji…
+    const switched = await react(photoIds[1], '🎉', { guestIdentifier: 'dup-guest' });
+    expect(switched.updated).toBe(true);
+    let rows = await db('photo_feedback')
+      .where({ photo_id: photoIds[1], feedback_type: 'reaction', guest_identifier: 'dup-guest' });
+    expect(rows).toHaveLength(1);
+    expect(rows[0].reaction).toBe('🎉');
+
+    // …and toggle-off removes the full guest-scoped set.
+    await db('photo_feedback').insert(mk('🎉'));
+    const removed = await react(photoIds[1], '🎉', { guestIdentifier: 'dup-guest' });
+    expect(removed.removed).toBe(true);
+    rows = await db('photo_feedback')
+      .where({ photo_id: photoIds[1], feedback_type: 'reaction', guest_identifier: 'dup-guest' });
+    expect(rows).toHaveLength(0);
+  });
+
+  it('summary and exports carry reactions', async () => {
+    const summary = await feedbackService.getEventFeedbackSummary(eventId);
+    expect(Number(summary.stats.total_reactions)).toBeGreaterThan(0);
+
+    const longRows = await feedbackService.exportEventFeedback(eventId);
+    const longReaction = longRows.find((r) => r.feedback_type === 'reaction');
+    expect(longReaction.reaction).toBeTruthy();
+
+    const pivotRows = await feedbackService.exportEventFeedbackPivoted(eventId);
+    const pivotWithReaction = pivotRows.find((r) => r.reaction);
+    expect(REACTION_EMOJIS).toContain(pivotWithReaction.reaction);
+  });
+});

backend/__tests__/utils/galleryInfoBanner.test.js

@@ -0,0 +1,177 @@
+/**
+ * Gallery info banner (#932).
+ *
+ * A short note rendered ABOVE the photo grid — the reporter's case is an
+ * onboarding hint ("use the menu button to filter"), which is useless in the
+ * promo slot down by the footer because the guest has to scroll the whole
+ * gallery to reach it.
+ *
+ * Covers what the migration actually produces on a real engine (the harness
+ * runs SQLite) and the inherit/custom/off resolution the gallery render
+ * depends on. The resolution is duplicated here rather than imported because
+ * it lives in the React layer; the point is to pin the CONTRACT — which
+ * source wins for each mode — so a change on either side has to update this
+ * file deliberately.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+process.env.TEST_DATABASE_PATH = path.join(
+  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-info-banner-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'info-banner-test-secret';
+
+const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
+
+let db;
+let cleanup;
+
+beforeAll(async () => {
+  ({ db, cleanup } = await bootCrmDb());
+  await seedMinimal(db);
+});
+
+afterAll(async () => {
+  if (cleanup) await cleanup();
+});
+
+describe('migration 176 — schema', () => {
+  it('adds events.info_mode defaulting to inherit', async () => {
+    expect(await db.schema.hasColumn('events', 'info_mode')).toBe(true);
+
+    const [id] = await db('events').insert({
+      slug: 'info-default-test',
+      event_type: 'wedding',
+      event_name: 'Info Default Test',
+      event_date: '2026-06-22',
+      host_email: 'host@example.com',
+      admin_email: 'admin@example.com',
+      password_hash: 'x',
+      share_link: '/gallery/info-default-test/share',
+      share_token: 'info-default-test-share',
+      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+      is_active: 1,
+      is_archived: 0,
+      is_draft: 0,
+      created_at: new Date().toISOString(),
+    }).returning('id');
+    const eventId = id?.id ?? id;
+
+    const row = await db('events').where({ id: eventId }).first();
+    // A gallery created before anyone configures the feature must inherit,
+    // so switching the global default on lights up every existing gallery.
+    expect(row.info_mode).toBe('inherit');
+    expect(row.info_markdown ?? null).toBeNull();
+  });
+
+  it('adds events.info_markdown as nullable text', async () => {
+    expect(await db.schema.hasColumn('events', 'info_markdown')).toBe(true);
+  });
+
+  it('seeds branding_info_markdown empty, so upgrading shows no banner', async () => {
+    const row = await db('app_settings').where({ setting_key: 'branding_info_markdown' }).first();
+    expect(row).toBeTruthy();
+    expect(JSON.parse(row.setting_value)).toBe('');
+    expect(row.setting_type).toBe('branding');
+  });
+});
+
+// Mirrors GalleryLayout's resolution.
+function resolveInfoBanner(event, brandingDefault) {
+  const mode = event.info_mode || 'inherit';
+  if (mode === 'off') return '';
+  if (mode === 'custom') {
+    const own = (event.info_markdown || '').trim();
+    return (own || brandingDefault || '').trim();
+  }
+  return (brandingDefault || '').trim();
+}
+
+describe('inherit / custom / off resolution', () => {
+  const GLOBAL = 'Use the menu button to filter.';
+
+  it('inherit renders the global default', () => {
+    expect(resolveInfoBanner({ info_mode: 'inherit' }, GLOBAL)).toBe(GLOBAL);
+  });
+
+  it('a missing mode is treated as inherit (rows predating the migration)', () => {
+    expect(resolveInfoBanner({}, GLOBAL)).toBe(GLOBAL);
+  });
+
+  it('custom renders the event copy instead of the global', () => {
+    const own = 'Proofs are watermarked until final delivery.';
+    expect(resolveInfoBanner({ info_mode: 'custom', info_markdown: own }, GLOBAL)).toBe(own);
+  });
+
+  it('custom with blank copy falls back to the global rather than showing nothing', () => {
+    expect(resolveInfoBanner({ info_mode: 'custom', info_markdown: '   ' }, GLOBAL)).toBe(GLOBAL);
+  });
+
+  it('off suppresses the banner even when a global default exists', () => {
+    expect(resolveInfoBanner({ info_mode: 'off' }, GLOBAL)).toBe('');
+  });
+
+  it('off wins over the event own copy too', () => {
+    expect(resolveInfoBanner({ info_mode: 'off', info_markdown: 'ignored' }, GLOBAL)).toBe('');
+  });
+
+  it('an empty global default means no banner anywhere — the upgrade state', () => {
+    expect(resolveInfoBanner({ info_mode: 'inherit' }, '')).toBe('');
+    expect(resolveInfoBanner({}, undefined)).toBe('');
+  });
+});
+
+describe('per-event persistence', () => {
+  let eventId;
+
+  beforeAll(async () => {
+    const [id] = await db('events').insert({
+      slug: 'info-persist-test',
+      event_type: 'wedding',
+      event_name: 'Info Persist Test',
+      event_date: '2026-06-22',
+      host_email: 'host@example.com',
+      admin_email: 'admin@example.com',
+      password_hash: 'x',
+      share_link: '/gallery/info-persist-test/share',
+      share_token: 'info-persist-test-share',
+      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
+      is_active: 1,
+      is_archived: 0,
+      is_draft: 0,
+      created_at: new Date().toISOString(),
+    }).returning('id');
+    eventId = id?.id ?? id;
+  });
+
+  it('stores a custom override', async () => {
+    await db('events').where({ id: eventId })
+      .update({ info_mode: 'custom', info_markdown: '**Heads up** — proofs only.' });
+
+    const row = await db('events').where({ id: eventId }).first();
+    expect(row.info_mode).toBe('custom');
+    expect(row.info_markdown).toBe('**Heads up** — proofs only.');
+  });
+
+  it('switching away from custom clears the stored copy', async () => {
+    // Matches the route's normalisation: mode != custom nulls the text so a
+    // later switch back to custom can't resurrect stale copy.
+    await db('events').where({ id: eventId })
+      .update({ info_mode: 'off', info_markdown: null });
+
+    const row = await db('events').where({ id: eventId }).first();
+    expect(row.info_mode).toBe('off');
+    expect(row.info_markdown).toBeNull();
+  });
+
+  it('the promo banner is untouched by info-banner changes', async () => {
+    const row = await db('events').where({ id: eventId }).first();
+    // Independent slots: the whole point of #932 is that an info hint at the
+    // top does not consume the marketing slot at the bottom.
+    expect(row.promo_mode).toBe('inherit');
+    expect(row.promo_markdown ?? null).toBeNull();
+  });
+});

backend/__tests__/utils/sessionCutoff.test.js

@@ -0,0 +1,56 @@
+/**
+ * Unit tests for the global session cutoff (utils/sessionCutoff.js). Uses a
+ * real in-memory SQLite `app_settings` table so the read/write/parse path is
+ * exercised exactly as in production.
+ */
+const knex = require('knex');
+
+let db;
+let cutoff;
+
+beforeEach(async () => {
+  db = knex({ client: 'sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true });
+  await db.schema.createTable('app_settings', (t) => {
+    t.increments('id');
+    t.string('setting_key').notNullable().unique();
+    t.text('setting_value');
+    t.string('setting_type');
+    t.timestamp('updated_at');
+  });
+  jest.resetModules();
+  jest.doMock('../../src/database/db', () => ({ db }));
+  cutoff = require('../../src/utils/sessionCutoff');
+  cutoff._resetCache();
+});
+
+afterEach(async () => {
+  jest.dontMock('../../src/database/db');
+  await db.destroy();
+});
+
+test('no cutoff set → nothing is invalidated', async () => {
+  expect(await cutoff.getSessionsValidAfter()).toBe(0);
+  expect(await cutoff.isTokenBeforeCutoff({ iat: 1000 })).toBe(false);
+});
+
+test('token issued before the cutoff is rejected, at/after is accepted', async () => {
+  await cutoff.setSessionsValidAfter(2000);
+  expect(await cutoff.isTokenBeforeCutoff({ iat: 1999 })).toBe(true);   // pre-restore session
+  expect(await cutoff.isTokenBeforeCutoff({ iat: 2000 })).toBe(false);  // same second → kept
+  expect(await cutoff.isTokenBeforeCutoff({ iat: 2001 })).toBe(false);  // post-restore login
+});
+
+test('setSessionsValidAfter upserts a single row and refreshes the cache', async () => {
+  await cutoff.setSessionsValidAfter(1000);
+  await cutoff.setSessionsValidAfter(3000);
+  const rows = await db('app_settings').where('setting_key', 'security_sessions_valid_after');
+  expect(rows).toHaveLength(1);
+  cutoff._resetCache();
+  expect(await cutoff.getSessionsValidAfter()).toBe(3000);
+});
+
+test('a token without iat is never treated as before the cutoff', async () => {
+  await cutoff.setSessionsValidAfter(2000);
+  expect(await cutoff.isTokenBeforeCutoff({})).toBe(false);
+  expect(await cutoff.isTokenBeforeCutoff(null)).toBe(false);
+});

backend/__tests__/utils/streamResponse.test.js

@@ -1,160 +0,0 @@
-/**
- * The contract that matters here is negative: a source that disappears must
- * NOT be able to end the process (#1128).
- *
- * `fs.createReadStream` is lazy, so its ENOENT lands on a later tick, outside
- * the route's try/catch. An EventEmitter emitting 'error' with no listener
- * throws, and an uncaught throw from an I/O callback exits Node — which is how
- * one missing thumbnail tier took every gallery on the install down.
- *
- * These use a REAL fs stream over a real missing path rather than a fake
- * emitter: the point under test is the lazy-open timing, and a hand-rolled
- * mock that emits synchronously would pass while proving nothing.
- */
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { Readable } = require('stream');
-const { EventEmitter } = require('events');
-
-const { pipeStreamToResponse } = require('../../src/utils/streamResponse');
-
-jest.mock('../../src/utils/logger', () => ({
-  warn: jest.fn(), error: jest.fn(), info: jest.fn(), debug: jest.fn(),
-}));
-
-/** Minimal Express-ish response that records what happened to it. */
-function makeRes() {
-  const res = new EventEmitter();
-  res.headers = { 'Content-Length': '1234', ETag: '"x"' };
-  res.statusCode = 200;
-  res.headersSent = false;
-  res.writableEnded = false;
-  res.body = null;
-  res.destroyed = false;
-  res.removeHeader = (h) => { delete res.headers[h]; };
-  res.setHeader = (h, v) => { res.headers[h] = v; };
-  res.status = (code) => { res.statusCode = code; return res; };
-  res.json = (payload) => { res.body = payload; res.writableEnded = true; return res; };
-  res.destroy = () => { res.destroyed = true; };
-  // pipe() target surface
-  res.write = () => true;
-  res.end = () => { res.writableEnded = true; };
-  res.on = EventEmitter.prototype.on.bind(res);
-  res.emit = EventEmitter.prototype.emit.bind(res);
-  return res;
-}
-
-const settle = () => new Promise((resolve) => setTimeout(resolve, 50));
-
-describe('pipeStreamToResponse (#1128)', () => {
-  it('turns a missing file into a 404 instead of an unhandled error', async () => {
-    const missing = path.join(os.tmpdir(), `picpeak-not-here-${Date.now()}.jpg`);
-    const res = makeRes();
-
-    pipeStreamToResponse(stream_(missing), res, { context: 'thumbnail for photo 1' });
-    await settle();
-
-    expect(res.statusCode).toBe(404);
-    expect(res.body).toEqual({ error: 'File not found' });
-  });
-
-  // How this test discriminates, since the failure mode is a process-level
-  // one: replacing the call above with a bare `stream.pipe(res)` — what the
-  // thumbnail route did — makes jest fail this suite on the unhandled 'error'
-  // event before either assertion runs. Verified by doing exactly that.
-  // Catching the throw with a process.on('uncaughtException') listener does
-  // NOT work here and would be theatre: the runner installs its own handling,
-  // so such a listener never sees it and the assertion could never fail.
-  function stream_(p) { return fs.createReadStream(p); }
-
-  it('strips every header that described the file it can no longer send', async () => {
-    const res = makeRes();
-    // What the image and zip routes actually stage before streaming.
-    res.headers = {
-      'Content-Length': '1234',
-      ETag: '"x"',
-      'Content-Type': 'image/jpeg',
-      'Content-Disposition': 'attachment; filename="gallery.zip"',
-      'Cache-Control': 'private, max-age=1800',
-    };
-    const stream = fs.createReadStream(path.join(os.tmpdir(), `gone-${Date.now()}.jpg`));
-
-    pipeStreamToResponse(stream, res);
-    await settle();
-
-    expect(res.headers['Content-Length']).toBeUndefined();
-    expect(res.headers.ETag).toBeUndefined();
-    // Express does NOT overwrite an existing Content-Type, so leaving it makes
-    // res.json() emit JSON labelled image/jpeg — or a corrupt .zip download.
-    expect(res.headers['Content-Type']).toBeUndefined();
-    expect(res.headers['Content-Disposition']).toBeUndefined();
-  });
-
-  it('does not let a transient 404 be cached as a broken tile', async () => {
-    const res = makeRes();
-    // The thumbnail route stages 30 minutes; the hero route an hour.
-    res.headers = { 'Cache-Control': 'private, max-age=1800' };
-    const stream = fs.createReadStream(path.join(os.tmpdir(), `gone3-${Date.now()}.jpg`));
-
-    pipeStreamToResponse(stream, res);
-    await settle();
-
-    // The regeneration race is transient by definition: the tier exists moments
-    // later. Caching this 404 would keep the tile broken long after the file is
-    // back — the opposite of what this helper is for.
-    expect(res.headers['Cache-Control']).toBe('no-store');
-  });
-
-  it('honours a caller that wants a different missing-status', async () => {
-    const res = makeRes();
-    const stream = fs.createReadStream(path.join(os.tmpdir(), `gone2-${Date.now()}.zip`));
-
-    pipeStreamToResponse(stream, res, { missingStatus: 410 });
-    await settle();
-
-    expect(res.statusCode).toBe(410);
-  });
-
-  it('destroys the response instead of rewriting a status that is already sent', async () => {
-    const res = makeRes();
-    res.headersSent = true;
-
-    const stream = new Readable({ read() {} });
-    pipeStreamToResponse(stream, res, { context: 'photo 9' });
-    stream.emit('error', Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
-    await settle();
-
-    // Once bytes are on the wire a 404 is not available; a truncated image the
-    // client would cache is worse than a broken connection.
-    expect(res.destroyed).toBe(true);
-    expect(res.statusCode).toBe(200);
-    expect(res.body).toBeNull();
-  });
-
-  it('reports a non-ENOENT failure as a 500 rather than a 404', async () => {
-    const res = makeRes();
-    const stream = new Readable({ read() {} });
-
-    pipeStreamToResponse(stream, res);
-    stream.emit('error', Object.assign(new Error('disk exploded'), { code: 'EIO' }));
-    await settle();
-
-    expect(res.statusCode).toBe(500);
-    expect(res.body).toEqual({ error: 'Failed to serve file' });
-  });
-
-  it('releases the source when the client hangs up mid-download', async () => {
-    const res = makeRes();
-    let destroyed = false;
-    const stream = new Readable({ read() {}, destroy(err, cb) { destroyed = true; cb(err); } });
-
-    pipeStreamToResponse(stream, res);
-    res.emit('close');
-    await settle();
-
-    // Otherwise an abandoned grid leaks one open fd per tile.
-    expect(destroyed).toBe(true);
-  });
-});

backend/assets/fonts/IBM-Plex-Sans-Full/OFL-LICENSE.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

backend/jest.config.js

@@ -1,8 +1,9 @@
 module.exports = {
   testEnvironment: 'node',
-  // bootCrmDb() runs EVERY core migration in beforeAll and the chain keeps
-  // growing (134 migrations and counting via backports). 120s matches the
-  // beta-branch convention from #860.
+  // bootCrmDb() runs EVERY core migration in beforeAll; the chain keeps
+  // growing (163-165 pushed several suites past jest's default on CI
+  // runners — the 3.94 release PR failed on exactly this). 120s matches
+  // the convention the newer suites already pin explicitly.
   testTimeout: 120000,
   coverageDirectory: 'coverage',
   collectCoverageFrom: [

backend/migrations/core/052_add_css_templates.js

@@ -77,11 +77,7 @@ const DEFAULT_CSS_TEMPLATE = `/*
 
 .photo-card img {
   width: 100%;
-  /* 100%, not a fixed pixel height: every aspect-ratio layout (masonry,
-     justified, mosaic, gallery-premium) gives .photo-card a definite height
-     computed from photos.width/height, and this rule's specificity (0,1,1)
-     beats the .h-full utility (0,1,0) the layouts rely on — #1131. */
-  height: 100%;
+  height: 200px;
   object-fit: cover;
   transition: transform 0.3s ease;
 }

backend/migrations/core/053_add_liquid_glass_templates.js

@@ -503,9 +503,7 @@ const LIQUID_GLASS_DARK = `/*
 
 .photo-card img {
   width: 100%;
-  /* See #1131: a fixed height here beats the layouts' .h-full utility and
-     detaches the image from its aspect-ratio-sized card. */
-  height: 100%;
+  height: 240px;
   object-fit: cover;
   transition: transform 0.4s ease, filter 0.4s ease;
   filter: brightness(0.9);
@@ -641,7 +639,7 @@ const LIQUID_GLASS_DARK = `/*
   }
 
   .photo-card img {
-    height: 100%;
+    height: 180px;
   }
 
   /* Reduce animation complexity on mobile */

backend/migrations/core/158_slideshow_order_category.js

@@ -0,0 +1,37 @@
+/**
+ * Migration 158: per-event slideshow ordering + category filter (#202).
+ *
+ * - `show_order`      — 'chronological' (default, upload order) | 'random'
+ *                       (client-side shuffle). Lets the Live Slideshow play
+ *                       photos in a varied order during an event.
+ * - `show_category_id`— optional FK into `photo_categories`. When set, the
+ *                       slideshow only shows photos in that category (NULL =
+ *                       all visible photos, the existing behaviour).
+ *
+ * Both additive + guarded. Defaults preserve today's behaviour (chronological,
+ * all photos), so existing slideshows are unchanged.
+ */
+exports.up = async function up(knex) {
+  const hasOrder = await knex.schema.hasColumn('events', 'show_order');
+  if (!hasOrder) {
+    await knex.schema.alterTable('events', (t) => {
+      t.string('show_order', 20).defaultTo('chronological');
+    });
+  }
+  const hasCat = await knex.schema.hasColumn('events', 'show_category_id');
+  if (!hasCat) {
+    await knex.schema.alterTable('events', (t) => {
+      t.integer('show_category_id').nullable();
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  for (const col of ['show_order', 'show_category_id']) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await knex.schema.hasColumn('events', col)) {
+      // eslint-disable-next-line no-await-in-loop
+      await knex.schema.alterTable('events', (t) => t.dropColumn(col));
+    }
+  }
+};

backend/migrations/core/159_add_category_display_order.js

@@ -0,0 +1,57 @@
+/**
+ * Migration 159: per-event category ordering (#782).
+ *
+ * Adds a `display_order` integer to `photo_categories` so photographers can
+ * arrange an event's categories in the flow of the day (Pre-Ceremony →
+ * Ceremony → Reception …) instead of the hard-coded A–Z order. Mirrors the
+ * `display_order` column + reorder pattern already used by `event_types`.
+ *
+ * Preserve existing galleries: backfill `display_order` from the CURRENT
+ * (alphabetical) order, scoped — globals numbered together, event-specific
+ * numbered per event — so nothing reshuffles on upgrade. A custom order is
+ * opt-in via the admin reorder controls. See feedback: migrations should pin
+ * previously-implicit defaults onto existing rows.
+ *
+ * Backfill runs in JS (not a SQL window function) to stay portable across
+ * SQLite (dev) and Postgres (prod).
+ *
+ * Additive + hasColumn-guarded.
+ */
+async function addColumn(knex, table, column, builder) {
+  if (!(await knex.schema.hasColumn(table, column))) {
+    await knex.schema.alterTable(table, builder);
+  }
+}
+
+exports.up = async function (knex) {
+  if (!(await knex.schema.hasTable('photo_categories'))) return;
+
+  await addColumn(knex, 'photo_categories', 'display_order', (t) => {
+    t.integer('display_order').notNullable().defaultTo(0);
+    t.index('display_order');
+  });
+
+  // Backfill from the current alphabetical order, per scope, so existing
+  // galleries render exactly as before until an admin reorders.
+  const cats = await knex('photo_categories')
+    .select('id', 'name', 'is_global', 'event_id')
+    .orderBy('name', 'asc');
+
+  const counters = {};
+  for (const c of cats) {
+    const scope = c.is_global ? 'global' : `event:${c.event_id}`;
+    counters[scope] = (counters[scope] || 0) + 1;
+    await knex('photo_categories')
+      .where('id', c.id)
+      .update({ display_order: counters[scope] });
+  }
+};
+
+exports.down = async function (knex) {
+  if (!(await knex.schema.hasTable('photo_categories'))) return;
+  if (await knex.schema.hasColumn('photo_categories', 'display_order')) {
+    await knex.schema.alterTable('photo_categories', (t) =>
+      t.dropColumn('display_order')
+    );
+  }
+};

backend/migrations/core/160_add_event_category_order.js

@@ -0,0 +1,46 @@
+/**
+ * Migration 160: per-event category order override (#782).
+ *
+ * Builds on migration 159 (photo_categories.display_order = the GLOBAL default
+ * order) by adding a per-event OVERRIDE layer. Global categories are shared
+ * across every event, so a single display_order can only express one order for
+ * them. This table lets a single gallery arrange its categories — globals AND
+ * event-specific, interleaved into the flow of the day — independently of the
+ * global default.
+ *
+ * Resolution (see adminCategories / gallery):
+ *   1. if the event has override rows -> use override.position;
+ *   2. else fall back to photo_categories.display_order (the global default);
+ *   3. else name.
+ *
+ * An event is either "using the default" (no rows here) or "customised" (a row
+ * per category it shows). No backfill: every existing event starts on the
+ * default order, so nothing reshuffles — a custom order is opt-in per event.
+ *
+ * Additive + hasTable-guarded.
+ */
+exports.up = async function (knex) {
+  if (!(await knex.schema.hasTable('photo_categories'))) return;
+  if (await knex.schema.hasTable('event_category_order')) return;
+
+  await knex.schema.createTable('event_category_order', (t) => {
+    t.increments('id').primary();
+    t.integer('event_id').notNullable()
+      .references('id').inTable('events').onDelete('CASCADE');
+    t.integer('category_id').notNullable()
+      .references('id').inTable('photo_categories').onDelete('CASCADE');
+    t.integer('position').notNullable().defaultTo(0);
+    t.timestamp('created_at').defaultTo(knex.fn.now());
+
+    // At most one position per (event, category).
+    t.unique(['event_id', 'category_id']);
+    // Ordered reads are always scoped to one event.
+    t.index(['event_id', 'position']);
+  });
+};
+
+exports.down = async function (knex) {
+  if (await knex.schema.hasTable('event_category_order')) {
+    await knex.schema.dropTable('event_category_order');
+  }
+};

backend/migrations/core/161_setup_wizard_completed_flag.js

@@ -0,0 +1,43 @@
+/**
+ * Migration 161: `setup_wizard_completed` app setting (#800).
+ *
+ * The setup wizard gains an event-types step that may rename or DELETE the
+ * seeded system event types. That is only safe on a pristine install, so the
+ * backend gates system-type deletion on this flag being unset (plus zero
+ * usage — see eventTypeService.deleteEventType).
+ *
+ * Backfill rule: any install that already has an admin account predates the
+ * wizard step (or already finished the wizard), so it is marked completed
+ * here — the deletion window never opens on existing setups. A genuinely
+ * fresh install runs this migration BEFORE its first admin is created, so
+ * the flag starts false and the wizard's finish call flips it to true.
+ *
+ * Idempotent: skips when the key already exists. Values are JSON-stringified
+ * to match getAppSetting's JSON.parse on read.
+ */
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable('app_settings'))) return;
+
+  const existing = await knex('app_settings')
+    .where({ setting_key: 'setup_wizard_completed' })
+    .first();
+  if (existing) return;
+
+  let hasAdmin = false;
+  if (await knex.schema.hasTable('admin_users')) {
+    const row = await knex('admin_users').count({ c: '*' }).first();
+    hasAdmin = Number(row?.c || 0) > 0;
+  }
+
+  await knex('app_settings').insert({
+    setting_key: 'setup_wizard_completed',
+    setting_value: JSON.stringify(hasAdmin),
+    setting_type: 'boolean',
+    updated_at: new Date(),
+  });
+};
+
+exports.down = async function down(knex) {
+  if (!(await knex.schema.hasTable('app_settings'))) return;
+  await knex('app_settings').where({ setting_key: 'setup_wizard_completed' }).del();
+};

backend/migrations/core/162_admin_oidc_identity.js

@@ -0,0 +1,51 @@
+/**
+ * Migration 162: OIDC identity binding for admin users (#798).
+ *
+ * - `auth_provider`    — 'local' (default) or 'oidc'. Which authority owns the
+ *                        account's credentials.
+ * - `external_issuer`  — the validated `iss` of the IdP that owns the subject.
+ *                        OIDC only guarantees `sub` uniqueness WITHIN an
+ *                        issuer, so bindings match on (iss, sub) — otherwise
+ *                        switching `oidc_issuer_url` could map a new
+ *                        provider's user onto an old provider's admin when
+ *                        their subjects collide.
+ * - `external_subject` — the IdP's stable subject identifier (OIDC `sub`).
+ *                        SSO logins match on (external_issuer,
+ *                        external_subject), NEVER on email alone —
+ *                        email-matching is an account-takeover vector with
+ *                        IdPs that don't verify addresses. Nullable: local
+ *                        accounts have neither.
+ *
+ * Composite unique index so one IdP identity can't map to two admin rows.
+ * Additive + guarded; existing rows keep working untouched ('local', NULL).
+ */
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasColumn('admin_users', 'auth_provider'))) {
+    await knex.schema.alterTable('admin_users', (t) => {
+      t.string('auth_provider', 20).notNullable().defaultTo('local');
+    });
+  }
+  if (!(await knex.schema.hasColumn('admin_users', 'external_issuer'))) {
+    await knex.schema.alterTable('admin_users', (t) => {
+      t.string('external_issuer', 512).nullable();
+    });
+  }
+  if (!(await knex.schema.hasColumn('admin_users', 'external_subject'))) {
+    await knex.schema.alterTable('admin_users', (t) => {
+      t.string('external_subject', 255).nullable();
+      t.unique(['external_issuer', 'external_subject'], {
+        indexName: 'admin_users_issuer_subject_unique',
+      });
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  for (const col of ['external_subject', 'external_issuer', 'auth_provider']) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await knex.schema.hasColumn('admin_users', col)) {
+      // eslint-disable-next-line no-await-in-loop
+      await knex.schema.alterTable('admin_users', (t) => t.dropColumn(col));
+    }
+  }
+};

backend/migrations/core/163_add_event_show_qr.js

@@ -0,0 +1,22 @@
+/**
+ * #837 — per-event override for the live-slideshow QR overlay.
+ * Mirrors show_watermark: NULL = inherit the global slideshow_qr_enabled
+ * setting, true/false force the overlay on/off for this event.
+ */
+exports.up = async function up(knex) {
+  const has = await knex.schema.hasColumn('events', 'show_qr');
+  if (!has) {
+    await knex.schema.alterTable('events', (t) => {
+      t.boolean('show_qr').nullable().defaultTo(null);
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  const has = await knex.schema.hasColumn('events', 'show_qr');
+  if (has) {
+    await knex.schema.alterTable('events', (t) => {
+      t.dropColumn('show_qr');
+    });
+  }
+};

backend/migrations/core/164_add_emoji_reactions.js

@@ -0,0 +1,55 @@
+/**
+ * Emoji reactions on photos (#839).
+ *
+ * - event_feedback_settings.allow_reactions: per-event toggle next to
+ *   allow_likes / allow_ratings / allow_comments. Defaults TRUE for parity
+ *   with the sibling toggles — the master feedback_enabled gate (default
+ *   false, opt-in per event) still decides whether any feedback UI shows.
+ * - photo_feedback.reaction: the emoji value for feedback_type='reaction'
+ *   rows (validated against the fixed set in constants/reactions.js).
+ * - photos.reaction_count: denormalized total, maintained by
+ *   updatePhotoFeedbackStats alongside like_count / favorite_count.
+ */
+
+exports.up = async function (knex) {
+  const hasAllowReactions = await knex.schema.hasColumn('event_feedback_settings', 'allow_reactions');
+  if (!hasAllowReactions) {
+    await knex.schema.alterTable('event_feedback_settings', (table) => {
+      table.boolean('allow_reactions').defaultTo(true);
+    });
+  }
+
+  const hasReaction = await knex.schema.hasColumn('photo_feedback', 'reaction');
+  if (!hasReaction) {
+    await knex.schema.alterTable('photo_feedback', (table) => {
+      // 16 chars: emoji are multi-byte/multi-codepoint (variation selectors),
+      // but well under 16 characters each.
+      table.string('reaction', 16);
+    });
+  }
+
+  const hasReactionCount = await knex.schema.hasColumn('photos', 'reaction_count');
+  if (!hasReactionCount) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.integer('reaction_count').defaultTo(0);
+    });
+  }
+};
+
+exports.down = async function (knex) {
+  if (await knex.schema.hasColumn('photos', 'reaction_count')) {
+    await knex.schema.alterTable('photos', (table) => {
+      table.dropColumn('reaction_count');
+    });
+  }
+  if (await knex.schema.hasColumn('photo_feedback', 'reaction')) {
+    await knex.schema.alterTable('photo_feedback', (table) => {
+      table.dropColumn('reaction');
+    });
+  }
+  if (await knex.schema.hasColumn('event_feedback_settings', 'allow_reactions')) {
+    await knex.schema.alterTable('event_feedback_settings', (table) => {
+      table.dropColumn('allow_reactions');
+    });
+  }
+};

backend/migrations/core/165_add_reveal_mode.js

@@ -0,0 +1,44 @@
+/**
+ * Reveal mode (#838): hide the gallery from guests until a manual or
+ * scheduled reveal — guests can still upload, the host/admin/slideshow see
+ * everything.
+ *
+ * - events.reveal_mode: the per-event toggle (only meaningful together with
+ *   allow_user_uploads; off by default so nothing changes for existing events)
+ * - events.reveal_at: optional scheduled reveal time. Effective visibility is
+ *   computed at REQUEST time (reveal_at <= now opens the gate even before the
+ *   scheduler runs), the minutely scheduler only stamps revealed_at durably.
+ * - events.revealed_at: set by "Reveal now" or the scheduler; NULL while
+ *   hidden. Re-enabling reveal_mode clears it (re-hide).
+ */
+
+// Each column guarded independently: a partially applied prior run (or a
+// fork that added one of them) must not leave the others missing — the
+// routes select all three.
+exports.up = async function (knex) {
+  if (!(await knex.schema.hasColumn('events', 'reveal_mode'))) {
+    await knex.schema.alterTable('events', (table) => {
+      table.boolean('reveal_mode').defaultTo(false);
+    });
+  }
+  if (!(await knex.schema.hasColumn('events', 'reveal_at'))) {
+    await knex.schema.alterTable('events', (table) => {
+      table.timestamp('reveal_at').nullable();
+    });
+  }
+  if (!(await knex.schema.hasColumn('events', 'revealed_at'))) {
+    await knex.schema.alterTable('events', (table) => {
+      table.timestamp('revealed_at').nullable();
+    });
+  }
+};
+
+exports.down = async function (knex) {
+  for (const column of ['revealed_at', 'reveal_at', 'reveal_mode']) {
+    if (await knex.schema.hasColumn('events', column)) {
+      await knex.schema.alterTable('events', (table) => {
+        table.dropColumn(column);
+      });
+    }
+  }
+};

backend/migrations/core/166_add_login_logo_visible.js

@@ -0,0 +1,21 @@
+/**
+ * Migration 166: per-event toggle to hide the branding logo on the
+ * gallery password page (#894).
+ *
+ * NULL (the default) keeps today's behaviour — the global branding logo is
+ * shown above the password form. Only an explicit `false` hides it for
+ * that gallery; the admin login page and other surfaces are unaffected.
+ */
+exports.up = async function (knex) {
+  if (await knex.schema.hasColumn('events', 'login_logo_visible')) return;
+  await knex.schema.alterTable('events', (t) => {
+    t.boolean('login_logo_visible').nullable();
+  });
+};
+
+exports.down = async function (knex) {
+  if (!(await knex.schema.hasColumn('events', 'login_logo_visible'))) return;
+  await knex.schema.alterTable('events', (t) => {
+    t.dropColumn('login_logo_visible');
+  });
+};

backend/migrations/core/169_add_rebill_proof_attach.js

@@ -0,0 +1,50 @@
+/**
+ * Migration 169: re-bill proof-attachment support (issue #866).
+ *
+ *   - inbound_documents.proof_attach_error : best-effort failure marker. When a
+ *                                            re-billed supplier invoice's stored
+ *                                            proof PDF is missing/unreadable at
+ *                                            the moment the client invoice is
+ *                                            issued, we DON'T silently drop it —
+ *                                            we stamp the reason here so the
+ *                                            re-bill row in CRM → Customer shows
+ *                                            a recovery banner.
+ *   - customer_accounts.rebill_attach_proof: per-customer tri-state override for
+ *                                            "attach the supplier proof to the
+ *                                            client-invoice email".
+ *                                              NULL  = inherit the global default
+ *                                              true  = always attach
+ *                                              false = never attach
+ *                                            The global default itself lives in
+ *                                            app_settings (accounting_rebill_
+ *                                            attach_proof, default off) and needs
+ *                                            no seed row — an absent key coerces
+ *                                            to false, exactly like
+ *                                            accounting_require_proof.
+ *
+ * Additive + hasColumn-guarded so re-runs are safe.
+ */
+async function addColumn(knex, table, column, builder) {
+  if (!(await knex.schema.hasColumn(table, column))) {
+    await knex.schema.alterTable(table, builder);
+  }
+}
+
+exports.up = async function (knex) {
+  if (await knex.schema.hasTable('inbound_documents')) {
+    await addColumn(knex, 'inbound_documents', 'proof_attach_error', (t) => t.text('proof_attach_error'));
+  }
+  if (await knex.schema.hasTable('customer_accounts')) {
+    // Nullable boolean = tri-state (NULL inherit / true on / false off).
+    await addColumn(knex, 'customer_accounts', 'rebill_attach_proof', (t) => t.boolean('rebill_attach_proof').nullable());
+  }
+};
+
+exports.down = async function (knex) {
+  if (await knex.schema.hasTable('inbound_documents') && await knex.schema.hasColumn('inbound_documents', 'proof_attach_error')) {
+    await knex.schema.alterTable('inbound_documents', (t) => t.dropColumn('proof_attach_error'));
+  }
+  if (await knex.schema.hasTable('customer_accounts') && await knex.schema.hasColumn('customer_accounts', 'rebill_attach_proof')) {
+    await knex.schema.alterTable('customer_accounts', (t) => t.dropColumn('rebill_attach_proof'));
+  }
+};

backend/migrations/core/170_add_transfers.js

@@ -0,0 +1,244 @@
+/**
+ * Migration 170: PicTransfer — cross-event file transfers (#997).
+ *
+ * Adds the tables that back the "send these files to someone" feature:
+ *
+ *   transfers          One share link. Bundles photos picked from ANY event,
+ *                      protected by a 64-hex recipient token. Optionally opens
+ *                      a 6-char upload token so the client can send files back
+ *                      (logos etc.). Disabled after `expires_at`; files are
+ *                      kept `grace_days` days past disable, then hard-deleted.
+ *   transfer_files     Join rows: which photos are in a transfer (cross-event).
+ *                      photo_id → photos CASCADE, so removing the underlying
+ *                      photo just drops it from the transfer; the reverse
+ *                      (deleting a transfer) never touches the source photos.
+ *   transfer_uploads   Files the client uploaded through the upload token.
+ *                      These have their own bytes on disk (uploads/transfers/…)
+ *                      and are what the retention sweep deletes.
+ *   transfer_downloads Lightweight audit of recipient downloads (count + IP).
+ *
+ * Downloads always serve ORIGINAL files (never watermarked) — a transfer is a
+ * deliberate "here are your files" hand-off. Reuses the same original-file
+ * resolution + archiver streaming as the gallery download-all path.
+ */
+
+exports.up = async function (knex) {
+  if (!(await knex.schema.hasTable('transfers'))) {
+    await knex.schema.createTable('transfers', (table) => {
+      table.increments('id').primary();
+      // Recipient download token — 64 hex chars = 32 bytes = 256 bits.
+      table.string('token', 64).notNullable().unique();
+      table.string('title', 255).notNullable().defaultTo('');
+      table.text('message');
+      table.integer('created_by').unsigned()
+        .references('id').inTable('admin_users').onDelete('SET NULL');
+      // Link is disabled once this passes (the "set time period" cap).
+      table.timestamp('expires_at').notNullable();
+      // Optional download cap. NULL or 0 = unlimited within the window.
+      table.integer('max_downloads');
+      table.integer('download_count').notNullable().defaultTo(0);
+      table.boolean('is_active').notNullable().defaultTo(true);
+      // When the link flipped inactive — starts the retention clock.
+      table.timestamp('disabled_at');
+      // Keep files this many days after disable, then hard-delete.
+      table.integer('grace_days').notNullable().defaultTo(7);
+      table.timestamp('admin_notified_at');
+      table.timestamp('deleted_at');
+      // Optional client-upload channel (6-char token).
+      table.boolean('allow_uploads').notNullable().defaultTo(false);
+      table.string('upload_token', 16).unique();
+      table.timestamp('upload_expires_at');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+      table.index(['is_active', 'expires_at'], 'transfers_active_expiry_idx');
+      table.index(['deleted_at'], 'transfers_deleted_idx');
+    });
+  }
+
+  if (!(await knex.schema.hasTable('transfer_files'))) {
+    await knex.schema.createTable('transfer_files', (table) => {
+      table.increments('id').primary();
+      table.integer('transfer_id').unsigned().notNullable()
+        .references('id').inTable('transfers').onDelete('CASCADE');
+      table.integer('photo_id').unsigned().notNullable()
+        .references('id').inTable('photos').onDelete('CASCADE');
+      table.integer('sort_order').notNullable().defaultTo(0);
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.index(['transfer_id'], 'transfer_files_transfer_idx');
+      // A photo can only appear once per transfer.
+      table.unique(['transfer_id', 'photo_id'], 'transfer_files_unique');
+    });
+  }
+
+  if (!(await knex.schema.hasTable('transfer_uploads'))) {
+    await knex.schema.createTable('transfer_uploads', (table) => {
+      table.increments('id').primary();
+      table.integer('transfer_id').unsigned().notNullable()
+        .references('id').inTable('transfers').onDelete('CASCADE');
+      table.string('original_filename', 512).notNullable();
+      // Storage-relative key, e.g. uploads/transfers/{id}/{stored-name}.
+      table.string('stored_path', 1024).notNullable();
+      table.integer('size_bytes');
+      table.string('mime_type', 100);
+      table.string('uploader_ip', 45);
+      table.timestamp('uploaded_at').defaultTo(knex.fn.now());
+      table.index(['transfer_id'], 'transfer_uploads_transfer_idx');
+    });
+  }
+
+  if (!(await knex.schema.hasTable('transfer_downloads'))) {
+    await knex.schema.createTable('transfer_downloads', (table) => {
+      table.increments('id').primary();
+      table.integer('transfer_id').unsigned().notNullable()
+        .references('id').inTable('transfers').onDelete('CASCADE');
+      table.string('kind', 20).notNullable().defaultTo('all'); // 'all' | 'single'
+      table.integer('photo_id').unsigned();
+      table.string('ip', 45);
+      table.timestamp('downloaded_at').defaultTo(knex.fn.now());
+      table.index(['transfer_id'], 'transfer_downloads_transfer_idx');
+    });
+  }
+
+  // Defaults for the create-transfer form + retention/upload behaviour.
+  const settings = [
+    { setting_key: 'transfer_default_expiry_days', setting_value: JSON.stringify(14), setting_type: 'number' },
+    { setting_key: 'transfer_default_grace_days', setting_value: JSON.stringify(7), setting_type: 'number' },
+    { setting_key: 'transfer_default_max_downloads', setting_value: JSON.stringify(0), setting_type: 'number' },
+    { setting_key: 'transfer_max_upload_size_mb', setting_value: JSON.stringify(50), setting_type: 'number' },
+    {
+      setting_key: 'transfer_upload_allowed_mime',
+      setting_value: JSON.stringify([
+        'image/jpeg', 'image/png', 'image/webp', 'image/gif',
+        'image/tiff', 'application/pdf', 'application/zip',
+      ]),
+      setting_type: 'general',
+    },
+  ];
+  for (const s of settings) {
+    const exists = await knex('app_settings').where('setting_key', s.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({ ...s, updated_at: knex.fn.now() });
+    }
+  }
+
+  // Feature flag — PicTransfer is a strictly opt-in module like slideshow /
+  // workflows: the sidebar entry, the /admin/transfers area and every
+  // transfer route (admin + public) stay dark until an admin turns it on
+  // under Settings → Features. Default OFF; idempotent seed.
+  if (await knex.schema.hasTable('feature_flags')) {
+    const existingFlag = await knex('feature_flags').where({ key: 'transfers' }).first();
+    if (!existingFlag) {
+      await knex('feature_flags').insert({ key: 'transfers', value: false });
+    }
+  }
+
+  // Admin notification when a transfer link expires (EN + DE, matching the
+  // convention of the other admin-notification templates — see migration 087).
+  const existingTemplate = await knex('email_templates')
+    .where('template_key', 'transfer_link_expired')
+    .first();
+  if (!existingTemplate) {
+    await knex('email_templates').insert({
+      template_key: 'transfer_link_expired',
+      subject_en: 'A transfer link has expired — {{transfer_title}}',
+      subject_de: 'Ein Transfer-Link ist abgelaufen — {{transfer_title}}',
+      body_html_en: `
+<h2>A transfer link has expired</h2>
+
+<p>The following file transfer is no longer downloadable by its recipient:</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Transfer:</strong> {{transfer_title}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Expired at:</strong> {{expiry_date}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Files included:</strong> {{file_count}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Client uploads received:</strong> {{upload_count}}</p>
+</div>
+
+<p>The files will be kept for {{grace_days}} more days (until {{delete_date}})
+so you can re-share or retrieve anything you still need, then they are
+automatically deleted.</p>
+
+<p><a href="{{admin_url}}">Open PicTransfer in the admin area</a></p>
+
+<p>Best regards,<br>
+Your PicPeak Installation</p>`,
+      body_text_en: `A transfer link has expired
+
+The following file transfer is no longer downloadable by its recipient:
+
+Transfer: {{transfer_title}}
+Expired at: {{expiry_date}}
+Files included: {{file_count}}
+Client uploads received: {{upload_count}}
+
+The files will be kept for {{grace_days}} more days (until {{delete_date}}) so
+you can re-share or retrieve anything you still need, then they are
+automatically deleted.
+
+Open PicTransfer in the admin area: {{admin_url}}
+
+Best regards,
+Your PicPeak Installation`,
+      body_html_de: `
+<h2>Ein Transfer-Link ist abgelaufen</h2>
+
+<p>Der folgende Datei-Transfer kann vom Empfänger nicht mehr heruntergeladen werden:</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Transfer:</strong> {{transfer_title}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Abgelaufen am:</strong> {{expiry_date}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Enthaltene Dateien:</strong> {{file_count}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Empfangene Kunden-Uploads:</strong> {{upload_count}}</p>
+</div>
+
+<p>Die Dateien werden noch {{grace_days}} Tage aufbewahrt (bis {{delete_date}}),
+damit Sie alles Benötigte erneut teilen oder abrufen können; danach werden sie
+automatisch gelöscht.</p>
+
+<p><a href="{{admin_url}}">PicTransfer im Admin-Bereich öffnen</a></p>
+
+<p>Mit freundlichen Grüßen,<br>
+Ihre PicPeak-Installation</p>`,
+      body_text_de: `Ein Transfer-Link ist abgelaufen
+
+Der folgende Datei-Transfer kann vom Empfänger nicht mehr heruntergeladen werden:
+
+Transfer: {{transfer_title}}
+Abgelaufen am: {{expiry_date}}
+Enthaltene Dateien: {{file_count}}
+Empfangene Kunden-Uploads: {{upload_count}}
+
+Die Dateien werden noch {{grace_days}} Tage aufbewahrt (bis {{delete_date}}),
+danach werden sie automatisch gelöscht.
+
+PicTransfer im Admin-Bereich öffnen: {{admin_url}}
+
+Mit freundlichen Grüßen,
+Ihre PicPeak-Installation`,
+      variables: JSON.stringify([
+        'transfer_title', 'expiry_date', 'file_count', 'upload_count',
+        'grace_days', 'delete_date', 'admin_url',
+      ]),
+    });
+  }
+};
+
+exports.down = async function (knex) {
+  if (await knex.schema.hasTable('feature_flags')) {
+    await knex('feature_flags').where({ key: 'transfers' }).del();
+  }
+  await knex('email_templates').where('template_key', 'transfer_link_expired').del();
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'transfer_default_expiry_days',
+      'transfer_default_grace_days',
+      'transfer_default_max_downloads',
+      'transfer_max_upload_size_mb',
+      'transfer_upload_allowed_mime',
+    ])
+    .del();
+  await knex.schema.dropTableIfExists('transfer_downloads');
+  await knex.schema.dropTableIfExists('transfer_uploads');
+  await knex.schema.dropTableIfExists('transfer_files');
+  await knex.schema.dropTableIfExists('transfers');
+};