chore(main): release 3.108.0-beta.0 (#1102)

* feat(gallery): sized preview tiers so phones stop pulling 1920px (#1095)

A phone can display ~1170px at most, but the preview tier is a single
1920px JPEG with no size parameter — so every lightbox swipe ships
roughly twice the bytes it can use, and the slide track preloads
neighbours, which multiplies it. On the reporter's all-external install
a null preview_url falls back to the untouched NAS original, which makes
it worse again.

Backend: ?w= on the gallery preview route, whitelisted to 640/1280/1920.
A whitelist rather than a free-form width because every distinct value
is a permanent rendition on disk — an open parameter is an invitation to
fill the volume. Unrecognised or absent values fall through to the
canonical 1920 preview, so old clients and hand-typed URLs behave
exactly as today.

Extra tiers are cache, not state: ensurePreviewImageAtWidth keys them by
width, looks them up in storage and generates on miss, and never writes
photos.preview_path. That column owns the canonical rendition, and
threading a width through it would mean the last size anyone requested
silently becomes "the" preview. Requesting 1920 resolves to the existing
preview rather than a w1920 duplicate, so no install grows a second copy
of every preview it already has.

The tier is part of the ETag. Without it a client holding the 1920
rendition gets a 304 for its 640 request and renders the wrong size,
which is this feature inverted.

Frontend: the lightbox picks a tier from innerWidth x devicePixelRatio,
capped at DPR 3 — uncapped, a DPR-10 device asks for 3900px and lands
straight back on the desktop rendition. At the top tier the URL is left
byte-identical so existing caches and ETags stay valid and desktop sees
no change at all. saveData and a 2g/3g effectiveType drop one tier;
both are Chromium-only, so they are a bonus rather than the mechanism.

Grid thumbnails are NOT tiered here, deliberately. generateThumbnail
resolves its width from admin settings rather than an argument, so
tiering it is a separate change — and shipping a srcset whose candidates
the server ignores would be worse than shipping none: the browser would
take the "600w" candidate, receive the 300px image and upscale it, which
is the reported softness made slightly worse. That half of #1095 lands
separately.

* fix(gallery): scope tier keys per photo, size by long edge, clean up tiers

External review. Three findings against the tier work, one a
cross-gallery leak.

The tier cache key was the photo's BASENAME. Managed uploads keep camera
basenames, so two events can each hold an IMG_0001.jpg — and a tier is
served straight from a cache hit without re-reading the source, so the
second gallery gets the first gallery's photo. Keys are now scoped by
photo id for every source type. The RAW branch passed proc.outputBasename,
which would have dropped that scoping again; it now passes the scoped name.

Tier selection used viewport WIDTH, but ?w= bounds the LONG edge
(fit:'inside'). On a 390x844 phone at DPR 3 a 2:3 portrait is bound by
height and renders ~1755 device px, so width-only picked 1280 and made
portraits softer than today; landscape on the same phone needs ~1170. It
now computes the rendered long edge from the photo's own dimensions and
falls back to the top tier — today's behaviour — when they are unknown.

Tiers live outside photos.preview_path, so nothing else knew they
existed: delete, bulk-delete and archive left them orphaned in previews/
forever, and regenerate-previews refreshed only the canonical rendition
while phones kept the stale copy. previewTierKeys derives them from the
same deterministic scheme and all four paths clean up. Deliberately
outside the preview_path guard — a tier can exist when the canonical
rendition never did, so keying cleanup off preview_path would strand
precisely the photos only ever viewed on a phone.

The existing tier tests encoded the old width-only semantics and were
updated rather than kept; that is a behaviour change, not a test fix.

---------

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

.dockerignore

@@ -5,7 +5,10 @@
 .env.*
 docker-compose*.yml
 .DS_Store
-node_modules
+# **/ so backend/node_modules and frontend/node_modules are excluded too —
+# the root-context Dockerfile.aio COPYs those directories and must get its
+# deps from its builder stages, never from the host checkout.
+**/node_modules
 npm-debug.log
 coverage
 .nyc_output
@@ -18,3 +21,31 @@ storage/events/archived/*
 storage/thumbnails/*
 data/*.db
 logs/*
+
+# Dockerfile.aio builds from the REPOSITORY ROOT and Docker reads only this
+# file — backend/.dockerignore is never consulted — so the unprefixed rules
+# above miss backend/data, backend/logs and backend/storage. A checkout that has
+# been used to run PicPeak would otherwise bake its database, photos, logs and
+# SETUP_TOKEN into a published image layer.
+# backend/data wholesale, not a suffix list. It holds only runtime state and is
+# gitignored in full (.gitignore: `data/`), while suffix rules kept letting real
+# secrets through: a used checkout here carries ADMIN_CREDENTIALS.txt alongside
+# the database, plus -journal files and any DATABASE_PATH that does not end in
+# .db. Any of those in a published layer is a credential leak.
+backend/data
+backend/logs
+backend/storage
+
+# Same root-context trap, one level deeper: the `.env`, `.env.*` and `data/*.db`
+# rules above are unanchored only in appearance — Docker matches them against the
+# path from the build context, so they catch `./.env` and never `backend/.env`.
+# A checkout that has been used to run PicPeak locally keeps its JWT_SECRET,
+# DB_PASSWORD and SMTP credentials there, and `COPY backend/ .` puts the file at
+# /app/.env in the published layer. Match at any depth instead, the way
+# **/node_modules above already does.
+**/.env
+**/.env.*
+**/*.db
+**/*.db-journal
+**/*.sqlite*
+frontend/dist

.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)
@@ -210,6 +223,55 @@ LOGS=./logs
 #   attempts is exponential: 1m, 5m, 30m, 2h, 12h.
 # WEBHOOK_MAX_ATTEMPTS=5
 
+# -----------------------------------------------------------------------------
+# Face recognition — "People in this gallery" (#1074, optional)
+# -----------------------------------------------------------------------------
+# Requires the optional picpeak-ml sidecar container:
+#   docker compose --profile faces up -d
+#
+# NONE of these variables do anything until the `faces` feature flag is
+# enabled in Admin → Settings, AND the per-event "Detect people in this
+# gallery" toggle is switched on. Both default to OFF. With the flag off the
+# backend never contacts the sidecar, so leaving these at their defaults on an
+# install without the container is completely inert.
+#
+# Face embeddings are biometric data (GDPR Art. 9 special category in the EU).
+# The photographer is the controller and needs a lawful basis for the people
+# in their photos — see docs/feature-face-recognition.md before enabling.
+#
+# NOT AVAILABLE ON THE ALL-IN-ONE IMAGE. The single-container build sets
+# PICPEAK_SINGLE_CONTAINER=true and the backend refuses to enable face
+# recognition there regardless of these variables or the feature flag: that
+# image runs the backend, frontend, database and every worker in one
+# container, with no ML sidecar to talk to, and face detection would compete
+# with image processing for the same CPU and memory. Use the standard
+# multi-container deployment if you want this feature.
+#
+# FACE_ML_TOKEN (no default — REQUIRED to run the sidecar)
+#   Shared secret between the backend and the sidecar. The sidecar refuses to
+#   start without it rather than serving anonymously, so an accidentally
+#   published port is never a free face-detection API. Generate with:
+#     openssl rand -hex 32
+# FACE_ML_TOKEN=
+#
+# FACE_ML_URL (default: http://picpeak-ml:8000)
+#   Defaults to the sidecar's compose service name, so the standard
+#   deployment needs no configuration here. Only change it if you run the
+#   sidecar outside the default compose network.
+# FACE_ML_URL=http://picpeak-ml:8000
+#
+# FACE_PROCESSOR_CONCURRENCY (default: 1)
+#   Face-detection workers in the backend. Defaults to 1 deliberately: face
+#   scanning shares a host with Sharp image processing, which is the real
+#   memory pressure (see UPLOAD_PROCESSOR_CONCURRENCY). Raise only on hosts
+#   with headroom to spare.
+# FACE_PROCESSOR_CONCURRENCY=1
+#
+# FACE_ORT_THREADS (default: 1)
+#   ONNX Runtime threads inside the sidecar. More threads mean faster
+#   per-photo inference and higher RSS.
+# FACE_ORT_THREADS=1
+
 # Note on FRONTEND_API_URL (documentation only):
 # When using pre-built frontend images, runtime env vars cannot override the built JS.
 # Do NOT rely on FRONTEND_API_URL in Compose. Instead, keep VITE_API_URL=/api and

.github/dockerhub/aio.md

@@ -0,0 +1,47 @@
+# picpeak — All-in-one
+
+**picpeak** is an open-source, self-hosted **photo-sharing platform for photographers**, with an optional CRM / accounting suite. This image is the **all-in-one** build: the backend, the built web UI and SQLite in **one container, one process** — no compose file, no separate database, no reverse proxy to wire up.
+
+- 📦 **Source, docs & issues:** https://github.com/PicPeak/picpeak
+- 🧩 **Multi-container images:** [`picpeak/backend`](https://hub.docker.com/r/picpeak/backend) + [`picpeak/frontend`](https://hub.docker.com/r/picpeak/frontend)
+
+## Supported tags
+- `latest` / `stable` — latest stable release
+- `x.y.z` — a pinned release (**recommended for production**)
+- `beta` / `main` — latest build from `main` (may be unstable)
+- **Architectures:** `linux/amd64`, `linux/arm64` (x86 and ARM NAS)
+
+## Quick start
+
+    docker run -d --name picpeak -p 3000:3000 \
+      -v picpeak:/data \
+      -e JWT_SECRET="$(openssl rand -base64 48)" \
+      picpeak/aio:stable
+
+Then open **http://localhost:3000/admin** and complete the setup wizard. Read the one-time setup token with:
+
+    docker exec picpeak cat /data/db/SETUP_TOKEN
+
+> 🔗 Share links need to know your address. The image defaults `FRONTEND_URL` to `http://localhost:3000`; pass `-e FRONTEND_URL=https://photos.example.com` (or set the site URL in Settings) before you send a gallery to a client.
+
+## Ports & volumes
+- Container port **3000** (HTTP; put your own TLS terminator in front for public use).
+- **One volume: `/data`** — back it up and you have backed up the install.
+  - `/data/db` — `picpeak.db` and `SETUP_TOKEN`
+  - `/data/storage` — originals, thumbnails, archives
+  - `/data/logs`, `/data/backup`
+
+## External Postgres
+SQLite is this image's default, not its only option. Point it at an existing database exactly like the backend image:
+
+    -e DATABASE_CLIENT=pg -e DB_HOST=… -e DB_USER=… -e DB_PASSWORD=…
+
+## How it differs from the compose stack
+- **SQLite takes one writer at a time** — right for a home server, a NAS or a single studio; the compose stack with PostgreSQL is what scales.
+- **No Redis** — background jobs run in-process.
+- **Face recognition is unavailable** here. It needs the separate [`picpeak/ml`](https://hub.docker.com/r/picpeak/ml) sidecar, and a second image-processing pipeline competing with thumbnailing for one container's CPU would just make the install slow. Run the multi-container deployment for that feature.
+
+You can move to the full stack later without reinstalling: take a `.picpeak` backup and restore it there.
+
+## Docs
+Volume layout, the external-Postgres variant, TLS, updates and the limits: **https://docs.picpeak.app/deployment/single-container**

.github/dockerhub/ml.md

@@ -0,0 +1,56 @@
+# picpeak — ML sidecar (face detection)
+
+**picpeak** is an open-source, self-hosted **photo-sharing platform for photographers**. This image is the **optional face-detection sidecar**: it detects faces in one image and returns a bounding box, five landmarks, quality signals and a 512-d embedding per face.
+
+**Nothing else.** No database, no volumes, no state, no egress, no model download at runtime. Clustering, person identity, thresholds and every privacy decision live in the picpeak backend, where the data already is — this service forgets each image the moment it answers.
+
+If you don't run this container, the feature does not exist.
+
+- 📦 **Source, docs & issues:** https://github.com/PicPeak/picpeak
+- 🧩 **Runs with:** [`picpeak/backend`](https://hub.docker.com/r/picpeak/backend) + [`picpeak/frontend`](https://hub.docker.com/r/picpeak/frontend)
+
+## Supported tags
+- `latest` / `stable` — latest stable release
+- `x.y.z` — a pinned release (**recommended for production** — keep it on the **same** tag as the backend)
+- `beta` / `main` — latest build from `main` (may be unstable)
+- **Architectures:** `linux/amd64`, `linux/arm64`
+
+> The sidecar's API contract is versioned with the backend that calls it, so `PICPEAK_CHANNEL` resolves the same string across all picpeak images.
+
+## Turning it on
+The maintained compose file already contains this service behind a profile — you do not write it by hand:
+
+    docker compose --profile faces up -d
+
+Then two deliberate actions in the app, neither of which is installing this container:
+
+1. Enable the **`faces`** feature flag in admin settings.
+2. Enable **"Detect people in this gallery"** per event.
+
+**Nothing in the backend touches this service while the flag is off**, so an install without this container never attempts a connection.
+
+## Configuration
+| | |
+|---|---|
+| `FACE_ML_TOKEN` | **Required.** The container **refuses to start** without it, so an accidentally published port is never a free face-detection API. Must match the backend's `FACE_ML_TOKEN`. |
+| `FACE_ORT_THREADS` | ONNX Runtime threads (default `1`). |
+
+Port **8000**, no volumes, no published ports needed — the backend reaches it on the compose network. `FACE_ML_URL` defaults to `http://picpeak-ml:8000` (the compose service name), so the standard deployment needs no URL configuration.
+
+## API
+All endpoints except `/health` require the `X-Face-ML-Token` header.
+
+| | |
+|---|---|
+| `GET /health` | `{"status": "ok"}` — unauthenticated, used by the healthcheck |
+| `GET /info` | `{detector, embedder, model_version, dim}` |
+| `POST /faces` | multipart `image` → `{model_version, faces: [...]}` |
+
+## Models
+YuNet (detection) + FaceNet-512 (embedding), **both MIT**, baked into the image and verified by SHA-256 at build time — never downloaded at runtime, so airgapped installs work and a model cannot change under a running deployment. See [`ml/LICENSES.md`](https://github.com/PicPeak/picpeak/blob/main/ml/LICENSES.md) for why these and not InsightFace's non-commercial weights.
+
+## Not available on the all-in-one image
+[`picpeak/aio`](https://hub.docker.com/r/picpeak/aio) sets `PICPEAK_SINGLE_CONTAINER=true` and the backend refuses to enable face recognition there — a second image-processing pipeline competing with thumbnailing for one small container's CPU would not fail loudly, it would just make the install slow. Run the multi-container deployment for this feature.
+
+## Docs
+**https://docs.picpeak.app** · sidecar internals, model conversion and the alignment/threshold contract: [`ml/README.md`](https://github.com/PicPeak/picpeak/blob/main/ml/README.md)

.github/workflows/README-DOCKER.md

@@ -1,6 +1,8 @@
 # Docker Build and Push Workflow
 
-This GitHub Actions workflow automatically builds and pushes Docker images for both the backend and frontend to GitHub Container Registry (ghcr.io).
+This GitHub Actions workflow automatically builds and pushes Docker images for the backend, the frontend, the all-in-one image and the optional ML sidecar to GitHub Container Registry (ghcr.io). On the canonical org repo every one of them is mirrored to Docker Hub as `docker.io/picpeak/{backend,frontend,aio,ml}`; forks build the same images GHCR-only.
+
+The **all-in-one image** (`<repo>/aio`, built from `Dockerfile.aio` at the repo root, #1042) bundles the backend and the built frontend into a single container with SQLite as the default engine — one `docker run`, no compose. It follows the same per-arch build → digest-merge → per-version tag scheme as the other two images, is mirrored to Docker Hub (`docker.io/picpeak/aio`) alongside GHCR on the canonical org repo, and every PR additionally runs a `smoke-aio` job that boots the image and asserts the SPA shell, brand-title rendering, immutable asset caching, and the SQLite engine resolution.
 
 ## Features
 
@@ -10,6 +12,7 @@ This GitHub Actions workflow automatically builds and pushes Docker images for b
 - 🔒 **Security scanning** with Trivy vulnerability scanner
 - 💾 **Build caching** for faster subsequent builds
 - 📊 **Build summaries** in GitHub Actions UI
+- 📝 **Docker Hub pages** for `aio` and `ml` synced from `.github/dockerhub/*.md` on every `main` merge (`dockerhub-descriptions` job). `backend` and `frontend` pages are still hand-maintained in the Hub UI — add `.github/dockerhub/{backend,frontend}.md` with their current text before putting them under the same job.
 
 ## Authentication
 
@@ -52,6 +55,11 @@ docker pull ghcr.io/picpeak/picpeak/backend:v1.0.0
 
 # Pull for specific architecture
 docker pull --platform linux/arm64 ghcr.io/picpeak/picpeak/backend:latest
+
+# The same images on Docker Hub (identical tags, identical digests)
+docker pull picpeak/backend:latest
+docker pull picpeak/aio:stable
+docker pull picpeak/ml:stable
 ```
 
 ### Using in Docker Compose

.github/workflows/tests.yml

@@ -113,3 +113,33 @@ jobs:
       - name: Run Vitest suite
         working-directory: ./frontend
         run: npm test -- --run
+
+  # Optional face-detection sidecar (#1074). Runs on every PR regardless of
+  # whether the feature is enabled anywhere — these tests need no model
+  # weights (they stub the pipeline out) and cover the auth boundary, the
+  # request guards and the alignment geometry, which is where a mistake is a
+  # security problem or a silent accuracy problem rather than a visible bug.
+  ml:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          # Matches ml/Dockerfile's base image, so a wheel that resolves here
+          # resolves in the image too.
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: ml/requirements.txt
+
+      - name: Install ml deps
+        working-directory: ./ml
+        run: pip install -r requirements.txt pytest httpx
+
+      - name: Run pytest suite
+        working-directory: ./ml
+        run: python -m pytest tests/ -q

.gitignore

@@ -131,26 +131,17 @@ 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/
 
-# Python bytecode. The ML sidecar lives on main only, so this branch never
-# needed the rule — which is how a `git add -A` from a shared working tree
-# committed 16 .pyc files here in #1247.
+# Python artifacts — the picpeak-ml sidecar (#1074) is the only Python in
+# this tree, but bytecode and virtualenvs must never be committed.
 __pycache__/
-*.pyc
-
-# Issue / PR screenshots belong on a `screenshots/*` branch, never on main or
-# stable — that is what those branches exist for. Two landed at the repo root
-# on main in #1241 and shipped as part of the source tree; nothing stopped it.
-#
-# Anchored with a leading slash so docs/ keeps its own images.
-/issue-*.png
-/issue-*.jpg
-/screenshot-*.png
-/screenshot-*.jpg
-/*-screenshot.png
-/*-screenshot.jpg
-
+*.py[cod]
+.pytest_cache/
+ml/.venv/
+ml/venv/
+# Locally produced model weights. The image fetches these by pinned URL and
+# SHA-256 at build time; a 90MB blob must not end up in git history.
+ml/*.onnx
+ml/*.h5

.release-please-manifest-beta.json

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

.release-please-manifest.json

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

CONTRIBUTING.md

@@ -163,14 +163,13 @@ PicPeak runs on two long-lived branches:
 | Branch | Role | What targets it |
 |---|---|---|
 | **`main`** | Active development. The next release is being assembled here. | Feature PRs. Most bugfix PRs. |
-| **`stable`** | Curated release channel. Production-recommended. | Security fixes and regular bugfix backports, kept small and free of unrelated features. |
+| **`stable`** | Curated release channel. Production-recommended. | Urgent bugfix backports only — small, surgical PRs that land cleanly without dragging in unrelated changes. |
 
 ### Which branch should my PR target?
 
 - **New feature** → target `main`.
 - **Bugfix that ONLY affects active dev** → target `main`.
-- **Bugfix that current stable users need** → target `main`; regular bug fixes are generally backported automatically to `stable`. Maintainers handle conflicts or create a separate focused backport PR when needed.
-- **Security vulnerability** → report privately using [SECURITY.md](SECURITY.md). Security fixes are always released on both `stable` and `main`; coordinate any fix with the maintainers before opening a public PR.
+- **Bugfix that current stable users need** → open a small PR against `main`, AND a separate small PR against `stable` with the same change. Keep both surgical so each lands cleanly.
 
 **Hard rule on PR scope**: bugfix PRs against `stable` must be small enough to backport without conflict. Omnibus PRs (e.g. five unrelated sub-features) are fine for `main`, but never for `stable` — they make the next `main → stable` merge painful and break the "stable is always shippable" invariant.
 
@@ -188,6 +187,6 @@ See [RELEASING.md](RELEASING.md) for the full operational doc (promotion criteri
 
 - Create an [issue](https://github.com/PicPeak/picpeak/issues) for bugs or features
 - Join [discussions](https://github.com/PicPeak/picpeak/discussions) for questions
-- Security vulnerabilities: Follow the [security policy](SECURITY.md) and use [private vulnerability reporting](https://github.com/PicPeak/picpeak/security/advisories/new)
+- Security issues: Open a [security issue](https://github.com/PicPeak/picpeak/issues/new?labels=security) on GitHub
 
-Thank you for contributing! 🎉
+Thank you for contributing! 🎉

Dockerfile.aio

@@ -0,0 +1,178 @@
+# All-in-one image (#1042): one container, one Node process.
+#
+# The backend serves the built frontend itself via server.js's SERVE_FRONTEND
+# block (SPA fallback, OG crawler intercept, brand-title render, immutable
+# asset caching) — no nginx, no supervisor, no bundled Postgres/Redis. SQLite
+# is the explicit default engine; pointing DB_HOST/DB_USER/DB_PASSWORD (+
+# DATABASE_CLIENT=pg) at an external Postgres works exactly like the backend
+# image. Build context is the REPO ROOT (both backend/ and frontend/ are
+# needed): docker build -f Dockerfile.aio .
+#
+# KEEP IN SYNC: the runtime stage below mirrors backend/Dockerfile's
+# production stage (base image, apk set, npm removal, nodejs user, fontconfig
+# registration, directory layout, healthcheck, entrypoint). When
+# backend/Dockerfile changes, change this file too — the aio smoke job in
+# docker-build.yml catches boot-level drift, not package-level drift.
+
+# ---------------------------------------------------------------------------
+# Frontend build — mirrors frontend/Dockerfile's builder stage
+# ---------------------------------------------------------------------------
+FROM node:22-alpine AS frontend-builder
+
+ARG CACHEBUST=1
+
+WORKDIR /app
+
+COPY frontend/package*.json ./
+RUN npm ci --legacy-peer-deps
+
+COPY frontend/ .
+RUN npm run build
+
+# ---------------------------------------------------------------------------
+# Backend deps — mirrors backend/Dockerfile's builder stage
+# ---------------------------------------------------------------------------
+FROM node:22-alpine AS backend-builder
+
+ARG CACHEBUST=1
+
+WORKDIR /app
+
+COPY backend/package*.json ./
+RUN npm ci --omit=dev
+
+# ---------------------------------------------------------------------------
+# Runtime — mirrors backend/Dockerfile's production stage + the frontend dist
+# ---------------------------------------------------------------------------
+FROM node:22-alpine
+
+ARG CACHEBUST=1
+ARG BUILD_DATE
+ARG VCS_REF
+ARG VERSION
+
+LABEL org.opencontainers.image.source="https://github.com/PicPeak/picpeak"
+LABEL org.opencontainers.image.description="PicPeak all-in-one (backend + frontend, single container)"
+LABEL org.opencontainers.image.licenses="MIT"
+
+WORKDIR /app
+
+# Explicit engine selection (#1038/#1042): SQLite is this image's DEFAULT
+# engine — set explicitly, never inferred, and wait-for-db.sh skips its
+# Postgres readiness wait for it. Point the container at an external Postgres
+# by overriding DATABASE_CLIENT=pg and setting DB_HOST/DB_USER/DB_PASSWORD,
+# exactly like the backend image. The boot resolver still logs the engine and
+# refuses the populated-both conflict.
+# STORAGE_PATH: getStoragePath() falls back to path.join(__dirname,
+# '../../../storage') — which resolves to the container-root `/storage` here,
+# writable by root but EACCES for the nodejs user after the su-exec drop.
+# Compose masks this by setting STORAGE_PATH=/app/storage; this image must
+# pin the same path (it is the directory the Dockerfile creates and chowns).
+ENV NODE_ENV=production \
+    DATABASE_CLIENT=sqlite3
+
+# See backend/Dockerfile for the rationale of each of the following blocks.
+RUN echo "cachebust=${CACHEBUST}" && apk upgrade --no-cache
+
+RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
+
+#   sqlite — DatabaseBackupService.createSQLiteBackup() SPAWNS the `sqlite3`
+#     CLI for `.backup` and PRAGMA integrity_check; the npm module does not
+#     ship that binary. backend/Dockerfile omits it because compose always runs
+#     Postgres — this image defaults to SQLite, so without it every database
+#     backup fails with ENOENT.
+RUN apk add --no-cache dumb-init postgresql-client sqlite ffmpeg su-exec \
+    fontconfig ttf-dejavu ttf-liberation poppler-utils exiftool && \
+    fc-cache -f
+
+RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
+
+COPY --from=backend-builder --chown=nodejs:nodejs /app/node_modules ./node_modules
+COPY --chown=nodejs:nodejs backend/ .
+
+RUN chmod -R a+r /app && chmod +x wait-for-db.sh
+
+RUN printf '<?xml version="1.0"?>\n<!DOCTYPE fontconfig SYSTEM "fonts.dtd">\n<fontconfig>\n  <dir>/app/assets/fonts</dir>\n</fontconfig>\n' > /etc/fonts/conf.d/99-picpeak-fonts.conf && \
+    fc-cache -f /app/assets/fonts
+
+# ---------------------------------------------------------------------------
+# One volume, one layout (#1042 scope: "single data layout on one volume")
+# ---------------------------------------------------------------------------
+#   /data/db       picpeak.db (+ -wal/-shm) and SETUP_TOKEN
+#   /data/storage  originals, thumbnails, archives
+#   /data/logs     application logs
+#   /data/backup   built-in backup output; /backup symlinks here
+#
+# `-v picpeak:/data` and nothing else to remember — back up /data and you have
+# backed up the install. /backup is where migrations 029 + 030 seed the backup
+# destinations, so it is symlinked in rather than left dangling.
+ENV DATA_ROOT=/data \
+    DATA_DIR=/data/db \
+    DATABASE_PATH=/data/db/picpeak.db \
+    STORAGE_PATH=/data/storage \
+    LOG_DIR=/data/logs \
+    BACKUP_DIR=/data/backup
+
+# Share links are absolute only when a base URL is known: getFrontendBaseUrl()
+# reads FRONTEND_URL, falls back to the general_site_url setting, and otherwise
+# returns "" — which makes share_url come out as a bare "/gallery/<slug>/<token>"
+# in API responses, QR codes and emails. docker-compose.yml defaults this to
+# http://localhost:3000, but the documented one-liner for this image passes only
+# JWT_SECRET, so without a default here every fresh single-container install
+# would hand out unusable links. Same default as compose; override with
+# -e FRONTEND_URL=https://photos.example.com, or set the site URL in Settings.
+ENV FRONTEND_URL=http://localhost:3000
+
+# /app/storage is a second entrance to the same volume. The business-document
+# writers (quoteService, invoice sending/reminders, contract signatures) build
+# their paths from `path.join(process.cwd(), 'storage', ...)` and never consult
+# STORAGE_PATH. Compose hides that because it sets STORAGE_PATH=/app/storage
+# with WORKDIR /app, so the two happen to be the same directory; here they are
+# not, and /app is root-owned, so a quote or invoice PDF would fail to write as
+# UID 1001 — and be lost with the container even if it succeeded. Teaching
+# those services STORAGE_PATH is the real fix and belongs in its own change;
+# the symlink restores the coincidence compose already relies on.
+RUN mkdir -p /data/db /data/storage/events/active /data/storage/events/archived \
+             /data/storage/thumbnails /data/logs \
+             /data/backup/picpeak /data/backup/database && \
+    ln -s /data/backup /backup && \
+    ln -s /data/storage /app/storage && \
+    chown -R nodejs:nodejs /data
+
+VOLUME ["/data"]
+
+# The frontend bundle, served by server.js's SERVE_FRONTEND block. Explicit
+# opt-in rather than the dist-exists autodetect, so the behavior is pinned
+# even if the autodetect heuristic ever changes.
+COPY --from=frontend-builder --chown=nodejs:nodejs /app/dist /app/frontend/dist
+ENV SERVE_FRONTEND=true \
+    FRONTEND_DIR=/app/frontend/dist
+
+# Marks this as the single-container build. The backend refuses to enable face
+# recognition (#1074) when it sees this, on performance grounds: that feature
+# needs a separate ML container this image does not contain, and it would add
+# a second image-processing pipeline competing with Sharp for the CPU and
+# memory of a container sized for one photographer plus guests browsing. The
+# failure would not be loud — just a slow install that looks broken.
+#
+# An explicit marker rather than inferring it from SERVE_FRONTEND or the
+# SQLite path: legitimate multi-container deployments do both of those, and
+# none of them should lose the feature by accident.
+ENV PICPEAK_SINGLE_CONTAINER=true
+
+# No USER directive — same as backend/Dockerfile: the container starts as root
+# so wait-for-db.sh can chown bind-mounted volumes to UID 1001, then drops
+# privileges via su-exec (#484).
+
+EXPOSE 3000
+
+# Shell form so it resolves $PORT: a hard-coded 3000 marks an otherwise healthy
+# container unhealthy forever the moment anyone overrides the port.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider "http://localhost:${PORT:-3000}/health" || exit 1
+
+ENTRYPOINT ["dumb-init", "--"]
+# --max-http-header-size matches nginx's `large_client_header_buffers 4 32k`.
+# Requests reach Node directly here, and its 16 KiB default would reject a guest
+# carrying several per-gallery JWT cookies before Express ever saw them.
+CMD ["./wait-for-db.sh", "node", "--max-http-header-size=32768", "server.js"]

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,aio,ml}` (and on Docker Hub as `picpeak/{backend,frontend,aio,ml}`) 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,90 @@ 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.
+### Or: one container, no compose file
 
-> 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`).
-
-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).
-
-**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.
-
-## 🔄 Release Channels
-
-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.
-
-### Stable Channel (Recommended)
-- Production-ready releases
-- Thoroughly tested before release
-- Docker tags: `stable`, `latest`, or specific version like `v2.3.0`
-
-### 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`
-
-### Switching Channels
-
-Set the `PICPEAK_CHANNEL` environment variable in your `.env` file:
+For a home server, a NAS, or a single small studio, the all-in-one image runs the whole app as one process with SQLite — no compose file, no separate database, no reverse proxy to wire up:
 
 ```bash
-# For stable releases (default)
-PICPEAK_CHANNEL=stable
-
-# For beta releases
-PICPEAK_CHANNEL=beta
-
-# For a specific version
-PICPEAK_CHANNEL=v2.3.0
+docker run -d --name picpeak -p 3000:3000 \
+  -v picpeak:/data \
+  -e JWT_SECRET="$(openssl rand -base64 48)" \
+  ghcr.io/picpeak/picpeak/aio:main
 ```
 
-Then update your containers:
+Then open **http://localhost:3000/admin** and read the setup token with `docker exec picpeak cat /data/db/SETUP_TOKEN`.
 
-```bash
-docker compose -f docker-compose.production.yml pull
-docker compose -f docker-compose.production.yml up -d
-```
+`:main` is the active-development tag, and today it is the only one the all-in-one image has — `Dockerfile.aio` landed after the current stable release, so `:stable` and `:latest` first appear for this image once the aio build reaches the `stable` branch. Switch to `:stable` then, or pin a version tag (`3.107.4-beta.0`) if you would rather not track `main`.
 
-### Update Notifications
+The compose stack above is still the right choice for anything busier — SQLite takes one writer at a time, and Postgres is what scales. You can move to it later without reinstalling: take a `.picpeak` backup and restore it into the full stack. See **[Single-container install](https://docs.picpeak.app/deployment/single-container)** for the volume layout, the external-Postgres variant, TLS, and the limits.
 
-The admin dashboard automatically notifies you when updates are available for your channel. To disable update checks, set:
+### Docker images
 
-```bash
-UPDATE_CHECK_ENABLED=false
-```
+| | GHCR | Docker Hub |
+|---|---|---|
+| Backend | `ghcr.io/picpeak/picpeak/backend` | [`picpeak/backend`](https://hub.docker.com/r/picpeak/backend) |
+| Frontend | `ghcr.io/picpeak/picpeak/frontend` | [`picpeak/frontend`](https://hub.docker.com/r/picpeak/frontend) |
+| All-in-one | `ghcr.io/picpeak/picpeak/aio` | [`picpeak/aio`](https://hub.docker.com/r/picpeak/aio) |
+| ML sidecar (optional) | `ghcr.io/picpeak/picpeak/ml` | [`picpeak/ml`](https://hub.docker.com/r/picpeak/ml) |
+
+Both registries get the same digests and the same tags — `stable`/`latest`, a pinned `x.y.z`, and `beta`/`main` for the active development channel — for `linux/amd64` and `linux/arm64`. Keep every image in one install on the **same** tag.
+
+## 🌟 Why 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
+- **🌍 Multi-Language** — built-in i18n (EN, DE)
+
+## ✨ Features
+
+**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.
+
+**For clients** — clean mobile-optimized galleries, one-click bulk downloads, smart search, **People in this gallery** face grouping (opt-in per gallery, needs the optional [ML sidecar](ml/README.md)), optional guest uploads, and download protection (watermarking + right-click prevention).
+
+**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).
+
+<details>
+<summary><strong>🧾 For studios — CRM &amp; Accounting (Beta, off by default)</strong></summary>
+
+- 📝 **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
+
+</details>
+
+> [!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) |
+| 📦 Single-container install (one `docker run`, SQLite) | [docs.picpeak.app/deployment/single-container](https://docs.picpeak.app/deployment/single-container) |
+| ⚙️ 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 +164,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,28 +52,29 @@ 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)
 
-Regular bug fixes are generally backported automatically from `main` to `stable`. Keep backports focused on the fix, without unrelated features, and resolve conflicts manually when needed.
-
-**Security fixes are always released on both `stable` and `main`.** Do not wait for a full promotion to deliver a security update. A fix first applied to `stable` must also be forward-ported to `main`; a fix first applied to `main` must also reach `stable`. See [SECURITY.md](SECURITY.md) for the support policy.
-
-When a backport needs manual handling:
+If a critical bug or security issue affects the current stable and `main` has moved too far for a full promotion to be appropriate, backport just the fix:
 
 1. Create a `security/cve-backport-X.Y.Z` or `fix/critical-X.Y.Z` branch off `stable`.
 2. Cherry-pick or hand-write the minimal fix.
 3. Open a PR to `stable` with the smallest possible diff.
 4. After merge, release-please will propose a patch-level stable release (e.g. `v3.55.1`).
 5. **Forward-port the fix to `main`** if it isn't already there. Otherwise the next full promotion will reintroduce the bug.
-6. For security fixes, verify that the fix has been published through **both** release channels; merging the code is only part of delivery.
 
 PR #412 ("backport 18 dependency CVE patches from beta") is a worked example of this path (predates the rename; the mechanics are unchanged).
 
@@ -88,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.

SECURITY.md

@@ -1,81 +1,88 @@
 # Security Policy
 
-## Scope
-
-This policy covers the PicPeak backend, frontend, all-in-one (AIO) image, optional
-ML component, and the Docker images published by the PicPeak project. Other
-PicPeak repositories define their own supported versions and release channels.
-
 ## Supported Versions
 
-Security support follows the current release channels:
+We release patches for security vulnerabilities. Currently supported versions:
 
-| Version or channel | Security support |
-| --- | --- |
-| Latest stable release from `stable` | Supported; security fixes are published through this channel |
-| Latest beta release from `main` | Supported; security fixes are published through this channel |
-| Superseded stable or beta releases | Upgrade to the latest release in the same channel; older releases are not maintained separately |
-| 2.x and earlier | No longer supported |
-
-See the [latest stable release](https://github.com/PicPeak/picpeak/releases/latest)
-and [all releases, including betas](https://github.com/PicPeak/picpeak/releases).
-Version numbers differ between channels; each channel receives its own updates.
-
-### Security fixes and bug backports
-
-**Security fixes are always released on both `stable` and `main`.** A fix that
-lands on one branch must also reach the other branch and be published through
-both release channels. Security updates do not wait for the next full
-`main`-to-`stable` promotion.
-
-Regular bug fixes are also generally backported automatically to `stable`.
-Backports remain focused on the fix, without pulling in unrelated features.
-Maintainers resolve conflicts or handle a backport manually when necessary.
-
-The [release process](RELEASING.md) describes backports, forward-ports and
-publication. Operators must apply the published updates to their installations.
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.x.x   | :white_check_mark: |
+| < 2.0   | :x:                |
 
 ## Reporting a Vulnerability
 
-**Do not report vulnerabilities in public issues, discussions or pull requests.**
+We take the security of PicPeak seriously. If you have discovered a security vulnerability, please follow these steps:
 
-Report privately through:
+### 1. **Do NOT create a public GitHub issue**
 
-- [GitHub Private Vulnerability Reporting](https://github.com/PicPeak/picpeak/security/advisories/new) (preferred).
-- Email **info@picpeak.app** if you cannot use GitHub's private reporting form.
+### 2. Report the vulnerability privately by:
+- **Preferred:** Use [GitHub Private Vulnerability Reporting](https://github.com/PicPeak/picpeak/security/advisories/new)
+- **Alternative:** Email us at **info@picpeak.app** with the details
+- Include:
+  - Description of the vulnerability
+  - Steps to reproduce
+  - Potential impact
+  - Suggested fix (if any)
 
-Include the affected component, version or image tag, deployment method,
-reproduction steps, expected impact and any suggested fix. Share only the
-information needed to reproduce the problem; remove credentials and personal
-data from logs or examples.
+### 3. You can expect:
+- Acknowledgment within 48 hours
+- Regular updates on our progress
+- Credit in the fix announcement (unless you prefer to remain anonymous)
 
-We aim to acknowledge reports within 48 hours. This is a response target, not a
-guaranteed service level or a promised resolution time. We will provide progress
-updates and coordinate disclosure with the reporter. Reporter credit is optional;
-tell us if you prefer to remain anonymous.
+## Security Measures
 
-## Deployment Security
+PicPeak implements several security measures:
 
-Security depends on both the software and its configuration. Operators should:
+### Authentication & Authorization
+- JWT-based authentication with secure token storage
+- bcrypt password hashing with configurable rounds
+- Role-based access control for admin functions
+- Session timeout management
 
-- Use HTTPS and configure the reverse proxy and trusted proxy settings correctly.
-- Use strong credentials and keep deployment secrets private.
-- Apply updates for the chosen release channel and restrict unnecessary network access.
-- Keep backups and verify that they can be restored.
+### Input Validation
+- All user inputs are validated and sanitized
+- SQL injection prevention through parameterized queries
+- XSS protection via Content Security Policy
+- File upload restrictions and validation
 
-See the deployment guides for [HTTPS](https://docs.picpeak.app/deployment/ssl-certificates),
-[reverse proxies](https://docs.picpeak.app/deployment/reverse-proxy),
-[security settings](https://docs.picpeak.app/guides/admin-settings/security)
-and [backup and restore](https://docs.picpeak.app/guides/backup-restore).
+### Rate Limiting
+- API rate limiting to prevent abuse
+- Brute force protection on authentication endpoints
+- Configurable limits per endpoint
+
+### Data Protection
+- HTTPS enforcement in production
+- Secure cookie settings
+- CORS configuration
+- Sensitive data encryption
+
+### Infrastructure
+- Regular dependency updates
+- Security headers (HSTS, X-Frame-Options, etc.)
+- Activity logging for audit trails
+- Automated backups
+
+## Best Practices for Deployment
+
+1. **Always use HTTPS** in production
+2. **Change default passwords** immediately
+3. **Keep dependencies updated** regularly
+4. **Configure firewall rules** appropriately
+5. **Monitor logs** for suspicious activity
+6. **Backup regularly** and test restoration
 
 ## Vulnerability Disclosure
 
-We coordinate disclosure with the reporter while preparing fixes. Security fixes
-are published through both supported channels. Advisories and release notes
-identify affected versions, the fixed version in each channel, the impact and
-any required mitigation or upgrade steps. Reporter credit is included with
-permission.
+We believe in responsible disclosure. Once a vulnerability is fixed:
 
-For ordinary bugs and support requests, use
-[GitHub Issues](https://github.com/PicPeak/picpeak/issues) or
-[GitHub Discussions](https://github.com/PicPeak/picpeak/discussions).
+1. We'll publish a security advisory
+2. Credit researchers (with permission)
+3. Detail the impact and mitigation steps
+4. Release patches for all supported versions
+
+## Contact
+
+- Security issues: Email **info@picpeak.app** or use [GitHub Private Vulnerability Reporting](https://github.com/PicPeak/picpeak/security/advisories/new)
+- General support: [GitHub Issues](https://github.com/PicPeak/picpeak/issues)
+
+Thank you for helping keep PicPeak and its users safe!

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/adminArchives.restoreCategories.test.js

@@ -1,498 +0,0 @@
-/**
- * Restoring an archive must put the photos back into their categories.
- *
- * The archive writer already persists `category_name` per photo in
- * `photos_manifest.json` — that is why the manifest exists, and the comment
- * above it says so: "(and category linkage) can't be derived from the
- * extracted files alone". The restore route then read only
- * `original_filename` from it and kept deriving the category from the ZIP's
- * first path segment.
- *
- * Archives store photos exactly as they sit on disk, so an event whose photos
- * live in the gallery root produces a FLAT zip. `path.dirname()` is '.' for
- * every entry, no category is resolved, and every restored photo lands with
- * `category_id = null` — silently, with a 200 response.
- *
- * These pin the manifest as the source of truth, with the directory as the
- * fallback that keeps foldered and legacy archives working.
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const express = require('express');
-const request = require('supertest');
-
-describe('archive restore restores categories (flat archives included)', () => {
-  let tmpDir; let db; let cleanup; let app; let storagePath;
-
-  beforeAll(async () => {
-    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-restore-cat-'));
-    storagePath = path.join(tmpDir, 'storage');
-    process.env.NODE_ENV = 'test';
-    process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'data', 'test.db');
-    process.env.STORAGE_PATH = storagePath;
-    await fs.promises.mkdir(path.dirname(process.env.TEST_DATABASE_PATH), { recursive: true });
-    await fs.promises.mkdir(path.join(storagePath, 'archives'), { 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(),
-    }));
-    jest.doMock('../../src/middleware/ownership', () => ({
-      requireEventOwnership: (_req, _res, next) => next(),
-    }));
-
-    ({ db, cleanup } = await require('./helpers/crmDb').bootCrmDb());
-    // bootCrmDb points STORAGE_PATH at its own tmp dir; follow it rather than
-    // fighting it, so the archives the tests write are where the route looks.
-    storagePath = process.env.STORAGE_PATH;
-    await fs.promises.mkdir(path.join(storagePath, 'archives'), { recursive: true });
-
-    app = express();
-    app.use(express.json());
-    app.use('/admin/archives', require('../../src/routes/adminArchives'));
-  }, 180000);
-
-  afterAll(async () => {
-    if (cleanup) await cleanup();
-    await fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
-  });
-
-  beforeEach(async () => {
-    await db('photos').del();
-    await db('photo_categories').del();
-    await db('events').del();
-  });
-
-  /** A one-pixel JPEG is enough; the route only stats the extracted file. */
-  const PIXEL = Buffer.from(
-    '/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a'
-    + 'HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAABAAAAAAAA'
-    + 'AAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AKp//2Q==',
-    'base64',
-  );
-
-  async function writeArchive(name, entries) {
-    // Required lazily: the suite calls jest.resetModules() in beforeAll, and
-    // archiver's readable-stream copy does not survive being split across the
-    // two module registries.
-    const archiver = require('archiver');
-    const archivePath = path.join(storagePath, 'archives', name);
-    await new Promise((resolve, reject) => {
-      const output = fs.createWriteStream(archivePath);
-      const zip = archiver('zip', { zlib: { level: 0 } });
-      output.on('close', resolve);
-      zip.on('error', reject);
-      zip.pipe(output);
-      for (const [entryName, buffer] of Object.entries(entries)) {
-        zip.append(buffer, { name: entryName });
-      }
-      zip.finalize();
-    });
-    return path.join('archives', name);
-  }
-
-  async function seedArchivedEvent(archiveRelPath, slug) {
-    const [row] = await db('events').insert({
-      slug,
-      event_type: 'wedding',
-      event_name: slug,
-      event_date: '2026-06-27',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: `${slug}-share`,
-      expires_at: new Date().toISOString(),
-      is_archived: 1,  // sqlite stores booleans as 0/1, see utils/dbCompat
-      archive_path: archiveRelPath,
-    }).returning('id');
-    return typeof row === 'object' ? row.id : row;
-  }
-
-  const categoryOf = async (filename) => {
-    const photo = await db('photos').where('filename', filename).first();
-    if (!photo || !photo.category_id) return null;
-    const category = await db('photo_categories').where('id', photo.category_id).first();
-    return category ? category.name : null;
-  };
-
-  it('takes the category from the manifest when the archive is flat', async () => {
-    // Exactly the shape a gallery-root event archives to: no directories.
-    const manifest = JSON.stringify([
-      { filename: 'a.jpg', original_filename: 'DSC_0001.jpg', category_name: 'Polterabend' },
-      { filename: 'b.jpg', original_filename: 'DSC_0002.jpg', category_name: 'Ceremony' },
-    ]);
-    const archiveRelPath = await writeArchive('flat.zip', {
-      'a.jpg': PIXEL,
-      'b.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(manifest, 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'flat-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    // The whole bug: both of these used to be null.
-    expect(await categoryOf('a.jpg')).toBe('Polterabend');
-    expect(await categoryOf('b.jpg')).toBe('Ceremony');
-  });
-
-  it('stores a real timestamp on restored photos, not "[object Object]"', async () => {
-    // The jest+sqlite landmine: a Date handed to knex inside jest stores as
-    // the literal string "[object Object]". Production writes ms-numbers and
-    // is unaffected, so this only ever corrupts what tests read back — which
-    // is how it survives unnoticed.
-    const archiveRelPath = await writeArchive('timestamp.zip', {
-      'individual/STAMPED.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'STAMPED.jpg', original_filename: 'STAMPED.jpg', category_name: 'Ceremony' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'timestamp-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    const photo = await db('photos').where({ event_id: eventId, filename: 'STAMPED.jpg' }).first();
-    expect(String(photo.uploaded_at)).not.toBe('[object Object]');
-    expect(Number.isNaN(new Date(photo.uploaded_at).getTime())).toBe(false);
-  });
-
-  it('reuses an existing category row instead of creating a duplicate', async () => {
-    const archiveRelPath = await writeArchive('reuse.zip', {
-      'c.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'c.jpg', original_filename: 'DSC_0003.jpg', category_name: 'Party' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'reuse-event');
-    await db('photo_categories').insert({
-      event_id: eventId, name: 'Party', slug: 'party', created_at: new Date(),
-    });
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    expect(await categoryOf('c.jpg')).toBe('Party');
-    const rows = await db('photo_categories').where({ event_id: eventId, name: 'Party' });
-    expect(rows).toHaveLength(1);
-  });
-
-  it('still falls back to the directory for legacy archives with no manifest', async () => {
-    // No manifest at all — the shape every archive had before the manifest
-    // landed. The directory is the only signal left, and it must keep working.
-    //
-    // `individual/` is what a REAL archive contains: entry names are the
-    // storage key minus `events/active/{slug}`, and that layout is
-    // `individual/` / `collages/`. Categories have never been directories, so
-    // the fallback invents a category with that name — not useful, but better
-    // than losing every category, and this pins what actually happens rather
-    // than a category-shaped folder no archive produces.
-    const archiveRelPath = await writeArchive('foldered.zip', {
-      'individual/d.jpg': PIXEL,
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'foldered-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    expect(await categoryOf('d.jpg')).toBe('individual');
-  });
-
-  it('reuses a GLOBAL category instead of cloning it into the event', async () => {
-    // Seeded categories (Ceremony, Reception, ...) have event_id NULL. An
-    // event-only lookup misses them, so the restore used to create a second
-    // "Ceremony" — and because is_global defaults to TRUE, that duplicate then
-    // appeared in every other event's category list.
-    const [g] = await db('photo_categories').insert({
-      event_id: null, name: 'Ceremony', slug: 'ceremony', is_global: true, created_at: new Date(),
-    }).returning('id');
-    const globalId = typeof g === 'object' ? g.id : g;
-
-    const archiveRelPath = await writeArchive('global.zip', {
-      'individual/gl.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'gl.jpg', original_filename: 'DSC_1.jpg', category_name: 'Ceremony' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'global-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    const photo = await db('photos').where('filename', 'gl.jpg').first();
-    expect(photo.category_id).toBe(globalId);
-    // No clone, global or otherwise.
-    const all = await db('photo_categories').where('name', 'Ceremony');
-    expect(all).toHaveLength(1);
-  });
-
-  it('does not create a GLOBAL category when it has to invent one', async () => {
-    // is_global defaults to true on this column, so an unqualified insert would
-    // leak a restore's category name into every gallery on the instance.
-    const archiveRelPath = await writeArchive('newcat.zip', {
-      'individual/nc.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'nc.jpg', original_filename: 'DSC_2.jpg', category_name: 'Polterabend' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'newcat-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    const created = await db('photo_categories').where('name', 'Polterabend').first();
-    expect(created.event_id).toBe(eventId);
-    expect(created.is_global === false || created.is_global === 0).toBe(true);
-  });
-
-  it('matches the manifest when the ZIP was written with original filenames', async () => {
-    // With general_use_original_filenames_for_downloads on at archive time,
-    // archiveService names entries after the ORIGINAL filename while the
-    // manifest stays keyed by photos.filename. Looking up the extracted
-    // basename missed every entry, so categories were lost on exactly those
-    // archives.
-    const archiveRelPath = await writeArchive('original-names.zip', {
-      'individual/DSC_4242.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'stored_9f8e7d.jpg', original_filename: 'DSC_4242.jpg', category_name: 'Drohne' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'original-names-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    expect(await categoryOf('DSC_4242.jpg')).toBe('Drohne');
-  });
-
-  it('prefers the event-scoped category when a global shares its name', async () => {
-    // The category API permits both. A single OR-lookup with .first() returned
-    // whichever the engine chose, so a photo could be reassigned to the global
-    // row and lose event-local settings such as allow_downloads.
-    const archiveRelPath = await writeArchive('collide.zip', {
-      'individual/co.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'co.jpg', original_filename: 'DSC_3.jpg', category_name: 'Reception' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'collide-event');
-
-    await db('photo_categories').insert({
-      event_id: null, name: 'Reception', slug: 'reception-global', is_global: true, created_at: new Date(),
-    });
-    const [own] = await db('photo_categories').insert({
-      event_id: eventId, name: 'Reception', slug: 'reception-own', is_global: false, created_at: new Date(),
-    }).returning('id');
-    const ownId = typeof own === 'object' ? own.id : own;
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    const photo = await db('photos').where('filename', 'co.jpg').first();
-    expect(photo.category_id).toBe(ownId);
-  });
-
-  it('matches a sanitized original filename, as the ZIP would have written it', async () => {
-    // archiveService runs original names through sanitizeForZipEntry() before
-    // writing the entry, so the emitted name differs from the manifest column.
-    const archiveRelPath = await writeArchive('sanitized.zip', {
-      'individual/od_dr_DSC_5.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'stored_abc.jpg', original_filename: 'od/dr/DSC_5.jpg', category_name: 'Strand' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'sanitized-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    expect(await categoryOf('od_dr_DSC_5.jpg')).toBe('Strand');
-  });
-
-  it('ignores a legacy event-owned row when falling back to globals', async () => {
-    // The bug fixed here left rows behind on upgraded instances: event-owned
-    // AND is_global true, because the column defaults true. Matching on the
-    // flag alone would let one event's leftover be adopted by another event's
-    // restore, tying photos to a category that vanishes with someone else's
-    // gallery.
-    const otherEventId = await seedArchivedEvent('archives/none.zip', 'legacy-owner-event');
-    await db('photo_categories').insert({
-      event_id: otherEventId, name: 'Sunset', slug: 'sunset-legacy',
-      is_global: true, created_at: new Date(),
-    });
-
-    const archiveRelPath = await writeArchive('legacy-global.zip', {
-      'individual/lg.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'lg.jpg', original_filename: 'DSC_6.jpg', category_name: 'Sunset' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'legacy-global-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    const photo = await db('photos').where('filename', 'lg.jpg').first();
-    const cat = await db('photo_categories').where('id', photo.category_id).first();
-    // Its own row, not the other event's leftover.
-    expect(cat.event_id).toBe(eventId);
-  });
-
-  it('drops an ambiguous original-name alias rather than guessing', async () => {
-    // Two photos in different ZIP folders can share an original basename;
-    // archiveService treats the paths as distinct and suffixes neither. Both
-    // would collapse onto one alias, and whichever won would hand the other
-    // photo someone else's category.
-    const archiveRelPath = await writeArchive('ambiguous.zip', {
-      'individual/SHARED.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'a_stored.jpg', original_filename: 'SHARED.jpg', category_name: 'Alpha' },
-        { filename: 'b_stored.jpg', original_filename: 'SHARED.jpg', category_name: 'Beta' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'ambiguous-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    // Falls back to the directory rather than picking Alpha or Beta at random.
-    expect(await categoryOf('SHARED.jpg')).toBe('individual');
-    for (const name of ['Alpha', 'Beta']) {
-      expect(await db('photo_categories').where({ event_id: eventId, name }).first()).toBeFalsy();
-    }
-  });
-
-  it('honours a manifest that says UNCATEGORIZED, instead of inventing one from the directory', async () => {
-    // The case the manifest-first change was for. A real archive puts every
-    // photo under `individual/`, so a photo the manifest records as having no
-    // category used to come back filed under a category called "individual" —
-    // the manifest being authoritative for "category X" but not for "none".
-    const manifest = JSON.stringify([
-      { filename: 'u.jpg', original_filename: 'DSC_7000.jpg', category_name: null },
-    ]);
-    const archiveRelPath = await writeArchive('uncategorized.zip', {
-      'individual/u.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(manifest, 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'uncategorized-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    expect(await categoryOf('u.jpg')).toBeNull();
-    // And no junk category row was created as a side effect.
-    const rows = await db('photo_categories').where({ event_id: eventId });
-    expect(rows).toHaveLength(0);
-  });
-
-  it('drops a canonical filename that two photos claim, rather than guessing', async () => {
-    // photos.filename is not unique within an event: s3AutoImporter takes
-    // path.basename(entry.key) and dedupes by path, so two imported files in
-    // different subfolders both land as IMG_1234.jpg. Both ZIP entries reduce
-    // to the same basename at restore, so keeping the last row seen would give
-    // one photo the other's category.
-    const archiveRelPath = await writeArchive('dup-canonical.zip', {
-      'individual/IMG_1234.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'IMG_1234.jpg', original_filename: 'a.jpg', category_name: 'Alpha' },
-        { filename: 'IMG_1234.jpg', original_filename: 'b.jpg', category_name: 'Beta' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'dup-canonical-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    expect(await categoryOf('IMG_1234.jpg')).toBe('individual');
-    for (const name of ['Alpha', 'Beta']) {
-      expect(await db('photo_categories').where({ event_id: eventId, name }).first()).toBeFalsy();
-    }
-  });
-
-  it("drops a name that one row owns canonically and another claims as an alias", async () => {
-    // Undecidable: with original-filename archiving ON the ZIP entry under
-    // this name is the ALIAS owner's file, with it OFF it is the canonical
-    // owner's, and the manifest does not record which mode was used. The
-    // point of the two-pass split is that this now resolves the same way
-    // every run — the archive query has no ORDER BY, so it used to be a coin
-    // flip between dropping the name and overwriting it.
-    const archiveRelPath = await writeArchive('alias-vs-canonical.zip', {
-      'individual/CANON.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'CANON.jpg', original_filename: 'unrelated.jpg', category_name: 'Canonical' },
-        { filename: 'other_stored.jpg', original_filename: 'CANON.jpg', category_name: 'Aliased' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'alias-vs-canonical-event');
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    // Falls back to the directory rather than guessing either row.
-    expect(await categoryOf('CANON.jpg')).toBe('individual');
-    for (const name of ['Canonical', 'Aliased']) {
-      expect(await db('photo_categories').where({ event_id: eventId, name }).first()).toBeFalsy();
-    }
-  });
-
-  it('picks the lowest id and warns when two categories share a name', async () => {
-    // Allowed: two event-scoped categories with the same display name and
-    // different slugs. .first() used to pick either, so a re-run could move
-    // photos between them and inherit the wrong allow_downloads.
-    const archiveRelPath = await writeArchive('dupe-category.zip', {
-      'individual/DUPE.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'DUPE.jpg', original_filename: 'DUPE.jpg', category_name: 'Ceremony' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'dupe-category-event');
-
-    const [first] = await db('photo_categories').insert({
-      name: 'Ceremony', slug: 'ceremony-a', is_global: 0, event_id: eventId,
-    }).returning('id');
-    await db('photo_categories').insert({
-      name: 'Ceremony', slug: 'ceremony-b', is_global: 0, event_id: eventId,
-    });
-    const firstId = typeof first === 'object' ? first.id : first;
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    // Stable, not arbitrary: the same run twice lands on the same row.
-    const photo = await db('photos').where({ event_id: eventId, filename: 'DUPE.jpg' }).first();
-    expect(photo.category_id).toBe(firstId);
-    // And no third "Ceremony" was invented.
-    expect((await db('photo_categories').where({ event_id: eventId, name: 'Ceremony' })).length)
-      .toBe(2);
-  });
-
-  it('does not invent a category for a photo row that already exists', async () => {
-    // archiveEvent retains photo rows, so a restore can skip every insert.
-    // Resolving categories before that check created one from the stale
-    // manifest name that nothing then used — renaming a category while its
-    // event was archived left the old name behind as an empty duplicate.
-    const archiveRelPath = await writeArchive('existing-rows.zip', {
-      'individual/KEPT.jpg': PIXEL,
-      'photos_manifest.json': Buffer.from(JSON.stringify([
-        { filename: 'KEPT.jpg', original_filename: 'KEPT.jpg', category_name: 'OldName' },
-      ]), 'utf8'),
-    });
-    const eventId = await seedArchivedEvent(archiveRelPath, 'existing-rows-event');
-    await db('photos').insert({
-      event_id: eventId, filename: 'KEPT.jpg', path: 'whatever/KEPT.jpg', type: 'jpg',
-      uploaded_at: new Date().toISOString(),
-    });
-
-    const res = await request(app).post(`/admin/archives/${eventId}/restore`).send({});
-    expect(res.status).toBe(200);
-
-    expect(await db('photo_categories').where({ event_id: eventId, name: 'OldName' }).first())
-      .toBeFalsy();
-  });
-
-});

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/businessProfileLogoUpload.test.js

@@ -1,195 +0,0 @@
-/**
- * POST /api/admin/business-profile/logo and PUT /api/admin/business-profile
- * — GHSA-6wrv-9pr4-hhmw regression coverage.
- *
- * The upload route used to take the stored file extension straight from
- * the client-supplied filename and only checked `file.mimetype` against an
- * allowlist — a file could declare an image MIME type while carrying a
- * `.html`/`.js` extension and arbitrary content, land in the same-origin
- * `/uploads/logos` static mount, and execute as script. The mass-assignable
- * `logoPath` field on PUT compounded it: an attacker could point the
- * "logo" at any other uploaded file.
- *
- * These tests pin:
- *   (a) a MIME/extension mismatch is rejected at upload,
- *   (b) the extension actually written to disk always matches the
- *       validated MIME type, never the client-supplied filename,
- *   (c) legitimate PNG/JPEG/SVG uploads still succeed,
- *   (d) `logoPath` on PUT cannot be set to an arbitrary string pointing at
- *       another file, only to a path the upload route itself produced.
- *
- * Defense-in-depth (not a re-opening of the above): fileFilter only pairs
- * the claimed MIME type against the extension — it can't see the bytes,
- * since it runs before multer finishes writing the stream to disk. A file
- * whose declared MIME/extension pair is valid but whose actual content
- * doesn't match (e.g. a PNG-declared upload that isn't really a PNG) is
- * now caught by validateFileContent() (magic-number check) after multer
- * writes it, closing the gap where declared-vs-actual content diverges.
- */
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-bplogo-test-'));
-process.env.NODE_ENV = 'test';
-process.env.TEST_DATABASE_PATH = path.join(tmpDir, 'db.sqlite');
-process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
-fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'bplogo-route-test-secret';
-
-const request = require('supertest');
-const {
-  bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken, buildRouteApp,
-} = require('./helpers/crmDb');
-
-// Real magic-number-prefixed payloads, for content-sniffing to accept.
-const REAL_PNG_BYTES = Buffer.concat([
-  Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]),
-  Buffer.from('not a real png body, but the header is real'),
-]);
-const REAL_JPEG_BYTES = Buffer.concat([
-  Buffer.from([0xFF, 0xD8, 0xFF]),
-  Buffer.from('not a real jpeg body, but the header is real'),
-]);
-
-describe('business profile — logo upload content/extension validation', () => {
-  let db;
-  let cleanup;
-  let app;
-  let token;
-
-  const uploadLogo = (buffer, filename, mimetype) => request(app)
-    .post('/api/admin/business-profile/logo')
-    .set('Authorization', `Bearer ${token}`)
-    .attach('logo', buffer, { filename, contentType: mimetype });
-
-  const put = (payload) => request(app)
-    .put('/api/admin/business-profile')
-    .set('Authorization', `Bearer ${token}`)
-    .send(payload);
-
-  const get = () => request(app)
-    .get('/api/admin/business-profile')
-    .set('Authorization', `Bearer ${token}`);
-
-  const profileOf = (res) => (res.body.data || res.body).profile;
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    const { adminId } = await seedMinimal(db);
-    await assignAdminRole(db, adminId, 'super_admin');
-    token = mintAdminToken(adminId);
-    app = buildRouteApp('/api/admin/business-profile', require('../../src/routes/adminBusinessProfile'));
-  }, 120000);
-
-  afterAll(async () => {
-    if (cleanup) await cleanup();
-  });
-
-  // fileFilter rejections surface via Express's generic error handler
-  // (the pre-existing behaviour of every sibling logo/favicon upload
-  // route in this codebase — none of them special-case multer's
-  // fileFilter `Error` into a 400 either), so the status code itself
-  // can be 400 or 500 depending on environment. What actually matters
-  // for GHSA-6wrv-9pr4-hhmw is that the request never succeeds and
-  // nothing with the dangerous extension is ever written to disk.
-  const logosDirFiles = () => {
-    const logosDir = path.join(process.env.STORAGE_PATH, 'uploads', 'logos');
-    return fs.existsSync(logosDir) ? fs.readdirSync(logosDir) : [];
-  };
-
-  it('rejects an HTML/script payload disguised as an image via mismatched extension', async () => {
-    const evil = Buffer.from('<script>alert(document.domain)</script>');
-    const res = await uploadLogo(evil, 'evil.html', 'image/svg+xml');
-    expect(res.status).not.toBe(200);
-    expect(logosDirFiles().some((f) => f.endsWith('.html'))).toBe(false);
-  });
-
-  it('rejects a .js file disguised with an image MIME type', async () => {
-    const evil = Buffer.from('alert(1)');
-    const res = await uploadLogo(evil, 'evil.js', 'image/png');
-    expect(res.status).not.toBe(200);
-    expect(logosDirFiles().some((f) => f.endsWith('.js'))).toBe(false);
-  });
-
-  it('rejects a disallowed MIME type outright', async () => {
-    const res = await uploadLogo(Buffer.from('whatever'), 'file.pdf', 'application/pdf');
-    expect(res.status).not.toBe(200);
-    expect(logosDirFiles().some((f) => f.endsWith('.pdf'))).toBe(false);
-  });
-
-  it('accepts a legitimate PNG upload and stores it with a .png extension', async () => {
-    const res = await uploadLogo(REAL_PNG_BYTES, 'logo.png', 'image/png');
-    expect(res.status).toBe(200);
-    const logoPath = (res.body.data || res.body).logoPath;
-    expect(logoPath).toMatch(/^\/uploads\/logos\/pdf-logo-\d+\.png$/);
-
-    const onDisk = path.join(process.env.STORAGE_PATH, logoPath.replace(/^\//, ''));
-    expect(fs.existsSync(onDisk)).toBe(true);
-
-    expect(profileOf(await get()).logoPath).toBe(logoPath);
-  });
-
-  it('accepts a legitimate JPEG upload and stores it with a .jpg extension', async () => {
-    const res = await uploadLogo(REAL_JPEG_BYTES, 'logo.jpg', 'image/jpeg');
-    expect(res.status).toBe(200);
-    const logoPath = (res.body.data || res.body).logoPath;
-    expect(logoPath).toMatch(/^\/uploads\/logos\/pdf-logo-\d+\.jpg$/);
-  });
-
-  it('rejects a PNG-declared upload whose bytes are not actually a PNG, and leaves nothing on disk', async () => {
-    const before = logosDirFiles();
-    const res = await uploadLogo(Buffer.from('totally not a png'), 'logo.png', 'image/png');
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/content does not match/i);
-
-    // No new file left behind: the rejected upload's own file was cleaned
-    // up, and every other file on disk (if any) is unchanged.
-    expect(logosDirFiles()).toEqual(before);
-  });
-
-  it('accepts a legitimate SVG upload and always stores it with a .svg extension, even under a spoofed filename', async () => {
-    const svg = Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"><rect width="1" height="1"/></svg>');
-    // Client-declared filename ext is .svg here to pass validateFileType
-    // (mismatched ext is covered by the rejection tests above); the point
-    // of this test is that the ON-DISK extension comes from the MIME type
-    // lookup table, not path.extname(originalname).
-    const res = await uploadLogo(svg, 'vector-logo.svg', 'image/svg+xml');
-    expect(res.status).toBe(200);
-    const logoPath = (res.body.data || res.body).logoPath;
-    expect(logoPath).toMatch(/^\/uploads\/logos\/pdf-logo-\d+\.svg$/);
-  });
-
-  it('rejects logoPath on PUT set to an arbitrary string pointing at another file', async () => {
-    const before = profileOf(await get()).logoPath;
-
-    const res = await put({ logoPath: '/uploads/logos/cms-somepage-1234.png' });
-    expect(res.status).toBe(400);
-
-    expect(profileOf(await get()).logoPath).toBe(before);
-  });
-
-  it('rejects logoPath on PUT with a path-traversal payload', async () => {
-    const res = await put({ logoPath: '/uploads/logos/../../../../etc/passwd' });
-    expect(res.status).toBe(400);
-  });
-
-  it('accepts logoPath on PUT when it matches the pattern this route itself writes', async () => {
-    const upload = await uploadLogo(REAL_PNG_BYTES, 'logo2.png', 'image/png');
-    const uploadedPath = (upload.body.data || upload.body).logoPath;
-
-    // Round-trip: PUT-ing back the exact value the upload endpoint
-    // returned (what the frontend's generic profile save does) must
-    // keep working.
-    const res = await put({ logoPath: uploadedPath });
-    expect(res.status).toBe(200);
-    expect(profileOf(await get()).logoPath).toBe(uploadedPath);
-  });
-
-  it('still allows clearing logoPath with an empty string', async () => {
-    const res = await put({ logoPath: '' });
-    expect(res.status).toBe(200);
-    expect(profileOf(await get()).logoPath).toBe('');
-  });
-});

backend/__tests__/integration/captureDateBackfill.test.js

@@ -1,227 +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);
-    // Read but not written, so it is accounted for rather than dropped.
-    expect(done.body.lastResult.skipped).toBe(1);
-  });
-
-  it('does not date a row whose file was replaced while it was reading (#1201)', async () => {
-    // replacePhoto swaps a NEW file under an existing row and rewrites
-    // path/filename (reachable from replace_by_name). The replacement carries
-    // no date of its own, so captured_at is still NULL and the whereNull guard
-    // alone would let the previous file's EXIF date land on it. The write is
-    // fenced on the identity that was read, so the row is skipped instead —
-    // and not counted as updated either.
-    const { photoId } = await seed({ relpath: 'orig.jpg', exifIso: '2026-06-03T09:00:00Z' });
-
-    const res = await request(app).post('/api/admin/photos/repair-capture-dates');
-    expect(res.body.count).toBe(1);
-    // Simulate the replacement landing before the loop writes.
-    await db('photos').where({ id: photoId })
-      .update({ path: 'capfill/replaced.jpg', filename: 'replaced.jpg' });
-    const done = await settle();
-
-    expect((await db('photos').where({ id: photoId }).first()).captured_at).toBeNull();
-    expect(done.body.lastResult.success).toBe(0);
-    // Not an error and not "no EXIF" — the date was found, another writer just
-    // got there first. It stays in the backlog for the next run.
-    expect(done.body.lastResult).toMatchObject({ noExif: 0, failed: 0, skipped: 1 });
-  });
-});

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/faceAutoCategories.test.js

@@ -0,0 +1,217 @@
+/**
+ * Auto-category rule engine (#1074 phase 3).
+ *
+ * The rules themselves are simple enough to read. What needs testing is the
+ * promise around them: this engine may only ever fill an EMPTY category, and
+ * everything it touches must be reversible. A photographer's own assignment
+ * is a decision; this is a heuristic, and the heuristic never wins.
+ */
+
+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-autocat-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'autocat-test-secret';
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup; let engine;
+
+async function seedEvent(slug) {
+  const [row] = await db('events').insert({
+    slug,
+    event_type: 'wedding',
+    event_name: slug,
+    event_date: '2026-01-01',
+    host_email: 'h@example.com',
+    admin_email: 'a@example.com',
+    password_hash: 'x',
+    share_link: `${slug}-share`,
+    expires_at: new Date().toISOString(),
+    face_recognition_enabled: true,
+  }).returning('id');
+  return typeof row === 'object' ? row.id : row;
+}
+
+/** A scanned photo with `faceCount` faces, each `faceSide` px square. */
+async function addScannedPhoto(eventId, faceCount, { faceSide = 400, categoryId = null } = {}) {
+  const [p] = await db('photos').insert({
+    event_id: eventId,
+    filename: `${Math.random()}.jpg`,
+    path: '/tmp/x.jpg',
+    type: 'individual',
+    width: 1000,
+    height: 1000,
+    processing_status: 'complete',
+    face_status: 'done',
+    face_count: faceCount,
+    category_id: categoryId,
+  }).returning('id');
+  const photoId = typeof p === 'object' ? p.id : p;
+
+  for (let i = 0; i < faceCount; i++) {
+    await db('photo_faces').insert({
+      photo_id: photoId,
+      event_id: eventId,
+      bbox_x: 10, bbox_y: 10, bbox_w: faceSide, bbox_h: faceSide,
+      det_score: 0.95,
+      model_version: 'test-v1',
+      created_at: new Date().toISOString(),
+    });
+  }
+  return photoId;
+}
+
+async function enable(on) {
+  const existing = await db('app_settings')
+    .where('setting_key', 'face_auto_categorize_enabled').first();
+  if (existing) {
+    await db('app_settings')
+      .where('setting_key', 'face_auto_categorize_enabled')
+      .update({ setting_value: JSON.stringify(on) });
+  }
+}
+
+async function categoryOf(photoId) {
+  const photo = await db('photos').where({ id: photoId }).first();
+  if (!photo.category_id) return null;
+  const cat = await db('photo_categories').where({ id: photo.category_id }).first();
+  return cat?.slug ?? null;
+}
+
+describe('faceAutoCategories (#1074 phase 3)', () => {
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    engine = require('../../src/services/faceAutoCategories');
+    await enable(true);
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  describe('rules', () => {
+    it('sorts by face count, and by face size for portraits', async () => {
+      const eventId = await seedEvent('rules');
+      // 400px face in a 1000x1000 frame = 16% of the frame, over the 8% floor.
+      const portrait = await addScannedPhoto(eventId, 1, { faceSide: 400 });
+      const details = await addScannedPhoto(eventId, 0);
+      const small = await addScannedPhoto(eventId, 3);
+      const group = await addScannedPhoto(eventId, 9);
+
+      await engine.categorizeEvent(eventId);
+
+      expect(await categoryOf(details)).toBe('details');
+      expect(await categoryOf(portrait)).toBe('portraits');
+      expect(await categoryOf(small)).toBe('small-groups');
+      expect(await categoryOf(group)).toBe('groups');
+    });
+
+    it('does not call a distant single face a portrait', async () => {
+      // One person in a wide landscape is not a portrait of them. 60px in a
+      // 1000x1000 frame is 0.36% — far below the 8% floor.
+      const eventId = await seedEvent('small-face');
+      const distant = await addScannedPhoto(eventId, 1, { faceSide: 60 });
+
+      await engine.categorizeEvent(eventId);
+
+      expect(await categoryOf(distant)).toBeNull();
+    });
+
+    it('ignores photos that have not been scanned', async () => {
+      const eventId = await seedEvent('unscanned');
+      const [p] = await db('photos').insert({
+        event_id: eventId, filename: 'u.jpg', path: '/tmp/u.jpg', type: 'individual',
+        processing_status: 'complete', face_status: 'pending',
+      }).returning('id');
+      const photoId = typeof p === 'object' ? p.id : p;
+
+      await engine.categorizeEvent(eventId);
+      expect(await categoryOf(photoId)).toBeNull();
+    });
+  });
+
+  describe('the promise', () => {
+    it('NEVER overwrites a category a person chose', async () => {
+      // The single most important behaviour in this file.
+      const eventId = await seedEvent('no-overwrite');
+      const [c] = await db('photo_categories').insert({
+        name: 'Ceremony', slug: 'ceremony', is_global: false, event_id: eventId,
+        created_at: new Date().toISOString(),
+      }).returning('id');
+      const ceremonyId = typeof c === 'object' ? c.id : c;
+
+      // 9 faces — the rules would call this "groups" if they were allowed to.
+      const claimed = await addScannedPhoto(eventId, 9, { categoryId: ceremonyId });
+
+      await engine.categorizeEvent(eventId);
+
+      expect(await categoryOf(claimed)).toBe('ceremony');
+      const row = await db('photos').where({ id: claimed }).first();
+      expect(row.auto_categorized).toBeFalsy();
+    });
+
+    it('marks only what it assigned, so undo is exact', async () => {
+      const eventId = await seedEvent('undo');
+      const [c] = await db('photo_categories').insert({
+        name: 'Ceremony', slug: 'ceremony-2', is_global: false, event_id: eventId,
+        created_at: new Date().toISOString(),
+      }).returning('id');
+      const ceremonyId = typeof c === 'object' ? c.id : c;
+
+      const manual = await addScannedPhoto(eventId, 4, { categoryId: ceremonyId });
+      const auto = await addScannedPhoto(eventId, 4);
+
+      await engine.categorizeEvent(eventId);
+      expect(await categoryOf(auto)).toBe('small-groups');
+
+      const result = await engine.undoEvent(eventId);
+
+      expect(result.cleared).toBe(1);
+      // The automatic one is cleared...
+      expect(await categoryOf(auto)).toBeNull();
+      // ...and the photographer's own choice survives untouched.
+      expect(await categoryOf(manual)).toBe('ceremony-2');
+    });
+
+    it('is a no-op while the setting is off', async () => {
+      const eventId = await seedEvent('disabled');
+      const photoId = await addScannedPhoto(eventId, 0);
+
+      await enable(false);
+      const result = await engine.categorizeEvent(eventId);
+      await enable(true);
+
+      expect(result.skipped).toBe(true);
+      expect(await categoryOf(photoId)).toBeNull();
+    });
+
+    it('is idempotent — a second run assigns nothing new', async () => {
+      const eventId = await seedEvent('idempotent');
+      await addScannedPhoto(eventId, 0);
+      await addScannedPhoto(eventId, 7);
+
+      const first = await engine.categorizeEvent(eventId);
+      const second = await engine.categorizeEvent(eventId);
+
+      expect(first.assigned).toBe(2);
+      expect(second.assigned).toBe(0);
+    });
+
+    it('reuses one category per slug rather than creating duplicates', async () => {
+      const eventId = await seedEvent('reuse');
+      await addScannedPhoto(eventId, 0);
+      await addScannedPhoto(eventId, 0);
+      await addScannedPhoto(eventId, 0);
+
+      await engine.categorizeEvent(eventId);
+
+      const details = await db('photo_categories')
+        .where({ slug: 'details' })
+        .where(function () { this.where('event_id', eventId).orWhere('is_global', true); });
+      expect(details).toHaveLength(1);
+    });
+  });
+});

backend/__tests__/integration/faceClustering.test.js

@@ -0,0 +1,325 @@
+/**
+ * Clustering engine (#1074).
+ *
+ * Uses synthetic embeddings with known identities rather than real faces: the
+ * question here is whether the ALGORITHM groups vectors correctly, which is
+ * separable from whether the model produces good vectors. Model quality is
+ * the spike's job.
+ */
+
+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-faceclust-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'faceclust-test-secret';
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup; let clustering;
+
+/** Deterministic unit vector for identity `id`, jittered by `variant`. */
+function makeEmbedding(id, variant = 0, dim = 64) {
+  const vec = new Float32Array(dim);
+  for (let i = 0; i < dim; i++) {
+    vec[i] = Math.sin((i + 1) * (id + 1) * 0.7) + variant * 0.02 * Math.cos(i * 3.1);
+  }
+  let norm = 0;
+  for (let i = 0; i < dim; i++) norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  for (let i = 0; i < dim; i++) vec[i] /= norm;
+  return vec;
+}
+
+async function seedEvent(slug) {
+  const [row] = await db('events').insert({
+    slug,
+    event_type: 'wedding',
+    event_name: slug,
+    event_date: '2026-01-01',
+    host_email: 'h@example.com',
+    admin_email: 'a@example.com',
+    password_hash: 'x',
+    share_link: `${slug}-share`,
+    expires_at: new Date().toISOString(),
+  }).returning('id');
+  return typeof row === 'object' ? row.id : row;
+}
+
+async function insertFace(eventId, embedding, overrides = {}) {
+  const [p] = await db('photos').insert({
+    event_id: eventId,
+    filename: `${Math.random()}.jpg`,
+    path: '/tmp/x.jpg',
+    type: 'individual',
+  }).returning('id');
+  const photoId = typeof p === 'object' ? p.id : p;
+
+  const row = {
+    photo_id: photoId,
+    event_id: eventId,
+    bbox_x: 0, bbox_y: 0, bbox_w: 200, bbox_h: 200,
+    det_score: 0.99,
+    embedding: clustering.packEmbedding(embedding),
+    model_version: 'test-v1',
+    created_at: new Date().toISOString(),
+    ...overrides,
+  };
+  const [f] = await db('photo_faces').insert(row).returning('id');
+  return { ...row, id: typeof f === 'object' ? f.id : f };
+}
+
+describe('faceClustering (#1074)', () => {
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    clustering = require('../../src/services/faceClustering');
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  describe('embedding round-trip', () => {
+    it('survives pack/unpack through the BLOB column exactly', async () => {
+      const original = makeEmbedding(1);
+      const eventId = await seedEvent('roundtrip');
+      const face = await insertFace(eventId, original);
+
+      const stored = await db('photo_faces').where({ id: face.id }).first();
+      const restored = clustering.unpackEmbedding(stored.embedding);
+
+      expect(restored).toHaveLength(original.length);
+      for (let i = 0; i < original.length; i++) {
+        expect(restored[i]).toBeCloseTo(original[i], 6);
+      }
+    });
+
+    it('returns null for a corrupt blob rather than throwing', () => {
+      expect(clustering.unpackEmbedding(Buffer.from([1, 2, 3]))).toBeNull();
+      expect(clustering.unpackEmbedding(null)).toBeNull();
+    });
+  });
+
+  describe('assignment', () => {
+    it('groups the same identity and separates different ones', async () => {
+      const eventId = await seedEvent('grouping');
+      const faces = [];
+      // Three identities, four shots each, interleaved so assignment order
+      // is not conveniently grouped.
+      for (let variant = 0; variant < 4; variant++) {
+        for (const identity of [1, 2, 3]) {
+          faces.push(await insertFace(eventId, makeEmbedding(identity, variant)));
+        }
+      }
+
+      await clustering.assignFaces(eventId, faces);
+
+      const people = await db('event_people').where({ event_id: eventId });
+      expect(people).toHaveLength(3);
+
+      // Every face of one identity must share a person id.
+      const rows = await db('photo_faces').where({ event_id: eventId }).select('id', 'person_id');
+      const byPerson = new Map();
+      for (const r of rows) {
+        byPerson.set(r.person_id, (byPerson.get(r.person_id) || 0) + 1);
+      }
+      expect([...byPerson.values()].sort()).toEqual([4, 4, 4]);
+    });
+
+    it('leaves low-quality faces unassigned instead of spawning junk people', async () => {
+      const eventId = await seedEvent('quality-floor');
+      const good = await insertFace(eventId, makeEmbedding(5));
+      // Tiny bbox — below the 40px floor.
+      const tiny = await insertFace(eventId, makeEmbedding(6), { bbox_w: 12, bbox_h: 12 });
+      // Weak detection score.
+      const weak = await insertFace(eventId, makeEmbedding(7), { det_score: 0.2 });
+
+      await clustering.assignFaces(eventId, [good, tiny, weak]);
+
+      const rows = await db('photo_faces')
+        .whereIn('id', [good.id, tiny.id, weak.id])
+        .select('id', 'person_id');
+      const map = Object.fromEntries(rows.map((r) => [r.id, r.person_id]));
+
+      expect(map[good.id]).not.toBeNull();
+      // Still stored — they show in "this photo contains" — just unassigned.
+      expect(map[tiny.id]).toBeNull();
+      expect(map[weak.id]).toBeNull();
+      expect(await db('event_people').where({ event_id: eventId })).toHaveLength(1);
+    });
+
+    it('never mixes embedding spaces from different model versions', async () => {
+      const eventId = await seedEvent('model-version');
+      const a = await insertFace(eventId, makeEmbedding(9), { model_version: 'v1' });
+      await clustering.assignFaces(eventId, [a]);
+
+      // Same vector, different model. Comparable numerically, meaningless
+      // semantically — it must NOT join the v1 cluster.
+      const b = await insertFace(eventId, makeEmbedding(9), { model_version: 'v2' });
+      await clustering.assignFaces(eventId, [b]);
+
+      const people = await db('event_people').where({ event_id: eventId });
+      expect(people).toHaveLength(2);
+    });
+  });
+
+  describe('merge and split', () => {
+    it('merge moves every face and removes the source person', async () => {
+      const eventId = await seedEvent('merge');
+      const f1 = await insertFace(eventId, makeEmbedding(11));
+      const f2 = await insertFace(eventId, makeEmbedding(21));
+      await clustering.assignFaces(eventId, [f1, f2]);
+
+      const people = await db('event_people').where({ event_id: eventId }).orderBy('id');
+      expect(people).toHaveLength(2);
+
+      await clustering.mergePeople(eventId, [people[1].id], people[0].id);
+
+      expect(await db('event_people').where({ event_id: eventId })).toHaveLength(1);
+      const remaining = await db('event_people').where({ event_id: eventId }).first();
+      expect(remaining.face_count_total).toBe(2);
+      const orphaned = await db('photo_faces')
+        .where({ event_id: eventId }).whereNull('person_id');
+      expect(orphaned).toHaveLength(0);
+    });
+
+    it('split pulls the named faces into a new person', async () => {
+      const eventId = await seedEvent('split');
+      const faces = [];
+      for (let v = 0; v < 4; v++) faces.push(await insertFace(eventId, makeEmbedding(13, v)));
+      await clustering.assignFaces(eventId, faces);
+
+      const person = await db('event_people').where({ event_id: eventId }).first();
+      expect(person.face_count_total).toBe(4);
+
+      const newId = await clustering.splitPerson(eventId, person.id, [faces[0].id, faces[1].id]);
+      expect(newId).toBeTruthy();
+
+      const original = await db('event_people').where({ id: person.id }).first();
+      const created = await db('event_people').where({ id: newId }).first();
+      expect(original.face_count_total).toBe(2);
+      expect(created.face_count_total).toBe(2);
+    });
+
+    it('deletes a person left with no faces rather than keeping a ghost', async () => {
+      const eventId = await seedEvent('empty-person');
+      const f = await insertFace(eventId, makeEmbedding(15));
+      await clustering.assignFaces(eventId, [f]);
+      const person = await db('event_people').where({ event_id: eventId }).first();
+
+      await db('photo_faces').where({ id: f.id }).update({ person_id: null });
+      await clustering.recomputeCentroid(person.id);
+
+      expect(await db('event_people').where({ id: person.id }).first()).toBeUndefined();
+    });
+  });
+
+  describe('regressions from external review', () => {
+    it('merge carries a name and suppression onto the survivor', async () => {
+      // A merge used to move the faces and delete the source outright, so a
+      // photographer-entered name vanished and a person they had hidden came
+      // back guest-visible.
+      const eventId = await seedEvent('merge-metadata');
+      const a = await insertFace(eventId, makeEmbedding(61));
+      const b = await insertFace(eventId, makeEmbedding(62));
+      await clustering.assignFaces(eventId, [a, b]);
+
+      const [p1, p2] = await db('event_people').where({ event_id: eventId }).orderBy('id');
+      // Target is unnamed and visible; the SOURCE carries the human state.
+      await db('event_people').where({ id: p2.id }).update({ label: 'Anna', is_hidden: true });
+
+      await clustering.mergePeople(eventId, [p2.id], p1.id);
+
+      const survivor = await db('event_people').where({ id: p1.id }).first();
+      expect(survivor.label).toBe('Anna');
+      expect(!!survivor.is_hidden).toBe(true);
+    });
+
+    it('recluster keeps hidden/ignored on people that were never named', async () => {
+      // The old query remembered only rows with a label, so a suppressed
+      // bystander came back visible after one "Re-group people".
+      const eventId = await seedEvent('recluster-suppression');
+      const faces = [];
+      for (let v = 0; v < 3; v++) faces.push(await insertFace(eventId, makeEmbedding(71, v)));
+      await clustering.assignFaces(eventId, faces);
+
+      const person = await db('event_people').where({ event_id: eventId }).first();
+      expect(person.label).toBeNull();
+      await db('event_people').where({ id: person.id }).update({ is_ignored: true });
+
+      await clustering.recluster(eventId);
+
+      const after = await db('event_people').where({ event_id: eventId });
+      expect(after.length).toBeGreaterThan(0);
+      expect(after.every((p) => !!p.is_ignored)).toBe(true);
+    });
+  });
+
+  describe('recluster', () => {
+    it('re-derives clusters and preserves photographer-assigned names', async () => {
+      // This is the property that makes re-clustering safe to offer as a
+      // button: without it, one click silently discards every typed name.
+      const eventId = await seedEvent('recluster');
+      const faces = [];
+      for (let v = 0; v < 3; v++) {
+        faces.push(await insertFace(eventId, makeEmbedding(31, v)));
+        faces.push(await insertFace(eventId, makeEmbedding(32, v)));
+      }
+      await clustering.assignFaces(eventId, faces);
+
+      const people = await db('event_people').where({ event_id: eventId }).orderBy('id');
+      expect(people).toHaveLength(2);
+      await db('event_people').where({ id: people[0].id }).update({ label: 'Anna' });
+      await db('event_people').where({ id: people[1].id }).update({ label: 'Ben' });
+
+      const count = await clustering.recluster(eventId);
+      expect(count).toBe(2);
+
+      const after = await db('event_people').where({ event_id: eventId });
+      const labels = after.map((p) => p.label).filter(Boolean).sort();
+      expect(labels).toEqual(['Anna', 'Ben']);
+    });
+
+    it('is stable across repeated runs', async () => {
+      const eventId = await seedEvent('recluster-stable');
+      const faces = [];
+      for (let v = 0; v < 3; v++) {
+        for (const id of [41, 42]) faces.push(await insertFace(eventId, makeEmbedding(id, v)));
+      }
+      await clustering.assignFaces(eventId, faces);
+
+      const first = await clustering.recluster(eventId);
+      const second = await clustering.recluster(eventId);
+      expect(second).toBe(first);
+    });
+  });
+
+  describe('consolidate', () => {
+    it('refuses to merge two people the photographer named differently', async () => {
+      // A human assertion this heuristic does not get to overrule.
+      const eventId = await seedEvent('consolidate-labels');
+      const a = await insertFace(eventId, makeEmbedding(51));
+      await clustering.assignFaces(eventId, [a]);
+      const first = await db('event_people').where({ event_id: eventId }).first();
+
+      // A near-identical centroid that would otherwise merge.
+      const [inserted] = await db('event_people').insert({
+        event_id: eventId,
+        centroid: clustering.packEmbedding(makeEmbedding(51, 0.01)),
+        face_count_total: 1,
+        model_version: 'test-v1',
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      }).returning('id');
+      const secondId = typeof inserted === 'object' ? inserted.id : inserted;
+
+      await db('event_people').where({ id: first.id }).update({ label: 'Anna' });
+      await db('event_people').where({ id: secondId }).update({ label: 'Ben' });
+
+      await clustering.consolidate(eventId);
+
+      expect(await db('event_people').where({ event_id: eventId })).toHaveLength(2);
+    });
+  });
+});

backend/__tests__/integration/faceExternalImportEnqueue.test.js

@@ -0,0 +1,239 @@
+/**
+ * External imports are queued for face scanning, in the right order (#1090).
+ *
+ * Managed uploads are enqueued by photoProcessor, which writes face_status
+ * 'pending' once a photo is processed (photoProcessor.js:573 — "the only
+ * correct place to enqueue"). External media never goes through photoProcessor:
+ * adminExternalMedia inserts rows directly, so they stayed NULL and were only
+ * ever picked up by a manual Re-scan.
+ *
+ * The ordering matters as much as the enqueue. events.external_path is written
+ * only AFTER the whole import loop, so marking rows 'pending' as they are
+ * inserted publishes claimable work while the event still points at the old
+ * directory — or none at all, on a first import. The face worker polls
+ * continuously, would resolve those photos against the wrong path, and mark
+ * them permanently 'failed', a state only an explicit Re-scan clears.
+ *
+ * This drives the real route rather than re-implementing it, so removing the
+ * enqueue fails the first test and moving it back onto the insert fails the
+ * second.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const express = require('express');
+const request = require('supertest');
+
+describe('external import queues faces (#1090)', () => {
+  let tmpDir; let db; let app; let mediaRoot;
+  // Recorded from inside the per-photo thumbnail call, i.e. mid-loop.
+  let pendingSeenDuringLoop = 0;
+  let externalPathDuringLoop;
+  // When set to an event id, the mocked thumbnail call turns detection on
+  // mid-loop, standing in for an admin flipping the toggle during an import.
+  let flipFacesOnDuringLoop = null;
+  // Stands in for a concurrent Re-scan completing a row mid-import.
+  let markDoneDuringLoop = false;
+
+  beforeAll(async () => {
+    tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'picpeak-extenq-'));
+    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 || 'extenq-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(),
+    }));
+
+    // Runs once per photo, inside the import loop — the only hook that can
+    // observe the intermediate state the ordering bug would expose.
+    jest.doMock('../../src/services/imageProcessor', () => ({
+      generateThumbnail: jest.fn(async () => {
+        const { db: liveDb } = require('../../src/database/db');
+        const rows = await liveDb('photos').where({ face_status: 'pending' });
+        pendingSeenDuringLoop += rows.length;
+        const ev = await liveDb('events').first();
+        externalPathDuringLoop = ev ? ev.external_path : undefined;
+        if (markDoneDuringLoop) {
+          const rows = await liveDb('photos').orderBy('id', 'asc').limit(1);
+          if (rows.length) {
+            await liveDb('photos').where({ id: rows[0].id }).update({ face_status: 'done' });
+          }
+        }
+        if (flipFacesOnDuringLoop) {
+          await liveDb('events').where({ id: flipFacesOnDuringLoop })
+            .update({ face_recognition_enabled: true });
+        }
+        return 'thumbnails/mock.jpg';
+      }),
+      ensureThumbnail: jest.fn(),
+    }));
+
+    jest.doMock('../../src/utils/logger', () => ({
+      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
+    }));
+
+    // bootCrmDb runs every migrations/core/*.up() directly — knex's Migrator
+    // deadlocks on 001_init's nested initializeDatabase() call.
+    ({ 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({ facesEnabled, flagOn }) {
+    await db('feature_flags').insert({ key: 'faces', value: flagOn })
+      .onConflict('key').merge()
+      .catch(async () => { await db('feature_flags').where({ key: 'faces' }).update({ value: flagOn }); });
+    // The flag read is TTL-cached (requireFeatureFlag.js:26-34); production
+    // invalidates after every write, and so must this.
+    require('../../src/middleware/requireFeatureFlag').invalidateFeatureFlagCache();
+
+    await db('photos').del();
+    await db('events').del();
+    const [e] = await db('events').insert({
+      slug: `extenq-${Math.random().toString(36).slice(2, 8)}`,
+      event_type: 'wedding',
+      event_name: 'extenq',
+      event_date: '2026-01-01',
+      host_email: 'h@example.com',
+      admin_email: 'a@example.com',
+      password_hash: 'x',
+      share_link: `extenq-${Math.random()}`,
+      expires_at: new Date().toISOString(),
+      face_recognition_enabled: facesEnabled,
+      source_mode: 'reference',
+    }).returning('id');
+
+    pendingSeenDuringLoop = 0;
+    externalPathDuringLoop = undefined;
+    markDoneDuringLoop = false;
+    return typeof e === 'object' ? e.id : e;
+  }
+
+  async function runImport(eventId) {
+    return request(app)
+      .post(`/api/admin/external-media/events/${eventId}/import-external`)
+      .send({ external_path: 'nas', recursive: true });
+  }
+
+  it('queues imported photos when detection is on', async () => {
+    const eventId = await seedEvent({ facesEnabled: true, flagOn: true });
+
+    const res = await runImport(eventId);
+    expect(res.status).toBe(200);
+
+    const photos = await db('photos').where({ event_id: eventId });
+    expect(photos.length).toBeGreaterThan(0);
+    // The regression: these stayed NULL and waited for a manual Re-scan.
+    expect(photos.every((p) => p.face_status === 'pending')).toBe(true);
+  });
+
+  it('does not publish claimable rows before events.external_path is written', async () => {
+    const eventId = await seedEvent({ facesEnabled: true, flagOn: true });
+
+    await runImport(eventId);
+
+    // Observed from inside the loop: nothing is claimable yet. The event path
+    // is already committed (see the test above), so this is no longer load
+    // bearing for correctness — but keeping the enqueue at the end is what lets
+    // the feature setting be read after the loop, so the invariant stays.
+    expect(pendingSeenDuringLoop).toBe(0);
+
+    // ...and afterwards both are in place.
+    const ev = await db('events').where({ id: eventId }).first();
+    expect(ev.external_path).toBe('nas');
+    expect((await db('photos').where({ event_id: eventId, face_status: 'pending' })).length)
+      .toBe((await db('photos').where({ event_id: eventId })).length);
+  });
+
+  it('honours a toggle flipped DURING the import', async () => {
+    // The setting is read after the loop, not before: on a large library the
+    // loop runs for minutes, and the toggle endpoint only queues rows that
+    // already existed when it fired. Reading it up front would strand every
+    // photo imported after that moment at NULL forever.
+    const eventId = await seedEvent({ facesEnabled: false, flagOn: true });
+    flipFacesOnDuringLoop = eventId;
+
+    await runImport(eventId);
+    flipFacesOnDuringLoop = null;
+
+    const photos = await db('photos').where({ event_id: eventId });
+    expect(photos.length).toBeGreaterThan(0);
+    expect(photos.every((p) => p.face_status === 'pending')).toBe(true);
+  });
+
+  it('commits events.external_path before the first row is inserted', async () => {
+    // enqueueEvent accepts processing_status NULL (faceProcessor.js:243-246),
+    // which these inserts leave unset — so a toggle or Re-scan firing mid-import
+    // can queue partial rows. If the event still pointed at the old directory
+    // they would resolve against it and burn to 'failed'. Setting the path
+    // first also means a half-finished import leaves rows that still resolve,
+    // instead of rows stranded against the previous path.
+    const eventId = await seedEvent({ facesEnabled: true, flagOn: true });
+
+    await runImport(eventId);
+
+    // Sampled from inside the per-photo thumbnail call, i.e. while rows are
+    // still being inserted.
+    expect(externalPathDuringLoop).toBe('nas');
+  });
+
+  it('does not re-queue rows a concurrent scan already handled', async () => {
+    // Committing the event path before the loop means a toggle or Re-scan
+    // firing mid-import can now genuinely queue and even finish some of these
+    // rows. A blanket update at the end would drag 'done' rows back to
+    // 'pending' for a duplicate sidecar scan and knock 'processing' rows out
+    // from under the worker.
+    const eventId = await seedEvent({ facesEnabled: true, flagOn: true });
+    markDoneDuringLoop = true;
+
+    await runImport(eventId);
+    markDoneDuringLoop = false;
+
+    const done = await db('photos').where({ event_id: eventId, face_status: 'done' });
+    expect(done.length).toBeGreaterThan(0); // the concurrent scan's work survived
+  });
+
+  it('leaves face_status untouched when the per-event toggle is off', async () => {
+    const eventId = await seedEvent({ facesEnabled: false, flagOn: true });
+    await runImport(eventId);
+    const photos = await db('photos').where({ event_id: eventId });
+    expect(photos.length).toBeGreaterThan(0);
+    expect(photos.every((p) => p.face_status === null)).toBe(true);
+  });
+
+  it('leaves face_status untouched when the global flag is off', async () => {
+    // Installs without the feature must never accumulate face_status rows —
+    // the same invariant photoProcessor's guard protects.
+    const eventId = await seedEvent({ facesEnabled: true, flagOn: false });
+    await runImport(eventId);
+    const photos = await db('photos').where({ event_id: eventId });
+    expect(photos.length).toBeGreaterThan(0);
+    expect(photos.every((p) => p.face_status === null)).toBe(true);
+  });
+});

backend/__tests__/integration/faceExternalPhotos.test.js

@@ -0,0 +1,163 @@
+/**
+ * External / reference photos are scannable (#1090).
+ *
+ * faceProcessor used to short-circuit every photo with source_origin
+ * 'external' or 'reference' to 'skipped', because resolvePhotoStorageKey
+ * returns null for anything outside managed storage and ensurePreviewImage
+ * could not build a preview for it. #1078 removed that limitation —
+ * ensurePreviewImage now reads externals straight off the mount and writes
+ * the preview into managed storage — but the guard stayed, so the whole
+ * feature was a no-op on external-media installs. The reporter's gallery sat
+ * at 0/3230 with every row 'skipped' and no error.
+ *
+ * These pin both halves: the guard is gone, and a photo whose source is
+ * genuinely missing still fails rather than being quietly skipped — the blanket
+ * skip used to absorb that case too, so a real breakage looked like an
+ * unsupported one.
+ */
+
+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-faceext-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'faceext-test-secret';
+// A real, existing media root. getExternalMediaRoot only honours the env var
+// if the directory exists and caches it on first call, so this has to be set
+// up before anything requires externalMediaService.
+process.env.EXTERNAL_MEDIA_ROOT = path.join(path.dirname(process.env.TEST_DATABASE_PATH), 'media');
+fs.mkdirSync(path.join(process.env.EXTERNAL_MEDIA_ROOT, 'share', 'individual'), { recursive: true });
+// Non-empty on purpose: an empty directory is read as an unmounted share
+// (faceTransientSource.test.js), so a "healthy storage, dead photo" fixture
+// needs a sibling present or it defers instead of failing.
+fs.writeFileSync(path.join(process.env.EXTERNAL_MEDIA_ROOT, 'share', 'individual', 'sibling.jpg'), 'x');
+
+const sharp = require('sharp');
+
+let mockPreviewBuffer;
+// Set per-test: what ensurePreviewImage returns for the photo under test.
+let previewKeyResult;  // eslint-disable-line prefer-const
+const mockEnsurePreviewImage = jest.fn(async () => previewKeyResult);
+const mockDetectFaces = jest.fn();
+
+jest.mock('../../src/services/imageProcessor', () => ({
+  ...jest.requireActual('../../src/services/imageProcessor'),
+  ensurePreviewImage: (...args) => mockEnsurePreviewImage(...args),
+}));
+
+jest.mock('../../src/services/storage', () => ({
+  getStorage: () => ({ get: async () => mockPreviewBuffer }),
+}));
+
+jest.mock('../../src/services/faceClient', () => ({
+  detectFaces: (...args) => mockDetectFaces(...args),
+  SidecarUnavailableError: class extends Error {},
+}));
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup; let faceProcessor;
+
+async function seedPhoto({ sourceOrigin = 'managed', sourceMode = 'managed' } = {}) {
+  const [e] = await db('events').insert({
+    slug: `ext-${Math.random().toString(36).slice(2, 8)}`,
+    event_type: 'wedding',
+    event_name: 'ext',
+    event_date: '2026-01-01',
+    host_email: 'h@example.com',
+    admin_email: 'a@example.com',
+    password_hash: 'x',
+    share_link: `ext-${Math.random()}`,
+    expires_at: new Date().toISOString(),
+    face_recognition_enabled: true,
+    source_mode: sourceMode,
+    external_path: 'share',
+  }).returning('id');
+  const eventId = typeof e === 'object' ? e.id : e;
+
+  const [p] = await db('photos').insert({
+    event_id: eventId,
+    filename: 'ext.jpg',
+    path: '/tmp/ext.jpg',
+    type: 'individual',
+    width: 1920,
+    height: 1440,
+    processing_status: 'complete',
+    face_status: 'processing',
+    source_origin: sourceOrigin,
+    external_relpath: sourceOrigin === 'managed' ? null : 'individual/ext.jpg',
+  }).returning('id');
+  return { eventId, photoId: typeof p === 'object' ? p.id : p };
+}
+
+describe('face scanning of external/reference photos (#1090)', () => {
+  beforeAll(async () => {
+    mockPreviewBuffer = await sharp({
+      create: { width: 1920, height: 1440, channels: 3, background: { r: 20, g: 40, b: 80 } },
+    }).jpeg().toBuffer();
+
+    ({ db, cleanup } = await bootCrmDb());
+    await db('feature_flags').insert({ key: 'faces', value: true })
+      .onConflict('key').merge()
+      .catch(async () => { await db('feature_flags').where({ key: 'faces' }).update({ value: true }); });
+    faceProcessor = require('../../src/services/faceProcessor');
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  beforeEach(() => {
+    mockEnsurePreviewImage.mockClear();
+    mockDetectFaces.mockClear();
+    previewKeyResult = 'previews/preview_ext.jpg';
+    mockDetectFaces.mockResolvedValue({
+      model_version: 'test-v1',
+      faces: [{
+        bbox: [100, 100, 50, 50],
+        score: 0.99,
+        landmarks: [[0, 0], [0, 0], [0, 0], [0, 0], [0, 0]],
+        yaw: 0, pitch: 0, blur: 500,
+        embedding: Array.from({ length: 64 }, (_, i) => (i === 0 ? 1 : 0)),
+      }],
+    });
+  });
+
+  it.each(['external', 'reference'])('scans a %s photo instead of skipping it', async (origin) => {
+    const { photoId } = await seedPhoto({ sourceOrigin: origin, sourceMode: 'reference' });
+
+    const result = await faceProcessor.processPhotoFaces(photoId);
+
+    // The regression: this used to return 'skipped' without ever building a
+    // preview or contacting the sidecar.
+    expect(result.status).not.toBe('skipped');
+    expect(mockEnsurePreviewImage).toHaveBeenCalled();
+    expect(mockDetectFaces).toHaveBeenCalled();
+
+    const photo = await db('photos').where({ id: photoId }).first();
+    expect(photo.face_status).toBe('done');
+    expect(await db('photo_faces').where({ photo_id: photoId }).first()).toBeTruthy();
+  });
+
+  it('fails, not skips, when the external source is genuinely gone', async () => {
+    // A missing file is a property of that photo, so it should be visible as a
+    // failure the admin can act on — not silently absorbed the way the old
+    // blanket skip did.
+    //
+    // The containing directory exists here on purpose. An absent directory is
+    // a dropped mount, which defers rather than fails
+    // (faceTransientSource.test.js); this is the other case — healthy storage,
+    // dead photo.
+    previewKeyResult = null;
+    const { photoId } = await seedPhoto({ sourceOrigin: 'external', sourceMode: 'reference' });
+
+    const result = await faceProcessor.processPhotoFaces(photoId);
+
+    expect(result.status).toBe('failed');
+    expect(mockDetectFaces).not.toHaveBeenCalled();
+    const photo = await db('photos').where({ id: photoId }).first();
+    expect(photo.face_status).toBe('failed');
+    expect(photo.face_error).toMatch(/preview/i);
+  });
+});

backend/__tests__/integration/facePrivacy.test.js

@@ -0,0 +1,339 @@
+/**
+ * Privacy and visibility guarantees for face recognition (#1074).
+ *
+ * These are the tests that matter most in this feature. Two of them cover
+ * defects that would be invisible in normal use:
+ *
+ *   - The people strip is computed from face rows, which have no concept of
+ *     photo visibility. Handing a guest a raw count leaks how many hidden
+ *     photos someone appears in, and a cover face picked without scoping
+ *     renders a crop of a photo the guest may not open.
+ *
+ *   - Face embeddings are biometric data. They must not ride along in a
+ *     .picpeak export, which gets handed to clients and moved between
+ *     operators.
+ */
+
+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-faceprivacy-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'faceprivacy-test-secret';
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup; let clustering; let peopleService; let faceProcessor;
+
+function makeEmbedding(id, variant = 0, dim = 64) {
+  const vec = new Float32Array(dim);
+  for (let i = 0; i < dim; i++) {
+    vec[i] = Math.sin((i + 1) * (id + 1) * 0.7) + variant * 0.02 * Math.cos(i * 3.1);
+  }
+  let norm = 0;
+  for (let i = 0; i < dim; i++) norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  for (let i = 0; i < dim; i++) vec[i] /= norm;
+  return vec;
+}
+
+async function seedEvent(slug) {
+  const [row] = await db('events').insert({
+    slug,
+    event_type: 'wedding',
+    event_name: slug,
+    event_date: '2026-01-01',
+    host_email: 'h@example.com',
+    admin_email: 'a@example.com',
+    password_hash: 'x',
+    share_link: `${slug}-share`,
+    expires_at: new Date().toISOString(),
+    face_recognition_enabled: true,
+  }).returning('id');
+  return typeof row === 'object' ? row.id : row;
+}
+
+async function addPhotoWithFace(eventId, embedding, { visibility = 'visible', score = 0.99 } = {}) {
+  const [p] = await db('photos').insert({
+    event_id: eventId,
+    filename: `${Math.random()}.jpg`,
+    path: '/tmp/x.jpg',
+    type: 'individual',
+    visibility,
+    processing_status: 'complete',
+  }).returning('id');
+  const photoId = typeof p === 'object' ? p.id : p;
+
+  const row = {
+    photo_id: photoId,
+    event_id: eventId,
+    bbox_x: 0, bbox_y: 0, bbox_w: 200, bbox_h: 200,
+    det_score: score,
+    embedding: clustering.packEmbedding(embedding),
+    model_version: 'test-v1',
+    created_at: new Date().toISOString(),
+  };
+  const [f] = await db('photo_faces').insert(row).returning('id');
+  return { photoId, face: { ...row, id: typeof f === 'object' ? f.id : f } };
+}
+
+describe('face privacy and visibility (#1074)', () => {
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    clustering = require('../../src/services/faceClustering');
+    peopleService = require('../../src/services/facePeopleService');
+    faceProcessor = require('../../src/services/faceProcessor');
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  describe('visibility scoping', () => {
+    it('counts only photos the audience can actually see', async () => {
+      const eventId = await seedEvent('visibility-count');
+      const faces = [];
+      // Same person: 3 visible photos, 4 hidden ones.
+      for (let v = 0; v < 3; v++) {
+        faces.push((await addPhotoWithFace(eventId, makeEmbedding(1, v))).face);
+      }
+      for (let v = 3; v < 7; v++) {
+        faces.push((await addPhotoWithFace(eventId, makeEmbedding(1, v), { visibility: 'hidden' })).face);
+      }
+      await clustering.assignFaces(eventId, faces);
+
+      const guestView = await peopleService.listPeople(eventId, { isClient: false, minClusterSize: 1 });
+      const clientView = await peopleService.listPeople(eventId, { isClient: true, minClusterSize: 1 });
+
+      expect(guestView).toHaveLength(1);
+      // The leak this test exists to prevent: 3, never 7.
+      expect(guestView[0].face_count).toBe(3);
+      expect(clientView[0].face_count).toBe(7);
+    });
+
+    it('never returns face_count_total to a guest', async () => {
+      const eventId = await seedEvent('no-total-leak');
+      const { face } = await addPhotoWithFace(eventId, makeEmbedding(2));
+      await clustering.assignFaces(eventId, [face]);
+
+      const [person] = await peopleService.listPeople(eventId, { isClient: false, minClusterSize: 1 });
+      expect(person).not.toHaveProperty('total_face_count');
+      expect(person).not.toHaveProperty('is_hidden');
+    });
+
+    it('picks a cover face from a photo the guest may open', async () => {
+      const eventId = await seedEvent('cover-scoping');
+      // The BEST face (highest score) is in a hidden photo — a naive
+      // implementation would hand its crop to the guest.
+      const hidden = await addPhotoWithFace(eventId, makeEmbedding(3, 0), {
+        visibility: 'hidden', score: 0.99,
+      });
+      const visible = await addPhotoWithFace(eventId, makeEmbedding(3, 1), {
+        visibility: 'visible', score: 0.80,
+      });
+      await clustering.assignFaces(eventId, [hidden.face, visible.face]);
+
+      const [guestPerson] = await peopleService.listPeople(eventId, { isClient: false, minClusterSize: 1 });
+      expect(guestPerson.cover.photo_id).toBe(visible.photoId);
+      expect(guestPerson.cover.photo_id).not.toBe(hidden.photoId);
+    });
+
+    it('drops a person entirely when all their photos are hidden', async () => {
+      const eventId = await seedEvent('all-hidden');
+      const faces = [];
+      for (let v = 0; v < 3; v++) {
+        faces.push((await addPhotoWithFace(eventId, makeEmbedding(4, v), { visibility: 'hidden' })).face);
+      }
+      await clustering.assignFaces(eventId, faces);
+
+      const guestView = await peopleService.listPeople(eventId, { isClient: false, minClusterSize: 1 });
+      expect(guestView).toHaveLength(0);
+      const clientView = await peopleService.listPeople(eventId, { isClient: true, minClusterSize: 1 });
+      expect(clientView).toHaveLength(1);
+    });
+
+    it('omits hidden and ignored people from the guest response', async () => {
+      const eventId = await seedEvent('hidden-people');
+      const a = (await addPhotoWithFace(eventId, makeEmbedding(5))).face;
+      const b = (await addPhotoWithFace(eventId, makeEmbedding(6))).face;
+      await clustering.assignFaces(eventId, [a, b]);
+
+      const people = await db('event_people').where({ event_id: eventId }).orderBy('id');
+      await db('event_people').where({ id: people[0].id }).update({ is_hidden: true });
+      await db('event_people').where({ id: people[1].id }).update({ is_ignored: true });
+
+      const guestView = await peopleService.listPeople(eventId, { isClient: false, minClusterSize: 1 });
+      expect(guestView).toHaveLength(0);
+      const adminView = await peopleService.listPeople(eventId, { isClient: true, forAdmin: true });
+      expect(adminView).toHaveLength(2);
+    });
+
+    it('does not attach a hidden person to a photo a guest can see', async () => {
+      const eventId = await seedEvent('person-ids-hidden');
+      const { photoId, face } = await addPhotoWithFace(eventId, makeEmbedding(7));
+      await clustering.assignFaces(eventId, [face]);
+      const person = await db('event_people').where({ event_id: eventId }).first();
+      await db('event_people').where({ id: person.id }).update({ is_hidden: true });
+
+      const guestMap = await peopleService.getPersonIdsByPhoto(eventId, [photoId], { forAdmin: false });
+      expect(guestMap.get(photoId)).toBeUndefined();
+
+      const adminMap = await peopleService.getPersonIdsByPhoto(eventId, [photoId], { forAdmin: true });
+      expect(adminMap.get(photoId)).toEqual([person.id]);
+    });
+
+    it('respects the minimum cluster size so one-off bystanders stay out', async () => {
+      const eventId = await seedEvent('min-cluster');
+      const solo = (await addPhotoWithFace(eventId, makeEmbedding(8))).face;
+      const crowd = [];
+      for (let v = 0; v < 4; v++) {
+        crowd.push((await addPhotoWithFace(eventId, makeEmbedding(9, v))).face);
+      }
+      await clustering.assignFaces(eventId, [solo, ...crowd]);
+
+      const people = await peopleService.listPeople(eventId, { isClient: false, minClusterSize: 3 });
+      expect(people).toHaveLength(1);
+      expect(people[0].face_count).toBe(4);
+    });
+  });
+
+  describe('erasure', () => {
+    it('purgeEvent removes every face row and resets the photos', async () => {
+      const eventId = await seedEvent('purge');
+      const faces = [];
+      for (let v = 0; v < 3; v++) {
+        faces.push((await addPhotoWithFace(eventId, makeEmbedding(10, v))).face);
+      }
+      await clustering.assignFaces(eventId, faces);
+      await db('photos').where({ event_id: eventId }).update({ face_status: 'done', face_count: 1 });
+
+      expect(await db('photo_faces').where({ event_id: eventId })).not.toHaveLength(0);
+      expect(await db('event_people').where({ event_id: eventId })).not.toHaveLength(0);
+
+      await faceProcessor.purgeEvent(eventId);
+
+      expect(await db('photo_faces').where({ event_id: eventId })).toHaveLength(0);
+      expect(await db('event_people').where({ event_id: eventId })).toHaveLength(0);
+      const photos = await db('photos').where({ event_id: eventId });
+      expect(photos.every((p) => p.face_status === null && p.face_count === null)).toBe(true);
+    });
+
+    it('purgePhotoFaces removes face rows WITHOUT relying on the FK cascade', async () => {
+      // The regression this guards: PicPeak does not enable
+      // `PRAGMA foreign_keys` on SQLite, so ON DELETE CASCADE never fires
+      // there and biometric embeddings outlived the photo. The pragma is
+      // explicitly OFF here so the assertion can only pass if the deletion
+      // path purges the rows itself.
+      await db.raw('PRAGMA foreign_keys = OFF');
+
+      const eventId = await seedEvent('purge-no-cascade');
+      const faces = [];
+      for (let v = 0; v < 3; v++) {
+        faces.push((await addPhotoWithFace(eventId, makeEmbedding(20, v))).face);
+      }
+      await clustering.assignFaces(eventId, faces);
+
+      const person = await db('event_people').where({ event_id: eventId }).first();
+      expect(person.face_count_total).toBe(3);
+
+      const victim = faces[0];
+      await faceProcessor.purgePhotoFaces(victim.photo_id);
+
+      expect(await db('photo_faces').where({ photo_id: victim.photo_id })).toHaveLength(0);
+      // …and the person it belonged to was rebuilt, not left with a stale count.
+      const after = await db('event_people').where({ id: person.id }).first();
+      expect(after.face_count_total).toBe(2);
+    });
+
+    it('purging the last face of a person removes the person too', async () => {
+      await db.raw('PRAGMA foreign_keys = OFF');
+      const eventId = await seedEvent('purge-last-face');
+      const { face, photoId } = await addPhotoWithFace(eventId, makeEmbedding(21));
+      await clustering.assignFaces(eventId, [face]);
+      expect(await db('event_people').where({ event_id: eventId })).toHaveLength(1);
+
+      await faceProcessor.purgePhotoFaces(photoId);
+
+      expect(await db('event_people').where({ event_id: eventId })).toHaveLength(0);
+    });
+
+    it('deleting an event removes its people and faces', async () => {
+      await db.raw('PRAGMA foreign_keys = ON');
+      const eventId = await seedEvent('event-delete');
+      const { face } = await addPhotoWithFace(eventId, makeEmbedding(11));
+      await clustering.assignFaces(eventId, [face]);
+
+      await db('photos').where({ event_id: eventId }).del();
+      await db('events').where({ id: eventId }).del();
+
+      expect(await db('photo_faces').where({ event_id: eventId })).toHaveLength(0);
+      expect(await db('event_people').where({ event_id: eventId })).toHaveLength(0);
+    });
+  });
+
+  describe('all-in-one image block (#1042 / PR #1068)', () => {
+    // Blocked for performance: the AIO image runs backend, frontend, SQLite
+    // and every worker in one container, with no ML sidecar to talk to. The
+    // failure there would not be loud — just a slow install that looks
+    // broken — so the gate is asserted rather than assumed.
+    const faceSettings = require('../../src/services/faceSettings');
+
+    afterEach(() => { delete process.env.PICPEAK_SINGLE_CONTAINER; });
+
+    it('reports the feature off regardless of the flag row', async () => {
+      process.env.PICPEAK_SINGLE_CONTAINER = 'true';
+      expect(faceSettings.isSingleContainerImage()).toBe(true);
+      // Even with the flag ON in the database.
+      await db('feature_flags').insert({ key: 'faces', value: true })
+        .onConflict('key').merge()
+        .catch(async () => {
+          await db('feature_flags').where({ key: 'faces' }).update({ value: true });
+        });
+      expect(await faceSettings.isFeatureEnabled()).toBe(false);
+    });
+
+    it('refuses per-event detection too', async () => {
+      process.env.PICPEAK_SINGLE_CONTAINER = 'true';
+      const eventId = await seedEvent('aio-block');
+      const event = await db('events').where({ id: eventId }).first();
+      expect(event.face_recognition_enabled).toBeTruthy();
+      expect(await faceSettings.isEnabledForEvent(event)).toBe(false);
+    });
+
+    it('accepts only explicit truthy markers', () => {
+      for (const v of ['true', '1', 'yes', 'TRUE']) {
+        process.env.PICPEAK_SINGLE_CONTAINER = v;
+        expect(faceSettings.isSingleContainerImage()).toBe(true);
+      }
+      for (const v of ['false', '0', '', 'no']) {
+        process.env.PICPEAK_SINGLE_CONTAINER = v;
+        expect(faceSettings.isSingleContainerImage()).toBe(false);
+      }
+      delete process.env.PICPEAK_SINGLE_CONTAINER;
+      expect(faceSettings.isSingleContainerImage()).toBe(false);
+    });
+  });
+
+  describe('export and backup exclusion', () => {
+    it('excludes both face tables from .picpeak exports', () => {
+      const { EXCLUDED_TABLES } = require('../../src/services/picpeakExportService');
+      expect(EXCLUDED_TABLES.has('photo_faces')).toBe(true);
+      expect(EXCLUDED_TABLES.has('event_people')).toBe(true);
+    });
+
+    it('excludes both face tables from the database backup table list', async () => {
+      const databaseBackup = require('../../src/services/databaseBackup');
+      const service = databaseBackup.DatabaseBackupService
+        ? new databaseBackup.DatabaseBackupService()
+        : databaseBackup;
+      if (typeof service.getTables !== 'function') return; // shape differs; covered by the export test
+
+      const tables = await service.getTables();
+      expect(tables).not.toContain('photo_faces');
+      expect(tables).not.toContain('event_people');
+      // Sanity: the filter didn't eat everything.
+      expect(tables).toContain('events');
+    });
+  });
+});

backend/__tests__/integration/faceProcessorScaling.test.js

@@ -0,0 +1,146 @@
+/**
+ * Bounding-box coordinate space (#1074).
+ *
+ * The sidecar reports boxes in the pixel space of the image it was HANDED —
+ * the ≤1920px preview — while every consumer (the strip's avatar crop, the
+ * admin manager, the auto-category portrait rule) compares them against
+ * photos.width/height, the ORIGINAL dimensions. faceProcessor scales once so
+ * everything downstream can assume original-image coordinates.
+ *
+ * This is the defect that survived longest in review, and it is invisible on
+ * any photo already under 1920px — the entire demo gallery was 750px, so the
+ * scale factor was always exactly 1.0 and the correction never ran. Verified
+ * by hand afterwards on a real 4000x3000 upload (stored box moved from
+ * 1493,204 to 3110,426 — a factor of 2.083, exactly 4000/1920). This test
+ * exists so that verification does not have to be repeated by hand.
+ */
+
+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-facescale-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'facescale-test-secret';
+
+// A 1920x1440 JPEG standing in for the preview rendition. faceProcessor reads
+// its dimensions with sharp to derive the scale, so it must be a real image.
+const sharp = require('sharp');
+
+let mockPreviewBuffer;
+const mockSidecarBox = [1493, 204, 131, 161]; // what the sidecar sees on the preview
+
+jest.mock('../../src/services/imageProcessor', () => ({
+  ...jest.requireActual('../../src/services/imageProcessor'),
+  ensurePreviewImage: jest.fn(async () => 'previews/preview_test.jpg'),
+}));
+
+jest.mock('../../src/services/storage', () => ({
+  getStorage: () => ({ get: async () => mockPreviewBuffer }),
+}));
+
+jest.mock('../../src/services/faceClient', () => ({
+  detectFaces: jest.fn(async () => ({
+    model_version: 'test-v1',
+    faces: [{
+      bbox: mockSidecarBox,
+      score: 0.99,
+      landmarks: [[0, 0], [0, 0], [0, 0], [0, 0], [0, 0]],
+      yaw: 0, pitch: 0, blur: 500,
+      embedding: Array.from({ length: 64 }, (_, i) => (i === 0 ? 1 : 0)),
+    }],
+  })),
+  SidecarUnavailableError: class extends Error {},
+}));
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup; let faceProcessor;
+
+async function seedPhoto(width, height) {
+  const [e] = await db('events').insert({
+    slug: `scale-${width}-${Math.random().toString(36).slice(2, 8)}`,
+    event_type: 'wedding',
+    event_name: 'scale',
+    event_date: '2026-01-01',
+    host_email: 'h@example.com',
+    admin_email: 'a@example.com',
+    password_hash: 'x',
+    share_link: `scale-${Math.random()}`,
+    expires_at: new Date().toISOString(),
+    face_recognition_enabled: true,
+  }).returning('id');
+  const eventId = typeof e === 'object' ? e.id : e;
+
+  const [p] = await db('photos').insert({
+    event_id: eventId,
+    filename: 'big.jpg',
+    path: '/tmp/big.jpg',
+    type: 'individual',
+    width,
+    height,
+    processing_status: 'complete',
+    face_status: 'processing',
+  }).returning('id');
+  return { eventId, photoId: typeof p === 'object' ? p.id : p };
+}
+
+describe('face bbox coordinate space (#1074)', () => {
+  beforeAll(async () => {
+    mockPreviewBuffer = await sharp({
+      create: { width: 1920, height: 1440, channels: 3, background: { r: 20, g: 40, b: 80 } },
+    }).jpeg().toBuffer();
+
+    ({ db, cleanup } = await bootCrmDb());
+    // The faces flag gates everything; turn it on for this suite.
+    await db('feature_flags').insert({ key: 'faces', value: true })
+      .onConflict('key').merge()
+      .catch(async () => { await db('feature_flags').where({ key: 'faces' }).update({ value: true }); });
+    faceProcessor = require('../../src/services/faceProcessor');
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  it('scales preview-space boxes into ORIGINAL image coordinates', async () => {
+    // 4000px original, 1920px preview -> every coordinate must grow by 4000/1920.
+    const { photoId } = await seedPhoto(4000, 3000);
+    await faceProcessor.processPhotoFaces(photoId);
+
+    const face = await db('photo_faces').where({ photo_id: photoId }).first();
+    const scale = 4000 / 1920;
+
+    expect(face.bbox_x).toBeCloseTo(mockSidecarBox[0] * scale, 1);
+    expect(face.bbox_y).toBeCloseTo(mockSidecarBox[1] * scale, 1);
+    expect(face.bbox_w).toBeCloseTo(mockSidecarBox[2] * scale, 1);
+    expect(face.bbox_h).toBeCloseTo(mockSidecarBox[3] * scale, 1);
+
+    // The regression this guards: the raw preview-space value being stored.
+    expect(face.bbox_x).not.toBeCloseTo(mockSidecarBox[0], 1);
+    // And a sanity check that it lands inside the original frame.
+    expect(face.bbox_x + face.bbox_w).toBeLessThanOrEqual(4000);
+  });
+
+  it('leaves boxes untouched when the photo is already preview-sized', async () => {
+    // The case that hid the bug: no downscale, so scale is exactly 1 and the
+    // stored box equals what the sidecar reported.
+    const { photoId } = await seedPhoto(1920, 1440);
+    await faceProcessor.processPhotoFaces(photoId);
+
+    const face = await db('photo_faces').where({ photo_id: photoId }).first();
+    expect(face.bbox_x).toBeCloseTo(mockSidecarBox[0], 1);
+    expect(face.bbox_w).toBeCloseTo(mockSidecarBox[2], 1);
+  });
+
+  it('falls back to unscaled rather than corrupting when width is unknown', async () => {
+    // Pre-dimension-migration rows have no width. Storing a box scaled by
+    // NaN/0 would be worse than storing an unscaled one.
+    const { photoId } = await seedPhoto(null, null);
+    await faceProcessor.processPhotoFaces(photoId);
+
+    const face = await db('photo_faces').where({ photo_id: photoId }).first();
+    expect(Number.isFinite(face.bbox_x)).toBe(true);
+    expect(face.bbox_x).toBeCloseTo(mockSidecarBox[0], 1);
+  });
+});

backend/__tests__/integration/faceQueueDeferral.test.js

@@ -0,0 +1,226 @@
+/**
+ * A deferred photo must not stall the queue.
+ *
+ * claimNextPhoto orders by id ascending, and the queue defaults to a single
+ * worker. So returning an unreachable photo to 'pending' — the obvious way to
+ * say "try again later" — makes that same row the oldest pending one forever:
+ * the worker reclaims it after every backoff and never reaches a higher id.
+ * One dead mount would stall face scanning for the entire install, including
+ * unrelated events and fresh uploads.
+ *
+ * The row is instead left parked in 'processing' with its face_started_at
+ * intact. It is not claimable, so the worker advances; the existing janitor
+ * returns it to 'pending' after STUCK_TIMEOUT_MS, which is the retry.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-defer-'));
+process.env.TEST_DATABASE_PATH = path.join(tmpRoot, 'db.sqlite');
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'defer-test-secret';
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup; let faceQueue; let faceProcessor;
+
+describe('deferred photos do not block the queue', () => {
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    faceQueue = require('../../src/services/faceQueue');
+    faceProcessor = require('../../src/services/faceProcessor');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+    await fs.promises.rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('exports TransientSourceError for the queue to branch on', () => {
+    // The queue imports this from faceProcessor; if the export is dropped the
+    // instanceof check silently becomes false and every deferral turns back
+    // into a permanent failure.
+    expect(typeof faceProcessor.TransientSourceError).toBe('function');
+    expect(new faceProcessor.TransientSourceError(1, 'x'))
+      .toBeInstanceOf(Error);
+  });
+
+  it('does NOT return a deferred row to pending', () => {
+    // Source inspection, deliberately. workerLoop is an unexported infinite
+    // loop, so the branch cannot be driven directly, and asserting on database
+    // state alone does not distinguish the fix from the bug — a version that
+    // re-queues the row passes every state assertion in this file. What
+    // actually matters is that this one branch does not call releaseToPending,
+    // so that is what is pinned. Same approach as the contract tests added for
+    // #596.
+    const src = fs.readFileSync(
+      path.join(__dirname, '..', '..', 'src', 'services', 'faceQueue.js'), 'utf8'
+    );
+
+    const marker = 'if (err instanceof TransientSourceError) {';
+    const start = src.indexOf(marker);
+    expect(start).toBeGreaterThan(-1);
+
+    // The branch body, up to its closing brace.
+    const body = src.slice(start, src.indexOf('\n      }', start));
+    expect(body).not.toMatch(/releaseToPending/);
+    expect(body).toMatch(/continue/);
+
+    // And the sidecar branch, which SHOULD still release, so this test fails
+    // if the two branches are ever collapsed back together.
+    const sideStart = src.indexOf('if (err instanceof SidecarUnavailableError) {');
+    expect(sideStart).toBeGreaterThan(-1);
+    const sideBody = src.slice(sideStart, src.indexOf('\n      }', sideStart));
+    expect(sideBody).toMatch(/releaseToPending/);
+  });
+
+  it('leaves a deferred row claimable-later, not claimable-now', async () => {
+    // A row parked in 'processing' is invisible to claimNextPhoto, which only
+    // ever selects face_status='pending' — that is what lets the worker move
+    // past it instead of spinning on it.
+    const [e] = await db('events').insert({
+      slug: `defer-${Math.random().toString(36).slice(2, 8)}`,
+      event_type: 'wedding',
+      event_name: 'defer',
+      event_date: '2026-01-01',
+      host_email: 'h@example.com',
+      admin_email: 'a@example.com',
+      password_hash: 'x',
+      share_link: `defer-${Math.random()}`,
+      expires_at: new Date().toISOString(),
+      face_recognition_enabled: true,
+    }).returning('id');
+    const eventId = typeof e === 'object' ? e.id : e;
+
+    const [stuck] = await db('photos').insert({
+      event_id: eventId,
+      filename: 'stuck.jpg',
+      path: 'd/stuck.jpg',
+      type: 'individual',
+      processing_status: 'complete',
+      face_status: 'processing',
+      face_started_at: new Date().toISOString(),
+      source_origin: 'external',
+    }).returning('id');
+    const stuckId = typeof stuck === 'object' ? stuck.id : stuck;
+
+    const parked = await db('photos')
+      .where({ id: stuckId, face_status: 'pending' })
+      .first();
+    expect(parked).toBeUndefined(); // not claimable while parked
+
+    // The janitor's contract is what turns the park into a retry: it resets
+    // 'processing' rows whose face_started_at is older than the stuck timeout.
+    // Backdate past it and the row becomes claimable again.
+    const longAgo = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    await db('photos').where({ id: stuckId }).update({ face_started_at: longAgo });
+
+    const cutoff = new Date(Date.now() - 600000).toISOString();
+    const reset = await db('photos')
+      .where('face_status', 'processing')
+      .where('face_started_at', '<', cutoff)
+      .update({ face_status: 'pending', face_started_at: null });
+
+    expect(reset).toBeGreaterThan(0);
+    const after = await db('photos').where({ id: stuckId }).first();
+    expect(after.face_status).toBe('pending');
+  });
+
+  it('claimNextPhoto skips events inside their backoff window', async () => {
+    // The per-event cooldown is what stops the janitor handing a whole dead
+    // gallery back every sweep. Without the exclusion the worker walks all of
+    // it again — one slow stat per photo against a possibly hard-mounted
+    // share — before reaching any healthy event.
+    const mk = async (name) => {
+      const [e] = await db('events').insert({
+        slug: `cd-${name}-${Math.random().toString(36).slice(2, 8)}`,
+        event_type: 'wedding',
+        event_name: name,
+        event_date: '2026-01-01',
+        host_email: 'h@example.com',
+        admin_email: 'a@example.com',
+        password_hash: 'x',
+        share_link: `cd-${name}-${Math.random()}`,
+        expires_at: new Date().toISOString(),
+        face_recognition_enabled: true,
+      }).returning('id');
+      const eventId = typeof e === 'object' ? e.id : e;
+      const [p2] = await db('photos').insert({
+        event_id: eventId,
+        filename: `${name}.jpg`,
+        path: `cd/${name}.jpg`,
+        type: 'individual',
+        processing_status: 'complete',
+        face_status: 'pending',
+        source_origin: 'external',
+      }).returning('id');
+      return { eventId, photoId: typeof p2 === 'object' ? p2.id : p2 };
+    };
+
+    await db('photos').del();
+    const dead = await mk('dead');     // lower id -> would win the FIFO
+    const healthy = await mk('healthy');
+
+    // Without exclusion the dead event's row is claimed first...
+    const first = await faceQueue.claimNextPhoto([]);
+    expect(first.id).toBe(dead.photoId);
+    await db('photos').where({ id: dead.photoId }).update({ face_status: 'pending' });
+
+    // ...and with it, the worker reaches the healthy event instead.
+    const second = await faceQueue.claimNextPhoto([dead.eventId]);
+    expect(second.id).toBe(healthy.photoId);
+  });
+
+  it('backoff spares managed rows in a mixed-source event', async () => {
+    // A reference event can hold managed uploads alongside imported external
+    // ones. Excluding the whole event id would leave those unscanned for as
+    // long as external rows keep renewing the cooldown — indefinitely, during
+    // a real outage — even though their local source is fine.
+    await db('photos').del();
+    const [e] = await db('events').insert({
+      slug: `mix-${Math.random().toString(36).slice(2, 8)}`,
+      event_type: 'wedding',
+      event_name: 'mix',
+      event_date: '2026-01-01',
+      host_email: 'h@example.com',
+      admin_email: 'a@example.com',
+      password_hash: 'x',
+      share_link: `mix-${Math.random()}`,
+      expires_at: new Date().toISOString(),
+      face_recognition_enabled: true,
+      source_mode: 'reference',
+    }).returning('id');
+    const eventId = typeof e === 'object' ? e.id : e;
+
+    const add = async (origin, name) => {
+      const [p2] = await db('photos').insert({
+        event_id: eventId,
+        filename: name,
+        path: `mix/${name}`,
+        type: 'individual',
+        processing_status: 'complete',
+        face_status: 'pending',
+        source_origin: origin,
+      }).returning('id');
+      return typeof p2 === 'object' ? p2.id : p2;
+    };
+    await add('external', 'ext.jpg');            // lower id, would win the FIFO
+    const managedId = await add('managed', 'man.jpg');
+
+    // Event is in backoff: the external row is skipped, the managed one is not.
+    const claimed = await faceQueue.claimNextPhoto([eventId]);
+    expect(claimed).toBeTruthy();
+    expect(claimed.id).toBe(managedId);
+  });
+
+  it('startQueue is exported and does not throw on import', () => {
+    // faceQueue requires faceProcessor for TransientSourceError while
+    // faceProcessor is itself required by the routes — a circular require here
+    // would surface as an undefined export rather than a crash, so assert the
+    // module actually loaded something usable.
+    expect(faceQueue).toBeTruthy();
+    expect(Object.keys(faceQueue).length).toBeGreaterThan(0);
+  });
+});

backend/__tests__/integration/faceTransientSource.test.js

@@ -0,0 +1,209 @@
+/**
+ * A dropped mount defers a scan; a dead photo fails it.
+ *
+ * ensurePreviewImage returns null for both "this JPEG is corrupt" and "the
+ * NFS share is gone", and #1090 made that distinction matter: external
+ * libraries now reach this path, and network mounts drop far more often than
+ * local disks. Failing on an outage strands the photo — faceQueue only ever
+ * claims 'pending', and nothing re-queues a failure automatically, so a mount
+ * that blinked mid-scan would cost an entire gallery a manual Re-scan.
+ *
+ * The probe checks the containing DIRECTORY rather than the file, because that
+ * is what separates the two cases: a missing file inside a healthy directory
+ * is a broken photo, an unreachable directory is broken storage.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-transient-'));
+process.env.TEST_DATABASE_PATH = path.join(tmpRoot, 'db.sqlite');
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'transient-test-secret';
+// Created BEFORE anything requires externalMediaService: getExternalMediaRoot
+// only honours the env var if the directory already exists, and caches the
+// result on first call — set it later and every path silently resolves
+// against a fallback root instead.
+process.env.EXTERNAL_MEDIA_ROOT = path.join(tmpRoot, 'media');
+fs.mkdirSync(process.env.EXTERNAL_MEDIA_ROOT, { recursive: true });
+
+let previewKeyResult = null;
+const mockEnsurePreviewImage = jest.fn(async () => previewKeyResult);
+
+jest.mock('../../src/services/imageProcessor', () => ({
+  ...jest.requireActual('../../src/services/imageProcessor'),
+  ensurePreviewImage: (...args) => mockEnsurePreviewImage(...args),
+}));
+
+jest.mock('../../src/services/faceClient', () => ({
+  detectFaces: jest.fn(async () => ({ model_version: 'test-v1', faces: [] })),
+  SidecarUnavailableError: class extends Error {},
+}));
+
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup; let faceProcessor;
+
+async function seedExternalPhoto({ externalPath, relpath = 'individual/a.jpg' }) {
+  const [e] = await db('events').insert({
+    slug: `tr-${Math.random().toString(36).slice(2, 8)}`,
+    event_type: 'wedding',
+    event_name: 'tr',
+    event_date: '2026-01-01',
+    host_email: 'h@example.com',
+    admin_email: 'a@example.com',
+    password_hash: 'x',
+    share_link: `tr-${Math.random()}`,
+    expires_at: new Date().toISOString(),
+    face_recognition_enabled: true,
+    source_mode: 'reference',
+    external_path: externalPath,
+  }).returning('id');
+  const eventId = typeof e === 'object' ? e.id : e;
+
+  const [p] = await db('photos').insert({
+    event_id: eventId,
+    filename: 'a.jpg',
+    path: 'tr/a.jpg',
+    type: 'individual',
+    width: 4000,
+    height: 3000,
+    processing_status: 'complete',
+    face_status: 'processing',
+    source_origin: 'external',
+    external_relpath: relpath,
+  }).returning('id');
+  return { eventId, photoId: typeof p === 'object' ? p.id : p };
+}
+
+describe('transient source vs dead photo', () => {
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    await db('feature_flags').insert({ key: 'faces', value: true })
+      .onConflict('key').merge()
+      .catch(async () => { await db('feature_flags').where({ key: 'faces' }).update({ value: true }); });
+    faceProcessor = require('../../src/services/faceProcessor');
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+    await fs.promises.rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+  });
+
+  beforeEach(() => {
+    previewKeyResult = null; // i.e. ensurePreviewImage could not build one
+    mockEnsurePreviewImage.mockClear();
+  });
+
+  it('defers, not fails, when the source directory is unreachable', async () => {
+    // Nothing was ever created under EXTERNAL_MEDIA_ROOT for this path, so the
+    // directory does not resolve — the shape a dropped mount presents.
+    const { photoId } = await seedExternalPhoto({ externalPath: 'vanished-share' });
+
+    await expect(faceProcessor.processPhotoFaces(photoId))
+      .rejects.toBeInstanceOf(faceProcessor.TransientSourceError);
+
+    // Critically: still claimable. A 'failed' here is what stranded the photo.
+    const photo = await db('photos').where({ id: photoId }).first();
+    expect(photo.face_status).not.toBe('failed');
+  });
+
+  it('defers when the event root survives an unmount but is empty', async () => {
+    // The common NFS/SMB shape: unmounting leaves the mountpoint behind as an
+    // ordinary empty directory, so fs.access succeeds on storage that is
+    // entirely gone. The EVENT ROOT is the thing that goes empty — the photo's
+    // own subdirectory vanishes with it.
+    const emptyRoot = path.join(process.env.EXTERNAL_MEDIA_ROOT, 'unmounted');
+    await fs.promises.mkdir(emptyRoot, { recursive: true });
+    const { photoId } = await seedExternalPhoto({ externalPath: 'unmounted' });
+
+    await expect(faceProcessor.processPhotoFaces(photoId))
+      .rejects.toBeInstanceOf(faceProcessor.TransientSourceError);
+
+    const photo = await db('photos').where({ id: photoId }).first();
+    expect(photo.face_status).not.toBe('failed');
+  });
+
+  it('fails when the directory is healthy but the file is gone', async () => {
+    // Directory exists, file does not — a genuinely broken photo, which should
+    // surface as a failure the admin can see rather than retry forever.
+    const live = path.join(process.env.EXTERNAL_MEDIA_ROOT, 'live-share', 'individual');
+    await fs.promises.mkdir(live, { recursive: true });
+    // Non-empty: an empty directory is now read as an unmounted share, so the
+    // "healthy storage, dead photo" case needs a sibling file present.
+    await fs.promises.writeFile(path.join(live, 'sibling.jpg'), 'x');
+    const { photoId } = await seedExternalPhoto({ externalPath: 'live-share' });
+
+    const result = await faceProcessor.processPhotoFaces(photoId);
+
+    expect(result.status).toBe('failed');
+    const photo = await db('photos').where({ id: photoId }).first();
+    expect(photo.face_status).toBe('failed');
+    expect(photo.face_error).toMatch(/preview/i);
+  });
+
+  it('fails a missing subdirectory rather than deferring the whole event', async () => {
+    // individual/ deleted while collages/ is fine. Probing only the photo's own
+    // directory reports ENOENT and would read as a mount-wide outage, deferring
+    // the event and starving every healthy sibling folder. The root is
+    // populated, so the mount is up and this is a broken path.
+    const root = path.join(process.env.EXTERNAL_MEDIA_ROOT, 'partial');
+    await fs.promises.mkdir(path.join(root, 'collages'), { recursive: true });
+    await fs.promises.writeFile(path.join(root, 'collages', 'kept.jpg'), 'x');
+    const { photoId } = await seedExternalPhoto({ externalPath: 'partial' });
+
+    const result = await faceProcessor.processPhotoFaces(photoId);
+    expect(result.status).toBe('failed');
+  });
+
+  it('defers a file that exists but cannot be read', async () => {
+    // EACCES / EIO / ESTALE on the file itself, with the mount up: a transient
+    // condition wearing a per-file disguise. Only ENOENT means genuinely gone.
+    const root = path.join(process.env.EXTERNAL_MEDIA_ROOT, 'locked');
+    const dir = path.join(root, 'individual');
+    await fs.promises.mkdir(dir, { recursive: true });
+    const file = path.join(dir, 'a.jpg');
+    await fs.promises.writeFile(file, 'x');
+    await fs.promises.chmod(file, 0o000);
+
+    const { photoId } = await seedExternalPhoto({ externalPath: 'locked' });
+    try {
+      await expect(faceProcessor.processPhotoFaces(photoId))
+        .rejects.toBeInstanceOf(faceProcessor.TransientSourceError);
+    } finally {
+      await fs.promises.chmod(file, 0o644).catch(() => {});
+    }
+  });
+
+  it('still fails managed photos without probing the mount', async () => {
+    // The probe is scoped to external/reference rows: a managed photo with no
+    // preview is broken, and there is no mount to blame.
+    const [e] = await db('events').insert({
+      slug: `tr-m-${Math.random().toString(36).slice(2, 8)}`,
+      event_type: 'wedding',
+      event_name: 'trm',
+      event_date: '2026-01-01',
+      host_email: 'h@example.com',
+      admin_email: 'a@example.com',
+      password_hash: 'x',
+      share_link: `tr-m-${Math.random()}`,
+      expires_at: new Date().toISOString(),
+      face_recognition_enabled: true,
+    }).returning('id');
+    const [p] = await db('photos').insert({
+      event_id: typeof e === 'object' ? e.id : e,
+      filename: 'm.jpg',
+      path: 'trm/m.jpg',
+      type: 'individual',
+      width: 100,
+      height: 100,
+      processing_status: 'complete',
+      face_status: 'processing',
+      source_origin: 'managed',
+    }).returning('id');
+
+    const result = await faceProcessor.processPhotoFaces(typeof p === 'object' ? p.id : p);
+    expect(result.status).toBe('failed');
+  });
+});

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/previewTiers.test.js

@@ -0,0 +1,191 @@
+/**
+ * Responsive preview tiers (#1095).
+ *
+ * A phone can display ~1170px at most, so the single 1920px preview ships
+ * roughly twice the bytes it can use on every lightbox swipe — and the
+ * lightbox prefetches neighbours, so a guest flicking through a wedding
+ * gallery on cellular pays that repeatedly.
+ *
+ * The width is whitelisted rather than free-form: every distinct value is a
+ * permanent cache entry on disk, so an open ?w= is an invitation to fill the
+ * volume with renditions nobody asked for.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+process.env.NODE_ENV = 'test';
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-tiers-'));
+process.env.TEST_DATABASE_PATH = path.join(tmpRoot, 'db.sqlite');
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'tiers-test-secret';
+process.env.STORAGE_PATH = path.join(tmpRoot, 'storage');
+fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
+
+const sharp = require('sharp');
+const imageProcessor = require('../../src/services/imageProcessor');
+const { bootCrmDb } = require('./helpers/crmDb');
+
+let db; let cleanup;
+
+describe('preview tiers (#1095)', () => {
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+  }, 120000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+    await fs.promises.rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+  });
+
+  describe('normalizeTierWidth', () => {
+    const { normalizeTierWidth, PREVIEW_WIDTHS, THUMBNAIL_WIDTHS } = imageProcessor;
+
+    it('accepts every advertised width', () => {
+      for (const w of PREVIEW_WIDTHS) {
+        expect(normalizeTierWidth(String(w), PREVIEW_WIDTHS)).toBe(w);
+      }
+      for (const w of THUMBNAIL_WIDTHS) {
+        expect(normalizeTierWidth(String(w), THUMBNAIL_WIDTHS)).toBe(w);
+      }
+    });
+
+    it('rejects anything not on the list', () => {
+      // The disk-filling cases: arbitrary sizes, and a caller walking a range.
+      for (const bad of ['999', '1921', '0', '-100', '99999']) {
+        expect(normalizeTierWidth(bad, PREVIEW_WIDTHS)).toBeNull();
+      }
+    });
+
+    it('rejects junk without throwing', () => {
+      // Straight off a query string, so it is whatever the client sent.
+      for (const bad of [undefined, null, '', 'abc', '12abc', {}, [], '1e3', 'NaN']) {
+        expect(normalizeTierWidth(bad, PREVIEW_WIDTHS)).toBeNull();
+      }
+    });
+
+    it('does not let a thumbnail width through the preview list', () => {
+      // The two lists are separate on purpose; 600 is a thumb tier, not a
+      // preview tier, and vice versa for 1280.
+      expect(normalizeTierWidth('600', PREVIEW_WIDTHS)).toBeNull();
+      expect(normalizeTierWidth('1280', THUMBNAIL_WIDTHS)).toBeNull();
+    });
+  });
+
+  describe('ensurePreviewImageAtWidth', () => {
+    async function seedPhoto() {
+      const [e] = await db('events').insert({
+        slug: `tier-${Math.random().toString(36).slice(2, 8)}`,
+        event_type: 'wedding',
+        event_name: 'tier',
+        event_date: '2026-01-01',
+        host_email: 'h@example.com',
+        admin_email: 'a@example.com',
+        password_hash: 'x',
+        share_link: `tier-${Math.random()}`,
+        expires_at: new Date().toISOString(),
+      }).returning('id');
+      const eventId = typeof e === 'object' ? e.id : e;
+
+      // A real image on disk under STORAGE_PATH, since the managed branch
+      // resolves through storage rather than a mount.
+      const rel = `events/active/tier/${Math.random().toString(36).slice(2, 8)}.jpg`;
+      const abs = path.join(process.env.STORAGE_PATH, rel);
+      await fs.promises.mkdir(path.dirname(abs), { recursive: true });
+      await sharp({ create: { width: 3000, height: 2000, channels: 3, background: { r: 10, g: 90, b: 160 } } })
+        .jpeg().toFile(abs);
+
+      const [p] = await db('photos').insert({
+        event_id: eventId,
+        filename: path.basename(rel),
+        path: rel.replace(/^events\/active\//, ''),
+        type: 'individual',
+        width: 3000,
+        height: 2000,
+        processing_status: 'complete',
+        source_origin: 'managed',
+      }).returning('id');
+      return db('photos').where({ id: typeof p === 'object' ? p.id : p }).first();
+    }
+
+    it('scopes keys by photo id so two galleries cannot collide', async () => {
+      // The leak: managed auto-imports keep camera basenames, so two events can
+      // each hold an IMG_0001.jpg. A tier is served straight from a cache hit
+      // without re-reading the source, so a shared key hands one gallery's
+      // photo to another.
+      const a = await seedPhoto();
+      const b = await seedPhoto();
+      await db('photos').where({ id: a.id }).update({ path: 'wedding-a/IMG_0001.jpg' });
+      await db('photos').where({ id: b.id }).update({ path: 'wedding-b/IMG_0001.jpg' });
+
+      const keyA = imageProcessor.previewTierKeys(await db('photos').where({ id: a.id }).first())[0];
+      const keyB = imageProcessor.previewTierKeys(await db('photos').where({ id: b.id }).first())[0];
+
+      expect(keyA).not.toBe(keyB);
+      expect(keyA).toContain(`p${a.id}_`);
+      expect(keyB).toContain(`p${b.id}_`);
+    });
+
+    it('derives every non-default tier key for cleanup', () => {
+      // Tiers live outside preview_path, so delete/archive/regenerate have no
+      // other way to find them. 1920 is excluded because that IS preview_path.
+      const keys = imageProcessor.previewTierKeys({ id: 5, path: 'e/a.jpg', source_origin: 'managed' });
+      expect(keys).toHaveLength(imageProcessor.PREVIEW_WIDTHS.length - 1);
+      expect(keys.some((k) => k.includes('w1920'))).toBe(false);
+      expect(keys.every((k) => k.includes('p5_'))).toBe(true);
+    });
+
+    it('deletePreviewTiers removes generated tiers from storage', async () => {
+      const photo = await seedPhoto();
+      const key = await imageProcessor.ensurePreviewImageAtWidth(photo, 640);
+      const abs = path.join(process.env.STORAGE_PATH, key);
+      expect(fs.existsSync(abs)).toBe(true);
+
+      await imageProcessor.deletePreviewTiers(await db('photos').where({ id: photo.id }).first());
+      expect(fs.existsSync(abs)).toBe(false);
+    });
+
+    it('produces a distinct key per width and never touches preview_path', async () => {
+      const photo = await seedPhoto();
+
+      const small = await imageProcessor.ensurePreviewImageAtWidth(photo, 640);
+      expect(small).toContain('preview_w640_');
+
+      // The extra tiers are cache, not state. Writing them to the row would
+      // mean the last size requested silently becomes "the" preview.
+      const row = await db('photos').where({ id: photo.id }).first();
+      expect(row.preview_path == null || !String(row.preview_path).includes('w640')).toBe(true);
+    });
+
+    it('resolves the default width to the canonical preview, not a w1920 copy', async () => {
+      // Otherwise every existing install grows a duplicate of every preview it
+      // already has, for no benefit.
+      const photo = await seedPhoto();
+      const def = await imageProcessor.ensurePreviewImageAtWidth(photo, 1920);
+      expect(def).not.toContain('preview_w1920_');
+    });
+
+    it('reuses the cached tier instead of regenerating', async () => {
+      const photo = await seedPhoto();
+      const first = await imageProcessor.ensurePreviewImageAtWidth(photo, 1280);
+      expect(first).toBeTruthy();
+
+      const abs = path.join(process.env.STORAGE_PATH, first);
+      const before = (await fs.promises.stat(abs)).mtimeMs;
+      await new Promise((r) => setTimeout(r, 20));
+
+      const second = await imageProcessor.ensurePreviewImageAtWidth(photo, 1280);
+      expect(second).toBe(first);
+      expect((await fs.promises.stat(abs)).mtimeMs).toBe(before);
+    });
+
+    it('actually resizes to the requested tier', async () => {
+      const photo = await seedPhoto();
+      const key = await imageProcessor.ensurePreviewImageAtWidth(photo, 640);
+      const meta = await sharp(path.join(process.env.STORAGE_PATH, key)).metadata();
+      // 3000x2000 constrained to a 640 long edge.
+      expect(Math.max(meta.width, meta.height)).toBe(640);
+      expect(meta.height).toBe(Math.round(640 * (2000 / 3000)));
+    });
+  });
+});

backend/__tests__/integration/publishPasswordPolicy.test.js

@@ -1,114 +0,0 @@
-/**
- * Publishing must not be a way around the configured gallery password policy.
- *
- * `POST /:id/publish` (#627) re-hashes `password_hash` from a plaintext the
- * admin re-types in the publish dialog, and validated it with nothing but
- * express-validator's `isLength({ min: 6 })`. So the configured complexity —
- * moderate by default, meaning 8 characters plus upper, lower and a digit —
- * governed event creation and password reset, while this door accepted
- * `aaaaaa` and made it the live gallery password.
- *
- * Not an escalation: it needs admin auth plus events.edit, and such an admin
- * could already set a weak password elsewhere. It is a policy gap — the admin
- * UI advertises a complexity level this write path did not enforce.
- */
-
-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-pubpolicy-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'publish-policy-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-pubpolicy-storage-'));
-
-const request = require('supertest');
-const {
-  bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken, buildRouteApp,
-} = require('./helpers/crmDb');
-
-describe('publish enforces the gallery password policy', () => {
-  let db; let cleanup; let app; let token;
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    const { adminId } = await seedMinimal(db);
-    await assignAdminRole(db, adminId, 'admin');
-    token = mintAdminToken(adminId);
-    app = buildRouteApp('/admin/events', require('../../src/routes/adminEvents'));
-  }, 120000);
-
-  afterAll(async () => { if (cleanup) await cleanup(); });
-
-  async function seedDraft(slug) {
-    const [row] = await db('events').insert({
-      slug,
-      event_type: 'wedding',
-      event_name: `Event ${slug}`,
-      event_date: '2026-09-01',
-      host_email: 'client@example.com',
-      admin_email: 'admin@example.com',
-      password_hash: 'original-hash',
-      require_password: 1,
-      share_link: `/gallery/${slug}/share`,
-      share_token: `${slug}-token`,
-      expires_at: new Date(Date.now() + 7 * 24 * 3600 * 1000).toISOString(),
-      is_active: 1,
-      is_archived: 0,
-      is_draft: 1,
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    return typeof row === 'object' ? row.id : row;
-  }
-
-  it('refuses a password that misses the configured complexity', async () => {
-    const id = await seedDraft('weak-publish');
-
-    const res = await request(app)
-      .post(`/admin/events/${id}/publish`)
-      .set('Authorization', `Bearer ${token}`)
-      .send({ password: 'aaaaaa' });
-
-    expect(res.status).toBe(400);
-    expect(res.body.error).toMatch(/security requirements/i);
-
-    // Rejected BEFORE the write, not after — the gallery must be untouched,
-    // and still a draft.
-    const after = await db('events').where({ id }).first();
-    expect(after.password_hash).toBe('original-hash');
-    expect(after.is_draft === 1 || after.is_draft === true).toBe(true);
-  });
-
-  it('still accepts a password that meets it', async () => {
-    const id = await seedDraft('strong-publish');
-
-    const res = await request(app)
-      .post(`/admin/events/${id}/publish`)
-      .set('Authorization', `Bearer ${token}`)
-      .send({ password: 'Sup3r-Secret' });
-
-    expect(res.status).toBe(200);
-
-    const bcrypt = require('bcrypt');
-    const after = await db('events').where({ id }).first();
-    expect(after.password_hash).not.toBe('original-hash');
-    expect(await bcrypt.compare('Sup3r-Secret', after.password_hash)).toBe(true);
-  });
-
-  it('leaves a publish without a password alone', async () => {
-    // The legacy sentinel path: no password in the body means no rehash, so
-    // the policy has nothing to check and must not block the publish.
-    const id = await seedDraft('no-password-publish');
-
-    const res = await request(app)
-      .post(`/admin/events/${id}/publish`)
-      .set('Authorization', `Bearer ${token}`)
-      .send({});
-
-    expect(res.status).toBe(200);
-    const after = await db('events').where({ id }).first();
-    expect(after.password_hash).toBe('original-hash');
-  });
-});

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__/integration/uncategorizedFilter.test.js

@@ -1,107 +0,0 @@
-/**
- * The admin photo list's category filter, and the value it answers to (#1211).
- *
- * The frontend used to send `category_id=0` for "Uncategorized". This route
- * skips `'0'` outright — the guard reads `category_id !== '0'` — so no
- * condition was applied and the whole event came back. Four lines below that
- * guard sits the branch that does the work, keyed on the literal
- * `uncategorized`, which nothing was sending.
- *
- * Reported in #1209 by someone trying to isolate a few thousand uncategorised
- * imports. The frontend half is fixed in PhotoFilters; this pins the backend
- * half of the same contract, because the failure mode was the two ends
- * disagreeing about a string and neither one being wrong on its own.
- */
-
-const request = require('supertest');
-const express = require('express');
-
-const { bootCrmDb, seedMinimal } = require('./helpers/crmDb');
-
-describe('admin photo list — uncategorized filter (#1211)', () => {
-  let db; let cleanup; let app;
-  let eventId; let categoryId;
-  let uncategorisedIds; let categorisedId;
-
-  const list = async (query = '') => {
-    const res = await request(app).get(`/api/admin/events/${eventId}/photos${query}`);
-    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 () => {
-    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(),
-    }));
-    jest.doMock('../../src/middleware/ownership', () => ({
-      requireEventOwnership: (_req, _res, next) => next(),
-    }));
-    jest.doMock('../../src/utils/logger', () => ({
-      debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn(),
-    }));
-
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-
-    const [ev] = await db('events').insert({
-      slug: 'uncat-filter', event_type: 'wedding', event_name: 'Uncat Filter',
-      event_date: '2026-08-01', host_email: 'h@example.com', admin_email: 'a@example.com',
-      password_hash: 'x', share_link: '/gallery/uncat-filter/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 [cat] = await db('photo_categories')
-      .insert({ name: 'Ceremony', slug: 'ceremony', event_id: eventId })
-      .returning('id');
-    categoryId = typeof cat === 'object' ? cat.id : cat;
-
-    const insertPhoto = async (filename, category) => {
-      const [p] = await db('photos').insert({
-        event_id: eventId, filename, path: `events/uncat/${filename}`,
-        type: 'individual', category_id: category,
-        uploaded_at: new Date().toISOString(),
-      }).returning('id');
-      return typeof p === 'object' ? p.id : p;
-    };
-
-    // Two with no category — the shape a plugin upload leaves behind — and one
-    // filed properly, so a filter that does nothing is visibly different from
-    // a filter that works.
-    uncategorisedIds = [await insertPhoto('a.jpg', null), await insertPhoto('b.jpg', null)];
-    categorisedId = await insertPhoto('c.jpg', categoryId);
-    uncategorisedIds.sort((a, b) => a - b);
-
-    app = express();
-    app.use(express.json());
-    app.use('/api/admin/events', require('../../src/routes/adminPhotos'));
-  }, 180000);
-
-  afterAll(async () => { if (cleanup) await cleanup(); });
-
-  it('returns only the photos with no category', async () => {
-    expect(await list('?category_id=uncategorized')).toEqual(uncategorisedIds);
-  });
-
-  it('returns everything when no category filter is given', async () => {
-    expect(await list()).toEqual([...uncategorisedIds, categorisedId].sort((a, b) => a - b));
-  });
-
-  it('still filters by a real category id', async () => {
-    expect(await list(`?category_id=${categoryId}`)).toEqual([categorisedId]);
-  });
-
-  it('treats 0 as no filter at all', async () => {
-    // Pinning the behaviour that made the bug silent rather than loud: '0' is
-    // not "uncategorized" and never was, it simply falls through the guard. A
-    // future change that made 0 mean uncategorized here would be fine too —
-    // but it must be a decision, not an accident, and this test forces it.
-    expect(await list('?category_id=0')).toEqual([...uncategorisedIds, categorisedId].sort((a, b) => a - b));
-  });
-});

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/authMustChangePassword.test.js

@@ -1,123 +0,0 @@
-/**
- * GHSA-h4w8-57xq-53fx enforcement half: `must_change_password` was written
- * by the admin password-reset flow (userManagementService.resetAdminPassword)
- * and returned in a few response payloads, but no route-blocking logic ever
- * checked it — a reset admin could keep using the old/weak password on every
- * protected route indefinitely. adminAuth() is now the server-side backstop:
- * a flagged admin gets 403 MUST_CHANGE_PASSWORD on everything except the
- * routes they need to clear the flag (change-password) or leave (logout).
- *
- * Mirrors the mocking shape of adminAuthRoleFallback.test.js — a stub `db`
- * chain, no real SQLite needed, so this stays a fast unit test.
- */
-
-const jwt = require('jsonwebtoken');
-
-jest.mock('../../src/utils/tokenRevocation', () => ({ isTokenRevoked: jest.fn().mockResolvedValue(false) }));
-jest.mock('../../src/utils/logger', () => ({ warn: jest.fn(), error: jest.fn(), debug: jest.fn(), info: jest.fn() }));
-
-let mockMustChangePassword = false;
-const mockAdminRow = { id: 7, username: 'scoped', email: 's@example.com', password_changed_at: null, role_id: 1, role_name: 'editor' };
-
-jest.mock('../../src/database/db', () => ({
-  db: () => ({
-    leftJoin() { return this; },
-    where() { return this; },
-    select() { return this; },
-    first: () => Promise.resolve({ ...mockAdminRow, must_change_password: mockMustChangePassword }),
-  }),
-}));
-
-const { adminAuth } = require('../../src/middleware/auth');
-
-const SECRET = 'test-secret-for-must-change-password';
-
-function makeReq(originalUrl) {
-  const token = jwt.sign(
-    { id: mockAdminRow.id, type: 'admin' },
-    SECRET,
-    { algorithm: 'HS256', issuer: 'picpeak-auth' },
-  );
-  return { headers: { authorization: `Bearer ${token}` }, ip: '127.0.0.1', connection: {}, originalUrl };
-}
-
-function makeRes() {
-  return {
-    statusCode: null,
-    body: null,
-    status(code) { this.statusCode = code; return this; },
-    json(payload) { this.body = payload; return this; },
-  };
-}
-
-describe('adminAuth must_change_password enforcement (GHSA-h4w8-57xq-53fx)', () => {
-  const OLD_SECRET = process.env.JWT_SECRET;
-  beforeAll(() => { process.env.JWT_SECRET = SECRET; });
-  afterAll(() => { process.env.JWT_SECRET = OLD_SECRET; });
-  beforeEach(() => { mockMustChangePassword = false; });
-
-  it('blocks an arbitrary protected route with 403 MUST_CHANGE_PASSWORD when the flag is set', async () => {
-    mockMustChangePassword = true;
-    const req = makeReq('/api/admin/dashboard/stats');
-    const res = makeRes();
-    const next = jest.fn();
-
-    await adminAuth(req, res, next);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(403);
-    expect(res.body).toEqual(expect.objectContaining({ code: 'MUST_CHANGE_PASSWORD' }));
-    expect(req.admin).toBeUndefined();
-  });
-
-  it('does not block when the flag is not set', async () => {
-    mockMustChangePassword = false;
-    const req = makeReq('/api/admin/dashboard/stats');
-    const res = makeRes();
-    const next = jest.fn();
-
-    await adminAuth(req, res, next);
-
-    expect(next).toHaveBeenCalled();
-    expect(req.admin.mustChangePassword).toBe(false);
-  });
-
-  it.each([
-    ['/api/admin/auth/change-password'],
-    ['/api/admin/auth/logout'],
-  ])('still allows %s through when the flag is set', async (originalUrl) => {
-    mockMustChangePassword = true;
-    const req = makeReq(originalUrl);
-    const res = makeRes();
-    const next = jest.fn();
-
-    await adminAuth(req, res, next);
-
-    expect(next).toHaveBeenCalled();
-    expect(req.admin.mustChangePassword).toBe(true);
-    expect(res.statusCode).toBeNull();
-  });
-
-  it('allows the exempt change-password path even with a query string', async () => {
-    mockMustChangePassword = true;
-    const req = makeReq('/api/admin/auth/change-password?foo=bar');
-    const res = makeRes();
-    const next = jest.fn();
-
-    await adminAuth(req, res, next);
-
-    expect(next).toHaveBeenCalled();
-  });
-
-  it('does not exempt a route that merely starts with the change-password path', async () => {
-    mockMustChangePassword = true;
-    const req = makeReq('/api/admin/auth/change-password-history');
-    const res = makeRes();
-    const next = jest.fn();
-
-    await adminAuth(req, res, next);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(res.statusCode).toBe(403);
-  });
-});

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__/middleware/maintenance.spaShell.test.js

@@ -0,0 +1,123 @@
+/**
+ * Regression test for the maintenance-mode lockout in single-container mode.
+ *
+ * In the compose stack nginx serves the frontend, so a request for /admin/login
+ * or /gallery/<slug> never reaches Express. The all-in-one image (#1042) has no
+ * nginx: server.js serves the SPA itself, and maintenanceMiddleware is mounted
+ * far ahead of that static block. Gating those paths therefore answered the
+ * HTML document with 503 JSON, which broke two things at once —
+ *
+ *   1. an admin who enabled maintenance mode could never disable it, because
+ *      /admin/login and its /assets/ bundle would not load (the login *API* was
+ *      already exempt, but nothing could call it), and
+ *   2. a guest saw raw JSON instead of the branded maintenance screen the
+ *      frontend already ships.
+ *
+ * The shell is inert HTML: it boots, calls /api/public/settings (exempt) and
+ * renders MaintenanceMode itself, so letting it through costs nothing.
+ *
+ * The dividing line is taken from frontend/nginx.conf rather than invented:
+ * paths nginx answers from the frontend container are exempt, paths it
+ * proxy_passes to the backend stay gated. That makes the all-in-one image
+ * behave exactly like compose in both directions. The gated half is where the
+ * risk lives — a negative "everything that is not an API is a shell" rule
+ * looks right and quietly un-gates /og/ (event names, cover images) and the
+ * public CMS at the site root — so most of the cases below assert it.
+ */
+
+const { maintenanceMiddleware } = require('../../src/middleware/maintenance');
+
+jest.mock('../../src/database/db', () => {
+  const settings = { setting_key: 'general_maintenance_mode', setting_value: 'true' };
+  const db = jest.fn(() => ({
+    where: jest.fn().mockReturnThis(),
+    first: jest.fn().mockResolvedValue(settings),
+  }));
+  return { db };
+});
+jest.mock('../../src/utils/logger', () => ({
+  error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(),
+}));
+
+// Maintenance state is cached for a minute; each case starts from a clean read.
+const { clearMaintenanceCache } = require('../../src/middleware/maintenance');
+
+async function run(path, { method = 'GET', authorization } = {}) {
+  clearMaintenanceCache();
+  const req = { path, method, headers: authorization ? { authorization } : {} };
+  const res = {
+    statusCode: null,
+    body: null,
+    status(code) { this.statusCode = code; return this; },
+    json(payload) { this.body = payload; return this; },
+  };
+  const next = jest.fn();
+  await maintenanceMiddleware(req, res, next);
+  return { passed: next.mock.calls.length === 1, status: res.statusCode, body: res.body };
+}
+
+describe('maintenanceMiddleware — SPA shell vs API split', () => {
+  describe('passes the frontend shell through so the branded screen can render', () => {
+    it.each([
+      ['/admin', 'admin shell entry'],
+      ['/admin/login', 'the page that calls the exempt login API'],
+      ['/assets/index-abc123.js', 'hashed bundle the shell loads'],
+      ['/gallery/some-event', 'guest gallery route'],
+      ['/customer/portal', 'customer portal route'],
+    ])('%s (%s)', async (path) => {
+      const { passed } = await run(path);
+      expect(passed).toBe(true);
+    });
+  });
+
+  describe('still gates everything that is not a shell', () => {
+    it.each([
+      ['/api/gallery/some-event/verify', 'public gallery API'],
+      ['/api/photos/1', 'photo API'],
+      ['/photos/anything.jpg', 'backend-owned photo mount'],
+      ['/thumbnails/anything.jpg', 'backend-owned thumbnail mount'],
+      ['/fonts/anything.woff2', 'backend-owned font mount'],
+      // nginx proxy_passes these to the backend, so compose gates them today
+      // and the all-in-one image must not be the one deployment that does not.
+      ['/', 'site root — nginx `location = /` hands this to the public CMS'],
+      ['/og/gallery/some-event', 'OG renderer: leaks the event name'],
+      ['/og/gallery/some-event/cover', 'OG cover: leaks the hero thumbnail'],
+      ['/s/abc123', 'short-link renderer'],
+      ['/robots.txt', 'proxied one-to-one by nginx'],
+      ['/favicon.ico', 'proxied one-to-one by nginx'],
+    ])('%s (%s) returns 503', async (path) => {
+      const { passed, status, body } = await run(path);
+      expect(passed).toBe(false);
+      expect(status).toBe(503);
+      expect(body).toMatchObject({ maintenance: true });
+    });
+
+    it('does not let a non-GET request masquerade as a shell load', async () => {
+      const { passed, status } = await run('/api/gallery/some-event/verify', { method: 'POST' });
+      expect(passed).toBe(false);
+      expect(status).toBe(503);
+    });
+  });
+
+  describe('keeps the pre-existing admin exemptions', () => {
+    it('admin login API stays reachable', async () => {
+      expect((await run('/api/auth/admin/login', { method: 'POST' })).passed).toBe(true);
+    });
+
+    it('/api/public/settings stays reachable so the shell can read the flag', async () => {
+      expect((await run('/api/public/settings')).passed).toBe(true);
+    });
+
+    it('an authenticated admin still reaches /api/admin', async () => {
+      const { passed } = await run('/api/admin/events', { authorization: 'Bearer token' });
+      expect(passed).toBe(true);
+    });
+
+    it('an unauthenticated /api/admin request is not served by this middleware', async () => {
+      // isAdminRoute suppresses the 503 so the auth layer can answer 401.
+      const { passed, status } = await run('/api/admin/events');
+      expect(passed).toBe(true);
+      expect(status).toBeNull();
+    });
+  });
+});

backend/__tests__/middleware/photoAuth.thumbnailScope.test.js

@@ -0,0 +1,103 @@
+/**
+ * Regression test for the cross-event thumbnail enumeration leak.
+ *
+ * Thumbnails are served flat from /thumbnails/thumb_<name> with
+ * deterministic, enumerable filenames. photoAuth previously granted any
+ * holder of a gallery token for ANY active event access to ANY thumbnail
+ * (it set eventSlug=null and returned next() as long as the token's event
+ * existed), so a visitor to one gallery could pull another (password-
+ * protected) gallery's entire thumbnail set. The fix scopes thumbnail
+ * access to the token's event by matching the requested file against
+ * photos.thumbnail_path for that event_id.
+ */
+
+process.env.JWT_SECRET = 'test-secret-thumbnail-scope-000000000000';
+
+const jwt = require('jsonwebtoken');
+
+// Two events, each owning one thumbnail. The photos mock resolves a row
+// only when BOTH event_id and thumbnail_path match — i.e. it models the
+// real ownership query.
+const EVENTS = [
+  { id: 10, slug: 'event-a', is_active: 1 },
+  { id: 20, slug: 'event-b', is_active: 1 },
+];
+const PHOTOS = [
+  { id: 1, event_id: 10, thumbnail_path: 'thumbnails/thumb_event-a_ceremony_0001.jpg' },
+  { id: 2, event_id: 20, thumbnail_path: 'thumbnails/thumb_event-b_ceremony_0001.jpg' },
+];
+
+jest.mock('../../src/database/db', () => ({
+  db: (table) => ({
+    _cond: null,
+    where(cond) { this._cond = cond; return this; },
+    first() {
+      if (table === 'events') {
+        return Promise.resolve(EVENTS.find((e) => e.id === this._cond.id) || null);
+      }
+      if (table === 'photos') {
+        return Promise.resolve(
+          PHOTOS.find((p) => p.event_id === this._cond.event_id
+            && p.thumbnail_path === this._cond.thumbnail_path) || null
+        );
+      }
+      return Promise.resolve(null);
+    },
+  }),
+}));
+
+jest.mock('../../src/utils/logger', () => ({
+  info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn(),
+}));
+
+const photoAuth = require('../../src/middleware/photoAuth');
+
+function galleryToken(eventId) {
+  return jwt.sign({ type: 'gallery', eventId }, process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
+}
+
+function makeReqRes(token, thumbPath) {
+  const req = { path: thumbPath, headers: { authorization: `Bearer ${token}` }, cookies: {} };
+  const res = {
+    statusCode: null,
+    body: null,
+    status(code) { this.statusCode = code; return this; },
+    json(payload) { this.body = payload; return this; },
+  };
+  return { req, res };
+}
+
+describe('photoAuth — thumbnail ownership scoping', () => {
+  it('denies a gallery token for event A fetching event B\'s thumbnail', async () => {
+    const { req, res } = makeReqRes(galleryToken(10), '/thumb_event-b_ceremony_0001.jpg');
+    const next = jest.fn();
+
+    await photoAuth(req, res, next);
+
+    // Access denied: middleware must not pass the request through.
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBeGreaterThanOrEqual(400);
+    expect(req.event).toBeUndefined();
+  });
+
+  it('allows a gallery token to fetch its own event\'s thumbnail', async () => {
+    const { req, res } = makeReqRes(galleryToken(20), '/thumb_event-b_ceremony_0001.jpg');
+    const next = jest.fn();
+
+    await photoAuth(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(req.event).toMatchObject({ id: 20 });
+  });
+
+  it('denies a traversal / foreign filename that matches no owned thumbnail', async () => {
+    const { req, res } = makeReqRes(galleryToken(10), '/thumb_../../etc/passwd');
+    const next = jest.fn();
+
+    await photoAuth(req, res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.statusCode).toBeGreaterThanOrEqual(400);
+    expect(req.event).toBeUndefined();
+  });
+});

backend/__tests__/middleware/securityHardeningBatch2.test.js

@@ -1,70 +0,0 @@
-/**
- * Second security sweep on the same branch as the password-strength DoS fix
- * (stable port: the maintenance and admin-preview cases do not apply here).
- * Each block pins one gap the audit found:
- *
- *  - the general rate limiter skipped anyone holding ANY verified JWT,
- *    including a gallery token minted for free on password-less galleries
- *  - the multipart branch of the CSRF Content-Type gate accepted cross-site
- *    form posts
- */
-const jwt = require('jsonwebtoken');
-
-process.env.JWT_SECRET = 'hardening-batch2-secret';
-
-const fake = { maintenance: 'true', revoked: false, beforeCutoff: false, admin: { id: 1, password_changed_at: null } };
-
-jest.mock('../../src/database/db', () => {
-  const db = jest.fn((table) => {
-    const q = {
-      where: jest.fn().mockReturnThis(),
-      select: jest.fn().mockReturnThis(),
-      first: jest.fn(async () => {
-        if (table === 'app_settings') {
-          return { setting_key: 'general_maintenance_mode', setting_value: fake.maintenance };
-        }
-        if (table === 'admin_users') return fake.admin;
-        return null;
-      }),
-    };
-    return q;
-  });
-  return { db, withRetry: (fn) => fn() };
-});
-jest.mock('../../src/utils/logger', () => ({ error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() }));
-process.env.FRONTEND_URL = 'https://photos.example.com';
-
-const { isAuthenticated } = require('../../src/services/rateLimitService');
-const { multipartOriginAllowed } = require('../../src/utils/requestOrigin');
-
-const iat = Math.floor(Date.now() / 1000) - 10;
-const adminToken = (extra = {}) => jwt.sign({ type: 'admin', id: 1, iat, ...extra }, process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
-const galleryToken = () => jwt.sign({ type: 'gallery', eventId: 1, iat }, process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
-
-describe('general rate limiter skip', () => {
-  const req = (token) => ({ path: '/api/gallery/x/photos', headers: { authorization: `Bearer ${token}` }, cookies: {} });
-  it('is granted to an admin session', () => {
-    expect(isAuthenticated(req(adminToken()))).toBe(true);
-  });
-  it('is NOT granted to a gallery token', () => {
-    expect(isAuthenticated(req(galleryToken()))).toBe(false);
-  });
-});
-
-describe('multipart origin gate', () => {
-  const req = (headers) => ({ headers: { host: 'photos.example.com', ...headers } });
-  it('accepts same-origin, same-site and non-browser requests', () => {
-    expect(multipartOriginAllowed(req({ 'sec-fetch-site': 'same-origin' }))).toBe(true);
-    expect(multipartOriginAllowed(req({ 'sec-fetch-site': 'same-site' }))).toBe(true);
-    expect(multipartOriginAllowed(req({ 'sec-fetch-site': 'none' }))).toBe(true);
-    expect(multipartOriginAllowed(req({}))).toBe(true);
-    expect(multipartOriginAllowed(req({ origin: 'https://photos.example.com' }))).toBe(true);
-    // Same-origin install without FRONTEND_URL: Origin matches the Host.
-    expect(multipartOriginAllowed({ headers: { host: 'gallery.local', origin: 'http://gallery.local' } })).toBe(true);
-  });
-  it('rejects cross-site form posts', () => {
-    expect(multipartOriginAllowed(req({ 'sec-fetch-site': 'cross-site' }))).toBe(false);
-    expect(multipartOriginAllowed(req({ origin: 'https://evil.example' }))).toBe(false);
-    expect(multipartOriginAllowed(req({ origin: 'null' }))).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_add_face_recognition.test.js

@@ -0,0 +1,166 @@
+/**
+ * Migration 177 (#1074) — face recognition schema.
+ *
+ * The acceptance criteria for #1074 name three properties explicitly, so
+ * they get tests rather than a manual check:
+ *
+ *   - idempotent on re-run,
+ *   - a working down(),
+ *   - and — the one that matters most — installing it must NOT enqueue
+ *     anything. A `face_status` column defaulting to 'pending' would put
+ *     every existing photo on every install into a queue the operator never
+ *     asked for, on installs with no sidecar at all.
+ */
+
+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-mig177-')), 'db.sqlite',
+);
+process.env.JWT_SECRET = process.env.JWT_SECRET || 'mig177-test-secret';
+
+const { bootCrmDb } = require('../integration/helpers/crmDb');
+const migration = require('../../migrations/core/177_add_face_recognition');
+
+describe('migration 177 — face recognition schema', () => {
+  let db; let cleanup;
+
+  beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
+
+  it('creates both tables with the columns the pipeline writes', async () => {
+    expect(await db.schema.hasTable('photo_faces')).toBe(true);
+    expect(await db.schema.hasTable('event_people')).toBe(true);
+
+    for (const col of [
+      'photo_id', 'event_id', 'bbox_x', 'bbox_y', 'bbox_w', 'bbox_h',
+      'det_score', 'yaw', 'pitch', 'blur', 'embedding', 'model_version',
+      'person_id', 'created_at',
+    ]) {
+      expect(await db.schema.hasColumn('photo_faces', col)).toBe(true);
+    }
+
+    for (const col of [
+      'event_id', 'label', 'cover_face_id', 'centroid', 'face_count_total',
+      'model_version', 'is_hidden', 'is_ignored',
+    ]) {
+      expect(await db.schema.hasColumn('event_people', col)).toBe(true);
+    }
+  });
+
+  it('adds the photos and events columns', async () => {
+    for (const col of ['face_status', 'face_count', 'face_started_at', 'face_error']) {
+      expect(await db.schema.hasColumn('photos', col)).toBe(true);
+    }
+    for (const col of [
+      'face_recognition_enabled', 'faces_visible_to_guests', 'faces_last_scan_at',
+    ]) {
+      expect(await db.schema.hasColumn('events', col)).toBe(true);
+    }
+  });
+
+  it('enqueues nothing — face_status has no default', async () => {
+    // The whole "zero behaviour change by default" guarantee rests on this.
+    const [{ id: eventId }] = await db('events').insert({
+      slug: 'mig177-event',
+      event_type: 'wedding',
+      event_name: 'Migration 177',
+      event_date: '2026-01-01',
+      host_email: 'h@example.com',
+      admin_email: 'a@example.com',
+      password_hash: 'x',
+      share_link: 'mig177-share',
+      expires_at: new Date().toISOString(),
+    }).returning('id');
+
+    const eid = typeof eventId === 'object' ? eventId.id : eventId;
+    await db('photos').insert({
+      event_id: eid, filename: 'a.jpg', path: '/tmp/a.jpg', type: 'individual',
+    });
+
+    const row = await db('photos').where({ event_id: eid }).first();
+    expect(row.face_status).toBeNull();
+    expect(await db('photo_faces').count({ c: '*' }).first()).toMatchObject({ c: 0 });
+  });
+
+  it('seeds the tunable thresholds rather than hardcoding them', async () => {
+    // Immich's clustering guide exists because no single threshold survives
+    // contact with every library — these must be operator-reachable.
+    const keys = [
+      'face_match_threshold', 'face_min_cluster_size',
+      'face_quality_min_score', 'face_quality_min_px',
+    ];
+    const rows = await db('app_settings').whereIn('setting_key', keys);
+    expect(rows).toHaveLength(keys.length);
+    expect(rows.every((r) => r.setting_type === 'faces')).toBe(true);
+  });
+
+  it('is idempotent on re-run', async () => {
+    await expect(migration.up(db)).resolves.not.toThrow();
+    // And did not duplicate the settings rows.
+    const rows = await db('app_settings').where('setting_key', 'face_match_threshold');
+    expect(rows).toHaveLength(1);
+  });
+
+  it('down() removes everything it added, and up() restores it', async () => {
+    await migration.down(db);
+
+    expect(await db.schema.hasTable('photo_faces')).toBe(false);
+    expect(await db.schema.hasTable('event_people')).toBe(false);
+    expect(await db.schema.hasColumn('photos', 'face_status')).toBe(false);
+    expect(await db.schema.hasColumn('events', 'face_recognition_enabled')).toBe(false);
+    expect(await db('app_settings').where('setting_key', 'face_match_threshold')).toHaveLength(0);
+
+    await migration.up(db);
+    expect(await db.schema.hasTable('photo_faces')).toBe(true);
+    expect(await db.schema.hasColumn('photos', 'face_status')).toBe(true);
+  });
+
+  it('cascades face rows when a photo is deleted', async () => {
+    // #1074 acceptance criterion: deleting a photo removes its face rows.
+    //
+    // SQLite ignores foreign keys unless the pragma is on, and PicPeak does
+    // NOT enable it globally (a large amount of existing data and fixtures
+    // would start failing). So the cascade below proves only that the schema
+    // declares it correctly — the code does not RELY on it. Deletion paths
+    // purge face rows explicitly; see faceProcessor.purgeEvent /
+    // purgePhotoFaces and the erasure tests in facePrivacy.test.js.
+    await db.raw('PRAGMA foreign_keys = ON');
+
+    const [{ id: eventId }] = await db('events').insert({
+      slug: 'mig177-cascade',
+      event_type: 'wedding',
+      event_name: 'Cascade',
+      event_date: '2026-01-01',
+      host_email: 'h@example.com',
+      admin_email: 'a@example.com',
+      password_hash: 'x',
+      share_link: 'mig177-cascade-share',
+      expires_at: new Date().toISOString(),
+    }).returning('id');
+    const eid = typeof eventId === 'object' ? eventId.id : eventId;
+
+    const [{ id: photoId }] = await db('photos')
+      .insert({ event_id: eid, filename: 'c.jpg', path: '/tmp/c.jpg', type: 'individual' })
+      .returning('id');
+    const pid = typeof photoId === 'object' ? photoId.id : photoId;
+
+    await db('photo_faces').insert({
+      photo_id: pid,
+      event_id: eid,
+      bbox_x: 1, bbox_y: 2, bbox_w: 3, bbox_h: 4,
+      model_version: 'test',
+      created_at: new Date().toISOString(),
+    });
+    expect(await db('photo_faces').where({ photo_id: pid })).toHaveLength(1);
+
+    await db('photos').where({ id: pid }).del();
+    expect(await db('photo_faces').where({ photo_id: pid })).toHaveLength(0);
+  });
+});

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/adminContractsSignedPdfPathTraversal.test.js

@@ -1,126 +0,0 @@
-/**
- * Same bug class as GHSA-9q5j-vqfw-32hr (fixed in adminEvents/logo.js) —
- * the signed-PDF upload's multer `filename` callback built the stored
- * path directly from `req.params.id` with no integer validation:
- *
- *   filename: (req, file, cb) => {
- *     cb(null, `contract-${req.params.id}-${Date.now()}${ext}`);
- *   }
- *
- * `POST /:id/upload-signed-pdf` declares `param('id').isInt({ min: 1 })`,
- * but express-validator's check only runs inside the route handler via
- * validateRequest(req) — AFTER multer has already parsed the multipart
- * body and invoked the filename callback. A traversal payload in the raw
- * `:id` URL segment reaches multer completely unvalidated.
- *
- * Fixed by rejecting any non-positive-integer id before it is used to
- * build the filename, independent of the declared-but-too-late
- * express-validator check.
- */
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
-// ALLOWED_MEDIA_TYPES in fileSecurityUtils.js only defines image/video
-// entries, so the route's real fileFilter (validateFileType(..., ['application/pdf']))
-// rejects every PDF upload with "Only PDF files are allowed" — a
-// separate, pre-existing bug unrelated to the path-traversal fix under
-// test here (also present in publicContracts.js, which is why neither
-// suite exercises a successful upload). Stub validateFileType so this
-// suite can drive the full route, including the filename-callback fix,
-// end-to-end.
-jest.mock('../../src/utils/fileSecurityUtils', () => {
-  const actual = jest.requireActual('../../src/utils/fileSecurityUtils');
-  return {
-    ...actual,
-    validateFileType: (filename, mimetype, allowedTypes) => allowedTypes.includes(mimetype),
-  };
-});
-
-process.env.NODE_ENV = 'test';
-process.env.TEST_DATABASE_PATH = path.join(
-  fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-contracts-signed-pdf-')), 'db.sqlite'
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'admin-contracts-signed-pdf-test-secret';
-
-const request = require('supertest');
-const {
-  bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken, buildRouteApp,
-} = require('../integration/helpers/crmDb');
-
-describe('POST /api/admin/contracts/:id/upload-signed-pdf — path traversal guard', () => {
-  let db; let cleanup; let app; let adminId; let customerId; let token;
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    ({ adminId, customerId } = await seedMinimal(db));
-    await assignAdminRole(db, adminId, 'super_admin');
-    token = mintAdminToken(adminId);
-
-    // Feature flag defaults OFF on a fresh install — the contracts
-    // router 403s every route until it's on.
-    await db('feature_flags').where({ key: 'contracts' }).update({ value: true });
-
-    app = buildRouteApp('/api/admin/contracts', require('../../src/routes/adminContracts'));
-  }, 120000);
-
-  afterAll(async () => { await cleanup(); });
-
-  const auth = (req) => req.set('Authorization', `Bearer ${token}`);
-  const signedDir = () => path.join(process.env.STORAGE_PATH, 'uploads/contracts/signed');
-
-  async function insertContract(over = {}) {
-    const base = {
-      contract_number: `K-TEST-${Math.random().toString(16).slice(2, 8)}`,
-      customer_account_id: customerId,
-      title: 'Test Contract',
-      issue_date: new Date().toISOString().slice(0, 10),
-      status: 'sent',
-      language: 'de',
-      created_at: new Date().toISOString(),
-      ...over,
-    };
-    const inserted = await db('contracts').insert(base).returning('id');
-    return inserted[0]?.id ?? inserted[0];
-  }
-
-  it('rejects a traversal payload in the id param instead of writing outside uploads/contracts/signed', async () => {
-    // '../../../../tmp/pwned' URL-encoded so the raw request path still
-    // has a single segment (matches Express's `:id`), but Express
-    // decodes the param back into literal '../' sequences before the
-    // route sees it.
-    const traversalId = encodeURIComponent('../../../../tmp/pwned');
-
-    const res = await auth(
-      request(app).post(`/api/admin/contracts/${traversalId}/upload-signed-pdf`)
-    ).attach('file', Buffer.from('%PDF-1.4 fake'), 'signed.pdf');
-
-    expect(res.status).toBeGreaterThanOrEqual(400);
-    expect(res.body.error).toMatch(/invalid contract id/i);
-
-    // No file should have been written anywhere — the filename callback
-    // must error out before multer opens a write stream.
-    const escapedFile = path.join(os.tmpdir(), 'pwned');
-    expect(fs.existsSync(escapedFile)).toBe(false);
-    if (fs.existsSync(signedDir())) {
-      expect(fs.readdirSync(signedDir())).toHaveLength(0);
-    }
-  });
-
-  it('still accepts a normal numeric contract id', async () => {
-    const id = await insertContract();
-
-    const res = await auth(
-      request(app).post(`/api/admin/contracts/${id}/upload-signed-pdf`)
-    ).attach('file', Buffer.from('%PDF-1.4 fake'), 'signed.pdf');
-
-    expect(res.status).toBe(200);
-
-    const files = fs.readdirSync(signedDir());
-    expect(files.some((f) => f.startsWith(`contract-${id}-`))).toBe(true);
-
-    const row = await db('contracts').where({ id }).first();
-    expect(row.status).toBe('fully_signed');
-    expect(row.signed_pdf_path).toMatch(new RegExp(`contract-${id}-`));
-  });
-});

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/adminEventsCascadeStorage.test.js

@@ -1,223 +0,0 @@
-/**
- * Regression test: deleting an event must remove its stored objects.
- *
- * deleteEventCascade() cleaned up the local filesystem only (#608). On an
- * S3/R2 storage backend that cleanup is a no-op, so every deleted gallery
- * left its originals and derived tiers in the bucket — unreferenced,
- * invisible in the UI, and billed forever. Measured on a v3.45.16 install
- * against Cloudflare R2: deleting a 403-photo event changed the bucket
- * object count by exactly zero.
- *
- * The keys must be collected BEFORE the transaction deletes the photo
- * rows, because afterwards nothing knows which objects were this event's.
- */
-
-const os = require('os');
-const path = require('path');
-
-// The cascade runs a real `fs.rm(..., { recursive: true })` over
-// {STORAGE_PATH}/events/{active,archived}/{slug}. Point that at a throwaway
-// directory before requiring the module under test — the default resolves
-// into the working tree.
-process.env.STORAGE_PATH = path.join(os.tmpdir(), 'picpeak-cascade-storage-test');
-
-const mockStorage = { delete: jest.fn().mockResolvedValue(undefined) };
-
-const mockEvent = {
-  id: 42,
-  slug: 'other-demo-2026-01-01',
-  event_name: 'Demo',
-  source_mode: 'managed',
-  // Written through the backend by archiveService, so it is a bucket object
-  // and the fs.unlink in the cascade never touched it on S3.
-  archive_path: 'archives/other-demo-2026-01-01.zip',
-  // The pre-built "Download All" zip. Lives under the event prefix, so the
-  // recursive fs.rm covers it on local disk and nothing covers it on S3.
-  download_zip_path: 'events/active/other-demo-2026-01-01/.download-cache/all.zip',
-};
-
-const mockPhotos = [
-  {
-    id: 1,
-    path: 'other-demo-2026-01-01/photo_one.jpg',
-    thumbnail_path: 'thumbnails/thumb_aaa_photo_one.jpg',
-    hero_path: null,
-    preview_path: 'previews/prev_aaa_photo_one.jpg',
-    watermark_path: 'watermarked/wm_aaa_photo_one.jpg',
-    source_origin: 'managed',
-  },
-  {
-    id: 2,
-    path: 'other-demo-2026-01-01/photo_two.jpg',
-    thumbnail_path: 'thumbnails/thumb_bbb_photo_two.jpg',
-    hero_path: null,
-    preview_path: null,
-    watermark_path: null,
-    source_origin: 'managed',
-  },
-  {
-    // External photos live outside the managed backend and must be left alone.
-    id: 3,
-    path: 'ignored.jpg',
-    thumbnail_path: null,
-    hero_path: null,
-    preview_path: null,
-    watermark_path: null,
-    source_origin: 'external',
-  },
-];
-
-let mockPhotoRowsDeleted = false;
-let mockJobRowsDeleted = false;
-
-// Photos in OTHER events that share a canonical derivative key with this one.
-let mockSharedDerivatives = [];
-
-// The shared-derivative probe: db('photos').whereNot(...).where(cb).select(...)
-const sharedProbe = {
-  where: () => sharedProbe,
-  whereIn: () => sharedProbe,
-  orWhereIn: () => sharedProbe,
-  select: async () => mockSharedDerivatives,
-};
-
-function mockMakeDb() {
-  const table = (name) => {
-    const chain = {
-      where: () => chain,
-      first: async () => (name === 'events' ? mockEvent : undefined),
-      whereNotNull: () => chain,
-      whereNot: () => sharedProbe,
-      orWhereIn: () => chain,
-      whereIn: () => chain,
-      select: async () => {
-        if (name === 'photos') {
-          // The whole point: if this runs after the transaction, the rows
-          // are gone and we would collect nothing.
-          return mockPhotoRowsDeleted ? [] : mockPhotos;
-        }
-        return [];
-      },
-      del: async () => {
-        if (name === 'photos') mockPhotoRowsDeleted = true;
-        if (name === 'download_jobs') mockJobRowsDeleted = true;
-        return 1;
-      },
-    };
-    return chain;
-  };
-  // #1132 guards the merge-dismissals delete behind a hasTable check.
-  table.schema = { hasTable: async () => false };
-  table.transaction = async (cb) => cb(table);
-  return table;
-}
-
-jest.mock('../../src/database/db', () => ({
-  db: mockMakeDb(),
-  logActivity: jest.fn().mockResolvedValue(undefined),
-}));
-
-jest.mock('../../src/services/storage', () => ({
-  getStorage: () => mockStorage,
-}));
-
-const { deleteEventCascade } = require('../../src/routes/adminEvents/helpers');
-
-describe('deleteEventCascade — storage cleanup', () => {
-  beforeEach(() => {
-    mockStorage.delete.mockClear();
-    mockPhotoRowsDeleted = false;
-    mockJobRowsDeleted = false;
-    mockSharedDerivatives = [];
-  });
-
-  it('deletes originals and every derived tier from the storage backend', async () => {
-    await deleteEventCascade(42, { id: 1, username: 'admin' });
-
-    const deleted = mockStorage.delete.mock.calls.map(([key]) => key);
-
-    expect(deleted).toEqual(expect.arrayContaining([
-      'events/active/other-demo-2026-01-01/photo_one.jpg',
-      'events/active/other-demo-2026-01-01/photo_two.jpg',
-      'thumbnails/thumb_aaa_photo_one.jpg',
-      'thumbnails/thumb_bbb_photo_two.jpg',
-      'previews/prev_aaa_photo_one.jpg',
-    ]));
-  });
-
-  it('deletes pre-generated watermarks and the archive zip', async () => {
-    await deleteEventCascade(42, { id: 1, username: 'admin' });
-
-    const deleted = mockStorage.delete.mock.calls.map(([key]) => key);
-
-    // Both are storage-backend objects that only fs.unlink ever touched, so
-    // both survived an event delete on S3.
-    expect(deleted).toEqual(expect.arrayContaining([
-      'watermarked/wm_aaa_photo_one.jpg',
-      'archives/other-demo-2026-01-01.zip',
-    ]));
-  });
-
-  it('deletes the Download All cache, which only fs.rm ever covered', async () => {
-    await deleteEventCascade(42, { id: 1, username: 'admin' });
-
-    const deleted = mockStorage.delete.mock.calls.map(([key]) => key);
-
-    // Sits under events/active/{slug}/.download-cache/ — swept by the
-    // recursive fs.rm on local disk, invisible to it on S3 where the prefix
-    // is not a directory. Gallery-sized. (download_jobs is main-only, so the
-    // per-job archives main also sweeps have no counterpart here.)
-    expect(deleted).toContain(
-      'events/active/other-demo-2026-01-01/.download-cache/all.zip'
-    );
-  });
-
-  it('leaves a derivative alone when another event still points at it', async () => {
-    // Canonical thumbnail/hero/preview keys are not event-scoped — the
-    // basename is the photo's filename, and filenames are not unique across
-    // events. Deleting one a surviving gallery still references would blank
-    // its tile.
-    mockSharedDerivatives = [{
-      thumbnail_path: 'thumbnails/thumb_aaa_photo_one.jpg',
-      hero_path: null,
-      preview_path: null,
-      watermark_path: null,
-    }];
-
-    await deleteEventCascade(42, { id: 1, username: 'admin' });
-
-    const deleted = mockStorage.delete.mock.calls.map(([key]) => key);
-    expect(deleted).not.toContain('thumbnails/thumb_aaa_photo_one.jpg');
-    // The originals are slug-scoped and must still go.
-    expect(deleted).toContain('events/active/other-demo-2026-01-01/photo_one.jpg');
-    // So must a derivative nobody else claims.
-    expect(deleted).toContain('thumbnails/thumb_bbb_photo_two.jpg');
-  });
-
-  it('never asks the backend to delete the same key twice', async () => {
-    await deleteEventCascade(42, { id: 1, username: 'admin' });
-
-    const managed = mockStorage.delete.mock.calls
-      .map(([key]) => key)
-      .filter((key) => !key.startsWith('thumbnails/thumb_w') && !key.startsWith('previews/preview_w'));
-
-    expect(managed).toEqual([...new Set(managed)]);
-  });
-
-  it('leaves external/reference photos in place', async () => {
-    await deleteEventCascade(42, { id: 1, username: 'admin' });
-
-    const deleted = mockStorage.delete.mock.calls.map(([key]) => key);
-    expect(deleted).not.toEqual(expect.arrayContaining(['ignored.jpg']));
-    expect(deleted).not.toEqual(expect.arrayContaining(['events/active/ignored.jpg']));
-  });
-
-  it('still completes the delete when the storage backend throws', async () => {
-    mockStorage.delete.mockRejectedValue(new Error('bucket unreachable'));
-
-    await expect(deleteEventCascade(42, { id: 1, username: 'admin' }))
-      .resolves.toEqual({ id: 42, name: 'Demo' });
-
-    mockStorage.delete.mockResolvedValue(undefined);
-  });
-});

backend/__tests__/routes/adminEventsLogoPathTraversal.test.js

@@ -1,122 +0,0 @@
-/**
- * GHSA-9q5j-vqfw-32hr — the event-logo upload's multer `filename` callback
- * built the stored path directly from `req.params.id` with no integer
- * validation:
- *
- *   filename: (req, file, cb) => {
- *     cb(null, `event-${req.params.id}-logo-${Date.now()}${ext}`);
- *   }
- *
- * A traversal payload in the `:id` route param (URL-encoded so it still
- * matches a single Express path segment, then decoded back into literal
- * `../` sequences by Express before handlers see it) could escape the
- * intended uploads/logos/events/ directory. Most directly reachable via a
- * super_admin session: requireEventOwnership short-circuits with next() and
- * zero DB lookup for that role (src/middleware/ownership.js), so nothing
- * upstream of multer validates the id first.
- *
- * Fixed by rejecting any non-positive-integer id before it is used to build
- * the filename, regardless of role or ownership-check ordering.
- */
-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-logo-')), 'db.sqlite'
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'admin-events-logo-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: '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('POST /api/admin/events/:id/logo — path traversal guard', () => {
-  let db; let cleanup; let app; let adminId; let token;
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    ({ adminId } = await seedMinimal(db));
-    // super_admin: requireEventOwnership short-circuits with no DB lookup
-    // for this role, so it reaches multer with nothing upstream having
-    // validated the id — the exact path GHSA-9q5j-vqfw-32hr exploited.
-    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(); });
-
-  const auth = (req) => req.set('Authorization', `Bearer ${token}`);
-  const logoDir = () => path.join(process.env.STORAGE_PATH, 'uploads/logos/events');
-
-  it('rejects a traversal payload in the id param instead of writing outside uploads/logos/events', async () => {
-    // '../../../../tmp/pwned' URL-encoded so the raw request path still has
-    // a single segment (matches Express's `:id`), but Express decodes the
-    // param back into literal '../' sequences before the route sees it.
-    const traversalId = encodeURIComponent('../../../../tmp/pwned');
-
-    const res = await auth(
-      request(app).post(`/api/admin/events/${traversalId}/logo`)
-    ).attach('logo', Buffer.from('fake image data'), 'logo.png');
-
-    expect(res.status).toBeGreaterThanOrEqual(400);
-    expect(res.body.error).toMatch(/invalid event id/i);
-
-    // No file should have been written anywhere — the filename callback
-    // must error out before multer opens a write stream.
-    const escapedFile = path.join(os.tmpdir(), 'pwned');
-    expect(fs.existsSync(escapedFile)).toBe(false);
-    if (fs.existsSync(logoDir())) {
-      expect(fs.readdirSync(logoDir())).toHaveLength(0);
-    }
-  });
-
-  it('still accepts a normal numeric event id', async () => {
-    const id = await insertEvent(db, adminId, { event_name: 'Logo Event' });
-
-    const res = await auth(
-      request(app).post(`/api/admin/events/${id}/logo`)
-    ).attach('logo', Buffer.from('fake image data'), 'logo.png');
-
-    expect(res.status).toBe(200);
-    expect(res.body.hero_logo_url).toMatch(new RegExp(`^/uploads/logos/events/event-${id}-logo-`));
-
-    const files = fs.readdirSync(logoDir());
-    expect(files.some((f) => f.startsWith(`event-${id}-logo-`))).toBe(true);
-
-    const row = await db('events').where({ id }).first();
-    expect(row.hero_logo_url).toBe(res.body.hero_logo_url);
-  });
-});

backend/__tests__/routes/adminMfa.test.js

@@ -38,7 +38,6 @@ const { authenticator } = require('otplib');
 const {
   bootCrmDb, mintAdminToken, buildRouteApp,
 } = require('../integration/helpers/crmDb');
-const mfaService = require('../../src/services/mfaService');
 
 jest.setTimeout(120000);
 
@@ -236,138 +235,6 @@ describe('MFA disable — /api/admin/auth/mfa/disable', () => {
     expect(row.two_factor_secret).toBeNull();
     expect(row.two_factor_recovery_codes).toBeNull();
   });
-
-  // Concurrency regression: a plain UPDATE with no conditional guard let two
-  // requests carrying the same captured code both read the same
-  // two_factor_last_used_step and both persist, defeating replay protection.
-  // The guarded UPDATE (mfaService.persistTotpStep) makes only the first
-  // writer's affected-row count > 0; the loser must be rejected.
-  it('two concurrent disable requests with the SAME captured code: only one succeeds', async () => {
-    const admin = await seedAdmin();
-    const { secret, token } = await enroll(admin.id);
-    const code = authenticator.generate(secret);
-
-    const [r1, r2] = await Promise.all([
-      request(adminApp)
-        .post('/api/admin/auth/mfa/disable')
-        .set('Authorization', `Bearer ${token}`)
-        .send({ code }),
-      request(adminApp)
-        .post('/api/admin/auth/mfa/disable')
-        .set('Authorization', `Bearer ${token}`)
-        .send({ code }),
-    ]);
-
-    expect([r1.status, r2.status].sort()).toEqual([200, 400]);
-
-    const status = await request(adminApp)
-      .get('/api/admin/auth/mfa/status')
-      .set('Authorization', `Bearer ${token}`);
-    expect(status.body.enabled).toBe(false);
-  });
-});
-
-describe('MFA regenerate recovery codes — /api/admin/auth/mfa/recovery-codes', () => {
-  it('a valid TOTP regenerates the recovery codes and persists the step', async () => {
-    const admin = await seedAdmin();
-    const { secret, token } = await enroll(admin.id);
-
-    const res = await request(adminApp)
-      .post('/api/admin/auth/mfa/recovery-codes')
-      .set('Authorization', `Bearer ${token}`)
-      .send({ code: authenticator.generate(secret) });
-
-    expect(res.status).toBe(200);
-    expect(res.body.recoveryCodes).toHaveLength(10);
-  });
-
-  it('a wrong code is rejected (400)', async () => {
-    const admin = await seedAdmin();
-    const { secret, token } = await enroll(admin.id);
-    const valid = authenticator.generate(secret);
-    const wrong = valid === '000000' ? '111111' : '000000';
-
-    const res = await request(adminApp)
-      .post('/api/admin/auth/mfa/recovery-codes')
-      .set('Authorization', `Bearer ${token}`)
-      .send({ code: wrong });
-    expect(res.status).toBe(400);
-  });
-
-  // Concurrency regression (see the disable test above for the mechanism):
-  // this is the endpoint called out as the worst lost-update case, since it
-  // both rotates the recovery codes and (previously) persisted the step in
-  // one unconditional UPDATE.
-  it('two concurrent regenerations with the SAME captured code: only one succeeds', async () => {
-    const admin = await seedAdmin();
-    const { secret, token } = await enroll(admin.id);
-    const code = authenticator.generate(secret);
-
-    const [r1, r2] = await Promise.all([
-      request(adminApp)
-        .post('/api/admin/auth/mfa/recovery-codes')
-        .set('Authorization', `Bearer ${token}`)
-        .send({ code }),
-      request(adminApp)
-        .post('/api/admin/auth/mfa/recovery-codes')
-        .set('Authorization', `Bearer ${token}`)
-        .send({ code }),
-    ]);
-
-    expect([r1.status, r2.status].sort()).toEqual([200, 400]);
-    const winner = r1.status === 200 ? r1 : r2;
-    expect(winner.body.recoveryCodes).toHaveLength(10);
-
-    const row = await db('admin_users').where({ id: admin.id }).first();
-    expect(row.two_factor_last_used_step).not.toBeNull();
-  });
-});
-
-describe('mfaService.persistTotpStep — atomic replay-tracking persist', () => {
-  // Deterministic simulation of the race: two "concurrent" requests that
-  // read the SAME two_factor_last_used_step and computed the SAME totpStep
-  // from the same captured code. Calling persistTotpStep twice in a row with
-  // that identical totpStep reproduces exactly the DB-level outcome of a
-  // true race, without relying on event-loop timing.
-  it('the second writer with the same totpStep affects 0 rows and is rejected', async () => {
-    const admin = await seedAdmin();
-    const { secret } = await enroll(admin.id);
-    const row = await db('admin_users').where({ id: admin.id }).first();
-    const code = authenticator.generate(secret);
-    const totpStep = mfaService.verifyTotpEncryptedStep(code, row.two_factor_secret, null);
-    expect(totpStep).toEqual(expect.any(Number));
-
-    const first = await mfaService.persistTotpStep(db, admin.id, totpStep, { updated_at: new Date() });
-    expect(first).toBe(true);
-
-    // The row's two_factor_last_used_step has now already advanced to
-    // totpStep by the time this "losing" write runs — the guard condition
-    // (whereNull OR < totpStep) is false, so 0 rows are affected.
-    const second = await mfaService.persistTotpStep(db, admin.id, totpStep, { updated_at: new Date() });
-    expect(second).toBe(false);
-
-    const after = await db('admin_users').where({ id: admin.id }).first();
-    expect(Number(after.two_factor_last_used_step)).toBe(totpStep);
-  });
-
-  it('succeeds when the new step advances past the current one', async () => {
-    const admin = await seedAdmin();
-    const { secret } = await enroll(admin.id);
-    const row = await db('admin_users').where({ id: admin.id }).first();
-    const code = authenticator.generate(secret);
-    const totpStep = mfaService.verifyTotpEncryptedStep(code, row.two_factor_secret, null);
-
-    const ok = await mfaService.persistTotpStep(db, admin.id, totpStep, {});
-    expect(ok).toBe(true);
-
-    const nextStepAuthenticator = authenticator.clone({ epoch: Date.now() + 30000 });
-    const nextCode = nextStepAuthenticator.generate(secret);
-    const nextStep = mfaService.verifyTotpEncryptedStep(nextCode, row.two_factor_secret, totpStep);
-    expect(nextStep).toBeGreaterThan(totpStep);
-
-    const advanced = await mfaService.persistTotpStep(db, admin.id, nextStep, {});
-    expect(advanced).toBe(true);
-  });
 });
 
 describe('Admin login challenge — /api/auth/admin/login[/mfa]', () => {
@@ -417,86 +284,6 @@ describe('Admin login challenge — /api/auth/admin/login[/mfa]', () => {
     expect(res.body.user.id).toBe(admin.id);
   });
 
-  // GHSA-qcwx-r25m-j869: verifyTotp() was stateless, so otplib's window:1
-  // tolerance let the same 6-digit code complete two independent logins
-  // within its ~90s validity window. mfaService now tracks each admin's
-  // last-consumed TOTP step and rejects a code that doesn't advance past it.
-  it('#GHSA-qcwx-r25m-j869 — a TOTP code cannot be replayed into a second login', async () => {
-    const admin = await seedAdmin();
-    const { secret } = await enroll(admin.id);
-    const code = authenticator.generate(secret);
-
-    // First use of the code completes a login.
-    const c1 = await request(authApp)
-      .post('/api/auth/admin/login')
-      .send({ username: admin.username, password: admin.password });
-    const first = await request(authApp)
-      .post('/api/auth/admin/login/mfa')
-      .send({ mfaToken: c1.body.mfaToken, code });
-    expect(first.status).toBe(200);
-    expect(first.body.user).toBeDefined();
-
-    // Replaying the SAME code for an independent second login must fail,
-    // even though otplib's window:1 tolerance still considers it valid.
-    const c2 = await request(authApp)
-      .post('/api/auth/admin/login')
-      .send({ username: admin.username, password: admin.password });
-    const replay = await request(authApp)
-      .post('/api/auth/admin/login/mfa')
-      .send({ mfaToken: c2.body.mfaToken, code });
-    expect(replay.status).toBe(401);
-    expect(replay.body.code).toBe('MFA_INVALID');
-    expect(replay.body.user).toBeUndefined();
-
-    // A freshly generated code for the NEXT TOTP step is not a replay and
-    // succeeds. Generated via a cloned authenticator with a future epoch
-    // rather than mocking Date.now(), so mfaService's own step computation
-    // (real Date.now()) still lands the match one step ahead.
-    const nextStepAuthenticator = authenticator.clone({ epoch: Date.now() + 30000 });
-    const nextCode = nextStepAuthenticator.generate(secret);
-    const c3 = await request(authApp)
-      .post('/api/auth/admin/login')
-      .send({ username: admin.username, password: admin.password });
-    const third = await request(authApp)
-      .post('/api/auth/admin/login/mfa')
-      .send({ mfaToken: c3.body.mfaToken, code: nextCode });
-    expect(third.status).toBe(200);
-    expect(third.body.user).toBeDefined();
-    expect(third.body.user.id).toBe(admin.id);
-  });
-
-  // Concurrency regression: verifyTotpEncryptedStep()'s "does this advance"
-  // check was read against a snapshot taken earlier in the request, then a
-  // PLAIN update persisted the step — two concurrent requests carrying the
-  // SAME captured code could both pass the check and both complete a login
-  // before either write landed. The persist is now a conditional UPDATE
-  // (mfaService.persistTotpStep), so only the first writer's affected-row
-  // count is > 0 and the other is correctly treated as a replay.
-  it('two concurrent login/mfa requests with the SAME captured code: only one completes', async () => {
-    const admin = await seedAdmin();
-    const { secret } = await enroll(admin.id);
-    const code = authenticator.generate(secret);
-
-    const c1 = await request(authApp)
-      .post('/api/auth/admin/login')
-      .send({ username: admin.username, password: admin.password });
-    const c2 = await request(authApp)
-      .post('/api/auth/admin/login')
-      .send({ username: admin.username, password: admin.password });
-
-    const [r1, r2] = await Promise.all([
-      request(authApp).post('/api/auth/admin/login/mfa').send({ mfaToken: c1.body.mfaToken, code }),
-      request(authApp).post('/api/auth/admin/login/mfa').send({ mfaToken: c2.body.mfaToken, code }),
-    ]);
-
-    expect([r1.status, r2.status].sort()).toEqual([200, 401]);
-    const winner = r1.status === 200 ? r1 : r2;
-    const loser = r1.status === 200 ? r2 : r1;
-    expect(winner.body.user).toBeDefined();
-    expect(loser.body.user).toBeUndefined();
-    expect(loser.body.code).toBe('MFA_INVALID');
-  });
-
   it('login/mfa with a wrong code is 401 MFA_INVALID', async () => {
     const admin = await seedAdmin();
     const { secret } = await enroll(admin.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/adminShortUrlOwnership.test.js

@@ -1,151 +0,0 @@
-/**
- * GHSA-9h7q-2jpf-vj85 — DELETE /api/admin/short-urls/:id only checked
- * `events.edit` permission, with no ownership scoping. GET and POST for an
- * event's short URLs both chain requireEventOwnership; DELETE takes the
- * short URL row's own :id (not :eventId), so any admin holding events.edit
- * could delete another admin's branded gallery short URL. The route now
- * resolves the short URL's event first and applies the same ownership
- * predicate requireEventOwnership uses. super_admin keeps global access.
- */
-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-suown-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'suown-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-suown-storage-'));
-
-const request = require('supertest');
-const express = require('express');
-const cookieParser = require('cookie-parser');
-const { bootCrmDb, assignAdminRole, mintAdminToken } = require('../integration/helpers/crmDb');
-
-describe('short URL delete ownership scoping', () => {
-  let db; let cleanup; let app; let service;
-  let superTok; let ownerTok; let foreignTok;
-  let ownerId;
-  let foreignShortUrlId;
-
-  const auth = (req, tok) => req.set('Authorization', `Bearer ${tok}`);
-
-  async function seedEvent(createdBy, slugSuffix) {
-    const farFuture = new Date(Date.now() + 365 * 86400000).toISOString();
-    const [id] = await db('events').insert({
-      slug: `suown-${slugSuffix}`,
-      event_type: 'wedding',
-      event_name: 'Test Event',
-      event_date: '2026-08-01',
-      host_email: 'h@e.com',
-      admin_email: 'a@e.com',
-      password_hash: 'x',
-      share_link: `suown-${slugSuffix}`,
-      share_token: `suown-share-${slugSuffix}`,
-      expires_at: farFuture,
-      is_active: true,
-      is_archived: false,
-      created_by: createdBy,
-      created_at: new Date().toISOString(),
-    });
-    return db('events').where({ id }).first();
-  }
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    service = require('../../src/services/galleryShortUrlService');
-
-    const superIns = await db('admin_users').insert({
-      username: 'suown-super', email: 'suown-super@example.com',
-      password_hash: 'x', must_change_password: false, created_at: new Date(),
-    }).returning('id');
-    const superId = superIns[0]?.id ?? superIns[0];
-    await assignAdminRole(db, superId, 'super_admin');
-    superTok = mintAdminToken(superId);
-
-    const ownerIns = await db('admin_users').insert({
-      username: 'suown-owner', email: 'suown-owner@example.com',
-      password_hash: 'x', must_change_password: false, created_at: new Date(),
-    }).returning('id');
-    ownerId = ownerIns[0]?.id ?? ownerIns[0];
-    await assignAdminRole(db, ownerId, 'editor');
-    ownerTok = mintAdminToken(ownerId);
-
-    const foreignIns = await db('admin_users').insert({
-      username: 'suown-foreign', email: 'suown-foreign@example.com',
-      password_hash: 'x', must_change_password: false, created_at: new Date(),
-    }).returning('id');
-    const foreignId = foreignIns[0]?.id ?? foreignIns[0];
-    await assignAdminRole(db, foreignId, 'editor');
-    foreignTok = mintAdminToken(foreignId);
-
-    // Event owned by `owner`, NOT `foreign`.
-    await seedEvent(ownerId, 'owned');
-
-    app = express();
-    app.use(express.json());
-    app.use(cookieParser());
-    app.use('/api/admin', require('../../src/routes/adminShortUrls'));
-  }, 120000);
-
-  afterAll(async () => { if (cleanup) await cleanup(); });
-
-  beforeEach(async () => {
-    // Fresh short URL per DELETE test so earlier deletes don't interfere.
-    const event = await db('events').where({ created_by: ownerId }).first();
-    const row = await service.createShortUrl({
-      eventId: event.id,
-      customSlug: `suown-target-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
-      createdBy: ownerId,
-    });
-    foreignShortUrlId = row.id;
-  });
-
-  it('an admin who does not own the event cannot delete its short URL (403, row survives)', async () => {
-    const res = await auth(
-      request(app).delete(`/api/admin/short-urls/${foreignShortUrlId}`),
-      foreignTok,
-    );
-    expect(res.status).toBe(403);
-    const row = await db('gallery_short_urls').where({ id: foreignShortUrlId }).first();
-    expect(row).toBeDefined();
-    expect(row.deleted_at).toBeFalsy();
-  });
-
-  it('the owning admin can delete its own short URL', async () => {
-    const res = await auth(
-      request(app).delete(`/api/admin/short-urls/${foreignShortUrlId}`),
-      ownerTok,
-    );
-    expect(res.status).toBe(204);
-    const row = await db('gallery_short_urls').where({ id: foreignShortUrlId }).first();
-    expect(row.deleted_at).toBeTruthy();
-  });
-
-  it('super_admin can delete any short URL', async () => {
-    const res = await auth(
-      request(app).delete(`/api/admin/short-urls/${foreignShortUrlId}`),
-      superTok,
-    );
-    expect(res.status).toBe(204);
-    const row = await db('gallery_short_urls').where({ id: foreignShortUrlId }).first();
-    expect(row.deleted_at).toBeTruthy();
-  });
-
-  it('deleting a nonexistent short URL id returns 404', async () => {
-    const res = await auth(
-      request(app).delete('/api/admin/short-urls/9999999'),
-      superTok,
-    );
-    expect(res.status).toBe(404);
-  });
-
-  it('deleting a nonexistent short URL id as a non-owner also returns 404 (existence check runs first)', async () => {
-    const res = await auth(
-      request(app).delete('/api/admin/short-urls/9999999'),
-      foreignTok,
-    );
-    expect(res.status).toBe(404);
-  });
-});

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/databaseBackupConfigDestination.test.js

@@ -1,122 +0,0 @@
-/**
- * PUT /api/admin/database-backup/config must reject a
- * database_backup_destination_path that resolves inside a publicly served
- * directory (GHSA-jw8m-43r2-jqrm class, #1365).
- *
- * Before #1365, database_backup_destination_path was silently ignored by
- * databaseBackupService.backup() (a destructuring bug always fell back to
- * the hardcoded /backup/database), so this setting being freely writable by
- * any backup.create holder — the built-in `admin` role has it without
- * settings.edit or backup.restore — was harmless. Making the setting
- * actually take effect reopens the exact exfiltration path GHSA-jw8m fixed
- * for the per-request override, through the persisted setting instead.
- */
-
-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-dbbackup-config-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'dbbackup-config-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-dbbackup-storage-'));
-
-const request = require('supertest');
-const express = require('express');
-const bcrypt = require('bcrypt');
-const jwt = require('jsonwebtoken');
-
-const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
-
-describe('database backup destination-path config guard (GHSA-jw8m class, #1365)', () => {
-  let db; let cleanup; let app; let adminToken;
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-
-    const role = await db('roles').where({ name: 'admin' }).first();
-    const r = await db('admin_users').insert({
-      username: 'limited-admin',
-      email: 'limited-admin-config@example.com',
-      password_hash: await bcrypt.hash('Passw0rd!', 4),
-      role_id: role.id,
-      is_active: 1,
-      created_at: new Date(),
-      updated_at: new Date(),
-    }).returning('id');
-    const id = r[0]?.id ?? r[0];
-    adminToken = jwt.sign(
-      { id, username: 'limited-admin', type: 'admin', role: 'admin', loginTime: Date.now() },
-      process.env.JWT_SECRET,
-      { expiresIn: '1h', issuer: 'picpeak-auth' },
-    );
-
-    app = express();
-    app.use(express.json());
-    app.use('/api/admin/database-backup', require('../../src/routes/adminDatabaseBackup'));
-  }, 120000);
-
-  afterAll(async () => { if (cleanup) await cleanup(); });
-
-  it('rejects a destination inside the public uploads/logos mount', async () => {
-    const res = await request(app)
-      .put('/api/admin/database-backup/config')
-      .set('Authorization', `Bearer ${adminToken}`)
-      .send({ database_backup_destination_path: path.join(process.env.STORAGE_PATH, 'uploads', 'logos') });
-
-    expect(res.status).toBe(400);
-
-    // The seeded default must survive untouched — the rejected value never lands.
-    const row = await db('app_settings').where({ setting_key: 'database_backup_destination_path' }).first();
-    expect(JSON.parse(row.setting_value)).toBe('/backup/database');
-  });
-
-  it('rejects a destination inside the public fonts mount', async () => {
-    const res = await request(app)
-      .put('/api/admin/database-backup/config')
-      .set('Authorization', `Bearer ${adminToken}`)
-      .send({ database_backup_destination_path: path.join(process.env.STORAGE_PATH, 'fonts') });
-
-    expect(res.status).toBe(400);
-  });
-
-  it('accepts a destination outside any public mount', async () => {
-    const safePath = path.join(process.env.STORAGE_PATH, 'db-backups');
-    const res = await request(app)
-      .put('/api/admin/database-backup/config')
-      .set('Authorization', `Bearer ${adminToken}`)
-      .send({ database_backup_destination_path: safePath });
-
-    expect(res.status).toBe(200);
-
-    const row = await db('app_settings').where({ setting_key: 'database_backup_destination_path' }).first();
-    expect(JSON.parse(row.setting_value)).toBe(safePath);
-  });
-
-  // A retention of 0 or less pushes cleanupOldBackups' cutoff to today or
-  // the future, deleting every completed backup on the next scheduled run
-  // — a backup.create holder achieving what backup.delete gates on /cleanup.
-  it.each([-1, 0])('rejects database_backup_retention_days=%s', async (bad) => {
-    const res = await request(app)
-      .put('/api/admin/database-backup/config')
-      .set('Authorization', `Bearer ${adminToken}`)
-      .send({ database_backup_retention_days: bad });
-
-    expect(res.status).toBe(400);
-  });
-
-  it('accepts a positive database_backup_retention_days', async () => {
-    const res = await request(app)
-      .put('/api/admin/database-backup/config')
-      .set('Authorization', `Bearer ${adminToken}`)
-      .send({ database_backup_retention_days: 90 });
-
-    expect(res.status).toBe(200);
-
-    const row = await db('app_settings').where({ setting_key: 'database_backup_retention_days' }).first();
-    expect(JSON.parse(row.setting_value)).toBe(90);
-  });
-});

backend/__tests__/routes/galleryDownloadStorage.test.js

@@ -1,278 +0,0 @@
-/**
- * Single-photo gallery downloads must go through the storage backend (#1048).
- *
- * `GET /api/gallery/:slug/download/:photoId` resolved a LOCAL filesystem path
- * unconditionally and handed it to res.sendFile. On an S3/R2 deployment
- * managed photos never exist on local disk, so every per-photo download 404'd
- * with ENOENT — while download-all and secure-images worked fine, because they
- * already went through getStorage(). The gallery looks healthy until a guest
- * clicks the download button on a single photo.
- *
- * The local branch is pinned just as hard: sendFile emits Content-Length,
- * Accept-Ranges, ETag and Last-Modified and answers Range with a 206. Routing
- * local installs through a bare stream.pipe(res) to share one code path would
- * silently drop all of that, and a resumed download would append a second full
- * body onto the partial file.
- */
-
-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-dl-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'download-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-dl-storage-'));
-
-const { Readable } = require('stream');
-
-const SLUG = 'download-gallery';
-const FILENAME = 'original.jpg';
-// Deliberately not written to disk anywhere: if the route reads the
-// filesystem instead of the backend, it cannot produce these bytes.
-const mockObjectBody = Buffer.from('S3-ONLY-ORIGINAL-BYTES-not-on-local-disk');
-const mockBackendKind = { value: 's3' };
-
-const mockStorage = {
-  kind: () => mockBackendKind.value,
-  stat: jest.fn(async () => ({ size: mockObjectBody.length, mtime: new Date('2026-08-20T10:00:00Z') })),
-  get: jest.fn(async () => Readable.from([mockObjectBody])),
-  getRange: jest.fn(async (key, start, end) => Readable.from([mockObjectBody.subarray(start, end + 1)])),
-  delete: jest.fn(async () => undefined),
-  exists: jest.fn(async () => true),
-};
-
-jest.mock('../../src/services/storage', () => ({
-  getStorage: () => mockStorage,
-  initStorage: async () => mockStorage,
-}));
-
-const request = require('supertest');
-const express = require('express');
-const cookieParser = require('cookie-parser');
-const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
-
-describe('single-photo download through the storage backend (#1048)', () => {
-  let db; let cleanup; let app; let eventId; let photoId;
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-
-    const ev = await db('events').insert({
-      slug: SLUG,
-      event_type: 'wedding',
-      event_name: 'Downloads',
-      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: 'download-share',
-      expires_at: new Date(Date.now() + 7 * 864e5).toISOString(),
-      is_active: 1,
-      is_archived: 0,
-      is_draft: 0,
-      require_password: 0,
-      allow_downloads: 1,
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    eventId = ev[0]?.id ?? ev[0];
-
-    const row = await db('photos').insert({
-      event_id: eventId,
-      filename: FILENAME,
-      path: `${SLUG}/${FILENAME}`,
-      type: 'individual',
-      source_origin: 'managed',
-      mime_type: 'image/jpeg',
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    photoId = row[0]?.id ?? row[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(() => {
-    mockBackendKind.value = 's3';
-    mockStorage.get.mockClear();
-    mockStorage.getRange.mockClear();
-  });
-
-  it('streams the stored object instead of 404ing on a local path', async () => {
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/download/${photoId}`)
-      .buffer(true)
-      .parse((response, cb) => {
-        const chunks = [];
-        response.on('data', (c) => chunks.push(c));
-        response.on('end', () => cb(null, Buffer.concat(chunks)));
-      });
-
-    expect(res.status).toBe(200);
-    // The bytes only exist in the backend — proof it did not read the disk.
-    expect(res.body.equals(mockObjectBody)).toBe(true);
-    expect(mockStorage.get).toHaveBeenCalledWith(`events/active/${SLUG}/${FILENAME}`);
-    // Never written locally, so a filesystem read could not have served this.
-    expect(fs.existsSync(path.join(process.env.STORAGE_PATH, 'events/active', SLUG, FILENAME))).toBe(false);
-  });
-
-  it('sends Content-Length so the browser can show download progress', async () => {
-    const res = await request(app).get(`/api/gallery/${SLUG}/download/${photoId}`);
-
-    expect(res.headers['content-length']).toBe(String(mockObjectBody.length));
-    expect(res.headers['accept-ranges']).toBe('bytes');
-    expect(res.headers['content-disposition']).toContain(FILENAME);
-  });
-
-  it('answers a Range request with 206 and only the requested bytes', async () => {
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/download/${photoId}`)
-      .set('Range', 'bytes=0-9')
-      .buffer(true)
-      .parse((response, cb) => {
-        const chunks = [];
-        response.on('data', (c) => chunks.push(c));
-        response.on('end', () => cb(null, Buffer.concat(chunks)));
-      });
-
-    expect(res.status).toBe(206);
-    expect(res.headers['content-range']).toBe(`bytes 0-9/${mockObjectBody.length}`);
-    expect(res.headers['content-length']).toBe('10');
-    expect(res.body.equals(mockObjectBody.subarray(0, 10))).toBe(true);
-    expect(mockStorage.getRange).toHaveBeenCalledWith(`events/active/${SLUG}/${FILENAME}`, 0, 9);
-  });
-
-  it('ignores a malformed Range rather than emitting a nonsense 206', async () => {
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/download/${photoId}`)
-      .set('Range', 'bytes=abc-def');
-
-    expect(res.status).toBe(200);
-    expect(res.headers['content-range']).toBeUndefined();
-  });
-
-  it('404s cleanly when the object is missing from the backend', async () => {
-    mockStorage.stat.mockResolvedValueOnce(null);
-
-    const res = await request(app).get(`/api/gallery/${SLUG}/download/${photoId}`);
-
-    expect(res.status).toBe(404);
-    // The error must not inherit the image headers staged for a successful
-    // download, or the browser saves a .jpg containing JSON.
-    expect(res.headers['content-type']).toMatch(/json/);
-    expect(res.headers['content-disposition']).toBeUndefined();
-  });
-
-  it('keeps res.sendFile on a local backend rather than a bare pipe', async () => {
-    mockBackendKind.value = 'local';
-    const abs = path.join(process.env.STORAGE_PATH, 'events/active', SLUG, FILENAME);
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, 'local-disk-bytes');
-
-    const res = await request(app).get(`/api/gallery/${SLUG}/download/${photoId}`);
-
-    expect(res.status).toBe(200);
-    expect(mockStorage.get).not.toHaveBeenCalled();
-    // sendFile's signature: conditional-request headers a raw pipe never sets.
-    expect(res.headers.etag).toBeDefined();
-    expect(res.headers['last-modified']).toBeDefined();
-
-    fs.rmSync(abs, { force: true });
-  });
-
-  it('does not serve a partial body when the If-Range validator is stale', async () => {
-    // The object was replaced since the client's last attempt. Answering 206
-    // from the new bytes would let it splice two versions into one file.
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/download/${photoId}`)
-      .set('Range', 'bytes=0-9')
-      .set('If-Range', new Date('2020-01-01T00:00:00Z').toUTCString());
-
-    expect(res.status).toBe(200);
-    expect(res.headers['content-range']).toBeUndefined();
-    expect(res.headers['content-length']).toBe(String(mockObjectBody.length));
-  });
-
-  it('still serves 206 when the If-Range validator matches', async () => {
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/download/${photoId}`)
-      .set('Range', 'bytes=0-9')
-      .set('If-Range', new Date('2026-08-20T10:00:00Z').toUTCString());
-
-    expect(res.status).toBe(206);
-    expect(res.headers['content-range']).toBe(`bytes 0-9/${mockObjectBody.length}`);
-  });
-
-  it('errors cleanly when the object vanishes between stat and get', async () => {
-    // HeadObject succeeding does not mean GetObject will — a concurrent
-    // delete lands here. The staged image headers must not escape with it.
-    const gone = new Error('NoSuchKey');
-    gone.name = 'NoSuchKey';
-    mockStorage.get.mockRejectedValueOnce(gone);
-
-    const res = await request(app).get(`/api/gallery/${SLUG}/download/${photoId}`);
-
-    expect(res.status).toBe(404);
-    expect(res.headers['content-type']).toMatch(/json/);
-    expect(res.headers['content-disposition']).toBeUndefined();
-  });
-
-  it('does not send 206 headers before the range fetch can fail', async () => {
-    // writeHead(206) before the await would make this ERR_HTTP_HEADERS_SENT.
-    mockStorage.getRange.mockRejectedValueOnce(new Error('connection reset'));
-
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/download/${photoId}`)
-      .set('Range', 'bytes=0-9');
-
-    expect(res.status).toBe(500);
-    expect(res.headers['content-type']).toMatch(/json/);
-    expect(res.headers['content-range']).toBeUndefined();
-  });
-
-  it('answers HEAD from stat instead of draining the object out of S3', async () => {
-    const before = (await db('photos').where('id', photoId).first()).download_count || 0;
-    const logsBefore = (await db('access_logs').where({ photo_id: photoId, action: 'download' })).length;
-
-    const res = await request(app).head(`/api/gallery/${SLUG}/download/${photoId}`);
-
-    expect(res.status).toBe(200);
-    expect(res.headers['content-length']).toBe(String(mockObjectBody.length));
-    expect(res.headers['accept-ranges']).toBe('bytes');
-    // The whole point: no egress for a metadata probe.
-    expect(mockStorage.get).not.toHaveBeenCalled();
-    expect(mockStorage.getRange).not.toHaveBeenCalled();
-
-    // And no side effects: a probe is not a download.
-    const after = (await db('photos').where('id', photoId).first()).download_count || 0;
-    expect(after).toBe(before);
-    const logsAfter = (await db('access_logs').where({ photo_id: photoId, action: 'download' })).length;
-    expect(logsAfter).toBe(logsBefore);
-  });
-
-  it('returns a clean error when the range stream dies before its first chunk', async () => {
-    // Resolves, then errors — writeHead would already have committed the 206,
-    // leaving a connection reset as the only possible outcome.
-    const { Readable: R } = require('stream');
-    mockStorage.getRange.mockImplementationOnce(async () => {
-      const dead = new R({ read() { this.destroy(new Error('socket hang up')); } });
-      return dead;
-    });
-
-    const res = await request(app)
-      .get(`/api/gallery/${SLUG}/download/${photoId}`)
-      .set('Range', 'bytes=0-9');
-
-    expect(res.status).toBe(500);
-    expect(res.headers['content-type']).toMatch(/json/);
-    expect(res.headers['content-range']).toBeUndefined();
-  });
-});

backend/__tests__/routes/galleryDraftPreviewResolve.test.js

@@ -1,268 +0,0 @@
-/**
- * Previewing an unpublished gallery through its SHORT share URL (#1386).
- *
- * /info has honoured admin_preview since #868, but two sibling routes never
- * did, and both sit on the short-URL path:
- *
- *   GET /resolve/:identifier      — filtered drafts out via ACTIVE_EVENT_FILTER
- *   GET /:slug/verify-token/:token — same, inline
- *
- * With "use short gallery URLs" OFF the admin's View Gallery link carries the
- * slug, GalleryPage never calls /resolve, and the preview worked. With it ON
- * the link is the token form, GalleryPage resolves it first, and the draft
- * 404'd as "Gallery Not Found" — which is exactly what was reported.
- *
- * The relaxation is admin-preview-only, so the other half of these tests is
- * the part that must NOT move: anonymous callers still get 404 for a draft,
- * and GHSA-rh8r's rule (never hand a share_token back on a bare slug lookup)
- * has to survive the new path too.
- */
-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-draft-preview-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'draft-preview-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-draft-preview-storage-'));
-
-const request = require('supertest');
-const express = require('express');
-const cookieParser = require('cookie-parser');
-const { bootCrmDb, seedMinimal, assignAdminRole, mintAdminToken } = require('../integration/helpers/crmDb');
-
-// Share-token fixtures, deliberately low-entropy and obviously fake. They
-// have to satisfy SHARE_TOKEN_REGEX (32 hex chars), and random-looking hex of
-// that shape is exactly what secret scanners flag — GitGuardian raised two
-// "Generic High Entropy Secret" findings on the first version of this file.
-const DRAFT_SLUG = 'draft-preview-event';
-const DRAFT_TOKEN = 'deadbeefdeadbeefdeadbeefdeadbeef';
-const LIVE_SLUG = 'published-event';
-const LIVE_TOKEN = 'feedfacefeedfacefeedfacefeedface';
-
-describe('draft preview through the short share URL (#1386)', () => {
-  let db; let cleanup; let app; let adminId; let foreignId;
-
-  // Two transports. admin_preview=1 is an intent flag authenticated by the
-  // admin cookie — what the frontend sends. ?preview=<jwt> is the legacy
-  // hand-built-link form, kept working.
-  const preview = (id = adminId) => `preview=${mintAdminToken(id)}`;
-  const asAdmin = (req, id = adminId) => req.set('Cookie', `admin_token=${mintAdminToken(id)}`);
-
-  async function insertEvent({ slug, token, isDraft }) {
-    await db('events').insert({
-      slug,
-      event_type: 'wedding',
-      event_name: slug,
-      event_date: '2026-09-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: `/gallery/${slug}/${token}`,
-      share_token: token,
-      require_password: 0,
-      expires_at: new Date(Date.now() + 7 * 864e5).toISOString(),
-      is_active: 1,
-      is_archived: 0,
-      is_draft: isDraft ? 1 : 0,
-      created_by: adminId,
-      created_at: new Date().toISOString(),
-    });
-  }
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    ({ adminId } = await seedMinimal(db));
-    await assignAdminRole(db, adminId);
-    const [row] = await db('admin_users').insert({
-      username: 'foreign', email: 'foreign@example.test', password_hash: 'unused', is_active: 1,
-    }).returning('id');
-    foreignId = row?.id ?? row;
-    await assignAdminRole(db, foreignId, 'viewer');
-
-    await insertEvent({ slug: DRAFT_SLUG, token: DRAFT_TOKEN, isDraft: true });
-    await insertEvent({ slug: LIVE_SLUG, token: LIVE_TOKEN, isDraft: false });
-
-    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('the reported case — admin previewing a draft', () => {
-    it('resolves the draft by share token (was 404 "Gallery Not Found")', async () => {
-      const res = await request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?${preview()}`);
-      expect(res.status).toBe(200);
-      expect(res.body.slug).toBe(DRAFT_SLUG);
-      expect(res.body.matchType).toBe('token');
-    });
-
-    it('resolves the draft by full share link', async () => {
-      const identifier = encodeURIComponent(`/gallery/${DRAFT_SLUG}/${DRAFT_TOKEN}`);
-      const res = await request(app).get(`/api/gallery/resolve/${identifier}?${preview()}`);
-      expect(res.status).toBe(200);
-      expect(res.body.slug).toBe(DRAFT_SLUG);
-    });
-
-    it('clears verify-token for the draft, the next step of the same flow', async () => {
-      const res = await request(app)
-        .get(`/api/gallery/${DRAFT_SLUG}/verify-token/${DRAFT_TOKEN}?${preview()}`);
-      expect(res.status).toBe(200);
-      expect(res.body.valid).toBe(true);
-    });
-  });
-
-  // The transport the SHIPPED frontend uses. The first cut of this fix only
-  // tested ?preview=, which the browser never sends on an API call — so the
-  // suite passed while the feature stayed broken end to end. Caught in review.
-  describe('admin_preview=1 authenticated by the admin cookie', () => {
-    it('resolves the draft', async () => {
-      const res = await asAdmin(
-        request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?admin_preview=1`),
-      );
-      expect(res.status).toBe(200);
-      expect(res.body.slug).toBe(DRAFT_SLUG);
-    });
-
-    it('clears verify-token', async () => {
-      const res = await asAdmin(
-        request(app).get(`/api/gallery/${DRAFT_SLUG}/verify-token/${DRAFT_TOKEN}?admin_preview=1`),
-      );
-      expect(res.status).toBe(200);
-      expect(res.body.valid).toBe(true);
-    });
-
-    it('serves /info for the draft', async () => {
-      const res = await asAdmin(
-        request(app).get(`/api/gallery/${DRAFT_SLUG}/info?admin_preview=1`),
-      );
-      expect(res.status).toBe(200);
-    });
-
-    it('serves draft MEDIA, which is what the flag on the URL is for', async () => {
-      // AuthenticatedImage/Video use native fetch and never see the axios
-      // interceptor, so the flag has to travel on the media URL itself. Without
-      // it the preview loaded metadata and showed no images at all.
-      const res = await asAdmin(
-        request(app).get(`/api/gallery/${DRAFT_SLUG}/photos?admin_preview=1`),
-      );
-      expect(res.status).toBe(200);
-    });
-
-    it('404s with the flag but no admin cookie — the flag authorizes nothing', async () => {
-      const res = await request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?admin_preview=1`);
-      expect(res.status).toBe(404);
-    });
-
-    it('404s with the flag and a cookie that is not an admin JWT', async () => {
-      const res = await request(app)
-        .get(`/api/gallery/resolve/${DRAFT_TOKEN}?admin_preview=1`)
-        .set('Cookie', 'admin_token=not-a-jwt');
-      expect(res.status).toBe(404);
-    });
-  });
-
-  describe('what must not move', () => {
-    it('404s an anonymous resolve of the draft token', async () => {
-      const res = await request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}`);
-      expect(res.status).toBe(404);
-    });
-
-    it('404s when ?preview= carries a token that is not a valid admin JWT', async () => {
-      const res = await request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?preview=not-a-jwt`);
-      expect(res.status).toBe(404);
-    });
-
-    it('404s when ?preview= is absent entirely', async () => {
-      const res = await request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?preview=`);
-      expect(res.status).toBe(404);
-    });
-
-    it('404s a non-owning admin on verify-token too (#1411)', async () => {
-      // This route selected its own columns and omitted created_by, so the
-      // ownership check saw an ownerless event and waved the caller through
-      // while /resolve and /info refused them.
-      const res = await asAdmin(
-        request(app).get(`/api/gallery/${DRAFT_SLUG}/verify-token/${DRAFT_TOKEN}?admin_preview=1`),
-        foreignId,
-      );
-      expect(res.status).toBe(404);
-    });
-
-    it('404s an admin who does not own the event (#1411)', async () => {
-      // Was 200: a valid signature was the whole check, so any admin previewed
-      // any draft, including another photographer's. Now ownership applies —
-      // the same rule requireEventOwnership enforces everywhere else.
-      const res = await asAdmin(
-        request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?admin_preview=1`),
-        foreignId,
-      );
-      expect(res.status).toBe(404);
-
-      const info = await asAdmin(
-        request(app).get(`/api/gallery/${DRAFT_SLUG}/info?admin_preview=1`),
-        foreignId,
-      );
-      expect(info.status).toBe(404);
-    });
-
-    it('404s an admin whose role grants no gallery permissions (#1411)', async () => {
-      // The owner, but stripped of events.view/photos.view.
-      const original = (await db('admin_users').where({ id: adminId }).first()).role_id;
-      await db('admin_users').where({ id: adminId }).update({ role_id: null });
-      try {
-        const res = await asAdmin(
-          request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?admin_preview=1`),
-        );
-        expect(res.status).toBe(404);
-      } finally {
-        await db('admin_users').where({ id: adminId }).update({ role_id: original });
-      }
-    });
-
-    it('404s an admin whose account has been deactivated (#1411)', async () => {
-      await db('admin_users').where({ id: adminId }).update({ is_active: 0 });
-      try {
-        const res = await asAdmin(
-          request(app).get(`/api/gallery/resolve/${DRAFT_TOKEN}?admin_preview=1`),
-        );
-        expect(res.status).toBe(404);
-      } finally {
-        await db('admin_users').where({ id: adminId }).update({ is_active: 1 });
-      }
-    });
-
-    it('404s an anonymous verify-token for the draft', async () => {
-      const res = await request(app)
-        .get(`/api/gallery/${DRAFT_SLUG}/verify-token/${DRAFT_TOKEN}`);
-      expect(res.status).toBe(404);
-    });
-
-    it('still withholds the share_token on a bare slug lookup (GHSA-rh8r)', async () => {
-      // The draft path must not become a way around the token-withholding rule.
-      const res = await request(app).get(`/api/gallery/resolve/${DRAFT_SLUG}?${preview()}`);
-      expect(res.status).toBe(200);
-      expect(res.body.matchType).toBe('slug');
-      expect(res.body.token).toBeUndefined();
-      expect(res.body.share_link).toBeUndefined();
-      expect(res.body.share_url).toBeUndefined();
-      expect(JSON.stringify(res.body)).not.toContain(DRAFT_TOKEN);
-    });
-
-    it('leaves the published gallery resolving anonymously, as before', async () => {
-      const res = await request(app).get(`/api/gallery/resolve/${LIVE_TOKEN}`);
-      expect(res.status).toBe(200);
-      expect(res.body.slug).toBe(LIVE_SLUG);
-      expect(res.body.token).toBe(LIVE_TOKEN);
-    });
-
-    it('still 404s an identifier that matches nothing', async () => {
-      const res = await request(app).get(`/api/gallery/resolve/no-such-gallery?${preview()}`);
-      expect(res.status).toBe(404);
-    });
-  });
-});

backend/__tests__/routes/galleryProtectedVideoUrls.test.js

@@ -1,163 +0,0 @@
-/**
- * Videos under enhanced/maximum image protection (#1370).
- *
- * Both halves of the video path used to be routed through /api/secure-images
- * once an event left `standard` protection, and neither half could carry a
- * video:
- *
- *   1. galleryQueryService emitted `/api/secure-images/{slug}/secure/{id}/{{token}}`
- *      as the video's `url`. The lightbox drops that straight into a <video>
- *      element, nothing substitutes `{{token}}` (the helper that could is
- *      unreferenced), and the route answers 403 "Invalid or expired token".
- *   2. Even with a valid token it would still fail: the secure-images route
- *      pipes every byte through secureImageService.processProtectedImage,
- *      which calls sharp() and throws on an mp4 → 404.
- *
- * The guest saw a poster frozen at 0:00 with no error of any kind.
- *
- * Videos now keep the JWT route at every protection level. That is not a new
- * exposure — thumbnails of those same videos have always been served from it —
- * so these tests also pin the inverse: still images must keep bouncing to the
- * secure endpoint. Every assertion here fails on the unfixed code except the
- * two guarding images.
- */
-
-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-video-urls-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'video-urls-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-video-urls-storage-'));
-
-const request = require('supertest');
-const express = require('express');
-const cookieParser = require('cookie-parser');
-const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
-
-const SLUG = 'protected-video-gallery';
-const VIDEO_BYTES = Buffer.from('not really an mp4, but the route only streams bytes');
-
-describe('videos stay playable under enhanced/maximum protection (#1370)', () => {
-  let db; let cleanup; let app; let eventId; let videoId; let imageId;
-
-  async function setProtection(level) {
-    await db('events').where('id', eventId).update({ protection_level: level });
-  }
-
-  async function photoPayload(id) {
-    const res = await request(app).get(`/api/gallery/${SLUG}/photos`);
-    expect(res.status).toBe(200);
-    const photo = res.body.photos.find((p) => p.id === id);
-    expect(photo).toBeDefined();
-    return photo;
-  }
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-
-    const ev = await db('events').insert({
-      slug: SLUG,
-      event_type: 'wedding',
-      event_name: 'Protected Video',
-      event_date: '2026-09-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: `/gallery/${SLUG}/s`,
-      share_token: 'protected-video-share',
-      expires_at: new Date(Date.now() + 7 * 864e5).toISOString(),
-      is_active: 1,
-      is_archived: 0,
-      is_draft: 0,
-      // Password-free so verifyGalleryAccess takes the public path, same as
-      // the sibling gallery suites.
-      require_password: 0,
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    eventId = ev[0]?.id ?? ev[0];
-
-    const mediaDir = path.join(process.env.STORAGE_PATH, 'events/active', SLUG, 'individual');
-    fs.mkdirSync(mediaDir, { recursive: true });
-    fs.writeFileSync(path.join(mediaDir, 'clip.mp4'), VIDEO_BYTES);
-    fs.writeFileSync(path.join(mediaDir, 'still.jpg'), Buffer.from('jpeg-ish'));
-
-    const vid = await db('photos').insert({
-      event_id: eventId,
-      filename: 'clip.mp4',
-      path: `${SLUG}/individual/clip.mp4`,
-      type: 'individual',
-      media_type: 'video',
-      mime_type: 'video/mp4',
-      duration: 43,
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    videoId = vid[0]?.id ?? vid[0];
-
-    const img = await db('photos').insert({
-      event_id: eventId,
-      filename: 'still.jpg',
-      path: `${SLUG}/individual/still.jpg`,
-      type: 'individual',
-      uploaded_at: new Date().toISOString(),
-    }).returning('id');
-    imageId = img[0]?.id ?? img[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(); });
-
-  describe.each(['enhanced', 'maximum'])('protection_level = %s', (level) => {
-    beforeAll(async () => { await setProtection(level); });
-
-    test('the video url is the JWT route, not a {{token}} template', async () => {
-      const photo = await photoPayload(videoId);
-      expect(photo.url).toBe(`/api/gallery/${SLUG}/photo/${videoId}`);
-      expect(photo.url).not.toContain('{{token}}');
-      expect(photo.requires_token).toBe(false);
-    });
-
-    test('the video streams instead of bouncing to the secure endpoint', async () => {
-      const res = await request(app).get(`/api/gallery/${SLUG}/photo/${videoId}`);
-      expect(res.status).toBe(200);
-      expect(res.headers['content-type']).toBe('video/mp4');
-      expect(res.headers['accept-ranges']).toBe('bytes');
-      expect(Buffer.from(res.body)).toEqual(VIDEO_BYTES);
-    });
-
-    test('range requests still work, so seeking is possible', async () => {
-      const res = await request(app)
-        .get(`/api/gallery/${SLUG}/photo/${videoId}`)
-        .set('Range', 'bytes=0-9');
-      expect(res.status).toBe(206);
-      expect(res.headers['content-range']).toBe(`bytes 0-9/${VIDEO_BYTES.length}`);
-    });
-
-    test('still images keep bouncing to the secure endpoint', async () => {
-      const photo = await photoPayload(imageId);
-      expect(photo.url).toBe(`/api/secure-images/${SLUG}/secure/${imageId}/{{token}}`);
-      expect(photo.requires_token).toBe(true);
-
-      const res = await request(app).get(`/api/gallery/${SLUG}/photo/${imageId}`);
-      expect(res.status).toBe(302);
-      expect(res.body.error).toBe('Secure access required');
-    });
-  });
-
-  describe('protection_level = standard', () => {
-    beforeAll(async () => { await setProtection('standard'); });
-
-    test('both media types take the JWT route, as before', async () => {
-      expect((await photoPayload(videoId)).url).toBe(`/api/gallery/${SLUG}/photo/${videoId}`);
-      expect((await photoPayload(imageId)).url).toBe(`/api/gallery/${SLUG}/photo/${imageId}`);
-    });
-  });
-});

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/passwordStrengthDos.test.js

@@ -1,80 +0,0 @@
-/**
- * POST /api/auth/password-strength is unauthenticated and feeds its body into
- * zxcvbn, whose matching is superlinear and runs synchronously on the event
- * loop. Behind express.json({ limit: '50mb' }) that made a single request a
- * whole-process denial of service: measured on this codebase, 1,000 characters
- * blocked for ~5 seconds and 5,000 did not return in two minutes.
- *
- * The control is the length cap inside validatePassword(), so it holds for
- * every caller. These tests pin the cap itself rather than the route, and use
- * a wall-clock ceiling that only an unbounded zxcvbn call can breach.
- */
-const { validatePassword, MAX_PASSWORD_LENGTH } = require('../../src/utils/passwordValidation');
-
-describe('password validation length cap (zxcvbn DoS)', () => {
-  it('rejects an over-length password without doing superlinear work', () => {
-    const huge = 'aA1!'.repeat(MAX_PASSWORD_LENGTH); // 4x the cap
-    const started = Date.now();
-    const result = validatePassword(huge);
-    const elapsed = Date.now() - started;
-
-    expect(result.valid).toBe(false);
-    expect(result.errors.join(' ')).toMatch(/at most 128 characters/);
-    // Unbounded, this input would not return for minutes.
-    expect(elapsed).toBeLessThan(250);
-  });
-
-  it('is bounded at the cap itself, the worst input it will still analyse', () => {
-    const atCap = 'aA1!'.repeat(MAX_PASSWORD_LENGTH / 4);
-    expect(atCap).toHaveLength(MAX_PASSWORD_LENGTH);
-
-    // 128 was chosen so the worst input the validator will still analyse costs
-    // about as much as an ordinary request (~41ms measured); 512 cost 1.4s.
-    const started = Date.now();
-    validatePassword(atCap);
-    expect(Date.now() - started).toBeLessThan(1000);
-  });
-
-  it('still accepts an ordinary strong password', () => {
-    const result = validatePassword('Tr0ub4dour&3-horse-battery');
-    expect(result.valid).toBe(true);
-  });
-
-  it('does not spin when a caller asks for a length the cap forbids', async () => {
-    // Codex review. generateSecurePassword retried by recursing on any invalid
-    // candidate, so the new cap made every candidate invalid for length > 128
-    // and turned the call into unbounded recursion. It now refuses up front,
-    // and the retry loop is bounded.
-    const { generateSecurePassword } = require('../../src/utils/passwordValidation');
-
-    expect(generateSecurePassword({ length: 16 })).toHaveLength(16);
-    expect(generateSecurePassword({ length: MAX_PASSWORD_LENGTH }))
-      .toHaveLength(MAX_PASSWORD_LENGTH);
-    expect(() => generateSecurePassword({ length: MAX_PASSWORD_LENGTH + 1 }))
-      .toThrow(/at most 128/);
-  });
-
-  it('does not echo the rejected password back in the error body', async () => {
-    // Codex review round 2. express-validator's errors.array() carries the
-    // submitted `value`, so the 400 for an oversized password returned the
-    // password itself -- reflecting a credential, and re-allocating up to the
-    // 50mb body limit on an unauthenticated endpoint, which partly undid the
-    // DoS fix this branch exists for.
-    const src = require('fs').readFileSync(
-      require('path').join(__dirname, '../../src/routes/auth.js'), 'utf8');
-
-    // No route may hand errors.array() straight to the response.
-    expect(src).not.toMatch(/errors:\s*errors\.array\(\)/);
-    // ...and the shared helper that replaces it must drop `value`.
-    const helper = require('fs').readFileSync(
-      require('path').join(__dirname, '../../src/utils/routeHelpers.js'), 'utf8');
-    expect(helper).toMatch(/safeValidationErrors\s*=\s*\(errors\)\s*=>\s*errors\.array\(\)\.map\(\(\{ value, \.\.\.rest \}\)/);
-  });
-
-  it('applies the cap through the context wrapper too', async () => {
-    const { validatePasswordInContext } = require('../../src/utils/passwordValidation');
-    const huge = 'aA1!'.repeat(MAX_PASSWORD_LENGTH);
-    const result = await validatePasswordInContext(huge, 'admin', {});
-    expect(result.valid).toBe(false);
-  });
-});

backend/__tests__/routes/publicContracts.test.js

@@ -25,18 +25,14 @@ process.env.STORAGE_PATH = path.join(tmpDir, 'storage');
 fs.mkdirSync(process.env.STORAGE_PATH, { recursive: true });
 process.env.JWT_SECRET = process.env.JWT_SECRET || 'crm-route-test-secret';
 
-const express = require('express');
-const cookieParser = require('cookie-parser');
 const request = require('supertest');
 const { bootCrmDb, seedMinimal, createPublicToken, buildRouteApp } = require('../integration/helpers/crmDb');
 const tokenGuards = require('../../src/utils/publicTokenGuards');
-const { errorHandler } = require('../../src/middleware/errorHandler');
 
 describe('publicContracts routes', () => {
   let db;
   let cleanup;
   let app;
-  let appWithErrorHandler;
   let customerId;
   let contractId;
 
@@ -55,17 +51,6 @@ describe('publicContracts routes', () => {
     contractId = inserted[0]?.id ?? inserted[0];
 
     app = buildRouteApp('/api/public/contracts', require('../../src/routes/publicContracts'));
-
-    // A second app instance wired to the REAL production error handler
-    // (buildRouteApp's is a simplified stand-in that only reads
-    // err.statusCode/err.status, which a bare MulterError doesn't set).
-    // Used below to verify the actual 4xx contract end-to-end, not just
-    // that multer aborted the request.
-    appWithErrorHandler = express();
-    appWithErrorHandler.use(express.json());
-    appWithErrorHandler.use(cookieParser());
-    appWithErrorHandler.use('/api/public/contracts', require('../../src/routes/publicContracts'));
-    appWithErrorHandler.use(errorHandler);
   }, 120000);
 
   afterAll(async () => {
@@ -146,40 +131,6 @@ describe('publicContracts routes', () => {
         .attach('file', Buffer.from('%PDF-1.4 fake'), 'signed.pdf');
       expect(res.status).toBe(404);
     });
-
-    // CVE-2026-82333 regression (#1374 follow-up): multer 2.3.0 added an
-    // opt-in `fieldArrayIndexLimit` that must be set to actually close the
-    // field-parser DoS — the version bump alone does nothing. This route is
-    // unauthenticated (token-in-URL only), so it's the sharpest place to
-    // prove a crafted request with an oversized array-index field name
-    // (`evil[999999999]`) is rejected rather than accepted or left to hang.
-    it('rejects a multipart request with an oversized array-index field name', async () => {
-      const token = await createPublicToken(db, 'contract_action_tokens', {
-        contract_id: contractId,
-      });
-      const res = await request(app)
-        .post(`/api/public/contracts/${token}/upload-signed-pdf`)
-        .field('evil[999999999]', 'x')
-        .attach('file', Buffer.from('%PDF-1.4 fake'), 'signed.pdf');
-      // multer aborts the request before the handler runs; buildRouteApp's
-      // generic error handler falls back to 500 for a bare MulterError
-      // (see appWithErrorHandler test below for the real 4xx contract), so
-      // here we only assert the upload was NOT accepted/processed.
-      expect(res.status).toBeGreaterThanOrEqual(400);
-      expect(res.body.error).not.toBe(undefined);
-    });
-
-    it('maps the oversized array-index rejection to a 400 through the real error handler', async () => {
-      const token = await createPublicToken(db, 'contract_action_tokens', {
-        contract_id: contractId,
-      });
-      const res = await request(appWithErrorHandler)
-        .post(`/api/public/contracts/${token}/upload-signed-pdf`)
-        .field('evil[999999999]', 'x')
-        .attach('file', Buffer.from('%PDF-1.4 fake'), 'signed.pdf');
-      expect(res.status).toBe(400);
-      expect(res.body.code).toBe('VALIDATION_ERROR');
-    });
   });
 
   describe('GET /:token/pdf', () => {

backend/__tests__/routes/restorePathAllowlist.test.js

@@ -22,38 +22,29 @@ process.env.JWT_SECRET = process.env.JWT_SECRET || 'restorepath-test-secret';
 
 const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
 
-// `bootCrmDb()` hands back the process-wide `db` singleton (module cache —
-// see its own comment), so it must only be called ONCE per test file: a
-// second call re-runs migrations against the same connection, and the first
-// call's `cleanup()` (db.destroy()) would tear down the connection both
-// describe blocks below share. Boot once at file scope; each describe below
-// only touches app_settings / env vars, never the connection lifecycle.
-let db; let cleanup; let checkRestorePathsAllowed;
-
-beforeAll(async () => {
-  ({ db, cleanup } = await bootCrmDb());
-  await seedMinimal(db);
-  ({ checkRestorePathsAllowed } = require('../../src/routes/adminRestore')._internal);
-}, 120000);
-
-afterAll(async () => { if (cleanup) await cleanup(); });
-
-async function setBackupSetting(key, value) {
-  const existing = await db('app_settings').where({ setting_key: key }).first();
-  if (existing) {
-    await db('app_settings').where({ setting_key: key }).update({ setting_value: JSON.stringify(value) });
-  } else {
-    await db('app_settings').insert({
-      setting_key: key, setting_value: JSON.stringify(value), setting_type: 'backup',
-    });
-  }
-}
-
 describe('restore path allowlist (GHSA-fw4c)', () => {
+  let db; let cleanup; let checkRestorePathsAllowed;
+
   beforeAll(async () => {
+    ({ db, cleanup } = await bootCrmDb());
+    await seedMinimal(db);
+
     // Configure a backup root so the allowlist is actually active.
-    await setBackupSetting('backup_destination_path', '/backup');
-  });
+    for (const [key, value] of [['backup_destination_path', '/backup']]) {
+      const existing = await db('app_settings').where({ setting_key: key }).first();
+      if (existing) {
+        await db('app_settings').where({ setting_key: key }).update({ setting_value: JSON.stringify(value) });
+      } else {
+        await db('app_settings').insert({
+          setting_key: key, setting_value: JSON.stringify(value), setting_type: 'backup',
+        });
+      }
+    }
+
+    ({ checkRestorePathsAllowed } = require('../../src/routes/adminRestore')._internal);
+  }, 120000);
+
+  afterAll(async () => { if (cleanup) await cleanup(); });
 
   it('allows the wizard\'s source TYPE tokens', async () => {
     for (const source of ['local', 's3', 'upload']) {
@@ -93,89 +84,3 @@ describe('restore path allowlist (GHSA-fw4c)', () => {
     expect(err).toBeNull();
   });
 });
-
-/**
- * GHSA-xfvx-j447-732c: `checkRestorePathsAllowed` constrained the top-level
- * `source`/`manifestPath` request fields (GHSA-fw4c above), but never looked
- * INSIDE the manifest itself. `manifest.database.backup_file` — handed
- * straight to restoreService's candidate resolution and eventually
- * interpolated into `sqlite3 .restore '<path>'` — was unchecked, so an
- * absolute path there could point the restore at an arbitrary file even
- * though `source`/`manifestPath` both passed containment.
- */
-describe('restore path allowlist — manifest database.backup_file containment (GHSA-xfvx)', () => {
-  let tmpRoot;
-
-  beforeAll(async () => {
-    await setBackupSetting('backup_destination_path', '/backup');
-
-    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-xfvx-manifest-'));
-    // Additional allowed root via the documented escape hatch — keeps this
-    // describe block's fixtures out of the shared '/backup' root above.
-    process.env.RESTORE_ALLOWED_ROOTS = tmpRoot;
-  });
-
-  afterAll(() => {
-    delete process.env.RESTORE_ALLOWED_ROOTS;
-    fs.rmSync(tmpRoot, { recursive: true, force: true });
-  });
-
-  const writeManifest = (name, databaseSection) => {
-    const manifestPath = path.join(tmpRoot, name);
-    fs.writeFileSync(manifestPath, JSON.stringify({
-      manifest: { version: '1.0', id: 'test' },
-      backup: { type: 'full' },
-      system: { platform: 'linux' },
-      application: { version: '1.0.0' },
-      files: { count: 0, manifest: [] },
-      database: databaseSection,
-      verification: { total_checksum: null, checksum_algorithm: null },
-    }));
-    return manifestPath;
-  };
-
-  it('rejects a manifest whose database.backup_file is an absolute path outside every configured root', async () => {
-    const manifestPath = writeManifest('evil-1.json', { backup_file: '/etc/passwd' });
-    const err = await checkRestorePathsAllowed({ source: 'local', manifestPath });
-    expect(err).toMatch(/database\.backup_file must be inside a configured backup location/i);
-  });
-
-  it('accepts a manifest whose database.backup_file is an absolute path inside a configured root', async () => {
-    const dbFile = path.join(tmpRoot, 'database', 'picpeak-db-sqlite-1.sql.gz');
-    fs.mkdirSync(path.dirname(dbFile), { recursive: true });
-    fs.writeFileSync(dbFile, 'not a real sqlite dump, just a fixture');
-    const manifestPath = writeManifest('legit-1.json', { backup_file: dbFile });
-    const err = await checkRestorePathsAllowed({ source: 'local', manifestPath });
-    expect(err).toBeNull();
-  });
-
-  it('does not choke on a manifest whose database.backup_file is a legitimate relative path', async () => {
-    // Relative candidates are resolved against restoreService's own
-    // `backupPath` (which this route-level pre-check doesn't have — it only
-    // sees `source`/`manifestPath`), so this layer intentionally defers
-    // relative-path containment to restoreService.performDatabaseRestore
-    // and must not false-positive here.
-    const manifestPath = writeManifest('legit-2.json', { backup_file: 'database/picpeak-db-sqlite-1.sql.gz' });
-    const err = await checkRestorePathsAllowed({ source: 'local', manifestPath });
-    expect(err).toBeNull();
-  });
-
-  it('rejects everything when no backup location is configured at all (fail closed, not fail open)', async () => {
-    // Simulate an install that never had backup_destination_path /
-    // backup_manifest_path seeded/configured, and isn't using the
-    // RESTORE_ALLOWED_ROOTS escape hatch either.
-    const savedRoots = process.env.RESTORE_ALLOWED_ROOTS;
-    delete process.env.RESTORE_ALLOWED_ROOTS;
-    await db('app_settings').whereIn('setting_key', ['backup_destination_path', 'backup_manifest_path']).del();
-
-    try {
-      const err = await checkRestorePathsAllowed({
-        source: '/backup/run-1', manifestPath: '/backup/run-1/manifest.json',
-      });
-      expect(err).toMatch(/no backup location is configured/i);
-    } finally {
-      process.env.RESTORE_ALLOWED_ROOTS = savedRoots;
-      await setBackupSetting('backup_destination_path', '/backup');
-    }
-  });
-});

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/downloadZipRegenConcurrency.test.js

@@ -1,127 +0,0 @@
-/**
- * Background zip rebuilds are capped (#1399).
- *
- * invalidateAll() invalidates every event holding a cached zip, and each
- * invalidate() arms its own debounce timer in the same tick — so they all fire
- * together. Every build opens its own storage reads, so a settings change
- * across 25 events was enough to exhaust the S3 agent pool and stall uploads,
- * thumbnails and gallery reads until the burst drained.
- *
- * The cap is on the BACKGROUND path only: a guest waiting on a download must
- * not be queued behind a settings-change burst.
- */
-jest.mock('../../src/database/db', () => ({ db: jest.fn() }));
-jest.mock('../../src/utils/logger', () => ({
-  info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn(),
-}));
-
-const { db } = require('../../src/database/db');
-const service = require('../../src/services/downloadZipService');
-
-const flush = () => new Promise((r) => setImmediate(r));
-
-describe('downloadZipService background regen concurrency (#1399)', () => {
-  let peak;
-  let inFlight;
-  let release;
-
-  beforeEach(() => {
-    // setImmediate must stay real: the flush() helper below rides on it, and
-    // jest's modern fake timers mock it too.
-    jest.useFakeTimers({ doNotFake: ['setImmediate'] });
-    peak = 0;
-    inFlight = 0;
-    release = [];
-    service.regenActive = 0;
-    service.regenWaiters = [];
-    service.debounceTimers.clear();
-    service.activeBuilds.clear();
-
-    jest.spyOn(service, 'generateZip').mockImplementation(() => {
-      inFlight += 1;
-      peak = Math.max(peak, inFlight);
-      return new Promise((resolve) => {
-        release.push(() => { inFlight -= 1; resolve(); });
-      });
-    });
-    jest.spyOn(service, '_cleanup').mockResolvedValue(undefined);
-  });
-
-  afterEach(() => {
-    jest.useRealTimers();
-    jest.restoreAllMocks();
-  });
-
-  it('never runs more than two rebuilds at once, however many fire together', async () => {
-    const rows = Array.from({ length: 12 }, (_, i) => ({ id: i + 1 }));
-    db.mockReturnValue({
-      whereNotNull: () => ({ select: () => Promise.resolve(rows) }),
-    });
-
-    await service.invalidateAll();
-    // Every debounce timer was armed in the same tick — fire them all.
-    jest.runAllTimers();
-    await flush();
-
-    expect(peak).toBe(2);
-    expect(service.generateZip).toHaveBeenCalledTimes(2);
-  });
-
-  it('starts the next rebuild as each one finishes', async () => {
-    const rows = Array.from({ length: 5 }, (_, i) => ({ id: i + 1 }));
-    db.mockReturnValue({
-      whereNotNull: () => ({ select: () => Promise.resolve(rows) }),
-    });
-
-    await service.invalidateAll();
-    jest.runAllTimers();
-    await flush();
-    expect(service.generateZip).toHaveBeenCalledTimes(2);
-
-    release.shift()();
-    await flush();
-    expect(service.generateZip).toHaveBeenCalledTimes(3);
-    expect(peak).toBe(2);
-
-    while (release.length) { release.shift()(); await flush(); }
-    expect(service.generateZip).toHaveBeenCalledTimes(5);
-    expect(peak).toBe(2);
-  });
-
-  it('does not queue a foreground download behind the burst', async () => {
-    const rows = Array.from({ length: 6 }, (_, i) => ({ id: i + 1 }));
-    db.mockReturnValue({
-      whereNotNull: () => ({ select: () => Promise.resolve(rows) }),
-    });
-
-    await service.invalidateAll();
-    jest.runAllTimers();
-    await flush();
-    expect(service.generateZip).toHaveBeenCalledTimes(2);
-
-    // A guest asking for a zip right now calls generateZip directly. It must
-    // not park behind the two rebuilds already holding the slots.
-    service.generateZip(999);
-    await flush();
-    expect(service.generateZip).toHaveBeenCalledWith(999);
-    expect(inFlight).toBe(3);
-  });
-
-  it('leaves the queue empty once every rebuild has run', async () => {
-    const rows = Array.from({ length: 5 }, (_, i) => ({ id: i + 1 }));
-    db.mockReturnValue({
-      whereNotNull: () => ({ select: () => Promise.resolve(rows) }),
-    });
-
-    await service.invalidateAll();
-    jest.runAllTimers();
-    await flush();
-    expect(service.regenWaiters.length).toBeGreaterThan(0);
-
-    while (release.length) { release.shift()(); await flush(); }
-    // Nothing parked, nothing counted as running — no slot leaked on the way
-    // through, which is what would quietly wedge the next burst.
-    expect(service.regenWaiters).toHaveLength(0);
-    expect(service.regenActive).toBe(0);
-  });
-});

backend/__tests__/services/downloadZipSocketLeak.test.js

@@ -1,193 +0,0 @@
-/**
- * A failed pre-zip build must not leave storage reads open.
- *
- * The builder opened one storage read per photo and handed the raw stream to
- * archiver. archiver drains its queue one entry at a time, so on an S3 backend
- * every photo beyond the one being written parked a socket with a full receive
- * buffer, and the error path (a source stream dying, or a photo upload
- * invalidating the build) walked away from all of them. archiver's abort()
- * does not touch the source streams, and the AWS SDK arms its socket timeout
- * on a 3s delay then clears it once the response headers arrive, so nothing
- * ever reclaimed those sockets. On a live server 43 of the 50 pooled sockets
- * ended up stuck for days and photo uploads stopped completing.
- */
-
-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-zipleak-')), 'db.sqlite',
-);
-process.env.JWT_SECRET = process.env.JWT_SECRET || 'zipleak-test-secret';
-process.env.STORAGE_PATH = fs.mkdtempSync(path.join(os.tmpdir(), 'picpeak-zipleak-storage-'));
-
-const { Readable } = require('stream');
-
-const PHOTO_COUNT = 6;
-const MAX_INFLIGHT_READS = 2;
-
-// One storage read. It never ends on its own, which is what a large photo
-// looks like to the builder: the bytes only move while archiver pulls them.
-class StoredObject extends Readable {
-  constructor(key, failAfterReads, chunks) {
-    super();
-    this.key = key;
-    this.failAfterReads = failAfterReads;
-    this.chunks = chunks;
-    this.reads = 0;
-  }
-
-  _read() {
-    this.reads += 1;
-    if (this.failAfterReads && this.reads > this.failAfterReads) {
-      // What a dropped connection to S3 looks like in Node.
-      this.destroy(new Error('aborted'));
-      return;
-    }
-    this.push(this.reads > this.chunks ? null : Buffer.alloc(4096, 1));
-  }
-}
-
-const reads = { opened: [], live: 0, peak: 0 };
-const failingKey = { value: null };
-const onOpen = { fn: null };
-// A read only finishes when the build pulls the whole object. Photos big
-// enough to matter never finish inside one archiver turn, and a stream that
-// ends on its own would be auto-destroyed and hide the leak.
-const objectChunks = { value: Number.POSITIVE_INFINITY };
-
-function openStoredObject(key) {
-  const stream = new StoredObject(key, key === failingKey.value ? 1 : 0, objectChunks.value);
-  reads.opened.push(stream);
-  reads.live += 1;
-  if (reads.live > reads.peak) reads.peak = reads.live;
-  let settled = false;
-  const settle = () => { if (!settled) { settled = true; reads.live -= 1; } };
-  stream.once('end', settle);
-  stream.once('close', settle);
-  if (onOpen.fn) onOpen.fn(reads.opened.length);
-  return stream;
-}
-
-const mockStorage = {
-  kind: () => 's3',
-  get: jest.fn(async (key) => openStoredObject(key)),
-  getToFile: jest.fn(async () => undefined),
-  putFromFile: jest.fn(async () => undefined),
-  stat: jest.fn(async () => ({ size: 1234, mtime: new Date() })),
-  delete: jest.fn(async () => undefined),
-  exists: jest.fn(async () => true),
-};
-
-jest.mock('../../src/services/storage', () => ({
-  getStorage: () => mockStorage,
-  initStorage: async () => mockStorage,
-}));
-
-// Nothing to watermark, so the builder takes the stream-from-storage branch,
-// which is the one that holds sockets. (This branch has no rendition step —
-// the resize/watermark split that main mocks out here does not exist yet.)
-jest.mock('../../src/services/watermarkService', () => ({
-  getWatermarkSettings: jest.fn(async () => ({ enabled: false })),
-  applyWatermark: jest.fn(),
-}));
-
-const { bootCrmDb, seedMinimal } = require('../integration/helpers/crmDb');
-const downloadZipService = require('../../src/services/downloadZipService');
-
-describe('pre-zip build releases its storage reads', () => {
-  let db; let cleanup; let eventId;
-
-  beforeAll(async () => {
-    ({ db, cleanup } = await bootCrmDb());
-    await seedMinimal(db);
-
-    const ev = await db('events').insert({
-      slug: 'zipleak',
-      event_type: 'wedding',
-      event_name: 'Zip Leak',
-      event_date: '2026-09-01',
-      host_email: 'h@example.com',
-      admin_email: 'a@example.com',
-      password_hash: 'x',
-      share_link: '/gallery/zipleak/s',
-      share_token: 'zipleak-share',
-      expires_at: new Date(Date.now() + 7 * 864e5).toISOString(),
-      is_active: 1,
-      is_archived: 0,
-      is_draft: 0,
-      require_password: 0,
-      allow_downloads: 1,
-      created_at: new Date().toISOString(),
-    }).returning('id');
-    eventId = ev[0]?.id ?? ev[0];
-
-    for (let i = 0; i < PHOTO_COUNT; i += 1) {
-      await db('photos').insert({
-        event_id: eventId,
-        filename: `photo-${i}.jpg`,
-        path: `zipleak/photo-${i}.jpg`,
-        type: 'individual',
-        source_origin: 'managed',
-        mime_type: 'image/jpeg',
-        visibility: 'visible',
-        uploaded_at: new Date(Date.now() - i * 1000).toISOString(),
-      });
-    }
-  }, 120000);
-
-  afterAll(async () => { if (cleanup) await cleanup(); });
-
-  beforeEach(() => {
-    reads.opened = [];
-    reads.live = 0;
-    reads.peak = 0;
-    failingKey.value = null;
-    onOpen.fn = null;
-    objectChunks.value = Number.POSITIVE_INFINITY;
-    mockStorage.get.mockClear();
-    downloadZipService.versions.clear();
-    downloadZipService.activeBuilds.clear();
-  });
-
-  it('destroys every open read when a source stream dies mid-build', async () => {
-    // The oldest photo is written first, so failing it strands the rest.
-    failingKey.value = 'events/active/zipleak/photo-0.jpg';
-
-    const result = await downloadZipService.generateZip(eventId);
-
-    expect(result.success).toBe(false);
-    expect(reads.opened.length).toBeGreaterThan(1);
-    const stranded = reads.opened.filter((s) => !s.destroyed);
-    expect(stranded.map((s) => s.key)).toEqual([]);
-  });
-
-  it('destroys every open read when an upload invalidates the build', async () => {
-    // What adminPhotos does on every upload, delete and bulk edit, landing
-    // while the archive is half built.
-    onOpen.fn = (count) => {
-      if (count !== 2) return;
-      downloadZipService.invalidate(eventId);
-      // invalidate() also schedules a rebuild; this test is not about that.
-      clearTimeout(downloadZipService.debounceTimers.get(eventId));
-      downloadZipService.debounceTimers.delete(eventId);
-    };
-
-    const result = await downloadZipService.generateZip(eventId);
-
-    expect(result).toEqual({ success: false, error: 'Build invalidated' });
-    expect(reads.opened.filter((s) => !s.destroyed).map((s) => s.key)).toEqual([]);
-  });
-
-  it('never holds more storage reads open than the build needs', async () => {
-    objectChunks.value = 8;
-
-    const result = await downloadZipService.generateZip(eventId);
-
-    expect(result.success).toBe(true);
-    expect(mockStorage.get).toHaveBeenCalledTimes(PHOTO_COUNT);
-    expect(reads.peak).toBeLessThanOrEqual(MAX_INFLIGHT_READS);
-  });
-});

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

@@ -91,16 +91,15 @@ describe('ensurePreviewImage — external/reference sources (#1078)', () => {
   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 relpath = `${sourceOrigin}-shot.jpg`;
+      await writeSourceJpeg(path.join(EXTERNAL_ROOT, EVENT.external_path, relpath));
 
       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,
+        external_relpath: relpath,
+        filename: relpath,
         preview_path: null,
       };
 
@@ -108,7 +107,7 @@ describe('ensurePreviewImage — external/reference sources (#1078)', () => {
 
       // 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(key).toBe(`previews/preview_ext${photo.id}_${relpath}`);
       expect(await storage.exists(key)).toBe(true);
 
       const meta = await sharp(storage.resolveLocalPath(key)).metadata();
@@ -125,14 +124,14 @@ describe('ensurePreviewImage — external/reference sources (#1078)', () => {
   );
 
   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 relpath = 'already-previewed.jpg';
+    await writeSourceJpeg(path.join(EXTERNAL_ROOT, EVENT.external_path, relpath));
     const photo = {
       id: 103,
       event_id: EVENT.id,
       source_origin: 'external',
-      external_relpath: path.join(EVENT.external_path, name),
-      filename: name,
+      external_relpath: relpath,
+      filename: relpath,
       preview_path: null,
     };
 
@@ -180,19 +179,19 @@ describe('ensurePreviewImage — external/reference sources (#1078)', () => {
     // 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 relpath = 'column-starved.jpg';
+    await writeSourceJpeg(path.join(EXTERNAL_ROOT, EVENT.external_path, relpath));
     const starved = {
       id: 106,
       event_id: EVENT.id,
-      external_relpath: path.join(EVENT.external_path, name),
+      external_relpath: relpath,
       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}`);
+      imageProcessor.ensurePreviewImage({ ...starved, source_origin: 'external', filename: relpath })
+    ).resolves.toBe(`previews/preview_ext106_${relpath}`);
   });
 
   it('still routes managed photos through the storage backend', async () => {

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);
-  });
-});