Merge pull request #353 from the-luap/release-please--branches--beta

chore(beta): release 3.32.2-beta.0

.env.example

@@ -7,6 +7,34 @@ NODE_ENV=production
 # JWT Secret (generate with: openssl rand -base64 64)
 JWT_SECRET=your_very_long_random_jwt_secret_here
 
+# Auth cookie Secure flag
+#   unset  - default: follows NODE_ENV (production=true, dev=false)
+#   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access)
+#   false  - never set Secure (allows HTTP; cookies not protected on HTTPS)
+#   auto   - decide per request: Secure on HTTPS, not on HTTP
+#
+# Use COOKIE_SECURE=auto if your deployment is reachable over both HTTPS
+# (via reverse proxy like Nginx Proxy Manager, Traefik, Caddy) AND plain
+# HTTP (e.g. LAN access at http://192.168.x.x:3010). The backend reads
+# req.secure from Express, which respects the X-Forwarded-Proto header
+# when the proxy is in the trust list.
+#
+# Requirements for auto mode:
+#   1. Your reverse proxy MUST send X-Forwarded-Proto: https on HTTPS
+#      requests. Standard configs for NPM/Traefik/Caddy do this by default.
+#   2. The proxy must be on a trusted IP range. By default PicPeak trusts
+#      loopback and private networks (127.0.0.1, 10.x, 172.16-31.x,
+#      192.168.x, link-local). Proxies outside those ranges need custom
+#      trust proxy configuration.
+# COOKIE_SECURE=auto
+
+# Cookie SameSite attribute (Lax | Strict | None). Default: Lax
+# COOKIE_SAMESITE=Lax
+
+# Cookie Domain — set this if serving auth cookies across subdomains.
+# Leave unset for same-origin setups.
+# COOKIE_DOMAIN=.example.com
+
 # Database Configuration (PostgreSQL)
 DATABASE_CLIENT=pg
 DB_USER=picpeak
@@ -22,6 +50,7 @@ REDIS_PASSWORD=your_secure_redis_password_here
 # Admin Account (initial setup)
 ADMIN_USERNAME=admin
 ADMIN_EMAIL=admin@yourdomain.com
+ADMIN_PASSWORD=your_secure_admin_password_here
 
 # Email Configuration
 # For Gmail: use app-specific password
@@ -39,6 +68,11 @@ EMAIL_FROM=noreply@yourdomain.com
 FRONTEND_URL=https://yourdomain.com
 ADMIN_URL=https://yourdomain.com
 
+# API URL for email assets (logos, images in notification emails)
+# This must be the publicly accessible URL where email recipients can load images.
+# If not set, defaults to http://localhost:3001 which will show broken images in emails.
+API_URL=https://yourdomain.com/api
+
 # Frontend API base
 # For pre-built images and production behind a reverse proxy, keep '/api'.
 # If you rebuild the frontend yourself, you may set a full URL at build time.
@@ -80,6 +114,85 @@ APP_STORAGE=./storage
 APP_DATA=./data
 LOGS=./logs
 
+# ─── Storage Backend ────────────────────────────────────────────────────────
+# PicPeak can store photos, thumbnails and archive zips on the local filesystem
+# (default) or on any S3-compatible object store (AWS S3, MinIO, Cloudflare R2,
+# Backblaze B2, Wasabi, DigitalOcean Spaces, …).
+#
+# STORAGE_BACKEND=local (default)
+#   Uses STORAGE_PATH on the local filesystem. Backwards compatible — every
+#   existing deployment keeps working unchanged.
+#
+# STORAGE_BACKEND=s3
+#   Reads STORAGE_S3_* below. Auto-import via the filesystem watcher is
+#   disabled in this mode (S3 has no inotify) — every photo must enter via the
+#   admin upload UI/API. Run `node backend/scripts/migrate-storage.js` to copy
+#   existing local content to S3 before flipping the env.
+#
+# STORAGE_BACKEND=local
+#
+# STORAGE_S3_BUCKET=picpeak
+# STORAGE_S3_REGION=us-east-1
+# STORAGE_S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
+# STORAGE_S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
+# Custom endpoint — set this for MinIO / R2 / B2 / Spaces. Leave unset for AWS.
+# STORAGE_S3_ENDPOINT=https://s3.us-west-002.backblazeb2.com
+# Optional namespace prefix inside the bucket — useful for multi-deployment buckets.
+# STORAGE_S3_PREFIX=picpeak
+# STORAGE_S3_FORCE_PATH_STYLE=false   # MinIO needs true; auto-on when endpoint is set
+# STORAGE_S3_SSL=true
+#
+# Minimum IAM policy (AWS S3) for the bucket above:
+#   {
+#     "Version": "2012-10-17",
+#     "Statement": [{
+#       "Effect": "Allow",
+#       "Action": [
+#         "s3:GetObject", "s3:PutObject", "s3:DeleteObject",
+#         "s3:ListBucket", "s3:GetBucketLocation"
+#       ],
+#       "Resource": [
+#         "arn:aws:s3:::picpeak",
+#         "arn:aws:s3:::picpeak/*"
+#       ]
+#     }]
+#   }
+#
+# EXTERNAL_MEDIA_ROOT (above) always lives on the local filesystem regardless
+# of STORAGE_BACKEND — reference-mode galleries are not migrated to S3 in v1.
+
+# ─── Outbound Webhooks (#327) ────────────────────────────────────────────────
+# 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.
+#
+# WEBHOOK_ALLOW_PRIVATE_URLS (default: false)
+#   Block URLs resolving to private IPs / loopback / .local etc. as an
+#   SSRF mitigation. Set to "true" ONLY in dev when your receiver is on
+#   the same docker network or localhost. Production deployments must
+#   leave this OFF.
+# WEBHOOK_ALLOW_PRIVATE_URLS=false
+#
+# WEBHOOK_DELIVERY_INTERVAL_MS (default: 5000)
+#   How often the worker polls webhook_deliveries for pending rows.
+# WEBHOOK_DELIVERY_INTERVAL_MS=5000
+#
+# WEBHOOK_DELIVERY_CONCURRENCY (default: 5)
+#   Maximum in-flight deliveries per worker tick. One slow consumer can
+#   monopolize all 5 slots — bump this if your receivers are slow OR ship
+#   a separate webhook-only deployment.
+# WEBHOOK_DELIVERY_CONCURRENCY=5
+#
+# WEBHOOK_HTTP_TIMEOUT_MS (default: 10000)
+#   Per-request timeout. Beyond this, the delivery is recorded as a
+#   network error and retried.
+# WEBHOOK_HTTP_TIMEOUT_MS=10000
+#
+# WEBHOOK_MAX_ATTEMPTS (default: 5)
+#   Total attempts before a delivery is marked failed. Backoff between
+#   attempts is exponential: 1m, 5m, 30m, 2h, 12h.
+# WEBHOOK_MAX_ATTEMPTS=5
+
 # 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/ISSUE_TEMPLATE/security_vulnerability.md

@@ -9,7 +9,7 @@ assignees: ''
 
 ⚠️ **IMPORTANT: For serious security vulnerabilities, please DO NOT create a public issue.**
 
-Instead, please email security@example.com with the details.
+Instead, please use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new) or email **info@picpeak.app** with the details.
 
 For minor security improvements or questions, you can use this template:
 

.gitignore

@@ -69,7 +69,9 @@ backend/data/
 backend/docs/
 backend/logs/
 logs/
-storage/
+# Anchored to repo root: matches the top-level runtime storage dir,
+# NOT backend/src/services/storage/ (the storage backend abstraction code).
+/storage/
 data/
 certbot/
 
@@ -86,11 +88,44 @@ docs/*_PLAN.md
 docs/test-*.md
 docs/feature-*.md
 
+# Scaffolding documentation (local development reference)
+docs/DATABASE_SCHEMA.md
+docs/BACKEND_SERVICES.md
+docs/API_ROUTES.md
+docs/FRONTEND_ARCHITECTURE.md
+docs/DEVELOPER_ONBOARDING.md
+docs/ENVIRONMENT_VARIABLES.md
+
+# Build artifact: OpenAPI spec generated locally + synced into the
+# picpeak-docs repo. Never tracked here — the docs site at
+# docs.picpeak.app is the source of truth.
+docs/openapi.json
+docs/openapi.yaml
+
 # Local backup directory (from testing)
 backup/
 
 # Local artifacts from browser tooling
 .playwright-mcp/
 
+# Local-only E2E suite (never pushed; runs as pre-push gate on this machine)
+tests/e2e/local/
+playwright-local-results/
+e2e-test.log
+scripts/e2e-local.sh
+
 # Local SQLite files in backend
 backend/*.sqlite*
+backend/*.db
+
+# Test files and artifacts
+test-images/
+test-logo*.jpg
+test-logo*.png
+test-results/
+
+# Development docker compose
+docker-compose.dev.yml
+
+# New layout development files
+new-layouts/

.release-please-manifest-beta.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.0.0-beta.0"
+  ".": "3.32.2-beta.0"
 }

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.3.1"
+  ".": "2.6.1"
 }

CHANGELOG.md

@@ -5,6 +5,974 @@ All notable changes to PicPeak will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.32.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.32.1-beta.0...v3.32.2-beta.0) (2026-05-01)
+
+
+### Bug Fixes
+
+* events search/counters ([#346](https://github.com/the-luap/picpeak/issues/346)), lazy gallery skeleton ([#321](https://github.com/the-luap/picpeak/issues/321)), smooth lightbox swipe ([#348](https://github.com/the-luap/picpeak/issues/348)) ([6229b38](https://github.com/the-luap/picpeak/commit/6229b38bac90cc0c538a72688efae3be77a3bb08))
+* **events:** server-side search/pagination to remove first-100 cap ([#346](https://github.com/the-luap/picpeak/issues/346)) ([a5b20ca](https://github.com/the-luap/picpeak/commit/a5b20ca3fe77df665d4a9744413d7ee4054858f0))
+* **gallery:** lazy-render skeleton grid for fast loads ([#321](https://github.com/the-luap/picpeak/issues/321) follow-up) ([d9d8137](https://github.com/the-luap/picpeak/commit/d9d81372b80f7d44dca54b7993f52c36574048c9))
+* **lightbox:** smooth carousel swipe + drop instructional hint ([#348](https://github.com/the-luap/picpeak/issues/348)) ([743086d](https://github.com/the-luap/picpeak/commit/743086d3cb9100fb163bc9d04d968e5b611a1f99))
+
+## [3.32.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.32.0-beta.0...v3.32.1-beta.0) (2026-04-30)
+
+
+### Documentation
+
+* move documentation to docs.picpeak.app, drop in-repo copies ([02ed5d4](https://github.com/the-luap/picpeak/commit/02ed5d400736f966283a138dedde2455448067ff))
+* move documentation to docs.picpeak.app, drop in-repo copies ([0faf9b3](https://github.com/the-luap/picpeak/commit/0faf9b32816f5f94aa584d2336cdb1e0b7082239))
+
+## [3.32.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.31.1-beta.0...v3.32.0-beta.0) (2026-04-29)
+
+
+### Features
+
+* **webhooks:** enrich event.* payloads with customer contact + share_token ([#341](https://github.com/the-luap/picpeak/issues/341)) ([7ea4801](https://github.com/the-luap/picpeak/commit/7ea4801544fd5cd8bca1907a71b5c4e96ee77649))
+* **webhooks:** enrich event.* payloads with customer contact + share_token ([#341](https://github.com/the-luap/picpeak/issues/341)) ([1e69d5f](https://github.com/the-luap/picpeak/commit/1e69d5ff71ac2d1d133b0e40637b437d7cc8bc4f))
+
+## [3.31.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.31.0-beta.0...v3.31.1-beta.0) (2026-04-28)
+
+
+### Bug Fixes
+
+* **events:** show customer phone in event details view ([#331](https://github.com/the-luap/picpeak/issues/331)) ([4c73d22](https://github.com/the-luap/picpeak/commit/4c73d228ed98b8ec05bec2824aee7ce066a184e1))
+* **gallery:** single-finger swipe nav in mobile lightbox ([#332](https://github.com/the-luap/picpeak/issues/332)) ([4c8eba0](https://github.com/the-luap/picpeak/commit/4c8eba0cb43635d92a53d90c58b19007136c1c12))
+* **gallery:** use ref for swipe-start to avoid stale-closure miss ([#332](https://github.com/the-luap/picpeak/issues/332)) ([fcddfe0](https://github.com/the-luap/picpeak/commit/fcddfe094b2a01963f7b420afa886e7d5dae4390))
+* **lightbox:** mobile toolbar clipping + iOS safe-area + viewport-fit ([#336](https://github.com/the-luap/picpeak/issues/336)) ([42a7ae4](https://github.com/the-luap/picpeak/commit/42a7ae4be8fe7b12104ae036465c9c4117606378))
+* mobile lightbox + share previews + customer phone bug triage ([1e40677](https://github.com/the-luap/picpeak/commit/1e4067713ce9a808a7b49319bc262e5c9a6599c6))
+* **share:** OG/Twitter-card metadata for gallery share URLs ([#333](https://github.com/the-luap/picpeak/issues/333)) ([5275621](https://github.com/the-luap/picpeak/commit/5275621fcd38f1ec09b54595163ecd5e63614b1a))
+
+## [3.31.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.30.0-beta.0...v3.31.0-beta.0) (2026-04-28)
+
+
+### Features
+
+* **frontend:** dedupe /public/settings via shared usePublicSettings hook ([#325](https://github.com/the-luap/picpeak/issues/325)) ([3d4ae4d](https://github.com/the-luap/picpeak/commit/3d4ae4d7e9f9995d93563e8092e05215362afb3b))
+* native S3 storage backend ([#328](https://github.com/the-luap/picpeak/issues/328)) + presigned download follow-up ([1b717ce](https://github.com/the-luap/picpeak/commit/1b717ce5ededa343d2fbb7e1c3493b4434743565))
+* outbound webhooks for event/photo lifecycle ([#327](https://github.com/the-luap/picpeak/issues/327)) ([c488f48](https://github.com/the-luap/picpeak/commit/c488f481caacf0d63dafc47f509e8de2708bc30f))
+* presigned download UI + S3 prefix walker auto-importer (follow-ups) ([446d80a](https://github.com/the-luap/picpeak/commit/446d80a4cc5eb0389994e29585b2a98dad373db2))
+* S3 storage + webhooks + settings dedupe + backup fixes ([06d54be](https://github.com/the-luap/picpeak/commit/06d54bec4d0afc4a1b9ba6f2449ed7d79f1d3e8f))
+
+
+### Bug Fixes
+
+* **backup:** cron schedule mapping + manifest format detection + bigint coerce ([ab4095f](https://github.com/the-luap/picpeak/commit/ab4095f5928b1476009cddfd3444d6f5b58b034d))
+* **backup:** incremental backups against S3 + jsonb stats parsing ([e232f9f](https://github.com/the-luap/picpeak/commit/e232f9f2cf54aeba1e16d769397428206a0f1801))
+
+## [3.30.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.29.1-beta.0...v3.30.0-beta.0) (2026-04-27)
+
+
+### Features
+
+* customisable 404 + gallery-not-found pages via CMS ([#324](https://github.com/the-luap/picpeak/issues/324)) ([4f77905](https://github.com/the-luap/picpeak/commit/4f77905b87bea474b3d2496350996deaad041230))
+* optional customer phone field gated by global toggle ([#322](https://github.com/the-luap/picpeak/issues/322)) ([be6cb28](https://github.com/the-luap/picpeak/commit/be6cb28c8097d2277c1af2a32cf8bc88ebbc7136))
+* public v1 API + token management + OpenAPI docs ([#322](https://github.com/the-luap/picpeak/issues/322)) ([808b15b](https://github.com/the-luap/picpeak/commit/808b15bafbcdab6ea55aff7f0e507153f513a70a))
+
+
+### Bug Fixes
+
+* dedupe parallel admin 401 redirects to /admin/login ([038e84c](https://github.com/the-luap/picpeak/commit/038e84cae7f56a0a1af8c71b85881ca5d320c6e3))
+* floor password_changed_at when comparing against JWT iat ([793e410](https://github.com/the-luap/picpeak/commit/793e410554b461522fbe24014dfd3baa915da2bb))
+* theme picker buttons no longer submit the parent form ([#326](https://github.com/the-luap/picpeak/issues/326)) ([2eead52](https://github.com/the-luap/picpeak/commit/2eead523193ccb7f23eb767097ad9698e8312833))
+* theme save without Live Preview, Branding default on new events, gallery loading flicker ([#323](https://github.com/the-luap/picpeak/issues/323), [#321](https://github.com/the-luap/picpeak/issues/321)) ([822be9a](https://github.com/the-luap/picpeak/commit/822be9a9b2716f1832a4cb6fccd53602e3cbab51))
+* theme-preset match loop ignores extra fields like logoUrl ([#323](https://github.com/the-luap/picpeak/issues/323)) ([b63a877](https://github.com/the-luap/picpeak/commit/b63a8774c4b44733b903736b2ca5a472a884055e))
+
+
+### Documentation
+
+* add Buy Me a Coffee badge + Support section ([46bc894](https://github.com/the-luap/picpeak/commit/46bc894d917bd55dbd9bafaa64fd38db21488b81))
+
+## [3.29.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.29.0-beta.0...v3.29.1-beta.0) (2026-04-26)
+
+
+### Bug Fixes
+
+* address bugs and feature requests from discussion [#317](https://github.com/the-luap/picpeak/issues/317) ([6cfff6f](https://github.com/the-luap/picpeak/commit/6cfff6f6a6dbdc5bc1e9fe4fbce5795cdb1855c6))
+* discussion [#317](https://github.com/the-luap/picpeak/issues/317) issues and [#318](https://github.com/the-luap/picpeak/issues/318) archive crash ([2f2f405](https://github.com/the-luap/picpeak/commit/2f2f405d9bc2831b3bbe2ca7fbf726d61382dc38))
+* prevent backend crash on archive when admin_email is null ([#318](https://github.com/the-luap/picpeak/issues/318)) ([e4b0f96](https://github.com/the-luap/picpeak/commit/e4b0f961b75952b6907cc2291fa256215c09c80c))
+
+## [3.29.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.28.3-beta.0...v3.29.0-beta.0) (2026-04-23)
+
+
+### Features
+
+* pre-zip download all and photo replacement by name ([#312](https://github.com/the-luap/picpeak/issues/312), [#313](https://github.com/the-luap/picpeak/issues/313)) ([d3f1206](https://github.com/the-luap/picpeak/commit/d3f12068164a6bfe6c4a3817ad2fc2e8ed7abf4f))
+* pre-zip download all and photo replacement by name ([#312](https://github.com/the-luap/picpeak/issues/312), [#313](https://github.com/the-luap/picpeak/issues/313)) ([e18afd3](https://github.com/the-luap/picpeak/commit/e18afd3e6b0b5a4cdb4873fb227d1b1d2bf35f21))
+
+## [3.28.3-beta.0](https://github.com/the-luap/picpeak/compare/v3.28.2-beta.0...v3.28.3-beta.0) (2026-04-13)
+
+
+### Bug Fixes
+
+* revert /api prefix in adminPhotos.js to avoid double-prefix ([094276d](https://github.com/the-luap/picpeak/commit/094276d3cc7117eee30e4bcbce487e54f0eacb29))
+* revert /api prefix in adminPhotos.js to avoid double-prefix ([#307](https://github.com/the-luap/picpeak/issues/307)) ([ceb2a09](https://github.com/the-luap/picpeak/commit/ceb2a09f483b4754fda232c5c1f7acb8971aac10))
+
+## [3.28.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.28.1-beta.0...v3.28.2-beta.0) (2026-04-12)
+
+
+### Bug Fixes
+
+* display welcome message in gallery and fix guest thumbnail URLs ([#306](https://github.com/the-luap/picpeak/issues/306), [#307](https://github.com/the-luap/picpeak/issues/307)) ([b05c36a](https://github.com/the-luap/picpeak/commit/b05c36ac810a557a2ac088ab7bec39bb76f9a2ae))
+* display welcome message in gallery and fix guest thumbnail URLs ([#306](https://github.com/the-luap/picpeak/issues/306), [#307](https://github.com/the-luap/picpeak/issues/307)) ([9323bef](https://github.com/the-luap/picpeak/commit/9323befdd99d64b85cca89af24ac1b7034d72eee))
+
+## [3.28.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.28.0-beta.0...v3.28.1-beta.0) (2026-04-12)
+
+
+### Bug Fixes
+
+* apply sort direction in gallery and respect show_feedback_to_guests ([#302](https://github.com/the-luap/picpeak/issues/302), [#303](https://github.com/the-luap/picpeak/issues/303)) ([3716ff5](https://github.com/the-luap/picpeak/commit/3716ff50854766bde588fbd6b9027f8647e59150))
+* apply sort direction in gallery view and respect show_feedback_to_guests ([#302](https://github.com/the-luap/picpeak/issues/302), [#303](https://github.com/the-luap/picpeak/issues/303)) ([dffe057](https://github.com/the-luap/picpeak/commit/dffe057772c922ab6a213e25f171157e0c2badf8))
+
+## [3.28.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.27.0-beta.0...v3.28.0-beta.0) (2026-04-11)
+
+
+### Features
+
+* add COOKIE_SECURE=auto for mixed HTTPS/HTTP deployments ([#298](https://github.com/the-luap/picpeak/issues/298)) ([b1dfbe4](https://github.com/the-luap/picpeak/commit/b1dfbe4c2fe271d8087974d02cf724f04058bdc9))
+* add COOKIE_SECURE=auto for mixed HTTPS/HTTP deployments ([#298](https://github.com/the-luap/picpeak/issues/298)) ([15a8ab4](https://github.com/the-luap/picpeak/commit/15a8ab41fd1c94e3397d300b161cd1fdd459ea05))
+
+
+### Bug Fixes
+
+* guest feedback flow bugs in Masonry grid and PhotoLightbox ([#292](https://github.com/the-luap/picpeak/issues/292)) ([54badef](https://github.com/the-luap/picpeak/commit/54badefc51b834d55530722f87c81a6ade33e35b))
+* guest feedback flow bugs in Masonry grid and PhotoLightbox ([#292](https://github.com/the-luap/picpeak/issues/292)) ([77f07e9](https://github.com/the-luap/picpeak/commit/77f07e9329e47f6ac5040f2e85d2710ebbea3ced))
+
+## [3.27.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.26.2-beta.0...v3.27.0-beta.0) (2026-04-11)
+
+
+### Features
+
+* add admin dark mode and SEO/robots.txt settings ([9c2a0d2](https://github.com/the-luap/picpeak/commit/9c2a0d272a21dfcace2ec795034e2f1adcba47e0))
+* add Apple Liquid Glass templates, image security settings, and automated releases ([6033461](https://github.com/the-luap/picpeak/commit/6033461be118ce78277ec568e1ef1ceeff7311c8))
+* add bulk category editing for photos ([#157](https://github.com/the-luap/picpeak/issues/157)) ([eca36c7](https://github.com/the-luap/picpeak/commit/eca36c70a23f18f937a9f5bddeff855e18f364c3))
+* add category hero/cover photo selection ([#163](https://github.com/the-luap/picpeak/issues/163)) ([6c30e2c](https://github.com/the-luap/picpeak/commit/6c30e2c2edd19a24d4f30a9558690bb7e2331b32))
+* add configurable upload batch size for reverse proxy compatibility ([#208](https://github.com/the-luap/picpeak/issues/208)) ([02a46e0](https://github.com/the-luap/picpeak/commit/02a46e083d68cfdb355b5a4fe4a8da7d667050b9))
+* Add CSS template system with custom gallery styling support ([0da45e6](https://github.com/the-luap/picpeak/commit/0da45e699ad998031aa56a92f2da5ee61a04e285))
+* add customizable event types with admin management ([f8881d5](https://github.com/the-luap/picpeak/commit/f8881d5bd62d449fb40917ec8c20f0eb16c1fdad))
+* add Dutch (nl) locale and fix missing translation keys across all locales ([b54a80d](https://github.com/the-luap/picpeak/commit/b54a80d251bcbb9a126e32eeaef522688bc810c6))
+* add Dutch locale and fix missing translation keys ([e32da68](https://github.com/the-luap/picpeak/commit/e32da68cbdfa430d62cbb1057ea418dc6b2f14fb))
+* add event management, gallery customization, and release automationFeature/event rename ([40ee671](https://github.com/the-luap/picpeak/commit/40ee67171d41522037bf9d4e7675b62ec564346d))
+* add Gallery Premium and Gallery Story layouts (Beta) ([e179def](https://github.com/the-luap/picpeak/commit/e179def3cceefe5fd6acd5574f2986e4f9e223ef))
+* add hero image focal point picker with anchor positioning ([#162](https://github.com/the-luap/picpeak/issues/162)) ([734868a](https://github.com/the-luap/picpeak/commit/734868abc23731b0ac9ad73e799194df1e6aa6ab))
+* add justified layout modes and aspect-ratio-aware mosaic ([#146](https://github.com/the-luap/picpeak/issues/146)) ([608bbd5](https://github.com/the-luap/picpeak/commit/608bbd50e7b31d49c7516a00e96f284fa16e2777))
+* Add justified layout modes and aspect-ratio-aware mosaic ([#146](https://github.com/the-luap/picpeak/issues/146)) ([ef2ae00](https://github.com/the-luap/picpeak/commit/ef2ae00ff20b754c2f2ed797e18c146d12d7f31a))
+* add justified/rows layout mode to masonry gallery ([#146](https://github.com/the-luap/picpeak/issues/146)) ([e081b56](https://github.com/the-luap/picpeak/commit/e081b56a44bf9fdaa3dd225d5dd4dde35bfe83d3))
+* add justified/rows layout mode to masonry gallery ([#146](https://github.com/the-luap/picpeak/issues/146)) + security fixes ([cd1d504](https://github.com/the-luap/picpeak/commit/cd1d50474f673b759c2f9401fdbe209a84773e39))
+* add multi-administrator support with RBAC and fix backup/restore for S3 ([892e47d](https://github.com/the-luap/picpeak/commit/892e47d017064d7922536f8e138bbb290a45cdc9))
+* add optional event date and expiration settings ([3079eaa](https://github.com/the-luap/picpeak/commit/3079eaa2e5d1728c2c0f315626cc253e4b08edc2))
+* add optional event date and expiration settings ([2151147](https://github.com/the-luap/picpeak/commit/2151147f2d3134448ff32130da44678e2942d73c)), closes [#118](https://github.com/the-luap/picpeak/issues/118)
+* add original filename preservation and Lightroom export support ([a59f414](https://github.com/the-luap/picpeak/commit/a59f41463f960a3a74ce3933dc7db84ee3a2018d))
+* add original filename preservation and Lightroom export support ([9872ad3](https://github.com/the-luap/picpeak/commit/9872ad3aef6488b359c5499a6dc3d8bfbfa48fde))
+* add per-event custom logo upload with bug fixes ([85170b8](https://github.com/the-luap/picpeak/commit/85170b883f504d83f1d862abb3f4e46741074826))
+* add per-event hero logo customization options ([0790a1d](https://github.com/the-luap/picpeak/commit/0790a1ddad774af89827a0a392e9fae0a945bff2))
+* add per-gallery thumbnail scale setting ([#172](https://github.com/the-luap/picpeak/issues/172)) ([#251](https://github.com/the-luap/picpeak/issues/251)) ([ee46088](https://github.com/the-luap/picpeak/commit/ee46088985ebbbb81d16e5bac23be2060c94397f))
+* add photo cap per event and Portuguese (pt-BR) locale ([1fa222e](https://github.com/the-luap/picpeak/commit/1fa222e9c4c26e525c7899e368988c6b0b08da85))
+* add photo cap per event and Portuguese locale ([088de43](https://github.com/the-luap/picpeak/commit/088de43f09f974d444f50452ef1117315c289ebc))
+* add quilted layout, fix mosaic, and backfill photo dimensions ([#146](https://github.com/the-luap/picpeak/issues/146)) ([46ed1bc](https://github.com/the-luap/picpeak/commit/46ed1bc276867a25b27bf22cd9b9d7e879a6947b))
+* add thumbnail settings UI to admin panel ([3a30fea](https://github.com/the-luap/picpeak/commit/3a30fea862034d64fbc7188fc25292594a9319e2))
+* add thumbnail settings UI to admin settings page ([#206](https://github.com/the-luap/picpeak/issues/206)) ([7d6d2f5](https://github.com/the-luap/picpeak/commit/7d6d2f56883a4402f0d97c95b0432a8a783c8024))
+* add update instructions dialog, email notifications, and capture date sorting ([50c0990](https://github.com/the-luap/picpeak/commit/50c09904a9434f988ab32a07da5d24db0e02065e)), closes [#181](https://github.com/the-luap/picpeak/issues/181)
+* add visual WYSIWYG email template editor ([#229](https://github.com/the-luap/picpeak/issues/229)) ([04a7ea8](https://github.com/the-luap/picpeak/commit/04a7ea80f95d6aeb474b145292e75f45fb85c66d))
+* **admin:** refine header layout and logo placement ([d64e7d0](https://github.com/the-luap/picpeak/commit/d64e7d08deae7ad1b6f744f447fe546115427942))
+* allow admin email updates in UI ([#36](https://github.com/the-luap/picpeak/issues/36)) ([3c2a79a](https://github.com/the-luap/picpeak/commit/3c2a79a31a0f1a44c8ec4f9a87f6fbcea9be651c))
+* beta/stable release channels with update notifications and bug fixes ([3c7dc20](https://github.com/the-luap/picpeak/commit/3c7dc2013fc3b57712ddf16db85f495b3cc7bfd7))
+* beta/stable release channels with update notifications and bug fixes ([#98](https://github.com/the-luap/picpeak/issues/98)) ([3c7dc20](https://github.com/the-luap/picpeak/commit/3c7dc2013fc3b57712ddf16db85f495b3cc7bfd7))
+* configurable upload batch size for reverse proxy compatibility ([9b7495e](https://github.com/the-luap/picpeak/commit/9b7495e0054975e66c9b5006c24a9fae63969de4))
+* configurable upload batch size for reverse proxy compatibility ([4243363](https://github.com/the-luap/picpeak/commit/424336340bef8e1629490ade154f0ceebb2a71e1))
+* decouple hero header from gallery layouts ([#158](https://github.com/the-luap/picpeak/issues/158)) ([7b8d8bd](https://github.com/the-luap/picpeak/commit/7b8d8bd92ba7a96717bb4d821b38dddc395f701a))
+* **docker:** add PUID/PGID and user mapping to avoid bind mount permission issues; feat(setup): prompt for admin email interactively; docs: PUID/PGID in .env.example ([410a33f](https://github.com/the-luap/picpeak/commit/410a33fecf1693cc75816c53ac460ec20089e2a1))
+* draft mode, admin branding, and workflow improvements ([dc98206](https://github.com/the-luap/picpeak/commit/dc98206737d1ebe43637319ce8c5b6da2e44c05d))
+* draft mode, admin branding, and workflow improvements ([40332a7](https://github.com/the-luap/picpeak/commit/40332a71db6534097940d3f9362b0fe651dba6c7))
+* dynamic website title from branding settings ([d29aab7](https://github.com/the-luap/picpeak/commit/d29aab7c70c5777451666fb7d5c7a9729dab684a))
+* **events:** add CSS template selector to event edit page ([6a6c2cd](https://github.com/the-luap/picpeak/commit/6a6c2cd34db26a53b5fb96415650e8136a74e47f))
+* gallery layouts, bulk category editing, and hero header improvements ([7037106](https://github.com/the-luap/picpeak/commit/7037106bff62593bba600d898a781f79f07b459d))
+* gallery layouts, hero customization, bulk categories & event types ([d9e00dc](https://github.com/the-luap/picpeak/commit/d9e00dc0dbd7cef0ddb4665e5306c98aac3573e3))
+* gallery layouts, hero customization, event types, and UX improvements ([#146](https://github.com/the-luap/picpeak/issues/146), [#155](https://github.com/the-luap/picpeak/issues/155)-163, [#170](https://github.com/the-luap/picpeak/issues/170), [#171](https://github.com/the-luap/picpeak/issues/171)) ([4280444](https://github.com/the-luap/picpeak/commit/4280444d70e73db09e67e18ce25bac75cf499b75))
+* **gallery/filters:** add Rated and Commented filters (UI + backend).\n\n- UI: add star (Rated) and message (Commented) buttons to feedback filter bars (desktop + mobile)\n- Backend: support filter=rated, commented, and combinations via aggregate counts/queries ([b03760a](https://github.com/the-luap/picpeak/commit/b03760ab01e21feb3578f90d065945d437d03452))
+* **gallery:** add quick Like/Favorite actions on thumbnails across layouts ([6368f10](https://github.com/the-luap/picpeak/commit/6368f1027f96107ba64964eb126911bfe185f54a))
+* **gallery:** always-visible feedback indicators on grid tiles; fallback image rendering in lightbox/hero; auto-auth from shared-link token; fix external photo resolver\n\n- GridGallery: bottom-left icons for like/rated/comment on every tile\n- Hero layout grid: added same indicators (non-intrusive icons)\n- Lightbox/Hero: add fallbackSrc to display thumbnail if original fails\n- GalleryAuth: auto-store token from /gallery/:slug/:token and hydrate event\n- Backend gallery photo route: use resolvePhotoFilePath for external-media\n\nfix(admin): move photo feedback badges to bottom-right on admin grid tiles\n\nfix(dashboard): add missing i18n keys for activity types + fallback to formatter\n\nfix(admin/feedback): correct thumbnail URL base + robust date parsing\n\nRefs: [#19](https://github.com/the-luap/picpeak/issues/19) ([6948aaa](https://github.com/the-luap/picpeak/commit/6948aaa92afc29609f85cf7fd631095f3e32ad3f))
+* **gallery:** compact vertical icon-only feedback filter in PhotoFilterBar; remove wide buttons to prevent overflow\n\n- Desktop: vertical icon stack (All/Grid, Likes, Favorites) outside scroll area\n- Mobile: vertical icon stack below categories\n- Keeps existing category bar layout and count\n\nRefs: [#19](https://github.com/the-luap/picpeak/issues/19) ([465f997](https://github.com/the-luap/picpeak/commit/465f997752fc930ac0a3ae530e9e57a378877d53))
+* **i18n:** add translations for settings tabs ([c030e87](https://github.com/the-luap/picpeak/commit/c030e872135b39701ef1f4bbb2f28bcaf4ce7fae))
+* implement 4 new features with bug fixes and refactoring plan ([77a4bfd](https://github.com/the-luap/picpeak/commit/77a4bfd49975551bf509354097f280cab3e48c7a))
+* implement beta/stable release channels with update notifications ([617e778](https://github.com/the-luap/picpeak/commit/617e778a48e0f0c24fcb8441d00ed2a816f19c03))
+* improve gallery layouts with aspect-ratio-aware masonry and mosaic modes ([#146](https://github.com/the-luap/picpeak/issues/146)) ([aacfcd5](https://github.com/the-luap/picpeak/commit/aacfcd517ea5739e834cf84627b55b3449740a5c))
+* improve hero image UX and live preview ([#163](https://github.com/the-luap/picpeak/issues/163), [#158](https://github.com/the-luap/picpeak/issues/158)) ([d63f67a](https://github.com/the-luap/picpeak/commit/d63f67a2afba1b92610382aa1012428ccacb86bd))
+* **lightbox:** keep feedback usable while navigating ([6368f10](https://github.com/the-luap/picpeak/commit/6368f1027f96107ba64964eb126911bfe185f54a)), closes [#19](https://github.com/the-luap/picpeak/issues/19)
+* Multi-administrator RBAC, CSS templates & security hardening ([#78](https://github.com/the-luap/picpeak/issues/78)) ([16b3ab0](https://github.com/the-luap/picpeak/commit/16b3ab039ae95f5641dc15a4811eb2b503f1791c))
+* multilingual email templates with translations table ([8c5996e](https://github.com/the-luap/picpeak/commit/8c5996e4ec43b2817d84cc040cfe52878ffb61d5))
+* multilingual email templates with translations table ([f50d7c0](https://github.com/the-luap/picpeak/commit/f50d7c0c51aa84a2182e450cd4b6a00777a8f9c0))
+* **native:** auto-serve SPA when dist exists (unless SERVE_FRONTEND=false); add clear logging; serve index.html for /admin ([fb16b7b](https://github.com/the-luap/picpeak/commit/fb16b7bbb8225192160c08050f1b164c36c8dc74))
+* **native:** build frontend and serve SPA from backend (SERVE_FRONTEND); fix Cannot GET /admin on native installs ([9fe10bc](https://github.com/the-luap/picpeak/commit/9fe10bcce2871a48f2409b4936d95c00249deb51))
+* **native:** serve built frontend from backend; build frontend during install/update; ensure env flags (SERVE_FRONTEND, FRONTEND_DIR) ([61ad2d6](https://github.com/the-luap/picpeak/commit/61ad2d61c137196c229817989f991e50fa389a6e))
+* new features and bug fixes for beta release ([151e1bf](https://github.com/the-luap/picpeak/commit/151e1bf50f206ae0571fa044c75b8bc9f0f40120))
+* original filename in admin UI, update dialog, and security hardening ([3ea9d5b](https://github.com/the-luap/picpeak/commit/3ea9d5b1219980032cbee7a2564c0004948923f5))
+* original filename in admin UI, update dialog, security hardening, and bug fixes ([bcf2745](https://github.com/the-luap/picpeak/commit/bcf2745ab64acb968ae4bd0710b28e78c14f340c))
+* overhaul public landing page and backup tooling ([2a4d388](https://github.com/the-luap/picpeak/commit/2a4d38813f7ab64a6bbb3a666f3c98a29443488d))
+* per-event custom logos, customizable event types, and multiple bug fixes ([4c08160](https://github.com/the-luap/picpeak/commit/4c081601e02888d7ad289acb7847aee9d6f5703f))
+* photo visibility control with client access ([#172](https://github.com/the-luap/picpeak/issues/172)) ([4a93e4e](https://github.com/the-luap/picpeak/commit/4a93e4e8cbe1b7a23a8be706291a270ccdf5bb55))
+* photo visibility control with client access ([#172](https://github.com/the-luap/picpeak/issues/172)) ([e1b6e43](https://github.com/the-luap/picpeak/commit/e1b6e43e524211c913d3d29ade5fc029df12920f))
+* pre-generate watermarks for instant lightbox loading ([1be974a](https://github.com/the-luap/picpeak/commit/1be974afbb0b7a1bdbdd140327771907a5d3c2ae)), closes [#112](https://github.com/the-luap/picpeak/issues/112)
+* pre-generated watermarks and mobile upload button improvements ([c6fdd38](https://github.com/the-luap/picpeak/commit/c6fdd38e842e1a8c0aa9cbab9fc791e6669e402d))
+* register Russian locale and add to language selector ([6f95b8c](https://github.com/the-luap/picpeak/commit/6f95b8c26cd794525e15e45d478f9ead0ec22555))
+* **select:** add per-tile checkbox selection in Admin grid and all gallery layouts; tile click opens viewer; checkbox toggles selection; auto-enable selection mode; add testids ([9fda54b](https://github.com/the-luap/picpeak/commit/9fda54bd06d37cd8f8f71056bf4f59e158cd8112))
+* **setup/docker:** auto-set PUID/PGID from invoking user and chown bind-mount folders; create missing data/events dirs ([0618b78](https://github.com/the-luap/picpeak/commit/0618b78725e85f97f0a4b4e834c17811c033c8f4))
+* **setup:** remove --admin-password; print admin credentials from ADMIN_CREDENTIALS.txt; fix ADMIN_URL to avoid /admin/admin; update native service commands ([84d0f63](https://github.com/the-luap/picpeak/commit/84d0f63d36c68532fea83e7087b1afeaa9b82f39))
+* show original filename in admin UI ([#184](https://github.com/the-luap/picpeak/issues/184)) ([0891be1](https://github.com/the-luap/picpeak/commit/0891be197fdb7d92ade5a293b8db0bed26fa6e3a))
+* sort photos by capture date with configurable default sort ([#283](https://github.com/the-luap/picpeak/issues/283)) ([8805fa5](https://github.com/the-luap/picpeak/commit/8805fa53e61c6b3672a8f6dad14d2fd17998a451))
+* sort photos by capture date with configurable default sort ([#283](https://github.com/the-luap/picpeak/issues/283)) ([633d4a0](https://github.com/the-luap/picpeak/commit/633d4a0f301e355ee9f057347f2f8dee8c5b4163))
+* support per-gallery password toggle ([5d6c061](https://github.com/the-luap/picpeak/commit/5d6c061f1c4fd20581b1e74fa114c96530b5de53))
+* visual WYSIWYG email template editor ([703c03f](https://github.com/the-luap/picpeak/commit/703c03fbee754a5291b57b885c5e82fbdd3e69e9))
+* warn about low thumbnail resolution when selecting beta themes ([ee3f6ae](https://github.com/the-luap/picpeak/commit/ee3f6ae13bf9c9fb3295286e84150e04bf9fbce4))
+* warn about low thumbnail resolution with beta themes ([aef9b4e](https://github.com/the-luap/picpeak/commit/aef9b4ed7fc443cbec8890c580759077e05e77b4))
+
+
+### Bug Fixes
+
+* add allow_user_uploads to gallery API responses ([691e3ab](https://github.com/the-luap/picpeak/commit/691e3aba09f2148afe902a0bb0139d062634e669))
+* add lightbox loading spinner and watermark cache invalidation ([050ed37](https://github.com/the-luap/picpeak/commit/050ed378199eb3b15c7c7f243792f68f858803f5))
+* Add settings translations and fix manual backup process ([#82](https://github.com/the-luap/picpeak/issues/82)) ([476fcce](https://github.com/the-luap/picpeak/commit/476fcce13f30f9f2d2f98a0c87c25fba09e9eebc))
+* add STORAGE_PATH to production docker-compose ([cdda709](https://github.com/the-luap/picpeak/commit/cdda70988664a177b351abc6a259ec39664d17ff))
+* address beta feedback - gallery layout fixes, Russian locale, email logo ([#249](https://github.com/the-luap/picpeak/issues/249)) ([486239a](https://github.com/the-luap/picpeak/commit/486239aeb9b5f56551d5aa90f0bad3008eedc3bb))
+* address Shannon security assessment findings (37 vulnerabilities) ([#254](https://github.com/the-luap/picpeak/issues/254)) ([23cd9cb](https://github.com/the-luap/picpeak/commit/23cd9cb680eb77b94a97266c3353dfc835f0cc69))
+* admin photo feedback filters have no effect ([#293](https://github.com/the-luap/picpeak/issues/293)) ([9ed8a2b](https://github.com/the-luap/picpeak/commit/9ed8a2b1994d139efd100c8fb97e6368655e5530))
+* **admin/feedback:** use correct event id when rendering photo thumbnails ([4c7b49a](https://github.com/the-luap/picpeak/commit/4c7b49a5f69a3fce4f9a0e837a082b56bb7e47d6)), closes [#19](https://github.com/the-luap/picpeak/issues/19)
+* **admin:** prevent category badge overlap in grid ([d64e7d0](https://github.com/the-luap/picpeak/commit/d64e7d08deae7ad1b6f744f447fe546115427942))
+* align backend port to 3000 across all configurations ([3a8d53f](https://github.com/the-luap/picpeak/commit/3a8d53f4927f577c4031c4bc3531e08191dc632a))
+* Align nginx backend port for production Docker deployments (v2.2.2) ([#88](https://github.com/the-luap/picpeak/issues/88)) ([e0bd19a](https://github.com/the-luap/picpeak/commit/e0bd19a74dd81bdd45be2384820830bd96769e1c))
+* apply password change fix to regular modal + longer toast delay ([#263](https://github.com/the-luap/picpeak/issues/263)) ([c63bc47](https://github.com/the-luap/picpeak/commit/c63bc47089b4b32c570bdeeb1f82bf722569875f))
+* apply password change redirect fix to regular modal too ([#263](https://github.com/the-luap/picpeak/issues/263)) ([147dc28](https://github.com/the-luap/picpeak/commit/147dc28440ca69ed970677fa221dfac00c8e2560))
+* **backup:** add lastBackup alias and totalBackups for frontend compatibility ([749100c](https://github.com/the-luap/picpeak/commit/749100c92abd2bb123b137e3d3c6bb342b8f5f00))
+* **backup:** allow manual backups when automated backups are disabled ([e6dd89e](https://github.com/the-luap/picpeak/commit/e6dd89e969fb7018633159155975bd2bd2fb0409))
+* checkbox and toggle settings not persisting after page refresh ([808ed1d](https://github.com/the-luap/picpeak/commit/808ed1d2f1164d9fd1114586c68a1f925bf73ddf)), closes [#117](https://github.com/the-luap/picpeak/issues/117)
+* CI workflow fixes for protected branches ([657c205](https://github.com/the-luap/picpeak/commit/657c205a4d8ca49070b69973f4c7a3d1418633af))
+* CI workflow fixes for protected branches ([cb01218](https://github.com/the-luap/picpeak/commit/cb012186d93403a1ac4e2d2f5283319603b290d6))
+* **ci:** add QEMU setup for multi-arch builds and skip for PRs ([0d36a27](https://github.com/the-luap/picpeak/commit/0d36a273bb58ffd0172efacd828e7171d954b41c))
+* clear notifications via API ([#35](https://github.com/the-luap/picpeak/issues/35)) ([013be18](https://github.com/the-luap/picpeak/commit/013be18d982986333e2ac24c7ede907de49690bc))
+* correct invitation activation validation and add missing translations ([991aa98](https://github.com/the-luap/picpeak/commit/991aa98f98cffd1d7785c272726615325e2c0208)), closes [#129](https://github.com/the-luap/picpeak/issues/129)
+* correct invitation email link URL path ([86fa104](https://github.com/the-luap/picpeak/commit/86fa1046d5439cb451feb164175c919c49ca219a)), closes [#129](https://github.com/the-luap/picpeak/issues/129)
+* correct storage path resolution in multiple files ([#96](https://github.com/the-luap/picpeak/issues/96)) ([0e3674b](https://github.com/the-luap/picpeak/commit/0e3674b2b0325bbcee5aa2c9ff7781da92f612d1))
+* correct storage path resolution in multiple files ([#96](https://github.com/the-luap/picpeak/issues/96)) ([3ccb815](https://github.com/the-luap/picpeak/commit/3ccb8154eb40a432aa467fb06b3f216fd0d2c6b4))
+* **cors:** scope CORS to /api only and avoid throwing on disallowed origins; prevents static asset 500s on native ([90bb21e](https://github.com/the-luap/picpeak/commit/90bb21e38bf1ba97e3fb8185b8d05f1296d745ee))
+* database migration restart bug, lightbox loading spinner, and watermark cache invalidation ([7c58749](https://github.com/the-luap/picpeak/commit/7c5874980640ae8c3d1050ce24daeb0a2aeab7a3))
+* **db:** improve PostgreSQL connection check in wait-for-db.sh ([e85a68a](https://github.com/the-luap/picpeak/commit/e85a68a386c72c276b4958599b5246e60dfac716))
+* display new password after admin password reset ([bd8b885](https://github.com/the-luap/picpeak/commit/bd8b885f7f060160eb852870d143f25ce628f3db))
+* docker compose v2 syntax and add missing ADMIN_PASSWORD to .env.example ([#189](https://github.com/the-luap/picpeak/issues/189)) ([0817443](https://github.com/the-luap/picpeak/commit/0817443e793e37c770c6a1968ecae4b9464107b0))
+* Docker Swarm DNS resolution and backup status display (v2.2.3) ([082d8ab](https://github.com/the-luap/picpeak/commit/082d8ab2054416b2a4f9e0438aa2bda0a8f4277e))
+* Docker Swarm DNS resolution and backup status display (v2.2.3) ([082d8ab](https://github.com/the-luap/picpeak/commit/082d8ab2054416b2a4f9e0438aa2bda0a8f4277e))
+* dynamic website title from branding settings ([4701edc](https://github.com/the-luap/picpeak/commit/4701edc12ecfab27cb2d1cfb0b4ed4fd53f56cc6))
+* event-specific custom CSS settings not being saved ([dadef81](https://github.com/the-luap/picpeak/commit/dadef81158972d28aa32812203500f77ed08a999)), closes [#136](https://github.com/the-luap/picpeak/issues/136)
+* events without expiration date incorrectly shown as expired ([c4f16eb](https://github.com/the-luap/picpeak/commit/c4f16eb76c909158abdb63aa4cc22f817f274dc5))
+* external media dimensions, theme race condition, email color customization ([dfae2c2](https://github.com/the-luap/picpeak/commit/dfae2c2bc6d86378c553cd847b439f7cb53a4f2a))
+* **frontend:** add missing externalMedia service and mount admin external-media routes; verify Vite build ([ab324f1](https://github.com/the-luap/picpeak/commit/ab324f192859204a3ea3c129530ccfe8f5a36968))
+* gallery thumbnails not loading (404 errors) [#96](https://github.com/the-luap/picpeak/issues/96) ([e3c3c4c](https://github.com/the-luap/picpeak/commit/e3c3c4c951c52de99bd0afd95b08d119153997b4))
+* **gallery/filters:** always apply global liked/favorited filters by aggregate counts (ignore guest_id); resolves mismatch between client guest_id and server identifier ([526dcd8](https://github.com/the-luap/picpeak/commit/526dcd8dfc030d86143cee799a88a1004d96b116))
+* **gallery/filters:** make feedback filters work globally when no guest_id is provided; remove guest_id from client photos query\n\n- Backend /api/gallery/:slug/photos: if filter present and guest_id missing, filter by like_count/favorite_count\n- Frontend useGalleryPhotos: stop passing random guestId (does not match server guest_identifier)\n\nThis makes Liked/Favorited filters reflect photos with aggregate feedback counts as expected. ([5b2561b](https://github.com/the-luap/picpeak/commit/5b2561b6f1da2665d6092ba954f8ff26df3959a4))
+* **gallery/sidebar:** compact icon-only feedback filter in sidebar (vertical, small) to avoid overflow; use GalleryFilter variant=compact ([ff89f96](https://github.com/the-luap/picpeak/commit/ff89f96e31130f75bcd7a406c5d895eac17b65de))
+* **gallery:** feedback filter headline + horizontal icons in sidebar (compact variant); ensure sidebar content scrolls (flex-col container) ([3a6d061](https://github.com/the-luap/picpeak/commit/3a6d06192a280ead8bd5d1fbfe06554e63f3346e))
+* handle legacy non-JSON logo paths when replacing logo ([0d5ce48](https://github.com/the-luap/picpeak/commit/0d5ce48dccf0c61f210725ffae15dafc5e9f7cab))
+* handle null dates in dashboard and gallery pages ([c5a8ffc](https://github.com/the-luap/picpeak/commit/c5a8ffc08cd4c53c37fe4fb9cde8519a68f1f343))
+* harden gallery downloads and per-gallery auth ([fc1bf53](https://github.com/the-luap/picpeak/commit/fc1bf534129092ca3638e4a4bc47274cd297fa5f))
+* hero header state and preview in admin theme editor ([#158](https://github.com/the-luap/picpeak/issues/158)) ([f554f46](https://github.com/the-luap/picpeak/commit/f554f463b3492346dba067c0980b52ef42dd5e70))
+* improve ghost button visibility in admin dark mode ([4912e2b](https://github.com/the-luap/picpeak/commit/4912e2bccf282134d5598a8ac80942ed46d0523c))
+* improve password validation errors and event list UX ([#170](https://github.com/the-luap/picpeak/issues/170), [#171](https://github.com/the-luap/picpeak/issues/171)) ([171abb3](https://github.com/the-luap/picpeak/commit/171abb31615484d77cf95a99cb5634afa0160adc))
+* improve photo serving, category filters, and upload chunking ([#155](https://github.com/the-luap/picpeak/issues/155), [#156](https://github.com/the-luap/picpeak/issues/156), [#161](https://github.com/the-luap/picpeak/issues/161)) ([fa4c838](https://github.com/the-luap/picpeak/commit/fa4c83812d87cfa63394e51186e320a072929d37))
+* increase upload limit to 1GB and fix category filters ([#155](https://github.com/the-luap/picpeak/issues/155), [#156](https://github.com/the-luap/picpeak/issues/156)) ([397d33a](https://github.com/the-luap/picpeak/commit/397d33a95a09e0b0986c3f6cf5965c544992a764))
+* issue [#203](https://github.com/the-luap/picpeak/issues/203) file type validation + security CVE fixes ([8017171](https://github.com/the-luap/picpeak/commit/80171713e0ffedda56f7cffb403b25a8d55634d1))
+* JSON serialize favicon and logo URLs for PostgreSQL storage ([b83f427](https://github.com/the-luap/picpeak/commit/b83f4272b584f937fea1f47656182e514b12d980))
+* lightbox watermark loading, white label translations, and dynamic footer year ([3b720ed](https://github.com/the-luap/picpeak/commit/3b720ed56ecd2ded6aec57309f8c408c63a617ef))
+* lightbox watermark loading, white label translations, and dynamic footer year ([ce8587b](https://github.com/the-luap/picpeak/commit/ce8587b24df3f53a11a74348eff8b5c5b96c5488))
+* lightbox watermark loading, white label translations, and dynamic footer year ([#108](https://github.com/the-luap/picpeak/issues/108)) ([3b720ed](https://github.com/the-luap/picpeak/commit/3b720ed56ecd2ded6aec57309f8c408c63a617ef))
+* mobile upload button not visible in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([cacaffa](https://github.com/the-luap/picpeak/commit/cacaffa5c39f67105c4cfb092ea62157121fb72e))
+* mobile upload button visibility in gallery ([2a2c23d](https://github.com/the-luap/picpeak/commit/2a2c23d11610e6c81684163eb4ea934a6d6104fb)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* mobile upload button visibility in gallery ([df7dbff](https://github.com/the-luap/picpeak/commit/df7dbffbffb180e62af0d2b58326f9de0f515439)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* mobile upload button visibility in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([05a5307](https://github.com/the-luap/picpeak/commit/05a5307e22dc45be4b75b2996ff9fac65dec399d))
+* mobile upload button visibility in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([6cb4342](https://github.com/the-luap/picpeak/commit/6cb43428d1e703267edeacda9ede050a8c4f8e0c))
+* Multi-administrator RBAC, CSS templates & security hardening ([#80](https://github.com/the-luap/picpeak/issues/80)) ([37d4e1c](https://github.com/the-luap/picpeak/commit/37d4e1cb6132346699a90aebfbaec83d84f931f4))
+* **native/http:** disable CSP upgrade-insecure-requests and HSTS unless ENABLE_HSTS=true; prevents HTTPS upgrades on HTTP installs ([24b4a31](https://github.com/the-luap/picpeak/commit/24b4a314a9e97b6c640ca29067e95028a23a8973))
+* **native:** correct setup paths to /opt/picpeak/app, update repo URL, add sqlite prod support; docs path fixes ([b992b15](https://github.com/the-luap/picpeak/commit/b992b151d3ca6ccb4a9b2434d94edcdc90ada3b0))
+* **native:** remove obsolete workers service; restart only backend; add API request logging and preflight handler; keep static assets outside CORS ([f3604b4](https://github.com/the-luap/picpeak/commit/f3604b438b37e5f2bddf98e79f458bfa2367cb75))
+* **nginx:** add Docker DNS resolver for Swarm/dynamic service discovery ([049837f](https://github.com/the-luap/picpeak/commit/049837f9d675ff5a4d93c02e5eb771bf65bc2616))
+* **nginx:** Add Docker DNS resolver for Swarm/dynamic service discovery (v2.2.3) ([cc1ddfd](https://github.com/the-luap/picpeak/commit/cc1ddfd42cccac07d5869fe2ee19c25a9ffa50e8))
+* **photos:** category changes now persist and display correctly ([#77](https://github.com/the-luap/picpeak/issues/77)) ([d9da98c](https://github.com/the-luap/picpeak/commit/d9da98c355011c247c526b28e6f07b329a632b55))
+* **photos:** resolve upload category selection and improve feedback buttons ([#77](https://github.com/the-luap/picpeak/issues/77)) ([856d533](https://github.com/the-luap/picpeak/commit/856d53343c6805706e1498892a29b120938f8547))
+* pin npm to v10 in backend Dockerfile ([ddefd3a](https://github.com/the-luap/picpeak/commit/ddefd3a95e5047d4a22aa4b6fef57dfb1c880967))
+* pin npm upgrade to v10 in backend Dockerfile ([978e447](https://github.com/the-luap/picpeak/commit/978e4473b5227ee61ad7d17487063eb3284bea36))
+* prefer admin token on admin routes ([#23](https://github.com/the-luap/picpeak/issues/23) [#28](https://github.com/the-luap/picpeak/issues/28)) ([d4404e3](https://github.com/the-luap/picpeak/commit/d4404e39bd7953649da02d3e300ffef46573ac97))
+* prevent database migration restart failures ([83a4344](https://github.com/the-luap/picpeak/commit/83a4344a01de4f65c5024fdf2d177a04457ccd2f)), closes [#107](https://github.com/the-luap/picpeak/issues/107)
+* prevent unnecessary image recompression and fix SQLite migration [#95](https://github.com/the-luap/picpeak/issues/95) ([3cdc0ea](https://github.com/the-luap/picpeak/commit/3cdc0ea7152e63cd72124a91394741a6e6904af3))
+* remove non-functional watermark toggle from Feature Toggles ([d4a15db](https://github.com/the-luap/picpeak/commit/d4a15dbe74d0d70bbe6ff03362dc7337fb8f4c5c))
+* render minimal/none header styles, cap hero height, switch category hero images ([#158](https://github.com/the-luap/picpeak/issues/158), [#162](https://github.com/the-luap/picpeak/issues/162), [#163](https://github.com/the-luap/picpeak/issues/163)) ([bc6c48b](https://github.com/the-luap/picpeak/commit/bc6c48bb2429505c2de3641693a8ff4f623a4951))
+* resend gallery email fails for events without password ([6b3ead7](https://github.com/the-luap/picpeak/commit/6b3ead747b1395d8ea2b3d135a5ac24db05e2eb8)), closes [#137](https://github.com/the-luap/picpeak/issues/137)
+* resolve admin invitation flow issues and improve STORAGE_PATH documentation ([41bf6ff](https://github.com/the-luap/picpeak/commit/41bf6ff884d5ef3181f95f3aa4a528434c23947a))
+* resolve branding display issues and invitation parsing errors ([1931d73](https://github.com/the-luap/picpeak/commit/1931d73b60d3419203cc8b420841abbfc9e14d2d))
+* Resolve branding display issues and invitation parsing errors (v2.2.1) ([#86](https://github.com/the-luap/picpeak/issues/86)) ([d7ecf83](https://github.com/the-luap/picpeak/commit/d7ecf83d32ec6608280b96e6cdee48e9a0ad0afa))
+* resolve code quality issues and add missing i18n keys ([#162](https://github.com/the-luap/picpeak/issues/162), [#163](https://github.com/the-luap/picpeak/issues/163)) ([329d224](https://github.com/the-luap/picpeak/commit/329d224846d3f4eefa31e42337f34047c267d578))
+* resolve code scanning security alerts (multer, tar, Node 22) ([85a07fc](https://github.com/the-luap/picpeak/commit/85a07fcca7ad935f4c0c300f5ffe2f3af8da1e5f))
+* resolve external media dimensions, gallery theme race condition, and add email color customization ([bbeedd1](https://github.com/the-luap/picpeak/commit/bbeedd1888561b6c57586b5f42bbfee3ffc69fd7))
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([33af088](https://github.com/the-luap/picpeak/commit/33af0885607799e0071e2e74a582c7eb396c9b83))
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([5ea4ef3](https://github.com/the-luap/picpeak/commit/5ea4ef3cf36b06f9e6c9108f80bfe2e9a6470898))
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([33483cf](https://github.com/the-luap/picpeak/commit/33483cf32dfae57f8da51c0765353792239135f9))
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([cd00bc1](https://github.com/the-luap/picpeak/commit/cd00bc13d4e02a86a0f1742ed1f11f064614b8da))
+* resolve JWT iat timing issue in password change ([#263](https://github.com/the-luap/picpeak/issues/263)) ([c031b1e](https://github.com/the-luap/picpeak/commit/c031b1e86333d90e8e0e0aa723572efa110f7fd1))
+* resolve mixed light/dark mode styling in admin UI ([#175](https://github.com/the-luap/picpeak/issues/175)) ([f8c8abd](https://github.com/the-luap/picpeak/commit/f8c8abd70bbae35d6cd519894624ade33b5115a8))
+* resolve password change redirect loop ([#263](https://github.com/the-luap/picpeak/issues/263)) and file watcher crash ([#269](https://github.com/the-luap/picpeak/issues/269)) ([b23c51b](https://github.com/the-luap/picpeak/commit/b23c51b386270dee4d911902b728dfacb1ff1bf9))
+* resolve password change redirect loop and file watcher crash ([835bdf5](https://github.com/the-luap/picpeak/commit/835bdf5abb40c7b143c5cdafb507c317a7c349bf)), closes [#269](https://github.com/the-luap/picpeak/issues/269)
+* resolve redirect loop after mandatory password change ([#263](https://github.com/the-luap/picpeak/issues/263)) ([07fc5e6](https://github.com/the-luap/picpeak/commit/07fc5e6519cd84f2214479d5f31bc35a495bfe4b))
+* resolve redirect loop after mandatory password change ([#263](https://github.com/the-luap/picpeak/issues/263)) ([3c8d344](https://github.com/the-luap/picpeak/commit/3c8d344ddd23974c9cf0f5f63edd6cd07817fee9))
+* respect allowed_file_types setting for upload validation ([#203](https://github.com/the-luap/picpeak/issues/203)) ([fe07a14](https://github.com/the-luap/picpeak/commit/fe07a148f1d998c0be00377c1f8b4eca3908305c))
+* respect optional email settings in event creation ([831ea6a](https://github.com/the-luap/picpeak/commit/831ea6a3bccfae4ec00ce1f619967b91b85150ce))
+* respect optional email settings in event creation ([#217](https://github.com/the-luap/picpeak/issues/217)) ([9c44a0e](https://github.com/the-luap/picpeak/commit/9c44a0ebfa527fa133512eb7f2f03335a2377aaa))
+* restore aspect-ratio layouts and improve hero image quality ([#180](https://github.com/the-luap/picpeak/issues/180)) ([3974ba5](https://github.com/the-luap/picpeak/commit/3974ba5de5a6605ad906608d3e4d61620a215059))
+* restore aspect-ratio layouts and improve hero image quality ([#180](https://github.com/the-luap/picpeak/issues/180)) ([5cef7fd](https://github.com/the-luap/picpeak/commit/5cef7fdd188389512bc4b55ae61536c8b1219eb8))
+* **security:** invalidate tokens on password change, enforce session timeout, fix role update ([f362239](https://github.com/the-luap/picpeak/commit/f3622396e77ce5d0b0741e439fc554a1dccaca50))
+* **security:** resolve all npm audit vulnerabilities ([4272618](https://github.com/the-luap/picpeak/commit/4272618b3f7fcb06aaca14fb724a6a7733251f24))
+* **security:** resolve Docker image CVEs for code scanning alerts ([cbecb93](https://github.com/the-luap/picpeak/commit/cbecb9323cf4b80c800326de14f6df73f60147c1))
+* **security:** token invalidation on password change, session timeout enforcement ([7ca9631](https://github.com/the-luap/picpeak/commit/7ca96315e254eef58d8ecc505f95a5186d2fa2da))
+* **security:** upgrade Alpine base image to fix libpng and c-ares CVEs ([b706eeb](https://github.com/the-luap/picpeak/commit/b706eeb5d332e9618706193976a7241aee53d879))
+* set JWT iat after password_changed_at to prevent token rejection ([#263](https://github.com/the-luap/picpeak/issues/263)) ([b1d1667](https://github.com/the-luap/picpeak/commit/b1d16670d56e19f7b35e7f2f12f3611fdb3fab58))
+* **setup/native:** correct repo URL, paths, and systemd for native install; support sqlite in production knex config ([87b8414](https://github.com/the-luap/picpeak/commit/87b8414e449802db6dc9f762453f7672616b83c9))
+* **setup/native:** Debian 12 compatibility (reliable RAM detection, sudo-less run_as_user, git safe.directory); ensure SQLite data dir; use user for migrate ([dc482e6](https://github.com/the-luap/picpeak/commit/dc482e614a5fbac44c6570d812669511301a4403))
+* **setup/native:** handle forced updates safely by fetch+checkout/reset instead of pull; stable on rewritten histories ([3697344](https://github.com/the-luap/picpeak/commit/3697344cd0add28b4da71c3b33e2ccc0a96f50f9))
+* **setup/update:** detect native installs first (/opt/picpeak/app/backend or systemd unit); avoid false docker updates on root ([adf576f](https://github.com/the-luap/picpeak/commit/adf576fbe17f40c13c1d77dd9751f2e9dbf523a1))
+* shorten Save button label on email template editor ([7250c42](https://github.com/the-luap/picpeak/commit/7250c427b905ffa3e8696dff607450f5a0b801b8))
+* show upload button in mobile topbar instead of sidebar ([ae181cf](https://github.com/the-luap/picpeak/commit/ae181cf92fc9c1e85cad7a7b843a4d83cec636ac)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* stabilize uploads and guest feedback filters ([aaaf598](https://github.com/the-luap/picpeak/commit/aaaf59817b3978635d2282c006853e183ab944d4))
+* sync header_style DB column with theme editor selections ([#158](https://github.com/the-luap/picpeak/issues/158)) ([2288309](https://github.com/the-luap/picpeak/commit/228830939553fd32c250704bb89a8ce233324d25))
+* sync header_style DB column with theme editor selections ([#158](https://github.com/the-luap/picpeak/issues/158)) ([a19e7c4](https://github.com/the-luap/picpeak/commit/a19e7c40a200ff822c947a83349ed07ccf4e1b01))
+* update dependencies to resolve code scanning security alerts ([1f524f2](https://github.com/the-luap/picpeak/commit/1f524f23580d2e2a21dbba28cb46aed76e85c475))
+* update docker-compose to docker compose and add ADMIN_PASSWORD to .env.example ([#189](https://github.com/the-luap/picpeak/issues/189)) ([a4c6248](https://github.com/the-luap/picpeak/commit/a4c624802b2926a16adcf0472a3041562f9b2f48))
+* update packages to fix security vulnerabilities ([8097a0c](https://github.com/the-luap/picpeak/commit/8097a0cb530bd8003597cde81606231efadb0bf5))
+* update security policy with private reporting channels ([308e086](https://github.com/the-luap/picpeak/commit/308e08626383bab213ce3eb5563608dff6168ef4))
+* update security policy with private reporting channels ([7f77362](https://github.com/the-luap/picpeak/commit/7f7736282f534adf4b9d5331d841a1f0bff7341c))
+* update security policy with proper contact email and private reporting ([67b0f32](https://github.com/the-luap/picpeak/commit/67b0f32456d0216e4c685a104c680fa5a5fd578f)), closes [#223](https://github.com/the-luap/picpeak/issues/223)
+* use actual photo aspect ratios in masonry columns mode ([#146](https://github.com/the-luap/picpeak/issues/146)) ([8711f96](https://github.com/the-luap/picpeak/commit/8711f967a15f5d57f6ad01bfdbd8d33f9ee96abc))
+* use CSS Columns for gap-free mosaic layout ([#146](https://github.com/the-luap/picpeak/issues/146)) ([821d329](https://github.com/the-luap/picpeak/commit/821d3296ea4b6bde499e5497d258f15ab8dd1dbc))
+* use photo dimensions for mosaic aspect ratios ([#146](https://github.com/the-luap/picpeak/issues/146)) ([27ff51e](https://github.com/the-luap/picpeak/commit/27ff51e7a1217848859b47940bc88caa6f1fb20f))
+* use Release Please extra-files instead of sync-versions job ([fe7d45d](https://github.com/the-luap/picpeak/commit/fe7d45dd122b2dca1b2a21ba5c86d32b9a193074))
+* video upload media type, select all, and dimension repair ([#203](https://github.com/the-luap/picpeak/issues/203), [#220](https://github.com/the-luap/picpeak/issues/220), [#180](https://github.com/the-luap/picpeak/issues/180)) ([fc75bcd](https://github.com/the-luap/picpeak/commit/fc75bcdfc38673d6e4dd1cd943cfb4638d3a306c))
+* video upload, select all, and dimension repair ([#203](https://github.com/the-luap/picpeak/issues/203), [#220](https://github.com/the-luap/picpeak/issues/220), [#180](https://github.com/the-luap/picpeak/issues/180)) ([a0bb080](https://github.com/the-luap/picpeak/commit/a0bb0805868e742f323b64312c3c5ef8ec408f68))
+* watermark thumbnails, custom logo display, and German translations ([f843e4c](https://github.com/the-luap/picpeak/commit/f843e4c25cef02eef354fd3ee25824e20e4f8fc8))
+* watermark thumbnails, custom logo display, and German translations ([ea20446](https://github.com/the-luap/picpeak/commit/ea20446a797a00cf45dbe7bf6f06574a79c4d8a6))
+* watermark upload JSON parsing and image quality preservation ([0e3b50d](https://github.com/the-luap/picpeak/commit/0e3b50d1b6a2dc532ebdc0981f81f77722e8f23a))
+* wire admin photo feedback filters into grid query ([#293](https://github.com/the-luap/picpeak/issues/293)) ([d4b4dc6](https://github.com/the-luap/picpeak/commit/d4b4dc628f28a303ff1c80ba6d8e5e768217ba51))
+* wrap email preview with full styled header/footer template ([9a6d2e8](https://github.com/the-luap/picpeak/commit/9a6d2e8e3a3fab8d7969a8a42e94934c38d88392))
+* wrap email preview with full styled header/footer template ([fc0911a](https://github.com/the-luap/picpeak/commit/fc0911acf8b7c8a18d71bb4267f1086acd1e0ca1)), closes [#229](https://github.com/the-luap/picpeak/issues/229)
+* wrap test email with standard email template ([#252](https://github.com/the-luap/picpeak/issues/252)) ([954a011](https://github.com/the-luap/picpeak/commit/954a0118bae5770c74f1e811e03b8fc702c70db2))
+
+
+### Documentation
+
+* add API_URL environment variable to .env.example files ([3e69579](https://github.com/the-luap/picpeak/commit/3e69579f5a171b31a253b2a42bb033bf1b97387d))
+* add PUID/PGID note for Docker bind mounts to avoid permission issues ([0178e71](https://github.com/the-luap/picpeak/commit/0178e71c67f198c6013ece52b0a2da0e2f1a6b2a))
+* clarify file system photo import requires existing event ([#269](https://github.com/the-luap/picpeak/issues/269)) ([5295516](https://github.com/the-luap/picpeak/commit/5295516b67a1d9f035564c5f9a724f25f8d21c78))
+* clarify file system photo import requires existing event ([#269](https://github.com/the-luap/picpeak/issues/269)) ([ee0baaf](https://github.com/the-luap/picpeak/commit/ee0baafc59f3588a26172aa8835c12dcaec35d10))
+* emphasize importance of STORAGE_PATH in env example ([3397807](https://github.com/the-luap/picpeak/commit/3397807670784e02cbe34a7a60db43c95d64f19c))
+* **readme:** reflect new External Media reference mode and update roadmap (gallery feedback status) ([ee13556](https://github.com/the-luap/picpeak/commit/ee13556c5cb4f24fe88e14fd00b821acf65b11cb))
+
+## [3.26.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.26.1-beta.0...v3.26.2-beta.0) (2026-04-11)
+
+
+### Bug Fixes
+
+* admin photo feedback filters have no effect ([#293](https://github.com/the-luap/picpeak/issues/293)) ([9ed8a2b](https://github.com/the-luap/picpeak/commit/9ed8a2b1994d139efd100c8fb97e6368655e5530))
+* wire admin photo feedback filters into grid query ([#293](https://github.com/the-luap/picpeak/issues/293)) ([d4b4dc6](https://github.com/the-luap/picpeak/commit/d4b4dc628f28a303ff1c80ba6d8e5e768217ba51))
+
+## [3.26.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.26.0-beta.0...v3.26.1-beta.0) (2026-04-09)
+
+
+### Bug Fixes
+
+* apply password change fix to regular modal + longer toast delay ([#263](https://github.com/the-luap/picpeak/issues/263)) ([c63bc47](https://github.com/the-luap/picpeak/commit/c63bc47089b4b32c570bdeeb1f82bf722569875f))
+* apply password change redirect fix to regular modal too ([#263](https://github.com/the-luap/picpeak/issues/263)) ([147dc28](https://github.com/the-luap/picpeak/commit/147dc28440ca69ed970677fa221dfac00c8e2560))
+* resolve JWT iat timing issue in password change ([#263](https://github.com/the-luap/picpeak/issues/263)) ([c031b1e](https://github.com/the-luap/picpeak/commit/c031b1e86333d90e8e0e0aa723572efa110f7fd1))
+* set JWT iat after password_changed_at to prevent token rejection ([#263](https://github.com/the-luap/picpeak/issues/263)) ([b1d1667](https://github.com/the-luap/picpeak/commit/b1d16670d56e19f7b35e7f2f12f3611fdb3fab58))
+
+
+### Documentation
+
+* clarify file system photo import requires existing event ([#269](https://github.com/the-luap/picpeak/issues/269)) ([5295516](https://github.com/the-luap/picpeak/commit/5295516b67a1d9f035564c5f9a724f25f8d21c78))
+* clarify file system photo import requires existing event ([#269](https://github.com/the-luap/picpeak/issues/269)) ([ee0baaf](https://github.com/the-luap/picpeak/commit/ee0baafc59f3588a26172aa8835c12dcaec35d10))
+
+## [3.26.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.25.0-beta.0...v3.26.0-beta.0) (2026-04-09)
+
+
+### Features
+
+* sort photos by capture date with configurable default sort ([#283](https://github.com/the-luap/picpeak/issues/283)) ([8805fa5](https://github.com/the-luap/picpeak/commit/8805fa53e61c6b3672a8f6dad14d2fd17998a451))
+* sort photos by capture date with configurable default sort ([#283](https://github.com/the-luap/picpeak/issues/283)) ([633d4a0](https://github.com/the-luap/picpeak/commit/633d4a0f301e355ee9f057347f2f8dee8c5b4163))
+
+
+### Bug Fixes
+
+* resolve password change redirect loop ([#263](https://github.com/the-luap/picpeak/issues/263)) and file watcher crash ([#269](https://github.com/the-luap/picpeak/issues/269)) ([b23c51b](https://github.com/the-luap/picpeak/commit/b23c51b386270dee4d911902b728dfacb1ff1bf9))
+* resolve password change redirect loop and file watcher crash ([835bdf5](https://github.com/the-luap/picpeak/commit/835bdf5abb40c7b143c5cdafb507c317a7c349bf)), closes [#269](https://github.com/the-luap/picpeak/issues/269)
+
+## [3.25.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.24.1-beta.0...v3.25.0-beta.0) (2026-04-08)
+
+
+### Features
+
+* draft mode, admin branding, and workflow improvements ([dc98206](https://github.com/the-luap/picpeak/commit/dc98206737d1ebe43637319ce8c5b6da2e44c05d))
+* draft mode, admin branding, and workflow improvements ([40332a7](https://github.com/the-luap/picpeak/commit/40332a71db6534097940d3f9362b0fe651dba6c7))
+
+## [3.24.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.24.0-beta.0...v3.24.1-beta.0) (2026-04-05)
+
+
+### Bug Fixes
+
+* resolve redirect loop after mandatory password change ([#263](https://github.com/the-luap/picpeak/issues/263)) ([07fc5e6](https://github.com/the-luap/picpeak/commit/07fc5e6519cd84f2214479d5f31bc35a495bfe4b))
+* resolve redirect loop after mandatory password change ([#263](https://github.com/the-luap/picpeak/issues/263)) ([3c8d344](https://github.com/the-luap/picpeak/commit/3c8d344ddd23974c9cf0f5f63edd6cd07817fee9))
+
+## [3.24.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.23.0-beta.0...v3.24.0-beta.0) (2026-04-04)
+
+
+### Features
+
+* warn about low thumbnail resolution when selecting beta themes ([ee3f6ae](https://github.com/the-luap/picpeak/commit/ee3f6ae13bf9c9fb3295286e84150e04bf9fbce4))
+* warn about low thumbnail resolution with beta themes ([aef9b4e](https://github.com/the-luap/picpeak/commit/aef9b4ed7fc443cbec8890c580759077e05e77b4))
+
+## [3.23.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.22.0-beta.0...v3.23.0-beta.0) (2026-04-04)
+
+
+### Features
+
+* multilingual email templates with translations table ([8c5996e](https://github.com/the-luap/picpeak/commit/8c5996e4ec43b2817d84cc040cfe52878ffb61d5))
+* multilingual email templates with translations table ([f50d7c0](https://github.com/the-luap/picpeak/commit/f50d7c0c51aa84a2182e450cd4b6a00777a8f9c0))
+
+
+### Bug Fixes
+
+* pin npm to v10 in backend Dockerfile ([ddefd3a](https://github.com/the-luap/picpeak/commit/ddefd3a95e5047d4a22aa4b6fef57dfb1c880967))
+* pin npm upgrade to v10 in backend Dockerfile ([978e447](https://github.com/the-luap/picpeak/commit/978e4473b5227ee61ad7d17487063eb3284bea36))
+
+## [3.22.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.21.1-beta.0...v3.22.0-beta.0) (2026-03-25)
+
+
+### Features
+
+* add Dutch (nl) locale and fix missing translation keys across all locales ([b54a80d](https://github.com/the-luap/picpeak/commit/b54a80d251bcbb9a126e32eeaef522688bc810c6))
+* add Dutch locale and fix missing translation keys ([e32da68](https://github.com/the-luap/picpeak/commit/e32da68cbdfa430d62cbb1057ea418dc6b2f14fb))
+
+## [3.21.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.21.0-beta.0...v3.21.1-beta.0) (2026-03-22)
+
+
+### Bug Fixes
+
+* address Shannon security assessment findings (37 vulnerabilities) ([#254](https://github.com/the-luap/picpeak/issues/254)) ([23cd9cb](https://github.com/the-luap/picpeak/commit/23cd9cb680eb77b94a97266c3353dfc835f0cc69))
+
+## [3.21.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.20.1-beta.0...v3.21.0-beta.0) (2026-03-18)
+
+
+### Features
+
+* add per-gallery thumbnail scale setting ([#172](https://github.com/the-luap/picpeak/issues/172)) ([#251](https://github.com/the-luap/picpeak/issues/251)) ([ee46088](https://github.com/the-luap/picpeak/commit/ee46088985ebbbb81d16e5bac23be2060c94397f))
+
+
+### Bug Fixes
+
+* wrap test email with standard email template ([#252](https://github.com/the-luap/picpeak/issues/252)) ([954a011](https://github.com/the-luap/picpeak/commit/954a0118bae5770c74f1e811e03b8fc702c70db2))
+
+## [3.20.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.20.0-beta.0...v3.20.1-beta.0) (2026-03-17)
+
+
+### Bug Fixes
+
+* address beta feedback - gallery layout fixes, Russian locale, email logo ([#249](https://github.com/the-luap/picpeak/issues/249)) ([486239a](https://github.com/the-luap/picpeak/commit/486239aeb9b5f56551d5aa90f0bad3008eedc3bb))
+
+## [3.20.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.19.2-beta.0...v3.20.0-beta.0) (2026-03-17)
+
+
+### Features
+
+* photo visibility control with client access ([#172](https://github.com/the-luap/picpeak/issues/172)) ([4a93e4e](https://github.com/the-luap/picpeak/commit/4a93e4e8cbe1b7a23a8be706291a270ccdf5bb55))
+* photo visibility control with client access ([#172](https://github.com/the-luap/picpeak/issues/172)) ([e1b6e43](https://github.com/the-luap/picpeak/commit/e1b6e43e524211c913d3d29ade5fc029df12920f))
+
+## [3.19.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.19.1-beta.0...v3.19.2-beta.0) (2026-03-16)
+
+
+### Bug Fixes
+
+* **security:** invalidate tokens on password change, enforce session timeout, fix role update ([f362239](https://github.com/the-luap/picpeak/commit/f3622396e77ce5d0b0741e439fc554a1dccaca50))
+* **security:** token invalidation on password change, session timeout enforcement ([7ca9631](https://github.com/the-luap/picpeak/commit/7ca96315e254eef58d8ecc505f95a5186d2fa2da))
+
+## [3.19.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.19.0-beta.0...v3.19.1-beta.0) (2026-03-16)
+
+
+### Bug Fixes
+
+* external media dimensions, theme race condition, email color customization ([dfae2c2](https://github.com/the-luap/picpeak/commit/dfae2c2bc6d86378c553cd847b439f7cb53a4f2a))
+* resolve external media dimensions, gallery theme race condition, and add email color customization ([bbeedd1](https://github.com/the-luap/picpeak/commit/bbeedd1888561b6c57586b5f42bbfee3ffc69fd7))
+
+## [3.19.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.18.2-beta.0...v3.19.0-beta.0) (2026-03-16)
+
+
+### Features
+
+* add photo cap per event and Portuguese (pt-BR) locale ([1fa222e](https://github.com/the-luap/picpeak/commit/1fa222e9c4c26e525c7899e368988c6b0b08da85))
+* add photo cap per event and Portuguese locale ([088de43](https://github.com/the-luap/picpeak/commit/088de43f09f974d444f50452ef1117315c289ebc))
+
+## [3.18.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.18.1-beta.0...v3.18.2-beta.0) (2026-03-16)
+
+
+### Bug Fixes
+
+* resolve code scanning security alerts (multer, tar, Node 22) ([85a07fc](https://github.com/the-luap/picpeak/commit/85a07fcca7ad935f4c0c300f5ffe2f3af8da1e5f))
+* update dependencies to resolve code scanning security alerts ([1f524f2](https://github.com/the-luap/picpeak/commit/1f524f23580d2e2a21dbba28cb46aed76e85c475))
+
+## [3.18.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.18.0-beta.0...v3.18.1-beta.0) (2026-03-16)
+
+
+### Bug Fixes
+
+* wrap email preview with full styled header/footer template ([9a6d2e8](https://github.com/the-luap/picpeak/commit/9a6d2e8e3a3fab8d7969a8a42e94934c38d88392))
+* wrap email preview with full styled header/footer template ([fc0911a](https://github.com/the-luap/picpeak/commit/fc0911acf8b7c8a18d71bb4267f1086acd1e0ca1)), closes [#229](https://github.com/the-luap/picpeak/issues/229)
+
+## [3.18.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.17.2-beta.0...v3.18.0-beta.0) (2026-03-16)
+
+
+### Features
+
+* add visual WYSIWYG email template editor ([#229](https://github.com/the-luap/picpeak/issues/229)) ([04a7ea8](https://github.com/the-luap/picpeak/commit/04a7ea80f95d6aeb474b145292e75f45fb85c66d))
+* register Russian locale and add to language selector ([6f95b8c](https://github.com/the-luap/picpeak/commit/6f95b8c26cd794525e15e45d478f9ead0ec22555))
+* visual WYSIWYG email template editor ([703c03f](https://github.com/the-luap/picpeak/commit/703c03fbee754a5291b57b885c5e82fbdd3e69e9))
+
+
+### Bug Fixes
+
+* shorten Save button label on email template editor ([7250c42](https://github.com/the-luap/picpeak/commit/7250c427b905ffa3e8696dff607450f5a0b801b8))
+
+## [3.17.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.17.1-beta.0...v3.17.2-beta.0) (2026-03-11)
+
+
+### Bug Fixes
+
+* update security policy with private reporting channels ([308e086](https://github.com/the-luap/picpeak/commit/308e08626383bab213ce3eb5563608dff6168ef4))
+* update security policy with proper contact email and private reporting ([67b0f32](https://github.com/the-luap/picpeak/commit/67b0f32456d0216e4c685a104c680fa5a5fd578f)), closes [#223](https://github.com/the-luap/picpeak/issues/223)
+* video upload media type, select all, and dimension repair ([#203](https://github.com/the-luap/picpeak/issues/203), [#220](https://github.com/the-luap/picpeak/issues/220), [#180](https://github.com/the-luap/picpeak/issues/180)) ([fc75bcd](https://github.com/the-luap/picpeak/commit/fc75bcdfc38673d6e4dd1cd943cfb4638d3a306c))
+* video upload, select all, and dimension repair ([#203](https://github.com/the-luap/picpeak/issues/203), [#220](https://github.com/the-luap/picpeak/issues/220), [#180](https://github.com/the-luap/picpeak/issues/180)) ([a0bb080](https://github.com/the-luap/picpeak/commit/a0bb0805868e742f323b64312c3c5ef8ec408f68))
+
+## [3.17.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.17.0-beta.0...v3.17.1-beta.0) (2026-03-08)
+
+
+### Bug Fixes
+
+* respect optional email settings in event creation ([831ea6a](https://github.com/the-luap/picpeak/commit/831ea6a3bccfae4ec00ce1f619967b91b85150ce))
+* respect optional email settings in event creation ([#217](https://github.com/the-luap/picpeak/issues/217)) ([9c44a0e](https://github.com/the-luap/picpeak/commit/9c44a0ebfa527fa133512eb7f2f03335a2377aaa))
+
+## [3.17.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.16.0-beta.0...v3.17.0-beta.0) (2026-03-05)
+
+
+### Features
+
+* configurable upload batch size for reverse proxy compatibility ([9b7495e](https://github.com/the-luap/picpeak/commit/9b7495e0054975e66c9b5006c24a9fae63969de4))
+
+## [3.16.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.15.3-beta.0...v3.16.0-beta.0) (2026-03-05)
+
+
+### Features
+
+* add thumbnail settings UI to admin panel ([3a30fea](https://github.com/the-luap/picpeak/commit/3a30fea862034d64fbc7188fc25292594a9319e2))
+* add thumbnail settings UI to admin settings page ([#206](https://github.com/the-luap/picpeak/issues/206)) ([7d6d2f5](https://github.com/the-luap/picpeak/commit/7d6d2f56883a4402f0d97c95b0432a8a783c8024))
+
+## [3.15.3-beta.0](https://github.com/the-luap/picpeak/compare/v3.15.2-beta.0...v3.15.3-beta.0) (2026-03-02)
+
+
+### Bug Fixes
+
+* issue [#203](https://github.com/the-luap/picpeak/issues/203) file type validation + security CVE fixes ([8017171](https://github.com/the-luap/picpeak/commit/80171713e0ffedda56f7cffb403b25a8d55634d1))
+* respect allowed_file_types setting for upload validation ([#203](https://github.com/the-luap/picpeak/issues/203)) ([fe07a14](https://github.com/the-luap/picpeak/commit/fe07a148f1d998c0be00377c1f8b4eca3908305c))
+* **security:** resolve all npm audit vulnerabilities ([4272618](https://github.com/the-luap/picpeak/commit/4272618b3f7fcb06aaca14fb724a6a7733251f24))
+* **security:** resolve Docker image CVEs for code scanning alerts ([cbecb93](https://github.com/the-luap/picpeak/commit/cbecb9323cf4b80c800326de14f6df73f60147c1))
+
+## [2.6.0](https://github.com/the-luap/picpeak/compare/v2.5.1...v2.6.0) (2026-03-11)
+
+
+### Features
+
+* add configurable upload batch size for reverse proxy compatibility ([#208](https://github.com/the-luap/picpeak/issues/208)) ([02a46e0](https://github.com/the-luap/picpeak/commit/02a46e083d68cfdb355b5a4fe4a8da7d667050b9))
+* configurable upload batch size for reverse proxy compatibility ([4243363](https://github.com/the-luap/picpeak/commit/424336340bef8e1629490ade154f0ceebb2a71e1))
+
+
+### Bug Fixes
+
+* video upload media type, select all, and dimension repair ([#203](https://github.com/the-luap/picpeak/issues/203), [#220](https://github.com/the-luap/picpeak/issues/220), [#180](https://github.com/the-luap/picpeak/issues/180)) ([fc75bcd](https://github.com/the-luap/picpeak/commit/fc75bcdfc38673d6e4dd1cd943cfb4638d3a306c))
+* video upload, select all, and dimension repair ([#203](https://github.com/the-luap/picpeak/issues/203), [#220](https://github.com/the-luap/picpeak/issues/220), [#180](https://github.com/the-luap/picpeak/issues/180)) ([a0bb080](https://github.com/the-luap/picpeak/commit/a0bb0805868e742f323b64312c3c5ef8ec408f68))
+
+## [2.5.1](https://github.com/the-luap/picpeak/compare/v2.5.0...v2.5.1) (2026-02-22)
+
+
+### Bug Fixes
+
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([33af088](https://github.com/the-luap/picpeak/commit/33af0885607799e0071e2e74a582c7eb396c9b83))
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([33483cf](https://github.com/the-luap/picpeak/commit/33483cf32dfae57f8da51c0765353792239135f9))
+
+## [2.5.0](https://github.com/the-luap/picpeak/compare/v2.4.0...v2.5.0) (2026-02-21)
+
+
+### Features
+
+* add admin dark mode and SEO/robots.txt settings ([9c2a0d2](https://github.com/the-luap/picpeak/commit/9c2a0d272a21dfcace2ec795034e2f1adcba47e0))
+* add bulk category editing for photos ([#157](https://github.com/the-luap/picpeak/issues/157)) ([eca36c7](https://github.com/the-luap/picpeak/commit/eca36c70a23f18f937a9f5bddeff855e18f364c3))
+* add category hero/cover photo selection ([#163](https://github.com/the-luap/picpeak/issues/163)) ([6c30e2c](https://github.com/the-luap/picpeak/commit/6c30e2c2edd19a24d4f30a9558690bb7e2331b32))
+* add customizable event types with admin management ([f8881d5](https://github.com/the-luap/picpeak/commit/f8881d5bd62d449fb40917ec8c20f0eb16c1fdad))
+* add Gallery Premium and Gallery Story layouts (Beta) ([e179def](https://github.com/the-luap/picpeak/commit/e179def3cceefe5fd6acd5574f2986e4f9e223ef))
+* add hero image focal point picker with anchor positioning ([#162](https://github.com/the-luap/picpeak/issues/162)) ([734868a](https://github.com/the-luap/picpeak/commit/734868abc23731b0ac9ad73e799194df1e6aa6ab))
+* add justified layout modes and aspect-ratio-aware mosaic ([#146](https://github.com/the-luap/picpeak/issues/146)) ([608bbd5](https://github.com/the-luap/picpeak/commit/608bbd50e7b31d49c7516a00e96f284fa16e2777))
+* Add justified layout modes and aspect-ratio-aware mosaic ([#146](https://github.com/the-luap/picpeak/issues/146)) ([ef2ae00](https://github.com/the-luap/picpeak/commit/ef2ae00ff20b754c2f2ed797e18c146d12d7f31a))
+* add justified/rows layout mode to masonry gallery ([#146](https://github.com/the-luap/picpeak/issues/146)) ([e081b56](https://github.com/the-luap/picpeak/commit/e081b56a44bf9fdaa3dd225d5dd4dde35bfe83d3))
+* add justified/rows layout mode to masonry gallery ([#146](https://github.com/the-luap/picpeak/issues/146)) + security fixes ([cd1d504](https://github.com/the-luap/picpeak/commit/cd1d50474f673b759c2f9401fdbe209a84773e39))
+* add optional event date and expiration settings ([3079eaa](https://github.com/the-luap/picpeak/commit/3079eaa2e5d1728c2c0f315626cc253e4b08edc2))
+* add optional event date and expiration settings ([2151147](https://github.com/the-luap/picpeak/commit/2151147f2d3134448ff32130da44678e2942d73c)), closes [#118](https://github.com/the-luap/picpeak/issues/118)
+* add original filename preservation and Lightroom export support ([a59f414](https://github.com/the-luap/picpeak/commit/a59f41463f960a3a74ce3933dc7db84ee3a2018d))
+* add original filename preservation and Lightroom export support ([9872ad3](https://github.com/the-luap/picpeak/commit/9872ad3aef6488b359c5499a6dc3d8bfbfa48fde))
+* add per-event custom logo upload with bug fixes ([85170b8](https://github.com/the-luap/picpeak/commit/85170b883f504d83f1d862abb3f4e46741074826))
+* add per-event hero logo customization options ([0790a1d](https://github.com/the-luap/picpeak/commit/0790a1ddad774af89827a0a392e9fae0a945bff2))
+* add quilted layout, fix mosaic, and backfill photo dimensions ([#146](https://github.com/the-luap/picpeak/issues/146)) ([46ed1bc](https://github.com/the-luap/picpeak/commit/46ed1bc276867a25b27bf22cd9b9d7e879a6947b))
+* add update instructions dialog, email notifications, and capture date sorting ([50c0990](https://github.com/the-luap/picpeak/commit/50c09904a9434f988ab32a07da5d24db0e02065e)), closes [#181](https://github.com/the-luap/picpeak/issues/181)
+* decouple hero header from gallery layouts ([#158](https://github.com/the-luap/picpeak/issues/158)) ([7b8d8bd](https://github.com/the-luap/picpeak/commit/7b8d8bd92ba7a96717bb4d821b38dddc395f701a))
+* gallery layouts, bulk category editing, and hero header improvements ([7037106](https://github.com/the-luap/picpeak/commit/7037106bff62593bba600d898a781f79f07b459d))
+* gallery layouts, hero customization, bulk categories & event types ([d9e00dc](https://github.com/the-luap/picpeak/commit/d9e00dc0dbd7cef0ddb4665e5306c98aac3573e3))
+* gallery layouts, hero customization, event types, and UX improvements ([#146](https://github.com/the-luap/picpeak/issues/146), [#155](https://github.com/the-luap/picpeak/issues/155)-163, [#170](https://github.com/the-luap/picpeak/issues/170), [#171](https://github.com/the-luap/picpeak/issues/171)) ([4280444](https://github.com/the-luap/picpeak/commit/4280444d70e73db09e67e18ce25bac75cf499b75))
+* improve gallery layouts with aspect-ratio-aware masonry and mosaic modes ([#146](https://github.com/the-luap/picpeak/issues/146)) ([aacfcd5](https://github.com/the-luap/picpeak/commit/aacfcd517ea5739e834cf84627b55b3449740a5c))
+* improve hero image UX and live preview ([#163](https://github.com/the-luap/picpeak/issues/163), [#158](https://github.com/the-luap/picpeak/issues/158)) ([d63f67a](https://github.com/the-luap/picpeak/commit/d63f67a2afba1b92610382aa1012428ccacb86bd))
+* new features and bug fixes for beta release ([151e1bf](https://github.com/the-luap/picpeak/commit/151e1bf50f206ae0571fa044c75b8bc9f0f40120))
+* original filename in admin UI, update dialog, and security hardening ([3ea9d5b](https://github.com/the-luap/picpeak/commit/3ea9d5b1219980032cbee7a2564c0004948923f5))
+* original filename in admin UI, update dialog, security hardening, and bug fixes ([bcf2745](https://github.com/the-luap/picpeak/commit/bcf2745ab64acb968ae4bd0710b28e78c14f340c))
+* per-event custom logos, customizable event types, and multiple bug fixes ([4c08160](https://github.com/the-luap/picpeak/commit/4c081601e02888d7ad289acb7847aee9d6f5703f))
+* pre-generate watermarks for instant lightbox loading ([1be974a](https://github.com/the-luap/picpeak/commit/1be974afbb0b7a1bdbdd140327771907a5d3c2ae)), closes [#112](https://github.com/the-luap/picpeak/issues/112)
+* pre-generated watermarks and mobile upload button improvements ([c6fdd38](https://github.com/the-luap/picpeak/commit/c6fdd38e842e1a8c0aa9cbab9fc791e6669e402d))
+* show original filename in admin UI ([#184](https://github.com/the-luap/picpeak/issues/184)) ([0891be1](https://github.com/the-luap/picpeak/commit/0891be197fdb7d92ade5a293b8db0bed26fa6e3a))
+## [3.15.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.15.1-beta.0...v3.15.2-beta.0) (2026-02-22)
+
+
+### Bug Fixes
+
+* add allow_user_uploads to gallery API responses ([691e3ab](https://github.com/the-luap/picpeak/commit/691e3aba09f2148afe902a0bb0139d062634e669))
+* add STORAGE_PATH to production docker-compose ([cdda709](https://github.com/the-luap/picpeak/commit/cdda70988664a177b351abc6a259ec39664d17ff))
+* checkbox and toggle settings not persisting after page refresh ([808ed1d](https://github.com/the-luap/picpeak/commit/808ed1d2f1164d9fd1114586c68a1f925bf73ddf)), closes [#117](https://github.com/the-luap/picpeak/issues/117)
+* correct invitation activation validation and add missing translations ([991aa98](https://github.com/the-luap/picpeak/commit/991aa98f98cffd1d7785c272726615325e2c0208)), closes [#129](https://github.com/the-luap/picpeak/issues/129)
+* correct invitation email link URL path ([86fa104](https://github.com/the-luap/picpeak/commit/86fa1046d5439cb451feb164175c919c49ca219a)), closes [#129](https://github.com/the-luap/picpeak/issues/129)
+* correct storage path resolution in multiple files ([#96](https://github.com/the-luap/picpeak/issues/96)) ([0e3674b](https://github.com/the-luap/picpeak/commit/0e3674b2b0325bbcee5aa2c9ff7781da92f612d1))
+* correct storage path resolution in multiple files ([#96](https://github.com/the-luap/picpeak/issues/96)) ([3ccb815](https://github.com/the-luap/picpeak/commit/3ccb8154eb40a432aa467fb06b3f216fd0d2c6b4))
+* docker compose v2 syntax and add missing ADMIN_PASSWORD to .env.example ([#189](https://github.com/the-luap/picpeak/issues/189)) ([0817443](https://github.com/the-luap/picpeak/commit/0817443e793e37c770c6a1968ecae4b9464107b0))
+* event-specific custom CSS settings not being saved ([dadef81](https://github.com/the-luap/picpeak/commit/dadef81158972d28aa32812203500f77ed08a999)), closes [#136](https://github.com/the-luap/picpeak/issues/136)
+* events without expiration date incorrectly shown as expired ([c4f16eb](https://github.com/the-luap/picpeak/commit/c4f16eb76c909158abdb63aa4cc22f817f274dc5))
+* handle null dates in dashboard and gallery pages ([c5a8ffc](https://github.com/the-luap/picpeak/commit/c5a8ffc08cd4c53c37fe4fb9cde8519a68f1f343))
+* hero header state and preview in admin theme editor ([#158](https://github.com/the-luap/picpeak/issues/158)) ([f554f46](https://github.com/the-luap/picpeak/commit/f554f463b3492346dba067c0980b52ef42dd5e70))
+* improve ghost button visibility in admin dark mode ([4912e2b](https://github.com/the-luap/picpeak/commit/4912e2bccf282134d5598a8ac80942ed46d0523c))
+* improve password validation errors and event list UX ([#170](https://github.com/the-luap/picpeak/issues/170), [#171](https://github.com/the-luap/picpeak/issues/171)) ([171abb3](https://github.com/the-luap/picpeak/commit/171abb31615484d77cf95a99cb5634afa0160adc))
+* improve photo serving, category filters, and upload chunking ([#155](https://github.com/the-luap/picpeak/issues/155), [#156](https://github.com/the-luap/picpeak/issues/156), [#161](https://github.com/the-luap/picpeak/issues/161)) ([fa4c838](https://github.com/the-luap/picpeak/commit/fa4c83812d87cfa63394e51186e320a072929d37))
+* increase upload limit to 1GB and fix category filters ([#155](https://github.com/the-luap/picpeak/issues/155), [#156](https://github.com/the-luap/picpeak/issues/156)) ([397d33a](https://github.com/the-luap/picpeak/commit/397d33a95a09e0b0986c3f6cf5965c544992a764))
+* mobile upload button not visible in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([cacaffa](https://github.com/the-luap/picpeak/commit/cacaffa5c39f67105c4cfb092ea62157121fb72e))
+* mobile upload button visibility in gallery ([2a2c23d](https://github.com/the-luap/picpeak/commit/2a2c23d11610e6c81684163eb4ea934a6d6104fb)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* mobile upload button visibility in gallery ([df7dbff](https://github.com/the-luap/picpeak/commit/df7dbffbffb180e62af0d2b58326f9de0f515439)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* mobile upload button visibility in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([05a5307](https://github.com/the-luap/picpeak/commit/05a5307e22dc45be4b75b2996ff9fac65dec399d))
+* mobile upload button visibility in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([6cb4342](https://github.com/the-luap/picpeak/commit/6cb43428d1e703267edeacda9ede050a8c4f8e0c))
+* remove non-functional watermark toggle from Feature Toggles ([d4a15db](https://github.com/the-luap/picpeak/commit/d4a15dbe74d0d70bbe6ff03362dc7337fb8f4c5c))
+* render minimal/none header styles, cap hero height, switch category hero images ([#158](https://github.com/the-luap/picpeak/issues/158), [#162](https://github.com/the-luap/picpeak/issues/162), [#163](https://github.com/the-luap/picpeak/issues/163)) ([bc6c48b](https://github.com/the-luap/picpeak/commit/bc6c48bb2429505c2de3641693a8ff4f623a4951))
+* resend gallery email fails for events without password ([6b3ead7](https://github.com/the-luap/picpeak/commit/6b3ead747b1395d8ea2b3d135a5ac24db05e2eb8)), closes [#137](https://github.com/the-luap/picpeak/issues/137)
+* resolve admin invitation flow issues and improve STORAGE_PATH documentation ([41bf6ff](https://github.com/the-luap/picpeak/commit/41bf6ff884d5ef3181f95f3aa4a528434c23947a))
+* resolve code quality issues and add missing i18n keys ([#162](https://github.com/the-luap/picpeak/issues/162), [#163](https://github.com/the-luap/picpeak/issues/163)) ([329d224](https://github.com/the-luap/picpeak/commit/329d224846d3f4eefa31e42337f34047c267d578))
+* resolve mixed light/dark mode styling in admin UI ([#175](https://github.com/the-luap/picpeak/issues/175)) ([f8c8abd](https://github.com/the-luap/picpeak/commit/f8c8abd70bbae35d6cd519894624ade33b5115a8))
+* restore aspect-ratio layouts and improve hero image quality ([#180](https://github.com/the-luap/picpeak/issues/180)) ([3974ba5](https://github.com/the-luap/picpeak/commit/3974ba5de5a6605ad906608d3e4d61620a215059))
+* restore aspect-ratio layouts and improve hero image quality ([#180](https://github.com/the-luap/picpeak/issues/180)) ([5cef7fd](https://github.com/the-luap/picpeak/commit/5cef7fdd188389512bc4b55ae61536c8b1219eb8))
+* show upload button in mobile topbar instead of sidebar ([ae181cf](https://github.com/the-luap/picpeak/commit/ae181cf92fc9c1e85cad7a7b843a4d83cec636ac)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* sync header_style DB column with theme editor selections ([#158](https://github.com/the-luap/picpeak/issues/158)) ([2288309](https://github.com/the-luap/picpeak/commit/228830939553fd32c250704bb89a8ce233324d25))
+* sync header_style DB column with theme editor selections ([#158](https://github.com/the-luap/picpeak/issues/158)) ([a19e7c4](https://github.com/the-luap/picpeak/commit/a19e7c40a200ff822c947a83349ed07ccf4e1b01))
+* update docker-compose to docker compose and add ADMIN_PASSWORD to .env.example ([#189](https://github.com/the-luap/picpeak/issues/189)) ([a4c6248](https://github.com/the-luap/picpeak/commit/a4c624802b2926a16adcf0472a3041562f9b2f48))
+* update packages to fix security vulnerabilities ([8097a0c](https://github.com/the-luap/picpeak/commit/8097a0cb530bd8003597cde81606231efadb0bf5))
+* use actual photo aspect ratios in masonry columns mode ([#146](https://github.com/the-luap/picpeak/issues/146)) ([8711f96](https://github.com/the-luap/picpeak/commit/8711f967a15f5d57f6ad01bfdbd8d33f9ee96abc))
+* use CSS Columns for gap-free mosaic layout ([#146](https://github.com/the-luap/picpeak/issues/146)) ([821d329](https://github.com/the-luap/picpeak/commit/821d3296ea4b6bde499e5497d258f15ab8dd1dbc))
+* use photo dimensions for mosaic aspect ratios ([#146](https://github.com/the-luap/picpeak/issues/146)) ([27ff51e](https://github.com/the-luap/picpeak/commit/27ff51e7a1217848859b47940bc88caa6f1fb20f))
+
+
+### Documentation
+
+* add API_URL environment variable to .env.example files ([3e69579](https://github.com/the-luap/picpeak/commit/3e69579f5a171b31a253b2a42bb033bf1b97387d))
+* emphasize importance of STORAGE_PATH in env example ([3397807](https://github.com/the-luap/picpeak/commit/3397807670784e02cbe34a7a60db43c95d64f19c))
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([5ea4ef3](https://github.com/the-luap/picpeak/commit/5ea4ef3cf36b06f9e6c9108f80bfe2e9a6470898))
+* resolve issues [#194](https://github.com/the-luap/picpeak/issues/194), [#195](https://github.com/the-luap/picpeak/issues/195), [#196](https://github.com/the-luap/picpeak/issues/196), [#197](https://github.com/the-luap/picpeak/issues/197) ([cd00bc1](https://github.com/the-luap/picpeak/commit/cd00bc13d4e02a86a0f1742ed1f11f064614b8da))
+
+## [3.15.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.15.0-beta.0...v3.15.1-beta.0) (2026-02-21)
+
+
+### Bug Fixes
+
+* docker compose v2 syntax and add missing ADMIN_PASSWORD to .env.example ([#189](https://github.com/the-luap/picpeak/issues/189)) ([0817443](https://github.com/the-luap/picpeak/commit/0817443e793e37c770c6a1968ecae4b9464107b0))
+* update docker-compose to docker compose and add ADMIN_PASSWORD to .env.example ([#189](https://github.com/the-luap/picpeak/issues/189)) ([a4c6248](https://github.com/the-luap/picpeak/commit/a4c624802b2926a16adcf0472a3041562f9b2f48))
+
+## [3.15.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.14.0-beta.0...v3.15.0-beta.0) (2026-02-17)
+
+
+### Features
+
+* original filename in admin UI, update dialog, security hardening, and bug fixes ([bcf2745](https://github.com/the-luap/picpeak/commit/bcf2745ab64acb968ae4bd0710b28e78c14f340c))
+
+
+### Bug Fixes
+
+* events without expiration date incorrectly shown as expired ([c4f16eb](https://github.com/the-luap/picpeak/commit/c4f16eb76c909158abdb63aa4cc22f817f274dc5))
+
+## [3.14.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.13.1-beta.0...v3.14.0-beta.0) (2026-02-17)
+
+
+### Features
+
+* add update instructions dialog, email notifications, and capture date sorting ([50c0990](https://github.com/the-luap/picpeak/commit/50c09904a9434f988ab32a07da5d24db0e02065e)), closes [#181](https://github.com/the-luap/picpeak/issues/181)
+* original filename in admin UI, update dialog, and security hardening ([3ea9d5b](https://github.com/the-luap/picpeak/commit/3ea9d5b1219980032cbee7a2564c0004948923f5))
+* show original filename in admin UI ([#184](https://github.com/the-luap/picpeak/issues/184)) ([0891be1](https://github.com/the-luap/picpeak/commit/0891be197fdb7d92ade5a293b8db0bed26fa6e3a))
+
+## [3.13.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.13.0-beta.0...v3.13.1-beta.0) (2026-02-15)
+
+
+### Bug Fixes
+
+* restore aspect-ratio layouts and improve hero image quality ([#180](https://github.com/the-luap/picpeak/issues/180)) ([3974ba5](https://github.com/the-luap/picpeak/commit/3974ba5de5a6605ad906608d3e4d61620a215059))
+* restore aspect-ratio layouts and improve hero image quality ([#180](https://github.com/the-luap/picpeak/issues/180)) ([5cef7fd](https://github.com/the-luap/picpeak/commit/5cef7fdd188389512bc4b55ae61536c8b1219eb8))
+
+## [3.13.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.12.0-beta.0...v3.13.0-beta.0) (2026-02-06)
+
+
+### Features
+
+* improve hero image UX and live preview ([#163](https://github.com/the-luap/picpeak/issues/163), [#158](https://github.com/the-luap/picpeak/issues/158)) ([d63f67a](https://github.com/the-luap/picpeak/commit/d63f67a2afba1b92610382aa1012428ccacb86bd))
+
+## [3.12.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.11.0-beta.0...v3.12.0-beta.0) (2026-02-06)
+
+
+### Features
+
+* add admin dark mode and SEO/robots.txt settings ([9c2a0d2](https://github.com/the-luap/picpeak/commit/9c2a0d272a21dfcace2ec795034e2f1adcba47e0))
+
+
+### Bug Fixes
+
+* improve ghost button visibility in admin dark mode ([4912e2b](https://github.com/the-luap/picpeak/commit/4912e2bccf282134d5598a8ac80942ed46d0523c))
+* resolve mixed light/dark mode styling in admin UI ([#175](https://github.com/the-luap/picpeak/issues/175)) ([f8c8abd](https://github.com/the-luap/picpeak/commit/f8c8abd70bbae35d6cd519894624ade33b5115a8))
+
+## [3.11.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.10.1-beta.0...v3.11.0-beta.0) (2026-02-06)
+
+
+### Features
+
+* add Gallery Premium and Gallery Story layouts (Beta) ([e179def](https://github.com/the-luap/picpeak/commit/e179def3cceefe5fd6acd5574f2986e4f9e223ef))
+* gallery layouts, hero customization, event types, and UX improvements ([#146](https://github.com/the-luap/picpeak/issues/146), [#155](https://github.com/the-luap/picpeak/issues/155)-163, [#170](https://github.com/the-luap/picpeak/issues/170), [#171](https://github.com/the-luap/picpeak/issues/171)) ([4280444](https://github.com/the-luap/picpeak/commit/4280444d70e73db09e67e18ce25bac75cf499b75))
+
+
+### Bug Fixes
+
+* improve password validation errors and event list UX ([#170](https://github.com/the-luap/picpeak/issues/170), [#171](https://github.com/the-luap/picpeak/issues/171)) ([171abb3](https://github.com/the-luap/picpeak/commit/171abb31615484d77cf95a99cb5634afa0160adc))
+* render minimal/none header styles, cap hero height, switch category hero images ([#158](https://github.com/the-luap/picpeak/issues/158), [#162](https://github.com/the-luap/picpeak/issues/162), [#163](https://github.com/the-luap/picpeak/issues/163)) ([bc6c48b](https://github.com/the-luap/picpeak/commit/bc6c48bb2429505c2de3641693a8ff4f623a4951))
+
+## [3.10.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.10.0-beta.0...v3.10.1-beta.0) (2026-02-03)
+
+
+### Bug Fixes
+
+* sync header_style DB column with theme editor selections ([#158](https://github.com/the-luap/picpeak/issues/158)) ([2288309](https://github.com/the-luap/picpeak/commit/228830939553fd32c250704bb89a8ce233324d25))
+* sync header_style DB column with theme editor selections ([#158](https://github.com/the-luap/picpeak/issues/158)) ([a19e7c4](https://github.com/the-luap/picpeak/commit/a19e7c40a200ff822c947a83349ed07ccf4e1b01))
+
+## [3.10.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.9.0-beta.0...v3.10.0-beta.0) (2026-02-03)
+
+
+### Features
+
+* add category hero/cover photo selection ([#163](https://github.com/the-luap/picpeak/issues/163)) ([6c30e2c](https://github.com/the-luap/picpeak/commit/6c30e2c2edd19a24d4f30a9558690bb7e2331b32))
+* add hero image focal point picker with anchor positioning ([#162](https://github.com/the-luap/picpeak/issues/162)) ([734868a](https://github.com/the-luap/picpeak/commit/734868abc23731b0ac9ad73e799194df1e6aa6ab))
+* gallery layouts, hero customization, bulk categories & event types ([d9e00dc](https://github.com/the-luap/picpeak/commit/d9e00dc0dbd7cef0ddb4665e5306c98aac3573e3))
+
+
+### Bug Fixes
+
+* hero header state and preview in admin theme editor ([#158](https://github.com/the-luap/picpeak/issues/158)) ([f554f46](https://github.com/the-luap/picpeak/commit/f554f463b3492346dba067c0980b52ef42dd5e70))
+* improve photo serving, category filters, and upload chunking ([#155](https://github.com/the-luap/picpeak/issues/155), [#156](https://github.com/the-luap/picpeak/issues/156), [#161](https://github.com/the-luap/picpeak/issues/161)) ([fa4c838](https://github.com/the-luap/picpeak/commit/fa4c83812d87cfa63394e51186e320a072929d37))
+* resolve code quality issues and add missing i18n keys ([#162](https://github.com/the-luap/picpeak/issues/162), [#163](https://github.com/the-luap/picpeak/issues/163)) ([329d224](https://github.com/the-luap/picpeak/commit/329d224846d3f4eefa31e42337f34047c267d578))
+
+## [3.9.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.8.0-beta.0...v3.9.0-beta.0) (2026-02-01)
+
+
+### Features
+
+* add bulk category editing for photos ([#157](https://github.com/the-luap/picpeak/issues/157)) ([eca36c7](https://github.com/the-luap/picpeak/commit/eca36c70a23f18f937a9f5bddeff855e18f364c3))
+* decouple hero header from gallery layouts ([#158](https://github.com/the-luap/picpeak/issues/158)) ([7b8d8bd](https://github.com/the-luap/picpeak/commit/7b8d8bd92ba7a96717bb4d821b38dddc395f701a))
+* gallery layouts, bulk category editing, and hero header improvements ([7037106](https://github.com/the-luap/picpeak/commit/7037106bff62593bba600d898a781f79f07b459d))
+
+
+### Bug Fixes
+
+* increase upload limit to 1GB and fix category filters ([#155](https://github.com/the-luap/picpeak/issues/155), [#156](https://github.com/the-luap/picpeak/issues/156)) ([397d33a](https://github.com/the-luap/picpeak/commit/397d33a95a09e0b0986c3f6cf5965c544992a764))
+
+## [3.8.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.7.0-beta.0...v3.8.0-beta.0) (2026-01-30)
+
+
+### Features
+
+* add quilted layout, fix mosaic, and backfill photo dimensions ([#146](https://github.com/the-luap/picpeak/issues/146)) ([46ed1bc](https://github.com/the-luap/picpeak/commit/46ed1bc276867a25b27bf22cd9b9d7e879a6947b))
+* improve gallery layouts with aspect-ratio-aware masonry and mosaic modes ([#146](https://github.com/the-luap/picpeak/issues/146)) ([aacfcd5](https://github.com/the-luap/picpeak/commit/aacfcd517ea5739e834cf84627b55b3449740a5c))
+
+
+### Bug Fixes
+
+* use actual photo aspect ratios in masonry columns mode ([#146](https://github.com/the-luap/picpeak/issues/146)) ([8711f96](https://github.com/the-luap/picpeak/commit/8711f967a15f5d57f6ad01bfdbd8d33f9ee96abc))
+* use CSS Columns for gap-free mosaic layout ([#146](https://github.com/the-luap/picpeak/issues/146)) ([821d329](https://github.com/the-luap/picpeak/commit/821d3296ea4b6bde499e5497d258f15ab8dd1dbc))
+* use photo dimensions for mosaic aspect ratios ([#146](https://github.com/the-luap/picpeak/issues/146)) ([27ff51e](https://github.com/the-luap/picpeak/commit/27ff51e7a1217848859b47940bc88caa6f1fb20f))
+
+## [3.7.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.6.0-beta.0...v3.7.0-beta.0) (2026-01-28)
+
+
+### Features
+
+* add justified layout modes and aspect-ratio-aware mosaic ([#146](https://github.com/the-luap/picpeak/issues/146)) ([608bbd5](https://github.com/the-luap/picpeak/commit/608bbd50e7b31d49c7516a00e96f284fa16e2777))
+* Add justified layout modes and aspect-ratio-aware mosaic ([#146](https://github.com/the-luap/picpeak/issues/146)) ([ef2ae00](https://github.com/the-luap/picpeak/commit/ef2ae00ff20b754c2f2ed797e18c146d12d7f31a))
+
+## [3.6.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.5.0-beta.0...v3.6.0-beta.0) (2026-01-27)
+
+
+### Features
+
+* add justified/rows layout mode to masonry gallery ([#146](https://github.com/the-luap/picpeak/issues/146)) ([e081b56](https://github.com/the-luap/picpeak/commit/e081b56a44bf9fdaa3dd225d5dd4dde35bfe83d3))
+* add justified/rows layout mode to masonry gallery ([#146](https://github.com/the-luap/picpeak/issues/146)) + security fixes ([cd1d504](https://github.com/the-luap/picpeak/commit/cd1d50474f673b759c2f9401fdbe209a84773e39))
+
+
+### Bug Fixes
+
+* update packages to fix security vulnerabilities ([8097a0c](https://github.com/the-luap/picpeak/commit/8097a0cb530bd8003597cde81606231efadb0bf5))
+
+## [3.5.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.4.0-beta.0...v3.5.0-beta.0) (2026-01-25)
+
+
+### Features
+
+* add per-event custom logo upload with bug fixes ([85170b8](https://github.com/the-luap/picpeak/commit/85170b883f504d83f1d862abb3f4e46741074826))
+* per-event custom logos, customizable event types, and multiple bug fixes ([4c08160](https://github.com/the-luap/picpeak/commit/4c081601e02888d7ad289acb7847aee9d6f5703f))
+
+## [3.4.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.3.0-beta.0...v3.4.0-beta.0) (2026-01-22)
+
+
+### Features
+
+* add customizable event types with admin management ([f8881d5](https://github.com/the-luap/picpeak/commit/f8881d5bd62d449fb40917ec8c20f0eb16c1fdad))
+* add per-event hero logo customization options ([0790a1d](https://github.com/the-luap/picpeak/commit/0790a1ddad774af89827a0a392e9fae0a945bff2))
+* new features and bug fixes for beta release ([151e1bf](https://github.com/the-luap/picpeak/commit/151e1bf50f206ae0571fa044c75b8bc9f0f40120))
+
+
+### Bug Fixes
+
+* event-specific custom CSS settings not being saved ([dadef81](https://github.com/the-luap/picpeak/commit/dadef81158972d28aa32812203500f77ed08a999)), closes [#136](https://github.com/the-luap/picpeak/issues/136)
+* handle null dates in dashboard and gallery pages ([c5a8ffc](https://github.com/the-luap/picpeak/commit/c5a8ffc08cd4c53c37fe4fb9cde8519a68f1f343))
+* remove non-functional watermark toggle from Feature Toggles ([d4a15db](https://github.com/the-luap/picpeak/commit/d4a15dbe74d0d70bbe6ff03362dc7337fb8f4c5c))
+* resend gallery email fails for events without password ([6b3ead7](https://github.com/the-luap/picpeak/commit/6b3ead747b1395d8ea2b3d135a5ac24db05e2eb8)), closes [#137](https://github.com/the-luap/picpeak/issues/137)
+
+## [3.3.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.2.5-beta.0...v3.3.0-beta.0) (2026-01-21)
+
+
+### Features
+
+* add original filename preservation and Lightroom export support ([a59f414](https://github.com/the-luap/picpeak/commit/a59f41463f960a3a74ce3933dc7db84ee3a2018d))
+* add original filename preservation and Lightroom export support ([9872ad3](https://github.com/the-luap/picpeak/commit/9872ad3aef6488b359c5499a6dc3d8bfbfa48fde))
+
+## [3.2.5-beta.0](https://github.com/the-luap/picpeak/compare/v3.2.4-beta.0...v3.2.5-beta.0) (2026-01-18)
+
+
+### Bug Fixes
+
+* add STORAGE_PATH to production docker-compose ([cdda709](https://github.com/the-luap/picpeak/commit/cdda70988664a177b351abc6a259ec39664d17ff))
+* correct invitation activation validation and add missing translations ([991aa98](https://github.com/the-luap/picpeak/commit/991aa98f98cffd1d7785c272726615325e2c0208)), closes [#129](https://github.com/the-luap/picpeak/issues/129)
+* correct invitation email link URL path ([86fa104](https://github.com/the-luap/picpeak/commit/86fa1046d5439cb451feb164175c919c49ca219a)), closes [#129](https://github.com/the-luap/picpeak/issues/129)
+* resolve admin invitation flow issues and improve STORAGE_PATH documentation ([41bf6ff](https://github.com/the-luap/picpeak/commit/41bf6ff884d5ef3181f95f3aa4a528434c23947a))
+
+
+### Documentation
+
+* emphasize importance of STORAGE_PATH in env example ([3397807](https://github.com/the-luap/picpeak/commit/3397807670784e02cbe34a7a60db43c95d64f19c))
+
+## [3.2.4-beta.0](https://github.com/the-luap/picpeak/compare/v3.2.3-beta.0...v3.2.4-beta.0) (2026-01-17)
+
+
+### Bug Fixes
+
+* correct storage path resolution in multiple files ([#96](https://github.com/the-luap/picpeak/issues/96)) ([0e3674b](https://github.com/the-luap/picpeak/commit/0e3674b2b0325bbcee5aa2c9ff7781da92f612d1))
+* correct storage path resolution in multiple files ([#96](https://github.com/the-luap/picpeak/issues/96)) ([3ccb815](https://github.com/the-luap/picpeak/commit/3ccb8154eb40a432aa467fb06b3f216fd0d2c6b4))
+
+## [3.2.3-beta.0](https://github.com/the-luap/picpeak/compare/v3.2.2-beta.0...v3.2.3-beta.0) (2026-01-16)
+
+
+### Bug Fixes
+
+* add allow_user_uploads to gallery API responses ([691e3ab](https://github.com/the-luap/picpeak/commit/691e3aba09f2148afe902a0bb0139d062634e669))
+* mobile upload button not visible in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([cacaffa](https://github.com/the-luap/picpeak/commit/cacaffa5c39f67105c4cfb092ea62157121fb72e))
+
+## [3.2.2-beta.0](https://github.com/the-luap/picpeak/compare/v3.2.1-beta.0...v3.2.2-beta.0) (2026-01-16)
+
+
+### Bug Fixes
+
+* mobile upload button visibility in gallery ([2a2c23d](https://github.com/the-luap/picpeak/commit/2a2c23d11610e6c81684163eb4ea934a6d6104fb)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* mobile upload button visibility in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([05a5307](https://github.com/the-luap/picpeak/commit/05a5307e22dc45be4b75b2996ff9fac65dec399d))
+
+## [3.2.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.2.0-beta.0...v3.2.1-beta.0) (2026-01-16)
+
+
+### Bug Fixes
+
+* mobile upload button visibility in gallery ([df7dbff](https://github.com/the-luap/picpeak/commit/df7dbffbffb180e62af0d2b58326f9de0f515439)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* mobile upload button visibility in gallery ([#113](https://github.com/the-luap/picpeak/issues/113)) ([6cb4342](https://github.com/the-luap/picpeak/commit/6cb43428d1e703267edeacda9ede050a8c4f8e0c))
+
+## [3.2.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.1.0-beta.0...v3.2.0-beta.0) (2026-01-16)
+
+
+### Features
+
+* add optional event date and expiration settings ([3079eaa](https://github.com/the-luap/picpeak/commit/3079eaa2e5d1728c2c0f315626cc253e4b08edc2))
+* add optional event date and expiration settings ([2151147](https://github.com/the-luap/picpeak/commit/2151147f2d3134448ff32130da44678e2942d73c)), closes [#118](https://github.com/the-luap/picpeak/issues/118)
+
+
+### Bug Fixes
+
+* checkbox and toggle settings not persisting after page refresh ([808ed1d](https://github.com/the-luap/picpeak/commit/808ed1d2f1164d9fd1114586c68a1f925bf73ddf)), closes [#117](https://github.com/the-luap/picpeak/issues/117)
+
+
+### Documentation
+
+* add API_URL environment variable to .env.example files ([3e69579](https://github.com/the-luap/picpeak/commit/3e69579f5a171b31a253b2a42bb033bf1b97387d))
+
+## [3.1.0-beta.0](https://github.com/the-luap/picpeak/compare/v3.0.1-beta.0...v3.1.0-beta.0) (2026-01-15)
+
+
+### Features
+
+* dynamic website title from branding settings ([d29aab7](https://github.com/the-luap/picpeak/commit/d29aab7c70c5777451666fb7d5c7a9729dab684a))
+* pre-generate watermarks for instant lightbox loading ([1be974a](https://github.com/the-luap/picpeak/commit/1be974afbb0b7a1bdbdd140327771907a5d3c2ae)), closes [#112](https://github.com/the-luap/picpeak/issues/112)
+* pre-generated watermarks and mobile upload button improvements ([c6fdd38](https://github.com/the-luap/picpeak/commit/c6fdd38e842e1a8c0aa9cbab9fc791e6669e402d))
+
+
+### Bug Fixes
+
+* add lightbox loading spinner and watermark cache invalidation ([050ed37](https://github.com/the-luap/picpeak/commit/050ed378199eb3b15c7c7f243792f68f858803f5))
+* lightbox watermark loading, white label translations, and dynamic footer year ([ce8587b](https://github.com/the-luap/picpeak/commit/ce8587b24df3f53a11a74348eff8b5c5b96c5488))
+* prevent database migration restart failures ([83a4344](https://github.com/the-luap/picpeak/commit/83a4344a01de4f65c5024fdf2d177a04457ccd2f)), closes [#107](https://github.com/the-luap/picpeak/issues/107)
+* show upload button in mobile topbar instead of sidebar ([ae181cf](https://github.com/the-luap/picpeak/commit/ae181cf92fc9c1e85cad7a7b843a4d83cec636ac)), closes [#113](https://github.com/the-luap/picpeak/issues/113)
+* watermark thumbnails, custom logo display, and German translations ([ea20446](https://github.com/the-luap/picpeak/commit/ea20446a797a00cf45dbe7bf6f06574a79c4d8a6))
+
+## [3.0.1-beta.0](https://github.com/the-luap/picpeak/compare/v3.0.0-beta.0...v3.0.1-beta.0) (2026-01-15)
+
+
+### Bug Fixes
+
+* CI workflow fixes for protected branches ([cb01218](https://github.com/the-luap/picpeak/commit/cb012186d93403a1ac4e2d2f5283319603b290d6))
+* lightbox watermark loading, white label translations, and dynamic footer year ([3b720ed](https://github.com/the-luap/picpeak/commit/3b720ed56ecd2ded6aec57309f8c408c63a617ef))
+* lightbox watermark loading, white label translations, and dynamic footer year ([ce8587b](https://github.com/the-luap/picpeak/commit/ce8587b24df3f53a11a74348eff8b5c5b96c5488))
+* lightbox watermark loading, white label translations, and dynamic footer year ([#108](https://github.com/the-luap/picpeak/issues/108)) ([3b720ed](https://github.com/the-luap/picpeak/commit/3b720ed56ecd2ded6aec57309f8c408c63a617ef))
+
+## [2.3.2](https://github.com/the-luap/picpeak/compare/v2.3.1...v2.3.2) (2026-01-15)
+
+
+### Bug Fixes
+
+* watermark thumbnails, custom logo display, and German translations ([f843e4c](https://github.com/the-luap/picpeak/commit/f843e4c25cef02eef354fd3ee25824e20e4f8fc8))
+* watermark thumbnails, custom logo display, and German translations ([ea20446](https://github.com/the-luap/picpeak/commit/ea20446a797a00cf45dbe7bf6f06574a79c4d8a6))
+
 ## [2.3.1](https://github.com/the-luap/picpeak/compare/v2.3.0...v2.3.1) (2026-01-15)
 
 

DEPLOYMENT_GUIDE.md

@@ -1,799 +0,0 @@
-# 🚀 PicPeak Deployment Guide
-
-This guide covers multiple deployment options for PicPeak, from simple local setups to production-ready configurations.
-
-## 📋 Table of Contents
-
-- [Quick Start](#-quick-start)
-- [Prerequisites](#prerequisites)
-- [Configuration](#-configuration)
-- [Deployment](#-deployment)
-- [First Login](#-first-login)
-- [Release Channels](#-release-channels)
-- [Reverse Proxy Setup](#-reverse-proxy-setup)
-- [External Media Library](#external-media-library)
-- [Maintenance](#-maintenance)
-- [Troubleshooting](#-troubleshooting)
-
-## 🚀 Quick Start
-
-### Option 1: Automated Setup Script (Easiest)
-
-For the simplest installation, use our unified setup script:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/the-luap/picpeak/main/scripts/picpeak-setup.sh -o picpeak-setup.sh && \
-chmod +x picpeak-setup.sh && \
-sudo ./picpeak-setup.sh
-```
-
-This script handles Docker/Native installation choice, OS detection, dependencies, database setup, and optional SSL.
-
-👉 **See [SIMPLE_SETUP.md](./SIMPLE_SETUP.md) for detailed instructions.**
-
-### Option 2: Docker with Pre-built Images (Recommended)
-
-```bash
-# Clone repository for configuration files
-git clone https://github.com/the-luap/picpeak.git
-cd picpeak
-
-# Copy and configure environment
-cp .env.example .env
-nano .env  # Edit with your values
-
-# Create required directories
-mkdir -p events/active events/archived data logs backup storage
-chmod -R 755 events data logs backup storage
-
-# Deploy using pre-built images
-docker compose -f docker-compose.production.yml up -d
-
-# Check logs
-docker compose -f docker-compose.production.yml logs -f
-```
-
-**Available image tags:**
-| Channel | Tags | Description |
-|---------|------|-------------|
-| Stable | `stable`, `latest`, `v2.3.0` | Production-ready releases |
-| Beta | `beta`, `v2.3.0-beta.1` | Early access to new features |
-| Branch | `main`, `beta` | Latest from each branch |
-
-To select a channel, set `PICPEAK_CHANNEL` in your `.env` file (see [Release Channels](#release-channels) section)
-
-### Option 3: Build from Source
-
-```bash
-git clone https://github.com/the-luap/picpeak.git
-cd picpeak
-cp .env.example .env
-nano .env  # Edit with your values
-
-mkdir -p events/active events/archived data logs backup storage
-chmod -R 755 events data logs backup storage
-
-docker compose build
-docker compose up -d
-```
-
-## Prerequisites
-
-- Docker and Docker Compose installed
-- Domain name (for production)
-- SMTP server credentials for emails
-- At least 2GB RAM and 20GB storage
-
-## 🔧 Configuration
-
-### Essential Environment Variables
-
-Generate secure values:
-```bash
-# JWT Secret
-openssl rand -base64 64
-
-# Database Password (avoid $ character - see warning below)
-openssl rand -base64 32 | tr -d '$'
-
-# Redis Password (avoid $ character - see warning below)
-openssl rand -base64 32 | tr -d '$'
-```
-
-⚠️ **PASSWORD WARNING**: Docker Compose interprets `$` as variable substitution. Either:
-- Avoid `$` in passwords (recommended - use the commands above)
-- Escape `$` as `$$` (e.g., `Pass$$word` instead of `Pass$word`)
-- Quote the entire value: `DB_PASSWORD='Pass$word'` (less reliable)
-
-### Public Landing Page
-
-- `npm run migrate` now seeds three general settings: `general_public_site_enabled`, `general_public_site_html`, and `general_public_site_custom_css` so existing installs stay disabled by default.
-- Configure the feature from **Admin → CMS Pages**. The landing page panel exposes the toggle, HTML editor, optional CSS overrides, preview, and a reset-to-default action.
-- All HTML and CSS submitted through the UI is sanitized server-side. Scripts, inline event handlers, disallowed attributes, `@import` rules, and `javascript:` URLs are stripped before content is cached or rendered.
-- Resetting via the UI (or calling `POST /api/admin/settings/public-site/reset`) restores the bundled template and clears custom CSS.
-- The landing page response is cached in-memory. Override the default 60s cache window by setting `PUBLIC_SITE_CACHE_TTL_MS` (milliseconds) in your environment if you need faster cache busting.
-- When the toggle is off PicPeak continues to serve the SPA/login redirect at `/`, preserving legacy behaviour until you explicitly enable the feature.
-
-### Backend Configuration (.env)
-Update `.env` with:
-- `JWT_SECRET` - Authentication secret (REQUIRED - generate a secure random value)
-- `DB_PASSWORD` - PostgreSQL password
-- `REDIS_PASSWORD` - Redis password
-- `SMTP_*` - Email configuration
-- **URL Configuration** (for backend CORS):
-  - `FRONTEND_URL` - Frontend origin (use full URL with scheme, no trailing slash)
-    - Example (Docker): `http://localhost:3000`
-- `ADMIN_URL` - Admin origin (same as `FRONTEND_URL` for Docker; full URL, no trailing slash)
-  - Example (Docker): `http://localhost:3000`
-  
-  Notes:
-  - Do not include trailing `/` (e.g., use `http://host:3000`, not `http://host:3000/`).
-  - Always include the scheme (`http://` or `https://`).
-  - The backend compares origins strictly for CORS; malformed values will cause login requests to fail with 500.
-
-#### Authentication Security
-- Configure login attempt thresholds from **Admin → Settings → Security**. Defaults are 5 failed attempts per IP within 15 minutes, resulting in a 30 minute lockout.
-
-#### External Database Example
-To use an external PostgreSQL instead of the bundled container, set the following in `.env` and ensure the `postgres` service is disabled or removed:
-
-```env
-DB_HOST=db.example.com
-DB_PORT=5432
-DB_USER=picpeak
-DB_PASSWORD=change_me
-DB_NAME=picpeak_prod
-```
-
-Compose uses these values via `env_file: .env`. The backend service also defaults `DB_HOST=${DB_HOST:-postgres}` so if you don’t set `DB_HOST` it will use the bundled `postgres` container.
-
-### Frontend Configuration (frontend/.env)
-Create `frontend/.env` from `frontend/.env.example`:
-```bash
-cp frontend/.env.example frontend/.env
-```
-
-Update `frontend/.env` with:
-- `VITE_API_URL` - Backend API URL
-  - Docker (pre-built images) and production behind reverse proxy: `/api` (recommended; avoids CORS and matches the frontend Nginx proxy in the image)
-  - Local dev (Vite): `http://localhost:3001` or `/api` if proxying through a dev proxy
-
-Note: When using pre-built frontend images, runtime container env does not change the already-built JS. Prefer the default `/api` and let the frontend Nginx proxy forward to the backend.
-
-⚠️ **IMPORTANT PORT CONFIGURATION**: 
-- The frontend runs on port **3000** in Docker (exposed via nginx)
-- The backend API runs on port **3001**
-- The frontend `.env` file MUST point to the correct backend port (3001)
-- Default `.env.example` is configured for Docker deployment
-
-### Email Configuration Examples
-
-#### Gmail
-```env
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=your-email@gmail.com
-SMTP_PASS=your-app-specific-password
-```
-
-#### SendGrid
-```env
-SMTP_HOST=smtp.sendgrid.net
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=apikey
-SMTP_PASS=your-sendgrid-api-key
-```
-
-## 📦 Deployment
-
-### Using Pre-built Images (Fastest)
-
-```bash
-# Pull latest images from GitHub Container Registry
-docker pull ghcr.io/the-luap/picpeak/backend:latest
-docker pull ghcr.io/the-luap/picpeak/frontend:latest
-
-# Start services using production compose file
-docker compose -f docker-compose.production.yml up -d
-
-# View running containers
-docker compose ps
-```
-
-### Building from Source (For Customization)
-
-```bash
-# Build images locally
-docker compose build
-
-# Or build with no cache for clean build
-docker compose build --no-cache
-
-# Start all services
-docker compose up -d
-
-# View running containers
-docker compose ps
-```
-
-### Access Points
-
-By default, services are exposed on:
-- Frontend (UI + Admin): http://localhost:3000 (admin at `/admin`)
-- Backend/API: http://localhost:3001 (API only; no UI routes)
-- PostgreSQL: localhost:5432 (if needed)
-- Redis: localhost:6379 (if needed)
-
-### Initial Admin Setup
-
-When deploying for the first time, an admin account is automatically created with a secure, randomly generated password. This password is displayed in the Docker logs during initialization and **must be changed** on first login.
-
-#### Finding the Auto-Generated Admin Password
-
-The admin password is automatically generated during the first startup and displayed in the backend container logs. Here's how to find it:
-
-**Option 1: Search Docker logs for admin password** (recommended)
-```bash
-# Find the auto-generated admin password in logs
-docker compose logs backend | grep "Admin password"
-```
-
-You should see output like:
-```
-✅ Admin password generated: BraveTiger6231!
-```
-
-**Option 2: View the complete initialization logs**
-```bash
-# View the complete admin setup logs
-docker compose logs backend | grep -A 10 "Admin user created"
-```
-
-**Option 3: Check the saved credentials file**
-```bash
-# The password is also saved in the backend container
-docker exec picpeak-backend cat data/ADMIN_CREDENTIALS.txt
-```
-
-**Option 4: Use the helper script**
-```bash
-# Show current admin username and email (password is hidden)
-docker exec picpeak-backend node scripts/show-admin-credentials.js
-
-# Reset the admin password to a new random password (displays new password in console)
-docker exec picpeak-backend node scripts/show-admin-credentials.js --reset
-```
-
-> **Note:** When using `--reset`, the new password will be displayed in the console output. Save it immediately - it will not be shown again!
-
-#### Important Security Notes
-
-- **Login requires the email address**, not username
-- When resetting password, the new password is displayed once in the console - save it immediately
-- **Password change is MANDATORY** on first login - the system will force you to change it
-- If you lose the password before first login, use the `--reset` option to generate a new one
-- New password requirements: minimum 12 characters, mixed case, numbers, and special characters
-
-## 🔐 First Login
-
-After deployment, you must complete the first login process which includes mandatory password change for security.
-
-### Step 1: Locate Your Admin Password
-
-1. **Find the auto-generated password** from the credentials file:
-   ```bash
-   # Docker deployment
-   docker compose exec backend cat /app/data/ADMIN_CREDENTIALS.txt
-   
-   # Or directly from the host (if you have access)
-   cat data/ADMIN_CREDENTIALS.txt
-   ```
-
-2. **Note the admin email** (default: `admin@example.com` unless customized)
-
-### Step 2: Access Admin Panel
-
-1. Navigate to your frontend domain and open the admin section:
-   - `http://your-domain.com/admin` (behind reverse proxy)
-   - `http://localhost:3000/admin` (Docker local)
-   
-   The backend at `:3001` serves API only and does not serve the admin UI.
-2. Login using:
-   - **Email**: `admin@example.com` (or your custom admin email)
-   - **Password**: The auto-generated password from the logs
-
-### Step 3: Mandatory Password Change
-
-Upon first login, the system will **automatically redirect** you to change your password:
-
-1. **You cannot skip this step** - it's enforced for security
-2. Enter the current auto-generated password
-3. Create a new secure password meeting these requirements:
-   - Minimum 12 characters
-   - At least one uppercase letter
-   - At least one lowercase letter
-   - At least one number
-   - At least one special character (!@#$%^&*)
-
-### Security Best Practices for New Password
-
-- **Use a unique password** not used elsewhere
-- **Consider a password manager** for generation and storage
-- **Include mixed characters**: `MySecureP@ssw0rd2024!`
-- **Avoid personal information** (names, dates, etc.)
-- **Save securely** - you cannot recover this password easily
-
-### If You Lose Access
-
-If you lose your admin credentials after the first login, you'll need to manually reset the password in the database or create a new admin user through the database.
-
-**Note**: The credentials file (`ADMIN_CREDENTIALS.txt`) is only created during initial deployment and contains the first admin password. After changing the password, this file becomes outdated but is kept for reference. If you need to regenerate the password and file during a reinstall, re-run the installer with the `--force-admin-password-reset` flag:
-
-```bash
-# Native reinstall example
-sudo ./picpeak-setup.sh --native --force-admin-password-reset
-
-# Docker reinstall example
-sudo ./picpeak-setup.sh --docker --force-admin-password-reset
-```
-
-The flag calls `scripts/reset-admin-password.js` in non-interactive mode, writes a fresh random password into `data/ADMIN_CREDENTIALS.txt`, and prints the new credentials at the end of the installer run.
-
-#### Configuring Admin Email
-
-By default, the admin email is `admin@example.com`. To use a different email address, set it in your `.env` file before first deployment:
-
-```env
-# .env
-ADMIN_EMAIL=your-email@yourdomain.com
-```
-
-**Note**: This only works on first deployment. To change the admin email after deployment, you'll need to update it in the database or create a new admin user through the admin panel.
-
-## 🔄 Release Channels
-
-PicPeak offers two release channels for different needs:
-
-### 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`
-
-### Configuring Your Channel
-
-Set the `PICPEAK_CHANNEL` environment variable in your `.env` file:
-
-```bash
-# For stable releases (default)
-PICPEAK_CHANNEL=stable
-
-# For beta releases
-PICPEAK_CHANNEL=beta
-
-# For a specific version
-PICPEAK_CHANNEL=v2.3.0
-```
-
-The `docker-compose.production.yml` uses this variable for both backend and frontend images:
-```yaml
-image: ghcr.io/the-luap/picpeak/backend:${PICPEAK_CHANNEL:-stable}
-```
-
-### Switching Channels
-
-To switch between channels:
-
-```bash
-# Edit your .env file
-nano .env
-# Change PICPEAK_CHANNEL=stable to PICPEAK_CHANNEL=beta (or vice versa)
-
-# Pull the new images and restart
-docker compose -f docker-compose.production.yml pull
-docker compose -f docker-compose.production.yml up -d
-```
-
-### Update Notifications
-
-The admin dashboard automatically notifies you when updates are available for your channel. This feature:
-- Checks GitHub releases hourly (cached to avoid rate limits)
-- Shows updates relevant to your current channel (stable or beta)
-- Can be disabled by setting `UPDATE_CHECK_ENABLED=false` in your `.env`
-
-## 🔒 Reverse Proxy Setup
-
-For production deployments, you should use a reverse proxy for SSL/HTTPS. The application exposes ports directly, allowing you to use any reverse proxy solution.
-
-### Routing Schema
-
-PicPeak consists of two services that need to be routed correctly:
-
-| Path | Service | Port | Description |
-|------|---------|------|-------------|
-| `/api/*` | Backend | 3001 | All API endpoints |
-| `/photos/*` | Backend | 3001 | Protected photo files |
-| `/thumbnails/*` | Backend | 3001 | Protected thumbnail files |
-| `/uploads/*` | Backend | 3001 | Upload files |
-| `/*` (everything else) | Frontend | 3000 | React SPA (including `/admin/*`, `/gallery/*`) |
-
-> **Important:** The `/admin/*` routes are served by the frontend (React SPA), NOT the backend. The backend only handles `/api/admin/*` requests.
-
-### Option 1: Nginx
-
-Install nginx and create `/etc/nginx/sites-available/picpeak`:
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-    return 301 https://$server_name$request_uri;
-}
-
-server {
-    listen 443 ssl http2;
-    server_name your-domain.com;
-
-    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
-
-    # Backend: API endpoints
-    location /api/ {
-        proxy_pass http://localhost:3001;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Backend: Protected media files
-    location ~ ^/(photos|thumbnails|uploads)/ {
-        proxy_pass http://localhost:3001;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # Frontend: Everything else (React SPA)
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-Enable the site:
-```bash
-sudo ln -s /etc/nginx/sites-available/picpeak /etc/nginx/sites-enabled/
-sudo nginx -t
-sudo systemctl reload nginx
-```
-
-### Option 2: Traefik
-
-Add labels to `docker-compose.override.yml`:
-
-```yaml
-version: '3.8'
-
-services:
-  frontend:
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.picpeak.rule=Host(`your-domain.com`)"
-      - "traefik.http.routers.picpeak.entrypoints=websecure"
-      - "traefik.http.routers.picpeak.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak.loadbalancer.server.port=80"
-
-  backend:
-    labels:
-      - "traefik.enable=true"
-      # API endpoints
-      - "traefik.http.routers.picpeak-api.rule=Host(`your-domain.com`) && PathPrefix(`/api`)"
-      - "traefik.http.routers.picpeak-api.entrypoints=websecure"
-      - "traefik.http.routers.picpeak-api.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak-api.loadbalancer.server.port=3001"
-      # Protected media files
-      - "traefik.http.routers.picpeak-media.rule=Host(`your-domain.com`) && (PathPrefix(`/photos`) || PathPrefix(`/thumbnails`) || PathPrefix(`/uploads`))"
-      - "traefik.http.routers.picpeak-media.entrypoints=websecure"
-      - "traefik.http.routers.picpeak-media.tls.certresolver=letsencrypt"
-      - "traefik.http.services.picpeak-media.loadbalancer.server.port=3001"
-```
-
-### Option 3: Caddy
-
-Create a `Caddyfile`:
-
-```caddyfile
-your-domain.com {
-    # Backend: API endpoints
-    handle /api/* {
-        reverse_proxy localhost:3001
-    }
-
-    # Backend: Protected media files
-    handle /photos/* {
-        reverse_proxy localhost:3001
-    }
-
-    handle /thumbnails/* {
-        reverse_proxy localhost:3001
-    }
-
-    handle /uploads/* {
-        reverse_proxy localhost:3001
-    }
-
-    # Frontend: Everything else (React SPA including /admin/*, /gallery/*)
-    handle {
-        reverse_proxy localhost:3000
-    }
-}
-```
-
-### SSL Certificates
-
-For any reverse proxy, you can use Let's Encrypt:
-
-```bash
-# With Certbot
-sudo certbot certonly --webroot -w /var/www/certbot -d your-domain.com
-
-# Or use your reverse proxy's built-in ACME support
-```
-
-## 🔧 Maintenance
-
-### Viewing Logs
-
-```bash
-# All services
-docker compose logs -f
-
-# Specific service
-docker compose logs -f backend
-docker compose logs -f frontend
-```
-
-### Backup
-
-#### Manual Backup
-```bash
-# Database backup
-docker exec picpeak-postgres pg_dump -U picpeak picpeak_prod > backup/db_$(date +%Y%m%d_%H%M%S).sql
-
-# Files backup
-tar -czf backup/photos_$(date +%Y%m%d_%H%M%S).tar.gz events/
-```
-
-#### Automated Backup
-The application includes a built-in backup service. Configure it in the admin panel:
-1. Login to admin panel
-2. Go to Settings → Backup
-3. Configure destination and schedule
-4. Enable backup service
-
-### Updates
-
-#### Method 1: Using Pre-built Images (Recommended)
-
-```bash
-# Pull latest changes (for configuration updates)
-git pull
-
-# Pull latest images from GitHub Container Registry
-docker compose -f docker-compose.production.yml pull
-
-# Restart with new images
-docker compose -f docker-compose.production.yml down
-docker compose -f docker-compose.production.yml up -d
-
-# Verify services are healthy
-docker compose -f docker-compose.production.yml ps
-```
-
-#### Method 2: Building from Source
-
-```bash
-# Pull latest changes
-git pull
-
-# Rebuild and restart
-docker compose down
-docker compose build --no-cache
-docker compose up -d
-
-# Verify services are healthy
-docker compose ps
-```
-
-#### Specific Version or Channel Updates
-
-To use a specific version or switch channels, update your `.env` file:
-
-```bash
-# Edit .env to change the channel or pin to a specific version
-nano .env
-
-# Options for PICPEAK_CHANNEL:
-# - stable    (recommended, production-ready)
-# - beta      (early access to new features)
-# - v2.3.0    (pin to specific stable version)
-# - v2.3.0-beta.1  (pin to specific beta version)
-
-# Then pull and restart
-docker compose -f docker-compose.production.yml pull
-docker compose -f docker-compose.production.yml up -d
-```
-
-The admin dashboard will notify you when updates are available for your configured channel.
-
-### Database Migrations
-
-Migrations run automatically on startup, but you can run them manually:
-
-```bash
-docker exec picpeak-backend npm run migrate
-```
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-#### 502 Bad Gateway / Login Failures
-**This is the most common deployment issue!** Usually caused by misconfigured URLs or network problems:
-
-1. **CORS Configuration Errors**:
-   ```bash
-   # WRONG - Missing port will cause CORS errors
-   FRONTEND_URL=http://10.0.252.12
-   
-   # CORRECT - Include the port you're accessing from
-   FRONTEND_URL=http://10.0.252.12:3000
-   ```
-   
-   The backend validates Origin headers against `FRONTEND_URL` for CORS. If they don't match exactly, you'll get 500 errors on login.
-
-2. **After Container Restarts**:
-   - Nginx may have cached old container IPs
-   - Solution: `docker restart picpeak-frontend`
-   - Always wait 30-60 seconds for health checks
-
-3. **Backend Not Starting After Migrations**:
-   - The logs may only show migrations completed
-   - Check if server is actually running: `docker exec picpeak-backend ps aux | grep node`
-   - Should see `node server.js` process
-
-4. **Login After Fresh Install**:
-   - Check backend logs for auto-generated admin password: `docker compose logs backend | grep "Admin password"`
-   - Email: `admin@example.com` (or your custom admin email from .env)
-   - Password: Auto-generated and shown in logs (e.g., `BraveTiger6231!`)
-   - Remember: Password MUST be changed on first login
-
-5. **Complete Fix Sequence**:
-   ```bash
-   # 1. Fix your .env file URLs
-   # 2. Full restart
-   docker-compose down
-   docker-compose up -d
-   
-   # 3. Wait for healthy status
-   sleep 60
-   docker ps  # All should show (healthy)
-   
-   # 4. Test backend directly
-   curl http://localhost:3001/health
-   
-   # 5. Test through frontend
-   curl http://localhost:3000/api/public/settings
-   ```
-
-#### Port Already in Use
-```bash
-# Check what's using the port
-sudo lsof -i :3000
-sudo lsof -i :3001
-
-# Change ports in .env
-FRONTEND_PORT=3002
-BACKEND_PORT=3003
-```
-
-#### Docker Compose Variable Substitution Errors
-If you see warnings like:
-```
-WARN[0000] The "fgbf" variable is not set. Defaulting to a blank string.
-```
-
-This means your password contains `$` which Docker Compose interprets as a variable. Solutions:
-1. **Best**: Generate passwords without `$`: `openssl rand -base64 32 | tr -d '$'`
-2. **Alternative**: Escape `$` as `$$` in your .env file
-3. **Example**: `DB_PASSWORD=Pass@#$$fgbf` instead of `DB_PASSWORD=Pass@#$fgbf`
-
-#### Permission Errors
-```bash
-# Fix ownership
-sudo chown -R 1000:1000 events data logs backup storage
-chmod -R 755 events data logs backup storage
-```
-
-#### Database Connection Issues
-```bash
-# Check if database is running
-docker compose ps
-docker compose logs postgres
-
-# Test connection
-docker exec picpeak-postgres pg_isready
-```
-
-#### Email Not Sending
-- Verify SMTP settings in .env
-- Check email queue: `docker exec picpeak-backend psql -U picpeak -d picpeak_prod -c "SELECT * FROM email_queue ORDER BY created_at DESC LIMIT 10;"`
-- For Gmail, use app-specific password
-- Check logs: `docker compose logs backend | grep email`
-
-### Health Checks
-
-```bash
-# Backend health
-curl http://localhost:3001/api/health
-
-# Frontend health
-curl http://localhost:3000
-
-# Database health
-docker exec picpeak-postgres pg_isready
-```
-
-### Useful Commands
-
-```bash
-# Enter backend container
-docker exec -it picpeak-backend sh
-
-# Enter database
-docker exec -it picpeak-postgres psql -U picpeak picpeak_prod
-
-# Reset admin password
-docker exec picpeak-backend node scripts/show-admin-credentials.js --reset
-
-# Check disk usage
-df -h
-du -sh events/ storage/ backup/
-
-# View running processes
-docker compose top
-```
-
-## Security Recommendations
-
-1. **Use HTTPS**: Always use a reverse proxy with SSL in production
-2. **Firewall**: Only expose necessary ports (80, 443)
-3. **Secure passwords**: Use strong, unique passwords for all services
-4. **Regular updates**: Keep Docker images and system packages updated
-5. **Backup strategy**: Set up automated backups and test restoration
-6. **Monitor logs**: Regularly check logs for suspicious activity
-7. **Rate limiting**: The app includes built-in rate limiting, configure as needed
-
-## Support
-
-For issues and questions:
-- Check logs first: `docker compose logs`
-- Review documentation in the repository
-- Check existing issues on GitHub
-- Create a new issue with:
-  - Error messages
-  - Log output
-  - Environment details (without secrets)
-  - Steps to reproduce

README.md

@@ -7,12 +7,28 @@
   [![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)
 </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 Gallery Preview](docs/screenshot-gallery.png)
 
+## 🎮 Live Demo
+
+Try PicPeak without installing anything:
+
+| | |
+|---|---|
+| **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!` |
+
+> The demo resets periodically. Uploaded content may be removed without notice.
+
 ## 🌟 Why Choose PicPeak?
 
 Unlike expensive SaaS solutions, PicPeak gives you:
@@ -68,9 +84,9 @@ cp .env.example .env
 nano .env
 
 # Start with Docker Compose
-docker-compose up -d
+docker compose up -d
 
-# Access at http://localhost:3005
+# Access at http://localhost:3000
 ```
 
 Note on Docker file permissions (PUID/PGID)
@@ -113,8 +129,8 @@ PICPEAK_CHANNEL=v2.3.0
 Then update your containers:
 
 ```bash
-docker-compose -f docker-compose.production.yml pull
-docker-compose -f docker-compose.production.yml up -d
+docker compose -f docker-compose.production.yml pull
+docker compose -f docker-compose.production.yml up -d
 ```
 
 ### Update Notifications
@@ -127,10 +143,17 @@ UPDATE_CHECK_ENABLED=false
 
 ## 📖 Documentation
 
-- 📘 [**Deployment Guide**](DEPLOYMENT_GUIDE.md) - Detailed installation instructions
-  - Includes the new [External Media Library](DEPLOYMENT_GUIDE.md#external-media-library) reference mode
-- 📚 [**Admin API (OpenAPI)**](docs/picpeak-admin-api.openapi.yaml) - Machine-readable documentation for event automation endpoints
-- 🛠️ [**Admin API Quickstart**](docs/admin-api-quickstart.md) - Step-by-step authentication and testing guide for the documented endpoints
+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:
+
+- 🚀 [**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
+- 💾 [**Backup & Restore**](https://docs.picpeak.app/guides/backup-restore) - Local, S3, rsync destinations
+- 🔌 [**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
@@ -161,10 +184,111 @@ Perfect for:
 
 - **Backend**: Node.js, Express, SQLite/PostgreSQL
 - **Frontend**: React, Tailwind CSS, Framer Motion
-- **Storage**: File-based with automatic archiving
+- **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 |
+|---|---|
+| `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) |
+
+### 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
@@ -297,6 +421,18 @@ These features are currently in beta testing and may have limited functionality
 
 **Status Legend:** ✅ Implemented | 🚧 In Progress | 🔄 Open | 📋 Planned
 
+## ☕ 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.
+
 ## 🙏 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.
@@ -318,7 +454,7 @@ PicPeak is released under the [MIT License](LICENSE). Use it freely for personal
 ## 🚀 Ready to Get Started?
 
 1. ⭐ **Star this repository** to show your support
-2. 📖 Read the [Deployment Guide](DEPLOYMENT_GUIDE.md)
+2. 📖 Read the [docs at docs.picpeak.app](https://docs.picpeak.app)
 3. 🐛 Report issues or request features
 4. 🤝 Join our community and contribute!
 
@@ -327,7 +463,9 @@ PicPeak is released under the [MIT License](LICENSE). Use it freely for personal
 <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/the-luap/picpeak">GitHub</a> •
-  <a href="DEPLOYMENT_GUIDE.md">Documentation</a> •
+  <a href="https://docs.picpeak.app">Documentation</a> •
   <a href="https://github.com/the-luap/picpeak/issues">Support</a>
 </p>

SECURITY.md

@@ -6,8 +6,8 @@ We release patches for security vulnerabilities. Currently supported versions:
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.x.x   | :white_check_mark: |
-| < 1.0   | :x:                |
+| 2.x.x   | :white_check_mark: |
+| < 2.0   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -15,9 +15,9 @@ We take the security of PicPeak seriously. If you have discovered a security vul
 
 ### 1. **Do NOT create a public GitHub issue**
 
-### 2. Report the vulnerability by:
-- Opening a [security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
-- Mark it clearly as "SECURITY" in the title
+### 2. Report the vulnerability privately by:
+- **Preferred:** Use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new)
+- **Alternative:** Email us at **info@picpeak.app** with the details
 - Include:
   - Description of the vulnerability
   - Steps to reproduce
@@ -82,7 +82,7 @@ We believe in responsible disclosure. Once a vulnerability is fixed:
 
 ## Contact
 
-- Security issues: [Create a security issue](https://github.com/the-luap/picpeak/issues/new?labels=security) on GitHub
+- Security issues: Email **info@picpeak.app** or use [GitHub Private Vulnerability Reporting](https://github.com/the-luap/picpeak/security/advisories/new)
 - General support: [GitHub Issues](https://github.com/the-luap/picpeak/issues)
 
 Thank you for helping keep PicPeak and its users safe!

SIMPLE_SETUP.md

@@ -219,29 +219,36 @@ location ~ ^/(photos|thumbnails|uploads) {
 
 ### Creating a Gallery
 
-#### Method 1: Via Admin Panel (Recommended)
-1. Login to admin panel
+#### Via Admin Panel
+1. Login to admin panel at `/admin`
 2. Click "Create New Event"
-3. Configure settings and upload photos
+3. Configure settings (name, date, password, customer email)
+4. Upload photos via drag & drop in the Photos tab
+5. Publish the gallery when ready
+
+#### Adding Photos via File System
+
+> **Important:** You must first create the event in the admin panel. The file watcher only detects new photos for events that already exist in the database. You cannot create a gallery by copying files alone.
+
+Once an event exists, you can add photos by copying them into the event's folder. PicPeak's built-in file watcher will automatically detect the new files, create database records, and generate thumbnails.
 
-#### Method 2: File System
 ```bash
-# Docker installation
-mkdir -p ~/picpeak/storage/events/active/wedding-smith-2024
-cp /path/to/photos/* ~/picpeak/storage/events/active/wedding-smith-2024/
+# Docker installation — copy photos into an existing event's folder
+cp /path/to/photos/*.jpg ~/picpeak/storage/events/active/<event-slug>/
 
 # Native installation
-sudo mkdir -p /opt/picpeak/events/active/wedding-smith-2024
-sudo cp /path/to/photos/* /opt/picpeak/events/active/wedding-smith-2024/
-sudo chown -R picpeak:picpeak /opt/picpeak/events/active/wedding-smith-2024
+sudo cp /path/to/photos/*.jpg /opt/picpeak/events/active/<event-slug>/
+sudo chown -R picpeak:picpeak /opt/picpeak/events/active/<event-slug>
 ```
 
+The event slug is visible in the admin panel URL or share link (e.g. `wedding-smith-2024`). Supported formats: `.jpg`, `.jpeg`, `.png`, `.webp`. The file watcher has a 2-second stability delay before processing new files.
+
 ### Gallery Structure
 ```
-wedding-smith-2024/
-├── collages/        # Group photos
-├── individual/      # Individual photos
-└── thumbnails/      # Auto-generated thumbnails
+<event-slug>/
+├── collages/        # Group photos (optional subfolder)
+├── individual/      # Individual photos (optional subfolder)
+└── photo.jpg        # Photos at root level also work
 ```
 
 ## 🔧 Service Management
@@ -461,8 +468,8 @@ sudo -u picpeak node scripts/reset-admin-password.js
    - Installation: `/tmp/picpeak-setup-*.log`
 
 2. **Documentation:**
-   - [Full Documentation](https://github.com/the-luap/picpeak)
-   - [Deployment Guide](./DEPLOYMENT_GUIDE.md)
+   - [Full Documentation](https://docs.picpeak.app)
+   - [Deployment Guide](https://docs.picpeak.app/deployment)
 
 3. **Support:**
    - [GitHub Issues](https://github.com/the-luap/picpeak/issues)

backend/.env.example

@@ -9,11 +9,44 @@ PORT=3001
 # Generate with: openssl rand -base64 32
 JWT_SECRET=your-very-secure-jwt-secret-at-least-32-characters-long-example123456
 
+# Auth cookie Secure flag
+#   unset  - default: follows NODE_ENV (production=true, dev=false)
+#   true   - always set Secure (HTTPS-only cookies; breaks plain-HTTP access)
+#   false  - never set Secure (allows HTTP; cookies not protected on HTTPS)
+#   auto   - decide per request: Secure on HTTPS, not on HTTP
+#
+# Use COOKIE_SECURE=auto if your deployment is reachable over both HTTPS
+# (via a reverse proxy like Nginx Proxy Manager, Traefik, Caddy) AND plain
+# HTTP (e.g. LAN access at http://192.168.x.x:3001). The backend reads
+# req.secure from Express, which respects the X-Forwarded-Proto header
+# when the proxy is in the trust list.
+#
+# Requirements for auto mode:
+#   1. Your reverse proxy MUST send X-Forwarded-Proto: https on HTTPS
+#      requests. Standard configs for NPM/Traefik/Caddy do this by default.
+#   2. The proxy must be on a trusted IP range. By default PicPeak trusts
+#      loopback and private networks (127.0.0.1, 10.x, 172.16-31.x,
+#      192.168.x, link-local). Proxies outside those ranges need custom
+#      trust proxy configuration.
+# COOKIE_SECURE=auto
+
+# Cookie SameSite attribute (Lax | Strict | None). Default: Lax
+# COOKIE_SAMESITE=Lax
+
+# Cookie Domain — set this if serving auth cookies across subdomains.
+# Leave unset for same-origin setups.
+# COOKIE_DOMAIN=.example.com
+
 # URLs (adjust for your domain)
 ADMIN_URL=https://photos.example.com
 FRONTEND_URL=https://photos.example.com
 BACKEND_URL=https://photos.example.com  # Or https://api.photos.example.com if separate
 
+# API URL for email assets (logos, images in emails)
+# This must be the publicly accessible URL where recipients can load images
+# If not set, defaults to http://localhost:3001 which will break images in production emails
+API_URL=https://photos.example.com/api
+
 # Database Configuration
 DATABASE_CLIENT=pg
 DB_HOST=localhost
@@ -39,6 +72,7 @@ SMTP_PASS=your-sendgrid-api-key
 EMAIL_FROM=noreply@example.com
 
 # Storage Paths
+# IMPORTANT: STORAGE_PATH must be set to avoid file path resolution issues
 # Docker deployment:
 STORAGE_PATH=/app/storage
 EVENTS_PATH=/app/storage/events

backend/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:20-alpine AS builder
+FROM node:22-alpine AS builder
 
 # Add build arguments
 ARG CACHEBUST=1
@@ -11,10 +11,6 @@ LABEL org.opencontainers.image.source="https://github.com/the-luap/picpeak"
 LABEL org.opencontainers.image.description="PicPeak Backend Service"
 LABEL org.opencontainers.image.licenses="MIT"
 
-# Upgrade npm to fix glob CVE-2025-64756 vulnerability
-# Pin to npm 10.x which supports --omit=dev flag
-RUN npm install -g npm@10
-
 WORKDIR /app
 
 # Copy package files
@@ -27,15 +23,15 @@ RUN npm ci --omit=dev
 COPY . .
 
 # Production stage
-FROM node:20-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 
-# Upgrade all packages to fix security vulnerabilities (BusyBox CVEs)
+# Upgrade all packages to fix security vulnerabilities (OpenSSL, libexpat, BusyBox CVEs)
 RUN apk upgrade --no-cache
 
-# Upgrade npm to fix glob CVE-2025-64756 vulnerability
-# Pin to npm 10.x which supports --omit=dev flag
+# Upgrade npm to fix tar, minimatch, brace-expansion CVEs in npm's own deps
+# Pin to 10.x to stay compatible with Node 22 Alpine (npm 11.x has dependency issues)
 RUN npm install -g npm@10
 
 # Install dumb-init for proper signal handling and postgresql-client for database checks

backend/__tests__/integration/backup-s3.test.js

@@ -7,12 +7,15 @@ const crypto = require('crypto');
 // Load services
 const backupService = require('../../src/services/backupService');
 const S3StorageAdapter = require('../../src/services/storage/s3Storage');
-const { db, initialize: initDb } = require('../../src/database/db');
+const { db, initializeDatabase: initDb } = require('../../src/database/db');
 const logger = require('../../src/utils/logger');
 
 // Test configuration
+// Defaults match the dev MinIO container in docker-compose.dev.yml (port 7104).
+// Override via TEST_S3_ENDPOINT / TEST_S3_ACCESS_KEY / TEST_S3_SECRET_KEY when running
+// against a different S3 endpoint (CI, hosted MinIO, real AWS, etc.).
 const TEST_CONFIG = {
-  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:9000',
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
   accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
   secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
   bucket: 'test-backup-bucket-' + Date.now(),
@@ -56,9 +59,17 @@ describe('S3 Backup Integration Tests', () => {
       }
     }
 
-    // Initialize database
-    await initDb();
-    await db.migrate.latest();
+    // Schema is expected to already be applied by `npm run migrate` against
+    // the dev database. db.migrate.latest() can't be used here because
+    // PicPeak's custom run-migrations.js tracks state in the `migrations`
+    // table (not knex's `knex_migrations`), so knex would try to re-apply
+    // every migration and crash on duplicate-table errors.
+    const ok = await db.schema.hasTable('events')
+      && await db.schema.hasTable('app_settings')
+      && await db.schema.hasTable('backup_runs');
+    if (!ok) {
+      throw new Error('Required tables missing — run `npm run migrate` against the dev DB first.');
+    }
 
     // Create test storage directory
     testStoragePath = path.join(__dirname, '../fixtures/test-storage');
@@ -69,10 +80,12 @@ describe('S3 Backup Integration Tests', () => {
     await setupTestData();
 
     // Mock logger to reduce noise
-    logger.info = jest.fn();
-    logger.debug = jest.fn();
-    logger.warn = jest.fn();
-    logger.error = jest.fn();
+    if (process.env.UNMOCK_LOGGER !== 'true') {
+      logger.info = jest.fn();
+      logger.debug = jest.fn();
+      logger.warn = jest.fn();
+      logger.error = jest.fn();
+    }
   });
 
   afterAll(async () => {
@@ -165,8 +178,9 @@ describe('S3 Backup Integration Tests', () => {
         .first();
 
       expect(backupRun.status).toBe('completed');
-      expect(backupRun.files_backed_up).toBeGreaterThan(0);
-      expect(backupRun.total_size_bytes).toBeGreaterThan(0);
+      // pg driver returns bigint columns as strings; coerce for the size assertion.
+      expect(Number(backupRun.files_backed_up)).toBeGreaterThan(0);
+      expect(Number(backupRun.total_size_bytes)).toBeGreaterThan(0);
 
       // Verify files in S3
       const s3Objects = await listS3Objects();
@@ -269,13 +283,16 @@ describe('S3 Backup Integration Tests', () => {
         .first();
 
       expect(secondRun.id).not.toBe(firstRun.id);
-      expect(secondRun.files_backed_up).toBe(1); // Only modified file
+      expect(Number(secondRun.files_backed_up)).toBe(1); // Only modified file
 
-      // Check manifest indicates incremental
+      // Check manifest indicates incremental. The current manifest schema
+      // groups counts under `incremental.changes.*` (added/modified/deleted/
+      // unchanged + size_difference) — see backupManifest.generateIncrementalManifest.
       if (secondRun.manifest_path) {
         const manifest = await backupService.getBackupManifest(secondRun.id);
         expect(manifest.manifest.incremental).toBeDefined();
-        expect(manifest.manifest.incremental.modified_files_count).toBe(1);
+        expect(manifest.manifest.incremental.changes).toBeDefined();
+        expect(manifest.manifest.incremental.changes.modified_files_count).toBe(1);
       }
     });
 
@@ -468,15 +485,16 @@ describe('S3 Backup Integration Tests', () => {
       { setting_key: 'backup_max_file_size_mb', setting_value: '100' }
     ];
 
+    // Schema drift: app_settings has no created_at column anymore and the
+    // unique constraint is on setting_key alone, not (setting_type, key).
     for (const setting of settings) {
       await db('app_settings')
         .insert({
           setting_type: 'backup',
           ...setting,
-          created_at: new Date(),
-          updated_at: new Date()
+          updated_at: new Date(),
         })
-        .onConflict(['setting_type', 'setting_key'])
+        .onConflict('setting_key')
         .merge();
     }
   }

backend/__tests__/integration/imageProcessor.storage.test.js

@@ -0,0 +1,165 @@
+const path = require('path');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const { S3Client, CreateBucketCommand, DeleteBucketCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+const sharp = require('sharp');
+
+const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../../src/services/storage/S3StorageBackend');
+const storageModule = require('../../src/services/storage');
+
+// Stub out the DB so getThumbnailSettings falls into its catch and uses defaults.
+jest.mock('../../src/database/db', () => ({
+  db: () => {
+    throw new Error('db disabled in this test');
+  },
+}));
+
+const TEST_S3 = {
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
+  accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
+  secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
+  region: 'us-east-1',
+};
+
+const skipS3 = process.env.SKIP_S3_TESTS === 'true';
+
+function backendCases() {
+  const cases = [
+    {
+      name: 'LocalFsStorage',
+      async setup() {
+        const root = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-imgproc-'));
+        const storage = new LocalFsStorage({ root });
+        await storage.init();
+        return { storage, cleanup: () => fs.rm(root, { recursive: true, force: true }) };
+      },
+    },
+  ];
+  if (!skipS3) {
+    cases.push({
+      name: 'S3StorageBackend (MinIO)',
+      async setup() {
+        const bucket = `picpeak-imgproc-${Date.now()}-${crypto.randomBytes(2).toString('hex')}`;
+        const s3Client = new S3Client({
+          endpoint: TEST_S3.endpoint,
+          region: TEST_S3.region,
+          credentials: { accessKeyId: TEST_S3.accessKeyId, secretAccessKey: TEST_S3.secretAccessKey },
+          forcePathStyle: true,
+        });
+        await s3Client.send(new CreateBucketCommand({ Bucket: bucket }));
+        const storage = new S3StorageBackend({
+          bucket,
+          region: TEST_S3.region,
+          endpoint: TEST_S3.endpoint,
+          accessKeyId: TEST_S3.accessKeyId,
+          secretAccessKey: TEST_S3.secretAccessKey,
+          forcePathStyle: true,
+          sslEnabled: false,
+        });
+        await storage.init();
+        return {
+          storage,
+          async cleanup() {
+            const list = await s3Client.send(new ListObjectsV2Command({ Bucket: bucket }));
+            if (list.Contents?.length) {
+              await s3Client.send(new DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: list.Contents.map((o) => ({ Key: o.Key })) },
+              }));
+            }
+            await s3Client.send(new DeleteBucketCommand({ Bucket: bucket }));
+          },
+        };
+      },
+    });
+  }
+  return cases;
+}
+
+async function makeSourceJpeg(targetDir, name) {
+  const localPath = path.join(targetDir, name);
+  // 800x600 random RGB image so sharp has something realistic to thumbnail.
+  const width = 800;
+  const height = 600;
+  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(localPath);
+  return localPath;
+}
+
+describe.each(backendCases())('imageProcessor through $name', ({ setup }) => {
+  let storage;
+  let cleanup;
+  let tmpDir;
+  let imageProcessor;
+
+  beforeAll(async () => {
+    ({ storage, cleanup } = await setup());
+    storageModule.setStorageForTesting(storage);
+    // Require AFTER setStorageForTesting so the module sees our injection.
+    delete require.cache[require.resolve('../../src/services/imageProcessor')];
+    imageProcessor = require('../../src/services/imageProcessor');
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'picpeak-imgproc-src-'));
+  }, 30000);
+
+  afterAll(async () => {
+    storageModule.resetStorage();
+    if (tmpDir) await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+    if (cleanup) await cleanup();
+  });
+
+  test('generateThumbnail writes through storage and returns a relative key', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'sample.jpg');
+    const key = await imageProcessor.generateThumbnail(src);
+    expect(key).toBe('thumbnails/thumb_sample.jpg');
+
+    expect(await storage.exists(key)).toBe(true);
+    const stat = await storage.stat(key);
+    expect(stat.size).toBeGreaterThan(100);
+
+    // Verify the bytes are a valid JPEG by re-parsing with sharp on local mode.
+    if (storage.kind() === 'local') {
+      const meta = await sharp(storage.resolveLocalPath(key)).metadata();
+      expect(meta.format).toBe('jpeg');
+      expect(meta.width).toBeLessThanOrEqual(300);
+    }
+  });
+
+  test('generateHeroImage writes through storage and returns a relative key', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'hero-source.jpg');
+    const key = await imageProcessor.generateHeroImage(src);
+    expect(key).toBe('heroes/hero_hero-source.jpg');
+    expect(await storage.exists(key)).toBe(true);
+  });
+
+  test('isThumbnailValid returns true for a good thumbnail and false for nothing', async () => {
+    const src = await makeSourceJpeg(tmpDir, 'valid-check.jpg');
+    const key = await imageProcessor.generateThumbnail(src);
+    expect(await imageProcessor.isThumbnailValid(key)).toBe(true);
+    expect(await imageProcessor.isThumbnailValid('thumbnails/does-not-exist.jpg')).toBe(false);
+  });
+
+  test('generateVideoPlaceholder writes a thumbnail entirely from buffer', async () => {
+    const key = await imageProcessor.generateVideoPlaceholder('demo.mp4');
+    expect(key).toBe('thumbnails/thumb_demo.jpg');
+    expect(await storage.exists(key)).toBe(true);
+  });
+
+  test('withLocalCopy yields a usable local path on both backends', async () => {
+    const sourceKey = 'fixture/withlocal.jpg';
+    const src = await makeSourceJpeg(tmpDir, 'withlocal.jpg');
+    const buf = await fs.readFile(src);
+    await storage.put(sourceKey, buf, { contentType: 'image/jpeg' });
+
+    const seenSize = await imageProcessor.withLocalCopy(sourceKey, async (localPath) => {
+      const meta = await sharp(localPath).metadata();
+      return meta.width;
+    });
+    expect(seenSize).toBe(800);
+  });
+});

backend/__tests__/integration/storageBackend.test.js

@@ -0,0 +1,189 @@
+const path = require('path');
+const fs = require('fs');
+const fsp = require('fs').promises;
+const os = require('os');
+const crypto = require('crypto');
+const { Readable } = require('stream');
+const { S3Client, CreateBucketCommand, DeleteBucketCommand, ListObjectsV2Command, DeleteObjectsCommand } = require('@aws-sdk/client-s3');
+
+const LocalFsStorage = require('../../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../../src/services/storage/S3StorageBackend');
+
+// MinIO defaults match docker-compose.dev.yml. Override via TEST_S3_* if needed.
+const TEST_S3 = {
+  endpoint: process.env.TEST_S3_ENDPOINT || 'http://localhost:7104',
+  accessKeyId: process.env.TEST_S3_ACCESS_KEY || 'minioadmin',
+  secretAccessKey: process.env.TEST_S3_SECRET_KEY || 'minioadmin',
+  region: 'us-east-1',
+};
+
+const skipS3 = process.env.SKIP_S3_TESTS === 'true';
+
+// Build the matrix of backends to test. Local always runs; S3 runs against MinIO
+// unless SKIP_S3_TESTS=true (CI default). The same suite runs against both so
+// every consumer can rely on identical semantics.
+function backendCases() {
+  const cases = [
+    {
+      name: 'LocalFsStorage',
+      async setup() {
+        const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'picpeak-storage-'));
+        const storage = new LocalFsStorage({ root });
+        await storage.init();
+        return { storage, cleanup: () => fsp.rm(root, { recursive: true, force: true }) };
+      },
+    },
+  ];
+
+  if (!skipS3) {
+    cases.push({
+      name: 'S3StorageBackend (MinIO)',
+      async setup() {
+        const bucket = `picpeak-test-${Date.now()}-${crypto.randomBytes(2).toString('hex')}`;
+        const s3Client = new S3Client({
+          endpoint: TEST_S3.endpoint,
+          region: TEST_S3.region,
+          credentials: { accessKeyId: TEST_S3.accessKeyId, secretAccessKey: TEST_S3.secretAccessKey },
+          forcePathStyle: true,
+        });
+        await s3Client.send(new CreateBucketCommand({ Bucket: bucket }));
+        const storage = new S3StorageBackend({
+          bucket,
+          region: TEST_S3.region,
+          endpoint: TEST_S3.endpoint,
+          accessKeyId: TEST_S3.accessKeyId,
+          secretAccessKey: TEST_S3.secretAccessKey,
+          forcePathStyle: true,
+          sslEnabled: false,
+        });
+        await storage.init();
+        return {
+          storage,
+          async cleanup() {
+            // Empty bucket then delete it.
+            const list = await s3Client.send(new ListObjectsV2Command({ Bucket: bucket }));
+            if (list.Contents?.length) {
+              await s3Client.send(new DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: list.Contents.map((o) => ({ Key: o.Key })) },
+              }));
+            }
+            await s3Client.send(new DeleteBucketCommand({ Bucket: bucket }));
+          },
+        };
+      },
+    });
+  }
+
+  return cases;
+}
+
+async function readToString(stream) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+describe.each(backendCases())('StorageBackend contract: $name', ({ setup }) => {
+  let storage;
+  let cleanup;
+
+  beforeAll(async () => {
+    ({ storage, cleanup } = await setup());
+  }, 30000);
+
+  afterAll(async () => {
+    if (cleanup) await cleanup();
+  });
+
+  test('put + get + exists + stat + delete round-trip with a buffer body', async () => {
+    const key = 'photos/event-a/IMG_0001.jpg';
+    const body = Buffer.from('hello picpeak');
+
+    await storage.put(key, body, { contentType: 'image/jpeg' });
+
+    expect(await storage.exists(key)).toBe(true);
+
+    const stat = await storage.stat(key);
+    expect(stat).not.toBeNull();
+    expect(stat.size).toBe(body.length);
+
+    const stream = await storage.get(key);
+    const text = await readToString(stream);
+    expect(text).toBe('hello picpeak');
+
+    await storage.delete(key);
+    expect(await storage.exists(key)).toBe(false);
+    expect(await storage.stat(key)).toBeNull();
+  });
+
+  test('put accepts a Readable stream body', async () => {
+    const key = 'photos/event-b/streamed.bin';
+    const body = Readable.from(Buffer.from('streamed payload'));
+
+    await storage.put(key, body);
+
+    const got = await readToString(await storage.get(key));
+    expect(got).toBe('streamed payload');
+  });
+
+  test('putFromFile + getToFile round-trip', async () => {
+    const tmpIn = path.join(os.tmpdir(), `in-${Date.now()}.txt`);
+    const tmpOut = path.join(os.tmpdir(), `out-${Date.now()}.txt`);
+    await fsp.writeFile(tmpIn, 'file payload');
+
+    const key = 'thumbnails/thumb_x.jpg';
+    await storage.putFromFile(key, tmpIn, { contentType: 'image/jpeg' });
+
+    await storage.getToFile(key, tmpOut);
+    const text = await fsp.readFile(tmpOut, 'utf-8');
+    expect(text).toBe('file payload');
+
+    await fsp.unlink(tmpIn).catch(() => {});
+    await fsp.unlink(tmpOut).catch(() => {});
+  });
+
+  test('list returns entries under a prefix with size + key', async () => {
+    await storage.put('events/active/a/photo1.jpg', Buffer.from('a1'));
+    await storage.put('events/active/a/photo2.jpg', Buffer.from('a22'));
+    await storage.put('events/active/b/photo3.jpg', Buffer.from('b333'));
+
+    const entries = await storage.list('events/active/a');
+    const keys = entries.map((e) => e.key).sort();
+    expect(keys).toEqual(['events/active/a/photo1.jpg', 'events/active/a/photo2.jpg']);
+    const sizes = Object.fromEntries(entries.map((e) => [e.key, e.size]));
+    expect(sizes['events/active/a/photo1.jpg']).toBe(2);
+    expect(sizes['events/active/a/photo2.jpg']).toBe(3);
+  });
+
+  test('rename moves an object from src to dst (atomic on local; copy+delete on s3)', async () => {
+    await storage.put('uploads/temp.jpg', Buffer.from('rename-me'));
+    await storage.rename('uploads/temp.jpg', 'uploads/final.jpg');
+
+    expect(await storage.exists('uploads/temp.jpg')).toBe(false);
+    expect(await storage.exists('uploads/final.jpg')).toBe(true);
+    const text = await readToString(await storage.get('uploads/final.jpg'));
+    expect(text).toBe('rename-me');
+  });
+
+  test('copy duplicates an object without removing the source', async () => {
+    await storage.put('events/source.jpg', Buffer.from('src'));
+    await storage.copy('events/source.jpg', 'events/copied.jpg');
+
+    expect(await storage.exists('events/source.jpg')).toBe(true);
+    expect(await storage.exists('events/copied.jpg')).toBe(true);
+  });
+
+  test('delete on a missing key is a no-op (does not throw)', async () => {
+    await expect(storage.delete('does/not/exist.jpg')).resolves.toBeUndefined();
+  });
+
+  test('stat on a missing key returns null', async () => {
+    expect(await storage.stat('still/not/here.jpg')).toBeNull();
+  });
+
+  test('rejects path traversal attempts', async () => {
+    await expect(storage.put('../escape.txt', Buffer.from('x'))).rejects.toThrow(/traversal/i);
+    await expect(storage.get('../escape.txt')).rejects.toThrow(/traversal/i);
+  });
+});

backend/__tests__/integration/webhookDelivery.test.js

@@ -0,0 +1,239 @@
+// Worker reads WEBHOOK_ALLOW_PRIVATE_URLS at module-load. Set it BEFORE
+// requiring the worker so the local-stub URLs (127.0.0.1:<random>) pass
+// the SSRF check by default.
+process.env.WEBHOOK_ALLOW_PRIVATE_URLS = 'true';
+process.env.WEBHOOK_DELIVERY_INTERVAL_MS = '50';
+
+const http = require('http');
+const { db } = require('../../src/database/db');
+const webhookService = require('../../src/services/webhookService');
+const { __test, startWebhookDeliveryWorker, stopWebhookDeliveryWorker } = require('../../src/services/webhookDeliveryWorker');
+
+// Local-only test stub: matches what dev/webhook-receiver/server.js does
+// in the docker-compose flow but spun up inside the Jest process so the
+// suite is self-contained.
+function makeStub({ status = 200, delayMs = 0, bodyOverride = null } = {}) {
+  const requests = [];
+  const server = http.createServer(async (req, res) => {
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    const body = Buffer.concat(chunks).toString('utf8');
+    requests.push({ method: req.method, url: req.url, headers: req.headers, body });
+    if (delayMs) await new Promise((r) => setTimeout(r, delayMs));
+    res.writeHead(status, { 'Content-Type': 'text/plain' });
+    res.end(bodyOverride !== null ? bodyOverride : (status >= 200 && status < 300 ? 'ok' : 'forced'));
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      resolve({ url: `http://127.0.0.1:${port}/`, requests, close: () => new Promise((r) => server.close(r)) });
+    });
+  });
+}
+
+async function insertWebhook(url, events = ['event.published'], extras = {}) {
+  // Tests need the WORKER to bypass SSRF on 127.0.0.1 stubs, but the
+  // route layer's allowlist check is bypassed here since we insert
+  // straight into the DB.
+  const { plaintext, preview } = webhookService.generateSecret();
+  const insert = await db('webhooks').insert({
+    name: extras.name || 'test',
+    url,
+    secret: plaintext,
+    secret_preview: preview,
+    events: JSON.stringify(events),
+    active: extras.active !== false,
+    created_by: 1,
+  }).returning('id');
+  const id = insert[0]?.id || insert[0];
+  return { id, secret: plaintext };
+}
+
+async function clearWebhooks() {
+  await db('webhook_deliveries').del();
+  await db('webhooks').del();
+}
+
+describe('webhook delivery worker (#327)', () => {
+  beforeAll(async () => {
+    // Schema is expected to already be applied by `npm run migrate`. We
+    // just verify the webhooks tables exist; if not, the test harness has
+    // missed running migration 082.
+    const ok = await db.schema.hasTable('webhooks');
+    if (!ok) throw new Error('webhooks table missing — run `npm run migrate` first');
+  }, 30000);
+
+  afterAll(async () => {
+    stopWebhookDeliveryWorker();
+    await db.destroy();
+  });
+
+  beforeEach(async () => {
+    await clearWebhooks();
+  });
+
+  test('signs the body with HMAC-SHA256 and the receiver can verify', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      const { id, secret } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: { id: 1, slug: 'sig-test' } });
+      await __test.tick();
+
+      expect(stub.requests).toHaveLength(1);
+      const got = stub.requests[0];
+      const sig = got.headers['x-picpeak-signature'];
+      expect(sig).toBeTruthy();
+      // Receiver-side verification using the SAME helper we ship in the README.
+      expect(webhookService.verifySignature(secret, got.body, sig)).toBe(true);
+      // Tampering must fail.
+      expect(webhookService.verifySignature(secret, got.body + 'x', sig)).toBe(false);
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('success');
+      expect(row.attempt_count).toBe(1);
+      expect(row.response_status).toBe(200);
+      expect(row.latency_ms).toBeGreaterThanOrEqual(0);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('headers include event type and a unique delivery id', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      await insertWebhook(stub.url, ['photo.uploaded']);
+      await webhookService.fire('photo.uploaded', { photo: { id: 7 } });
+      await __test.tick();
+
+      const got = stub.requests[0];
+      expect(got.headers['x-picpeak-event']).toBe('photo.uploaded');
+      expect(got.headers['x-picpeak-delivery']).toBeTruthy();
+      expect(got.headers['user-agent']).toMatch(/PicPeak-Webhooks/);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('on 5xx, schedules a retry with exponential backoff and stays pending', async () => {
+    const stub = await makeStub({ status: 500 });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: { id: 2 } });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('pending');
+      expect(row.attempt_count).toBe(1);
+      expect(row.response_status).toBe(500);
+      // BACKOFF_MS[0] = 60s; next_retry_at should be ~60s in the future.
+      const dueIn = new Date(row.next_retry_at).getTime() - Date.now();
+      expect(dueIn).toBeGreaterThan(50_000);
+      expect(dueIn).toBeLessThan(70_000);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('after MAX_ATTEMPTS failures, status flips to failed and the row is closed', async () => {
+    const stub = await makeStub({ status: 500 });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      // Pre-seed a delivery already at attempt_count = 4 so a single tick
+      // takes it to 5 → failed (avoids waiting through backoffs).
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 4,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.attempt_count).toBe(5);
+      expect(row.completed_at).toBeTruthy();
+      expect(row.next_retry_at).toBeNull();
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('truncates response body to 1KB before storing', async () => {
+    const big = 'x'.repeat(5000);
+    const stub = await makeStub({ status: 200, bodyOverride: big });
+    try {
+      const { id } = await insertWebhook(stub.url);
+      await webhookService.fire('event.published', { event: {} });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('success');
+      expect(Buffer.byteLength(row.response_body || '', 'utf8')).toBeLessThanOrEqual(1024);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('does not deliver to disabled webhooks (post-mortem state captured)', async () => {
+    const stub = await makeStub({ status: 200 });
+    try {
+      const { id } = await insertWebhook(stub.url, ['event.published'], { active: false });
+      // fire enqueues regardless of active state at fire-time, but we
+      // disabled BEFORE firing so nothing is enqueued. Direct insert to
+      // exercise the worker's mid-flight disable check:
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      expect(stub.requests).toHaveLength(0);
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.last_error).toMatch(/disabled/i);
+    } finally {
+      await stub.close();
+    }
+  });
+
+  test('rejects loopback URLs when WEBHOOK_ALLOW_PRIVATE_URLS=false', async () => {
+    __test.setAllowPrivateUrls(false);
+    try {
+      const { id } = await insertWebhook('http://127.0.0.1:9/');
+      await db('webhook_deliveries').insert({
+        webhook_id: id,
+        event_type: 'event.published',
+        payload: JSON.stringify({ id: 'd1', type: 'event.published', data: {} }),
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+      await __test.tick();
+
+      const row = await db('webhook_deliveries').where({ webhook_id: id }).first();
+      expect(row.status).toBe('failed');
+      expect(row.last_error).toMatch(/private|internal/i);
+    } finally {
+      __test.setAllowPrivateUrls(true);
+    }
+  });
+
+  test('worker can be started + stopped without leaking timers', async () => {
+    startWebhookDeliveryWorker();
+    startWebhookDeliveryWorker(); // idempotent
+    stopWebhookDeliveryWorker();
+    stopWebhookDeliveryWorker(); // idempotent
+    // If timers leaked the test runner would warn after force-exit; assertion
+    // is just "no throw".
+    expect(true).toBe(true);
+  });
+});

backend/migrations/README.md

@@ -1,6 +1,6 @@
 # Database Migrations
 
-This directory contains database migrations for the Wedding Photo Sharing platform.
+This directory contains database migrations for the PicPeak photo sharing platform.
 
 ## Directory Structure
 
@@ -9,6 +9,7 @@ Essential migrations that are always run for new deployments. These include:
 - `init.js` - Initial database schema creation
 - Backup service tables (029-035)
 - Gallery feedback tables (033)
+- Pre-generated watermarks (061)
 
 ### `/legacy`
 Migrations needed only when upgrading from older versions. New deployments can skip these as the core schema already includes all necessary tables and columns.

backend/migrations/core/001_init.js

@@ -14,8 +14,8 @@ exports.up = async function(knex) {
     // Create default admin user if none exists
     const adminExists = await knex('admin_users').first();
     if (!adminExists) {
-      // Generate a secure random password
-      const generatedPassword = generateReadablePassword();
+      // Use ADMIN_PASSWORD from environment if set, otherwise generate a random one
+      const generatedPassword = process.env.ADMIN_PASSWORD || generateReadablePassword();
       const passwordHash = await bcrypt.hash(generatedPassword, 12); // Increased rounds for better security
       
       // Get admin credentials from environment or use defaults

backend/migrations/core/061_add_event_types_table.js

@@ -0,0 +1,107 @@
+/**
+ * Migration: Add event_types table
+ *
+ * Creates a customizable event types system to replace hardcoded event types.
+ * This allows users to:
+ * - Rename existing event types (wedding, birthday, corporate, other)
+ * - Create custom event types with custom slug prefixes
+ * - Associate default theme presets with event types
+ *
+ * Backward compatible: Existing events keep their event_type strings.
+ * New events can use either legacy strings or custom event type slug_prefix.
+ */
+
+const { createTableIfNotExists, insertIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Creating event_types table...');
+
+  // Create event_types table
+  const hasEventTypesTable = await knex.schema.hasTable('event_types');
+  if (!hasEventTypesTable) {
+    await knex.schema.createTable('event_types', (table) => {
+      table.increments('id').primary();
+      table.string('name', 100).notNullable(); // Display name: "Family Shoot"
+      table.string('slug_prefix', 50).unique().notNullable(); // URL prefix: "family"
+      table.string('emoji', 10); // Icon emoji: "👨‍👩‍👧"
+      table.string('theme_preset', 50); // Default theme: "elegantWedding"
+      table.text('theme_config'); // Custom theme JSON overrides (optional)
+      table.integer('display_order').defaultTo(0); // Sorting in dropdowns
+      table.boolean('is_system').defaultTo(false); // Protect default types
+      table.boolean('is_active').defaultTo(true); // Allow hiding types
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+
+      // Indexes for performance
+      table.index('slug_prefix');
+      table.index('display_order');
+      table.index('is_active');
+    });
+    console.log('event_types table created');
+  } else {
+    console.log('event_types table already exists, skipping creation');
+  }
+
+  // Seed default event types (matching current hardcoded values)
+  const existingTypes = await knex('event_types').select('slug_prefix');
+  const existingSlugs = existingTypes.map(t => t.slug_prefix);
+
+  const defaultTypes = [
+    {
+      name: 'Wedding',
+      slug_prefix: 'wedding',
+      emoji: '💒',
+      theme_preset: 'elegantWedding',
+      display_order: 1,
+      is_system: true,
+      is_active: true
+    },
+    {
+      name: 'Birthday',
+      slug_prefix: 'birthday',
+      emoji: '🎂',
+      theme_preset: 'birthdayFun',
+      display_order: 2,
+      is_system: true,
+      is_active: true
+    },
+    {
+      name: 'Corporate',
+      slug_prefix: 'corporate',
+      emoji: '🏢',
+      theme_preset: 'corporateTimeline',
+      display_order: 3,
+      is_system: true,
+      is_active: true
+    },
+    {
+      name: 'Other',
+      slug_prefix: 'other',
+      emoji: '📸',
+      theme_preset: 'default',
+      display_order: 4,
+      is_system: true,
+      is_active: true
+    }
+  ];
+
+  const typesToInsert = defaultTypes.filter(type => !existingSlugs.includes(type.slug_prefix));
+
+  if (typesToInsert.length > 0) {
+    await knex('event_types').insert(typesToInsert);
+    console.log(`Inserted ${typesToInsert.length} default event types`);
+  } else {
+    console.log('Default event types already exist, skipping seed');
+  }
+
+  console.log('Migration 061_add_event_types_table completed successfully');
+};
+
+exports.down = async function(knex) {
+  console.log('Rolling back event_types table...');
+
+  // Drop the table (data will be lost)
+  await knex.schema.dropTableIfExists('event_types');
+
+  console.log('event_types table dropped');
+};

backend/migrations/core/061_add_optional_date_expiration_settings.js

@@ -0,0 +1,53 @@
+/**
+ * Migration: Add optional event date and expiration settings
+ * These settings control whether event_date and expiration are required
+ * when creating new events, supporting non-event use cases like portraits.
+ */
+
+exports.up = async function(knex) {
+  // Add new settings for optional date and expiration
+  const settings = [
+    { setting_key: 'event_require_event_date', setting_value: JSON.stringify(true), setting_type: 'boolean' },
+    { setting_key: 'event_require_expiration', setting_value: JSON.stringify(true), setting_type: 'boolean' }
+  ];
+
+  for (const setting of settings) {
+    const exists = await knex('app_settings').where('setting_key', setting.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({
+        ...setting,
+        updated_at: knex.fn.now()
+      });
+    }
+  }
+
+  // Make event_date and expires_at columns nullable
+  // PostgreSQL supports ALTER COLUMN ... DROP NOT NULL
+  // SQLite requires table recreation (handled differently)
+  const client = knex.client.config.client;
+
+  if (client === 'pg' || client === 'postgresql') {
+    // PostgreSQL: directly alter columns
+    await knex.raw('ALTER TABLE events ALTER COLUMN event_date DROP NOT NULL');
+    await knex.raw('ALTER TABLE events ALTER COLUMN expires_at DROP NOT NULL');
+  } else if (client === 'sqlite3' || client === 'better-sqlite3') {
+    // SQLite: columns are already effectively nullable in most cases
+    // SQLite doesn't enforce NOT NULL as strictly, and altering requires table recreation
+    // For safety, we'll skip the schema change for SQLite as it's complex
+    // The application logic will handle null values appropriately
+    console.log('SQLite detected - skipping schema alteration (columns will accept NULL values)');
+  }
+};
+
+exports.down = async function(knex) {
+  // Remove the settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'event_require_event_date',
+      'event_require_expiration'
+    ])
+    .del();
+
+  // Note: We don't restore NOT NULL constraints as that could fail
+  // if there are existing NULL values in the database
+};

backend/migrations/core/061_add_watermark_path.js

@@ -0,0 +1,28 @@
+/**
+ * Migration 061: Add pre-generated watermark path to photos table
+ * - photos.watermark_path: path to pre-generated watermarked image
+ * - photos.watermark_generated_at: timestamp of watermark generation
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 061_add_watermark_path');
+
+  // photos.watermark_path (nullable - path to pre-generated watermarked image)
+  await addColumnIfNotExists(knex, 'photos', 'watermark_path', (table) => {
+    table.string('watermark_path', 512);
+  });
+
+  // photos.watermark_generated_at (nullable - when watermark was last generated)
+  await addColumnIfNotExists(knex, 'photos', 'watermark_generated_at', (table) => {
+    table.timestamp('watermark_generated_at');
+  });
+
+  console.log('Migration 061_add_watermark_path completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 061_add_watermark_path');
+  // Keep columns (safe rollback not removing data). Intentionally no-op.
+};

backend/migrations/core/062_add_hero_logo_settings.js

@@ -0,0 +1,70 @@
+/**
+ * Migration: Add hero logo customization settings to events table
+ *
+ * Allows per-event customization of the hero gallery logo:
+ * - hero_logo_visible: Show/hide the logo overlay
+ * - hero_logo_size: Logo size (small, medium, large, xlarge)
+ * - hero_logo_position: Logo position (top, center, bottom)
+ *
+ * Addresses GitHub Issue #138: Add Option to customize the Hero gallery layout
+ */
+
+exports.up = async function (knex) {
+  console.log('Adding hero logo settings to events table...');
+
+  // Add hero_logo_visible column
+  const hasVisibleColumn = await knex.schema.hasColumn('events', 'hero_logo_visible');
+  if (!hasVisibleColumn) {
+    await knex.schema.table('events', (table) => {
+      table.boolean('hero_logo_visible').notNullable().defaultTo(true);
+    });
+    console.log('Added hero_logo_visible column');
+  }
+
+  // Add hero_logo_size column
+  const hasSizeColumn = await knex.schema.hasColumn('events', 'hero_logo_size');
+  if (!hasSizeColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_size', 20).notNullable().defaultTo('medium');
+    });
+    console.log('Added hero_logo_size column');
+  }
+
+  // Add hero_logo_position column
+  const hasPositionColumn = await knex.schema.hasColumn('events', 'hero_logo_position');
+  if (!hasPositionColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_position', 20).notNullable().defaultTo('top');
+    });
+    console.log('Added hero_logo_position column');
+  }
+
+  console.log('Migration 062_add_hero_logo_settings completed successfully');
+};
+
+exports.down = async function (knex) {
+  console.log('Rolling back hero logo settings...');
+
+  const hasVisibleColumn = await knex.schema.hasColumn('events', 'hero_logo_visible');
+  if (hasVisibleColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_visible');
+    });
+  }
+
+  const hasSizeColumn = await knex.schema.hasColumn('events', 'hero_logo_size');
+  if (hasSizeColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_size');
+    });
+  }
+
+  const hasPositionColumn = await knex.schema.hasColumn('events', 'hero_logo_position');
+  if (hasPositionColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_position');
+    });
+  }
+
+  console.log('Hero logo settings columns dropped');
+};

backend/migrations/core/062_add_original_filename.js

@@ -0,0 +1,23 @@
+/**
+ * Migration 062: Add original_filename to photos table
+ * - photos.original_filename: preserves the original filename from upload
+ *   This enables Lightroom integration by exporting filtered filenames
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 062_add_original_filename');
+
+  // photos.original_filename (nullable - original filename before renaming)
+  await addColumnIfNotExists(knex, 'photos', 'original_filename', (table) => {
+    table.string('original_filename', 512);
+  });
+
+  console.log('Migration 062_add_original_filename completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 062_add_original_filename');
+  // Keep column (safe rollback not removing data). Intentionally no-op.
+};

backend/migrations/core/063_add_event_custom_logo.js

@@ -0,0 +1,53 @@
+/**
+ * Migration: Add custom logo support to events table
+ *
+ * Allows per-event custom logo that overrides the global branding logo:
+ * - hero_logo_url: Public path to the uploaded custom logo
+ * - hero_logo_path: Full filesystem path to the custom logo
+ *
+ * Logo priority: Event custom logo > Global branding logo > Default PicPeak logo
+ *
+ * Addresses GitHub Issue #138: Per-event custom logo option
+ */
+
+exports.up = async function (knex) {
+  console.log('Adding custom logo columns to events table...');
+
+  const hasUrlColumn = await knex.schema.hasColumn('events', 'hero_logo_url');
+  if (!hasUrlColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_url', 500).nullable().defaultTo(null);
+    });
+    console.log('Added hero_logo_url column');
+  }
+
+  const hasPathColumn = await knex.schema.hasColumn('events', 'hero_logo_path');
+  if (!hasPathColumn) {
+    await knex.schema.table('events', (table) => {
+      table.string('hero_logo_path', 500).nullable().defaultTo(null);
+    });
+    console.log('Added hero_logo_path column');
+  }
+
+  console.log('Migration 063_add_event_custom_logo completed successfully');
+};
+
+exports.down = async function (knex) {
+  console.log('Rolling back custom logo columns...');
+
+  const hasUrlColumn = await knex.schema.hasColumn('events', 'hero_logo_url');
+  if (hasUrlColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_url');
+    });
+  }
+
+  const hasPathColumn = await knex.schema.hasColumn('events', 'hero_logo_path');
+  if (hasPathColumn) {
+    await knex.schema.table('events', (table) => {
+      table.dropColumn('hero_logo_path');
+    });
+  }
+
+  console.log('Custom logo columns dropped');
+};

backend/migrations/core/064_backfill_photo_dimensions.js

@@ -0,0 +1,105 @@
+/**
+ * Migration: Backfill photo dimensions
+ *
+ * This migration extracts width/height from existing photos that don't have
+ * these dimensions stored. This is needed for aspect-ratio-aware layouts
+ * (masonry, mosaic, justified) to work properly.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+exports.up = async function(knex) {
+  // Check if the width/height columns exist
+  const hasWidth = await knex.schema.hasColumn('photos', 'width');
+  const hasHeight = await knex.schema.hasColumn('photos', 'height');
+
+  if (!hasWidth || !hasHeight) {
+    console.log('[Migration 064] Width/height columns not found, skipping backfill');
+    return;
+  }
+
+  // Get storage path
+  const storagePath = process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
+
+  // Find photos without dimensions
+  const photos = await knex('photos')
+    .whereNull('width')
+    .orWhereNull('height')
+    .select('id', 'path', 'filename', 'media_type');
+
+  console.log(`[Migration 064] Found ${photos.length} photos without dimensions`);
+
+  if (photos.length === 0) {
+    return;
+  }
+
+  // Import sharp dynamically (only needed during migration)
+  let sharp;
+  try {
+    sharp = require('sharp');
+  } catch (err) {
+    console.error('[Migration 064] Sharp not available, skipping backfill:', err.message);
+    return;
+  }
+
+  let updated = 0;
+  let failed = 0;
+
+  for (const photo of photos) {
+    try {
+      // Skip videos - they need ffprobe for metadata
+      if (photo.media_type === 'video') {
+        continue;
+      }
+
+      // Construct the full file path
+      let fullPath;
+      if (photo.path) {
+        // Path is relative to events/active directory
+        fullPath = path.join(storagePath, 'events/active', photo.path);
+      } else {
+        console.warn(`[Migration 064] Photo ${photo.id} (${photo.filename}) has no path, skipping`);
+        continue;
+      }
+
+      // Check if file exists
+      if (!fs.existsSync(fullPath)) {
+        console.warn(`[Migration 064] Photo ${photo.id} file not found: ${fullPath}`);
+        failed++;
+        continue;
+      }
+
+      // Extract dimensions using sharp
+      const metadata = await sharp(fullPath).metadata();
+
+      if (metadata.width && metadata.height) {
+        await knex('photos')
+          .where('id', photo.id)
+          .update({
+            width: metadata.width,
+            height: metadata.height
+          });
+        updated++;
+
+        if (updated % 50 === 0) {
+          console.log(`[Migration 064] Updated ${updated} photos...`);
+        }
+      } else {
+        console.warn(`[Migration 064] Could not extract dimensions for photo ${photo.id}`);
+        failed++;
+      }
+    } catch (err) {
+      console.error(`[Migration 064] Error processing photo ${photo.id}:`, err.message);
+      failed++;
+    }
+  }
+
+  console.log(`[Migration 064] Completed: ${updated} updated, ${failed} failed`);
+};
+
+exports.down = async function(knex) {
+  // This migration only adds data, no rollback needed
+  // We don't want to null out dimensions on rollback as they're still valid
+  console.log('[Migration 064] Rollback: No action needed (data-only migration)');
+};

backend/migrations/core/065_add_header_style.js

@@ -0,0 +1,131 @@
+/**
+ * Migration: Add header_style and hero_divider_style columns
+ *
+ * This migration decouples the hero header style from gallery layout,
+ * allowing any combination of header style with any layout type.
+ */
+
+exports.up = async function(knex) {
+  console.log('[Migration 065] Adding header_style and hero_divider_style columns');
+
+  // Check if columns already exist
+  const hasHeaderStyle = await knex.schema.hasColumn('events', 'header_style');
+  const hasDividerStyle = await knex.schema.hasColumn('events', 'hero_divider_style');
+
+  if (!hasHeaderStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.string('header_style', 20).defaultTo('standard');
+    });
+    console.log('[Migration 065] Added header_style column');
+  }
+
+  if (!hasDividerStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.string('hero_divider_style', 20).defaultTo('wave');
+    });
+    console.log('[Migration 065] Added hero_divider_style column');
+  }
+
+  // Migrate existing events with hero layout in color_theme
+  console.log('[Migration 065] Migrating existing hero layouts...');
+
+  const events = await knex('events')
+    .whereNotNull('color_theme')
+    .select('id', 'color_theme');
+
+  let migratedCount = 0;
+
+  for (const event of events) {
+    try {
+      // Skip if color_theme is not JSON
+      if (!event.color_theme || !event.color_theme.startsWith('{')) {
+        continue;
+      }
+
+      const theme = JSON.parse(event.color_theme);
+
+      // Check if this event uses hero layout
+      if (theme.galleryLayout === 'hero') {
+        // Migrate: set headerStyle to 'hero' and galleryLayout to 'grid'
+        const updatedTheme = {
+          ...theme,
+          headerStyle: 'hero',
+          galleryLayout: 'grid',
+          heroDividerStyle: theme.heroDividerStyle || 'wave'
+        };
+
+        await knex('events')
+          .where('id', event.id)
+          .update({
+            color_theme: JSON.stringify(updatedTheme),
+            header_style: 'hero',
+            hero_divider_style: theme.heroDividerStyle || 'wave'
+          });
+
+        migratedCount++;
+      }
+    } catch (err) {
+      // Invalid JSON in color_theme, skip
+      console.warn(`[Migration 065] Could not parse color_theme for event ${event.id}: ${err.message}`);
+    }
+  }
+
+  console.log(`[Migration 065] Migrated ${migratedCount} events from hero layout`);
+  console.log('[Migration 065] Completed');
+};
+
+exports.down = async function(knex) {
+  console.log('[Migration 065] Removing header_style and hero_divider_style columns');
+
+  // First, migrate any hero header styles back to hero layout
+  const events = await knex('events')
+    .where('header_style', 'hero')
+    .whereNotNull('color_theme')
+    .select('id', 'color_theme');
+
+  for (const event of events) {
+    try {
+      if (!event.color_theme || !event.color_theme.startsWith('{')) {
+        continue;
+      }
+
+      const theme = JSON.parse(event.color_theme);
+
+      // Revert: set galleryLayout back to 'hero'
+      const revertedTheme = {
+        ...theme,
+        galleryLayout: 'hero'
+      };
+
+      // Remove the new properties
+      delete revertedTheme.headerStyle;
+      delete revertedTheme.heroDividerStyle;
+
+      await knex('events')
+        .where('id', event.id)
+        .update({
+          color_theme: JSON.stringify(revertedTheme)
+        });
+    } catch (err) {
+      console.warn(`[Migration 065] Could not revert color_theme for event ${event.id}: ${err.message}`);
+    }
+  }
+
+  // Remove the columns
+  const hasHeaderStyle = await knex.schema.hasColumn('events', 'header_style');
+  const hasDividerStyle = await knex.schema.hasColumn('events', 'hero_divider_style');
+
+  if (hasHeaderStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('header_style');
+    });
+  }
+
+  if (hasDividerStyle) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('hero_divider_style');
+    });
+  }
+
+  console.log('[Migration 065] Rollback completed');
+};

backend/migrations/core/066_add_hero_anchor_and_category_hero.js

@@ -0,0 +1,48 @@
+/**
+ * Migration: Add hero image anchor position and category-specific hero images
+ *
+ * Issue #162: Add hero_image_anchor column to events table for controlling
+ *             how hero images are cropped (top/center/bottom)
+ *
+ * Issue #163: Add hero_photo_id column to photo_categories table for
+ *             category-specific hero images
+ */
+
+exports.up = async function(knex) {
+  // Add hero_image_anchor to events table (Issue #162)
+  const hasHeroAnchor = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasHeroAnchor) {
+    await knex.schema.alterTable('events', function(table) {
+      // Values: 'top', 'center', 'bottom' - defaults to 'center' for backward compatibility
+      table.string('hero_image_anchor', 10).defaultTo('center');
+    });
+    console.log('Added hero_image_anchor column to events table');
+  }
+
+  // Add hero_photo_id to photo_categories table (Issue #163)
+  const hasCategoryHero = await knex.schema.hasColumn('photo_categories', 'hero_photo_id');
+  if (!hasCategoryHero) {
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.integer('hero_photo_id').references('id').inTable('photos').onDelete('SET NULL');
+    });
+    console.log('Added hero_photo_id column to photo_categories table');
+  }
+};
+
+exports.down = async function(knex) {
+  // Remove hero_image_anchor from events table
+  const hasHeroAnchor = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (hasHeroAnchor) {
+    await knex.schema.alterTable('events', function(table) {
+      table.dropColumn('hero_image_anchor');
+    });
+  }
+
+  // Remove hero_photo_id from photo_categories table
+  const hasCategoryHero = await knex.schema.hasColumn('photo_categories', 'hero_photo_id');
+  if (hasCategoryHero) {
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.dropColumn('hero_photo_id');
+    });
+  }
+};

backend/migrations/core/067_expand_hero_image_anchor.js

@@ -0,0 +1,32 @@
+/**
+ * Migration: Expand hero_image_anchor column to support focal point percentages
+ *
+ * Changes string(10) to string(20) so values like "100% 100%" (9 chars) fit
+ * with room to spare. Existing 'top', 'center', 'bottom' values are preserved.
+ */
+
+exports.up = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasColumn) {
+    // Column doesn't exist yet – nothing to expand
+    return;
+  }
+
+  // SQLite doesn't truly support ALTER COLUMN, but Knex handles the
+  // rebuild-table strategy internally when we call alterTable.
+  await knex.schema.alterTable('events', function(table) {
+    table.string('hero_image_anchor', 20).defaultTo('center').alter();
+  });
+  console.log('Expanded hero_image_anchor column to string(20)');
+};
+
+exports.down = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasColumn) {
+    return;
+  }
+
+  await knex.schema.alterTable('events', function(table) {
+    table.string('hero_image_anchor', 10).defaultTo('center').alter();
+  });
+};

backend/migrations/core/068_add_seo_robots_settings.js

@@ -0,0 +1,54 @@
+const DEFAULT_AI_AGENTS = [
+  'GPTBot',
+  'ChatGPT-User',
+  'Google-Extended',
+  'Claude-Web',
+  'Anthropic-AI',
+  'CCBot',
+  'Bytespider',
+  'FacebookBot',
+  'Omgilibot',
+  'Diffbot',
+  'PetalBot',
+  'Amazonbot',
+  'PerplexityBot',
+  'YouBot',
+  'Applebot-Extended'
+];
+
+exports.up = async function(knex) {
+  const defaults = [
+    { setting_key: 'seo_allow_indexing', setting_value: JSON.stringify(false), setting_type: 'seo' },
+    { setting_key: 'seo_block_ai_crawlers', setting_value: JSON.stringify(true), setting_type: 'seo' },
+    { setting_key: 'seo_block_social_bots', setting_value: JSON.stringify(false), setting_type: 'seo' },
+    { setting_key: 'seo_blocked_ai_agents', setting_value: JSON.stringify(DEFAULT_AI_AGENTS), setting_type: 'seo' },
+    { setting_key: 'seo_custom_rules', setting_value: JSON.stringify([]), setting_type: 'seo' },
+    { setting_key: 'seo_meta_noindex', setting_value: JSON.stringify(true), setting_type: 'seo' },
+    { setting_key: 'seo_meta_nofollow', setting_value: JSON.stringify(false), setting_type: 'seo' },
+    { setting_key: 'seo_meta_noai', setting_value: JSON.stringify(true), setting_type: 'seo' },
+    { setting_key: 'seo_sitemap_url', setting_value: JSON.stringify(''), setting_type: 'seo' }
+  ];
+
+  for (const setting of defaults) {
+    const exists = await knex('app_settings').where('setting_key', setting.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({ ...setting, updated_at: knex.fn.now() });
+    }
+  }
+};
+
+exports.down = async function(knex) {
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'seo_allow_indexing',
+      'seo_block_ai_crawlers',
+      'seo_block_social_bots',
+      'seo_blocked_ai_agents',
+      'seo_custom_rules',
+      'seo_meta_noindex',
+      'seo_meta_nofollow',
+      'seo_meta_noai',
+      'seo_sitemap_url'
+    ])
+    .del();
+};

backend/migrations/core/069_add_hero_path.js

@@ -0,0 +1,22 @@
+/**
+ * Migration 069: Add hero image path to photos table
+ * - photos.hero_path: path to hero-optimized image (1920x1080) for gallery headers
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 069_add_hero_path');
+
+  // photos.hero_path (nullable - path to hero-optimized image)
+  await addColumnIfNotExists(knex, 'photos', 'hero_path', (table) => {
+    table.string('hero_path', 512);
+  });
+
+  console.log('Migration 069_add_hero_path completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 069_add_hero_path');
+  // Keep columns (safe rollback not removing data). Intentionally no-op.
+};

backend/migrations/core/070_add_update_notification_settings.js

@@ -0,0 +1,161 @@
+/**
+ * Migration 070: Add update notification settings and email template
+ * - Settings for email notifications when new versions are available
+ * - Email template for version update notifications
+ */
+
+exports.up = async function(knex) {
+  console.log('Running migration: 070_add_update_notification_settings');
+
+  // Add app_settings for update notifications
+  const settings = [
+    {
+      setting_key: 'update_email_notifications_enabled',
+      setting_value: JSON.stringify(false),
+      setting_type: 'notifications'
+    },
+    {
+      setting_key: 'update_email_recipients',
+      setting_value: JSON.stringify(''), // Comma-separated emails, or empty for all admin emails
+      setting_type: 'notifications'
+    },
+    {
+      setting_key: 'last_notified_version',
+      setting_value: JSON.stringify(''),
+      setting_type: 'notifications'
+    }
+  ];
+
+  for (const setting of settings) {
+    const exists = await knex('app_settings').where('setting_key', setting.setting_key).first();
+    if (!exists) {
+      await knex('app_settings').insert({ ...setting, updated_at: knex.fn.now() });
+    }
+  }
+
+  // Check if email template already exists
+  const existingTemplate = await knex('email_templates')
+    .where('template_key', 'version_update_available')
+    .first();
+
+  if (!existingTemplate) {
+    await knex('email_templates').insert({
+      template_key: 'version_update_available',
+      subject_en: 'PicPeak Update Available: Version {{new_version}}',
+      subject_de: 'PicPeak Update verfugbar: Version {{new_version}}',
+      body_html_en: `
+<h2>A New Version of PicPeak is Available</h2>
+
+<p>Great news! A new version of PicPeak is available for your installation.</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Current Version:</strong> {{current_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>New Version:</strong> {{new_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Channel:</strong> {{channel}}</p>
+</div>
+
+<h3>What's New?</h3>
+<p>Check the release notes to see what's included in this update:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{release_notes_url}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">View Release Notes</a>
+</div>
+
+<h3>How to Update</h3>
+<p>To update your installation, log in to the admin panel and click on the "Update Available" notification. You'll find environment-specific instructions there.</p>
+
+<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; color: #856404; padding: 15px; border-radius: 4px; margin: 20px 0;">
+  <p style="margin: 0;"><strong>Reminder:</strong> Always backup your database before updating to ensure you can recover if anything goes wrong.</p>
+</div>
+
+<p>Best regards,<br>
+Your PicPeak Installation</p>`,
+      body_text_en: `A New Version of PicPeak is Available
+
+Great news! A new version of PicPeak is available for your installation.
+
+Current Version: {{current_version}}
+New Version: {{new_version}}
+Channel: {{channel}}
+
+What's New?
+Check the release notes to see what's included in this update:
+{{release_notes_url}}
+
+How to Update
+To update your installation, log in to the admin panel and click on the "Update Available" notification. You'll find environment-specific instructions there.
+
+REMINDER: Always backup your database before updating to ensure you can recover if anything goes wrong.
+
+Best regards,
+Your PicPeak Installation`,
+      body_html_de: `
+<h2>Eine neue Version von PicPeak ist verfugbar</h2>
+
+<p>Gute Neuigkeiten! Eine neue Version von PicPeak ist fur Ihre Installation verfugbar.</p>
+
+<div style="background-color: #f0f8ff; border-left: 4px solid #5C8762; padding: 20px; margin: 20px 0; border-radius: 4px;">
+  <p style="margin: 0;"><strong>Aktuelle Version:</strong> {{current_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Neue Version:</strong> {{new_version}}</p>
+  <p style="margin: 10px 0 0 0;"><strong>Kanal:</strong> {{channel}}</p>
+</div>
+
+<h3>Was ist neu?</h3>
+<p>Schauen Sie sich die Versionshinweise an, um zu sehen, was in diesem Update enthalten ist:</p>
+
+<div style="text-align: center; margin: 30px 0;">
+  <a href="{{release_notes_url}}" style="display: inline-block; padding: 14px 35px; background-color: #5C8762; color: white; text-decoration: none; border-radius: 5px; font-weight: 600; font-size: 16px;">Versionshinweise anzeigen</a>
+</div>
+
+<h3>So aktualisieren Sie</h3>
+<p>Um Ihre Installation zu aktualisieren, melden Sie sich im Admin-Panel an und klicken Sie auf die Benachrichtigung "Update verfugbar". Dort finden Sie umgebungsspezifische Anweisungen.</p>
+
+<div style="background-color: #fff3cd; border: 1px solid #ffeaa7; color: #856404; padding: 15px; border-radius: 4px; margin: 20px 0;">
+  <p style="margin: 0;"><strong>Erinnerung:</strong> Erstellen Sie immer ein Backup Ihrer Datenbank, bevor Sie aktualisieren, um sicherzustellen, dass Sie im Fehlerfall wiederherstellen konnen.</p>
+</div>
+
+<p>Mit freundlichen Grussen,<br>
+Ihre PicPeak-Installation</p>`,
+      body_text_de: `Eine neue Version von PicPeak ist verfugbar
+
+Gute Neuigkeiten! Eine neue Version von PicPeak ist fur Ihre Installation verfugbar.
+
+Aktuelle Version: {{current_version}}
+Neue Version: {{new_version}}
+Kanal: {{channel}}
+
+Was ist neu?
+Schauen Sie sich die Versionshinweise an, um zu sehen, was in diesem Update enthalten ist:
+{{release_notes_url}}
+
+So aktualisieren Sie
+Um Ihre Installation zu aktualisieren, melden Sie sich im Admin-Panel an und klicken Sie auf die Benachrichtigung "Update verfugbar". Dort finden Sie umgebungsspezifische Anweisungen.
+
+ERINNERUNG: Erstellen Sie immer ein Backup Ihrer Datenbank, bevor Sie aktualisieren, um sicherzustellen, dass Sie im Fehlerfall wiederherstellen konnen.
+
+Mit freundlichen Grussen,
+Ihre PicPeak-Installation`,
+      variables: JSON.stringify(['current_version', 'new_version', 'channel', 'release_notes_url'])
+    });
+  }
+
+  console.log('Migration 070_add_update_notification_settings completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 070_add_update_notification_settings');
+
+  // Remove settings
+  await knex('app_settings')
+    .whereIn('setting_key', [
+      'update_email_notifications_enabled',
+      'update_email_recipients',
+      'last_notified_version'
+    ])
+    .del();
+
+  // Remove email template
+  await knex('email_templates')
+    .where('template_key', 'version_update_available')
+    .del();
+};

backend/migrations/core/071_add_captured_at.js

@@ -0,0 +1,42 @@
+/**
+ * Migration 071: Add captured_at column to photos table
+ * - Stores the original capture date from EXIF metadata
+ * - Enables sorting photos by capture date instead of upload date
+ */
+
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 071_add_captured_at');
+
+  // Add captured_at column to photos table
+  await addColumnIfNotExists(knex, 'photos', 'captured_at', (table) => {
+    table.datetime('captured_at').nullable();
+  });
+
+  // Add index for sorting performance
+  const indexExists = await knex.schema.hasIndex
+    ? await knex.schema.hasIndex('photos', 'idx_photos_captured_at')
+    : false;
+
+  if (!indexExists) {
+    // Use raw query for index creation with IF NOT EXISTS
+    const client = knex.client.config.client;
+    if (client === 'pg') {
+      await knex.raw('CREATE INDEX IF NOT EXISTS idx_photos_captured_at ON photos(captured_at)');
+    } else if (client === 'sqlite3' || client === 'better-sqlite3') {
+      // SQLite doesn't support IF NOT EXISTS for indexes, so we need to check first
+      const existingIndexes = await knex.raw("SELECT name FROM sqlite_master WHERE type='index' AND name='idx_photos_captured_at'");
+      if (existingIndexes.length === 0) {
+        await knex.raw('CREATE INDEX idx_photos_captured_at ON photos(captured_at)');
+      }
+    }
+  }
+
+  console.log('Migration 071_add_captured_at completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 071_add_captured_at');
+  // Keep column for safe rollback (intentionally no-op)
+};

backend/migrations/core/073_make_event_emails_nullable.js

@@ -0,0 +1,13 @@
+exports.up = async function(knex) {
+  await knex.schema.alterTable('events', (table) => {
+    table.string('host_email', 255).nullable().alter();
+    table.string('admin_email', 255).nullable().alter();
+  });
+};
+
+exports.down = async function(knex) {
+  await knex.schema.alterTable('events', (table) => {
+    table.string('host_email', 255).notNullable().defaultTo('').alter();
+    table.string('admin_email', 255).notNullable().defaultTo('').alter();
+  });
+};

backend/migrations/core/074_add_photo_cap.js

@@ -0,0 +1,13 @@
+const { addColumnIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  console.log('Running migration: 074_add_photo_cap');
+  await addColumnIfNotExists(knex, 'events', 'photo_cap', (table) => {
+    table.integer('photo_cap').nullable().defaultTo(null);
+  });
+  console.log('Migration 074_add_photo_cap completed');
+};
+
+exports.down = async function(knex) {
+  console.log('Rollback: 074_add_photo_cap');
+};

backend/migrations/core/074_photo_visibility_client_access.js

@@ -0,0 +1,28 @@
+const { addColumnIfNotExists, createIndexIfNotExists } = require('../helpers');
+
+exports.up = async function(knex) {
+  // Add visibility column to photos table
+  await addColumnIfNotExists(knex, 'photos', 'visibility', (table) => {
+    table.string('visibility', 20).defaultTo('visible').notNullable();
+  });
+
+  // Add client access columns to events table
+  await addColumnIfNotExists(knex, 'events', 'client_access_enabled', (table) => {
+    table.boolean('client_access_enabled').defaultTo(false);
+  });
+
+  await addColumnIfNotExists(knex, 'events', 'client_password_hash', (table) => {
+    table.string('client_password_hash', 255).nullable();
+  });
+
+  await addColumnIfNotExists(knex, 'events', 'client_share_token', (table) => {
+    table.string('client_share_token', 64).nullable().unique();
+  });
+
+  // Index for filtering photos by visibility
+  await createIndexIfNotExists(knex, 'photos', ['event_id', 'visibility'], 'idx_photos_event_visibility');
+};
+
+exports.down = async function(knex) {
+  // Safe rollback - intentionally no-op to avoid data loss
+};

backend/migrations/core/075_email_template_translations.js

@@ -0,0 +1,281 @@
+/**
+ * Migration to create email_template_translations table
+ * Moves from per-column language support (subject_en, subject_de) to a
+ * normalized translations table where each language is a row.
+ * This allows adding new languages without schema changes.
+ */
+exports.up = async function(knex) {
+  // 1. Create the email_template_translations table
+  await knex.schema.createTable('email_template_translations', (table) => {
+    table.increments('id').primary();
+    table.integer('template_id').unsigned().notNullable()
+      .references('id').inTable('email_templates').onDelete('CASCADE');
+    table.string('language', 10).notNullable();
+    table.text('subject');
+    table.text('body_html');
+    table.text('body_text');
+    table.datetime('created_at').defaultTo(knex.fn.now());
+    table.datetime('updated_at').defaultTo(knex.fn.now());
+    table.unique(['template_id', 'language']);
+  });
+
+  console.log('Created email_template_translations table');
+
+  // 2. Migrate existing data from email_templates columns into rows
+  const templates = await knex('email_templates').select('*');
+  const columnInfo = await knex('email_templates').columnInfo();
+  const hasLangColumns = !!columnInfo.subject_en;
+
+  for (const template of templates) {
+    // Extract EN translation
+    const enSubject = hasLangColumns
+      ? (template.subject_en || template.subject || '')
+      : (template.subject || '');
+    const enHtml = hasLangColumns
+      ? (template.body_html_en || template.body_html || '')
+      : (template.body_html || '');
+    const enText = hasLangColumns
+      ? (template.body_text_en || template.body_text || '')
+      : (template.body_text || '');
+
+    // Insert EN translation
+    if (enSubject || enHtml) {
+      await knex('email_template_translations').insert({
+        template_id: template.id,
+        language: 'en',
+        subject: enSubject,
+        body_html: enHtml,
+        body_text: enText,
+        created_at: new Date(),
+        updated_at: new Date(),
+      });
+    }
+
+    // Extract DE translation (only if lang columns exist)
+    if (hasLangColumns) {
+      const deSubject = template.subject_de || '';
+      const deHtml = template.body_html_de || '';
+      const deText = template.body_text_de || '';
+
+      // Only insert if DE content differs from EN or has content
+      if (deSubject || deHtml) {
+        await knex('email_template_translations').insert({
+          template_id: template.id,
+          language: 'de',
+          subject: deSubject,
+          body_html: deHtml,
+          body_text: deText,
+          created_at: new Date(),
+          updated_at: new Date(),
+        });
+      }
+    }
+  }
+
+  console.log(`Migrated ${templates.length} templates to translations table`);
+
+  // 3. Seed NL, PT, RU translations for customer-facing templates
+  // Look up template IDs
+  const customerTemplates = await knex('email_templates')
+    .whereIn('template_key', [
+      'gallery_created', 'expiration_warning', 'gallery_expired', 'archive_complete'
+    ])
+    .select('id', 'template_key');
+
+  const templateMap = {};
+  customerTemplates.forEach(t => { templateMap[t.template_key] = t.id; });
+
+  const seedTranslations = [];
+
+  // --- gallery_created ---
+  if (templateMap.gallery_created) {
+    const id = templateMap.gallery_created;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Uw fotogalerij is klaar!',
+        body_html: `<h2>Galerij succesvol aangemaakt</h2>
+<p>Beste {{host_name}},</p>
+<p>Uw fotogalerij "{{event_name}}" is succesvol aangemaakt!</p>
+<p><strong>Galerij details:</strong></p>
+<ul>
+  <li>Evenementdatum: {{event_date}}</li>
+  <li>Galerij link: <a href="{{gallery_link}}">{{gallery_link}}</a></li>
+  <li>Wachtwoord: {{gallery_password}}</li>
+  <li>Verloopt op: {{expiry_date}}</li>
+</ul>
+<p>Deel deze link en het wachtwoord met uw gasten zodat zij de foto's kunnen bekijken en downloaden.</p>
+{{#if welcome_message}}<p><em>{{welcome_message}}</em></p>{{/if}}`,
+        body_text: `Galerij succesvol aangemaakt\n\nBeste {{host_name}},\n\nUw fotogalerij "{{event_name}}" is succesvol aangemaakt!\n\nGalerij link: {{gallery_link}}\nWachtwoord: {{gallery_password}}\nVerloopt op: {{expiry_date}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Sua galeria de fotos está pronta!',
+        body_html: `<h2>Galeria criada com sucesso</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>Sua galeria de fotos "{{event_name}}" foi criada com sucesso!</p>
+<p><strong>Detalhes da galeria:</strong></p>
+<ul>
+  <li>Data do evento: {{event_date}}</li>
+  <li>Link da galeria: <a href="{{gallery_link}}">{{gallery_link}}</a></li>
+  <li>Senha: {{gallery_password}}</li>
+  <li>Expira em: {{expiry_date}}</li>
+</ul>
+<p>Compartilhe este link e senha com seus convidados para que possam visualizar e baixar as fotos.</p>
+{{#if welcome_message}}<p><em>{{welcome_message}}</em></p>{{/if}}`,
+        body_text: `Galeria criada com sucesso\n\nPrezado(a) {{host_name}},\n\nSua galeria de fotos "{{event_name}}" foi criada com sucesso!\n\nLink da galeria: {{gallery_link}}\nSenha: {{gallery_password}}\nExpira em: {{expiry_date}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Ваша фотогалерея готова!',
+        body_html: `<h2>Галерея успешно создана</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Ваша фотогалерея "{{event_name}}" была успешно создана!</p>
+<p><strong>Детали галереи:</strong></p>
+<ul>
+  <li>Дата события: {{event_date}}</li>
+  <li>Ссылка на галерею: <a href="{{gallery_link}}">{{gallery_link}}</a></li>
+  <li>Пароль: {{gallery_password}}</li>
+  <li>Срок действия: {{expiry_date}}</li>
+</ul>
+<p>Поделитесь этой ссылкой и паролем с вашими гостями, чтобы они могли просматривать и скачивать фотографии.</p>
+{{#if welcome_message}}<p><em>{{welcome_message}}</em></p>{{/if}}`,
+        body_text: `Галерея успешно создана\n\nУважаемый(ая) {{host_name}},\n\nВаша фотогалерея "{{event_name}}" была успешно создана!\n\nСсылка: {{gallery_link}}\nПароль: {{gallery_password}}\nСрок действия: {{expiry_date}}`,
+      },
+    );
+  }
+
+  // --- expiration_warning ---
+  if (templateMap.expiration_warning) {
+    const id = templateMap.expiration_warning;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Uw fotogalerij verloopt binnenkort',
+        body_html: `<h2>Galerij verloopt binnenkort</h2>
+<p>Beste {{host_name}},</p>
+<p>Uw fotogalerij "{{event_name}}" verloopt over {{days_remaining}} dagen.</p>
+<p>Na het verlopen wordt de galerij gearchiveerd en is niet meer toegankelijk voor gasten.</p>
+<p><a href="{{gallery_link}}">Galerij bezoeken</a></p>`,
+        body_text: `Galerij verloopt binnenkort\n\nBeste {{host_name}},\n\nUw fotogalerij "{{event_name}}" verloopt over {{days_remaining}} dagen.\n\nGalerij: {{gallery_link}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Sua galeria de fotos expira em breve',
+        body_html: `<h2>Galeria expirando em breve</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>Sua galeria de fotos "{{event_name}}" expirará em {{days_remaining}} dias.</p>
+<p>Após a expiração, a galeria será arquivada e não estará mais acessível aos convidados.</p>
+<p><a href="{{gallery_link}}">Visitar galeria</a></p>`,
+        body_text: `Galeria expirando em breve\n\nPrezado(a) {{host_name}},\n\nSua galeria de fotos "{{event_name}}" expirará em {{days_remaining}} dias.\n\nGaleria: {{gallery_link}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Срок действия вашей фотогалереи скоро истекает',
+        body_html: `<h2>Срок действия галереи истекает</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Срок действия вашей фотогалереи "{{event_name}}" истекает через {{days_remaining}} дней.</p>
+<p>После истечения срока галерея будет архивирована и станет недоступна для гостей.</p>
+<p><a href="{{gallery_link}}">Перейти в галерею</a></p>`,
+        body_text: `Срок действия галереи истекает\n\nУважаемый(ая) {{host_name}},\n\nСрок действия вашей фотогалереи "{{event_name}}" истекает через {{days_remaining}} дней.\n\nГалерея: {{gallery_link}}`,
+      },
+    );
+  }
+
+  // --- gallery_expired ---
+  if (templateMap.gallery_expired) {
+    const id = templateMap.gallery_expired;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Uw fotogalerij {{event_name}} is verlopen',
+        body_html: `<h2>Galerij verlopen</h2>
+<p>Beste {{host_name}},</p>
+<p>Uw fotogalerij "{{event_name}}" is verlopen en niet meer toegankelijk.</p>
+<p>De foto's zijn gearchiveerd. Als u toegang nodig heeft, neem dan contact op met de beheerder via {{admin_email}}.</p>`,
+        body_text: `Galerij verlopen\n\nBeste {{host_name}},\n\nUw fotogalerij "{{event_name}}" is verlopen en niet meer toegankelijk.\n\nNeem contact op met: {{admin_email}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Sua galeria de fotos {{event_name}} expirou',
+        body_html: `<h2>Galeria expirada</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>Sua galeria de fotos "{{event_name}}" expirou e não está mais acessível.</p>
+<p>As fotos foram arquivadas. Se precisar de acesso, entre em contato com o administrador em {{admin_email}}.</p>`,
+        body_text: `Galeria expirada\n\nPrezado(a) {{host_name}},\n\nSua galeria de fotos "{{event_name}}" expirou e não está mais acessível.\n\nContato: {{admin_email}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Срок действия фотогалереи {{event_name}} истёк',
+        body_html: `<h2>Срок действия галереи истёк</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Срок действия вашей фотогалереи "{{event_name}}" истёк, и она больше недоступна.</p>
+<p>Фотографии были архивированы. Если вам нужен доступ, свяжитесь с администратором: {{admin_email}}.</p>`,
+        body_text: `Срок действия галереи истёк\n\nУважаемый(ая) {{host_name}},\n\nСрок действия вашей фотогалереи "{{event_name}}" истёк.\n\nКонтакт: {{admin_email}}`,
+      },
+    );
+  }
+
+  // --- archive_complete ---
+  if (templateMap.archive_complete) {
+    const id = templateMap.archive_complete;
+    seedTranslations.push(
+      {
+        template_id: id, language: 'nl',
+        subject: 'Archivering voltooid: {{event_name}}',
+        body_html: `<h2>Archivering voltooid</h2>
+<p>Beste {{host_name}},</p>
+<p>De fotogalerij "{{event_name}}" is succesvol gearchiveerd.</p>
+<p><strong>Archief details:</strong></p>
+<ul>
+  <li>Aantal foto's: {{photo_count}}</li>
+  <li>Archiefgrootte: {{archive_size}}</li>
+  <li>Archiefdatum: {{archive_date}}</li>
+</ul>`,
+        body_text: `Archivering voltooid\n\nBeste {{host_name}},\n\nDe fotogalerij "{{event_name}}" is succesvol gearchiveerd.\n\nAantal foto's: {{photo_count}}\nGrootte: {{archive_size}}`,
+      },
+      {
+        template_id: id, language: 'pt',
+        subject: 'Arquivamento concluído: {{event_name}}',
+        body_html: `<h2>Arquivamento concluído</h2>
+<p>Prezado(a) {{host_name}},</p>
+<p>A galeria de fotos "{{event_name}}" foi arquivada com sucesso.</p>
+<p><strong>Detalhes do arquivo:</strong></p>
+<ul>
+  <li>Número de fotos: {{photo_count}}</li>
+  <li>Tamanho do arquivo: {{archive_size}}</li>
+  <li>Data do arquivamento: {{archive_date}}</li>
+</ul>`,
+        body_text: `Arquivamento concluído\n\nPrezado(a) {{host_name}},\n\nA galeria de fotos "{{event_name}}" foi arquivada com sucesso.\n\nFotos: {{photo_count}}\nTamanho: {{archive_size}}`,
+      },
+      {
+        template_id: id, language: 'ru',
+        subject: 'Архивация завершена: {{event_name}}',
+        body_html: `<h2>Архивация завершена</h2>
+<p>Уважаемый(ая) {{host_name}},</p>
+<p>Фотогалерея "{{event_name}}" была успешно архивирована.</p>
+<p><strong>Детали архива:</strong></p>
+<ul>
+  <li>Количество фото: {{photo_count}}</li>
+  <li>Размер архива: {{archive_size}}</li>
+  <li>Дата архивации: {{archive_date}}</li>
+</ul>`,
+        body_text: `Архивация завершена\n\nУважаемый(ая) {{host_name}},\n\nФотогалерея "{{event_name}}" была успешно архивирована.\n\nФото: {{photo_count}}\nРазмер: {{archive_size}}`,
+      },
+    );
+  }
+
+  // Insert all seed translations
+  const now = new Date();
+  for (const trans of seedTranslations) {
+    trans.created_at = now;
+    trans.updated_at = now;
+    await knex('email_template_translations').insert(trans);
+  }
+
+  console.log(`Seeded ${seedTranslations.length} translations for customer-facing templates`);
+};
+
+exports.down = async function(knex) {
+  await knex.schema.dropTableIfExists('email_template_translations');
+};

backend/migrations/core/076_add_is_draft_column.js

@@ -0,0 +1,21 @@
+/**
+ * Migration to add is_draft column to events table.
+ * Draft events are not visible to gallery visitors until published.
+ */
+exports.up = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'is_draft');
+  if (!hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.boolean('is_draft').defaultTo(false);
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'is_draft');
+  if (hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('is_draft');
+    });
+  }
+};

backend/migrations/core/077_add_default_photo_sort.js

@@ -0,0 +1,17 @@
+exports.up = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'default_photo_sort');
+  if (!hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.string('default_photo_sort', 50).defaultTo('upload_date_desc');
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'default_photo_sort');
+  if (hasColumn) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('default_photo_sort');
+    });
+  }
+};

backend/migrations/core/078_add_guest_identity.js

@@ -0,0 +1,120 @@
+/**
+ * Add guest identity layer for per-person photo selections (issue #292).
+ *
+ * Adds:
+ *   - gallery_guests              — persistent guest profiles per event
+ *   - guest_invites               — pre-minted invite tokens (Phase 3.3)
+ *   - guest_verification_codes    — email-based identity recovery (Phase 3.2)
+ *   - event_feedback_settings.identity_mode ('simple' | 'guest', default 'simple')
+ *   - photo_feedback.guest_id FK  — links feedback to gallery_guests (nullable)
+ *
+ * All changes are additive. Existing events default to 'simple' mode so behavior
+ * is unchanged. Legacy photo_feedback rows keep NULL guest_id.
+ */
+
+exports.up = async function(knex) {
+  // 1. gallery_guests — persistent per-person identity within an event.
+  const hasGalleryGuests = await knex.schema.hasTable('gallery_guests');
+  if (!hasGalleryGuests) {
+    await knex.schema.createTable('gallery_guests', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').notNullable().references('id').inTable('events').onDelete('CASCADE');
+      table.string('name', 100).notNullable();
+      table.string('email', 255);
+      table.string('identifier', 64).notNullable(); // UUIDv4 issued server-side
+      table.string('ip_address_last', 45);
+      table.text('user_agent_last');
+      table.timestamp('email_verified_at');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('last_seen_at').defaultTo(knex.fn.now());
+      table.boolean('is_deleted').defaultTo(false);
+
+      table.unique(['event_id', 'identifier']);
+      table.index(['event_id']);
+      table.index(['event_id', 'email']);
+    });
+  }
+
+  // 2. guest_invites — pre-minted one-time-use tokens for invited guests.
+  const hasGuestInvites = await knex.schema.hasTable('guest_invites');
+  if (!hasGuestInvites) {
+    await knex.schema.createTable('guest_invites', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').notNullable().references('id').inTable('events').onDelete('CASCADE');
+      table.integer('guest_id').notNullable().references('id').inTable('gallery_guests').onDelete('CASCADE');
+      table.string('token', 64).notNullable().unique();
+      table.integer('created_by_admin_id').references('id').inTable('admin_users');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('redeemed_at');
+      table.timestamp('revoked_at');
+
+      table.index(['event_id']);
+      table.index(['guest_id']);
+    });
+  }
+
+  // 3. guest_verification_codes — short-lived codes for email-based recovery.
+  const hasGuestVerificationCodes = await knex.schema.hasTable('guest_verification_codes');
+  if (!hasGuestVerificationCodes) {
+    await knex.schema.createTable('guest_verification_codes', (table) => {
+      table.increments('id').primary();
+      table.integer('event_id').notNullable().references('id').inTable('events').onDelete('CASCADE');
+      table.string('email', 255).notNullable();
+      table.string('code_hash', 128).notNullable(); // bcrypt hash of 6-digit code
+      table.integer('attempts').defaultTo(0);
+      table.timestamp('expires_at').notNullable();
+      table.timestamp('consumed_at');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+
+      table.index(['event_id', 'email']);
+      table.index(['expires_at']);
+    });
+  }
+
+  // 4. event_feedback_settings.identity_mode
+  const hasIdentityMode = await knex.schema.hasColumn('event_feedback_settings', 'identity_mode');
+  if (!hasIdentityMode) {
+    await knex.schema.alterTable('event_feedback_settings', (table) => {
+      table.string('identity_mode', 16).notNullable().defaultTo('simple');
+    });
+    if (knex.client.config.client === 'pg') {
+      await knex.raw(`
+        ALTER TABLE event_feedback_settings
+        ADD CONSTRAINT event_feedback_settings_identity_mode_check
+        CHECK (identity_mode IN ('simple','guest'))
+      `);
+    }
+  }
+
+  // 5. photo_feedback.guest_id FK
+  const hasGuestIdColumn = await knex.schema.hasColumn('photo_feedback', 'guest_id');
+  if (!hasGuestIdColumn) {
+    await knex.schema.alterTable('photo_feedback', (table) => {
+      table.integer('guest_id').references('id').inTable('gallery_guests').onDelete('SET NULL');
+      table.index(['guest_id']);
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasGuestIdColumn = await knex.schema.hasColumn('photo_feedback', 'guest_id');
+  if (hasGuestIdColumn) {
+    await knex.schema.alterTable('photo_feedback', (table) => {
+      table.dropColumn('guest_id');
+    });
+  }
+
+  if (knex.client.config.client === 'pg') {
+    await knex.raw('ALTER TABLE event_feedback_settings DROP CONSTRAINT IF EXISTS event_feedback_settings_identity_mode_check');
+  }
+  const hasIdentityMode = await knex.schema.hasColumn('event_feedback_settings', 'identity_mode');
+  if (hasIdentityMode) {
+    await knex.schema.alterTable('event_feedback_settings', (table) => {
+      table.dropColumn('identity_mode');
+    });
+  }
+
+  await knex.schema.dropTableIfExists('guest_verification_codes');
+  await knex.schema.dropTableIfExists('guest_invites');
+  await knex.schema.dropTableIfExists('gallery_guests');
+};

backend/migrations/core/079_add_download_zip_cache.js

@@ -0,0 +1,26 @@
+/**
+ * Add download ZIP cache columns to events table.
+ *
+ * Enables pre-generated ZIP files for "Download All" so guests get
+ * instant downloads with Content-Length instead of on-the-fly streaming.
+ */
+
+exports.up = async function(knex) {
+  const hasZipPath = await knex.schema.hasColumn('events', 'download_zip_path');
+  if (!hasZipPath) {
+    await knex.schema.alterTable('events', (table) => {
+      table.text('download_zip_path').nullable().defaultTo(null);
+      table.datetime('download_zip_generated_at').nullable().defaultTo(null);
+    });
+  }
+};
+
+exports.down = async function(knex) {
+  const hasZipPath = await knex.schema.hasColumn('events', 'download_zip_path');
+  if (hasZipPath) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('download_zip_path');
+      table.dropColumn('download_zip_generated_at');
+    });
+  }
+};

backend/migrations/core/080_add_customer_phone.js

@@ -0,0 +1,33 @@
+const { addColumnIfNotExists } = require('../helpers');
+
+/**
+ * #322 — optional phone-number field on events. Off by default; surfaced
+ * only when the global `event_phone_field_enabled` app setting is true,
+ * so existing deployments see no UI change unless the admin opts in.
+ */
+exports.up = async function up(knex) {
+  await addColumnIfNotExists(knex, 'events', 'customer_phone', (table) => {
+    table.string('customer_phone', 32).nullable();
+  });
+
+  // Seed the global enable flag (default false).
+  const exists = await knex('app_settings')
+    .where('setting_key', 'event_phone_field_enabled')
+    .first();
+  if (!exists) {
+    await knex('app_settings').insert({
+      setting_key: 'event_phone_field_enabled',
+      setting_value: JSON.stringify(false),
+      setting_type: 'boolean'
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasColumn('events', 'customer_phone')) {
+    await knex.schema.alterTable('events', (table) => {
+      table.dropColumn('customer_phone');
+    });
+  }
+  await knex('app_settings').where('setting_key', 'event_phone_field_enabled').delete();
+};

backend/migrations/core/081_add_api_tokens.js

@@ -0,0 +1,41 @@
+/**
+ * #322 — long-lived API tokens for programmatic access (n8n, custom
+ * integrations, external apps). Each token belongs to an admin user; the
+ * token's effective permissions are the *intersection* of the user's
+ * role permissions and the token's own scope flags. That way revoking
+ * the user revokes the token, and scope flags let an admin issue a
+ * read-only token even if their account is super_admin.
+ */
+
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable('api_tokens'))) {
+    await knex.schema.createTable('api_tokens', (table) => {
+      table.increments('id').primary();
+      table.string('name', 100).notNullable();
+      // SHA-256 of the full token string (`pp_live_<random>`). Lookup
+      // hashes the incoming Authorization header and queries by this.
+      table.string('hashed_token', 64).notNullable().unique();
+      // Scope flags — comma-separated subset of: read, write, admin.
+      // 'read' allows GETs; 'write' adds POST/PATCH/DELETE on
+      // event/photo data; 'admin' allows creating/deleting events and
+      // anything else gated by admin.* permissions.
+      table.string('scopes', 64).notNullable().defaultTo('read');
+      table.integer('created_by').notNullable()
+        .references('id').inTable('admin_users').onDelete('CASCADE');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('expires_at').nullable();
+      table.timestamp('last_used_at').nullable();
+      table.timestamp('revoked_at').nullable();
+      // Cosmetic for the admin UI: first 8 chars of the plaintext
+      // token (after the prefix) so admins can identify which token is
+      // which without seeing the secret half.
+      table.string('preview', 16).nullable();
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasTable('api_tokens')) {
+    await knex.schema.dropTable('api_tokens');
+  }
+};

backend/migrations/core/082_add_webhooks.js

@@ -0,0 +1,80 @@
+/**
+ * #327 — outbound webhooks (push API) for the event/photo lifecycle.
+ *
+ * Two tables:
+ *   webhooks                — admin-managed subscriptions (URL + events + secret)
+ *   webhook_deliveries      — single source of truth for the delivery worker
+ *                              (audit log + retry queue in one).
+ */
+
+exports.up = async function up(knex) {
+  if (!(await knex.schema.hasTable('webhooks'))) {
+    await knex.schema.createTable('webhooks', (table) => {
+      table.increments('id').primary();
+      table.string('name', 100).notNullable();
+      // Validated via networkValidation.validateExternalUrl on create + per
+      // delivery (DNS-rebinding mitigation).
+      table.string('url', 2048).notNullable();
+      // Plaintext signing secret (`whsec_<random>`). Stored unencrypted
+      // because we need to recompute HMAC-SHA256 over every outbound body
+      // — a hash would make the secret unrecoverable. Same posture as
+      // SMTP passwords stored in app_settings; protect the DB. The
+      // plaintext is also returned to the admin once on create so they can
+      // configure the receiver to verify signatures.
+      table.string('secret', 100).notNullable();
+      // First 8 chars of the secret for the admin UI so operators can
+      // tell which webhook is which without revealing the full secret.
+      table.string('secret_preview', 16).nullable();
+      // JSON array of subscribed event types
+      // (e.g. ["event.published","photo.uploaded"]).
+      table.jsonb('events').notNullable().defaultTo('[]');
+      table.boolean('active').notNullable().defaultTo(true);
+      table.integer('created_by').notNullable()
+        .references('id').inTable('admin_users').onDelete('CASCADE');
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('updated_at').defaultTo(knex.fn.now());
+      table.timestamp('last_success_at').nullable();
+      table.timestamp('last_failure_at').nullable();
+      // Index for the delivery worker's "find subscriptions for this event"
+      // query — small set, but keeps the lookup constant-time as it grows.
+      table.index('active', 'webhooks_active_idx');
+    });
+  }
+
+  if (!(await knex.schema.hasTable('webhook_deliveries'))) {
+    await knex.schema.createTable('webhook_deliveries', (table) => {
+      table.increments('id').primary();
+      table.integer('webhook_id').notNullable()
+        .references('id').inTable('webhooks').onDelete('CASCADE');
+      table.string('event_type', 64).notNullable();
+      // Full signed payload (the JSON body that was POSTed).
+      table.jsonb('payload').notNullable();
+      table.integer('attempt_count').notNullable().defaultTo(0);
+      // pending → success | failed. pending rows with next_retry_at <= NOW()
+      // are picked up by the worker.
+      table.string('status', 16).notNullable().defaultTo('pending');
+      table.integer('response_status').nullable();
+      // Truncated to 1KB before storage so a verbose receiver can't blow
+      // up the row size.
+      table.text('response_body').nullable();
+      table.text('last_error').nullable();
+      table.integer('latency_ms').nullable();
+      table.timestamp('next_retry_at').nullable();
+      table.timestamp('created_at').defaultTo(knex.fn.now());
+      table.timestamp('completed_at').nullable();
+      // Worker hot-path query: WHERE status='pending' AND next_retry_at <= NOW()
+      // ORDER BY next_retry_at LIMIT N. This composite index serves it directly.
+      table.index(['status', 'next_retry_at'], 'webhook_deliveries_status_retry_idx');
+      table.index('webhook_id', 'webhook_deliveries_webhook_idx');
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasTable('webhook_deliveries')) {
+    await knex.schema.dropTable('webhook_deliveries');
+  }
+  if (await knex.schema.hasTable('webhooks')) {
+    await knex.schema.dropTable('webhooks');
+  }
+};

backend/migrations/core/083_add_presigned_and_webhook_extras.js

@@ -0,0 +1,49 @@
+/**
+ * Adds:
+ *   - events.allow_presigned_download — per-event opt-in for the
+ *     presigned-URL "Download All" path (#328 follow-up). Off by default
+ *     because it bypasses watermarks; admins flip it knowingly.
+ *   - webhooks.filter — JSONB predicate evaluated against the payload at
+ *     fire time (#327 follow-up). Empty object = no filter, fire always.
+ *   - webhooks.template — optional ${dot.path} string template applied
+ *     to the request body before signing. NULL = use the default JSON
+ *     envelope (back-compat).
+ */
+
+exports.up = async function up(knex) {
+  if (await knex.schema.hasTable('events')) {
+    const hasCol = await knex.schema.hasColumn('events', 'allow_presigned_download');
+    if (!hasCol) {
+      await knex.schema.alterTable('events', (table) => {
+        table.boolean('allow_presigned_download').notNullable().defaultTo(false);
+      });
+    }
+  }
+
+  if (await knex.schema.hasTable('webhooks')) {
+    const hasFilter = await knex.schema.hasColumn('webhooks', 'filter');
+    if (!hasFilter) {
+      await knex.schema.alterTable('webhooks', (table) => {
+        table.jsonb('filter').notNullable().defaultTo('{}');
+      });
+    }
+    const hasTemplate = await knex.schema.hasColumn('webhooks', 'template');
+    if (!hasTemplate) {
+      await knex.schema.alterTable('webhooks', (table) => {
+        table.text('template').nullable();
+      });
+    }
+  }
+};
+
+exports.down = async function down(knex) {
+  if (await knex.schema.hasColumn('webhooks', 'template')) {
+    await knex.schema.alterTable('webhooks', (t) => t.dropColumn('template'));
+  }
+  if (await knex.schema.hasColumn('webhooks', 'filter')) {
+    await knex.schema.alterTable('webhooks', (t) => t.dropColumn('filter'));
+  }
+  if (await knex.schema.hasColumn('events', 'allow_presigned_download')) {
+    await knex.schema.alterTable('events', (t) => t.dropColumn('allow_presigned_download'));
+  }
+};

backend/migrations/legacy/006_add_photo_counter_to_categories.js

@@ -1,22 +1,27 @@
 exports.up = async function(knex) {
-  // Add photo_counter column to photo_categories table
-  await knex.schema.alterTable('photo_categories', function(table) {
-    table.integer('photo_counter').defaultTo(0).notNullable();
-  });
+  // Check if photo_counter column already exists to make migration idempotent
+  const hasPhotoCounter = await knex.schema.hasColumn('photo_categories', 'photo_counter');
 
-  // Initialize counters based on existing photos
-  const categories = await knex('photo_categories').select('id');
-  
-  for (const category of categories) {
-    const photoCount = await knex('photos')
-      .where('category_id', category.id)
-      .count('id as count')
-      .first();
-    
-    if (photoCount && photoCount.count > 0) {
-      await knex('photo_categories')
-        .where('id', category.id)
-        .update({ photo_counter: photoCount.count });
+  if (!hasPhotoCounter) {
+    // Add photo_counter column to photo_categories table
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.integer('photo_counter').defaultTo(0).notNullable();
+    });
+
+    // Initialize counters based on existing photos
+    const categories = await knex('photo_categories').select('id');
+
+    for (const category of categories) {
+      const photoCount = await knex('photos')
+        .where('category_id', category.id)
+        .count('id as count')
+        .first();
+
+      if (photoCount && photoCount.count > 0) {
+        await knex('photo_categories')
+          .where('id', category.id)
+          .update({ photo_counter: photoCount.count });
+      }
     }
   }
 };

backend/migrations/legacy/008_add_language_support_to_email_templates.js

@@ -1,23 +1,33 @@
 exports.up = async function(knex) {
-  // Add language-specific columns to email_templates
-  await knex.schema.alterTable('email_templates', function(table) {
-    // Add English versions (rename existing columns for consistency)
-    table.renameColumn('subject', 'subject_en');
-    table.renameColumn('body_html', 'body_html_en');
-    table.renameColumn('body_text', 'body_text_en');
-    
-    // Add German versions
-    table.string('subject_de');
-    table.text('body_html_de');
-    table.text('body_text_de');
-  });
+  // Check which columns already exist to make migration idempotent
+  const hasSubjectEn = await knex.schema.hasColumn('email_templates', 'subject_en');
+  const hasSubjectDe = await knex.schema.hasColumn('email_templates', 'subject_de');
+  const hasSubjectOriginal = await knex.schema.hasColumn('email_templates', 'subject');
 
-  // Copy existing values to German columns as defaults
-  await knex('email_templates').update({
-    subject_de: knex.raw('subject_en'),
-    body_html_de: knex.raw('body_html_en'),
-    body_text_de: knex.raw('body_text_en')
-  });
+  // Only rename columns if they haven't been renamed yet
+  if (hasSubjectOriginal && !hasSubjectEn) {
+    await knex.schema.alterTable('email_templates', function(table) {
+      table.renameColumn('subject', 'subject_en');
+      table.renameColumn('body_html', 'body_html_en');
+      table.renameColumn('body_text', 'body_text_en');
+    });
+  }
+
+  // Only add German columns if they don't exist
+  if (!hasSubjectDe) {
+    await knex.schema.alterTable('email_templates', function(table) {
+      table.string('subject_de');
+      table.text('body_html_de');
+      table.text('body_text_de');
+    });
+
+    // Copy existing values to German columns as defaults
+    await knex('email_templates').update({
+      subject_de: knex.raw('subject_en'),
+      body_html_de: knex.raw('body_html_en'),
+      body_text_de: knex.raw('body_text_en')
+    });
+  }
 };
 
 exports.down = async function(knex) {

backend/migrations/run-migrations-safe.js

@@ -67,26 +67,37 @@ async function runMigrationSafely(filepath) {
     const migrationPath = path.join(__dirname, filepath);
     const migration = require(migrationPath);
     const filename = path.basename(filepath);
-    
+
     if (migration.up) {
       console.log(`Running migration: ${filepath}`);
-      
+
       // Run migration in a transaction if possible
+      // IMPORTANT: Include the migrations table insert INSIDE the transaction
+      // to ensure atomicity between schema changes and tracking
       if (db.client.config.client === 'pg') {
         await db.transaction(async (trx) => {
           await migration.up(trx);
+          // Insert migration record inside transaction for atomicity
+          await trx('migrations').insert({ filename });
         });
       } else {
         await migration.up(db);
+        await db('migrations').insert({ filename });
       }
-      
-      await db('migrations').insert({ filename });
+
       console.log(`Migration ${filepath} completed successfully`);
     }
   } catch (error) {
     // Check if error is because schema already exists
-    if (error.code === '42P07' || // PostgreSQL: relation already exists
-        error.code === 'SQLITE_ERROR' && error.message.includes('already exists')) {
+    // PostgreSQL error codes:
+    // - 42P07: duplicate_table (relation already exists)
+    // - 42701: duplicate_column (column already exists)
+    // - 42710: duplicate_object (constraint, index, etc. already exists)
+    // - 23505: unique_violation (migration record already exists)
+    const schemaExistsErrors = ['42P07', '42701', '42710', '23505'];
+    const isSQLiteAlreadyExists = error.code === 'SQLITE_ERROR' && error.message.includes('already exists');
+
+    if (schemaExistsErrors.includes(error.code) || isSQLiteAlreadyExists) {
       console.log(`Migration ${filepath} - schema already exists, marking as applied`);
       await markMigrationAsApplied(path.basename(filepath));
     } else {

backend/migrations/run-migrations.js

@@ -26,11 +26,22 @@ async function runMigration(filepath) {
   const migrationPath = path.join(__dirname, filepath);
   const migration = require(migrationPath);
   const filename = path.basename(filepath);
-  
+
   if (migration.up) {
     console.log(`Running migration: ${filepath}`);
-    await migration.up(db);
-    await db('migrations').insert({ filename });
+
+    // Run migration in a transaction if PostgreSQL to ensure atomicity
+    // between schema changes and migration tracking
+    if (db.client.config.client === 'pg') {
+      await db.transaction(async (trx) => {
+        await migration.up(trx);
+        await trx('migrations').insert({ filename });
+      });
+    } else {
+      await migration.up(db);
+      await db('migrations').insert({ filename });
+    }
+
     console.log(`Migration ${filepath} completed`);
   }
 }

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "picpeak-backend",
-  "version": "2.3.1",
+  "version": "3.32.2-beta.0",
   "description": "Backend for PicPeak event photo sharing platform",
   "main": "server.js",
   "scripts": {
@@ -8,7 +8,9 @@
     "dev": "nodemon server.js",
     "migrate": "node migrations/run-migrations.js",
     "migrate:safe": "node migrations/run-migrations-safe.js",
+    "generate:watermarks": "node scripts/generate-watermarks.js",
     "test": "jest",
+    "test:s3": "SKIP_S3_TESTS=false jest __tests__/integration/backup-s3",
     "lint": "eslint src/"
   },
   "dependencies": {
@@ -18,18 +20,19 @@
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
     "adm-zip": "^0.5.16",
     "archiver": "^5.3.1",
-    "axios": "^1.12.2",
+    "axios": "1.14.0",
     "bcrypt": "6.0.0",
     "chokidar": "4.0.3",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
     "dotenv": "^16.0.3",
+    "exifr": "^7.1.3",
     "express": "^4.18.2",
     "express-rate-limit": "^6.7.0",
     "express-validator": "^7.0.1",
     "fluent-ffmpeg": "^2.1.3",
     "form-data": "^4.0.4",
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "helmet": "^7.0.0",
     "i18next": "25.3.2",
     "i18next-browser-languagedetector": "^8.2.0",
@@ -42,12 +45,14 @@
     "mime-types": "^3.0.1",
     "multer": "^2.0.2",
     "node-cron": "^3.0.2",
-    "nodemailer": "^7.0.10",
+    "nodemailer": "^7.0.13",
     "pg": "^8.16.3",
     "react-i18next": "^15.6.0",
     "sanitize-html": "^2.17.0",
     "sharp": "0.34.3",
     "sqlite3": "^5.1.6",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
     "uuid": "^11.1.0",
     "winston": "^3.8.2",
     "zxcvbn": "^4.4.2"
@@ -64,7 +69,13 @@
       "tar-fs": "2.1.4"
     },
     "glob": "^11.1.0",
-    "body-parser": "^2.2.1",
-    "js-yaml": "^4.1.1"
+    "js-yaml": "^4.1.1",
+    "fast-xml-parser": ">=5.5.10",
+    "qs": ">=6.14.2",
+    "tar": ">=7.5.13",
+    "brace-expansion": ">=5.0.5",
+    "minimatch": ">=9.0.7",
+    "path-to-regexp": "0.1.13",
+    "lodash": ">=4.18.1"
   }
 }

backend/scripts/create-admin.js

@@ -44,28 +44,39 @@ async function createAdmin() {
       .orWhere('username', username)
       .first();
 
-    if (existingUser) {
-      console.error(`Error: User with email "${email}" or username "${username}" already exists`);
-      process.exit(1);
-    }
-
     // Hash password
     const passwordHash = await bcrypt.hash(password, 10);
 
-    // Create admin user
-    await db('admin_users').insert({
-      username,
-      email,
-      password_hash: passwordHash,
-      is_active: true,
-      created_at: new Date(),
-      updated_at: new Date()
-    });
+    if (existingUser) {
+      // Update existing user's password
+      await db('admin_users')
+        .where('id', existingUser.id)
+        .update({
+          password_hash: passwordHash,
+          updated_at: new Date()
+        });
 
-    console.log(`✅ Admin user created successfully!`);
-    console.log(`   Email: ${email}`);
-    console.log(`   Username: ${username}`);
-    console.log(`   Login URL: ${process.env.ADMIN_URL || 'http://localhost:3000'}/admin/login`);
+      console.log(`✅ Admin user updated successfully!`);
+      console.log(`   Email: ${existingUser.email}`);
+      console.log(`   Username: ${existingUser.username}`);
+      console.log(`   Password has been reset to the provided value`);
+      console.log(`   Login URL: ${process.env.ADMIN_URL || 'http://localhost:3000'}/admin/login`);
+    } else {
+      // Create new admin user
+      await db('admin_users').insert({
+        username,
+        email,
+        password_hash: passwordHash,
+        is_active: true,
+        created_at: new Date(),
+        updated_at: new Date()
+      });
+
+      console.log(`✅ Admin user created successfully!`);
+      console.log(`   Email: ${email}`);
+      console.log(`   Username: ${username}`);
+      console.log(`   Login URL: ${process.env.ADMIN_URL || 'http://localhost:3000'}/admin/login`);
+    }
     
     process.exit(0);
   } catch (error) {

backend/scripts/generate-openapi.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Generate the OpenAPI spec from JSDoc annotations in src/routes/v1/* and
+ * write it as YAML + JSON to ../docs/. Used by scripts/sync-api-docs.sh
+ * to keep the picpeak-docs site in lockstep with the running API.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Need yaml — runtime require so the script fails clearly with an
+// install hint instead of an opaque MODULE_NOT_FOUND.
+let yaml;
+try {
+  yaml = require('js-yaml');
+} catch {
+  console.error('generate-openapi: missing dependency `js-yaml`. Run `npm install --save-dev js-yaml` in /backend.');
+  process.exit(2);
+}
+
+const { getOpenApiSpec } = require('../src/openapi/spec');
+
+const outDir = path.resolve(__dirname, '../../docs');
+fs.mkdirSync(outDir, { recursive: true });
+
+const spec = getOpenApiSpec();
+fs.writeFileSync(path.join(outDir, 'openapi.json'), JSON.stringify(spec, null, 2));
+fs.writeFileSync(path.join(outDir, 'openapi.yaml'), yaml.dump(spec, { lineWidth: 100 }));
+
+console.log(`Wrote openapi.json + openapi.yaml to ${outDir}`);

backend/scripts/generate-watermarks.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * Script to generate pre-watermarked versions for existing photos
+ * This is a one-time migration script to populate watermarks for photos
+ * that existed before the pre-generation feature was implemented.
+ *
+ * Usage: node scripts/generate-watermarks.js [eventId]
+ *
+ * Options:
+ *   eventId - Optional: Only generate watermarks for a specific event
+ *
+ * Examples:
+ *   node scripts/generate-watermarks.js          # Generate for all photos
+ *   node scripts/generate-watermarks.js 5        # Generate for event ID 5
+ */
+
+const path = require('path');
+const { db } = require('../src/database/db');
+const watermarkService = require('../src/services/watermarkService');
+const watermarkGeneratorService = require('../src/services/watermarkGeneratorService');
+
+async function generateWatermarks(eventId = null) {
+  try {
+    console.log('='.repeat(60));
+    console.log('PicPeak Watermark Generation Script');
+    console.log('='.repeat(60));
+
+    // Check if watermarking is enabled
+    const settings = await watermarkService.getWatermarkSettings();
+
+    if (!settings || !settings.enabled) {
+      console.log('\nWatermarking is currently DISABLED in settings.');
+      console.log('Enable watermarking in Admin > Branding settings first.');
+      console.log('Exiting without generating watermarks.');
+      process.exit(0);
+    }
+
+    console.log('\nWatermark Settings:');
+    console.log(`  Enabled: ${settings.enabled}`);
+    console.log(`  Position: ${settings.position}`);
+    console.log(`  Opacity: ${settings.opacity}%`);
+    console.log(`  Size: ${settings.size}%`);
+    console.log(`  Logo: ${settings.logoPath || '(using text fallback)'}`);
+
+    // Build query
+    let query = db('photos')
+      .join('events', 'photos.event_id', 'events.id')
+      .whereNull('photos.watermark_path')
+      .whereNot(function() {
+        this.where('photos.media_type', 'video')
+          .orWhere('photos.mime_type', 'like', 'video/%');
+      })
+      .select(
+        'photos.id',
+        'photos.filename',
+        'photos.event_id',
+        'events.event_name'
+      );
+
+    if (eventId) {
+      query = query.where('photos.event_id', eventId);
+      console.log(`\nFiltering to event ID: ${eventId}`);
+    }
+
+    const photos = await query;
+
+    if (photos.length === 0) {
+      console.log('\nNo photos found without watermarks.');
+      if (eventId) {
+        console.log(`(Checked event ID: ${eventId})`);
+      }
+      console.log('All photos already have pre-generated watermarks or watermarking is disabled.');
+      process.exit(0);
+    }
+
+    console.log(`\nFound ${photos.length} photos without watermarks.`);
+
+    // Group by event for display
+    const eventCounts = {};
+    photos.forEach(p => {
+      eventCounts[p.event_name] = (eventCounts[p.event_name] || 0) + 1;
+    });
+
+    console.log('\nPhotos by event:');
+    Object.entries(eventCounts).forEach(([name, count]) => {
+      console.log(`  ${name}: ${count} photos`);
+    });
+
+    console.log('\nStarting watermark generation...\n');
+
+    let successCount = 0;
+    let failCount = 0;
+    const startTime = Date.now();
+
+    // Process photos with progress display
+    for (let i = 0; i < photos.length; i++) {
+      const photo = photos[i];
+      const progress = Math.round(((i + 1) / photos.length) * 100);
+
+      process.stdout.write(`\r[${progress}%] Processing photo ${i + 1}/${photos.length}: ${photo.filename.substring(0, 30)}...`);
+
+      try {
+        const result = await watermarkGeneratorService.generateForPhoto(photo.id);
+
+        if (result.success) {
+          successCount++;
+        } else {
+          failCount++;
+          console.log(`\n  Failed: ${photo.filename} - ${result.error}`);
+        }
+      } catch (error) {
+        failCount++;
+        console.log(`\n  Error: ${photo.filename} - ${error.message}`);
+      }
+    }
+
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    console.log('\n');
+    console.log('='.repeat(60));
+    console.log('Watermark Generation Complete');
+    console.log('='.repeat(60));
+    console.log(`  Total processed: ${photos.length}`);
+    console.log(`  Successful: ${successCount}`);
+    console.log(`  Failed: ${failCount}`);
+    console.log(`  Duration: ${duration} seconds`);
+    console.log(`  Average: ${(photos.length / parseFloat(duration)).toFixed(1)} photos/second`);
+
+    if (failCount > 0) {
+      console.log('\nSome watermarks failed to generate. Check the errors above.');
+      console.log('You can re-run this script to retry failed photos.');
+    }
+
+    process.exit(failCount > 0 ? 1 : 0);
+  } catch (error) {
+    console.error('\nFatal error:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const eventId = args[0] ? parseInt(args[0], 10) : null;
+
+if (args[0] && isNaN(eventId)) {
+  console.error('Error: eventId must be a number');
+  console.log('Usage: node scripts/generate-watermarks.js [eventId]');
+  process.exit(1);
+}
+
+// Run the script
+generateWatermarks(eventId)
+  .then(() => {
+    process.exit(0);
+  })
+  .catch(error => {
+    console.error('Unhandled error:', error);
+    process.exit(1);
+  });

backend/scripts/migrate-storage.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * migrate-storage.js
+ *
+ * One-shot migration tool to copy every PicPeak content file from the local
+ * filesystem (the legacy STORAGE_PATH) to a configured S3-compatible bucket.
+ *
+ * Reads the relative path of each known asset from the database:
+ *   photos.path
+ *   photos.thumbnail_path
+ *   photos.hero_path
+ *   photos.watermark_path
+ *   events.archive_path
+ *   events.download_zip_path
+ *
+ * For each, streams from local fs → S3, skipping files whose sha256 already
+ * matches a previously uploaded object (idempotent — safe to re-run).
+ *
+ * Does NOT flip STORAGE_BACKEND. After the migration completes clean, the
+ * operator updates their environment + restarts the backend explicitly.
+ *
+ * Usage:
+ *   node backend/scripts/migrate-storage.js                # live migration
+ *   node backend/scripts/migrate-storage.js --dry-run      # report only, no uploads
+ *   node backend/scripts/migrate-storage.js --failures-csv=/path/to/failures.csv
+ *   node backend/scripts/migrate-storage.js --concurrency=4
+ *
+ * Required env (S3 destination — same vars the backend reads with STORAGE_BACKEND=s3):
+ *   STORAGE_S3_BUCKET, STORAGE_S3_REGION, STORAGE_S3_ACCESS_KEY, STORAGE_S3_SECRET_KEY
+ *   STORAGE_S3_ENDPOINT (optional — for MinIO/R2/etc.)
+ *   STORAGE_S3_PREFIX (optional)
+ *
+ * STORAGE_PATH must point at the live local storage root. Postgres connection
+ * uses the same DB env vars the backend uses.
+ */
+
+require('dotenv').config();
+const fs = require('fs');
+const fsp = require('fs').promises;
+const path = require('path');
+const crypto = require('crypto');
+
+const { db } = require('../src/database/db');
+const LocalFsStorage = require('../src/services/storage/LocalFsStorage');
+const S3StorageBackend = require('../src/services/storage/S3StorageBackend');
+const logger = require('../src/utils/logger');
+
+function parseArgs(argv) {
+  const args = { dryRun: false, concurrency: 4, failuresCsv: '/tmp/migrate-storage-failures.csv' };
+  for (const arg of argv) {
+    if (arg === '--dry-run') args.dryRun = true;
+    else if (arg.startsWith('--concurrency=')) args.concurrency = Math.max(1, parseInt(arg.split('=')[1], 10) || 4);
+    else if (arg.startsWith('--failures-csv=')) args.failuresCsv = arg.split('=')[1];
+    else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: node migrate-storage.js [--dry-run] [--concurrency=N] [--failures-csv=PATH]');
+      process.exit(0);
+    }
+  }
+  return args;
+}
+
+function buildLocalSource() {
+  const root = process.env.STORAGE_PATH;
+  if (!root) {
+    throw new Error('STORAGE_PATH must be set to the local storage root.');
+  }
+  return new LocalFsStorage({ root });
+}
+
+function buildS3Destination() {
+  const required = ['STORAGE_S3_BUCKET', 'STORAGE_S3_ACCESS_KEY', 'STORAGE_S3_SECRET_KEY'];
+  const missing = required.filter((v) => !process.env[v]);
+  if (missing.length) {
+    throw new Error(`Missing S3 env vars: ${missing.join(', ')}`);
+  }
+  return new S3StorageBackend({
+    bucket: process.env.STORAGE_S3_BUCKET,
+    region: process.env.STORAGE_S3_REGION || 'us-east-1',
+    endpoint: process.env.STORAGE_S3_ENDPOINT,
+    accessKeyId: process.env.STORAGE_S3_ACCESS_KEY,
+    secretAccessKey: process.env.STORAGE_S3_SECRET_KEY,
+    prefix: process.env.STORAGE_S3_PREFIX,
+    forcePathStyle: process.env.STORAGE_S3_FORCE_PATH_STYLE === 'true' ? true : undefined,
+    sslEnabled: process.env.STORAGE_S3_SSL !== 'false',
+  });
+}
+
+async function sha256OfFile(localPath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(localPath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+async function collectKeys() {
+  const keys = new Map(); // key -> { source, contentType }
+
+  const addKey = (key, source) => {
+    if (!key) return;
+    const normalized = key.replace(/\\/g, '/').replace(/^\/+/, '');
+    if (!normalized) return;
+    if (!keys.has(normalized)) keys.set(normalized, { source });
+  };
+
+  // photos: path (events/active/{slug}/{filename}), thumbnail_path, hero_path, watermark_path
+  const photoBatch = await db('photos').select('id', 'path', 'thumbnail_path', 'hero_path', 'watermark_path');
+  for (const p of photoBatch) {
+    if (p.path) {
+      const photoKey = p.path.startsWith('events/active/') ? p.path : path.posix.join('events/active', p.path);
+      addKey(photoKey, `photos.path[${p.id}]`);
+    }
+    addKey(p.thumbnail_path, `photos.thumbnail_path[${p.id}]`);
+    addKey(p.hero_path, `photos.hero_path[${p.id}]`);
+    addKey(p.watermark_path, `photos.watermark_path[${p.id}]`);
+  }
+
+  // events: archive_path, download_zip_path
+  const eventBatch = await db('events').select('id', 'archive_path', 'download_zip_path');
+  for (const e of eventBatch) {
+    addKey(e.archive_path, `events.archive_path[${e.id}]`);
+    addKey(e.download_zip_path, `events.download_zip_path[${e.id}]`);
+  }
+
+  return keys;
+}
+
+async function migrateOne(key, meta, { source, dest, dryRun }) {
+  // Source must exist on local disk.
+  const localPath = source.resolveLocalPath(key);
+  let localStat;
+  try {
+    localStat = await fsp.stat(localPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { key, status: 'missing-locally', source: meta.source };
+    }
+    throw err;
+  }
+
+  // Idempotent skip: if S3 already has matching size + sha256.
+  const remoteStat = await dest.stat(key);
+  if (remoteStat && remoteStat.size === localStat.size) {
+    // sha256 match check via metadata is expensive; we trust size match for now.
+    // Operators paranoid about content drift can `rm` the bucket and re-run.
+    return { key, status: 'already-uploaded', source: meta.source };
+  }
+
+  if (dryRun) {
+    return { key, status: 'would-upload', source: meta.source, size: localStat.size };
+  }
+
+  await dest.putFromFile(key, localPath);
+
+  const verify = await dest.stat(key);
+  if (!verify || verify.size !== localStat.size) {
+    return { key, status: 'size-mismatch-after-upload', source: meta.source, expected: localStat.size, got: verify?.size };
+  }
+
+  return { key, status: 'uploaded', source: meta.source, size: localStat.size };
+}
+
+async function processWithConcurrency(items, concurrency, fn) {
+  const results = [];
+  let i = 0;
+  const workers = Array.from({ length: concurrency }, async () => {
+    while (true) {
+      const idx = i++;
+      if (idx >= items.length) return;
+      const [key, meta] = items[idx];
+      try {
+        const r = await fn(key, meta);
+        results.push(r);
+      } catch (err) {
+        results.push({ key, status: 'error', source: meta.source, error: err.message });
+      }
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+function formatCsvCell(v) {
+  if (v == null) return '';
+  const s = String(v);
+  if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+    return `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+async function writeFailuresCsv(filePath, failures) {
+  if (failures.length === 0) {
+    // Touch an empty file with header so callers see a deterministic outcome.
+    await fsp.writeFile(filePath, 'key,source,status,error\n');
+    return;
+  }
+  const lines = ['key,source,status,error'];
+  for (const f of failures) {
+    lines.push([f.key, f.source, f.status, f.error || ''].map(formatCsvCell).join(','));
+  }
+  await fsp.writeFile(filePath, lines.join('\n') + '\n');
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  logger.info(`migrate-storage starting (dry-run=${args.dryRun}, concurrency=${args.concurrency})`);
+
+  const source = buildLocalSource();
+  await source.init();
+
+  const dest = buildS3Destination();
+  await dest.init();
+
+  logger.info('collecting key list from database…');
+  const keys = await collectKeys();
+  logger.info(`found ${keys.size} unique keys to process`);
+
+  const items = Array.from(keys.entries());
+  const results = await processWithConcurrency(items, args.concurrency, (key, meta) =>
+    migrateOne(key, meta, { source, dest, dryRun: args.dryRun })
+  );
+
+  const counts = results.reduce((acc, r) => {
+    acc[r.status] = (acc[r.status] || 0) + 1;
+    return acc;
+  }, {});
+
+  console.log('\n=== migrate-storage summary ===');
+  for (const [status, count] of Object.entries(counts).sort()) {
+    console.log(`  ${status.padEnd(28)} ${count}`);
+  }
+
+  const failureStatuses = new Set(['error', 'missing-locally', 'size-mismatch-after-upload']);
+  const failures = results.filter((r) => failureStatuses.has(r.status));
+  await writeFailuresCsv(args.failuresCsv, failures);
+
+  if (failures.length > 0) {
+    console.log(`\nWrote ${failures.length} failures to ${args.failuresCsv}`);
+    console.log('Re-run with --dry-run to triage; fix sources or remove DB rows that point at missing files.');
+    process.exitCode = 1;
+  } else if (args.dryRun) {
+    console.log(`\nDry-run complete. Re-run without --dry-run to perform the migration.`);
+    console.log(`(Empty failures CSV written to ${args.failuresCsv}.)`);
+  } else {
+    console.log(`\nMigration complete. Update STORAGE_BACKEND=s3 + restart the backend to switch over.`);
+  }
+
+  await db.destroy();
+}
+
+main().catch(async (err) => {
+  console.error('migrate-storage failed:', err);
+  try { await db.destroy(); } catch (_) { /* ignore */ }
+  process.exit(2);
+});

backend/server.js

@@ -194,13 +194,23 @@ function composeInlineStyles(payload) {
   return cssSegments.join('\n\n');
 }
 
+function escapeHtml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
 function renderBrandHeader(branding) {
-  const displayName = branding.companyName || 'PicPeak';
-  const logoSrc = branding.logoUrl || '/picpeak-logo-transparent.png';
+  const displayName = escapeHtml(branding.companyName || 'PicPeak');
+  const logoSrc = encodeURI(branding.logoUrl || '/picpeak-logo-transparent.png');
   const logo = `<img src="${logoSrc}" alt="${displayName}" class="brand-logo" loading="lazy" decoding="async" />`;
 
   const tagline = branding.companyTagline
-    ? `<p class="brand-tagline">${branding.companyTagline}</p>`
+    ? `<p class="brand-tagline">${escapeHtml(branding.companyTagline)}</p>`
     : '';
 
   return `<header class="site-header">
@@ -224,13 +234,14 @@ function renderBrandHeader(branding) {
 }
 
 function renderBrandFooter(branding) {
-  const displayName = branding.companyName || 'PicPeak';
+  const displayName = escapeHtml(branding.companyName || 'PicPeak');
   const footerNote = branding.footerText
-    ? `<p>${branding.footerText}</p>`
+    ? `<p>${escapeHtml(branding.footerText)}</p>`
     : '<p>Powered by PicPeak to keep every celebration beautifully organised.</p>';
 
-  const supportLink = branding.supportEmail
-    ? `<a href="mailto:${branding.supportEmail}">Support</a>`
+  const supportEmail = escapeHtml(branding.supportEmail || '');
+  const supportLink = supportEmail
+    ? `<a href="mailto:${supportEmail}">Support</a>`
     : '';
 
   const legalLinks = `
@@ -252,10 +263,29 @@ function renderBrandFooter(branding) {
 </footer>`;
 }
 
+function buildSeoMetaTags(seoSettings) {
+  const tags = [];
+  const robotsDirectives = [];
+
+  if (seoSettings.seo_meta_noindex) robotsDirectives.push('noindex');
+  if (seoSettings.seo_meta_nofollow) robotsDirectives.push('nofollow');
+
+  if (robotsDirectives.length > 0) {
+    tags.push(`<meta name="robots" content="${robotsDirectives.join(', ')}" />`);
+  }
+
+  if (seoSettings.seo_meta_noai) {
+    tags.push('<meta name="robots" content="noai, noimageai" />');
+  }
+
+  return tags.join('\n  ');
+}
+
 function buildPublicSiteDocument(payload) {
   const inlineStyles = composeInlineStyles(payload);
   const header = renderBrandHeader(payload.branding);
   const footer = renderBrandFooter(payload.branding);
+  const seoMeta = payload.seoSettings ? buildSeoMetaTags(payload.seoSettings) : '';
 
   return `<!DOCTYPE html>
 <html lang="en">
@@ -263,8 +293,9 @@ function buildPublicSiteDocument(payload) {
   <meta charset="utf-8" />
   <meta http-equiv="X-UA-Compatible" content="IE=edge" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${payload.title}</title>
+  <title>${escapeHtml(payload.title)}</title>
   <meta name="description" content="Curated photo galleries and stories from unforgettable celebrations." />
+  ${seoMeta}
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
@@ -296,6 +327,21 @@ async function handlePublicSiteRequest(req, res, next) {
       return;
     }
 
+    // Inject SEO meta settings into payload
+    try {
+      const seoRows = await db('app_settings')
+        .where('setting_type', 'seo')
+        .whereIn('setting_key', ['seo_meta_noindex', 'seo_meta_nofollow', 'seo_meta_noai'])
+        .select('setting_key', 'setting_value');
+      const seoSettings = {};
+      for (const row of seoRows) {
+        let val = row.setting_value;
+        if (typeof val === 'string') { try { val = JSON.parse(val); } catch {} }
+        seoSettings[row.setting_key] = val;
+      }
+      payload.seoSettings = seoSettings;
+    } catch {}
+
     const document = buildPublicSiteDocument(payload);
 
     res.setHeader('Content-Type', 'text/html; charset=utf-8');
@@ -324,8 +370,22 @@ async function initializeRateLimiters() {
 }
 
 // Note: Rate limiters will be initialized after database connection
-app.use(express.json({ limit: '10gb' }));
-app.use(express.urlencoded({ extended: true, limit: '10gb' }));
+app.use(express.json({ limit: '50mb' }));
+app.use(express.urlencoded({ extended: true, limit: '50mb' }));
+
+// CSRF protection: require JSON Content-Type on mutating API requests
+// This blocks cross-origin form submissions which cannot set Content-Type: application/json
+app.use('/api', (req, res, next) => {
+  if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(req.method)) {
+    const contentType = req.headers['content-type'] || '';
+    const contentLength = parseInt(req.headers['content-length'] || '0', 10);
+    // Allow empty-body requests (e.g. logout), multipart for uploads, and JSON for API calls
+    if (contentLength > 0 && !contentType.includes('application/json') && !contentType.includes('multipart/form-data')) {
+      return res.status(415).json({ error: 'Unsupported Content-Type. Use application/json or multipart/form-data.' });
+    }
+  }
+  next();
+});
 
 // Request logging for API routes (with timestamps)
 const apiRequestLogger = (req, res, next) => {
@@ -351,8 +411,23 @@ app.use('/api/admin', sessionTimeoutMiddleware);
 
 // Middleware to set CORS headers for static files
 const setCorsHeaders = (req, res, next) => {
-  res.header('Access-Control-Allow-Origin', req.headers.origin || '*');
-  res.header('Access-Control-Allow-Credentials', 'true');
+  const origin = req.headers.origin;
+  const staticAllowedOrigins = [
+    process.env.FRONTEND_URL || 'http://localhost:3005',
+    process.env.ADMIN_URL || 'http://localhost:3005'
+  ];
+  if (process.env.NODE_ENV === 'development') {
+    staticAllowedOrigins.push(
+      'http://localhost:5173',
+      'http://localhost:3002',
+      'http://localhost:3001',
+      'http://localhost:3000'
+    );
+  }
+  if (origin && staticAllowedOrigins.indexOf(origin) !== -1) {
+    res.header('Access-Control-Allow-Origin', origin);
+    res.header('Access-Control-Allow-Credentials', 'true');
+  }
   res.header('Cross-Origin-Resource-Policy', 'cross-origin');
   next();
 };
@@ -395,24 +470,47 @@ if (process.env.NODE_ENV === 'development') {
   });
 }
 
-// Health check endpoint
+// OG/Twitter-card preview endpoint for gallery share URLs. Crawlers (WhatsApp,
+// Slack, Facebook, etc.) don't execute JS, so the SPA's client-side meta tags
+// never reach them. nginx routes UA-detected crawlers from /gallery/:slug to
+// here; humans still get the SPA via try_files.
+const { isSocialCrawler, handleGalleryOgRequest } = require('./src/services/galleryOgService');
+app.get('/og/gallery/:slug', handleGalleryOgRequest);
+
+// robots.txt endpoint (dynamic, served from DB settings)
+const { generateRobotsTxt } = require('./src/services/robotsTxtService');
+app.get('/robots.txt', async (req, res) => {
+  try {
+    const robotsTxt = await generateRobotsTxt();
+    res.setHeader('Content-Type', 'text/plain');
+    res.setHeader('Cache-Control', 'public, max-age=3600');
+    res.status(200).send(robotsTxt);
+  } catch (error) {
+    logger.error('Failed to generate robots.txt', { error: error.message });
+    // Safe default for a private photo platform
+    res.setHeader('Content-Type', 'text/plain');
+    res.status(200).send('User-agent: *\nDisallow: /\n');
+  }
+});
+
+// Health check endpoint. `pid` + `uptime` let monitors (and the local E2E
+// watchdog) detect a silent process restart between two checks.
 app.get('/health', async (req, res) => {
   try {
-    // Check database connectivity
     await db.raw('SELECT 1');
-    
-    res.json({ 
-      status: 'ok', 
-      database: 'connected',
-      timestamp: new Date().toISOString() 
+    res.json({
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+      pid: process.pid,
+      uptime: process.uptime()
     });
   } catch (error) {
     logger.error('Health check failed:', error);
-    res.status(503).json({ 
-      status: 'error', 
-      database: 'disconnected',
-      error: error.message,
-      timestamp: new Date().toISOString() 
+    res.status(503).json({
+      status: 'error',
+      timestamp: new Date().toISOString(),
+      pid: process.pid,
+      uptime: process.uptime()
     });
   }
 });
@@ -424,19 +522,44 @@ app.use('/api/auth', authRoutes);
 // Gallery routes - main routes first, then feedback routes
 app.use('/api/gallery', galleryRoutes);
 app.use('/api/gallery', require('./src/routes/galleryFeedback'));
+app.use('/api/gallery', require('./src/routes/galleryGuests'));
 app.use('/api/admin', adminRoutes);
 app.use('/api/admin/auth', adminAuthRoutes);
 app.use('/api/admin/system', require('./src/routes/adminSystem'));
 app.use('/api/admin/backup', require('./src/routes/adminBackup'));
 app.use('/api/admin/database-backup', require('./src/routes/adminDatabaseBackup'));
 app.use('/api/admin/feedback', require('./src/routes/adminFeedback'));
+app.use('/api/admin', require('./src/routes/adminGuests'));
 app.use('/api/admin/image-security', require('./src/routes/adminImageSecurity'));
 app.use('/api/admin/thumbnails', require('./src/routes/adminThumbnails'));
+app.use('/api/admin/photos', require('./src/routes/adminPhotoDimensions'));
 app.use('/api/admin/photos', require('./src/routes/adminPhotos'));
 app.use('/api/admin/photo-export', require('./src/routes/adminPhotoExport'));
 app.use('/api/admin/css-templates', require('./src/routes/adminCssTemplates'));
 app.use('/api/admin/events', require('./src/routes/adminEventRename'));
 app.use('/api/admin/users', require('./src/routes/adminUsers'));
+app.use('/api/admin/event-types', require('./src/routes/adminEventTypes'));
+app.use('/api/admin/api-tokens', require('./src/routes/adminApiTokens'));
+app.use('/api/admin/webhooks', require('./src/routes/adminWebhooks'));
+// Public v1 API for n8n / external integrations (#322). Mounted under
+// /api/v1; auth handled per-route via apiTokenAuth (Bearer tokens).
+app.use('/api/v1', require('./src/routes/v1/events'));
+
+// Swagger UI for the v1 API. Admin-gated since it lists endpoint shapes
+// that should not be enumerable to anonymous users (a common reduce-info-leak hardening).
+{
+  const swaggerUi = require('swagger-ui-express');
+  const { adminAuth } = require('./src/middleware/auth');
+  const { getOpenApiSpec } = require('./src/openapi/spec');
+  app.get('/api/openapi.json', adminAuth, (_req, res) => res.json(getOpenApiSpec()));
+  app.use(
+    '/api/docs',
+    adminAuth,
+    swaggerUi.serve,
+    swaggerUi.setup(getOpenApiSpec(), { customSiteTitle: 'PicPeak API · v1' })
+  );
+}
+
 app.use('/api/invite', require('./src/routes/acceptInvite'));
 app.use('/api/public/settings', require('./src/routes/publicSettings'));
 app.use('/api/public', require('./src/routes/publicCMS'));
@@ -460,7 +583,16 @@ try {
       res.sendFile(indexPath);
     });
 
-    // SPA fallback for admin + gallery routes
+    // SPA fallback for admin + gallery routes. For gallery URLs we intercept
+    // social-crawler User-Agents and serve OG/Twitter-card metadata so link
+    // previews show the event name + branding instead of the SPA stub.
+    app.get('/gallery/:slug/:token?', (req, res, next) => {
+      if (isSocialCrawler(req.get('user-agent'))) {
+        return handleGalleryOgRequest(req, res);
+      }
+      return next();
+    }, (req, res) => res.sendFile(indexPath));
+
     app.get(['/admin', '/admin/*', '/gallery/*'], (req, res) => {
       res.sendFile(indexPath);
     });
@@ -486,6 +618,10 @@ async function startServer() {
     // Initialize database
     await initializeDatabase();
 
+    // Initialize storage backend (local fs or S3) — fail fast on misconfig
+    const { initStorage } = require('./src/services/storage');
+    await initStorage();
+
     // Initialize rate limiters after database is ready
     await initializeRateLimiters();
     logger.info('Rate limiters initialized with database configuration');
@@ -512,6 +648,16 @@ async function startServer() {
     await initializeTransporter();
     startEmailQueueProcessor();
     
+    // Start webhook delivery worker (#327)
+    const { startWebhookDeliveryWorker } = require('./src/services/webhookDeliveryWorker');
+    startWebhookDeliveryWorker();
+
+    // Start S3 auto-importer (#328 follow-up). No-op when STORAGE_AUTO_IMPORT
+    // is unset OR STORAGE_BACKEND=local — replaces the chokidar watcher
+    // for S3-mode deployments that drop files into the bucket directly.
+    const { startS3AutoImporter } = require('./src/services/s3AutoImporter');
+    startS3AutoImporter();
+
     // Start backup service
     await startBackupService();
     

backend/src/database/db.js

@@ -463,8 +463,15 @@ async function ensureGlobalCategories() {
       table.text('title_de');
       table.text('content_en');
       table.text('content_de');
+      table.string('logo_url').nullable();
       table.timestamp('updated_at').defaultTo(db.fn.now());
     });
+  } else if (!(await db.schema.hasColumn('cms_pages', 'logo_url'))) {
+    // Online migration for existing deployments — see issue #324, per-page
+    // logo override for admin-customisable error pages.
+    await db.schema.alterTable('cms_pages', (table) => {
+      table.string('logo_url').nullable();
+    });
   }
 
   const categoryCountRow = await db('photo_categories').count({ count: 'id' }).first();
@@ -501,6 +508,24 @@ async function ensureGlobalCategories() {
       content_de: '<h2>Datenschutzerklärung</h2><p>Bitte bearbeiten Sie diesen Inhalt im Admin-Panel.</p>',
       updated_at: new Date(),
     },
+    // Customisable error pages — issue #324. Generic copy by default;
+    // admins can edit text + logo per page in the CMS Pages tab.
+    {
+      slug: 'not-found',
+      title_en: 'Page Not Found',
+      title_de: 'Seite nicht gefunden',
+      content_en: '<h2>Page Not Found</h2><p>The page you are looking for does not exist or has been moved.</p>',
+      content_de: '<h2>Seite nicht gefunden</h2><p>Die gesuchte Seite existiert nicht oder wurde verschoben.</p>',
+      updated_at: new Date(),
+    },
+    {
+      slug: 'gallery-not-found',
+      title_en: 'Gallery Not Found',
+      title_de: 'Galerie nicht gefunden',
+      content_en: '<h2>Gallery Not Found</h2><p>This gallery could not be found. The link may be incorrect, or the gallery may have expired or been archived. Please contact the organiser if you believe this is a mistake.</p>',
+      content_de: '<h2>Galerie nicht gefunden</h2><p>Diese Galerie konnte nicht gefunden werden. Der Link ist möglicherweise nicht korrekt, oder die Galerie ist abgelaufen oder wurde archiviert. Bitte kontaktieren Sie den Veranstalter, falls Sie glauben, dass dies ein Fehler ist.</p>',
+      updated_at: new Date(),
+    },
   ];
 
   for (const page of defaultPages) {

backend/src/middleware/apiTokenAuth.js

@@ -0,0 +1,123 @@
+const crypto = require('crypto');
+const { db } = require('../database/db');
+const logger = require('../utils/logger');
+
+const TOKEN_PREFIX = 'pp_live_';
+const VALID_SCOPES = ['read', 'write', 'admin'];
+
+function hashToken(plaintext) {
+  return crypto.createHash('sha256').update(plaintext).digest('hex');
+}
+
+/**
+ * Generate a new API token. Returns the plaintext (return once, never
+ * stored) plus the row payload to insert. Caller persists.
+ */
+function generateApiToken() {
+  const random = crypto.randomBytes(24).toString('base64url'); // 32 chars
+  const plaintext = `${TOKEN_PREFIX}${random}`;
+  return {
+    plaintext,
+    hashed: hashToken(plaintext),
+    preview: random.slice(0, 8)
+  };
+}
+
+function parseScopes(raw) {
+  if (!raw) return [];
+  return String(raw)
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => VALID_SCOPES.includes(s));
+}
+
+/**
+ * Middleware: authenticate via API token. Maps the token to its owner
+ * admin user, attaches { req.admin, req.apiToken }, then defers to the
+ * regular permission machinery on top.
+ *
+ * Mount this *instead* of `adminAuth` on /api/v1/* routes. Existing
+ * permission decorators (`requirePermission('events.create')`) still
+ * work because they read `req.admin.id`.
+ */
+async function apiTokenAuth(req, res, next) {
+  try {
+    const header = req.headers?.authorization || '';
+    if (!header.startsWith('Bearer ')) {
+      return res.status(401).json({ error: 'Missing API token', code: 'NO_TOKEN' });
+    }
+    const token = header.slice(7).trim();
+    if (!token.startsWith(TOKEN_PREFIX)) {
+      return res.status(401).json({ error: 'Invalid token format', code: 'INVALID_TOKEN' });
+    }
+
+    const hashed = hashToken(token);
+    const row = await db('api_tokens').where({ hashed_token: hashed }).first();
+    if (!row) {
+      return res.status(401).json({ error: 'Invalid token', code: 'INVALID_TOKEN' });
+    }
+    if (row.revoked_at) {
+      return res.status(401).json({ error: 'Token revoked', code: 'TOKEN_REVOKED' });
+    }
+    if (row.expires_at && new Date(row.expires_at) <= new Date()) {
+      return res.status(401).json({ error: 'Token expired', code: 'TOKEN_EXPIRED' });
+    }
+
+    const admin = await db('admin_users')
+      .where({ id: row.created_by, is_active: true })
+      .select('id', 'username', 'email', 'role_id')
+      .first();
+    if (!admin) {
+      return res.status(401).json({ error: 'Token owner unavailable', code: 'OWNER_INACTIVE' });
+    }
+
+    // Touch last_used_at — async, don't block the request.
+    db('api_tokens').where({ id: row.id }).update({ last_used_at: new Date() })
+      .catch((err) => logger.debug('api_tokens last_used update failed', { err: err.message }));
+
+    req.admin = admin;
+    req.apiToken = {
+      id: row.id,
+      name: row.name,
+      scopes: parseScopes(row.scopes)
+    };
+    return next();
+  } catch (error) {
+    logger.error('apiTokenAuth error', { error: error.message });
+    return res.status(500).json({ error: 'Authentication error' });
+  }
+}
+
+/**
+ * Middleware factory: require a specific scope on the API token. Use
+ * after apiTokenAuth — `requireApiScope('write')` rejects read-only
+ * tokens trying to mutate.
+ */
+function requireApiScope(scope) {
+  return (req, res, next) => {
+    const have = req.apiToken?.scopes || [];
+    // 'admin' implies write/read; 'write' implies read.
+    const expanded = new Set(have);
+    if (have.includes('admin')) ['write', 'read'].forEach((s) => expanded.add(s));
+    if (have.includes('write')) expanded.add('read');
+    if (!expanded.has(scope)) {
+      return res.status(403).json({
+        error: `Token lacks required scope: ${scope}`,
+        code: 'INSUFFICIENT_SCOPE',
+        required: scope,
+        granted: have
+      });
+    }
+    next();
+  };
+}
+
+module.exports = {
+  apiTokenAuth,
+  requireApiScope,
+  generateApiToken,
+  hashToken,
+  parseScopes,
+  TOKEN_PREFIX,
+  VALID_SCOPES
+};

backend/src/middleware/auth.js

@@ -91,10 +91,16 @@ async function adminAuth(req, res, next) {
       return res.status(401).json({ error: 'Invalid token' });
     }
 
-    // Check if password was changed after token was issued
+    // Check if password was changed after token was issued. JWT `iat` has
+    // 1-second resolution; `password_changed_at` is sub-second. Floor the
+    // comparison so a token issued in the *same* second as the password
+    // change isn't incorrectly rejected — that race used to bite anyone
+    // logging in immediately after a password reset/change.
     if (admin.password_changed_at) {
-      const passwordChangedTime = new Date(admin.password_changed_at).getTime() / 1000;
-      if (decoded.iat < passwordChangedTime) {
+      const passwordChangedSeconds = Math.floor(
+        new Date(admin.password_changed_at).getTime() / 1000
+      );
+      if (decoded.iat < passwordChangedSeconds) {
         logger.warn('Token used after password change', { userId: decoded.id });
         return res.status(401).json({
           error: 'Token invalid due to password change',
@@ -168,9 +174,10 @@ async function galleryAuth(req, res, next) {
       return res.status(404).json({ error: 'Gallery not found or expired' });
     }
     
-    // Check if gallery has expired
-    if (new Date(event.expires_at) < new Date()) {
-      return res.status(410).json({ 
+    // Check if gallery has expired (only if expires_at is set)
+    // Galleries with null expires_at never expire
+    if (event.expires_at && new Date(event.expires_at) < new Date()) {
+      return res.status(410).json({
         error: 'Gallery has expired',
         code: 'GALLERY_EXPIRED'
       });

backend/src/middleware/feedbackRateLimit.js

@@ -3,9 +3,20 @@ const { db } = require('../database/db');
 const logger = require('../utils/logger');
 
 /**
- * Generate a unique identifier for the guest
+ * Generate a unique identifier for the guest.
+ *
+ * In guest identity mode, `req.guest.identifier` is a server-issued UUID
+ * unique per person per event (set by the resolveGuest middleware). When
+ * present it takes precedence, so rate limits and deduplication become
+ * per-person instead of per-device.
+ *
+ * In simple (legacy) mode, the identifier falls back to a hash of IP + UA,
+ * matching prior behavior.
  */
 function generateGuestIdentifier(req) {
+  if (req.guest && req.guest.identifier) {
+    return req.guest.identifier;
+  }
   const ip = req.ip || req.connection.remoteAddress || 'unknown';
   const userAgent = req.headers['user-agent'] || 'unknown';
   return crypto

backend/src/middleware/gallery.js

@@ -4,6 +4,18 @@ const { formatBoolean } = require('../utils/dbCompat');
 const { getGalleryTokenFromRequest } = require('../utils/tokenUtils');
 const logger = require('../utils/logger');
 
+// Check if the request carries a valid admin preview token (Feature 3)
+function isAdminPreview(req) {
+  const previewToken = req.query?.preview;
+  if (!previewToken) return false;
+  try {
+    const decoded = jwt.verify(previewToken, process.env.JWT_SECRET, { issuer: 'picpeak-auth' });
+    return decoded.type === 'admin';
+  } catch {
+    return false;
+  }
+}
+
 // Middleware to verify gallery access
 async function verifyGalleryAccess(req, res, next) {
   try {
@@ -16,15 +28,18 @@ async function verifyGalleryAccess(req, res, next) {
         return res.status(401).json({ error: 'No token provided' });
       }
 
+      const adminPreview = isAdminPreview(req);
       event = await withRetry(async () => {
-        return await db('events')
-          .where({ 
+        const q = db('events')
+          .where({
             slug: requestedSlug,
             is_active: formatBoolean(true),
             is_archived: formatBoolean(false)
-          })
-          .select('*')
-          .first();
+          });
+        if (!adminPreview) {
+          q.where({ is_draft: formatBoolean(false) });
+        }
+        return await q.select('*').first();
       });
 
       if (!event) {
@@ -66,15 +81,18 @@ async function verifyGalleryAccess(req, res, next) {
     // If we have a slug in the URL params or from pre-middleware, verify it matches
     if (requestedSlug) {
       // Verify by slug and ensure it matches the token's event
+      const adminPreviewToken = isAdminPreview(req);
       event = await withRetry(async () => {
-        return await db('events')
-          .where({ 
+        const q = db('events')
+          .where({
             slug: requestedSlug,
             is_active: formatBoolean(true),
             is_archived: formatBoolean(false)
-          })
-          .select('*')
-          .first();
+          });
+        if (!adminPreviewToken) {
+          q.where({ is_draft: formatBoolean(false) });
+        }
+        return await q.select('*').first();
       });
       
       // Verify the token's eventId matches
@@ -83,15 +101,18 @@ async function verifyGalleryAccess(req, res, next) {
       }
     } else {
       // Fallback to using eventId from token
+      const adminPreviewFallback = isAdminPreview(req);
       event = await withRetry(async () => {
-        return await db('events')
-          .where({ 
-            id: decoded.eventId, 
+        const q = db('events')
+          .where({
+            id: decoded.eventId,
             is_active: formatBoolean(true),
             is_archived: formatBoolean(false)
-          })
-          .select('*')
-          .first();
+          });
+        if (!adminPreviewFallback) {
+          q.where({ is_draft: formatBoolean(false) });
+        }
+        return await q.select('*').first();
       });
     }
     
@@ -102,8 +123,9 @@ async function verifyGalleryAccess(req, res, next) {
     
     logger.debug('[verifyGalleryAccess] Event located', { eventId: event.id, slug: event.slug });
     req.event = event;
+    req.accessLevel = decoded.accessLevel || 'guest';
     req.sessionID = decoded.sessionId || `gallery_${event.id}_${Date.now()}`;
-    
+
     // Create client info for logging (similar to secureImageMiddleware but simpler)
     req.clientInfo = {
       ip: req.ip || req.connection.remoteAddress || 'unknown',
@@ -121,5 +143,6 @@ async function verifyGalleryAccess(req, res, next) {
 }
 
 module.exports = {
-  verifyGalleryAccess
+  verifyGalleryAccess,
+  isAdminPreview
 };

backend/src/middleware/guestAuth.js

@@ -0,0 +1,105 @@
+const jwt = require('jsonwebtoken');
+const { db } = require('../database/db');
+const logger = require('../utils/logger');
+const { getGuestTokenFromRequest } = require('../utils/tokenUtils');
+
+/**
+ * Non-blocking middleware. Reads an optional guest token from the request and,
+ * if present and valid, populates req.guest with { id, identifier, name, eventId }.
+ *
+ * If the token is missing, malformed, or expired → req.guest = null and the
+ * request continues. Downstream handlers (e.g. feedback submission) enforce
+ * presence explicitly based on event feedback settings (identity_mode).
+ */
+async function resolveGuest(req, res, next) {
+  try {
+    const slug = req.params?.slug;
+    const token = getGuestTokenFromRequest(req, slug);
+    if (!token) {
+      req.guest = null;
+      return next();
+    }
+
+    let decoded;
+    try {
+      const verified = jwt.verify(token, process.env.JWT_SECRET, {
+        issuer: 'picpeak-auth',
+        complete: true,
+      });
+      decoded = verified.payload;
+    } catch (err) {
+      // Invalid or expired guest tokens are silently ignored so that public
+      // gallery browsing continues to work even if the token is stale.
+      logger.debug('Invalid guest token', { reason: err.message });
+      req.guest = null;
+      return next();
+    }
+
+    if (decoded.type !== 'guest') {
+      req.guest = null;
+      return next();
+    }
+
+    // Verify the guest row still exists and is not soft-deleted.
+    const guest = await db('gallery_guests')
+      .where({ id: decoded.guestId, event_id: decoded.eventId, is_deleted: false })
+      .first();
+
+    if (!guest) {
+      req.guest = null;
+      return next();
+    }
+
+    req.guest = {
+      id: guest.id,
+      eventId: guest.event_id,
+      identifier: guest.identifier,
+      name: guest.name,
+      email: guest.email || null,
+    };
+
+    return next();
+  } catch (error) {
+    logger.error('resolveGuest middleware error', { error: error.message });
+    req.guest = null;
+    return next();
+  }
+}
+
+/**
+ * Blocking middleware that 401s if no guest identity was resolved.
+ * Use this on endpoints that require a valid guest session.
+ */
+function requireGuest(req, res, next) {
+  if (!req.guest) {
+    return res.status(401).json({ error: 'Guest identity required' });
+  }
+  return next();
+}
+
+/**
+ * Sign a new guest JWT. Scoped to a specific event and guest row.
+ * Expiry matches the gallery token default (24h).
+ */
+function signGuestToken({ guestId, eventId, identifier, name }, expiresIn = '24h') {
+  return jwt.sign(
+    {
+      type: 'guest',
+      guestId,
+      eventId,
+      identifier,
+      name,
+    },
+    process.env.JWT_SECRET,
+    {
+      issuer: 'picpeak-auth',
+      expiresIn,
+    }
+  );
+}
+
+module.exports = {
+  resolveGuest,
+  requireGuest,
+  signGuestToken,
+};

backend/src/middleware/ownership.js

@@ -0,0 +1,35 @@
+const { db } = require('../database/db');
+
+/**
+ * Middleware to enforce event ownership for non-super_admin users.
+ * Super admins bypass the check. Other admins can only access events they created.
+ */
+function requireEventOwnership(req, res, next) {
+  if (req.admin.roleName === 'super_admin') {
+    return next();
+  }
+
+  const eventId = req.params.eventId || req.params.id;
+  if (!eventId) {
+    return res.status(400).json({ error: 'Event ID is required' });
+  }
+
+  db('events')
+    .where('id', eventId)
+    .first()
+    .then((event) => {
+      if (!event) {
+        return res.status(404).json({ error: 'Event not found' });
+      }
+      // Allow access if: event has no owner (legacy/system), or admin owns it
+      if (event.created_by && event.created_by !== req.admin.id) {
+        return res.status(403).json({ error: 'Access denied' });
+      }
+      next();
+    })
+    .catch((err) => {
+      res.status(500).json({ error: 'Failed to verify ownership' });
+    });
+}
+
+module.exports = { requireEventOwnership };

backend/src/middleware/sessionTimeout.js

@@ -85,18 +85,28 @@ async function sessionTimeoutMiddleware(req, res, next) {
     const now = Date.now();
     const lastActivity = sessions.get(token);
     const timeout = await getSessionTimeout();
-    
-    // If session exists, check if it's expired
+
     if (lastActivity) {
+      // Existing session — check if idle too long
       if (now - lastActivity > timeout) {
         sessions.delete(token);
-        return res.status(401).json({ 
-          error: 'Session expired', 
-          code: 'SESSION_TIMEOUT' 
+        return res.status(401).json({
+          error: 'Session expired',
+          code: 'SESSION_TIMEOUT'
+        });
+      }
+    } else {
+      // First request with this token — check if token was issued longer ago than the timeout
+      // This prevents old/stolen tokens from bypassing session timeout after server restart
+      const tokenIssuedAt = (decoded.iat || 0) * 1000; // iat is in seconds
+      if (now - tokenIssuedAt > timeout) {
+        return res.status(401).json({
+          error: 'Session expired',
+          code: 'SESSION_TIMEOUT'
         });
       }
     }
-    
+
     // Update last activity
     sessions.set(token, now);
     

backend/src/openapi/spec.js

@@ -0,0 +1,70 @@
+/**
+ * OpenAPI 3.1 spec for /api/v1/* (#322). Source of truth for the
+ * picpeak-docs reference page. Built from JSDoc `@openapi` blocks
+ * scattered through src/routes/v1 — those stay co-located with the
+ * routes they describe so the spec can't drift in isolation.
+ */
+
+const swaggerJSDoc = require('swagger-jsdoc');
+const path = require('path');
+
+const baseDoc = {
+  openapi: '3.0.3',
+  info: {
+    title: 'PicPeak API',
+    version: 'v1',
+    description:
+      'Public REST API for PicPeak — create gallery events, upload photos, fetch share links. ' +
+      'Authenticate with a Bearer token issued via the admin **Settings → API Tokens** tab.'
+  },
+  servers: [
+    { url: '/api/v1', description: 'Same-origin (production)' }
+  ],
+  components: {
+    securitySchemes: {
+      bearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'pp_live_*',
+        description:
+          'Long-lived API token. Issue via Settings → API Tokens. ' +
+          'Token format: `pp_live_<random>`. Scopes: `read`, `write`, `admin`.'
+      }
+    },
+    schemas: {
+      EventSummary: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          slug: { type: 'string' },
+          event_name: { type: 'string' },
+          event_type: { type: 'string' },
+          event_date: { type: 'string', format: 'date', nullable: true },
+          expires_at: { type: 'string', format: 'date-time', nullable: true },
+          is_active: { type: 'boolean' },
+          is_archived: { type: 'boolean' },
+          is_draft: { type: 'boolean' },
+          created_at: { type: 'string', format: 'date-time' }
+        }
+      }
+    }
+  },
+  security: [{ bearerAuth: [] }]
+};
+
+const options = {
+  definition: baseDoc,
+  // Pull @openapi blocks from every v1 route file.
+  apis: [path.join(__dirname, '../routes/v1/**/*.js')]
+};
+
+let cached = null;
+
+function getOpenApiSpec() {
+  if (!cached) {
+    cached = swaggerJSDoc(options);
+  }
+  return cached;
+}
+
+module.exports = { getOpenApiSpec };

backend/src/routes/adminApiTokens.js

@@ -0,0 +1,117 @@
+/**
+ * Admin endpoints for managing API tokens (#322). Tokens are issued to
+ * an admin user; subsequent /api/v1/* calls authenticate via the token
+ * and act as the user that minted it (intersected with the token's
+ * scope set). Plaintext tokens are returned ONCE on creation.
+ */
+
+const express = require('express');
+const { body, validationResult } = require('express-validator');
+const { db, logActivity } = require('../database/db');
+const { adminAuth } = require('./../middleware/auth');
+const { requirePermission } = require('./../middleware/permissions');
+const { generateApiToken, VALID_SCOPES } = require('./../middleware/apiTokenAuth');
+const logger = require('../utils/logger');
+
+const router = express.Router();
+
+// List tokens for the current admin (or all, if super_admin) — without
+// the plaintext, never recoverable after creation.
+router.get('/', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
+    const tokens = await db('api_tokens')
+      .leftJoin('admin_users', 'admin_users.id', 'api_tokens.created_by')
+      .select(
+        'api_tokens.id',
+        'api_tokens.name',
+        'api_tokens.scopes',
+        'api_tokens.preview',
+        'api_tokens.created_at',
+        'api_tokens.expires_at',
+        'api_tokens.last_used_at',
+        'api_tokens.revoked_at',
+        'admin_users.username as owner_username'
+      )
+      .orderBy('api_tokens.created_at', 'desc');
+    res.json(tokens);
+  } catch (error) {
+    logger.error('Failed to list API tokens', { error: error.message });
+    res.status(500).json({ error: 'Failed to list tokens' });
+  }
+});
+
+// Create a token. Returns plaintext exactly once.
+router.post(
+  '/',
+  adminAuth,
+  requirePermission('settings.edit'),
+  [
+    body('name').isString().trim().isLength({ min: 1, max: 100 }),
+    body('scopes').isArray({ min: 1 }).custom((arr) => {
+      const ok = arr.every((s) => VALID_SCOPES.includes(s));
+      if (!ok) throw new Error(`Scopes must be a subset of: ${VALID_SCOPES.join(', ')}`);
+      return true;
+    }),
+    body('expires_at').optional({ nullable: true, checkFalsy: true }).isISO8601()
+  ],
+  async (req, res) => {
+    try {
+      const errors = validationResult(req);
+      if (!errors.isEmpty()) {
+        return res.status(400).json({ errors: errors.array() });
+      }
+      const { name, scopes, expires_at } = req.body;
+      const { plaintext, hashed, preview } = generateApiToken();
+
+      const insertResult = await db('api_tokens').insert({
+        name,
+        hashed_token: hashed,
+        scopes: scopes.join(','),
+        preview,
+        created_by: req.admin.id,
+        expires_at: expires_at || null
+      }).returning('id');
+      const id = insertResult[0]?.id || insertResult[0];
+
+      await logActivity('api_token_created', { name, scopes }, null, {
+        type: 'admin', id: req.admin.id, name: req.admin.username
+      });
+
+      // Return the plaintext exactly once.
+      res.status(201).json({
+        id,
+        name,
+        scopes,
+        token: plaintext,
+        preview,
+        expires_at: expires_at || null,
+        created_at: new Date().toISOString(),
+        notice: 'Save this token now — it will not be shown again.'
+      });
+    } catch (error) {
+      logger.error('Failed to create API token', { error: error.message });
+      res.status(500).json({ error: 'Failed to create token' });
+    }
+  }
+);
+
+// Revoke a token (soft-delete; lookups still find it but reject).
+router.delete('/:id', adminAuth, requirePermission('settings.edit'), async (req, res) => {
+  try {
+    const { id } = req.params;
+    const row = await db('api_tokens').where({ id }).first();
+    if (!row) return res.status(404).json({ error: 'Token not found' });
+    if (row.revoked_at) return res.status(400).json({ error: 'Token already revoked' });
+
+    await db('api_tokens').where({ id }).update({ revoked_at: new Date() });
+    await logActivity('api_token_revoked', { name: row.name }, null, {
+      type: 'admin', id: req.admin.id, name: req.admin.username
+    });
+    res.json({ id: Number(id), revoked: true });
+  } catch (error) {
+    logger.error('Failed to revoke API token', { error: error.message });
+    res.status(500).json({ error: 'Failed to revoke token' });
+  }
+});
+
+module.exports = router;

backend/src/routes/adminArchives.js

@@ -7,6 +7,7 @@ const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
 const archiver = require('archiver');
 const AdmZip = require('adm-zip');
+const { requireEventOwnership } = require('../middleware/ownership');
 const router = express.Router();
 
 // Get all archived events
@@ -82,7 +83,7 @@ router.get('/', adminAuth, requirePermission('archives.view'), async (req, res)
 });
 
 // Get single archive details
-router.get('/:id', adminAuth, requirePermission('archives.view'), async (req, res) => {
+router.get('/:id', adminAuth, requirePermission('archives.view'), requireEventOwnership, async (req, res) => {
   try {
     const archive = await db('events')
       .where('id', req.params.id)
@@ -138,7 +139,7 @@ router.get('/:id', adminAuth, requirePermission('archives.view'), async (req, re
 });
 
 // Restore archive
-router.post('/:id/restore', adminAuth, requirePermission('archives.restore'), async (req, res) => {
+router.post('/:id/restore', adminAuth, requirePermission('archives.restore'), requireEventOwnership, async (req, res) => {
   try {
     const archive = await db('events')
       .where('id', req.params.id)
@@ -301,7 +302,7 @@ router.post('/:id/restore', adminAuth, requirePermission('archives.restore'), as
 });
 
 // Download archive
-router.get('/:id/download', adminAuth, requirePermission('archives.download'), async (req, res) => {
+router.get('/:id/download', adminAuth, requirePermission('archives.download'), requireEventOwnership, async (req, res) => {
   try {
     const archive = await db('events')
       .where('id', req.params.id)
@@ -350,7 +351,7 @@ router.get('/:id/download', adminAuth, requirePermission('archives.download'), a
 });
 
 // Delete archive permanently
-router.delete('/:id', adminAuth, requirePermission('archives.delete'), async (req, res) => {
+router.delete('/:id', adminAuth, requirePermission('archives.delete'), requireEventOwnership, async (req, res) => {
   try {
     const archive = await db('events')
       .where('id', req.params.id)

backend/src/routes/adminAuth.js

@@ -1,5 +1,6 @@
 const express = require('express');
 const bcrypt = require('bcrypt');
+const jwt = require('jsonwebtoken');
 const { body } = require('express-validator');
 const { db, logActivity } = require('../database/db');
 const { adminAuth } = require('../middleware/auth');
@@ -7,6 +8,7 @@ const { endSession } = require('../middleware/sessionTimeout');
 const { validatePasswordStrength } = require('../utils/passwordGenerator');
 const { handleAsync, validateRequest, successResponse } = require('../utils/routeHelpers');
 const { NotFoundError, ConflictError, ValidationError } = require('../utils/errors');
+const { setAdminAuthCookie } = require('../utils/tokenUtils');
 const router = express.Router();
 
 // Get admin profile
@@ -122,15 +124,36 @@ router.post('/change-password', [
   // Hash new password with more rounds
   const newPasswordHash = await bcrypt.hash(newPassword, 12);
 
-  // Update password and clear must_change_password flag
+  // Update password, set password_changed_at to invalidate existing tokens, and clear must_change_password flag
+  const now = new Date();
   await db('admin_users')
     .where('id', userId)
     .update({
       password_hash: newPasswordHash,
+      password_changed_at: now,
       must_change_password: false,
-      updated_at: new Date()
+      updated_at: now
     });
 
+  // Issue a new token so the session remains valid after password_changed_at invalidated the old one.
+  // Set iat to 1 second after password_changed_at to guarantee the token passes the
+  // "iat < password_changed_at" check in auth middleware (password_changed_at has ms precision
+  // but JWT iat is floored to seconds, which can cause the new token to be rejected).
+  const iatAfterPasswordChange = Math.floor(now.getTime() / 1000) + 1;
+  const newToken = jwt.sign({
+    id: user.id,
+    username: user.username,
+    type: 'admin',
+    role: user.role_name,
+    iat: iatAfterPasswordChange,
+    loginTime: Date.now()
+  }, process.env.JWT_SECRET, {
+    expiresIn: '24h',
+    issuer: 'picpeak-auth'
+  });
+
+  setAdminAuthCookie(res, newToken);
+
   // Log activity
   await logActivity('password_changed',
     { admin_id: userId },

backend/src/routes/adminBackup.js

@@ -258,6 +258,13 @@ router.post('/test-connection', adminAuth, requirePermission('backup.create'), a
           break;
         }
 
+        // SSRF protection: block connections to private/internal addresses
+        const { isPrivateIP } = require('../utils/networkValidation');
+        if (isPrivateIP(host)) {
+          res.json({ success: false, message: 'Host cannot be a private or internal network address' });
+          break;
+        }
+
         // Validate username format if provided
         if (user && !/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(user)) {
           res.json({ success: false, message: 'Invalid username format' });
@@ -355,12 +362,17 @@ router.get('/manifest/:backupRunId', adminAuth, requirePermission('backup.view')
 router.post('/manifest/validate', adminAuth, requirePermission('backup.view'), async (req, res) => {
   try {
     const { manifestPath } = req.body;
-    
+
     if (!manifestPath) {
       return res.status(400).json({ error: 'manifestPath is required' });
     }
-    
-    const result = await validateBackupManifest(manifestPath);
+
+    // Prevent path traversal — manifest must be within backup directory
+    const backupBasePath = process.env.BACKUP_PATH || path.join(__dirname, '../../../backups');
+    const { safePathJoin } = require('../utils/fileSecurityUtils');
+    const safePath = safePathJoin(backupBasePath, manifestPath);
+
+    const result = await validateBackupManifest(safePath);
     
     res.json({
       valid: result.valid,
@@ -456,19 +468,24 @@ router.get('/manifests/:backupId/download', adminAuth, requirePermission('backup
 router.post('/manifests/validate', adminAuth, requirePermission('backup.view'), async (req, res) => {
   try {
     const { manifestPath, manifestData } = req.body;
-    
+
     if (!manifestPath && !manifestData) {
       return res.status(400).json({ error: 'Either manifestPath or manifestData is required' });
     }
-    
+
     if (manifestData) {
       // Validate provided manifest data directly
       const validationResult = await validateManifestData(manifestData);
       return res.json(validationResult);
     }
-    
+
+    // Prevent path traversal — manifest must be within backup directory
+    const backupBasePath = process.env.BACKUP_PATH || path.join(__dirname, '../../../backups');
+    const { safePathJoin } = require('../utils/fileSecurityUtils');
+    const safePath = safePathJoin(backupBasePath, manifestPath);
+
     // Use existing validation function for path
-    const result = await validateBackupManifest(manifestPath);
+    const result = await validateBackupManifest(safePath);
     
     res.json({
       valid: result.valid,
@@ -757,10 +774,14 @@ router.get('/checksums', adminAuth, requirePermission('backup.view'), async (req
   try {
     const { path: targetPath = '', recursive = true } = req.query;
     const checksums = {};
-    
+
     // Get storage path
     const storagePath = process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
-    const basePath = targetPath ? path.join(storagePath, targetPath) : storagePath;
+    let basePath = storagePath;
+    if (targetPath) {
+      const { safePathJoin } = require('../utils/fileSecurityUtils');
+      basePath = safePathJoin(storagePath, targetPath);
+    }
     
     // Calculate checksums for files
     async function calculateDirChecksums(dirPath, relative = '') {

backend/src/routes/adminCMS.js

@@ -1,10 +1,42 @@
 const express = require('express');
+const path = require('path');
+const fs = require('fs').promises;
+const multer = require('multer');
 const { body, validationResult } = require('express-validator');
 const { db, logActivity } = require('../database/db');
 const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
+const { validateFileType } = require('../utils/fileSecurityUtils');
 const router = express.Router();
 
+const getStoragePath = () => process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
+
+// Multer config for per-page logo uploads. Stores into the same
+// /uploads/logos directory the global branding logo uses, with a
+// per-slug filename so a page swap doesn't fight an unrelated upload.
+const pageLogoStorage = multer.diskStorage({
+  destination: async (_req, _file, cb) => {
+    const dir = path.join(getStoragePath(), 'uploads/logos');
+    await fs.mkdir(dir, { recursive: true });
+    cb(null, dir);
+  },
+  filename: (req, file, cb) => {
+    const ext = path.extname(file.originalname);
+    const safeSlug = (req.params.slug || 'page').replace(/[^a-z0-9-]/gi, '');
+    cb(null, `cms-${safeSlug}-${Date.now()}${ext}`);
+  }
+});
+
+const pageLogoUpload = multer({
+  storage: pageLogoStorage,
+  limits: { fileSize: 5 * 1024 * 1024 },
+  fileFilter: (_req, file, cb) => {
+    const allowed = ['image/jpeg', 'image/png', 'image/gif', 'image/svg+xml'];
+    if (validateFileType(file.originalname, file.mimetype, allowed)) cb(null, true);
+    else cb(new Error('Only JPEG, PNG, GIF and SVG image files are allowed'));
+  }
+});
+
 // Get all CMS pages
 router.get('/pages', adminAuth, requirePermission('cms.view'), async (req, res) => {
   try {
@@ -21,11 +53,11 @@ router.get('/pages/:slug', adminAuth, requirePermission('cms.view'), async (req,
   try {
     const { slug } = req.params;
     const page = await db('cms_pages').where('slug', slug).first();
-    
+
     if (!page) {
       return res.status(404).json({ error: 'Page not found' });
     }
-    
+
     res.json(page);
   } catch (error) {
     console.error('Error fetching CMS page:', error);
@@ -38,42 +70,46 @@ router.put('/pages/:slug', adminAuth, requirePermission('cms.edit'), [
   body('title_en').optional().isString(),
   body('title_de').optional().isString(),
   body('content_en').optional().isString(),
-  body('content_de').optional().isString()
+  body('content_de').optional().isString(),
+  body('logo_url').optional({ nullable: true }).isString()
 ], async (req, res) => {
   try {
     const errors = validationResult(req);
     if (!errors.isEmpty()) {
       return res.status(400).json({ errors: errors.array() });
     }
-    
+
     const { slug } = req.params;
-    const { title_en, title_de, content_en, content_de } = req.body;
-    
+    const { title_en, title_de, content_en, content_de, logo_url } = req.body;
+
     const page = await db('cms_pages').where('slug', slug).first();
     if (!page) {
       return res.status(404).json({ error: 'Page not found' });
     }
-    
-    // Update the page
-    await db('cms_pages')
-      .where('slug', slug)
-      .update({
-        title_en,
-        title_de,
-        content_en,
-        content_de,
-        updated_at: new Date()
-      });
-    
+
+    const updateFields = {
+      title_en,
+      title_de,
+      content_en,
+      content_de,
+      updated_at: new Date()
+    };
+    // Only touch logo_url when explicitly present so partial updates
+    // (e.g. text-only edits) don't accidentally clear the upload.
+    if (Object.prototype.hasOwnProperty.call(req.body, 'logo_url')) {
+      updateFields.logo_url = logo_url || null;
+    }
+
+    await db('cms_pages').where('slug', slug).update(updateFields);
+
     const updated = await db('cms_pages').where('slug', slug).first();
-    
-    // Log activity
+
     await logActivity('cms_page_updated',
       { page: slug },
       null,
       { type: 'admin', id: req.admin.id, name: req.admin.username }
     );
-    
+
     res.json(updated);
   } catch (error) {
     console.error('Error updating CMS page:', error);
@@ -81,4 +117,69 @@ router.put('/pages/:slug', adminAuth, requirePermission('cms.edit'), [
   }
 });
 
-module.exports = router;
+// Upload a per-page logo (#324). Persists the URL to cms_pages.logo_url
+// and returns it so the client can re-render without a refetch.
+router.post(
+  '/pages/:slug/logo',
+  adminAuth,
+  requirePermission('cms.edit'),
+  pageLogoUpload.single('logo'),
+  async (req, res) => {
+    try {
+      const { slug } = req.params;
+      if (!req.file) {
+        return res.status(400).json({ error: 'No file uploaded' });
+      }
+
+      const page = await db('cms_pages').where('slug', slug).first();
+      if (!page) {
+        // Best-effort cleanup of the orphaned upload before erroring.
+        await fs.unlink(req.file.path).catch(() => {});
+        return res.status(404).json({ error: 'Page not found' });
+      }
+
+      const logoUrl = `/uploads/logos/${path.basename(req.file.path)}`;
+      await db('cms_pages').where('slug', slug).update({
+        logo_url: logoUrl,
+        updated_at: new Date()
+      });
+
+      await logActivity('cms_page_logo_uploaded',
+        { page: slug },
+        null,
+        { type: 'admin', id: req.admin.id, name: req.admin.username }
+      );
+
+      res.json({ logo_url: logoUrl });
+    } catch (error) {
+      console.error('Error uploading CMS page logo:', error);
+      res.status(500).json({ error: 'Failed to upload logo' });
+    }
+  }
+);
+
+// Clear a per-page logo override (revert to global branding logo).
+router.delete(
+  '/pages/:slug/logo',
+  adminAuth,
+  requirePermission('cms.edit'),
+  async (req, res) => {
+    try {
+      const { slug } = req.params;
+      const page = await db('cms_pages').where('slug', slug).first();
+      if (!page) return res.status(404).json({ error: 'Page not found' });
+
+      await db('cms_pages').where('slug', slug).update({
+        logo_url: null,
+        updated_at: new Date()
+      });
+
+      res.json({ logo_url: null });
+    } catch (error) {
+      console.error('Error clearing CMS page logo:', error);
+      res.status(500).json({ error: 'Failed to clear logo' });
+    }
+  }
+);
+
+module.exports = router;

backend/src/routes/adminCategories.js

@@ -106,42 +106,53 @@ router.post('/', adminAuth, requirePermission('settings.edit'), [
 
 // Update a category
 router.put('/:id', adminAuth, requirePermission('settings.edit'), [
-  body('name').notEmpty().withMessage('Category name is required')
+  body('name').notEmpty().withMessage('Category name is required'),
+  body('hero_photo_id').optional({ nullable: true }).custom((value) => {
+    if (value === null || value === undefined) return true;
+    return Number.isInteger(Number(value));
+  }).withMessage('hero_photo_id must be an integer or null')
 ], async (req, res) => {
   try {
     const errors = validationResult(req);
     if (!errors.isEmpty()) {
       return res.status(400).json({ errors: errors.array() });
     }
-    
+
     const { id } = req.params;
-    const { name } = req.body;
-    
+    const { name, hero_photo_id } = req.body;
+
     const category = await db('photo_categories').where('id', id).first();
     if (!category) {
       return res.status(404).json({ error: 'Category not found' });
     }
-    
+
+    const updateData = {
+      name,
+      slug: name.toLowerCase()
+        .replace(/[^\w\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .trim()
+    };
+
+    // Update hero_photo_id if provided (including null to clear it)
+    if (Object.prototype.hasOwnProperty.call(req.body, 'hero_photo_id')) {
+      updateData.hero_photo_id = hero_photo_id || null;
+    }
+
     await db('photo_categories')
       .where('id', id)
-      .update({
-        name,
-        slug: name.toLowerCase()
-          .replace(/[^\w\s-]/g, '')
-          .replace(/\s+/g, '-')
-          .replace(/-+/g, '-')
-          .trim()
-      });
-    
+      .update(updateData);
+
     const updated = await db('photo_categories').where('id', id).first();
-    
+
     // Log activity
     await logActivity('category_updated',
-      { categoryName: name },
+      { categoryName: name, heroPhotoId: hero_photo_id },
       category.event_id,
       { type: 'admin', id: req.admin.id, name: req.admin.username }
     );
-    
+
     res.json(updated);
   } catch (error) {
     console.error('Error updating category:', error);
@@ -149,6 +160,55 @@ router.put('/:id', adminAuth, requirePermission('settings.edit'), [
   }
 });
 
+// Set category hero photo (#163)
+router.put('/:id/hero', adminAuth, requirePermission('settings.edit'), [
+  body('hero_photo_id').optional({ nullable: true }).custom((value) => {
+    if (value === null || value === undefined) return true;
+    return Number.isInteger(Number(value));
+  }).withMessage('hero_photo_id must be an integer or null')
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { id } = req.params;
+    const { hero_photo_id } = req.body;
+
+    const category = await db('photo_categories').where('id', id).first();
+    if (!category) {
+      return res.status(404).json({ error: 'Category not found' });
+    }
+
+    // If hero_photo_id is provided, verify it belongs to a photo in this category
+    if (hero_photo_id) {
+      const photo = await db('photos').where('id', hero_photo_id).first();
+      if (!photo) {
+        return res.status(404).json({ error: 'Photo not found' });
+      }
+    }
+
+    await db('photo_categories')
+      .where('id', id)
+      .update({ hero_photo_id: hero_photo_id || null });
+
+    const updated = await db('photo_categories').where('id', id).first();
+
+    // Log activity
+    await logActivity('category_hero_updated',
+      { categoryName: category.name, heroPhotoId: hero_photo_id },
+      category.event_id,
+      { type: 'admin', id: req.admin.id, name: req.admin.username }
+    );
+
+    res.json(updated);
+  } catch (error) {
+    console.error('Error updating category hero:', error);
+    res.status(500).json({ error: 'Failed to update category hero' });
+  }
+});
+
 // Delete a category
 router.delete('/:id', adminAuth, requirePermission('settings.edit'), async (req, res) => {
   try {

backend/src/routes/adminDashboard.js

@@ -62,6 +62,13 @@ router.get('/stats', adminAuth, requirePermission('analytics.view'), async (req,
       .count('id as count')
       .first();
 
+    // Get total events count (all events regardless of status) — used by the
+    // events list page to render accurate "All (N)" / Total Events counters
+    // when the table is server-paginated (#346).
+    const totalEvents = await db('events')
+      .count('id as count')
+      .first();
+
     // Calculate trends (compare with previous 30 days)
     const sixtyDaysAgo = new Date();
     sixtyDaysAgo.setDate(sixtyDaysAgo.getDate() - 60);
@@ -98,7 +105,8 @@ router.get('/stats', adminAuth, requirePermission('analytics.view'), async (req,
       totalDownloads: totalDownloads.count || 0,
       viewsTrend: Math.round(viewsTrend * 10) / 10,
       downloadsTrend: Math.round(downloadsTrend * 10) / 10,
-      archivedEvents: archivedEvents.count || 0
+      archivedEvents: archivedEvents.count || 0,
+      totalEvents: totalEvents.count || 0
     });
   } catch (error) {
     console.error('Dashboard stats error:', error);

backend/src/routes/adminEmail.js

@@ -4,6 +4,7 @@ const { body, validationResult } = require('express-validator');
 const { db, logActivity } = require('../database/db');
 const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
+const { wrapEmailHtml } = require('../services/emailProcessor');
 const router = express.Router();
 
 // Get email configuration
@@ -60,6 +61,12 @@ router.post('/config', [
       tls_reject_unauthorized
     } = req.body;
 
+    // Validate SMTP host is not a private/internal address (SSRF protection)
+    const { isPrivateIP } = require('../utils/networkValidation');
+    if (isPrivateIP(smtp_host)) {
+      return res.status(400).json({ error: 'SMTP host cannot point to a private or internal network address' });
+    }
+
     // Check if config exists
     const existingConfig = await db('email_configs').first();
     
@@ -159,22 +166,26 @@ router.post('/test', adminAuth, requirePermission('email.send'), async (req, res
 
     const transporter = nodemailer.createTransport(transportConfig);
 
-    // Send test email
+    // Send test email with the same wrapper used for all other emails
+    const subject = 'Test Email - Photo Sharing Platform';
+    const testHtmlBody = `
+      <h2>Test Email Successful!</h2>
+      <p>This is a test email from your Photo Sharing platform.</p>
+      <p>If you're seeing this, your email configuration is working correctly.</p>
+      <hr>
+      <p style="color: #666; font-size: 12px;">
+        Sent from: ${config.from_email}<br>
+        SMTP Host: ${config.smtp_host}<br>
+        Time: ${new Date().toISOString()}
+      </p>
+    `;
+    const wrappedHtml = await wrapEmailHtml(testHtmlBody, subject);
+
     await transporter.sendMail({
       from: `${config.from_name} <${config.from_email}>`,
       to: test_email,
-      subject: 'Test Email - Photo Sharing Platform',
-      html: `
-        <h2>Test Email Successful!</h2>
-        <p>This is a test email from your Photo Sharing platform.</p>
-        <p>If you're seeing this, your email configuration is working correctly.</p>
-        <hr>
-        <p style="color: #666; font-size: 12px;">
-          Sent from: ${config.from_email}<br>
-          SMTP Host: ${config.smtp_host}<br>
-          Time: ${new Date().toISOString()}
-        </p>
-      `,
+      subject,
+      html: wrappedHtml,
       text: 'Test Email Successful! Your email configuration is working correctly.'
     });
 
@@ -237,6 +248,58 @@ router.post('/test', adminAuth, requirePermission('email.send'), async (req, res
   }
 });
 
+// Helper: parse variables JSON safely
+function parseVariables(template) {
+  try {
+    if (!template.variables) return [];
+    if (typeof template.variables === 'object') return template.variables;
+    return JSON.parse(template.variables);
+  } catch (e) {
+    console.warn('Failed to parse variables for template:', template.template_key, e.message);
+    return [];
+  }
+}
+
+// Helper: get translations for a template, with legacy column fallback
+async function getTemplateTranslations(templateId, template) {
+  const translations = {};
+  try {
+    const rows = await db('email_template_translations')
+      .where('template_id', templateId)
+      .select('language', 'subject', 'body_html', 'body_text');
+
+    rows.forEach(row => {
+      translations[row.language] = {
+        subject: row.subject || '',
+        body_html: row.body_html || '',
+        body_text: row.body_text || '',
+      };
+    });
+  } catch (error) {
+    // Translations table might not exist yet (pre-migration)
+    // Fall back to legacy columns
+    if (template.subject_en !== undefined) {
+      translations.en = {
+        subject: template.subject_en || '',
+        body_html: template.body_html_en || '',
+        body_text: template.body_text_en || '',
+      };
+      translations.de = {
+        subject: template.subject_de || '',
+        body_html: template.body_html_de || '',
+        body_text: template.body_text_de || '',
+      };
+    } else {
+      translations.en = {
+        subject: template.subject || '',
+        body_html: template.body_html || '',
+        body_text: template.body_text || '',
+      };
+    }
+  }
+  return translations;
+}
+
 // Get email templates
 router.get('/templates', adminAuth, requirePermission('email.view'), async (req, res) => {
   try {
@@ -244,45 +307,17 @@ router.get('/templates', adminAuth, requirePermission('email.view'), async (req,
       .select('*')
       .orderBy('template_key');
 
-    // Parse variables JSON and format for multi-language support
-    const formattedTemplates = templates.map(template => {
-      const result = {
+    const formattedTemplates = [];
+    for (const template of templates) {
+      const translations = await getTemplateTranslations(template.id, template);
+      formattedTemplates.push({
         id: template.id,
         template_key: template.template_key,
-        variables: (() => {
-          try {
-            if (!template.variables) return [];
-            if (typeof template.variables === 'object') return template.variables;
-            return JSON.parse(template.variables);
-          } catch (e) {
-            console.warn('Failed to parse variables for template:', template.template_key, e.message);
-            return [];
-          }
-        })(),
-        updated_at: template.updated_at
-      };
-      
-      // Handle both old and new schema formats
-      if (template.subject_en !== undefined) {
-        // New schema with language columns
-        result.subject_en = template.subject_en;
-        result.body_html_en = template.body_html_en;
-        result.body_text_en = template.body_text_en;
-        result.subject_de = template.subject_de;
-        result.body_html_de = template.body_html_de;
-        result.body_text_de = template.body_text_de;
-      } else {
-        // Old schema - use basic columns for both languages
-        result.subject_en = template.subject;
-        result.body_html_en = template.body_html;
-        result.body_text_en = template.body_text;
-        result.subject_de = template.subject;
-        result.body_html_de = template.body_html;
-        result.body_text_de = template.body_text;
-      }
-      
-      return result;
-    });
+        variables: parseVariables(template),
+        translations,
+        updated_at: template.updated_at,
+      });
+    }
 
     res.json(formattedTemplates);
   } catch (error) {
@@ -302,119 +337,99 @@ router.get('/templates/:key', adminAuth, requirePermission('email.view'), async
       return res.status(404).json({ error: 'Template not found' });
     }
 
-    // Handle both old and new schema formats
-    const response = {
+    const translations = await getTemplateTranslations(template.id, template);
+
+    res.json({
       id: template.id,
       template_key: template.template_key,
-      variables: (() => {
-        try {
-          if (!template.variables) return [];
-          if (typeof template.variables === 'object') return template.variables;
-          return JSON.parse(template.variables);
-        } catch (e) {
-          console.warn('Failed to parse variables for template:', template.template_key, e.message);
-          return [];
-        }
-      })(),
-      updated_at: template.updated_at
-    };
-    
-    // Check which columns exist and use them appropriately
-    if (template.subject_en !== undefined) {
-      // New schema with language columns
-      response.subject_en = template.subject_en;
-      response.body_html_en = template.body_html_en;
-      response.body_text_en = template.body_text_en;
-      response.subject_de = template.subject_de;
-      response.body_html_de = template.body_html_de;
-      response.body_text_de = template.body_text_de;
-    } else {
-      // Old schema - use basic columns for both languages
-      response.subject_en = template.subject;
-      response.body_html_en = template.body_html;
-      response.body_text_en = template.body_text;
-      response.subject_de = template.subject;
-      response.body_html_de = template.body_html;
-      response.body_text_de = template.body_text;
-    }
-    
-    res.json(response);
+      variables: parseVariables(template),
+      translations,
+      updated_at: template.updated_at,
+    });
   } catch (error) {
     console.error('Email template fetch error:', error);
     res.status(500).json({ error: 'Failed to fetch email template' });
   }
 });
 
-// Update email template
+// Update email template translations
 router.put('/templates/:key', [
   adminAuth,
   requirePermission('email.edit'),
-  body('subject_en').optional().notEmpty().withMessage('English subject cannot be empty'),
-  body('subject_de').optional().notEmpty().withMessage('German subject cannot be empty'),
-  body('body_html_en').optional().notEmpty().withMessage('English HTML body cannot be empty'),
-  body('body_html_de').optional().notEmpty().withMessage('German HTML body cannot be empty')
 ], async (req, res) => {
   try {
-    const errors = validationResult(req);
-    if (!errors.isEmpty()) {
-      return res.status(400).json({ errors: errors.array() });
-    }
-
-    const {
-      subject_en, subject_de,
-      body_html_en, body_html_de,
-      body_text_en, body_text_de
-    } = req.body;
-
-    const updateData = {
-      updated_at: new Date()
-    };
-
-    // Check which columns exist in the database
     const template = await db('email_templates')
       .where('template_key', req.params.key)
       .first();
-      
+
     if (!template) {
       return res.status(404).json({ error: 'Template not found' });
     }
 
-    // Determine schema type and update accordingly
-    if (template.subject_en !== undefined) {
-      // New schema with language columns
-      if (subject_en !== undefined) updateData.subject_en = subject_en;
-      if (subject_de !== undefined) updateData.subject_de = subject_de;
-      if (body_html_en !== undefined) updateData.body_html_en = body_html_en;
-      if (body_html_de !== undefined) updateData.body_html_de = body_html_de;
-      if (body_text_en !== undefined) updateData.body_text_en = body_text_en || '';
-      if (body_text_de !== undefined) updateData.body_text_de = body_text_de || '';
-      
-      // Also update basic columns if they exist
-      if (template.subject !== undefined) {
-        updateData.subject = subject_en || updateData.subject_en;
-        updateData.body_html = body_html_en || updateData.body_html_en;
-        updateData.body_text = body_text_en || updateData.body_text_en || '';
-      }
-    } else {
-      // Old schema - only update basic columns
-      if (subject_en !== undefined) {
-        updateData.subject = subject_en;
-        updateData.body_html = body_html_en;
-        updateData.body_text = body_text_en || '';
+    const { translations } = req.body;
+
+    if (!translations || typeof translations !== 'object') {
+      return res.status(400).json({ error: 'translations object is required' });
+    }
+
+    // Upsert each language translation
+    for (const [language, data] of Object.entries(translations)) {
+      if (!data || typeof data !== 'object') continue;
+
+      const existing = await db('email_template_translations')
+        .where({ template_id: template.id, language })
+        .first();
+
+      const row = {
+        subject: data.subject || '',
+        body_html: data.body_html || '',
+        body_text: data.body_text || '',
+        updated_at: new Date(),
+      };
+
+      if (existing) {
+        await db('email_template_translations')
+          .where({ template_id: template.id, language })
+          .update(row);
+      } else {
+        await db('email_template_translations').insert({
+          template_id: template.id,
+          language,
+          ...row,
+          created_at: new Date(),
+        });
       }
     }
 
-    const updated = await db('email_templates')
-      .where('template_key', req.params.key)
-      .update(updateData);
+    // Update timestamp on parent template
+    await db('email_templates')
+      .where('id', template.id)
+      .update({ updated_at: new Date() });
 
-    if (!updated) {
-      return res.status(404).json({ error: 'Template not found' });
+    // Also sync legacy columns for backward compatibility
+    const enData = translations.en;
+    const deData = translations.de;
+    const legacyUpdate = { updated_at: new Date() };
+    const columnInfo = await db('email_templates').columnInfo();
+
+    if (enData && columnInfo.subject_en) {
+      legacyUpdate.subject_en = enData.subject || '';
+      legacyUpdate.body_html_en = enData.body_html || '';
+      legacyUpdate.body_text_en = enData.body_text || '';
     }
+    if (deData && columnInfo.subject_de) {
+      legacyUpdate.subject_de = deData.subject || '';
+      legacyUpdate.body_html_de = deData.body_html || '';
+      legacyUpdate.body_text_de = deData.body_text || '';
+    }
+
+    await db('email_templates')
+      .where('id', template.id)
+      .update(legacyUpdate);
 
     // Log activity
     await logActivity('email_template_updated',
-      { template_key: req.params.key },
+      { template_key: req.params.key, languages: Object.keys(translations) },
       null,
       { type: 'admin', id: req.admin.id, name: req.admin.username }
     );
@@ -438,29 +453,64 @@ router.post('/templates/:key/preview', adminAuth, requirePermission('email.view'
     }
 
     const { preview_data, language = 'en' } = req.body;
-    
-    // Get the appropriate language version
-    const subjectField = language === 'de' && template.subject_de ? 'subject_de' : 'subject_en';
-    const htmlField = language === 'de' && template.body_html_de ? 'body_html_de' : 'body_html_en';
-    const textField = language === 'de' && template.body_text_de ? 'body_text_de' : 'body_text_en';
-    
-    // Handle backward compatibility
-    let htmlContent = template[htmlField] || template.body_html || '';
-    let textContent = template[textField] || template.body_text || '';
-    let subject = template[subjectField] || template.subject || '';
+
+    // Get translation from translations table with fallback
+    let translation = null;
+    try {
+      translation = await db('email_template_translations')
+        .where({ template_id: template.id, language })
+        .first();
+
+      if (!translation && language !== 'en') {
+        translation = await db('email_template_translations')
+          .where({ template_id: template.id, language: 'en' })
+          .first();
+      }
+    } catch (e) {
+      // Fallback to legacy columns
+    }
+
+    let subject = '';
+    let htmlContent = '';
+    let textContent = '';
+
+    if (translation) {
+      subject = translation.subject || '';
+      htmlContent = translation.body_html || '';
+      textContent = translation.body_text || '';
+    } else {
+      // Legacy column fallback
+      const subjectField = language === 'de' && template.subject_de ? 'subject_de' : 'subject_en';
+      const htmlField = language === 'de' && template.body_html_de ? 'body_html_de' : 'body_html_en';
+      const textField = language === 'de' && template.body_text_de ? 'body_text_de' : 'body_text_en';
+      subject = template[subjectField] || template.subject || '';
+      htmlContent = template[htmlField] || template.body_html || '';
+      textContent = template[textField] || template.body_text || '';
+    }
 
     if (preview_data) {
+      const escapeHtml = (str) => String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+
       Object.keys(preview_data).forEach(key => {
         const regex = new RegExp(`{{${key}}}`, 'g');
-        htmlContent = htmlContent.replace(regex, preview_data[key]);
+        const escapedValue = escapeHtml(preview_data[key]);
+        htmlContent = htmlContent.replace(regex, escapedValue);
         textContent = textContent.replace(regex, preview_data[key]);
-        subject = subject.replace(regex, preview_data[key]);
+        subject = subject.replace(regex, escapeHtml(preview_data[key]));
       });
     }
 
+    // Wrap in the full styled email template with header/footer/logo
+    const wrappedHtml = await wrapEmailHtml(htmlContent, subject, language);
+
     res.json({
       subject,
-      body_html: htmlContent,
+      body_html: wrappedHtml,
       body_text: textContent,
       language
     });

backend/src/routes/adminEventTypes.js

@@ -0,0 +1,258 @@
+/**
+ * Admin Event Types Routes
+ * CRUD operations for managing customizable event types
+ *
+ * @module routes/adminEventTypes
+ */
+
+const express = require('express');
+const { body, param, validationResult } = require('express-validator');
+const { logActivity } = require('../database/db');
+const { adminAuth } = require('../middleware/auth');
+const { requirePermission } = require('../middleware/permissions');
+const eventTypeService = require('../services/eventTypeService');
+const logger = require('../utils/logger');
+
+const router = express.Router();
+
+/**
+ * GET /admin/event-types
+ * Get all event types (for admin management)
+ */
+router.get('/', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
+    const includeInactive = req.query.includeInactive === 'true';
+    const eventTypes = await eventTypeService.getAllEventTypes({
+      activeOnly: !includeInactive
+    });
+
+    res.json({ eventTypes });
+  } catch (error) {
+    logger.error('Error fetching event types:', { error: error.message });
+    res.status(500).json({ error: 'Failed to fetch event types' });
+  }
+});
+
+/**
+ * GET /admin/event-types/active
+ * Get only active event types (for dropdowns/selection)
+ */
+router.get('/active', adminAuth, async (req, res) => {
+  try {
+    const eventTypes = await eventTypeService.getActiveEventTypes();
+    res.json({ eventTypes });
+  } catch (error) {
+    logger.error('Error fetching active event types:', { error: error.message });
+    res.status(500).json({ error: 'Failed to fetch event types' });
+  }
+});
+
+/**
+ * GET /admin/event-types/:id
+ * Get a single event type by ID
+ */
+router.get('/:id', adminAuth, requirePermission('settings.view'), [
+  param('id').isInt().withMessage('Invalid event type ID')
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { id } = req.params;
+    const eventType = await eventTypeService.getEventTypeById(parseInt(id));
+
+    if (!eventType) {
+      return res.status(404).json({ error: 'Event type not found' });
+    }
+
+    res.json(eventType);
+  } catch (error) {
+    logger.error('Error fetching event type:', { error: error.message });
+    res.status(500).json({ error: 'Failed to fetch event type' });
+  }
+});
+
+/**
+ * POST /admin/event-types
+ * Create a new event type
+ */
+router.post('/', adminAuth, requirePermission('settings.edit'), [
+  body('name').notEmpty().trim().withMessage('Name is required'),
+  body('slug_prefix')
+    .notEmpty()
+    .trim()
+    .isLength({ min: 2, max: 50 })
+    .matches(/^[a-z0-9-]+$/i)
+    .withMessage('Slug prefix must be 2-50 characters and contain only letters, numbers, and hyphens'),
+  body('emoji').optional().trim(),
+  body('theme_preset').optional().trim(),
+  body('theme_config').optional(),
+  body('display_order').optional().isInt({ min: 0 })
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const {
+      name,
+      slug_prefix,
+      emoji,
+      theme_preset,
+      theme_config,
+      display_order
+    } = req.body;
+
+    const eventType = await eventTypeService.createEventType({
+      name,
+      slug_prefix,
+      emoji,
+      theme_preset,
+      theme_config,
+      display_order
+    });
+
+    // Log activity
+    await logActivity('event_type_created',
+      { name, slug_prefix },
+      null,
+      { type: 'admin', id: req.admin.id, name: req.admin.username }
+    );
+
+    res.status(201).json(eventType);
+  } catch (error) {
+    logger.error('Error creating event type:', { error: error.message });
+
+    if (error.code === 'DUPLICATE_SLUG_PREFIX') {
+      return res.status(400).json({ error: error.message });
+    }
+
+    res.status(500).json({ error: 'Failed to create event type' });
+  }
+});
+
+/**
+ * PUT /admin/event-types/:id
+ * Update an event type
+ */
+router.put('/:id', adminAuth, requirePermission('settings.edit'), [
+  param('id').isInt().withMessage('Invalid event type ID'),
+  body('name').optional().notEmpty().trim().withMessage('Name cannot be empty'),
+  body('slug_prefix')
+    .optional()
+    .trim()
+    .isLength({ min: 2, max: 50 })
+    .matches(/^[a-z0-9-]+$/i)
+    .withMessage('Slug prefix must be 2-50 characters and contain only letters, numbers, and hyphens'),
+  body('emoji').optional().trim(),
+  body('theme_preset').optional().trim(),
+  body('theme_config').optional(),
+  body('display_order').optional().isInt({ min: 0 }),
+  body('is_active').optional().isBoolean()
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { id } = req.params;
+    const updates = req.body;
+
+    const eventType = await eventTypeService.updateEventType(parseInt(id), updates);
+
+    // Log activity
+    await logActivity('event_type_updated',
+      { id, changes: Object.keys(updates) },
+      null,
+      { type: 'admin', id: req.admin.id, name: req.admin.username }
+    );
+
+    res.json(eventType);
+  } catch (error) {
+    logger.error('Error updating event type:', { error: error.message });
+
+    if (error.code === 'NOT_FOUND') {
+      return res.status(404).json({ error: error.message });
+    }
+    if (error.code === 'DUPLICATE_SLUG_PREFIX') {
+      return res.status(400).json({ error: error.message });
+    }
+
+    res.status(500).json({ error: 'Failed to update event type' });
+  }
+});
+
+/**
+ * DELETE /admin/event-types/:id
+ * Delete an event type (only non-system types with no events)
+ */
+router.delete('/:id', adminAuth, requirePermission('settings.edit'), [
+  param('id').isInt().withMessage('Invalid event type ID')
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { id } = req.params;
+    const result = await eventTypeService.deleteEventType(parseInt(id));
+
+    // Log activity
+    await logActivity('event_type_deleted',
+      { id, name: result.deleted.name, slug_prefix: result.deleted.slug_prefix },
+      null,
+      { type: 'admin', id: req.admin.id, name: req.admin.username }
+    );
+
+    res.json({ message: 'Event type deleted successfully' });
+  } catch (error) {
+    logger.error('Error deleting event type:', { error: error.message });
+
+    if (error.code === 'NOT_FOUND') {
+      return res.status(404).json({ error: error.message });
+    }
+    if (error.code === 'SYSTEM_TYPE' || error.code === 'IN_USE') {
+      return res.status(400).json({ error: error.message });
+    }
+
+    res.status(500).json({ error: 'Failed to delete event type' });
+  }
+});
+
+/**
+ * POST /admin/event-types/reorder
+ * Reorder event types by providing an array of IDs in the desired order
+ */
+router.post('/reorder', adminAuth, requirePermission('settings.edit'), [
+  body('orderedIds').isArray().withMessage('orderedIds must be an array'),
+  body('orderedIds.*').isInt().withMessage('Each ID must be an integer')
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { orderedIds } = req.body;
+    const eventTypes = await eventTypeService.reorderEventTypes(orderedIds);
+
+    // Log activity
+    await logActivity('event_types_reordered',
+      { newOrder: orderedIds },
+      null,
+      { type: 'admin', id: req.admin.id, name: req.admin.username }
+    );
+
+    res.json({ eventTypes, message: 'Event types reordered successfully' });
+  } catch (error) {
+    logger.error('Error reordering event types:', { error: error.message });
+    res.status(500).json({ error: 'Failed to reorder event types' });
+  }
+});
+
+module.exports = router;

backend/src/routes/adminEvents-enhanced.js

@@ -6,8 +6,10 @@ const { buildShareLinkVariants } = require('../services/shareLinkService');
 const { requirePermission } = require('../middleware/permissions');
 
 // Enhanced event creation with password validation
+// Note: This is a partial/reference file - dynamic event type validation should be implemented
+// similar to adminEvents.js using eventTypeService.isValidEventType()
 router.post('/', adminAuth, requirePermission('events.create'), [
-  body('event_type').isIn(['wedding', 'birthday', 'corporate', 'other']),
+  body('event_type').notEmpty().trim(), // Dynamic validation via eventTypeService
   body('event_name').notEmpty().trim(),
   body('event_date').isDate(),
   body('customer_email').isEmail().normalizeEmail(),
@@ -40,7 +42,8 @@ router.post('/', adminAuth, requirePermission('events.create'), [
       color_theme = null,
       expiration_days = 30,
       allow_user_uploads = false,
-      upload_category_id = null
+      upload_category_id = null,
+      photo_cap = null
     } = req.body;
     
     // Validate password strength for gallery
@@ -103,7 +106,8 @@ router.post('/', adminAuth, requirePermission('events.create'), [
       expires_at: expires_at.toISOString(),
       created_at: new Date().toISOString(),
       allow_user_uploads,
-      upload_category_id
+      upload_category_id,
+      photo_cap: photo_cap || null
     }).returning('id');
     
     // Handle both PostgreSQL (returns array of objects) and SQLite (returns array of IDs)

backend/src/routes/adminExternalMedia.js

@@ -5,6 +5,7 @@ const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
 const { list, resolveExternalPath, getExternalMediaRoot } = require('../services/externalMediaService');
 const { db, logActivity } = require('../database/db');
+const sharp = require('sharp');
 const logger = require('../utils/logger');
 
 const router = express.Router();
@@ -108,6 +109,18 @@ router.post('/events/:id/import-external', adminAuth, requirePermission('photos.
           .first();
         if (exists) { skipped++; continue; }
         const stats = await fs.stat(f.full);
+
+        // Extract dimensions via Sharp
+        let width = null;
+        let height = null;
+        try {
+          const metadata = await sharp(f.full).metadata();
+          width = metadata.width || null;
+          height = metadata.height || null;
+        } catch (dimErr) {
+          logger.warn(`Could not extract dimensions for ${f.rel}: ${dimErr.message}`);
+        }
+
         const inserted = await db('photos')
           .insert({
             event_id: eventId,
@@ -117,6 +130,8 @@ router.post('/events/:id/import-external', adminAuth, requirePermission('photos.
             thumbnail_path: null,
             type,
             size_bytes: stats.size,
+            width,
+            height,
             source_origin: 'external',
             external_relpath: f.rel
           })

backend/src/routes/adminFeedback.js

@@ -12,11 +12,13 @@ const {
   validateWordFilter,
   checkValidation
 } = require('../utils/feedbackValidation');
+const { requireEventOwnership } = require('../middleware/ownership');
 
 // Get event feedback settings
 router.get('/events/:eventId/feedback-settings',
   adminAuth,
   requirePermission('events.view'),
+  requireEventOwnership,
   validateEventId,
   checkValidation,
   async (req, res) => {
@@ -42,6 +44,7 @@ router.get('/events/:eventId/feedback-settings',
 router.put('/events/:eventId/feedback-settings',
   adminAuth,
   requirePermission('events.edit'),
+  requireEventOwnership,
   validateEventId,
   validateFeedbackSettings,
   checkValidation,
@@ -79,6 +82,7 @@ router.put('/events/:eventId/feedback-settings',
 router.get('/events/:eventId/feedback',
   adminAuth,
   requirePermission('events.view'),
+  requireEventOwnership,
   validateEventId,
   checkValidation,
   async (req, res) => {
@@ -204,6 +208,7 @@ router.delete('/feedback/:feedbackId',
 router.get('/events/:eventId/feedback-analytics',
   adminAuth,
   requirePermission('events.view'),
+  requireEventOwnership,
   validateEventId,
   checkValidation,
   async (req, res) => {
@@ -304,6 +309,7 @@ router.get('/events/:eventId/feedback-analytics',
 router.get('/events/:eventId/feedback/export',
   adminAuth,
   requirePermission('events.view'),
+  requireEventOwnership,
   validateEventId,
   checkValidation,
   async (req, res) => {

backend/src/routes/adminGuests.js

@@ -0,0 +1,609 @@
+const express = require('express');
+const crypto = require('crypto');
+const archiver = require('archiver');
+const router = express.Router();
+const { db, logActivity } = require('../database/db');
+const { adminAuth } = require('../middleware/auth');
+const { requirePermission } = require('../middleware/permissions');
+const { requireEventOwnership } = require('../middleware/ownership');
+const feedbackService = require('../services/feedbackService');
+const logger = require('../utils/logger');
+
+const FRONTEND_URL = process.env.FRONTEND_URL || '';
+
+// ----------------------------------------------------------------------------
+// Helpers
+// ----------------------------------------------------------------------------
+
+async function loadGuestOr404(eventId, guestId, res) {
+  const guest = await db('gallery_guests')
+    .where({ id: guestId, event_id: eventId, is_deleted: false })
+    .first();
+  if (!guest) {
+    res.status(404).json({ error: 'Guest not found' });
+    return null;
+  }
+  return guest;
+}
+
+function serializeGuest(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    email: row.email,
+    created_at: row.created_at,
+    last_seen_at: row.last_seen_at,
+    email_verified_at: row.email_verified_at,
+    is_deleted: row.is_deleted,
+  };
+}
+
+function escapeCsvCell(value) {
+  const str = value == null ? '' : String(value);
+  if (/[,"\n\r]/.test(str)) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+// ----------------------------------------------------------------------------
+// GET /admin/events/:eventId/guests — list guests with aggregated counts
+// ----------------------------------------------------------------------------
+
+router.get(
+  '/events/:eventId/guests',
+  adminAuth,
+  requirePermission('events.view'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId } = req.params;
+
+      const rows = await db('gallery_guests')
+        .leftJoin('photo_feedback', function () {
+          this.on('photo_feedback.guest_id', '=', 'gallery_guests.id');
+        })
+        .where('gallery_guests.event_id', eventId)
+        .where('gallery_guests.is_deleted', false)
+        .groupBy('gallery_guests.id')
+        .select(
+          'gallery_guests.id',
+          'gallery_guests.name',
+          'gallery_guests.email',
+          'gallery_guests.created_at',
+          'gallery_guests.last_seen_at',
+          'gallery_guests.email_verified_at',
+          db.raw("COUNT(CASE WHEN photo_feedback.feedback_type = 'like' THEN 1 END) AS likes"),
+          db.raw("COUNT(CASE WHEN photo_feedback.feedback_type = 'favorite' THEN 1 END) AS favorites"),
+          db.raw("COUNT(CASE WHEN photo_feedback.feedback_type = 'comment' THEN 1 END) AS comments"),
+          db.raw("COUNT(CASE WHEN photo_feedback.feedback_type = 'rating' THEN 1 END) AS ratings"),
+          db.raw('COUNT(DISTINCT photo_feedback.photo_id) AS distinct_photos')
+        )
+        .orderBy('gallery_guests.created_at', 'desc');
+
+      const guests = rows.map((r) => ({
+        ...serializeGuest(r),
+        stats: {
+          likes: parseInt(r.likes, 10) || 0,
+          favorites: parseInt(r.favorites, 10) || 0,
+          comments: parseInt(r.comments, 10) || 0,
+          ratings: parseInt(r.ratings, 10) || 0,
+          distinct_photos: parseInt(r.distinct_photos, 10) || 0,
+        },
+      }));
+
+      res.json({ guests });
+    } catch (error) {
+      logger.error('Error listing guests:', error);
+      res.status(500).json({ error: 'Failed to list guests' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// GET /admin/events/:eventId/guests/aggregate — photos sorted by distinct
+// guest pick count (Phase 2 aggregate view)
+// ----------------------------------------------------------------------------
+
+router.get(
+  '/events/:eventId/guests/aggregate',
+  adminAuth,
+  requirePermission('events.view'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId } = req.params;
+
+      const photos = await db('photos')
+        .leftJoin('photo_feedback', function () {
+          this.on('photo_feedback.photo_id', '=', 'photos.id')
+            .andOn(db.raw("photo_feedback.feedback_type IN ('like','favorite')"))
+            .andOnNotNull('photo_feedback.guest_id');
+        })
+        .where('photos.event_id', eventId)
+        .groupBy('photos.id')
+        .select(
+          'photos.id',
+          'photos.filename',
+          'photos.original_filename',
+          db.raw('COUNT(DISTINCT photo_feedback.guest_id) AS picker_count')
+        )
+        .orderBy('picker_count', 'desc')
+        .orderBy('photos.id', 'desc');
+
+      res.json({
+        photos: photos
+          .filter((p) => parseInt(p.picker_count, 10) > 0)
+          .map((p) => ({
+            id: p.id,
+            filename: p.filename,
+            original_filename: p.original_filename,
+            url: `/api/admin/photos/${eventId}/photo/${p.id}`,
+            thumbnail_url: `/api/admin/photos/${eventId}/thumbnail/${p.id}`,
+            picker_count: parseInt(p.picker_count, 10),
+          })),
+      });
+    } catch (error) {
+      logger.error('Error fetching aggregate view:', error);
+      res.status(500).json({ error: 'Failed to fetch aggregate view' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// GET /admin/events/:eventId/guests/invites — list pre-minted invites
+// ----------------------------------------------------------------------------
+
+router.get(
+  '/events/:eventId/guests/invites',
+  adminAuth,
+  requirePermission('events.view'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId } = req.params;
+      const event = await db('events').where({ id: eventId }).first();
+
+      const rows = await db('guest_invites')
+        .leftJoin('gallery_guests', 'gallery_guests.id', 'guest_invites.guest_id')
+        .where('guest_invites.event_id', eventId)
+        .select(
+          'guest_invites.id',
+          'guest_invites.token',
+          'guest_invites.created_at',
+          'guest_invites.redeemed_at',
+          'guest_invites.revoked_at',
+          'gallery_guests.id as guest_id',
+          'gallery_guests.name as guest_name',
+          'gallery_guests.email as guest_email'
+        )
+        .orderBy('guest_invites.created_at', 'desc');
+
+      const invites = rows.map((r) => ({
+        id: r.id,
+        token: r.token,
+        url: `${FRONTEND_URL}/gallery/${event.slug}?invite=${r.token}`,
+        created_at: r.created_at,
+        redeemed_at: r.redeemed_at,
+        revoked_at: r.revoked_at,
+        status: r.revoked_at ? 'revoked' : r.redeemed_at ? 'redeemed' : 'pending',
+        guest: {
+          id: r.guest_id,
+          name: r.guest_name,
+          email: r.guest_email,
+        },
+      }));
+
+      res.json({ invites });
+    } catch (error) {
+      logger.error('Error listing invites:', error);
+      res.status(500).json({ error: 'Failed to list invites' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// POST /admin/events/:eventId/guests/invites — create guest + invite
+// Body: { name, email? }
+// ----------------------------------------------------------------------------
+
+router.post(
+  '/events/:eventId/guests/invites',
+  adminAuth,
+  requirePermission('events.edit'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId } = req.params;
+      const name = String(req.body?.name || '').trim().slice(0, 100);
+      const email = String(req.body?.email || '').trim().slice(0, 255).toLowerCase();
+      if (!name) {
+        return res.status(400).json({ error: 'Name is required' });
+      }
+
+      const identifier = crypto.randomUUID();
+      const inviteToken = crypto.randomBytes(24).toString('hex');
+
+      let guestId;
+      let inviteId;
+      await db.transaction(async (trx) => {
+        const [guestRow] = await trx('gallery_guests')
+          .insert({
+            event_id: eventId,
+            name,
+            email: email || null,
+            identifier,
+          })
+          .returning(['id']);
+        guestId = guestRow.id;
+
+        const [inviteRow] = await trx('guest_invites')
+          .insert({
+            event_id: eventId,
+            guest_id: guestId,
+            token: inviteToken,
+            created_by_admin_id: req.admin.id,
+          })
+          .returning(['id']);
+        inviteId = inviteRow.id;
+      });
+
+      await logActivity(
+        'guest_invite_created',
+        { event_id: eventId, guest_id: guestId, invite_id: inviteId },
+        eventId,
+        { type: 'admin', id: req.admin.id, name: req.admin.username }
+      );
+
+      const event = await db('events').where({ id: eventId }).first();
+      res.json({
+        invite: {
+          id: inviteId,
+          token: inviteToken,
+          url: `${FRONTEND_URL}/gallery/${event.slug}?invite=${inviteToken}`,
+          status: 'pending',
+          guest: { id: guestId, name, email: email || null },
+        },
+      });
+    } catch (error) {
+      logger.error('Error creating invite:', error);
+      res.status(500).json({ error: 'Failed to create invite' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// DELETE /admin/events/:eventId/guests/invites/:inviteId — revoke
+// ----------------------------------------------------------------------------
+
+router.delete(
+  '/events/:eventId/guests/invites/:inviteId',
+  adminAuth,
+  requirePermission('events.edit'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId, inviteId } = req.params;
+      const updated = await db('guest_invites')
+        .where({ id: inviteId, event_id: eventId })
+        .whereNull('revoked_at')
+        .update({ revoked_at: db.fn.now() });
+
+      if (!updated) {
+        return res.status(404).json({ error: 'Invite not found or already revoked' });
+      }
+
+      await logActivity(
+        'guest_invite_revoked',
+        { event_id: eventId, invite_id: inviteId },
+        eventId,
+        { type: 'admin', id: req.admin.id, name: req.admin.username }
+      );
+
+      res.json({ success: true });
+    } catch (error) {
+      logger.error('Error revoking invite:', error);
+      res.status(500).json({ error: 'Failed to revoke invite' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// GET /admin/events/:eventId/guests/export-all — ZIP of per-guest exports
+// Query: format=txt|csv|json (default: csv)
+// ----------------------------------------------------------------------------
+
+router.get(
+  '/events/:eventId/guests/export-all',
+  adminAuth,
+  requirePermission('events.view'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId } = req.params;
+      const format = ['txt', 'csv', 'json'].includes(req.query.format) ? req.query.format : 'csv';
+
+      const guests = await db('gallery_guests')
+        .where({ event_id: eventId, is_deleted: false })
+        .select('id', 'name', 'email');
+
+      if (guests.length === 0) {
+        return res.status(404).json({ error: 'No guests to export' });
+      }
+
+      res.setHeader('Content-Type', 'application/zip');
+      res.setHeader(
+        'Content-Disposition',
+        `attachment; filename="event-${eventId}-guests.zip"`
+      );
+
+      const archive = archiver('zip', { zlib: { level: 9 } });
+      archive.on('error', (err) => {
+        logger.error('Archive error:', err);
+        res.status(500).end();
+      });
+      archive.pipe(res);
+
+      for (const g of guests) {
+        const selections = await db('photo_feedback')
+          .join('photos', 'photo_feedback.photo_id', 'photos.id')
+          .where('photo_feedback.guest_id', g.id)
+          .whereIn('photo_feedback.feedback_type', ['like', 'favorite'])
+          .select('photos.filename', 'photos.original_filename', 'photo_feedback.feedback_type');
+
+        const safeName = g.name.replace(/[^a-zA-Z0-9_-]/g, '_') || `guest_${g.id}`;
+        const filename = `${safeName}.${format}`;
+
+        let body;
+        if (format === 'json') {
+          body = JSON.stringify({ guest: g, selections }, null, 2);
+        } else if (format === 'csv') {
+          const header = 'filename,original_filename,feedback_type';
+          const rows = selections.map(
+            (s) =>
+              `${escapeCsvCell(s.filename)},${escapeCsvCell(s.original_filename)},${escapeCsvCell(s.feedback_type)}`
+          );
+          body = [header, ...rows].join('\n');
+        } else {
+          // txt — just filenames
+          body = selections.map((s) => s.original_filename || s.filename).join('\n');
+        }
+        archive.append(body, { name: filename });
+      }
+
+      await archive.finalize();
+    } catch (error) {
+      logger.error('Error exporting all guests:', error);
+      if (!res.headersSent) {
+        res.status(500).json({ error: 'Failed to export guests' });
+      }
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// GET /admin/events/:eventId/guests/:guestId — guest detail with selections
+// (Phase 2)
+// ----------------------------------------------------------------------------
+
+router.get(
+  '/events/:eventId/guests/:guestId',
+  adminAuth,
+  requirePermission('events.view'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId, guestId } = req.params;
+      const guest = await loadGuestOr404(eventId, guestId, res);
+      if (!guest) return;
+
+      const feedback = await db('photo_feedback')
+        .join('photos', 'photo_feedback.photo_id', 'photos.id')
+        .where('photo_feedback.guest_id', guestId)
+        .select(
+          'photo_feedback.id as feedback_id',
+          'photo_feedback.feedback_type',
+          'photo_feedback.rating',
+          'photo_feedback.comment_text',
+          'photo_feedback.created_at',
+          'photos.id as photo_id',
+          'photos.filename',
+          'photos.original_filename',
+          'photos.type'
+        )
+        .orderBy('photo_feedback.created_at', 'desc');
+
+      const photoFor = (row) => ({
+        id: row.photo_id,
+        filename: row.filename,
+        original_filename: row.original_filename,
+        type: row.type,
+        url: `/api/admin/photos/${eventId}/photo/${row.photo_id}`,
+        thumbnail_url: `/api/admin/photos/${eventId}/thumbnail/${row.photo_id}`,
+      });
+
+      const selections = {
+        liked: [],
+        favorited: [],
+        rated: [],
+        commented: [],
+      };
+      for (const row of feedback) {
+        if (row.feedback_type === 'like') {
+          selections.liked.push(photoFor(row));
+        } else if (row.feedback_type === 'favorite') {
+          selections.favorited.push(photoFor(row));
+        } else if (row.feedback_type === 'rating') {
+          selections.rated.push({ photo: photoFor(row), rating: row.rating });
+        } else if (row.feedback_type === 'comment') {
+          selections.commented.push({
+            photo: photoFor(row),
+            comment: row.comment_text,
+            created_at: row.created_at,
+          });
+        }
+      }
+
+      res.json({
+        guest: {
+          ...serializeGuest(guest),
+          stats: {
+            likes: selections.liked.length,
+            favorites: selections.favorited.length,
+            comments: selections.commented.length,
+            ratings: selections.rated.length,
+          },
+        },
+        selections,
+      });
+    } catch (error) {
+      logger.error('Error fetching guest detail:', error);
+      res.status(500).json({ error: 'Failed to fetch guest detail' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// GET /admin/events/:eventId/guests/:guestId/export — per-guest export
+// Query: format=txt|csv|json
+// ----------------------------------------------------------------------------
+
+router.get(
+  '/events/:eventId/guests/:guestId/export',
+  adminAuth,
+  requirePermission('events.view'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId, guestId } = req.params;
+      const format = ['txt', 'csv', 'json'].includes(req.query.format) ? req.query.format : 'txt';
+      const guest = await loadGuestOr404(eventId, guestId, res);
+      if (!guest) return;
+
+      const selections = await db('photo_feedback')
+        .join('photos', 'photo_feedback.photo_id', 'photos.id')
+        .where('photo_feedback.guest_id', guestId)
+        .whereIn('photo_feedback.feedback_type', ['like', 'favorite'])
+        .select('photos.filename', 'photos.original_filename', 'photo_feedback.feedback_type');
+
+      const safeName = guest.name.replace(/[^a-zA-Z0-9_-]/g, '_') || `guest_${guest.id}`;
+      const filename = `${safeName}.${format}`;
+
+      if (format === 'json') {
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
+        return res.send(JSON.stringify({ guest: serializeGuest(guest), selections }, null, 2));
+      }
+      if (format === 'csv') {
+        res.setHeader('Content-Type', 'text/csv');
+        res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
+        const header = 'filename,original_filename,feedback_type';
+        const rows = selections.map(
+          (s) =>
+            `${escapeCsvCell(s.filename)},${escapeCsvCell(s.original_filename)},${escapeCsvCell(s.feedback_type)}`
+        );
+        return res.send([header, ...rows].join('\n'));
+      }
+      // txt — one filename per line
+      res.setHeader('Content-Type', 'text/plain');
+      res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
+      return res.send(selections.map((s) => s.original_filename || s.filename).join('\n'));
+    } catch (error) {
+      logger.error('Error exporting guest:', error);
+      res.status(500).json({ error: 'Failed to export guest' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// DELETE /admin/events/:eventId/guests/:guestId — anonymize (soft delete)
+// ----------------------------------------------------------------------------
+
+router.delete(
+  '/events/:eventId/guests/:guestId',
+  adminAuth,
+  requirePermission('events.edit'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId, guestId } = req.params;
+      const guest = await loadGuestOr404(eventId, guestId, res);
+      if (!guest) return;
+
+      const result = await feedbackService.anonymizeGuestFeedback(guestId);
+
+      await db('gallery_guests').where({ id: guestId }).update({
+        is_deleted: true,
+        name: 'Removed',
+        email: null,
+        last_seen_at: db.fn.now(),
+      });
+
+      await logActivity(
+        'guest_deleted',
+        { event_id: eventId, guest_id: guestId, anonymized: result.anonymized },
+        eventId,
+        { type: 'admin', id: req.admin.id, name: req.admin.username }
+      );
+
+      res.json({ success: true, ...result });
+    } catch (error) {
+      logger.error('Error deleting guest:', error);
+      res.status(500).json({ error: 'Failed to delete guest' });
+    }
+  }
+);
+
+// ----------------------------------------------------------------------------
+// POST /admin/events/:eventId/guests/:keepId/merge — merge guests (Phase 3.4)
+// Body: { mergeIds: number[] }
+// ----------------------------------------------------------------------------
+
+router.post(
+  '/events/:eventId/guests/:keepId/merge',
+  adminAuth,
+  requirePermission('events.edit'),
+  requireEventOwnership,
+  async (req, res) => {
+    try {
+      const { eventId, keepId } = req.params;
+      const mergeIds = Array.isArray(req.body?.mergeIds) ? req.body.mergeIds : [];
+
+      if (mergeIds.length === 0) {
+        return res.status(400).json({ error: 'mergeIds is required' });
+      }
+      if (mergeIds.includes(Number(keepId))) {
+        return res.status(400).json({ error: 'Cannot merge a guest into itself' });
+      }
+
+      // Sanity check: all guests belong to this event.
+      const all = await db('gallery_guests')
+        .whereIn('id', [Number(keepId), ...mergeIds.map(Number)])
+        .where({ event_id: eventId });
+      if (all.length !== mergeIds.length + 1) {
+        return res.status(400).json({ error: 'All guests must belong to the same event' });
+      }
+
+      const result = await feedbackService.mergeGuestFeedback(Number(keepId), mergeIds.map(Number));
+
+      // Soft-delete the merged (source) guests.
+      await db('gallery_guests')
+        .whereIn('id', mergeIds.map(Number))
+        .update({ is_deleted: true, last_seen_at: db.fn.now() });
+
+      await logActivity(
+        'guest_merged',
+        { event_id: eventId, keep_id: keepId, merged_ids: mergeIds },
+        eventId,
+        { type: 'admin', id: req.admin.id, name: req.admin.username }
+      );
+
+      res.json({ success: true, ...result });
+    } catch (error) {
+      logger.error('Error merging guests:', error);
+      res.status(500).json({ error: 'Failed to merge guests' });
+    }
+  }
+);
+
+module.exports = router;

backend/src/routes/adminPhotoDimensions.js

@@ -0,0 +1,155 @@
+const express = require('express');
+const router = express.Router();
+const { db } = require('../database/db');
+const { adminAuth } = require('../middleware/auth');
+const { requirePermission } = require('../middleware/permissions');
+const fs = require('fs').promises;
+const logger = require('../utils/logger');
+
+const { resolvePhotoFilePath } = require('../services/photoResolver');
+
+// Module-level progress state
+let repairProgress = {
+  isRunning: false,
+  lastResult: null
+};
+
+// Repair photo dimensions (background job)
+router.post('/repair-dimensions', adminAuth, requirePermission('photos.edit'), async (req, res) => {
+  try {
+    if (repairProgress.isRunning) {
+      return res.status(409).json({ error: 'Repair is already running' });
+    }
+
+    const photos = await db('photos')
+      .join('events', 'photos.event_id', 'events.id')
+      .where(function () {
+        this.whereNull('photos.width').orWhereNull('photos.height');
+      })
+      .where(function () {
+        this.where('photos.media_type', '!=', 'video').orWhereNull('photos.media_type');
+      })
+      .select(
+        'photos.id', 'photos.path', 'photos.filename',
+        'photos.source_origin', 'photos.external_relpath', 'photos.event_id',
+        'events.source_mode', 'events.external_path', 'events.slug'
+      );
+
+    if (photos.length === 0) {
+      return res.json({ message: 'No photos need dimension repair', count: 0 });
+    }
+
+    // Return immediately
+    res.json({
+      message: `Started repairing dimensions for ${photos.length} photos`,
+      count: photos.length
+    });
+
+    // Process in background
+    repairProgress.isRunning = true;
+    repairProgress.lastResult = null;
+
+    setImmediate(async () => {
+      let sharp;
+      try {
+        sharp = require('sharp');
+      } catch (err) {
+        logger.error('Sharp not available for dimension repair:', err.message);
+        repairProgress.isRunning = false;
+        repairProgress.lastResult = { success: 0, failed: 0, error: 'Sharp not available' };
+        return;
+      }
+
+      let successCount = 0;
+      let errorCount = 0;
+
+      for (const photo of photos) {
+        try {
+          const event = { source_mode: photo.source_mode, external_path: photo.external_path, slug: photo.slug };
+          let fullPath;
+          try {
+            fullPath = resolvePhotoFilePath(event, photo);
+          } catch (err) {
+            logger.warn(`Photo ${photo.id} has no resolvable path, skipping dimension repair: ${err.message}`);
+            errorCount++;
+            continue;
+          }
+
+          try {
+            await fs.access(fullPath);
+          } catch (err) {
+            logger.warn(`File not found for photo ${photo.id}: ${fullPath}`);
+            errorCount++;
+            continue;
+          }
+
+          const metadata = await sharp(fullPath).metadata();
+
+          if (metadata.width && metadata.height) {
+            await db('photos')
+              .where({ id: photo.id })
+              .update({
+                width: metadata.width,
+                height: metadata.height
+              });
+            successCount++;
+
+            if (successCount % 50 === 0) {
+              logger.info(`Dimension repair progress: ${successCount} updated...`);
+            }
+          } else {
+            logger.warn(`Could not extract dimensions for photo ${photo.id}`);
+            errorCount++;
+          }
+        } catch (error) {
+          logger.error(`Error repairing dimensions for photo ${photo.id}:`, error);
+          errorCount++;
+        }
+      }
+
+      repairProgress.isRunning = false;
+      repairProgress.lastResult = { success: successCount, failed: errorCount };
+      logger.info(`Dimension repair complete: ${successCount} success, ${errorCount} errors`);
+    });
+  } catch (error) {
+    logger.error('Error starting dimension repair:', error);
+    res.status(500).json({ error: 'Failed to start dimension repair' });
+  }
+});
+
+// Get dimension repair status
+router.get('/repair-dimensions/status', adminAuth, requirePermission('photos.view'), async (req, res) => {
+  try {
+    const totalPhotos = await db('photos')
+      .where(function () {
+        this.where('media_type', '!=', 'video').orWhereNull('media_type');
+      })
+      .count('id as count')
+      .first();
+
+    const withDimensions = await db('photos')
+      .where(function () {
+        this.where('media_type', '!=', 'video').orWhereNull('media_type');
+      })
+      .whereNotNull('width')
+      .whereNotNull('height')
+      .count('id as count')
+      .first();
+
+    const total = Number(totalPhotos.count);
+    const withDims = Number(withDimensions.count);
+
+    res.json({
+      total,
+      withDimensions: withDims,
+      withoutDimensions: total - withDims,
+      isRunning: repairProgress.isRunning,
+      lastResult: repairProgress.lastResult
+    });
+  } catch (error) {
+    logger.error('Error fetching dimension repair status:', error);
+    res.status(500).json({ error: 'Failed to fetch dimension repair status' });
+  }
+});
+
+module.exports = router;

backend/src/routes/adminPhotoExport.js

@@ -71,12 +71,12 @@ router.get('/:eventId/filtered', adminAuth, requirePermission('photos.view'), [
     // Build filtered query
     const filterBuilder = new PhotoFilterBuilder(
       db('photos')
-        .leftJoin('categories', 'photos.category_id', 'categories.id')
+        .leftJoin('photo_categories', 'photos.category_id', 'photo_categories.id')
         .select(
           'photos.id',
           'photos.filename',
           'photos.original_filename',
-          'photos.file_path',
+          'photos.path',
           'photos.average_rating',
           'photos.feedback_count',
           'photos.like_count',
@@ -84,8 +84,8 @@ router.get('/:eventId/filtered', adminAuth, requirePermission('photos.view'), [
           'photos.comment_count',
           'photos.width',
           'photos.height',
-          'photos.created_at',
-          'categories.name as category_name'
+          'photos.uploaded_at',
+          'photo_categories.name as category_name'
         ),
       eventId
     );

backend/src/routes/adminPhotos.js

@@ -5,13 +5,19 @@ const fs = require('fs').promises;
 const { db, logActivity } = require('../database/db');
 const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
-const { generateThumbnail, ensureThumbnail } = require('../services/imageProcessor');
+const { generateThumbnail, ensureThumbnail, extractCaptureDate } = require('../services/imageProcessor');
+const { processUploadedVideo, isVideoMimeType } = require('../services/videoProcessor');
 const { generatePhotoFilename } = require('../utils/filenameSanitizer');
 const { escapeLikePattern } = require('../utils/sqlSecurity');
 const { validateUploadedFiles } = require('../middleware/uploadValidation');
-const { getMaxFilesPerUpload } = require('../services/uploadSettings');
+const { getMaxFilesPerUpload, getAllowedMimeTypes } = require('../services/uploadSettings');
 const { processUploadedPhotos } = require('../services/photoProcessor');
 const chunkedUpload = require('../services/chunkedUploadService');
+const watermarkGeneratorService = require('../services/watermarkGeneratorService');
+const downloadZipService = require('../services/downloadZipService');
+const { findReplacementCandidate, replacePhoto } = require('../services/photoReplacementService');
+const { requireEventOwnership } = require('../middleware/ownership');
+const { getStorage } = require('../services/storage');
 const router = express.Router();
 
 // Get storage path from environment or default
@@ -46,47 +52,55 @@ const storage = multer.diskStorage({
   }
 });
 
-const { validateFileType } = require('../utils/fileSecurityUtils');
+const { validateFileType, createFileUploadValidator } = require('../utils/fileSecurityUtils');
 
+// Create a multer instance that uses dynamically resolved allowed MIME types.
+// The allowed types are fetched from the database once per request (before multer
+// processes files) and attached to req.allowedMimeTypes so that the fileFilter
+// callback can read them synchronously.
 const upload = multer({
   storage: storage,
   limits: {
     fileSize: 10 * 1024 * 1024 * 1024, // 10GB limit per file to support large videos
     files: 2000, // Hard safety ceiling; actual limit enforced dynamically
-    // Set a reasonable field size limit to prevent memory issues
     fieldSize: 10 * 1024 * 1024, // 10MB for non-file fields
-    // Add part size limits to prevent incomplete uploads
-    parts: 10000, // Maximum number of parts (fields + files)
-    headerPairs: 2000 // Maximum number of header key-value pairs
+    parts: 10000,
+    headerPairs: 2000
   },
   fileFilter: (req, file, cb) => {
-    // Accept images and videos with proper validation
-    const allowedMimeTypes = [
-      'image/jpeg', 'image/png', 'image/webp',
-      'video/mp4', 'video/webm', 'video/quicktime', 'video/x-msvideo'
-    ];
+    // req.allowedMimeTypes is populated by the middleware that runs before multer
+    const allowedMimeTypes = req.allowedMimeTypes || ['image/jpeg', 'image/png', 'image/webp'];
 
     if (validateFileType(file.originalname, file.mimetype, allowedMimeTypes)) {
       return cb(null, true);
     } else {
-      cb(new Error('Only JPEG, PNG, WebP images and MP4, WebM, MOV, AVI videos are allowed'));
+      cb(new Error('Invalid file type. Check allowed file types in system settings.'));
     }
   },
-  // Add abort on limit to stop processing when limits are exceeded
   abortOnLimit: true
 });
 
-const { createFileUploadValidator } = require('../utils/fileSecurityUtils');
+// Middleware to resolve allowed MIME types from settings before multer runs
+const resolveAllowedTypes = async (req, res, next) => {
+  try {
+    req.allowedMimeTypes = await getAllowedMimeTypes();
+  } catch (error) {
+    console.error('Failed to resolve allowed MIME types:', error);
+    req.allowedMimeTypes = ['image/jpeg', 'image/png', 'image/webp'];
+  }
+  next();
+};
 
-// Create content validator middleware
-const validateUploadContent = createFileUploadValidator({
-  allowedTypes: [
-    'image/jpeg', 'image/png', 'image/webp',
-    'video/mp4', 'video/webm', 'video/quicktime', 'video/x-msvideo'
-  ],
-  maxFileSize: 10 * 1024 * 1024 * 1024, // 10GB to support large videos
-  validateContent: true
-});
+// Dynamic content validator middleware that reads allowed types from req
+const validateUploadContent = async (req, res, next) => {
+  const allowedTypes = req.allowedMimeTypes || ['image/jpeg', 'image/png', 'image/webp'];
+  const validator = createFileUploadValidator({
+    allowedTypes,
+    maxFileSize: 10 * 1024 * 1024 * 1024, // 10GB to support large videos
+    validateContent: true
+  });
+  return validator(req, res, next);
+};
 
 // Request timeout middleware for uploads
 const uploadTimeout = (timeout = 300000) => { // 5 minutes default
@@ -110,7 +124,7 @@ const uploadTimeout = (timeout = 300000) => { // 5 minutes default
 
 // Upload photos for an event
 // Max file count is configurable via general settings
-router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), uploadTimeout(600000), async (req, res, next) => { // 10 minute timeout
+router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), requireEventOwnership, uploadTimeout(600000), resolveAllowedTypes, async (req, res, next) => { // 10 minute timeout
   let maxFilesPerUpload;
   try {
     maxFilesPerUpload = await getMaxFilesPerUpload();
@@ -138,7 +152,8 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
 }, validateUploadContent, validateUploadedFiles, async (req, res) => {
   try {
     const { eventId } = req.params;
-    const { category_id } = req.body;
+    const { category_id, replace_by_name } = req.body;
+    const replaceByName = replace_by_name === 'true' || replace_by_name === true;
     
     console.log('Upload request received for event:', eventId);
     console.log('Body:', req.body);
@@ -160,7 +175,37 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
       }
       return res.status(404).json({ error: 'Event not found' });
     }
-    
+
+    // Enforce photo cap if set (replacements don't count as new)
+    if (event.photo_cap && event.photo_cap > 0) {
+      const existingPhotoCount = await db('photos')
+        .where({ event_id: eventId })
+        .count('id as count')
+        .first();
+      const currentCount = parseInt(existingPhotoCount.count) || 0;
+      let newFilesCount = (req.files && req.files.length) || 0;
+      // Subtract likely replacements from cap calculation
+      if (replaceByName && req.files) {
+        for (const file of req.files) {
+          const candidate = await findReplacementCandidate(parseInt(eventId), file.originalname);
+          if (candidate && !candidate.ambiguous) newFilesCount--;
+        }
+      }
+      if (currentCount + newFilesCount > event.photo_cap) {
+        // Clean up temp files
+        if (req.tempUploadPath) {
+          try {
+            await fs.rm(req.tempUploadPath, { recursive: true, force: true });
+          } catch (e) {
+            console.error('Failed to clean up temp path:', e);
+          }
+        }
+        return res.status(400).json({
+          error: `Photo cap exceeded. This event allows a maximum of ${event.photo_cap} photos. Currently ${currentCount} photos exist, and you are trying to upload ${newFilesCount} more.`
+        });
+      }
+    }
+
     if (!req.files || req.files.length === 0) {
       console.error('No files in request. req.files:', req.files);
       console.error('Request body keys:', Object.keys(req.body));
@@ -175,8 +220,9 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
       return res.status(400).json({ error: 'No files uploaded' });
     }
     
-    // Parse category_id to number if provided
-    const parsedCategoryId = category_id ? parseInt(category_id, 10) : null;
+    // Parse category_id to number if provided (handle string values like 'individual', 'collage')
+    const rawParsed = category_id ? parseInt(category_id, 10) : NaN;
+    const parsedCategoryId = !isNaN(rawParsed) ? rawParsed : null;
 
     // Determine photo type and category name
     let photoType = 'individual'; // default
@@ -198,18 +244,56 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
       categoryName = 'collages';
     }
     
-    // Create final destination directory
-    const finalDestPath = path.join(getStoragePath(), 'events/active', event.slug);
-    await fs.mkdir(finalDestPath, { recursive: true });
+    // Final destination key prefix under the storage backend (no local mkdir
+    // needed — LocalFsStorage creates the parent dir on put, S3 has no dirs).
+    const finalDestPathRel = path.posix.join('events/active', event.slug);
     
     const uploadedPhotos = [];
+    const replacedPhotos = [];
+    const skippedReplacements = [];
     const errors = [];
-    
-    // Process files in batches to optimize database operations
+
+    // Handle replacements first if enabled
+    let filesToUpload = req.files;
+    if (replaceByName && req.files.length > 0) {
+      const newFiles = [];
+      for (const file of req.files) {
+        const candidate = await findReplacementCandidate(parseInt(eventId), file.originalname);
+        if (candidate && !candidate.ambiguous) {
+          // Replace existing photo
+          const result = await replacePhoto(candidate, file.path, {
+            originalFilename: file.originalname,
+            mimeType: file.mimetype,
+            event,
+          });
+          if (result.success) {
+            replacedPhotos.push({
+              id: result.photo.id,
+              filename: result.photo.filename,
+              original_filename: file.originalname,
+              previous_filename: result.previousFilename,
+            });
+          } else {
+            errors.push({ filename: file.originalname, error: `Replacement failed: ${result.error}` });
+          }
+        } else if (candidate && candidate.ambiguous) {
+          skippedReplacements.push({
+            filename: file.originalname,
+            reason: `${candidate.count} photos share this name — uploaded as new`,
+          });
+          newFiles.push(file);
+        } else {
+          newFiles.push(file);
+        }
+      }
+      filesToUpload = newFiles;
+    }
+
+    // Process remaining new files in batches
     const BATCH_SIZE = 25; // Increased batch size for better performance with large uploads
-    
-    for (let i = 0; i < req.files.length; i += BATCH_SIZE) {
-      const batch = req.files.slice(i, i + BATCH_SIZE);
+
+    for (let i = 0; i < filesToUpload.length; i += BATCH_SIZE) {
+      const batch = filesToUpload.slice(i, i + BATCH_SIZE);
       
       // Start a single transaction for the batch
       const trx = await db.transaction();
@@ -247,28 +331,46 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
               extension
             );
             
-            // Calculate final path
-            const finalPath = path.join(finalDestPath, newFilename);
-            const storagePath = getStoragePath();
-            const relativePath = path.relative(path.join(storagePath, 'events/active'), finalPath);
-            
+            // Storage key: events/active/{slug}/{newFilename}
+            const finalKey = path.posix.join(finalDestPathRel, newFilename);
+            // photo.path is stored relative to events/active so resolvePhotoStorageKey
+            // can rebuild the full key on read.
+            const relativePath = path.posix.join(event.slug, newFilename);
+
+            // Extract capture date from EXIF metadata
+            let capturedAt = null;
+            try {
+              capturedAt = await extractCaptureDate(tempPath);
+            } catch (exifError) {
+              // Non-fatal - just log and continue without capture date
+              console.log(`Could not extract EXIF date for ${file.originalname}`);
+            }
+
+            // Determine media type
+            const isVideo = isVideoMimeType(file.mimetype);
+            const mediaType = isVideo ? 'video' : 'image';
+
             // Prepare photo data for batch insert
             const photoData = {
               event_id: parseInt(eventId),
               filename: newFilename,
+              original_filename: file.originalname, // Preserve original filename for Lightroom export
               path: relativePath,
               thumbnail_path: null, // Will generate after successful commit
               type: photoType,
               category_id: parsedCategoryId, // Save the selected category
-              size_bytes: tempStats.size // Use actual file size from stat
+              size_bytes: tempStats.size, // Use actual file size from stat
+              captured_at: capturedAt, // EXIF capture date (if available)
+              media_type: mediaType,
+              mime_type: file.mimetype
             };
             
             batchPhotos.push(photoData);
             
-            // Store move operation for later
+            // Store upload operation for later (after DB commit)
             fileRenameOperations.push({
               tempPath: tempPath,
-              finalPath: finalPath,
+              finalKey: finalKey,
               filename: newFilename,
               photoData: photoData
             });
@@ -290,36 +392,103 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
           await trx.commit();
           console.log(`Successfully committed batch of ${batchPhotos.length} photos`);
           
-          // Now move files from temp to final location after successful commit
+          // Now upload files from temp into the storage backend after successful commit
+          const storage = getStorage();
           for (let idx = 0; idx < fileRenameOperations.length; idx++) {
             const operation = fileRenameOperations[idx];
             try {
-              // Move the file from temp to final location
-              await fs.rename(operation.tempPath, operation.finalPath);
-              console.log(`Moved file from ${operation.tempPath} to ${operation.finalPath}`);
-              
-              // Verify the file was moved successfully
-              const finalStats = await fs.stat(operation.finalPath);
-              if (finalStats.size !== operation.photoData.size_bytes) {
-                throw new Error(`File size mismatch after move: expected ${operation.photoData.size_bytes}, got ${finalStats.size}`);
-              }
-              
-              // Generate thumbnail with final path
+              // Process source-dependent steps (sharp/ffmpeg) FIRST while the
+              // tmp file is still on local disk, then upload the original and
+              // unlink the tmp.
+              const photoId = insertedIds[idx]?.id || insertedIds[idx];
+              const isVideoFile = isVideoMimeType(operation.photoData.mime_type);
               let thumbnailPath = null;
+
               try {
-                thumbnailPath = await generateThumbnail(operation.finalPath);
-                
-                // Update the database with thumbnail path
-                if (thumbnailPath && insertedIds[idx]) {
-                  const photoId = insertedIds[idx]?.id || insertedIds[idx];
-                  await db('photos')
-                    .where({ id: photoId })
-                    .update({ thumbnail_path: thumbnailPath });
+                if (isVideoFile) {
+                  const videoThumbnailKey = path.posix.join(
+                    'thumbnails',
+                    `thumb_${operation.filename.replace(/\.[^.]+$/, '.jpg')}`
+                  );
+                  const result = await processUploadedVideo(operation.tempPath, videoThumbnailKey);
+                  thumbnailPath = result.thumbnailKey;
+
+                  if (photoId && result.metadata) {
+                    await db('photos')
+                      .where({ id: photoId })
+                      .update({
+                        thumbnail_path: thumbnailPath,
+                        duration: result.metadata.duration,
+                        video_codec: result.metadata.videoCodec,
+                        audio_codec: result.metadata.audioCodec,
+                        width: result.metadata.width,
+                        height: result.metadata.height
+                      });
+                  }
+                } else {
+                  thumbnailPath = await generateThumbnail(operation.tempPath);
+
+                  // Update the database with thumbnail path and image dimensions
+                  if (photoId) {
+                    const updateData = {};
+                    if (thumbnailPath) updateData.thumbnail_path = thumbnailPath;
+
+                    try {
+                      const sharp = require('sharp');
+                      const metadata = await sharp(operation.tempPath).metadata();
+                      if (metadata.width && metadata.height) {
+                        updateData.width = metadata.width;
+                        updateData.height = metadata.height;
+                      }
+                    } catch (metadataError) {
+                      console.warn(`Could not extract image dimensions for ${operation.filename}:`, metadataError.message);
+                    }
+
+                    if (Object.keys(updateData).length > 0) {
+                      await db('photos')
+                        .where({ id: photoId })
+                        .update(updateData);
+                    }
+                  }
                 }
               } catch (thumbError) {
-                console.error(`Thumbnail generation failed for ${operation.filename}:`, thumbError.message);
+                console.error(`Thumbnail/metadata processing failed for ${operation.filename}:`, thumbError.message);
               }
-              
+
+              // Upload the original through the storage backend, then drop the
+              // local tmp file. We do this AFTER thumbnail/metadata processing
+              // so sharp/ffmpeg still have a local source to work from.
+              await storage.putFromFile(operation.finalKey, operation.tempPath, {
+                contentType: operation.photoData.mime_type,
+              });
+              await fs.unlink(operation.tempPath).catch(() => {});
+
+              // Sanity check: round-trip the size we just wrote.
+              const stat = await storage.stat(operation.finalKey);
+              if (!stat || stat.size !== operation.photoData.size_bytes) {
+                throw new Error(`Size mismatch after upload: expected ${operation.photoData.size_bytes}, got ${stat ? stat.size : 'null'}`);
+              }
+
+              // Queue watermark generation in background (non-blocking, images only)
+              if (photoId && !isVideoFile) {
+                watermarkGeneratorService.generateForPhoto(photoId)
+                  .catch(err => console.warn(`Watermark generation queued failed for photo ${photoId}:`, err.message));
+              }
+
+              // Webhook (#327): per-photo upload event.
+              try {
+                const webhookService = require('../services/webhookService');
+                await webhookService.fire('photo.uploaded', {
+                  event: { id: parseInt(eventId, 10), slug: event.slug, event_name: event.event_name },
+                  photo: {
+                    id: insertedIds[idx]?.id || insertedIds[idx],
+                    filename: operation.filename,
+                    original_filename: operation.photoData.original_filename,
+                    size_bytes: operation.photoData.size_bytes,
+                  },
+                });
+              } catch (e) { /* non-fatal */ }
+
               // Add to successful uploads
               uploadedPhotos.push({
                 id: insertedIds[idx]?.id || insertedIds[idx],
@@ -328,10 +497,10 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
                 category_id: operation.photoData.category_id
               });
             } catch (moveError) {
-              console.error(`Failed to move file ${operation.tempPath} to ${operation.finalPath}:`, moveError);
-              errors.push({ 
-                filename: operation.filename, 
-                error: `File move failed: ${moveError.message}` 
+              console.error(`Failed to upload ${operation.tempPath} → ${operation.finalKey}:`, moveError);
+              errors.push({
+                filename: operation.filename,
+                error: `File upload failed: ${moveError.message}`
               });
               
               // Try to clean up the database entry if file move failed
@@ -381,21 +550,36 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
     
     // Log activity
     await logActivity('photos_uploaded',
-      { count: uploadedPhotos.length, eventName: event.event_name },
+      { count: uploadedPhotos.length, replacedCount: replacedPhotos.length, eventName: event.event_name },
       eventId,
       { type: 'admin', id: req.admin.id, name: req.admin.username }
     );
-    
+
+    // Log individual replacements for audit trail
+    for (const rp of replacedPhotos) {
+      await logActivity('photo_replaced',
+        { photoId: rp.id, originalFilename: rp.original_filename, previousFilename: rp.previous_filename, eventName: event.event_name },
+        eventId,
+        { type: 'admin', id: req.admin.id, name: req.admin.username }
+      );
+    }
+
     // Include any files that were invalid from the validation middleware
     const totalInvalidFiles = (req.invalidFiles || []).concat(errors);
-    
+
     // Prepare response
     const totalAttempted = req.files.length + (req.invalidFiles ? req.invalidFiles.length : 0);
+    const uploadMsg = uploadedPhotos.length > 0 ? `${uploadedPhotos.length} uploaded` : '';
+    const replaceMsg = replacedPhotos.length > 0 ? `${replacedPhotos.length} replaced` : '';
+    const parts = [uploadMsg, replaceMsg].filter(Boolean).join(', ');
     const response = {
-      message: `Successfully uploaded ${uploadedPhotos.length} photos`,
+      message: parts ? `Successfully ${parts}` : 'No photos processed',
       photos: uploadedPhotos,
+      replaced: replacedPhotos,
+      replacedCount: replacedPhotos.length,
+      skippedReplacements,
       totalFiles: totalAttempted,
-      successCount: uploadedPhotos.length,
+      successCount: uploadedPhotos.length + replacedPhotos.length,
       failureCount: totalInvalidFiles.length
     };
     
@@ -405,10 +589,15 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
       response.message = `Uploaded ${uploadedPhotos.length} of ${totalAttempted} photos. ${totalInvalidFiles.length} failed.`;
     }
     
+    // Invalidate download zip cache after successful upload or replacement
+    if (uploadedPhotos.length > 0 || replacedPhotos.length > 0) {
+      downloadZipService.invalidate(parseInt(eventId));
+    }
+
     res.json(response);
   } catch (error) {
     console.error('Error uploading photos:', error);
-    
+
     // Clean up temp upload directory on error
     if (req.tempUploadPath) {
       try {
@@ -424,7 +613,7 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), u
 });
 
 // Delete a photo
-router.delete('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.delete'), async (req, res) => {
+router.delete('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.delete'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId, photoId } = req.params;
     
@@ -437,42 +626,56 @@ router.delete('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.
       return res.status(404).json({ error: 'Photo not found' });
     }
     
-    // Delete physical files
-    const storagePath = getStoragePath();
-    const photoPath = path.join(storagePath, 'events/active', photo.path);
-    
+    // Delete original + thumbnail through the storage backend.
+    const storage = getStorage();
+    const { resolvePhotoStorageKey } = require('../services/photoResolver');
+    const event = await db('events').where({ id: eventId }).first();
+
     try {
-      await fs.unlink(photoPath);
+      const originalKey = resolvePhotoStorageKey(event, photo);
+      if (originalKey) await storage.delete(originalKey);
     } catch (error) {
       console.error('Error deleting photo file:', error);
     }
-    
-    // Delete thumbnail if exists
+
+    // photo.thumbnail_path is stored as the canonical storage key
+    // (e.g. "thumbnails/thumb_foo.jpg"), so pass it through verbatim.
     if (photo.thumbnail_path) {
-      const thumbPath = path.join(storagePath, 'events/active', photo.thumbnail_path);
       try {
-        // Check if file exists before attempting to delete
-        await fs.access(thumbPath);
-        await fs.unlink(thumbPath);
+        await storage.delete(photo.thumbnail_path);
       } catch (error) {
-        // Only log if it's not a "file not found" error
-        if (error.code !== 'ENOENT') {
-          console.error('Error deleting thumbnail:', error);
-        }
+        console.error('Error deleting thumbnail:', error);
       }
     }
-    
+    if (photo.hero_path) {
+      await storage.delete(photo.hero_path).catch(() => {});
+    }
+
+    // Delete pre-generated watermark if exists
+    if (photo.watermark_path) {
+      await watermarkGeneratorService.deleteForPhoto(photo.id);
+    }
+
     // Remove from database
     await db('photos').where({ id: photoId }).delete();
-    
-    // Log activity
-    const event = await db('events').where({ id: eventId }).first();
+
+    // Log activity (event was fetched above for storage key resolution)
     await logActivity('photo_deleted',
       { filename: photo.filename, eventName: event.event_name },
       eventId,
       { type: 'admin', id: req.admin.id, name: req.admin.username }
     );
-    
+
+    // Webhook (#327): single-photo delete.
+    try {
+      const webhookService = require('../services/webhookService');
+      await webhookService.fire('photo.deleted', {
+        event: { id: parseInt(eventId, 10), slug: event?.slug, event_name: event?.event_name },
+        photo: { id: parseInt(photoId, 10), filename: photo.filename },
+      });
+    } catch (e) { /* non-fatal */ }
+
+    downloadZipService.invalidate(parseInt(eventId));
     res.json({ message: 'Photo deleted successfully' });
   } catch (error) {
     console.error('Error deleting photo:', error);
@@ -481,10 +684,10 @@ router.delete('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.
 });
 
 // Update a photo (e.g., change category)
-router.patch('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.edit'), async (req, res) => {
+router.patch('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.edit'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId, photoId } = req.params;
-    const { category_id } = req.body;
+    const { category_id, visibility } = req.body;
 
     // Verify photo belongs to event
     const photo = await db('photos')
@@ -498,6 +701,13 @@ router.patch('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.e
     // Prepare update data
     const updateData = {};
 
+    // Handle visibility update (#172)
+    if (visibility !== undefined) {
+      if (['visible', 'hidden'].includes(visibility)) {
+        updateData.visibility = visibility;
+      }
+    }
+
     // Handle type-based categories ('individual' or 'collage')
     // These are string values that map to the photo.type field
     if (category_id === 'individual' || category_id === 'collage') {
@@ -537,7 +747,7 @@ router.patch('/:eventId/photos/:photoId', adminAuth, requirePermission('photos.e
 });
 
 // Bulk delete photos
-router.post('/:eventId/photos/bulk-delete', adminAuth, requirePermission('photos.delete'), async (req, res) => {
+router.post('/:eventId/photos/bulk-delete', adminAuth, requirePermission('photos.delete'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId } = req.params;
     const { photoIds } = req.body;
@@ -555,41 +765,47 @@ router.post('/:eventId/photos/bulk-delete', adminAuth, requirePermission('photos
       return res.status(404).json({ error: 'No photos found' });
     }
     
-    // Delete physical files
-    const storagePath = getStoragePath();
+    // Delete original + thumbnail + hero through the storage backend.
+    const storage = getStorage();
     const event = await db('events').where({ id: eventId }).first();
-    
+    const { resolvePhotoStorageKey } = require('../services/photoResolver');
+
     for (const photo of photos) {
-      // Delete photo file
-      const photoPath = path.join(storagePath, 'events/active', photo.path);
       try {
-        await fs.unlink(photoPath);
+        const originalKey = resolvePhotoStorageKey(event, photo);
+        if (originalKey) await storage.delete(originalKey);
       } catch (error) {
         console.error('Error deleting photo file:', error);
       }
-      
-      // Delete thumbnail
+
       if (photo.thumbnail_path) {
-        const thumbPath = path.join(storagePath, photo.thumbnail_path);
-        try {
-          // Check if file exists before attempting to delete
-          await fs.access(thumbPath);
-          await fs.unlink(thumbPath);
-        } catch (error) {
-          // Only log if it's not a "file not found" error
-          if (error.code !== 'ENOENT') {
-            console.error('Error deleting thumbnail:', error);
-          }
-        }
+        await storage.delete(photo.thumbnail_path).catch(() => {});
+      }
+      if (photo.hero_path) {
+        await storage.delete(photo.hero_path).catch(() => {});
+      }
+      if (photo.watermark_path) {
+        await watermarkGeneratorService.deleteForPhoto(photo.id);
       }
     }
-    
+
     // Delete from database
     await db('photos')
       .whereIn('id', photoIds)
       .where('event_id', eventId)
       .delete();
-    
+
+    // Webhook (#327): one photo.deleted per row in the bulk batch.
+    try {
+      const webhookService = require('../services/webhookService');
+      for (const photo of photos) {
+        await webhookService.fire('photo.deleted', {
+          event: { id: parseInt(eventId, 10), slug: event?.slug, event_name: event?.event_name },
+          photo: { id: photo.id, filename: photo.filename },
+        });
+      }
+    } catch (e) { /* non-fatal */ }
+
     // Log activity
     await logActivity('photos_bulk_deleted',
       { count: photos.length, eventName: event.event_name },
@@ -597,6 +813,7 @@ router.post('/:eventId/photos/bulk-delete', adminAuth, requirePermission('photos
       { type: 'admin', id: req.admin.id, name: req.admin.username }
     );
     
+    downloadZipService.invalidate(parseInt(eventId));
     res.json({ message: `${photos.length} photos deleted successfully` });
   } catch (error) {
     console.error('Error bulk deleting photos:', error);
@@ -605,7 +822,7 @@ router.post('/:eventId/photos/bulk-delete', adminAuth, requirePermission('photos
 });
 
 // Bulk update photos
-router.post('/:eventId/photos/bulk-update', adminAuth, requirePermission('photos.edit'), async (req, res) => {
+router.post('/:eventId/photos/bulk-update', adminAuth, requirePermission('photos.edit'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId } = req.params;
     const { photoIds, updates } = req.body;
@@ -626,9 +843,14 @@ router.post('/:eventId/photos/bulk-update', adminAuth, requirePermission('photos
     }
     
     // Prepare update data
-    const updateData = {
-      updated_at: new Date()
-    };
+    const updateData = {};
+
+    // Handle visibility update (#172)
+    if (updates.visibility !== undefined) {
+      if (['visible', 'hidden'].includes(updates.visibility)) {
+        updateData.visibility = updates.visibility;
+      }
+    }
 
     if (updates.category_id !== undefined) {
       // Handle type-based categories ('individual' or 'collage')
@@ -663,7 +885,7 @@ router.post('/:eventId/photos/bulk-update', adminAuth, requirePermission('photos
 });
 
 // Download a photo
-router.get('/:eventId/photos/:photoId/download', adminAuth, requirePermission('photos.download'), async (req, res) => {
+router.get('/:eventId/photos/:photoId/download', adminAuth, requirePermission('photos.download'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId, photoId } = req.params;
     
@@ -675,18 +897,33 @@ router.get('/:eventId/photos/:photoId/download', adminAuth, requirePermission('p
       return res.status(404).json({ error: 'Photo not found' });
     }
     
-    const { resolvePhotoFilePath } = require('../services/photoResolver');
+    const { resolvePhotoFilePath, resolvePhotoStorageKey } = require('../services/photoResolver');
     const event = await db('events').where('id', eventId).first();
+    const storage = getStorage();
+    const storageKey = resolvePhotoStorageKey(event, photo);
+
+    if (storageKey) {
+      const stat = await storage.stat(storageKey);
+      if (!stat) {
+        return res.status(404).json({ error: 'Photo file not found' });
+      }
+      res.set({
+        'Content-Type': photo.mime_type || 'application/octet-stream',
+        'Content-Length': stat.size,
+        'Content-Disposition': `attachment; filename="${photo.filename}"`,
+      });
+      const stream = await storage.get(storageKey);
+      stream.pipe(res);
+      return;
+    }
+
+    // External-mode photos still live on local disk.
     const filePath = resolvePhotoFilePath(event, photo);
-    
-    // Check if file exists
     try {
       await fs.access(filePath);
     } catch (error) {
       return res.status(404).json({ error: 'Photo file not found' });
     }
-    
-    // Send file
     res.download(filePath, photo.filename);
   } catch (error) {
     console.error('Error downloading photo:', error);
@@ -695,37 +932,81 @@ router.get('/:eventId/photos/:photoId/download', adminAuth, requirePermission('p
 });
 
 // Get all photos for an event
-router.get('/:eventId/photos', adminAuth, requirePermission('photos.view'), async (req, res) => {
+router.get('/:eventId/photos', adminAuth, requirePermission('photos.view'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId } = req.params;
-    const { category_id, type, search, sort = 'date', order = 'desc' } = req.query;
-    
+    const { category_id, type, search, sort = 'date', has_likes, has_favorites, has_comments, min_rating } = req.query;
+    const order = ['asc', 'desc'].includes(req.query.order) ? req.query.order : 'desc';
+    const logic = req.query.logic === 'OR' ? 'OR' : 'AND';
+
     let query = db('photos')
       .where({ 'photos.event_id': eventId })
       .leftJoin('photo_categories', 'photos.category_id', 'photo_categories.id')
       .select('photos.*', 'photo_categories.name as pc_name', 'photo_categories.slug as pc_slug');
-    
-    // Filter by type (individual/collage) - category_id maps to type
-    if (category_id !== undefined) {
-      if (category_id === '' || category_id === '0') {
-        // For backwards compatibility, empty category means no filter
-        // Don't filter anything
-      } else if (category_id === 'individual' || category_id === 'collage') {
+
+    // Filter by category_id
+    if (category_id !== undefined && category_id !== '' && category_id !== '0') {
+      if (category_id === 'individual' || category_id === 'collage') {
+        // Legacy type-based filtering
         query = query.where({ 'photos.type': category_id });
+      } else if (category_id === 'uncategorized') {
+        // Filter for photos with no category assigned
+        query = query.whereNull('photos.category_id');
+      } else {
+        // Numeric category ID from photo_categories table
+        const numericCategoryId = parseInt(category_id, 10);
+        if (!isNaN(numericCategoryId)) {
+          query = query.where({ 'photos.category_id': numericCategoryId });
+        }
       }
     }
-    
+
     // Keep type filter for backwards compatibility
     if (type) {
       query = query.where({ 'photos.type': type });
     }
-    
+
     // Search by filename
     if (search) {
       const escapedSearch = escapeLikePattern(search);
       query = query.where('photos.filename', 'like', `%${escapedSearch}%`);
     }
-    
+
+    // Feedback filters (has likes / favorites / comments / min rating) with AND/OR logic
+    const feedbackConditions = [];
+    if (has_likes === 'true' || has_likes === true) {
+      feedbackConditions.push(qb => qb.where('photos.like_count', '>', 0));
+    }
+    if (has_favorites === 'true' || has_favorites === true) {
+      feedbackConditions.push(qb => qb.where('photos.favorite_count', '>', 0));
+    }
+    if (has_comments === 'true' || has_comments === true) {
+      feedbackConditions.push(qb => qb.where('photos.comment_count', '>', 0));
+    }
+    if (min_rating !== undefined && min_rating !== null && min_rating !== '') {
+      const minRatingNum = parseFloat(min_rating);
+      if (!isNaN(minRatingNum)) {
+        feedbackConditions.push(qb => qb.where('photos.average_rating', '>=', minRatingNum));
+      }
+    }
+    if (feedbackConditions.length > 0) {
+      if (logic === 'OR') {
+        query = query.where(builder => {
+          feedbackConditions.forEach((cond, idx) => {
+            if (idx === 0) {
+              cond(builder);
+            } else {
+              builder.orWhere(sub => cond(sub));
+            }
+          });
+        });
+      } else {
+        feedbackConditions.forEach(cond => {
+          query = query.where(builder => cond(builder));
+        });
+      }
+    }
+
     // Sorting
     let orderByColumn = 'photos.uploaded_at';
     if (sort === 'name') {
@@ -755,6 +1036,7 @@ router.get('/:eventId/photos', adminAuth, requirePermission('photos.view'), asyn
       photos: photos.map(photo => ({
         id: photo.id,
         filename: photo.filename,
+        original_filename: photo.original_filename || null,
         // Use the correct admin photos router base for serving images
         url: `/admin/photos/${eventId}/photo/${photo.id}`,
         // Always expose a thumbnail URL; backend will generate on demand if missing
@@ -763,6 +1045,11 @@ router.get('/:eventId/photos', adminAuth, requirePermission('photos.view'), asyn
         category_id: photo.category_id || photo.type,
         category_name: photo.pc_name || (photo.type === 'individual' ? 'Individual Photos' : 'Collages'),
         category_slug: photo.pc_slug || photo.type,
+        media_type: photo.media_type || 'image',
+        mime_type: photo.mime_type || null,
+        width: photo.width || null,
+        height: photo.height || null,
+        duration: photo.duration || null,
         size: photo.size_bytes,
         uploaded_at: photo.uploaded_at,
         // Feedback data
@@ -780,7 +1067,7 @@ router.get('/:eventId/photos', adminAuth, requirePermission('photos.view'), asyn
 });
 
 // Serve photo with admin authentication
-router.get('/:eventId/photo/:photoId', adminAuth, requirePermission('photos.view'), async (req, res) => {
+router.get('/:eventId/photo/:photoId', adminAuth, requirePermission('photos.view'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId, photoId } = req.params;
     
@@ -792,23 +1079,33 @@ router.get('/:eventId/photo/:photoId', adminAuth, requirePermission('photos.view
       return res.status(404).json({ error: 'Photo not found' });
     }
     
-    const { resolvePhotoFilePath } = require('../services/photoResolver');
+    const { resolvePhotoFilePath, resolvePhotoStorageKey } = require('../services/photoResolver');
     const event = await db('events').where('id', eventId).first();
+    const storageKey = resolvePhotoStorageKey(event, photo);
+
+    res.setHeader('Content-Type', `image/${path.extname(photo.filename).slice(1)}`);
+    res.setHeader('Cache-Control', 'private, max-age=3600');
+    res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+
+    if (storageKey) {
+      const storage = getStorage();
+      const stat = await storage.stat(storageKey);
+      if (!stat) {
+        return res.status(404).json({ error: 'Photo file not found' });
+      }
+      res.setHeader('Content-Length', stat.size);
+      const stream = await storage.get(storageKey);
+      stream.pipe(res);
+      return;
+    }
+
+    // External-mode photos still live on local disk.
     const filePath = resolvePhotoFilePath(event, photo);
-    
-    // Check if file exists
     try {
       await fs.access(filePath);
     } catch (error) {
       return res.status(404).json({ error: 'Photo file not found' });
     }
-    
-    // Set appropriate headers
-    res.setHeader('Content-Type', `image/${path.extname(photo.filename).slice(1)}`);
-    res.setHeader('Cache-Control', 'private, max-age=3600');
-    res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
-    
-    // Send file (sendFile requires absolute path)
     res.sendFile(path.resolve(filePath));
   } catch (error) {
     console.error('Error serving photo:', error);
@@ -817,7 +1114,7 @@ router.get('/:eventId/photo/:photoId', adminAuth, requirePermission('photos.view
 });
 
 // Serve thumbnail with admin authentication
-router.get('/:eventId/thumbnail/:photoId', adminAuth, requirePermission('photos.view'), async (req, res) => {
+router.get('/:eventId/thumbnail/:photoId', adminAuth, requirePermission('photos.view'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId, photoId } = req.params;
     
@@ -832,22 +1129,24 @@ router.get('/:eventId/thumbnail/:photoId', adminAuth, requirePermission('photos.
     
     // Ensure thumbnail exists and is valid, regenerate if needed
     const thumbnailPath = await ensureThumbnail(photo);
-    
+
     if (!thumbnailPath) {
       console.error(`Failed to generate thumbnail for photo ${photoId}`);
       return res.status(404).json({ error: 'Thumbnail generation failed' });
     }
-    
-    const storagePath = getStoragePath();
-    const filePath = path.join(storagePath, thumbnailPath);
-    
-    // Set appropriate headers
+
     res.setHeader('Content-Type', 'image/jpeg'); // Thumbnails are always JPEG
     res.setHeader('Cache-Control', 'private, max-age=3600');
     res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
-    
-    // Send file (sendFile requires absolute path)
-    res.sendFile(path.resolve(filePath));
+
+    const storage = getStorage();
+    const stat = await storage.stat(thumbnailPath);
+    if (!stat) {
+      return res.status(404).json({ error: 'Thumbnail not found' });
+    }
+    res.setHeader('Content-Length', stat.size);
+    const stream = await storage.get(thumbnailPath);
+    stream.pipe(res);
   } catch (error) {
     console.error('Error serving thumbnail:', error);
     console.error('Photo ID:', req.params.photoId);
@@ -857,7 +1156,7 @@ router.get('/:eventId/thumbnail/:photoId', adminAuth, requirePermission('photos.
 });
 
 // Debug endpoint to check photo existence
-router.get('/:eventId/debug', adminAuth, requirePermission('photos.view'), async (req, res) => {
+router.get('/:eventId/debug', adminAuth, requirePermission('photos.view'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId } = req.params;
     
@@ -883,7 +1182,7 @@ router.get('/:eventId/debug', adminAuth, requirePermission('photos.view'), async
 // ============================================
 
 // Initialize a chunked upload
-router.post('/:eventId/chunked-upload/init', adminAuth, requirePermission('photos.upload'), async (req, res) => {
+router.post('/:eventId/chunked-upload/init', adminAuth, requirePermission('photos.upload'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId } = req.params;
     const { filename, fileSize, mimeType, totalChunks } = req.body;
@@ -921,7 +1220,7 @@ router.post('/:eventId/chunked-upload/init', adminAuth, requirePermission('photo
 });
 
 // Upload a chunk
-router.post('/:eventId/chunked-upload/:uploadId/chunk/:chunkIndex', adminAuth, requirePermission('photos.upload'), async (req, res) => {
+router.post('/:eventId/chunked-upload/:uploadId/chunk/:chunkIndex', adminAuth, requirePermission('photos.upload'), requireEventOwnership, async (req, res) => {
   try {
     const { uploadId, chunkIndex } = req.params;
 
@@ -942,7 +1241,7 @@ router.post('/:eventId/chunked-upload/:uploadId/chunk/:chunkIndex', adminAuth, r
 });
 
 // Complete chunked upload and process the file
-router.post('/:eventId/chunked-upload/:uploadId/complete', adminAuth, requirePermission('photos.upload'), async (req, res) => {
+router.post('/:eventId/chunked-upload/:uploadId/complete', adminAuth, requirePermission('photos.upload'), requireEventOwnership, async (req, res) => {
   try {
     const { eventId, uploadId } = req.params;
     const { category_id } = req.body;
@@ -984,7 +1283,7 @@ router.post('/:eventId/chunked-upload/:uploadId/complete', adminAuth, requirePer
 });
 
 // Get upload status
-router.get('/:eventId/chunked-upload/:uploadId/status', adminAuth, requirePermission('photos.view'), async (req, res) => {
+router.get('/:eventId/chunked-upload/:uploadId/status', adminAuth, requirePermission('photos.view'), requireEventOwnership, async (req, res) => {
   try {
     const { uploadId } = req.params;
 
@@ -1002,7 +1301,7 @@ router.get('/:eventId/chunked-upload/:uploadId/status', adminAuth, requirePermis
 });
 
 // Abort chunked upload
-router.delete('/:eventId/chunked-upload/:uploadId', adminAuth, requirePermission('photos.delete'), async (req, res) => {
+router.delete('/:eventId/chunked-upload/:uploadId', adminAuth, requirePermission('photos.delete'), requireEventOwnership, async (req, res) => {
   try {
     const { uploadId } = req.params;
 

backend/src/routes/adminSettings.js

@@ -23,6 +23,8 @@ const { clearShareLinkSettingsCache } = require('../services/shareLinkService');
 const { resetSecurityConfigCache } = require('../utils/authSecurity');
 const router = express.Router();
 const { clearMaxFilesPerUploadCache, MAX_ALLOWED_FILES_PER_UPLOAD } = require('../services/uploadSettings');
+const watermarkService = require('../services/watermarkService');
+const watermarkGeneratorService = require('../services/watermarkGeneratorService');
 
 const getStoragePath = () => process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
 
@@ -100,19 +102,31 @@ router.get('/', adminAuth, requirePermission('settings.view'), async (req, res)
     // Convert to object format
     const settingsObject = {};
     settings.forEach(setting => {
-      if (setting.setting_value) {
-        try {
-          // Try to parse as JSON first
-          settingsObject[setting.setting_key] = JSON.parse(setting.setting_value);
-        } catch (e) {
-          // If it's not valid JSON, use the raw value
+      // Check for null/undefined explicitly to handle boolean false and 0 values
+      // PostgreSQL json column returns parsed values (false as boolean, not string)
+      if (setting.setting_value !== null && setting.setting_value !== undefined) {
+        // If the value is already parsed (from json column), use it directly
+        if (typeof setting.setting_value !== 'string') {
           settingsObject[setting.setting_key] = setting.setting_value;
+        } else {
+          try {
+            // Try to parse as JSON first
+            settingsObject[setting.setting_key] = JSON.parse(setting.setting_value);
+          } catch (e) {
+            // If it's not valid JSON, use the raw value
+            settingsObject[setting.setting_key] = setting.setting_value;
+          }
         }
       } else {
         settingsObject[setting.setting_key] = null;
       }
     });
 
+    // Mask sensitive secrets before sending to client
+    if (settingsObject.security_recaptcha_secret_key) {
+      settingsObject.security_recaptcha_secret_key = '••••••••';
+    }
+
     res.json(settingsObject);
   } catch (error) {
     console.error('Settings fetch error:', error);
@@ -127,23 +141,35 @@ router.get('/:type', adminAuth, requirePermission('settings.view'), async (req,
     const settings = await db('app_settings')
       .where('setting_type', type)
       .select('*');
-    
+
     // Convert to object format
     const settingsObject = {};
     settings.forEach(setting => {
-      if (setting.setting_value) {
-        try {
-          // Try to parse as JSON first
-          settingsObject[setting.setting_key] = JSON.parse(setting.setting_value);
-        } catch (e) {
-          // If it's not valid JSON, use the raw value
+      // Check for null/undefined explicitly to handle boolean false and 0 values
+      // PostgreSQL json column returns parsed values (false as boolean, not string)
+      if (setting.setting_value !== null && setting.setting_value !== undefined) {
+        // If the value is already parsed (from json column), use it directly
+        if (typeof setting.setting_value !== 'string') {
           settingsObject[setting.setting_key] = setting.setting_value;
+        } else {
+          try {
+            // Try to parse as JSON first
+            settingsObject[setting.setting_key] = JSON.parse(setting.setting_value);
+          } catch (e) {
+            // If it's not valid JSON, use the raw value
+            settingsObject[setting.setting_key] = setting.setting_value;
+          }
         }
       } else {
         settingsObject[setting.setting_key] = null;
       }
     });
 
+    // Mask sensitive secrets before sending to client
+    if (settingsObject.security_recaptcha_secret_key) {
+      settingsObject.security_recaptcha_secret_key = '••••••••';
+    }
+
     res.json(settingsObject);
   } catch (error) {
     console.error('Settings fetch error:', error);
@@ -196,6 +222,9 @@ router.put('/branding', adminAuth, requirePermission('settings.edit'), async (re
       hide_powered_by
     } = req.body;
 
+    // Get current watermark settings hash for change detection
+    const oldSettingsHash = await watermarkService.getSettingsHash();
+
     const brandingSettings = {
       company_name,
       company_tagline,
@@ -306,7 +335,40 @@ router.put('/branding', adminAuth, requirePermission('settings.edit'), async (re
 
     clearPublicSiteCache();
 
-    res.json({ message: 'Branding settings updated successfully' });
+    // Check if watermark settings changed and trigger regeneration
+    const newSettingsHash = await watermarkService.getSettingsHash();
+    let watermarkRegenerationStarted = false;
+
+    if (oldSettingsHash !== newSettingsHash) {
+      // Clear watermark cache
+      watermarkService.clearCache();
+
+      // Check if watermarking is now enabled or settings changed
+      const currentSettings = await watermarkService.getWatermarkSettings();
+
+      if (currentSettings && currentSettings.enabled) {
+        // Start background regeneration of all watermarks
+        console.log('Watermark settings changed, starting background regeneration');
+        watermarkGeneratorService.regenerateAll()
+          .then(result => {
+            console.log(`Watermark regeneration completed: ${result.success}/${result.total} successful`);
+          })
+          .catch(err => {
+            console.error('Watermark regeneration failed:', err);
+          });
+        watermarkRegenerationStarted = true;
+      } else {
+        // Watermarking was disabled, clear all pre-generated watermarks
+        console.log('Watermarking disabled, clearing pre-generated watermarks');
+        watermarkGeneratorService.clearAllWatermarks()
+          .catch(err => console.error('Failed to clear watermarks:', err));
+      }
+    }
+
+    res.json({
+      message: 'Branding settings updated successfully',
+      watermarkRegenerationStarted
+    });
   } catch (error) {
     console.error('Branding update error:', error);
     res.status(500).json({ error: 'Failed to update branding settings' });
@@ -441,9 +503,27 @@ router.post('/branding/watermark-logo', adminAuth, requirePermission('settings.e
         updated_at: new Date()
       });
 
-    res.json({ 
+    // Trigger watermark regeneration since the logo changed
+    watermarkService.clearCache();
+    const currentSettings = await watermarkService.getWatermarkSettings();
+    let watermarkRegenerationStarted = false;
+
+    if (currentSettings && currentSettings.enabled) {
+      console.log('Watermark logo changed, starting background regeneration');
+      watermarkGeneratorService.regenerateAll()
+        .then(result => {
+          console.log(`Watermark regeneration completed: ${result.success}/${result.total} successful`);
+        })
+        .catch(err => {
+          console.error('Watermark regeneration failed:', err);
+        });
+      watermarkRegenerationStarted = true;
+    }
+
+    res.json({
       message: 'Watermark logo uploaded successfully',
-      watermarkLogoUrl: publicPath
+      watermarkLogoUrl: publicPath,
+      watermarkRegenerationStarted
     });
   } catch (error) {
     console.error('Watermark logo upload error:', error);
@@ -663,6 +743,70 @@ router.put('/analytics', adminAuth, requirePermission('settings.edit'), async (r
   }
 });
 
+// Update SEO settings
+router.put('/seo', adminAuth, requirePermission('settings.edit'), async (req, res) => {
+  try {
+    const settings = req.body;
+
+    // Validate seo_blocked_ai_agents is an array of strings
+    if (settings.seo_blocked_ai_agents !== undefined) {
+      if (!Array.isArray(settings.seo_blocked_ai_agents) ||
+          !settings.seo_blocked_ai_agents.every(a => typeof a === 'string')) {
+        return res.status(400).json({ error: 'seo_blocked_ai_agents must be an array of strings' });
+      }
+    }
+
+    // Validate seo_custom_rules structure
+    if (settings.seo_custom_rules !== undefined) {
+      if (!Array.isArray(settings.seo_custom_rules)) {
+        return res.status(400).json({ error: 'seo_custom_rules must be an array' });
+      }
+      for (const rule of settings.seo_custom_rules) {
+        if (!rule.userAgent || typeof rule.userAgent !== 'string') {
+          return res.status(400).json({ error: 'Each custom rule must have a userAgent string' });
+        }
+        if (!Array.isArray(rule.disallow) || !rule.disallow.every(d => typeof d === 'string')) {
+          return res.status(400).json({ error: 'Each custom rule must have a disallow array of strings' });
+        }
+      }
+    }
+
+    // Update or insert each setting
+    for (const [key, value] of Object.entries(settings)) {
+      await db('app_settings')
+        .insert({
+          setting_key: key,
+          setting_value: JSON.stringify(value),
+          setting_type: 'seo',
+          updated_at: new Date()
+        })
+        .onConflict('setting_key')
+        .merge({
+          setting_value: JSON.stringify(value),
+          updated_at: new Date()
+        });
+    }
+
+    // Clear robots.txt cache
+    const { clearRobotsTxtCache } = require('../services/robotsTxtService');
+    clearRobotsTxtCache();
+
+    // Log activity
+    await db('activity_logs').insert({
+      activity_type: 'seo_settings_updated',
+      actor_type: 'admin',
+      actor_id: req.admin.id,
+      actor_name: req.admin.username,
+      metadata: JSON.stringify({ settings_count: Object.keys(settings).length })
+    });
+
+    res.json({ message: 'SEO settings updated successfully' });
+  } catch (error) {
+    console.error('SEO settings update error:', error);
+    res.status(500).json({ error: 'Failed to update SEO settings' });
+  }
+});
+
 // Get storage info
 router.get('/storage/info', adminAuth, requirePermission('settings.view'), async (req, res) => {
   try {

backend/src/routes/adminSystem.js

@@ -8,6 +8,12 @@ const os = require('os');
 const { formatBoolean } = require('../utils/dbCompat');
 const logger = require('../utils/logger');
 const { checkForUpdates, getCurrentChannel } = require('../services/updateCheckService');
+const { detectEnvironment, generateUpdateInstructions } = require('../services/environmentService');
+const {
+  checkAndNotifyUpdates,
+  sendUpdateNotificationNow,
+  getUpdateNotificationSettings
+} = require('../services/updateNotificationService');
 const router = express.Router();
 
 // Get system version
@@ -65,6 +71,47 @@ router.get('/updates', adminAuth, requirePermission('settings.view'), async (req
   }
 });
 
+// Get update instructions for current environment
+router.get('/updates/instructions', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
+    // Check if update checking is enabled
+    const updateCheckEnabled = process.env.UPDATE_CHECK_ENABLED !== 'false';
+
+    if (!updateCheckEnabled) {
+      return res.json({
+        enabled: false,
+        message: 'Update checking is disabled'
+      });
+    }
+
+    const env = await detectEnvironment();
+    const updateInfo = await checkForUpdates();
+
+    if (!updateInfo.updateAvailable) {
+      return res.json({
+        updateAvailable: false,
+        currentVersion: updateInfo.current,
+        message: 'You are running the latest version'
+      });
+    }
+
+    const instructions = generateUpdateInstructions(env, updateInfo.latest.forChannel);
+
+    res.json({
+      updateAvailable: true,
+      currentVersion: updateInfo.current,
+      targetVersion: updateInfo.latest.forChannel,
+      channel: updateInfo.channel,
+      environment: env,
+      instructions,
+      releaseNotesUrl: `https://github.com/the-luap/picpeak/releases/tag/v${updateInfo.latest.forChannel}`
+    });
+  } catch (error) {
+    logger.error('Error generating update instructions:', error);
+    res.status(500).json({ error: 'Failed to generate update instructions' });
+  }
+});
+
 // Get comprehensive system status
 router.get('/status', adminAuth, requirePermission('settings.view'), async (req, res) => {
   try {
@@ -262,4 +309,68 @@ router.get('/database', adminAuth, requirePermission('settings.view'), async (re
   }
 });
 
+// Get update notification settings
+router.get('/updates/notifications', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
+    const settings = await getUpdateNotificationSettings();
+    res.json(settings);
+  } catch (error) {
+    logger.error('Error fetching update notification settings:', error);
+    res.status(500).json({ error: 'Failed to fetch update notification settings' });
+  }
+});
+
+// Update notification settings
+router.put('/updates/notifications', adminAuth, requirePermission('settings.edit'), async (req, res) => {
+  try {
+    const { enabled, recipients } = req.body;
+
+    if (typeof enabled !== 'undefined') {
+      await db('app_settings')
+        .where('setting_key', 'update_email_notifications_enabled')
+        .update({
+          setting_value: JSON.stringify(enabled === true),
+          updated_at: db.fn.now()
+        });
+    }
+
+    if (typeof recipients !== 'undefined') {
+      await db('app_settings')
+        .where('setting_key', 'update_email_recipients')
+        .update({
+          setting_value: JSON.stringify(recipients || ''),
+          updated_at: db.fn.now()
+        });
+    }
+
+    const updatedSettings = await getUpdateNotificationSettings();
+    res.json({ success: true, settings: updatedSettings });
+  } catch (error) {
+    logger.error('Error updating notification settings:', error);
+    res.status(500).json({ error: 'Failed to update notification settings' });
+  }
+});
+
+// Manually trigger update notification email
+router.post('/updates/notifications/send', adminAuth, requirePermission('settings.edit'), async (req, res) => {
+  try {
+    const result = await sendUpdateNotificationNow();
+    res.json(result);
+  } catch (error) {
+    logger.error('Error sending update notification:', error);
+    res.status(500).json({ error: 'Failed to send update notification' });
+  }
+});
+
+// Check and send update notifications (called on admin login or periodically)
+router.post('/updates/notifications/check', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
+    const result = await checkAndNotifyUpdates();
+    res.json(result);
+  } catch (error) {
+    logger.error('Error checking for update notifications:', error);
+    res.status(500).json({ error: 'Failed to check for update notifications' });
+  }
+});
+
 module.exports = router;

backend/src/routes/adminThumbnails.js

@@ -10,27 +10,33 @@ const logger = require('../utils/logger');
 
 const getStoragePath = () => process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
 
+// Parse JSON-encoded setting values
+function parseSettingValue(value) {
+  if (value === null || value === undefined) return null;
+  try { return JSON.parse(value); } catch (e) { return value; }
+}
+
 // Get thumbnail settings
 router.get('/settings', adminAuth, requirePermission('photos.view'), async (req, res) => {
   try {
     const settings = await db('app_settings')
-      .whereIn('key', [
+      .whereIn('setting_key', [
         'thumbnail_width',
         'thumbnail_height',
         'thumbnail_fit',
         'thumbnail_quality',
         'thumbnail_format'
       ])
-      .select('key', 'value', 'description');
-    
+      .select('setting_key', 'setting_value');
+
     const settingsMap = {};
     settings.forEach(s => {
-      settingsMap[s.key] = {
-        value: s.value,
-        description: s.description
+      const parsed = parseSettingValue(s.setting_value);
+      settingsMap[s.setting_key] = {
+        value: String(parsed ?? '')
       };
     });
-    
+
     res.json({
       settings: settingsMap,
       fitOptions: ['cover', 'contain', 'fill', 'inside', 'outside'],
@@ -66,17 +72,17 @@ router.put('/settings', adminAuth, requirePermission('photos.edit'), async (req,
     
     // Update settings
     const updates = [];
-    if (width) updates.push({ key: 'thumbnail_width', value: width.toString() });
-    if (height) updates.push({ key: 'thumbnail_height', value: height.toString() });
-    if (fit) updates.push({ key: 'thumbnail_fit', value: fit });
-    if (quality) updates.push({ key: 'thumbnail_quality', value: quality.toString() });
-    if (format) updates.push({ key: 'thumbnail_format', value: format });
-    
+    if (width) updates.push({ setting_key: 'thumbnail_width', setting_value: width });
+    if (height) updates.push({ setting_key: 'thumbnail_height', setting_value: height });
+    if (fit) updates.push({ setting_key: 'thumbnail_fit', setting_value: JSON.stringify(fit) });
+    if (quality) updates.push({ setting_key: 'thumbnail_quality', setting_value: quality });
+    if (format) updates.push({ setting_key: 'thumbnail_format', setting_value: JSON.stringify(format) });
+
     for (const update of updates) {
       await db('app_settings')
-        .where('key', update.key)
+        .where('setting_key', update.setting_key)
         .update({
-          value: update.value,
+          setting_value: update.setting_value,
           updated_at: db.fn.now()
         });
     }

backend/src/routes/adminUsers.js

@@ -114,7 +114,8 @@ router.post('/invite', [
   const invitation = await userManagementService.createInvitation({
     email: req.body.email,
     roleId: req.body.role_id,
-    invitedById: req.admin.id
+    invitedById: req.admin.id,
+    inviterRoleName: req.admin.roleName
   });
 
   successResponse(res, { invitation }, 201);
@@ -146,7 +147,12 @@ router.get('/:id', [
   param('id').isInt({ min: 1 }).withMessage('Valid user ID is required')
 ], handleAsync(async (req, res) => {
   validateRequest(req);
-  const user = await userManagementService.getAdminUserById(parseInt(req.params.id));
+  const targetId = parseInt(req.params.id);
+  // Non-super_admin users can only view their own profile
+  if (req.admin.roleName !== 'super_admin' && targetId !== req.admin.id) {
+    return res.status(403).json({ error: 'Access denied' });
+  }
+  const user = await userManagementService.getAdminUserById(targetId);
   res.json({ user: transformUser(user) });
 }));
 
@@ -169,7 +175,8 @@ router.put('/:id', [
   const user = await userManagementService.updateAdminUser(
     parseInt(req.params.id),
     req.body,
-    req.admin.id
+    req.admin.id,
+    { roleName: req.admin.roleName }
   );
 
   successResponse(res, { user: transformUser(user), message: 'User updated successfully' });

backend/src/routes/adminWebhooks.js

@@ -0,0 +1,389 @@
+/**
+ * Admin endpoints for managing outbound webhooks (#327). Mirrors
+ * adminApiTokens.js — same permission gates, same "secret shown once"
+ * pattern.
+ *
+ * Routes mounted under /api/admin/webhooks:
+ *   GET    /                                — list
+ *   POST   /                                — create (returns plaintext secret once)
+ *   GET    /:id                             — detail (no secret)
+ *   PUT    /:id                             — update name/url/events/active
+ *   DELETE /:id                             — delete (cascades to deliveries)
+ *   POST   /:id/test                        — fire a synthetic delivery now
+ *   GET    /:id/deliveries                  — list deliveries (paginated, filter)
+ *   GET    /:id/deliveries/:deliveryId      — delivery detail (payload+response)
+ *   POST   /:id/deliveries/:deliveryId/replay — re-enqueue a delivery
+ */
+
+const express = require('express');
+const { body, query, validationResult } = require('express-validator');
+const { db, logActivity } = require('../database/db');
+const { adminAuth } = require('../middleware/auth');
+const { requirePermission } = require('../middleware/permissions');
+const { validateExternalUrl } = require('../utils/networkValidation');
+const webhookService = require('../services/webhookService');
+const logger = require('../utils/logger');
+
+const router = express.Router();
+
+const ALLOW_PRIVATE_URLS = process.env.WEBHOOK_ALLOW_PRIVATE_URLS === 'true';
+
+function publicWebhook(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    events: typeof row.events === 'string' ? safeJson(row.events, []) : (row.events || []),
+    active: row.active,
+    secret_preview: row.secret_preview,
+    filter: typeof row.filter === 'string' ? safeJson(row.filter, {}) : (row.filter || {}),
+    template: row.template || null,
+    created_by: row.created_by,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    last_success_at: row.last_success_at,
+    last_failure_at: row.last_failure_at,
+  };
+}
+
+function safeJson(s, fallback) {
+  try { return JSON.parse(s); } catch { return fallback; }
+}
+
+// ─── List ────────────────────────────────────────────────────────────────
+router.get('/', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
+    const rows = await db('webhooks')
+      .leftJoin('admin_users', 'admin_users.id', 'webhooks.created_by')
+      .select(
+        'webhooks.*',
+        'admin_users.username as owner_username'
+      )
+      .orderBy('webhooks.created_at', 'desc');
+    res.json(rows.map((r) => ({
+      ...publicWebhook(r),
+      owner_username: r.owner_username,
+    })));
+  } catch (err) {
+    logger.error('webhooks list failed', { error: err.message });
+    res.status(500).json({ error: 'Failed to list webhooks' });
+  }
+});
+
+// ─── Create ──────────────────────────────────────────────────────────────
+router.post(
+  '/',
+  adminAuth,
+  requirePermission('settings.edit'),
+  [
+    body('name').isString().trim().isLength({ min: 1, max: 100 }),
+    body('url').isString().isLength({ max: 2048 }).custom((url) => {
+      if (ALLOW_PRIVATE_URLS) return true;
+      const check = validateExternalUrl(url);
+      if (!check.valid) throw new Error(check.error);
+      return true;
+    }),
+    body('events').isArray({ min: 1 }).custom((arr) => {
+      const ok = arr.every((e) => webhookService.EVENT_TYPES.includes(e));
+      if (!ok) throw new Error(`events must be a subset of: ${webhookService.EVENT_TYPES.join(', ')}`);
+      return true;
+    }),
+    body('active').optional().isBoolean(),
+    body('filter').optional().custom((v) => {
+      if (v == null) return true;
+      if (typeof v !== 'object' || Array.isArray(v)) {
+        throw new Error('filter must be an object of dot-path → value pairs');
+      }
+      return true;
+    }),
+    body('template').optional({ nullable: true }).custom((v) => {
+      const check = webhookService.validateTemplate(v);
+      if (!check.valid) throw new Error(check.error);
+      return true;
+    }),
+  ],
+  async (req, res) => {
+    try {
+      const errors = validationResult(req);
+      if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() });
+
+      const { name, url, events, active = true, filter, template } = req.body;
+      const { plaintext, preview } = webhookService.generateSecret();
+
+      const insertResult = await db('webhooks').insert({
+        name,
+        url,
+        secret: plaintext,
+        secret_preview: preview,
+        events: JSON.stringify(events),
+        active,
+        filter: JSON.stringify(filter || {}),
+        template: template || null,
+        created_by: req.admin.id,
+      }).returning('id');
+      const id = insertResult[0]?.id || insertResult[0];
+
+      await logActivity('webhook_created', { name, events }, null, {
+        type: 'admin', id: req.admin.id, name: req.admin.username,
+      });
+
+      const row = await db('webhooks').where({ id }).first();
+      res.status(201).json({
+        ...publicWebhook(row),
+        secret: plaintext,
+        notice: 'Save this signing secret now — it will not be shown again.',
+      });
+    } catch (err) {
+      logger.error('webhooks create failed', { error: err.message });
+      res.status(500).json({ error: 'Failed to create webhook' });
+    }
+  }
+);
+
+// ─── Detail ──────────────────────────────────────────────────────────────
+router.get('/:id', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
+    const row = await db('webhooks').where({ id: req.params.id }).first();
+    if (!row) return res.status(404).json({ error: 'Webhook not found' });
+    res.json(publicWebhook(row));
+  } catch (err) {
+    logger.error('webhooks detail failed', { error: err.message });
+    res.status(500).json({ error: 'Failed to load webhook' });
+  }
+});
+
+// ─── Update ──────────────────────────────────────────────────────────────
+router.put(
+  '/:id',
+  adminAuth,
+  requirePermission('settings.edit'),
+  [
+    body('name').optional().isString().trim().isLength({ min: 1, max: 100 }),
+    body('url').optional().isString().isLength({ max: 2048 }).custom((url) => {
+      if (ALLOW_PRIVATE_URLS) return true;
+      const check = validateExternalUrl(url);
+      if (!check.valid) throw new Error(check.error);
+      return true;
+    }),
+    body('events').optional().isArray({ min: 1 }).custom((arr) => {
+      const ok = arr.every((e) => webhookService.EVENT_TYPES.includes(e));
+      if (!ok) throw new Error(`events must be a subset of: ${webhookService.EVENT_TYPES.join(', ')}`);
+      return true;
+    }),
+    body('active').optional().isBoolean(),
+    body('filter').optional().custom((v) => {
+      if (v == null) return true;
+      if (typeof v !== 'object' || Array.isArray(v)) {
+        throw new Error('filter must be an object of dot-path → value pairs');
+      }
+      return true;
+    }),
+    body('template').optional({ nullable: true }).custom((v) => {
+      const check = webhookService.validateTemplate(v);
+      if (!check.valid) throw new Error(check.error);
+      return true;
+    }),
+  ],
+  async (req, res) => {
+    try {
+      const errors = validationResult(req);
+      if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() });
+
+      const row = await db('webhooks').where({ id: req.params.id }).first();
+      if (!row) return res.status(404).json({ error: 'Webhook not found' });
+
+      const updates = { updated_at: new Date() };
+      if ('name' in req.body) updates.name = req.body.name;
+      if ('url' in req.body) updates.url = req.body.url;
+      if ('events' in req.body) updates.events = JSON.stringify(req.body.events);
+      if ('active' in req.body) updates.active = req.body.active;
+      if ('filter' in req.body) updates.filter = JSON.stringify(req.body.filter || {});
+      if ('template' in req.body) updates.template = req.body.template || null;
+
+      await db('webhooks').where({ id: req.params.id }).update(updates);
+      const updated = await db('webhooks').where({ id: req.params.id }).first();
+
+      await logActivity('webhook_updated', { changes: Object.keys(updates) }, null, {
+        type: 'admin', id: req.admin.id, name: req.admin.username,
+      });
+
+      res.json(publicWebhook(updated));
+    } catch (err) {
+      logger.error('webhooks update failed', { error: err.message });
+      res.status(500).json({ error: 'Failed to update webhook' });
+    }
+  }
+);
+
+// ─── Delete ──────────────────────────────────────────────────────────────
+router.delete('/:id', adminAuth, requirePermission('settings.edit'), async (req, res) => {
+  try {
+    const row = await db('webhooks').where({ id: req.params.id }).first();
+    if (!row) return res.status(404).json({ error: 'Webhook not found' });
+    await db('webhooks').where({ id: req.params.id }).delete();
+    await logActivity('webhook_deleted', { name: row.name }, null, {
+      type: 'admin', id: req.admin.id, name: req.admin.username,
+    });
+    res.json({ id: Number(req.params.id), deleted: true });
+  } catch (err) {
+    logger.error('webhooks delete failed', { error: err.message });
+    res.status(500).json({ error: 'Failed to delete webhook' });
+  }
+});
+
+// ─── Send test event ─────────────────────────────────────────────────────
+router.post(
+  '/:id/test',
+  adminAuth,
+  requirePermission('settings.edit'),
+  [body('event_type').optional().isIn(webhookService.EVENT_TYPES)],
+  async (req, res) => {
+    try {
+      const errors = validationResult(req);
+      if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() });
+
+      const row = await db('webhooks').where({ id: req.params.id }).first();
+      if (!row) return res.status(404).json({ error: 'Webhook not found' });
+      if (!row.active) return res.status(400).json({ error: 'Webhook is disabled' });
+
+      const eventType = req.body.event_type || (() => {
+        const subscribed = typeof row.events === 'string' ? safeJson(row.events, []) : (row.events || []);
+        return subscribed[0] || 'event.published';
+      })();
+
+      // Fire a synthetic event WITHOUT writing to webhooks table — the test
+      // bypasses subscription matching by inserting a delivery directly.
+      const crypto = require('crypto');
+      const deliveryId = crypto.randomUUID();
+      const payload = {
+        id: deliveryId,
+        type: eventType,
+        created_at: new Date().toISOString(),
+        data: { test: true, fired_by: req.admin.username, webhook_id: row.id },
+      };
+      await db('webhook_deliveries').insert({
+        webhook_id: row.id,
+        event_type: eventType,
+        payload: JSON.stringify(payload),
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      });
+
+      res.status(202).json({ enqueued: true, event_type: eventType });
+    } catch (err) {
+      logger.error('webhook test failed', { error: err.message });
+      res.status(500).json({ error: 'Failed to enqueue test event' });
+    }
+  }
+);
+
+// ─── List deliveries ─────────────────────────────────────────────────────
+router.get(
+  '/:id/deliveries',
+  adminAuth,
+  requirePermission('settings.view'),
+  [
+    query('status').optional().isIn(['pending', 'success', 'failed']),
+    query('page').optional().isInt({ min: 1 }),
+    query('limit').optional().isInt({ min: 1, max: 100 }),
+  ],
+  async (req, res) => {
+    try {
+      const errors = validationResult(req);
+      if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() });
+
+      const webhookId = req.params.id;
+      const exists = await db('webhooks').where({ id: webhookId }).first();
+      if (!exists) return res.status(404).json({ error: 'Webhook not found' });
+
+      const page = parseInt(req.query.page || '1', 10);
+      const limit = parseInt(req.query.limit || '25', 10);
+      const offset = (page - 1) * limit;
+
+      let q = db('webhook_deliveries').where({ webhook_id: webhookId });
+      if (req.query.status) q = q.where({ status: req.query.status });
+
+      const totalRow = await q.clone().count('id as count').first();
+      const total = parseInt(totalRow?.count || 0, 10);
+
+      const rows = await q
+        .select(
+          'id', 'event_type', 'attempt_count', 'status', 'response_status',
+          'latency_ms', 'next_retry_at', 'created_at', 'completed_at', 'last_error'
+        )
+        .orderBy('created_at', 'desc')
+        .limit(limit)
+        .offset(offset);
+
+      res.json({ deliveries: rows, pagination: { page, limit, total } });
+    } catch (err) {
+      logger.error('deliveries list failed', { error: err.message });
+      res.status(500).json({ error: 'Failed to list deliveries' });
+    }
+  }
+);
+
+// ─── Delivery detail ─────────────────────────────────────────────────────
+router.get(
+  '/:id/deliveries/:deliveryId',
+  adminAuth,
+  requirePermission('settings.view'),
+  async (req, res) => {
+    try {
+      const row = await db('webhook_deliveries')
+        .where({ id: req.params.deliveryId, webhook_id: req.params.id })
+        .first();
+      if (!row) return res.status(404).json({ error: 'Delivery not found' });
+      res.json({
+        ...row,
+        payload: typeof row.payload === 'string' ? safeJson(row.payload, row.payload) : row.payload,
+      });
+    } catch (err) {
+      logger.error('delivery detail failed', { error: err.message });
+      res.status(500).json({ error: 'Failed to load delivery' });
+    }
+  }
+);
+
+// ─── Replay ──────────────────────────────────────────────────────────────
+router.post(
+  '/:id/deliveries/:deliveryId/replay',
+  adminAuth,
+  requirePermission('settings.edit'),
+  async (req, res) => {
+    try {
+      const row = await db('webhook_deliveries')
+        .where({ id: req.params.deliveryId, webhook_id: req.params.id })
+        .first();
+      if (!row) return res.status(404).json({ error: 'Delivery not found' });
+
+      // Re-enqueue: copy the original payload + event_type into a new row
+      // marked pending. Preserves the audit log of the original attempt.
+      const crypto = require('crypto');
+      const newPayload = (() => {
+        const obj = typeof row.payload === 'string' ? safeJson(row.payload, {}) : row.payload || {};
+        // Replays get a fresh delivery id but keep the event payload data.
+        return JSON.stringify({ ...obj, id: crypto.randomUUID(), replayed_from: row.id });
+      })();
+      const insertResult = await db('webhook_deliveries').insert({
+        webhook_id: row.webhook_id,
+        event_type: row.event_type,
+        payload: newPayload,
+        attempt_count: 0,
+        status: 'pending',
+        next_retry_at: new Date(),
+        created_at: new Date(),
+      }).returning('id');
+      const newId = insertResult[0]?.id || insertResult[0];
+      res.status(202).json({ enqueued: true, original_id: row.id, replay_id: newId });
+    } catch (err) {
+      logger.error('delivery replay failed', { error: err.message });
+      res.status(500).json({ error: 'Failed to replay delivery' });
+    }
+  }
+);
+
+module.exports = router;

backend/src/routes/auth.js

@@ -13,6 +13,7 @@ const {
   getGenericAuthError
 } = require('../utils/authSecurity');
 const { endSession } = require('../middleware/sessionTimeout');
+const { revokeToken } = require('../utils/tokenRevocation');
 const logger = require('../utils/logger');
 const {
   setAdminAuthCookie,
@@ -117,9 +118,8 @@ router.post('/admin/login', [
 
     setAdminAuthCookie(res, token);
 
-    // Include role in response
+    // Token is delivered via HttpOnly cookie only (not in response body)
     res.json({
-      token,
       user: {
         id: admin.id,
         username: admin.username,
@@ -145,7 +145,8 @@ router.post('/logout', async (req, res) => {
     const token = adminToken || galleryToken;
 
     if (token) {
-      // End the session
+      // Revoke the token so it can't be reused, then end the session
+      await revokeToken(token, 'user_logout');
       endSession(token);
 
       try {
@@ -198,6 +199,8 @@ router.post('/gallery/verify', [
       .first();
 
     if (!event) {
+      // Perform a dummy bcrypt compare to prevent timing-based slug enumeration
+      await bcrypt.compare(password || '', '$2b$10$abcdefghijklmnopqrstuuABCDEFGHIJKLMNOPQRSTUVWXYZ01234');
       await trackFailedAttempt(`gallery:${slug}`, ipAddress, userAgent);
       return res.status(401).json({ error: 'Invalid gallery or password' });
     }
@@ -280,7 +283,8 @@ router.post('/gallery/verify', [
         expires_at: event.expires_at,
         allow_user_uploads: event.allow_user_uploads,
         upload_category_id: event.upload_category_id,
-        require_password: requiresPassword
+        require_password: requiresPassword,
+        photo_cap: event.photo_cap
       }
     });
   } catch (error) {
@@ -289,6 +293,82 @@ router.post('/gallery/verify', [
   }
 });
 
+// Client access login (PIN-based)
+router.post('/gallery/:slug/client-login', [
+  body('password').notEmpty().isString()
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { slug } = req.params;
+    const { password } = req.body;
+    const ipAddress = getClientIp(req);
+    const userAgent = req.headers['user-agent'] || '';
+
+    const event = await db('events')
+      .where({ slug, is_active: formatBoolean(true), is_archived: formatBoolean(false) })
+      .first();
+
+    if (!event || !event.client_access_enabled || !event.client_password_hash) {
+      await trackFailedAttempt(`client:${slug}`, ipAddress, userAgent);
+      return res.status(401).json({ error: 'Invalid credentials' });
+    }
+
+    const lockoutStatus = await checkAccountLockout(`client:${slug}`, ipAddress);
+    if (lockoutStatus.isLocked) {
+      return res.status(423).json({
+        error: 'Too many failed attempts. Please try again later.',
+        retryAfter: lockoutStatus.remainingTime
+      });
+    }
+
+    const validPassword = await bcrypt.compare(password, event.client_password_hash);
+    if (!validPassword) {
+      await trackFailedAttempt(`client:${slug}`, ipAddress, userAgent);
+      return res.status(401).json({ error: 'Invalid credentials' });
+    }
+
+    await trackSuccessfulLogin(`client:${slug}`, ipAddress, userAgent);
+
+    const token = jwt.sign({
+      eventId: event.id,
+      eventSlug: event.slug,
+      type: 'gallery',
+      accessLevel: 'client',
+      ip: ipAddress,
+      loginTime: Date.now()
+    }, process.env.JWT_SECRET, {
+      expiresIn: '24h',
+      issuer: 'picpeak-auth'
+    });
+
+    setGalleryAuthCookies(res, token, event.slug);
+
+    res.json({
+      token,
+      event: {
+        id: event.id,
+        event_name: event.event_name,
+        event_type: event.event_type,
+        event_date: event.event_date,
+        welcome_message: event.welcome_message,
+        color_theme: event.color_theme,
+        expires_at: event.expires_at,
+        allow_user_uploads: event.allow_user_uploads,
+        upload_category_id: event.upload_category_id,
+        require_password: true
+      },
+      accessLevel: 'client'
+    });
+  } catch (error) {
+    logger.error('Client login error:', error);
+    res.status(500).json({ error: 'Authentication failed' });
+  }
+});
+
 // Share link authentication (token-based)
 router.post('/gallery/share-login', [
   body('slug').notEmpty().trim(),
@@ -304,6 +384,17 @@ router.post('/gallery/share-login', [
     const ipAddress = getClientIp(req);
     const userAgent = req.headers['user-agent'] || '';
 
+    // Rate limit share-link login attempts
+    const shareIdentifier = `gallery:${slug}:share`;
+    const lockoutStatus = await checkAccountLockout(shareIdentifier, ipAddress);
+    if (lockoutStatus.isLocked) {
+      logger.warn('Share link login attempt on locked gallery', { slug, ipAddress });
+      return res.status(423).json({
+        error: 'Too many failed attempts. Please try again later.',
+        retryAfter: lockoutStatus.remainingTime
+      });
+    }
+
     let event = await db('events')
       .where({ slug, is_active: formatBoolean(true), is_archived: formatBoolean(false) })
       .first();
@@ -316,12 +407,14 @@ router.post('/gallery/share-login', [
     }
 
     if (!event) {
+      await trackFailedAttempt(shareIdentifier, ipAddress, userAgent);
       return res.status(404).json({ error: 'Gallery not found' });
     }
 
     const expectedToken = getEventShareToken(event);
 
     if (!expectedToken || token !== expectedToken) {
+      await trackFailedAttempt(shareIdentifier, ipAddress, userAgent);
       return res.status(401).json({ error: 'Invalid or expired share link' });
     }
 
@@ -353,7 +446,8 @@ router.post('/gallery/share-login', [
         expires_at: event.expires_at,
         allow_user_uploads: event.allow_user_uploads,
         upload_category_id: event.upload_category_id,
-        require_password: requiresPassword
+        require_password: requiresPassword,
+        photo_cap: event.photo_cap
       }
     });
   } catch (error) {
@@ -362,10 +456,14 @@ router.post('/gallery/share-login', [
   }
 });
 
-// Gallery logout to clear cookies
+// Gallery logout to clear cookies and revoke token
 router.post('/gallery/logout', async (req, res) => {
   try {
     const { slug } = req.body || {};
+    const token = getGalleryTokenFromRequest(req, slug);
+    if (token) {
+      await revokeToken(token, 'gallery_logout');
+    }
     clearGalleryAuthCookies(res, slug);
     res.json({ message: 'Logged out successfully' });
   } catch (error) {
@@ -386,11 +484,17 @@ router.get('/session', async (req, res) => {
 
     try {
       const decoded = jwt.verify(token, process.env.JWT_SECRET);
-      
+
+      // Check if token has been revoked (e.g. after logout)
+      const { isTokenRevoked } = require('../utils/tokenRevocation');
+      if (await isTokenRevoked(decoded)) {
+        return res.status(401).json({ valid: false, error: 'Session has been invalidated' });
+      }
+
       // Calculate remaining time
       const now = Date.now() / 1000;
       const remainingTime = Math.max(0, decoded.exp - now);
-      
+
       res.json({
         valid: true,
         type: decoded.type,

backend/src/routes/events.js

@@ -11,6 +11,7 @@ const path = require('path');
 const router = express.Router();
 const { buildShareLinkVariants } = require('../services/shareLinkService');
 const { parseBooleanInput, parseStringInput } = require('../utils/parsers');
+const eventTypeService = require('../services/eventTypeService');
 
 // Use parseStringInput from shared parsers for customer data extraction
 const getCustomerNameFromPayload = (payload = {}) => parseStringInput(payload.customer_name);
@@ -55,7 +56,13 @@ const hasCustomerContactColumns = async () => {
 
 // Create new event
 router.post('/', adminAuth, [
-  body('event_type').isIn(['wedding', 'birthday', 'corporate', 'other']),
+  body('event_type').notEmpty().trim().custom(async (value) => {
+    const isValid = await eventTypeService.isValidEventType(value);
+    if (!isValid) {
+      throw new Error('Invalid event type');
+    }
+    return true;
+  }),
   body('event_name').notEmpty(),
   body('event_date').isDate(),
   body('customer_name').notEmpty().trim(),
@@ -183,6 +190,27 @@ router.post('/', adminAuth, [
       welcome_message: welcome_message || ''
     });
 
+    // Webhook lifecycle (#327). Legacy public endpoint — events go live
+    // immediately so created + published fire together. Payload uses the
+    // canonical event subject (#341) — every event.* webhook now includes
+    // customer contact + share_token.
+    try {
+      const webhookService = require('../services/webhookService');
+      const eventSubject = webhookService.buildEventSubject({
+        id: eventId,
+        slug,
+        event_name,
+        event_type,
+        event_date,
+        share_url: shareUrl,
+        share_token: shareToken,
+        customer_name: customerName,
+        customer_email: customerEmail,
+      });
+      await webhookService.fire('event.created', { event: eventSubject });
+      await webhookService.fire('event.published', { event: eventSubject });
+    } catch (e) { /* non-fatal */ }
+
     res.json({
       id: eventId,
       slug,

backend/src/routes/gallery.js

@@ -5,17 +5,21 @@ const archiver = require('archiver');
 const path = require('path');
 const router = express.Router();
 const watermarkService = require('../services/watermarkService');
-const { verifyGalleryAccess } = require('../middleware/gallery');
+const watermarkGeneratorService = require('../services/watermarkGeneratorService');
+const { verifyGalleryAccess, isAdminPreview } = require('../middleware/gallery');
 const secureImageService = require('../services/secureImageService');
 const logger = require('../utils/logger');
 const { resolvePhotoFilePath } = require('../services/photoResolver');
 const { getEventShareToken, resolveShareIdentifier, buildShareLinkVariants } = require('../services/shareLinkService');
 const { handleAsync } = require('../utils/routeHelpers');
 const { NotFoundError } = require('../utils/errors');
-const { ensureThumbnail } = require('../services/imageProcessor');
+const { ensureThumbnail, ensureHeroImage } = require('../services/imageProcessor');
+const downloadZipService = require('../services/downloadZipService');
+const { getStorage } = require('../services/storage');
+const fs = require('fs');
 
 // Get storage path from environment or default
-const getStoragePath = () => process.env.STORAGE_PATH || path.join(__dirname, '../../storage');
+const getStoragePath = () => process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
 
 // Check for slug redirect (for renamed events)
 async function checkSlugRedirect(slug) {
@@ -73,7 +77,7 @@ router.get('/:slug/verify-token/:token', handleAsync(async (req, res) => {
   const { slug, token } = req.params;
 
   const event = await db('events')
-    .where({ slug, is_active: formatBoolean(true), is_archived: formatBoolean(false) })
+    .where({ slug, is_active: formatBoolean(true), is_archived: formatBoolean(false), is_draft: formatBoolean(false) })
     .select('id', 'share_link', 'share_token')
     .first();
 
@@ -107,13 +111,23 @@ router.get('/:slug/info', async (req, res) => {
         'share_link',
         'share_token',
         'allow_downloads',
+        'allow_user_uploads',
         'disable_right_click',
         'watermark_downloads',
         'watermark_text',
         'require_password',
         'color_theme',
         'enable_devtools_protection',
-        'use_canvas_rendering'
+        'use_canvas_rendering',
+        'hero_logo_visible',
+        'hero_logo_size',
+        'hero_logo_position',
+        'hero_logo_url',
+        'header_style',
+        'hero_divider_style',
+        'hero_image_anchor',
+        'is_draft',
+        'default_photo_sort'
       )
       .first();
 
@@ -129,11 +143,16 @@ router.get('/:slug/info', async (req, res) => {
       }
       return res.status(404).json({ error: 'Gallery not found' });
     }
-    
+
     // Check if event is archived
     if (event.is_archived) {
       return res.status(404).json({ error: 'Gallery has been archived and is no longer available' });
     }
+
+    // Check if event is a draft (allow admin preview)
+    if (event.is_draft && !isAdminPreview(req)) {
+      return res.status(404).json({ error: 'Gallery is not yet published' });
+    }
     
     // If token provided, verify it matches the share link
     if (token) {
@@ -151,15 +170,24 @@ router.get('/:slug/info', async (req, res) => {
       event_date: event.event_date,
       expires_at: event.expires_at,
       is_active: event.is_active,
-      is_expired: !event.is_active || new Date(event.expires_at) < new Date(),
+      is_expired: !event.is_active || (event.expires_at && new Date(event.expires_at) < new Date()),
       requires_password: requiresPassword,
       color_theme: event.color_theme,
       allow_downloads: !(event.allow_downloads === false || event.allow_downloads === 0 || event.allow_downloads === '0'),
+      allow_user_uploads: event.allow_user_uploads === true || event.allow_user_uploads === 1 || event.allow_user_uploads === '1',
       disable_right_click: event.disable_right_click === true || event.disable_right_click === 1 || event.disable_right_click === '1',
       watermark_downloads: event.watermark_downloads === true || event.watermark_downloads === 1 || event.watermark_downloads === '1',
       watermark_text: event.watermark_text,
       enable_devtools_protection: event.enable_devtools_protection === true || event.enable_devtools_protection === 1 || event.enable_devtools_protection === '1',
-      use_canvas_rendering: event.use_canvas_rendering === true || event.use_canvas_rendering === 1 || event.use_canvas_rendering === '1'
+      use_canvas_rendering: event.use_canvas_rendering === true || event.use_canvas_rendering === 1 || event.use_canvas_rendering === '1',
+      hero_logo_visible: event.hero_logo_visible !== false && event.hero_logo_visible !== 0 && event.hero_logo_visible !== '0',
+      hero_logo_size: event.hero_logo_size || 'medium',
+      hero_logo_position: event.hero_logo_position || 'top',
+      hero_logo_url: event.hero_logo_url || null,
+      header_style: event.header_style || 'standard',
+      hero_divider_style: event.hero_divider_style || 'wave',
+      hero_image_anchor: event.hero_image_anchor || 'center',
+      default_photo_sort: event.default_photo_sort || 'upload_date_desc'
     });
   } catch (error) {
     console.error('Error fetching gallery info:', error);
@@ -170,14 +198,42 @@ router.get('/:slug/info', async (req, res) => {
 // Get all photos
 router.get('/:slug/photos', verifyGalleryAccess, async (req, res) => {
   try {
-    // Get filter parameters from query
-    const { filter, guest_id } = req.query;
-    
-    // First get all photos
-    let photos = await db('photos')
+    // Get filter and sort parameters from query
+    const { filter, guest_id, sort = 'upload_date', order = 'desc' } = req.query;
+
+    // Get watermark settings to generate cache-busting version for URLs
+    const watermarkSettings = await watermarkService.getWatermarkSettings();
+    const wmVersion = watermarkSettings?.enabled
+      ? `wm=${watermarkSettings.opacity}${watermarkSettings.position}${watermarkSettings.size}`
+      : '';
+
+    // Build the query with sorting
+    const sortOrder = order === 'asc' ? 'asc' : 'desc';
+    const isClient = req.accessLevel === 'client';
+    let photosQuery = db('photos')
       .where('photos.event_id', req.event.id)
-      .select('photos.*')
-      .orderBy('photos.uploaded_at', 'desc');
+      .select('photos.*');
+
+    // Guests only see visible photos; clients see all
+    if (!isClient) {
+      photosQuery = photosQuery.where(function() {
+        this.where('photos.visibility', 'visible').orWhereNull('photos.visibility');
+      });
+    }
+
+    // Apply sort option
+    if (sort === 'capture_date') {
+      // Sort by capture date, falling back to uploaded_at if capture date is null
+      photosQuery = photosQuery.orderByRaw('COALESCE(photos.captured_at, photos.uploaded_at) ' + sortOrder);
+    } else if (sort === 'filename') {
+      photosQuery = photosQuery.orderBy('photos.filename', sortOrder);
+    } else {
+      // Default: sort by upload date
+      photosQuery = photosQuery.orderBy('photos.uploaded_at', sortOrder);
+    }
+
+    // Execute the query
+    let photos = await photosQuery;
     
     // Apply filtering if requested (supports global stats + per-guest interactions)
     if (filter) {
@@ -258,6 +314,11 @@ router.get('/:slug/photos', verifyGalleryAccess, async (req, res) => {
       }
     }
     
+    // Check if feedback should be visible to guests
+    const feedbackService = require('../services/feedbackService');
+    const feedbackSettings = await feedbackService.getEventFeedbackSettings(req.event.id);
+    const showFeedbackToGuests = isClient || feedbackSettings.show_feedback_to_guests !== false;
+
     // Then get comment counts separately
     const commentCounts = await db('photo_feedback')
       .whereIn('photo_id', photos.map(p => p.id))
@@ -273,20 +334,36 @@ router.get('/:slug/photos', verifyGalleryAccess, async (req, res) => {
       commentMap[c.photo_id] = parseInt(c.comment_count);
     });
     
-    // Get distinct photo types for this event
-    const categoryResults = await db('photos')
+    // Get actual categories used by photos in this event
+    // This includes both global categories and event-specific ones
+    const usedCategoryIds = await db('photos')
       .where('event_id', req.event.id)
-      .select('type')
-      .distinct('type')
-      .orderBy('type', 'asc');
-    
-    // Convert types to category-like objects
-    const categories = categoryResults.map(result => ({
-      id: result.type,
-      name: result.type === 'individual' ? 'Individual Photos' : 'Collages',
-      slug: result.type,
-      is_global: false
-    }));
+      .whereNotNull('category_id')
+      .distinct('category_id')
+      .pluck('category_id');
+
+    // Fetch category details from photo_categories table
+    let categories = [];
+    if (usedCategoryIds.length > 0) {
+      const categoryDetails = await db('photo_categories')
+        .whereIn('id', usedCategoryIds)
+        .select('id', 'name', 'slug', 'is_global', 'hero_photo_id')
+        .orderBy('name', 'asc');
+
+      categories = categoryDetails.map(cat => ({
+        id: cat.id,
+        name: cat.name,
+        slug: cat.slug,
+        is_global: cat.is_global,
+        hero_photo_id: cat.hero_photo_id || null
+      }));
+    }
+
+    // Build a map for quick category lookup
+    const categoryMap = {};
+    categories.forEach(cat => {
+      categoryMap[cat.id] = cat;
+    });
     
     // Log view
     await db('access_logs').insert({
@@ -317,41 +394,66 @@ router.get('/:slug/photos', verifyGalleryAccess, async (req, res) => {
         expires_at: req.event.expires_at,
         hero_photo_id: req.event.hero_photo_id,
         allow_downloads: req.event.allow_downloads !== false,
+        allow_user_uploads: req.event.allow_user_uploads === true,
         disable_right_click: req.event.disable_right_click === true,
         watermark_downloads: req.event.watermark_downloads === true,
         watermark_text: req.event.watermark_text,
         enable_devtools_protection: req.event.enable_devtools_protection === true,
         use_canvas_rendering: req.event.use_canvas_rendering === true,
+        hero_logo_visible: req.event.hero_logo_visible !== false && req.event.hero_logo_visible !== 0 && req.event.hero_logo_visible !== '0',
+        hero_logo_size: req.event.hero_logo_size || 'medium',
+        hero_logo_position: req.event.hero_logo_position || 'top',
+        hero_logo_url: req.event.hero_logo_url || null,
+        header_style: req.event.header_style || 'standard',
+        hero_divider_style: req.event.hero_divider_style || 'wave',
+        hero_image_anchor: req.event.hero_image_anchor || 'center',
+        default_photo_sort: req.event.default_photo_sort || 'upload_date_desc',
+        download_zip_ready: !!(req.event.download_zip_path && req.event.download_zip_generated_at),
         ...protectionSettings
       },
       categories: categories,
       photos: photos.map(photo => {
         const useJwtUrl = (protectionSettings.protection_level === 'basic' || protectionSettings.protection_level === 'standard');
-        const photoUrl = useJwtUrl ? 
-          `/api/gallery/${req.params.slug}/photo/${photo.id}` : 
+        // Add watermark version to URLs for cache busting when settings change
+        const wmQuery = wmVersion ? `?${wmVersion}` : '';
+        const photoUrl = useJwtUrl ?
+          `/api/gallery/${req.params.slug}/photo/${photo.id}${wmQuery}` :
           `/api/secure-images/${req.params.slug}/secure/${photo.id}/{{token}}`;
-        
+
         return {
           id: photo.id,
           filename: photo.filename,
           url: photoUrl,
-          thumbnail_url: photo.thumbnail_path ? `/api/gallery/${req.params.slug}/thumbnail/${photo.id}` : null,
+          thumbnail_url: photo.thumbnail_path ? `/api/gallery/${req.params.slug}/thumbnail/${photo.id}${wmQuery}` : null,
+          // Hero-optimized image URL (1920x1080) for full-width hero sections
+          hero_url: `/api/gallery/${req.params.slug}/hero/${photo.id}${wmQuery}`,
           secure_url_template: `/api/secure-images/${req.params.slug}/secure/${photo.id}/{{token}}`,
           download_url_template: `/api/secure-images/${req.params.slug}/secure-download/${photo.id}/{{token}}`,
           type: photo.type,
-          category_id: photo.type,
-          category_name: photo.type === 'individual' ? 'Individual Photos' : 'Collages',
-          category_slug: photo.type,
+          category_id: photo.category_id || null,
+          category_name: photo.category_id && categoryMap[photo.category_id] ? categoryMap[photo.category_id].name : null,
+          category_slug: photo.category_id && categoryMap[photo.category_id] ? categoryMap[photo.category_id].slug : null,
           size: photo.size_bytes,
           uploaded_at: photo.uploaded_at,
+          // Image dimensions for layout calculations
+          width: photo.width || null,
+          height: photo.height || null,
           // Fixed: Use the calculated useJwtUrl variable instead of recalculating
           requires_token: !useJwtUrl,
-          // Feedback data
-          has_feedback: (commentMap[photo.id] > 0 || photo.average_rating > 0 || photo.like_count > 0),
-          average_rating: photo.average_rating || 0,
-          comment_count: commentMap[photo.id] || 0,
-          like_count: photo.like_count || 0,
-          favorite_count: photo.favorite_count || 0
+          // EXIF capture date
+          captured_at: photo.captured_at || null,
+          // Media type
+          media_type: photo.media_type || null,
+          mime_type: photo.mime_type || null,
+          duration: photo.duration || null,
+          // Feedback data (hidden when show_feedback_to_guests is disabled)
+          has_feedback: showFeedbackToGuests ? (commentMap[photo.id] > 0 || photo.average_rating > 0 || photo.like_count > 0) : false,
+          average_rating: showFeedbackToGuests ? (photo.average_rating || 0) : 0,
+          comment_count: showFeedbackToGuests ? (commentMap[photo.id] || 0) : 0,
+          like_count: showFeedbackToGuests ? (photo.like_count || 0) : 0,
+          favorite_count: showFeedbackToGuests ? (photo.favorite_count || 0) : 0,
+          // Visibility (only included for clients)
+          ...(isClient ? { visibility: photo.visibility || 'visible' } : {})
         };
       })
     });
@@ -361,24 +463,91 @@ router.get('/:slug/photos', verifyGalleryAccess, async (req, res) => {
   }
 });
 
+// Toggle photo visibility (client-only)
+router.patch('/:slug/photos/:photoId/visibility', verifyGalleryAccess, async (req, res) => {
+  try {
+    if (req.accessLevel !== 'client') {
+      return res.status(403).json({ error: 'Client access required' });
+    }
+
+    const { photoId } = req.params;
+    const { visibility } = req.body;
+
+    if (!['visible', 'hidden'].includes(visibility)) {
+      return res.status(400).json({ error: 'Invalid visibility value' });
+    }
+
+    const photo = await db('photos')
+      .where({ id: photoId, event_id: req.event.id })
+      .first();
+
+    if (!photo) {
+      return res.status(404).json({ error: 'Photo not found' });
+    }
+
+    await db('photos')
+      .where({ id: photoId, event_id: req.event.id })
+      .update({ visibility });
+
+    res.json({ message: 'Photo visibility updated', visibility });
+  } catch (error) {
+    logger.error('Error updating photo visibility:', error);
+    res.status(500).json({ error: 'Failed to update photo visibility' });
+  }
+});
+
+// Bulk toggle photo visibility (client-only)
+router.patch('/:slug/photos/visibility/bulk', verifyGalleryAccess, async (req, res) => {
+  try {
+    if (req.accessLevel !== 'client') {
+      return res.status(403).json({ error: 'Client access required' });
+    }
+
+    const { photoIds, visibility } = req.body;
+
+    if (!Array.isArray(photoIds) || photoIds.length === 0) {
+      return res.status(400).json({ error: 'Invalid photo IDs' });
+    }
+
+    if (!['visible', 'hidden'].includes(visibility)) {
+      return res.status(400).json({ error: 'Invalid visibility value' });
+    }
+
+    const count = await db('photos')
+      .whereIn('id', photoIds)
+      .where('event_id', req.event.id)
+      .update({ visibility });
+
+    res.json({ message: `${count} photos updated`, visibility });
+  } catch (error) {
+    logger.error('Error bulk updating photo visibility:', error);
+    res.status(500).json({ error: 'Failed to update photo visibility' });
+  }
+});
+
 // Download single photo
 router.get('/:slug/download/:photoId', verifyGalleryAccess, async (req, res) => {
   try {
     const { photoId } = req.params;
-    
+
     // Check if downloads are allowed for this event
     if (req.event.allow_downloads === false) {
       return res.status(403).json({ error: 'Downloads are disabled for this gallery' });
     }
-    
+
     const photo = await db('photos')
       .where({ id: photoId, event_id: req.event.id })
       .first();
-    
+
     if (!photo) {
       return res.status(404).json({ error: 'Photo not found' });
     }
-    
+
+    // Block guest access to hidden photos
+    if (photo.visibility === 'hidden' && req.accessLevel !== 'client') {
+      return res.status(403).json({ error: 'Photo not available' });
+    }
+
     // Update download count
     await db('photos').where('id', photoId).increment('download_count', 1);
     
@@ -457,32 +626,86 @@ router.get('/:slug/download-all', verifyGalleryAccess, async (req, res) => {
     if (req.event.allow_downloads === false) {
       return res.status(403).json({ error: 'Downloads are disabled for this gallery' });
     }
-    
+
+    // Try to serve pre-generated zip (instant download with Content-Length)
+    const zipInfo = await downloadZipService.getZipInfo(req.event.id);
+    if (zipInfo) {
+      const storage = getStorage();
+
+      // Per-event presigned-URL fast path (#328 follow-up). Conditions:
+      //   1. STORAGE_BACKEND=s3 (presigned URLs are S3-only)
+      //   2. event.allow_presigned_download is true (admin opted in)
+      //   3. Watermarking is OFF for this event — presigned URLs bypass the
+      //      backend, which means no watermark on bytes leaving S3.
+      // Falls through to streaming on any condition mismatch.
+      const wantsPresigned = req.event.allow_presigned_download === true || req.event.allow_presigned_download === 1;
+      const watermarkOnEvent = req.event.watermark_downloads === true || req.event.watermark_downloads === 1;
+      if (wantsPresigned && storage.kind() === 's3' && !watermarkOnEvent) {
+        try {
+          const url = await storage.signedUrl(zipInfo.key, 300); // 5 min
+          db('access_logs').insert({
+            event_id: req.event.id,
+            ip_address: req.ip,
+            user_agent: req.headers['user-agent'],
+            action: 'download_all_presigned'
+          }).catch(() => {});
+          res.redirect(302, url);
+          return;
+        } catch (err) {
+          logger.warn('presigned download-all failed, falling back to stream', {
+            eventId: req.event.id,
+            error: err.message,
+          });
+        }
+      }
+
+      res.setHeader('Content-Type', 'application/zip');
+      res.setHeader('Content-Length', zipInfo.size);
+      res.setHeader('Content-Disposition', `attachment; filename="${req.event.slug}.zip"`);
+      const stream = await storage.get(zipInfo.key);
+      stream.pipe(res);
+
+      // Log bulk download
+      db('access_logs').insert({
+        event_id: req.event.id,
+        ip_address: req.ip,
+        user_agent: req.headers['user-agent'],
+        action: 'download_all'
+      }).catch(() => {});
+      return;
+    }
+
+    // Fallback: on-the-fly streaming (existing behavior)
+    // Also trigger background zip generation for next time
+    downloadZipService.generateZip(req.event.id).catch(err =>
+      logger.warn('Background zip generation failed', { eventId: req.event.id, error: err.message })
+    );
+
     // Fetch photos
     const photos = await db('photos')
       .where('photos.event_id', req.event.id)
       .select('photos.*')
       .orderBy('photos.type', 'asc')
       .orderBy('photos.uploaded_at', 'desc');
-    
+
     if (photos.length === 0) {
       return res.status(404).json({ error: 'No photos found' });
     }
-    
+
     // Count unique types
     const uniqueTypes = new Set(photos.map(p => p.type)).size;
     const hasMultipleTypes = uniqueTypes > 1;
-    
+
     res.setHeader('Content-Type', 'application/zip');
     res.setHeader('Content-Disposition', `attachment; filename="${req.event.slug}.zip"`);
-    
+
     const archive = archiver('zip', { zlib: { level: 5 } });
     archive.on('error', (err) => {
       throw err;
     });
-    
+
     archive.pipe(res);
-    
+
     // Get watermark settings - apply if global setting OR event-level setting is enabled
     const watermarkSettings = await watermarkService.getWatermarkSettings();
     const eventWatermarkEnabled = req.event.watermark_downloads === true || req.event.watermark_downloads === 1;
@@ -493,51 +716,54 @@ router.get('/:slug/download-all', verifyGalleryAccess, async (req, res) => {
       text: req.event.watermark_text || watermarkSettings?.text || 'Protected'
     } : null;
 
-    // Add photos to archive
+    // Add photos to archive — managed photos via storage backend, external via local path.
+    const { resolvePhotoStorageKey } = require('../services/photoResolver');
+    const storage = getStorage();
     for (const photo of photos) {
-      let filePath;
-      try {
-        filePath = resolvePhotoFilePath(req.event, photo);
-      } catch (resolveError) {
-        logger.warn('Skipping photo in bulk download due to unresolved path', {
-          slug: req.params.slug,
-          photoId: photo.id,
-          eventId: req.event.id,
-          error: resolveError.message,
-        });
-        continue;
-      }
-
-      // Determine the file name in the archive
+      const storageKey = resolvePhotoStorageKey(req.event, photo);
       let archiveName;
       if (hasMultipleTypes) {
-        // Use photo type as folder
         const folderName = photo.type === 'individual' ? 'Individual Photos' : 'Collages';
         archiveName = path.join(folderName, photo.filename);
       } else {
-        // No folders, just the filename
         archiveName = photo.filename;
       }
 
-      if (shouldApplyWatermark && effectiveSettings) {
-        try {
-          const watermarkedBuffer = await watermarkService.applyWatermark(filePath, effectiveSettings);
+      try {
+        if (shouldApplyWatermark && effectiveSettings) {
+          // Watermark service operates on a local path. For managed photos in
+          // S3 mode, materialize a tmp local copy first.
+          const { withLocalCopy } = require('../services/imageProcessor');
+          const sourceForWatermark = storageKey
+            ? null
+            : resolvePhotoFilePath(req.event, photo);
+
+          const watermarkedBuffer = storageKey
+            ? await withLocalCopy(storageKey, (localPath) =>
+                watermarkService.applyWatermark(localPath, effectiveSettings)
+              )
+            : await watermarkService.applyWatermark(sourceForWatermark, effectiveSettings);
+
           archive.append(watermarkedBuffer, { name: archiveName });
-        } catch (watermarkError) {
-          logger.warn('Failed to watermark photo for bulk download, skipping original to avoid leak', {
-            slug: req.params.slug,
-            photoId: photo.id,
-            eventId: req.event.id,
-            error: watermarkError.message,
-          });
+        } else if (storageKey) {
+          const stream = await storage.get(storageKey);
+          archive.append(stream, { name: archiveName });
+        } else {
+          const filePath = resolvePhotoFilePath(req.event, photo);
+          archive.file(filePath, { name: archiveName });
         }
-      } else {
-        archive.file(filePath, { name: archiveName });
+      } catch (err) {
+        logger.warn('Skipping photo in bulk download due to error', {
+          slug: req.params.slug,
+          photoId: photo.id,
+          eventId: req.event.id,
+          error: err.message,
+        });
       }
     }
-    
+
     await archive.finalize();
-    
+
     // Log bulk download
     await db('access_logs').insert({
       event_id: req.event.id,
@@ -618,31 +844,32 @@ router.post('/:slug/download-selected', verifyGalleryAccess, async (req, res) =>
       text: req.event.watermark_text || watermarkSettings?.text || 'Protected'
     } : null;
 
+    const { resolvePhotoStorageKey: resolveSelectedKey } = require('../services/photoResolver');
+    const { withLocalCopy: withSelectedLocalCopy } = require('../services/imageProcessor');
+    const selectedStorage = getStorage();
     for (const photo of photos) {
+      const name = photo.filename || `photo-${photo.id}.jpg`;
+      const storageKey = resolveSelectedKey(req.event, photo);
       try {
-        const filePath = resolvePhotoFilePath(req.event, photo);
-        const name = photo.filename || `photo-${photo.id}.jpg`;
         if (shouldApplyWatermark && effectiveSettings) {
-          try {
-            const watermarkedBuffer = await watermarkService.applyWatermark(filePath, effectiveSettings);
-            archive.append(watermarkedBuffer, { name });
-          } catch (watermarkError) {
-            logger.warn('Failed to watermark selected photo, skipping original to avoid leak', {
-              slug: req.params.slug,
-              photoId: photo.id,
-              eventId: req.event.id,
-              error: watermarkError.message,
-            });
-          }
+          const buf = storageKey
+            ? await withSelectedLocalCopy(storageKey, (lp) =>
+                watermarkService.applyWatermark(lp, effectiveSettings)
+              )
+            : await watermarkService.applyWatermark(resolvePhotoFilePath(req.event, photo), effectiveSettings);
+          archive.append(buf, { name });
+        } else if (storageKey) {
+          const stream = await selectedStorage.get(storageKey);
+          archive.append(stream, { name });
         } else {
-          archive.file(filePath, { name });
+          archive.file(resolvePhotoFilePath(req.event, photo), { name });
         }
-      } catch (resolveError) {
-        logger.warn('Skipping selected photo due to unresolved path', {
+      } catch (err) {
+        logger.warn('Skipping selected photo due to error', {
           slug: req.params.slug,
           photoId: photo.id,
           eventId: req.event.id,
-          error: resolveError.message,
+          error: err.message,
         });
       }
     }
@@ -677,11 +904,15 @@ router.get('/:slug/photo/:photoId',
         .where({ id: photoId, event_id: req.event.id })
         .first();
 
-
       if (!photo) {
         return res.status(404).json({ error: 'Photo not found' });
       }
 
+      // Block guest access to hidden photos
+      if (photo.visibility === 'hidden' && req.accessLevel !== 'client') {
+        return res.status(403).json({ error: 'Photo not available' });
+      }
+
       // Check if this is a video
       const isVideo = photo.media_type === 'video' || (photo.mime_type && photo.mime_type.startsWith('video/'));
 
@@ -699,8 +930,34 @@ router.get('/:slug/photo/:photoId',
 
       // Resolve the absolute file path for this photo, supporting both managed and external reference modes
       const { resolvePhotoFilePath } = require('../services/photoResolver');
-      const filePath = resolvePhotoFilePath(req.event, photo);
+      const fs = require('fs');
 
+      let filePath;
+      try {
+        filePath = resolvePhotoFilePath(req.event, photo);
+      } catch (resolveError) {
+        logger.error('Failed to resolve photo path', {
+          slug: req.params.slug,
+          photoId,
+          eventId: req.event.id,
+          error: resolveError.message,
+          photoPath: photo.path,
+          photoFilename: photo.filename
+        });
+        return res.status(404).json({ error: 'Photo file not found' });
+      }
+
+      // Verify file exists before attempting to serve
+      if (!fs.existsSync(filePath)) {
+        logger.error('Photo file does not exist at resolved path', {
+          slug: req.params.slug,
+          photoId,
+          eventId: req.event.id,
+          resolvedPath: filePath,
+          photoPath: photo.path
+        });
+        return res.status(404).json({ error: 'Photo file not found' });
+      }
 
       // Log access - temporarily disabled for debugging
       // await secureImageService.logImageAccess(
@@ -712,14 +969,13 @@ router.get('/:slug/photo/:photoId',
 
       // Handle video streaming with range requests
       if (isVideo) {
-        const fs = require('fs');
         const stat = fs.statSync(filePath);
         const fileSize = stat.size;
         const range = req.headers.range;
 
         if (range) {
           // Parse range header
-          const parts = range.replace(/bytes=/, "").split("-");
+          const parts = range.replace(/bytes=/, '').split('-');
           const start = parseInt(parts[0], 10);
           const end = parts[1] ? parseInt(parts[1], 10) : fileSize - 1;
           const chunksize = (end - start) + 1;
@@ -754,13 +1010,52 @@ router.get('/:slug/photo/:photoId',
       // Get watermark settings
       const watermarkSettings = await watermarkService.getWatermarkSettings();
 
+      // Generate ETag based on photo id, modification time, and watermark settings
+      // This ensures cache invalidation when watermark settings change
+      const stat = fs.statSync(filePath);
+      const watermarkHash = watermarkSettings?.enabled
+        ? `-wm${watermarkSettings.opacity}${watermarkSettings.position}${watermarkSettings.size}`
+        : '-nowm';
+      const etag = `"${photoId}-${stat.mtime.getTime()}${watermarkHash}"`;
+
+      // Check if client has valid cached version
+      if (req.headers['if-none-match'] === etag) {
+        return res.status(304).end();
+      }
+
       if (watermarkSettings && watermarkSettings.enabled) {
-        // Apply watermark and send
+        // Try to serve pre-generated watermarked file for instant loading
+        if (photo.watermark_path) {
+          const watermarkFilePath = path.join(getStoragePath(), photo.watermark_path);
+          try {
+            // Check if pre-generated watermark file exists
+            if (fs.existsSync(watermarkFilePath)) {
+              res.set({
+                'Content-Type': photo.mime_type || 'image/jpeg',
+                'Cache-Control': 'private, max-age=1800',
+                'ETag': etag,
+                'X-Protection-Level': 'basic'
+              });
+              return res.sendFile(watermarkFilePath);
+            }
+          } catch (err) {
+            // File doesn't exist or error, fall through to on-the-fly generation
+            logger.warn(`Pre-generated watermark not found for photo ${photoId}, falling back to on-the-fly`);
+          }
+        }
+
+        // Fallback: Apply watermark on-the-fly (slower, but ensures image is served)
+        // Also queue regeneration for next time
         const watermarkedBuffer = await watermarkService.applyWatermark(filePath, watermarkSettings);
 
+        // Queue watermark generation in background for next request
+        watermarkGeneratorService.generateForPhoto(photo.id)
+          .catch(err => logger.warn(`Background watermark generation failed for photo ${photo.id}:`, err.message));
+
         res.set({
           'Content-Type': photo.mime_type || 'image/jpeg',
           'Cache-Control': 'private, max-age=1800', // Cache for 30 minutes
+          'ETag': etag,
           'X-Protection-Level': 'basic'
         });
 
@@ -769,6 +1064,7 @@ router.get('/:slug/photo/:photoId',
         // Send original file with basic protection headers
         res.set({
           'Cache-Control': 'private, max-age=1800',
+          'ETag': etag,
           'X-Protection-Level': 'basic'
         });
         // Ensure absolute path for res.sendFile
@@ -802,6 +1098,11 @@ router.get('/:slug/thumbnail/:photoId',
         return res.status(404).json({ error: 'Photo not found' });
       }
 
+      // Block guest access to hidden photos
+      if (photo.visibility === 'hidden' && req.accessLevel !== 'client') {
+        return res.status(403).json({ error: 'Photo not available' });
+      }
+
       // Ensure thumbnail exists and is valid, regenerate if needed
       const thumbnailPath = await ensureThumbnail(photo);
 
@@ -820,17 +1121,40 @@ router.get('/:slug/thumbnail/:photoId',
         'thumbnail'
       );
 
+      // Check if watermarks are enabled and apply to thumbnail
+      const watermarkSettings = await watermarkService.getWatermarkSettings();
+
+      // Generate ETag based on photo id, thumbnail modification time, and watermark settings
+      const fs = require('fs');
+      const stat = fs.statSync(thumbPath);
+      const watermarkHash = watermarkSettings?.enabled
+        ? `-wm${watermarkSettings.opacity}${watermarkSettings.position}${watermarkSettings.size}`
+        : '-nowm';
+      const etag = `"thumb-${photoId}-${stat.mtime.getTime()}${watermarkHash}"`;
+
+      // Check if client has valid cached version
+      if (req.headers['if-none-match'] === etag) {
+        return res.status(304).end();
+      }
+
       // Set appropriate headers with enhanced security
       res.set({
         'Content-Type': 'image/jpeg',
         'Cache-Control': 'private, max-age=1800', // Reduced cache time
         'Cross-Origin-Resource-Policy': 'cross-origin',
         'X-Content-Type-Options': 'nosniff',
-        'X-Protected-Thumbnail': 'true'
+        'X-Protected-Thumbnail': 'true',
+        'ETag': etag
       });
 
-      // Send file
-      res.sendFile(path.resolve(thumbPath));
+      if (watermarkSettings && watermarkSettings.enabled) {
+        // Apply watermark to thumbnail
+        const watermarkedBuffer = await watermarkService.applyWatermark(thumbPath, watermarkSettings);
+        res.send(watermarkedBuffer);
+      } else {
+        // Send file without watermark
+        res.sendFile(path.resolve(thumbPath));
+      }
     } catch (error) {
       logger.error('Error serving thumbnail:', {
         error: error.message,
@@ -842,6 +1166,97 @@ router.get('/:slug/thumbnail/:photoId',
   }
 );
 
+// Serve hero-optimized image (1920x1080 for full-width hero sections)
+router.get('/:slug/hero/:photoId',
+  verifyGalleryAccess,
+  async (req, res) => {
+    try {
+      const { photoId } = req.params;
+
+      const photo = await db('photos')
+        .where({ id: photoId, event_id: req.event.id })
+        .first();
+
+      if (!photo) {
+        return res.status(404).json({ error: 'Photo not found' });
+      }
+
+      // Block guest access to hidden photos
+      if (photo.visibility === 'hidden' && req.accessLevel !== 'client') {
+        return res.status(403).json({ error: 'Photo not available' });
+      }
+
+      // Check if this is a video - videos don't get hero images
+      const isVideo = photo.media_type === 'video' || (photo.mime_type && photo.mime_type.startsWith('video/'));
+      if (isVideo) {
+        // For videos, redirect to the regular photo endpoint
+        return res.redirect(`/api/gallery/${req.params.slug}/photo/${photoId}`);
+      }
+
+      // Ensure hero image exists and is valid, regenerate if needed
+      const heroPath = await ensureHeroImage(photo);
+
+      if (!heroPath) {
+        // If hero generation fails, fall back to original photo
+        logger.warn(`Failed to generate hero image for photo ${photoId}, falling back to original`);
+        return res.redirect(`/api/gallery/${req.params.slug}/photo/${photoId}`);
+      }
+
+      const heroFullPath = path.join(getStoragePath(), heroPath);
+      const fs = require('fs');
+
+      // Verify file exists before attempting to serve
+      if (!fs.existsSync(heroFullPath)) {
+        logger.error('Hero image file does not exist at resolved path', {
+          slug: req.params.slug,
+          photoId,
+          eventId: req.event.id,
+          resolvedPath: heroFullPath
+        });
+        return res.redirect(`/api/gallery/${req.params.slug}/photo/${photoId}`);
+      }
+
+      // Get file stats for ETag
+      const stat = fs.statSync(heroFullPath);
+      const etag = `"hero-${photoId}-${stat.mtime.getTime()}"`;
+
+      // Check if client has valid cached version
+      if (req.headers['if-none-match'] === etag) {
+        return res.status(304).end();
+      }
+
+      // Check if watermarks should be applied
+      const watermarkSettings = await watermarkService.getWatermarkSettings();
+
+      res.set({
+        'Content-Type': 'image/jpeg',
+        'Cache-Control': 'private, max-age=3600', // Cache for 1 hour
+        'Cross-Origin-Resource-Policy': 'cross-origin',
+        'X-Content-Type-Options': 'nosniff',
+        'X-Hero-Image': 'true',
+        'ETag': etag
+      });
+
+      if (watermarkSettings && watermarkSettings.enabled) {
+        // Apply watermark to hero image
+        const watermarkedBuffer = await watermarkService.applyWatermark(heroFullPath, watermarkSettings);
+        res.send(watermarkedBuffer);
+      } else {
+        // Send hero image without watermark
+        res.sendFile(path.resolve(heroFullPath));
+      }
+    } catch (error) {
+      logger.error('Error serving hero image:', {
+        error: error.message,
+        photoId: req.params.photoId,
+        eventId: req.event?.id
+      });
+      // Fall back to original photo on any error
+      res.redirect(`/api/gallery/${req.params.slug}/photo/${req.params.photoId}`);
+    }
+  }
+);
+
 // Get feedback settings for gallery
 router.get('/:slug/feedback-settings', verifyGalleryAccess, async (req, res) => {
   try {
@@ -851,10 +1266,12 @@ router.get('/:slug/feedback-settings', verifyGalleryAccess, async (req, res) =>
     res.json({
       feedback_enabled: settings.feedback_enabled || false,
       allow_ratings: settings.allow_ratings,
-      allow_likes: settings.allow_likes, 
+      allow_likes: settings.allow_likes,
       allow_comments: settings.allow_comments,
       allow_favorites: settings.allow_favorites,
-      show_feedback_to_guests: settings.show_feedback_to_guests
+      show_feedback_to_guests: settings.show_feedback_to_guests,
+      require_name_email: settings.require_name_email || false,
+      identity_mode: settings.identity_mode || 'simple'
     });
   } catch (error) {
     console.error('Error fetching feedback settings:', error);
@@ -927,6 +1344,17 @@ router.post('/:eventId/upload', verifyGalleryAccess, async (req, res) => {
 
     // Import multer and photo processing
     const multer = require('multer');
+    const { getAllowedMimeTypes } = require('../services/uploadSettings');
+    const { validateFileType } = require('../utils/fileSecurityUtils');
+
+    // Resolve allowed MIME types from settings
+    let allowedMimeTypes;
+    try {
+      allowedMimeTypes = await getAllowedMimeTypes();
+    } catch {
+      allowedMimeTypes = ['image/jpeg', 'image/png', 'image/webp'];
+    }
+
     const upload = multer({
       dest: tempUploadDir,
       limits: {
@@ -934,8 +1362,7 @@ router.post('/:eventId/upload', verifyGalleryAccess, async (req, res) => {
         files: 10 // Max 10 files at once
       },
       fileFilter: (req, file, cb) => {
-        const allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
-        if (allowedTypes.includes(file.mimetype)) {
+        if (validateFileType(file.originalname, file.mimetype, allowedMimeTypes)) {
           cb(null, true);
         } else {
           cb(new Error('Invalid file type'));

backend/src/routes/galleryFeedback.js

@@ -3,6 +3,7 @@ const router = express.Router();
 const { photoAuth } = require('../middleware/photoAuth');
 const { verifyGalleryAccess } = require('../middleware/gallery');
 const { feedbackRateLimit, generateGuestIdentifier } = require('../middleware/feedbackRateLimit');
+const { resolveGuest } = require('../middleware/guestAuth');
 const feedbackService = require('../services/feedbackService');
 const feedbackModeration = require('../services/feedbackModeration');
 const { db, logActivity } = require('../database/db');
@@ -22,7 +23,7 @@ router.get('/:slug/feedback-settings',
     try {
       const event = req.event;
       const settings = await feedbackService.getEventFeedbackSettings(event.id);
-      
+
       // Only send relevant settings to guests
       // Convert SQLite boolean values (0/1) to proper booleans
       const guestSettings = {
@@ -32,9 +33,10 @@ router.get('/:slug/feedback-settings',
         allow_comments: Boolean(settings.allow_comments),
         allow_favorites: Boolean(settings.allow_favorites),
         require_name_email: Boolean(settings.require_name_email),
-        show_feedback_to_guests: Boolean(settings.show_feedback_to_guests)
+        show_feedback_to_guests: Boolean(settings.show_feedback_to_guests),
+        identity_mode: settings.identity_mode || 'simple'
       };
-      
+
       res.json(guestSettings);
     } catch (error) {
       logger.error('Error getting feedback settings:', error);
@@ -46,6 +48,7 @@ router.get('/:slug/feedback-settings',
 // Get feedback for a specific photo
 router.get('/:slug/photos/:photoId/feedback',
   verifyGalleryAccess,
+  resolveGuest,
   validatePhotoId,
   checkValidation,
   async (req, res) => {
@@ -137,6 +140,7 @@ router.get('/:slug/photos/:photoId/feedback',
 // Submit feedback for a photo
 router.post('/:slug/photos/:photoId/feedback',
   verifyGalleryAccess,
+  resolveGuest,
   validatePhotoId,
   validateFeedbackSubmission,
   checkValidation,
@@ -144,15 +148,28 @@ router.post('/:slug/photos/:photoId/feedback',
     try {
       const { photoId } = req.params;
       const event = req.event;
-      const guestIdentifier = generateGuestIdentifier(req);
-      
-      // Get feedback settings
+
+      // Get feedback settings first so we can enforce identity_mode.
       const settings = await feedbackService.getEventFeedbackSettings(event.id);
-      
+
       if (!settings.feedback_enabled) {
         return res.status(403).json({ error: 'Feedback is not enabled for this event' });
       }
-      
+
+      // In guest identity mode, a valid guest token is required. The server
+      // never trusts guest_name/guest_email from the body in this mode — it
+      // reads them from the verified token via req.guest.
+      if (settings.identity_mode === 'guest') {
+        if (!req.guest || req.guest.eventId !== event.id) {
+          return res.status(401).json({
+            error: 'Guest identity required',
+            code: 'GUEST_IDENTITY_REQUIRED'
+          });
+        }
+      }
+
+      const guestIdentifier = generateGuestIdentifier(req);
+
       // Check if specific feedback type is allowed
       const feedbackType = req.body.feedback_type;
       const typeAllowed = {
@@ -161,29 +178,32 @@ router.post('/:slug/photos/:photoId/feedback',
         comment: settings.allow_comments,
         favorite: settings.allow_favorites
       };
-      
+
       if (!typeAllowed[feedbackType]) {
         return res.status(403).json({ error: `${feedbackType} feedback is not enabled` });
       }
-      
+
       // Verify photo belongs to event
       const photo = await db('photos')
         .where({ id: photoId, event_id: event.id })
         .first();
-      
+
       if (!photo) {
         return res.status(404).json({ error: 'Photo not found' });
       }
-      
-      // Validate guest requirements
-      const guestValidation = await validateGuestRequirements(settings, req.body);
-      if (!guestValidation.valid) {
-        return res.status(400).json({ 
-          error: 'Guest information required',
-          errors: guestValidation.errors 
-        });
+
+      // Validate guest requirements only in simple mode. In guest mode, the
+      // identity is already provided via the token and verified above.
+      if (settings.identity_mode !== 'guest') {
+        const guestValidation = await validateGuestRequirements(settings, req.body);
+        if (!guestValidation.valid) {
+          return res.status(400).json({
+            error: 'Guest information required',
+            errors: guestValidation.errors
+          });
+        }
       }
-      
+
       // Apply rate limiting based on feedback type
       const rateLimitMiddleware = feedbackRateLimit(feedbackType);
       await new Promise((resolve, reject) => {
@@ -192,19 +212,21 @@ router.post('/:slug/photos/:photoId/feedback',
           else resolve();
         });
       });
-      
+
       // If we got here and response was sent (rate limited), return
       if (res.headersSent) return;
-      
-      // Prepare feedback data
+
+      // Prepare feedback data. In guest mode, use the verified token as the
+      // source of truth for name/email — never the body.
       const feedbackData = {
         feedback_type: feedbackType,
         rating: req.body.rating,
         comment_text: req.body.comment_text,
-        guest_name: req.body.guest_name,
-        guest_email: req.body.guest_email,
+        guest_name: req.guest?.name ?? req.body.guest_name,
+        guest_email: req.guest?.email ?? req.body.guest_email,
+        guest_id: req.guest?.id ?? null,
         ip_address: req.ip || req.connection.remoteAddress,
-        user_agent: req.headers['user-agent'],
+        user_agent: (req.headers['user-agent'] || '').replace(/[<>&"']/g, '').substring(0, 255),
         moderate_comments: settings.moderate_comments
       };
       
@@ -316,22 +338,32 @@ router.get('/:slug/feedback-summary',
 // Get user's own feedback for all photos
 router.get('/:slug/my-feedback',
   verifyGalleryAccess,
+  resolveGuest,
   async (req, res) => {
     try {
       const event = req.event;
-      const guestIdentifier = generateGuestIdentifier(req);
-      
-      const myFeedback = await db('photo_feedback')
+
+      const query = db('photo_feedback')
         .join('photos', 'photo_feedback.photo_id', 'photos.id')
-        .where('photo_feedback.event_id', event.id)
-        .where('photo_feedback.guest_identifier', guestIdentifier)
+        .where('photo_feedback.event_id', event.id);
+
+      // Prefer guest_id lookup when a verified guest token is present
+      // (per-person identity). Fall back to the device hash otherwise.
+      if (req.guest?.id) {
+        query.where('photo_feedback.guest_id', req.guest.id);
+      } else {
+        const guestIdentifier = generateGuestIdentifier(req);
+        query.where('photo_feedback.guest_identifier', guestIdentifier);
+      }
+
+      const myFeedback = await query
         .select(
           'photo_feedback.*',
           'photos.filename',
           'photos.path'
         )
         .orderBy('photo_feedback.created_at', 'desc');
-      
+
       res.json(myFeedback);
     } catch (error) {
       logger.error('Error getting user feedback:', error);

backend/src/routes/galleryGuests.js

@@ -0,0 +1,409 @@
+const express = require('express');
+const crypto = require('crypto');
+const router = express.Router();
+const { db } = require('../database/db');
+const logger = require('../utils/logger');
+const { verifyGalleryAccess } = require('../middleware/gallery');
+const { resolveGuest, requireGuest, signGuestToken } = require('../middleware/guestAuth');
+const feedbackService = require('../services/feedbackService');
+const guestRecovery = require('../services/guestRecoveryService');
+
+const MAX_NAME_LEN = 100;
+const MAX_EMAIL_LEN = 255;
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// In-memory rate limit for guest registration (20 per hour per IP). Simple
+// sliding window; on process restart the counters reset which is acceptable.
+const registrationAttempts = new Map();
+const REGISTRATION_WINDOW_MS = 60 * 60 * 1000;
+const REGISTRATION_MAX = 20;
+
+function checkRegistrationRate(ip) {
+  const now = Date.now();
+  const entry = registrationAttempts.get(ip) || { count: 0, windowStart: now };
+  if (now - entry.windowStart > REGISTRATION_WINDOW_MS) {
+    entry.count = 0;
+    entry.windowStart = now;
+  }
+  entry.count += 1;
+  registrationAttempts.set(ip, entry);
+  return entry.count <= REGISTRATION_MAX;
+}
+
+function sanitizeName(value) {
+  if (typeof value !== 'string') return '';
+  // Strip HTML/control chars, collapse whitespace.
+  const cleaned = value
+    .replace(/[<>&"']/g, '')
+    .replace(/[\u0000-\u001F\u007F]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return cleaned.slice(0, MAX_NAME_LEN);
+}
+
+function sanitizeEmail(value) {
+  if (typeof value !== 'string') return '';
+  return value.trim().slice(0, MAX_EMAIL_LEN).toLowerCase();
+}
+
+/**
+ * POST /gallery/:slug/guest
+ * Body: { name, email? }
+ *
+ * Registers a new per-person guest identity for this gallery. Returns a JWT
+ * that the frontend must send as the x-guest-token header on subsequent
+ * feedback requests.
+ */
+router.post('/:slug/guest', verifyGalleryAccess, async (req, res) => {
+  try {
+    const ip = req.ip || req.connection.remoteAddress || 'unknown';
+    if (!checkRegistrationRate(ip)) {
+      return res.status(429).json({ error: 'Too many registration attempts' });
+    }
+
+    const event = req.event;
+    const settings = await feedbackService.getEventFeedbackSettings(event.id);
+
+    // Guest registration is only meaningful when feedback is enabled.
+    if (!settings.feedback_enabled) {
+      return res.status(403).json({ error: 'Feedback is not enabled for this gallery' });
+    }
+
+    const name = sanitizeName(req.body?.name);
+    if (!name || name.length < 1) {
+      return res.status(400).json({ error: 'Name is required', field: 'name' });
+    }
+
+    let email = sanitizeEmail(req.body?.email);
+    if (email && !EMAIL_REGEX.test(email)) {
+      return res.status(400).json({ error: 'Invalid email format', field: 'email' });
+    }
+    if (settings.require_name_email && !email) {
+      return res.status(400).json({ error: 'Email is required', field: 'email' });
+    }
+
+    const identifier = crypto.randomUUID();
+    const userAgent = (req.headers['user-agent'] || '').substring(0, 500);
+
+    const [row] = await db('gallery_guests')
+      .insert({
+        event_id: event.id,
+        name,
+        email: email || null,
+        identifier,
+        ip_address_last: ip.substring(0, 45),
+        user_agent_last: userAgent,
+      })
+      .returning(['id', 'name', 'email', 'identifier', 'created_at']);
+
+    const token = signGuestToken({
+      guestId: row.id,
+      eventId: event.id,
+      identifier: row.identifier,
+      name: row.name,
+    });
+
+    logger.info('Guest registered', {
+      eventId: event.id,
+      guestId: row.id,
+      name: row.name,
+    });
+
+    return res.json({
+      guest: {
+        id: row.id,
+        name: row.name,
+        email: row.email,
+        identifier: row.identifier,
+      },
+      token,
+    });
+  } catch (error) {
+    logger.error('Guest registration failed', { error: error.message });
+    return res.status(500).json({ error: 'Failed to register guest' });
+  }
+});
+
+/**
+ * GET /gallery/:slug/guest/me
+ * Returns the current guest profile from a valid guest token. 401 otherwise.
+ */
+router.get('/:slug/guest/me', verifyGalleryAccess, resolveGuest, requireGuest, async (req, res) => {
+  try {
+    if (req.guest.eventId !== req.event.id) {
+      return res.status(403).json({ error: 'Guest token does not match gallery' });
+    }
+
+    // Update last_seen_at on each profile fetch (cheap and useful for admin).
+    await db('gallery_guests')
+      .where({ id: req.guest.id })
+      .update({
+        last_seen_at: db.fn.now(),
+        ip_address_last: (req.ip || '').substring(0, 45),
+        user_agent_last: (req.headers['user-agent'] || '').substring(0, 500),
+      });
+
+    return res.json({
+      guest: {
+        id: req.guest.id,
+        name: req.guest.name,
+        email: req.guest.email,
+        identifier: req.guest.identifier,
+      },
+    });
+  } catch (error) {
+    logger.error('Guest profile fetch failed', { error: error.message });
+    return res.status(500).json({ error: 'Failed to fetch guest profile' });
+  }
+});
+
+/**
+ * DELETE /gallery/:slug/guest/me
+ *
+ * "Forget me" — soft-deletes the guest row and anonymizes their feedback so
+ * aggregate counts remain stable but personal data is removed.
+ */
+router.delete('/:slug/guest/me', verifyGalleryAccess, resolveGuest, requireGuest, async (req, res) => {
+  try {
+    if (req.guest.eventId !== req.event.id) {
+      return res.status(403).json({ error: 'Guest token does not match gallery' });
+    }
+
+    await feedbackService.anonymizeGuestFeedback(req.guest.id);
+
+    await db('gallery_guests')
+      .where({ id: req.guest.id })
+      .update({
+        is_deleted: true,
+        name: 'Removed',
+        email: null,
+        last_seen_at: db.fn.now(),
+      });
+
+    logger.info('Guest self-forgot', {
+      eventId: req.event.id,
+      guestId: req.guest.id,
+    });
+
+    return res.json({ success: true });
+  } catch (error) {
+    logger.error('Guest forget-me failed', { error: error.message });
+    return res.status(500).json({ error: 'Failed to forget guest' });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Phase 3.2 — Email-based identity recovery
+// ---------------------------------------------------------------------------
+
+// Simple in-memory rate limit for recover/verify (5 per hour per IP).
+const recoveryAttempts = new Map();
+const VERIFY_WINDOW_MS = 60 * 60 * 1000;
+const VERIFY_MAX = 20;
+function checkRecoveryRate(ip) {
+  const now = Date.now();
+  const entry = recoveryAttempts.get(ip) || { count: 0, windowStart: now };
+  if (now - entry.windowStart > VERIFY_WINDOW_MS) {
+    entry.count = 0;
+    entry.windowStart = now;
+  }
+  entry.count += 1;
+  recoveryAttempts.set(ip, entry);
+  return entry.count <= VERIFY_MAX;
+}
+
+/**
+ * POST /gallery/:slug/guest/recover
+ * Body: { email }
+ *
+ * Sends a 6-digit code to the email if it matches an existing guest. Returns
+ * 200 regardless of whether a matching guest exists (prevents enumeration).
+ */
+router.post('/:slug/guest/recover', verifyGalleryAccess, async (req, res) => {
+  try {
+    const ip = req.ip || 'unknown';
+    if (!checkRecoveryRate(ip)) {
+      return res.status(429).json({ error: 'Too many recovery attempts' });
+    }
+
+    const email = sanitizeEmail(req.body?.email);
+    if (!email || !EMAIL_REGEX.test(email)) {
+      // Still return 200 to avoid leaking validity of the email field.
+      return res.json({ success: true });
+    }
+
+    const event = req.event;
+    const settings = await feedbackService.getEventFeedbackSettings(event.id);
+    if (!settings.feedback_enabled || settings.identity_mode !== 'guest') {
+      return res.json({ success: true });
+    }
+
+    const guest = await db('gallery_guests')
+      .where({ event_id: event.id, email, is_deleted: false })
+      .first();
+
+    if (guest) {
+      try {
+        const code = await guestRecovery.createCode(event.id, email);
+        await guestRecovery.sendRecoveryEmail(email, code, event.event_name || 'your gallery');
+      } catch (sendError) {
+        logger.error('Failed to send recovery email', { error: sendError.message });
+        // Still return 200 so clients can't distinguish failures.
+      }
+    }
+
+    return res.json({ success: true });
+  } catch (error) {
+    logger.error('Guest recovery request failed', { error: error.message });
+    return res.json({ success: true });
+  }
+});
+
+/**
+ * POST /gallery/:slug/guest/verify
+ * Body: { email, code }
+ *
+ * Exchanges a valid verification code for a guest token. Reuses the existing
+ * guest row associated with the email (the guest continues where they left
+ * off, cross-device).
+ */
+router.post('/:slug/guest/verify', verifyGalleryAccess, async (req, res) => {
+  try {
+    const ip = req.ip || 'unknown';
+    if (!checkRecoveryRate(ip)) {
+      return res.status(429).json({ error: 'Too many verification attempts' });
+    }
+
+    const email = sanitizeEmail(req.body?.email);
+    const code = String(req.body?.code || '').trim();
+    if (!email || !code) {
+      return res.status(400).json({ error: 'Email and code are required' });
+    }
+
+    const event = req.event;
+    const verifyResult = await guestRecovery.verifyCode(event.id, email, code);
+    if (!verifyResult.ok) {
+      return res.status(401).json({ error: 'Invalid or expired code', reason: verifyResult.reason });
+    }
+
+    const guest = await db('gallery_guests')
+      .where({ event_id: event.id, email, is_deleted: false })
+      .first();
+    if (!guest) {
+      return res.status(404).json({ error: 'Guest not found' });
+    }
+
+    await db('gallery_guests')
+      .where({ id: guest.id })
+      .update({
+        email_verified_at: guest.email_verified_at || db.fn.now(),
+        last_seen_at: db.fn.now(),
+        ip_address_last: (req.ip || '').substring(0, 45),
+      });
+
+    const token = signGuestToken({
+      guestId: guest.id,
+      eventId: event.id,
+      identifier: guest.identifier,
+      name: guest.name,
+    });
+
+    logger.info('Guest recovered via email', { eventId: event.id, guestId: guest.id });
+
+    return res.json({
+      guest: {
+        id: guest.id,
+        name: guest.name,
+        email: guest.email,
+        identifier: guest.identifier,
+      },
+      token,
+    });
+  } catch (error) {
+    logger.error('Guest verify failed', { error: error.message });
+    return res.status(500).json({ error: 'Failed to verify code' });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Phase 3.3 — Invite token redemption
+// ---------------------------------------------------------------------------
+
+/**
+ * POST /gallery/:slug/guest/redeem
+ * Body: { inviteToken }
+ *
+ * Redeems a pre-minted invite token (created by admin). Single use.
+ */
+router.post('/:slug/guest/redeem', verifyGalleryAccess, async (req, res) => {
+  try {
+    const inviteToken = String(req.body?.inviteToken || '').trim();
+    if (!inviteToken) {
+      return res.status(400).json({ error: 'Invite token required' });
+    }
+
+    const event = req.event;
+
+    const result = await db.transaction(async (trx) => {
+      const invite = await trx('guest_invites')
+        .where({ token: inviteToken, event_id: event.id })
+        .first();
+      if (!invite) return { error: 'not_found' };
+      if (invite.revoked_at) return { error: 'revoked' };
+      if (invite.redeemed_at) return { error: 'already_redeemed' };
+
+      const guest = await trx('gallery_guests')
+        .where({ id: invite.guest_id, is_deleted: false })
+        .first();
+      if (!guest) return { error: 'guest_missing' };
+
+      await trx('guest_invites')
+        .where({ id: invite.id })
+        .update({ redeemed_at: trx.fn.now() });
+
+      await trx('gallery_guests')
+        .where({ id: guest.id })
+        .update({
+          last_seen_at: trx.fn.now(),
+          ip_address_last: (req.ip || '').substring(0, 45),
+          user_agent_last: (req.headers['user-agent'] || '').substring(0, 500),
+        });
+
+      return { guest };
+    });
+
+    if (result.error) {
+      const statusMap = {
+        not_found: 404,
+        revoked: 410,
+        already_redeemed: 409,
+        guest_missing: 404,
+      };
+      return res.status(statusMap[result.error] || 400).json({ error: result.error });
+    }
+
+    const token = signGuestToken({
+      guestId: result.guest.id,
+      eventId: event.id,
+      identifier: result.guest.identifier,
+      name: result.guest.name,
+    });
+
+    logger.info('Invite redeemed', { eventId: event.id, guestId: result.guest.id });
+
+    return res.json({
+      guest: {
+        id: result.guest.id,
+        name: result.guest.name,
+        email: result.guest.email,
+        identifier: result.guest.identifier,
+      },
+      token,
+    });
+  } catch (error) {
+    logger.error('Invite redemption failed', { error: error.message });
+    return res.status(500).json({ error: 'Failed to redeem invite' });
+  }
+});
+
+module.exports = router;

backend/src/routes/protectedImages.js

@@ -1,11 +1,12 @@
 const express = require('express');
-const path = require('path');
 const { db } = require('../database/db');
 const { formatBoolean } = require('../utils/dbCompat');
 const { verifyGalleryAccess } = require('../middleware/gallery');
 const watermarkService = require('../services/watermarkService');
 const secureImageService = require('../services/secureImageService');
-const { getStoragePath } = require('../config/storage');
+const { getStorage } = require('../services/storage');
+const { resolvePhotoStorageKey, resolvePhotoFilePath } = require('../services/photoResolver');
+const { withLocalCopy } = require('../services/imageProcessor');
 const crypto = require('crypto');
 
 const router = express.Router();
@@ -98,11 +99,11 @@ router.get('/:slug/photo/:photoId/view', verifyGalleryAccess, async (req, res) =
       fragmentImage: eventProtectionLevel === 'maximum'
     };
 
-    // Build full path to photo
-    const photoPath = path.join(getStoragePath(), 'events/active', req.event.slug, photo.path);
+    // Resolve photo location through the storage backend (managed) or local
+    // disk (external reference mode).
+    const storageKey = resolvePhotoStorageKey(req.event, photo);
+    const storage = getStorage();
 
-    // For basic/standard protection without special features, serve original file
-    // This avoids unnecessary recompression
     const needsProcessing = eventProtectionLevel === 'enhanced' ||
                             eventProtectionLevel === 'maximum' ||
                             protectionSettings.addFingerprint;
@@ -110,15 +111,25 @@ router.get('/:slug/photo/:photoId/view', verifyGalleryAccess, async (req, res) =
     let finalImage;
 
     if (!needsProcessing) {
-      // Serve original file without processing
-      const fs = require('fs').promises;
-      finalImage = await fs.readFile(photoPath);
+      // Serve original bytes via the storage backend (or local disk for external).
+      if (storageKey) {
+        const stream = await storage.get(storageKey);
+        const chunks = [];
+        for await (const chunk of stream) chunks.push(chunk);
+        finalImage = Buffer.concat(chunks);
+      } else {
+        const fs = require('fs').promises;
+        finalImage = await fs.readFile(resolvePhotoFilePath(req.event, photo));
+      }
     } else {
-      // Process image with protection measures
-      const processedImage = await secureImageService.processProtectedImage(photoPath, protectionSettings);
+      // secureImageService.processProtectedImage operates on a local path.
+      // Materialize a tmp local copy in S3 mode, then run processing.
+      const runProcessing = (lp) => secureImageService.processProtectedImage(lp, protectionSettings);
+      const processedImage = storageKey
+        ? await withLocalCopy(storageKey, runProcessing)
+        : await runProcessing(resolvePhotoFilePath(req.event, photo));
 
       if (processedImage.type === 'fragmented') {
-        // Return fragmented image data for canvas reconstruction
         return res.json({
           type: 'fragmented',
           fragments: processedImage.fragments.map(f => ({
@@ -273,12 +284,13 @@ router.get('/:slug/photo/:photoId/signed/:token', async (req, res) => {
     
     // Get watermark settings
     const watermarkSettings = await watermarkService.getWatermarkSettings();
-    
-    // Build full path to photo
-    const photoPath = path.join(getStoragePath(), 'events/active', event.slug, photo.path);
-    
-    // Apply watermark if enabled
-    const imageBuffer = await watermarkService.applyWatermark(photoPath, watermarkSettings);
+
+    // Apply watermark — managed photos are sourced via the storage backend
+    // (S3 mode materializes a tmp local copy via withLocalCopy).
+    const storageKey = resolvePhotoStorageKey(event, photo);
+    const imageBuffer = storageKey
+      ? await withLocalCopy(storageKey, (lp) => watermarkService.applyWatermark(lp, watermarkSettings))
+      : await watermarkService.applyWatermark(resolvePhotoFilePath(event, photo), watermarkSettings);
     
     // Set appropriate headers
     res.set({

backend/src/routes/publicCMS.js

@@ -22,6 +22,9 @@ router.get('/pages/:slug', async (req, res) => {
       title,
       content,
       slug: page.slug,
+      // Per-page logo override (#324). Null means "fall back to global
+      // branding logo" — the consumer decides.
+      logo_url: page.logo_url || null,
       updated_at: page.updated_at
     });
   } catch (error) {

backend/src/routes/publicSettings.js

@@ -12,7 +12,13 @@ router.get('/', async (req, res) => {
         .where(function() {
           this.whereIn('setting_type', ['branding', 'theme', 'general', 'security', 'analytics', 'boolean'])
             .orWhere('setting_key', 'like', 'analytics_%')
-            .orWhere('setting_key', 'like', 'event_require_%');
+            .orWhere('setting_key', 'like', 'event_require_%')
+            .orWhereIn('setting_key', [
+              'seo_meta_noindex', 'seo_meta_nofollow', 'seo_meta_noai',
+              'event_default_require_password',
+              'gallery_show_filter_bar',
+              'event_phone_field_enabled'
+            ]);
         })
         .select('setting_key', 'setting_value');
     });
@@ -74,7 +80,21 @@ router.get('/', async (req, res) => {
       // Event field requirements
       event_require_customer_name: settingsObject.event_require_customer_name !== false,
       event_require_customer_email: settingsObject.event_require_customer_email !== false,
-      event_require_admin_email: settingsObject.event_require_admin_email !== false
+      event_require_admin_email: settingsObject.event_require_admin_email !== false,
+      event_require_event_date: settingsObject.event_require_event_date !== false,
+      event_require_expiration: settingsObject.event_require_expiration !== false,
+      // Default value for "Require password" toggle in event creation form
+      event_default_require_password: settingsObject.event_default_require_password !== false,
+      // Phone-number field on events is opt-in (#322).
+      event_phone_field_enabled: settingsObject.event_phone_field_enabled === true,
+      // Whether to show the search/sort filter bar in public galleries (default: true)
+      gallery_show_filter_bar: settingsObject.gallery_show_filter_bar !== false,
+      // Upload settings (safe to expose - needed for client-side validation)
+      allowed_file_types: settingsObject.general_allowed_file_types || 'jpg,jpeg,png,webp',
+      // SEO meta tag flags (safe to expose - these are intended for crawlers)
+      seo_meta_noindex: settingsObject.seo_meta_noindex === true,
+      seo_meta_nofollow: settingsObject.seo_meta_nofollow === true,
+      seo_meta_noai: settingsObject.seo_meta_noai === true
     };
 
     res.json(publicSettings);

backend/src/routes/secureImages.js

@@ -5,7 +5,9 @@ const secureImageService = require('../services/secureImageService');
 const secureImageMiddleware = require('../middleware/secureImageMiddleware');
 const logger = require('../utils/logger');
 const { formatBoolean } = require('../utils/dbCompat');
-const { resolvePhotoFilePath } = require('../services/photoResolver');
+const { resolvePhotoFilePath, resolvePhotoStorageKey } = require('../services/photoResolver');
+const { withLocalCopy } = require('../services/imageProcessor');
+const { getStorage } = require('../services/storage');
 
 const router = express.Router();
 
@@ -139,18 +141,10 @@ router.get('/:slug/secure/:photoId/:token',
         return res.status(404).json({ error: 'Photo not found' });
       }
 
-      let filePath;
-      try {
-        filePath = resolvePhotoFilePath(req.event, photo);
-      } catch (resolveError) {
-        logger.error('Failed to resolve photo path for secure token generation', {
-          slug: req.params.slug,
-          photoId,
-          eventId: req.event.id,
-          error: resolveError.message,
-        });
-        return res.status(404).json({ error: 'Photo file not found' });
-      }
+      // Resolve photo through storage backend (managed) or fall back to local
+      // path (external reference mode). secureImageService needs a local file,
+      // so we materialize a tmp copy via withLocalCopy in S3 mode.
+      const storageKey = resolvePhotoStorageKey(event, photo);
 
       // Get protection settings for this event
       const protectionSettings = {
@@ -160,11 +154,21 @@ router.get('/:slug/secure/:photoId/:token',
         fragmentImage: event.use_canvas_rendering === true && fragment !== undefined
       };
 
-      // Process image with protection measures
-      const processedImage = await secureImageService.processProtectedImage(
-        filePath,
-        protectionSettings
-      );
+      let processedImage;
+      try {
+        const runProcessing = (lp) => secureImageService.processProtectedImage(lp, protectionSettings);
+        processedImage = storageKey
+          ? await withLocalCopy(storageKey, runProcessing)
+          : await runProcessing(resolvePhotoFilePath(event, photo));
+      } catch (resolveError) {
+        logger.error('Failed to process secure image', {
+          slug: req.params.slug,
+          photoId,
+          eventId: event.id,
+          error: resolveError.message,
+        });
+        return res.status(404).json({ error: 'Photo file not found' });
+      }
 
       // Handle fragmented images
       if (processedImage.type === 'fragmented') {
@@ -292,11 +296,30 @@ router.get('/:slug/secure-download/:photoId/:token',
         return res.status(404).json({ error: 'Photo not found' });
       }
 
-      let filePath;
+      // Resolve photo through storage backend (managed) or local disk (external).
+      const storageKey = resolvePhotoStorageKey(req.event, photo);
+
+      const watermarkService = require('../services/watermarkService');
+      const watermarkSettings = await watermarkService.getWatermarkSettings();
+      const wantsWatermark = watermarkSettings && watermarkSettings.enabled;
+
+      let fileBuffer;
       try {
-        filePath = resolvePhotoFilePath(req.event, photo);
+        if (wantsWatermark) {
+          fileBuffer = storageKey
+            ? await withLocalCopy(storageKey, (lp) => watermarkService.applyWatermark(lp, watermarkSettings))
+            : await watermarkService.applyWatermark(resolvePhotoFilePath(req.event, photo), watermarkSettings);
+        } else if (storageKey) {
+          const stream = await getStorage().get(storageKey);
+          const chunks = [];
+          for await (const chunk of stream) chunks.push(chunk);
+          fileBuffer = Buffer.concat(chunks);
+        } else {
+          const fs = require('fs').promises;
+          fileBuffer = await fs.readFile(resolvePhotoFilePath(req.event, photo));
+        }
       } catch (resolveError) {
-        logger.error('Failed to resolve photo path for secure download', {
+        logger.error('Failed to fetch photo for secure download', {
           slug: req.params.slug,
           photoId,
           eventId: req.event.id,
@@ -305,18 +328,6 @@ router.get('/:slug/secure-download/:photoId/:token',
         return res.status(404).json({ error: 'Photo file not found' });
       }
 
-      // Apply watermark if enabled
-      const watermarkService = require('../services/watermarkService');
-      const watermarkSettings = await watermarkService.getWatermarkSettings();
-      
-      let fileBuffer;
-      if (watermarkSettings && watermarkSettings.enabled) {
-        fileBuffer = await watermarkService.applyWatermark(filePath, watermarkSettings);
-      } else {
-        const fs = require('fs').promises;
-        fileBuffer = await fs.readFile(filePath);
-      }
-
       // Update download count
       await db('photos').where('id', photoId).increment('download_count', 1);
 
@@ -350,34 +361,11 @@ router.get('/:slug/secure-download/:photoId/:token',
 /**
  * Get security statistics for monitoring
  */
-router.get('/security/stats', async (req, res) => {
-  try {
-    // Only allow admin access
-    const token = req.headers.authorization?.split(' ')[1];
-    if (!token) {
-      return res.status(401).json({ error: 'No token provided' });
-    }
+const { adminAuth } = require('../middleware/auth');
+const { requirePermission } = require('../middleware/permissions');
 
-    const jwt = require('jsonwebtoken');
-    // Try to verify with issuer first, fallback to no issuer for backward compatibility
-    let decoded;
-    try {
-      decoded = jwt.verify(token, process.env.JWT_SECRET, {
-        issuer: 'picpeak-auth'
-      });
-    } catch (issuerError) {
-      // If verification fails with issuer, try without issuer (backward compatibility)
-      if (issuerError.name === 'JsonWebTokenError' && issuerError.message.includes('jwt issuer invalid')) {
-        decoded = jwt.verify(token, process.env.JWT_SECRET);
-      } else {
-        throw issuerError;
-      }
-    }
-    const admin = await db('admin_users').where({ id: decoded.id }).first();
-    
-    if (!admin) {
-      return res.status(401).json({ error: 'Invalid token' });
-    }
+router.get('/security/stats', adminAuth, requirePermission('settings.view'), async (req, res) => {
+  try {
 
     // Get security statistics
     const stats = {

backend/src/routes/v1/events.js

@@ -0,0 +1,485 @@
+/**
+ * Public v1 API — events + photo upload + share link.
+ *
+ * Surface chosen for the n8n / automation use case (#322): create gallery,
+ * upload photos, get a share URL. Intentionally narrow — update/delete
+ * are admin-only via the UI for v1. Mounts under /api/v1 with apiTokenAuth.
+ *
+ * Each route is annotated with @openapi JSDoc that swagger-jsdoc picks
+ * up to generate docs/openapi.yaml (gitignored), which is then synced
+ * into the picpeak-docs site at docs.picpeak.app.
+ */
+
+const express = require('express');
+const path = require('path');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const crypto = require('crypto');
+const multer = require('multer');
+const sharp = require('sharp');
+const { body, query, validationResult } = require('express-validator');
+const { db, logActivity } = require('../../database/db');
+const { apiTokenAuth, requireApiScope } = require('../../middleware/apiTokenAuth');
+const { buildShareLinkVariants } = require('../../services/shareLinkService');
+const { generateThumbnail } = require('../../services/imageProcessor');
+const logger = require('../../utils/logger');
+
+const router = express.Router();
+
+const getStoragePath = () => process.env.STORAGE_PATH || path.join(__dirname, '../../../../storage');
+
+// ──────────────────────────────────────────────────────────────────────────
+// Multer for single-photo upload. Lean — no replace-by-name, no batching.
+// ──────────────────────────────────────────────────────────────────────────
+const photoStorage = multer.diskStorage({
+  destination: async (_req, _file, cb) => {
+    const tempDir = path.join(getStoragePath(), 'temp');
+    await fs.mkdir(tempDir, { recursive: true });
+    cb(null, tempDir);
+  },
+  filename: (_req, file, cb) => {
+    const ext = path.extname(file.originalname);
+    cb(null, `v1_${Date.now()}_${crypto.randomBytes(4).toString('hex')}${ext}`);
+  }
+});
+const photoUpload = multer({
+  storage: photoStorage,
+  limits: { fileSize: 100 * 1024 * 1024 }, // 100MB per file for v1
+  fileFilter: (_req, file, cb) => {
+    if (/^image\//.test(file.mimetype)) cb(null, true);
+    else cb(new Error('Only image uploads are accepted on this endpoint'));
+  }
+});
+
+const slugify = (s) =>
+  String(s).toLowerCase().replace(/[^a-z0-9]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+
+// ──────────────────────────────────────────────────────────────────────────
+// POST /events — create event
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * @openapi
+ * /events:
+ *   post:
+ *     tags: [Events]
+ *     summary: Create a gallery event
+ *     description: Returns the new event's id, slug, and absolute share URL.
+ *     security: [{ bearerAuth: [] }]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [event_name, event_type]
+ *             properties:
+ *               event_name: { type: string }
+ *               event_type:
+ *                 type: string
+ *                 enum: [wedding, birthday, corporate, other, family]
+ *               event_date: { type: string, format: date, nullable: true }
+ *               customer_name: { type: string, nullable: true }
+ *               customer_email: { type: string, format: email, nullable: true }
+ *               customer_phone: { type: string, nullable: true, description: "Only persisted when the global phone-field setting is enabled." }
+ *               admin_email: { type: string, format: email, nullable: true }
+ *               require_password: { type: boolean, default: true }
+ *               password: { type: string, nullable: true, description: "Required when require_password is true." }
+ *               expires_at: { type: string, format: date-time, nullable: true }
+ *     responses:
+ *       201:
+ *         description: Event created
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 id: { type: integer }
+ *                 slug: { type: string }
+ *                 share_url: { type: string, format: uri }
+ *                 share_token: { type: string }
+ *       400: { description: Validation error }
+ *       401: { description: Missing/invalid token }
+ *       403: { description: Token lacks admin scope }
+ */
+router.post(
+  '/events',
+  apiTokenAuth,
+  requireApiScope('admin'),
+  [
+    body('event_name').isString().trim().notEmpty(),
+    body('event_type').isIn(['wedding', 'birthday', 'corporate', 'other', 'family']),
+    body('event_date').optional({ nullable: true, checkFalsy: true }).isISO8601(),
+    body('customer_name').optional({ nullable: true }).isString(),
+    body('customer_email').optional({ nullable: true, checkFalsy: true }).isEmail(),
+    body('customer_phone').optional({ nullable: true, checkFalsy: true }).isString().isLength({ max: 32 }),
+    body('admin_email').optional({ nullable: true, checkFalsy: true }).isEmail(),
+    body('require_password').optional().isBoolean(),
+    body('password').optional({ nullable: true }).isString().isLength({ min: 6 }),
+    body('expires_at').optional({ nullable: true, checkFalsy: true }).isISO8601()
+  ],
+  async (req, res) => {
+    try {
+      const errors = validationResult(req);
+      if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() });
+      const {
+        event_name, event_type, event_date,
+        customer_name = null, customer_email = null, customer_phone = null,
+        admin_email = null, require_password = true, password,
+        expires_at = null
+      } = req.body;
+
+      if (require_password && (!password || password.length < 6)) {
+        return res.status(400).json({ error: 'Password is required when require_password is true (min 6 chars)' });
+      }
+
+      // Honour global phone-field toggle (#322).
+      let persistPhone = null;
+      if (customer_phone) {
+        const setting = await db('app_settings').where('setting_key', 'event_phone_field_enabled').first();
+        const enabled = setting ? JSON.parse(setting.setting_value) === true : false;
+        persistPhone = enabled ? customer_phone : null;
+      }
+
+      // Generate unique slug.
+      const baseSlug = `${event_type}-${slugify(event_name)}-${event_date || crypto.randomBytes(3).toString('hex')}`;
+      let slug = baseSlug;
+      let counter = 1;
+      while (await db('events').where({ slug }).first()) slug = `${baseSlug}-${counter++}`;
+
+      const shareToken = crypto.randomBytes(16).toString('hex');
+      const { shareUrl, shareLinkToStore } = await buildShareLinkVariants({ slug, shareToken });
+
+      // password_hash is NOT NULL; use a random placeholder when no
+      // password is required so the column constraint is satisfied.
+      const bcrypt = require('bcrypt');
+      const passwordHash = require_password
+        ? await bcrypt.hash(password, 10)
+        : await bcrypt.hash(crypto.randomBytes(32).toString('hex'), 10);
+
+      const insertResult = await db('events').insert({
+        slug,
+        event_type,
+        event_name,
+        event_date: event_date || null,
+        host_name: customer_name,
+        host_email: customer_email,
+        admin_email,
+        password_hash: passwordHash,
+        require_password,
+        share_link: shareLinkToStore,
+        share_token: shareToken,
+        expires_at: expires_at || null,
+        created_at: new Date().toISOString(),
+        created_by: req.admin.id,
+        is_draft: false,
+        ...(customer_name ? { customer_name } : {}),
+        ...(customer_email ? { customer_email } : {}),
+        ...(persistPhone ? { customer_phone: persistPhone } : {})
+      }).returning('id');
+      const id = insertResult[0]?.id || insertResult[0];
+
+      await logActivity('event_created', { via: 'api_v1', event_type }, id, {
+        type: 'admin', id: req.admin.id, name: req.admin.username
+      });
+
+      // Webhook lifecycle (#327). v1 events are not draft-aware, so they're
+      // both created AND published in the same call. Canonical event
+      // subject (#341) — customer contact + share_token always included.
+      try {
+        const webhookService = require('../../services/webhookService');
+        const eventSubject = webhookService.buildEventSubject({
+          id,
+          slug,
+          event_name,
+          event_type,
+          event_date,
+          share_url: shareUrl,
+          share_token: shareToken,
+          customer_name,
+          customer_email,
+          customer_phone,
+        });
+        await webhookService.fire('event.created', { event: eventSubject });
+        await webhookService.fire('event.published', { event: eventSubject });
+      } catch (e) { /* non-fatal */ }
+
+      res.status(201).json({ id, slug, share_url: shareUrl, share_token: shareToken });
+    } catch (error) {
+      logger.error('v1 POST /events failed', { error: error.message, stack: error.stack });
+      res.status(500).json({ error: 'Failed to create event', detail: error.message });
+    }
+  }
+);
+
+// ──────────────────────────────────────────────────────────────────────────
+// GET /events — list
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * @openapi
+ * /events:
+ *   get:
+ *     tags: [Events]
+ *     summary: List gallery events (paginated)
+ *     security: [{ bearerAuth: [] }]
+ *     parameters:
+ *       - in: query
+ *         name: page
+ *         schema: { type: integer, minimum: 1, default: 1 }
+ *       - in: query
+ *         name: limit
+ *         schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
+ *     responses:
+ *       200:
+ *         description: Paginated list
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 events:
+ *                   type: array
+ *                   items: { $ref: '#/components/schemas/EventSummary' }
+ *                 pagination:
+ *                   type: object
+ *                   properties:
+ *                     page: { type: integer }
+ *                     limit: { type: integer }
+ *                     total: { type: integer }
+ */
+router.get(
+  '/events',
+  apiTokenAuth,
+  requireApiScope('read'),
+  [
+    query('page').optional().isInt({ min: 1 }).toInt(),
+    query('limit').optional().isInt({ min: 1, max: 100 }).toInt()
+  ],
+  async (req, res) => {
+    try {
+      const page = req.query.page || 1;
+      const limit = req.query.limit || 25;
+      const offset = (page - 1) * limit;
+
+      const [events, totalRow] = await Promise.all([
+        db('events')
+          .select('id', 'slug', 'event_name', 'event_type', 'event_date', 'expires_at',
+            'is_active', 'is_archived', 'is_draft', 'created_at')
+          .orderBy('created_at', 'desc')
+          .limit(limit)
+          .offset(offset),
+        db('events').count('id as count').first()
+      ]);
+      const total = parseInt(totalRow?.count || 0, 10);
+      res.json({ events, pagination: { page, limit, total } });
+    } catch (error) {
+      logger.error('v1 GET /events failed', { error: error.message });
+      res.status(500).json({ error: 'Failed to list events' });
+    }
+  }
+);
+
+// ──────────────────────────────────────────────────────────────────────────
+// GET /events/:id — read
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * @openapi
+ * /events/{id}:
+ *   get:
+ *     tags: [Events]
+ *     summary: Get a single event
+ *     security: [{ bearerAuth: [] }]
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema: { type: integer }
+ *     responses:
+ *       200: { description: Event details }
+ *       404: { description: Not found }
+ */
+router.get('/events/:id', apiTokenAuth, requireApiScope('read'), async (req, res) => {
+  try {
+    const event = await db('events').where({ id: req.params.id }).first();
+    if (!event) return res.status(404).json({ error: 'Event not found' });
+    delete event.password_hash;
+    delete event.client_password_hash;
+    res.json(event);
+  } catch (error) {
+    logger.error('v1 GET /events/:id failed', { error: error.message });
+    res.status(500).json({ error: 'Failed to fetch event' });
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// POST /events/:id/photos — upload one photo
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * @openapi
+ * /events/{id}/photos:
+ *   post:
+ *     tags: [Photos]
+ *     summary: Upload a single photo to an event
+ *     security: [{ bearerAuth: [] }]
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema: { type: integer }
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         multipart/form-data:
+ *           schema:
+ *             type: object
+ *             required: [photo]
+ *             properties:
+ *               photo: { type: string, format: binary }
+ *     responses:
+ *       201:
+ *         description: Photo uploaded
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 id: { type: integer }
+ *                 filename: { type: string }
+ *                 path: { type: string }
+ *                 thumbnail_path: { type: string, nullable: true }
+ *                 size_bytes: { type: integer }
+ *       400: { description: No file or invalid type }
+ *       404: { description: Event not found }
+ */
+router.post(
+  '/events/:id/photos',
+  apiTokenAuth,
+  requireApiScope('write'),
+  photoUpload.single('photo'),
+  async (req, res) => {
+    let tempPath = null;
+    try {
+      if (!req.file) return res.status(400).json({ error: 'No file uploaded under field "photo"' });
+      tempPath = req.file.path;
+
+      const event = await db('events').where({ id: req.params.id }).first();
+      if (!event) return res.status(404).json({ error: 'Event not found' });
+
+      const ext = path.extname(req.file.originalname);
+      const finalName = `${Date.now()}_${crypto.randomBytes(4).toString('hex')}${ext}`;
+      // photo.path is stored relative to events/active so resolvePhotoStorageKey
+      // can rebuild the full key on read. Same shape as adminPhotos uploads.
+      const relPath = path.posix.join(event.slug, finalName);
+      const finalKey = path.posix.join('events/active', relPath);
+
+      const stat = fsSync.statSync(tempPath);
+
+      // Read sharp metadata + generate thumbnail FROM the local temp file
+      // before uploading the original through the storage backend. (Same
+      // ordering as adminPhotos.js so sharp/ffmpeg always have a real fs path.)
+      let width = null;
+      let height = null;
+      try {
+        const meta = await sharp(tempPath).metadata();
+        width = meta.width || null;
+        height = meta.height || null;
+      } catch { /* non-fatal */ }
+
+      let thumbRel = null;
+      try {
+        thumbRel = await generateThumbnail(tempPath);
+      } catch (err) {
+        logger.warn('v1 thumbnail generation failed', { err: err.message });
+      }
+
+      // Upload the original via the storage backend (local fs OR S3),
+      // then drop the multer temp file.
+      const { getStorage } = require('../../services/storage');
+      await getStorage().putFromFile(finalKey, tempPath, { contentType: req.file.mimetype });
+      await fs.unlink(tempPath).catch(() => {});
+      tempPath = null;
+
+      const insertResult = await db('photos').insert({
+        event_id: event.id,
+        filename: finalName,
+        original_filename: req.file.originalname,
+        path: relPath,
+        thumbnail_path: thumbRel,
+        type: 'individual',
+        size_bytes: stat.size,
+        width,
+        height,
+        media_type: 'image',
+        mime_type: req.file.mimetype,
+        uploaded_at: new Date().toISOString()
+      }).returning('id');
+      const id = insertResult[0]?.id || insertResult[0];
+
+      await logActivity('photo_uploaded', { via: 'api_v1', filename: finalName }, event.id, {
+        type: 'admin', id: req.admin.id, name: req.admin.username
+      });
+
+      // Webhook (#327): one event per uploaded photo so receivers get a
+      // 1:1 stream they can react to.
+      try {
+        const webhookService = require('../../services/webhookService');
+        await webhookService.fire('photo.uploaded', {
+          event: { id: event.id, slug: event.slug, event_name: event.event_name },
+          photo: { id, filename: finalName, original_filename: req.file.originalname, size_bytes: stat.size, width, height },
+        });
+      } catch (e) { /* non-fatal */ }
+
+      res.status(201).json({ id, filename: finalName, path: relPath, thumbnail_path: thumbRel, size_bytes: stat.size });
+    } catch (error) {
+      logger.error('v1 POST /events/:id/photos failed', { error: error.message });
+      if (tempPath) await fs.unlink(tempPath).catch(() => {});
+      res.status(500).json({ error: 'Failed to upload photo' });
+    }
+  }
+);
+
+// ──────────────────────────────────────────────────────────────────────────
+// GET /events/:id/share-link — full URL for sending to guests
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * @openapi
+ * /events/{id}/share-link:
+ *   get:
+ *     tags: [Events]
+ *     summary: Get the absolute share URL for an event
+ *     security: [{ bearerAuth: [] }]
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema: { type: integer }
+ *     responses:
+ *       200:
+ *         description: Share URL
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 slug: { type: string }
+ *                 share_token: { type: string }
+ *                 share_url: { type: string, format: uri }
+ *       404: { description: Not found }
+ */
+router.get('/events/:id/share-link', apiTokenAuth, requireApiScope('read'), async (req, res) => {
+  try {
+    const event = await db('events').where({ id: req.params.id }).first();
+    if (!event) return res.status(404).json({ error: 'Event not found' });
+    const { shareUrl } = await buildShareLinkVariants({ slug: event.slug, shareToken: event.share_token });
+    res.json({ slug: event.slug, share_token: event.share_token, share_url: shareUrl });
+  } catch (error) {
+    logger.error('v1 GET /events/:id/share-link failed', { error: error.message });
+    res.status(500).json({ error: 'Failed to build share link' });
+  }
+});
+
+module.exports = router;

backend/src/services/archiveService.js

@@ -1,57 +1,47 @@
 const archiver = require('archiver');
-const fs = require('fs').promises;
+const fs = require('fs');
+const fsp = require('fs').promises;
 const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
 const { db } = require('../database/db');
 const { queueEmail } = require('./emailProcessor');
 const logger = require('../utils/logger');
 const feedbackService = require('./feedbackService');
-
-const getStoragePath = () => process.env.STORAGE_PATH || path.join(__dirname, '../../../storage');
-const ACTIVE_PATH = () => path.join(getStoragePath(), 'events/active');
-const ARCHIVE_PATH = () => path.join(getStoragePath(), 'events/archived');
+const { getStorage } = require('./storage');
 
 async function archiveEvent(event) {
+  const storage = getStorage();
+  const archiveName = `${event.slug}.zip`;
+  const archiveRelKey = path.posix.join('events/archived', archiveName);
+  const eventPrefix = path.posix.join('events/active', event.slug);
+
+  const tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'picpeak-archive-'));
+  const tmpArchive = path.join(tmpDir, `${crypto.randomBytes(4).toString('hex')}-${archiveName}`);
+
   try {
-    const eventPath = path.join(ACTIVE_PATH(), event.slug);
-    const archiveName = `${event.slug}.zip`;
-    const archivePath = path.join(ARCHIVE_PATH(), archiveName);
-    
-    // Ensure archive directory exists
-    await fs.mkdir(ARCHIVE_PATH(), { recursive: true });
-    
-    // Create archive
-    const output = require('fs').createWriteStream(archivePath);
-    const archive = archiver('zip', {
-      zlib: { level: 9 } // Maximum compression
-    });
-    
-    archive.on('error', (err) => {
-      throw err;
-    });
-    
-    // Export feedback data before archiving
+    // Collect feedback data first so it can be included as in-memory entries.
+    const feedbackEntries = [];
     const feedbackSettings = await feedbackService.getEventFeedbackSettings(event.id);
     if (feedbackSettings.feedback_enabled) {
       try {
         logger.info(`Exporting feedback data for event ${event.slug}`);
         const feedbackData = await feedbackService.exportEventFeedback(event.id);
-        
+
         if (feedbackData && feedbackData.length > 0) {
-          // Create feedback JSON file
-          const feedbackJson = JSON.stringify(feedbackData, null, 2);
-          const feedbackJsonPath = path.join(eventPath, 'feedback_data.json');
-          await fs.writeFile(feedbackJsonPath, feedbackJson, 'utf8');
-          
-          // Create feedback CSV file
-          const feedbackCsv = convertToCSV(feedbackData);
-          const feedbackCsvPath = path.join(eventPath, 'feedback_data.csv');
-          await fs.writeFile(feedbackCsvPath, feedbackCsv, 'utf8');
-          
-          // Create feedback summary
+          feedbackEntries.push({
+            name: 'feedback_data.json',
+            buffer: Buffer.from(JSON.stringify(feedbackData, null, 2), 'utf8'),
+          });
+          feedbackEntries.push({
+            name: 'feedback_data.csv',
+            buffer: Buffer.from(convertToCSV(feedbackData), 'utf8'),
+          });
           const summary = await feedbackService.getEventFeedbackSummary(event.id);
-          const summaryPath = path.join(eventPath, 'feedback_summary.json');
-          await fs.writeFile(summaryPath, JSON.stringify(summary, null, 2), 'utf8');
-          
+          feedbackEntries.push({
+            name: 'feedback_summary.json',
+            buffer: Buffer.from(JSON.stringify(summary, null, 2), 'utf8'),
+          });
           logger.info(`Feedback data exported: ${feedbackData.length} entries`);
         }
       } catch (error) {
@@ -59,53 +49,126 @@ async function archiveEvent(event) {
         // Continue with archiving even if feedback export fails
       }
     }
-    
-    output.on('close', async () => {
-      logger.info(`Archive created: ${archiveName} (${archive.pointer()} bytes)`);
-      
-      // Update database
-      await db('events').where('id', event.id).update({
-        is_archived: true,
-        archive_path: path.relative(getStoragePath(), archivePath),
-        archived_at: new Date()
+
+    // Stream every photo (and any other content under events/active/{slug}/) into
+    // the zip directly from the storage backend.
+    const photoEntries = await storage.list(eventPrefix);
+
+    let totalBytes = 0;
+    await new Promise((resolve, reject) => {
+      const output = fs.createWriteStream(tmpArchive);
+      const archive = archiver('zip', { zlib: { level: 9 } });
+
+      output.on('close', () => {
+        totalBytes = archive.pointer();
+        resolve();
       });
-      
-      // Delete original files
-      await fs.rm(eventPath, { recursive: true });
-      
-      // Delete thumbnails
-      const photos = await db('photos').where('event_id', event.id);
-      for (const photo of photos) {
-        if (photo.thumbnail_path) {
-          const thumbPath = path.join(getStoragePath(), photo.thumbnail_path);
-          await fs.unlink(thumbPath).catch(() => {}); // Ignore if already deleted
+      archive.on('error', reject);
+      archive.pipe(output);
+
+      const append = async () => {
+        for (const entry of photoEntries) {
+          const nameInZip = entry.key.startsWith(`${eventPrefix}/`)
+            ? entry.key.slice(eventPrefix.length + 1)
+            : entry.key;
+          const stream = await storage.get(entry.key);
+          archive.append(stream, { name: nameInZip });
         }
+        for (const f of feedbackEntries) {
+          archive.append(f.buffer, { name: f.name });
+        }
+        archive.finalize();
+      };
+
+      append().catch(reject);
+    });
+
+    // Upload the finalized zip to the storage backend.
+    await storage.putFromFile(archiveRelKey, tmpArchive, { contentType: 'application/zip' });
+
+    logger.info(`Archive created: ${archiveName} (${totalBytes} bytes)`);
+
+    // Update DB BEFORE deleting originals so a crash mid-cleanup leaves the
+    // archive accessible rather than orphaning the photos.
+    await db('events').where('id', event.id).update({
+      is_archived: true,
+      archive_path: archiveRelKey,
+      archived_at: new Date(),
+    });
+
+    // Fire event.archived webhook (#327). Receivers infer per-photo loss
+    // from this event — we deliberately do NOT fire photo.deleted for each
+    // archived photo to avoid flooding subscribers on bulk archives.
+    // Canonical event subject (#341) so the shape matches event.created /
+    // event.published / event.expired; archive_path is an event.archived-
+    // specific extra.
+    try {
+      const webhookService = require('./webhookService');
+      await webhookService.fire('event.archived', {
+        event: {
+          ...webhookService.buildEventSubject({
+            id: event.id,
+            slug: event.slug,
+            event_name: event.event_name,
+            event_type: event.event_type,
+            event_date: event.event_date,
+            share_token: event.share_token,
+            customer_name: event.customer_name || event.host_name,
+            customer_email: event.customer_email || event.host_email,
+            customer_phone: event.customer_phone,
+          }),
+          archive_path: archiveRelKey,
+        },
+      });
+    } catch (e) { /* non-fatal */ }
+
+    // Delete the originals from storage.
+    for (const entry of photoEntries) {
+      await storage.delete(entry.key).catch((err) =>
+        logger.warn(`Failed to delete archived original ${entry.key}: ${err.message}`)
+      );
+    }
+
+    // Delete thumbnails for this event's photos.
+    const photos = await db('photos').where('event_id', event.id);
+    for (const photo of photos) {
+      if (photo.thumbnail_path) {
+        await storage.delete(photo.thumbnail_path).catch(() => {});
       }
-      
-      // Queue completion email
+      if (photo.hero_path) {
+        await storage.delete(photo.hero_path).catch(() => {});
+      }
+      // Best effort: remove watermarked variants too if a refactor added them.
+      if (photo.watermark_path) {
+        await storage.delete(photo.watermark_path).catch(() => {});
+      }
+    }
+
+    // Queue completion email — admin_email is nullable on events (migration 073);
+    // skip queueing rather than violating email_queue.recipient_email NOT NULL.
+    if (event.admin_email) {
       await queueEmail(event.id, event.admin_email, 'archive_complete', {
         event_name: event.event_name,
-        archive_size: (archive.pointer() / 1024 / 1024).toFixed(2) + ' MB'
+        archive_size: (totalBytes / 1024 / 1024).toFixed(2) + ' MB',
       });
-    });
-    
-    archive.pipe(output);
-    archive.directory(eventPath, false);
-    await archive.finalize();
-    
+    } else {
+      logger.info(`Skipping archive_complete email for event ${event.slug}: no admin_email set`);
+    }
   } catch (error) {
     logger.error(`Error archiving event ${event.slug}:`, error);
     throw error;
+  } finally {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
   }
 }
 
 // Helper function to convert JSON to CSV
 function convertToCSV(data) {
   if (!data || data.length === 0) return '';
-  
+
   const headers = Object.keys(data[0]);
   const csvHeaders = headers.join(',');
-  
+
   const csvRows = data.map(row => {
     return headers.map(header => {
       const value = row[header];
@@ -116,7 +179,7 @@ function convertToCSV(data) {
       return value || '';
     }).join(',');
   });
-  
+
   return [csvHeaders, ...csvRows].join('\n');
 }
 

backend/src/services/backupManifest.js

@@ -181,8 +181,13 @@ class BackupManifestGenerator {
       const content = await fs.readFile(filePath, 'utf8');
       let manifest;
 
-      // Detect format and parse
-      if (filePath.endsWith('.yaml') || filePath.endsWith('.yml')) {
+      // Detect format from BOTH the extension and the content. Earlier code
+      // trusted the extension alone, which broke when callers stored a YAML
+      // manifest under a .json temp name (getBackupManifest does this when
+      // downloading the s3:// path to a tmp file).
+      const looksLikeJson = content.trimStart().startsWith('{')
+        || content.trimStart().startsWith('[');
+      if (filePath.endsWith('.yaml') || filePath.endsWith('.yml') || !looksLikeJson) {
         manifest = yaml.load(content);
       } else {
         manifest = JSON.parse(content);
@@ -318,6 +323,12 @@ class BackupManifestGenerator {
       deleted_files: comparison.deleted_files.map(f => f.path)
     };
 
+    // Recalculate the checksum after attaching the incremental section,
+    // otherwise validateManifest() rejects the loaded manifest because
+    // generateManifest() stamped a checksum that did NOT include this
+    // section.
+    fullManifest.verification.total_checksum = this.calculateManifestChecksum(fullManifest);
+
     return fullManifest;
   }
 

backend/src/services/backupService.js

@@ -268,6 +268,15 @@ async function getDatabaseBackupInfoInternal() {
 
     if (recent && recent.file_path) {
       const hasChanged = await hasDatabaseChanged(recent.completed_at);
+      // Postgres jsonb columns come back already parsed; sqlite TEXT comes
+      // back as a JSON string. Accept both.
+      const parseField = (v) => {
+        if (v == null) return null;
+        if (typeof v === 'object') return v;
+        try { return JSON.parse(v); } catch { return null; }
+      };
+      const stats = parseField(recent.statistics);
+      const checksums = parseField(recent.table_checksums);
       return {
         type: recent.backup_type || 'unknown',
         backupFile: recent.file_path,
@@ -275,8 +284,8 @@ async function getDatabaseBackupInfoInternal() {
         checksum: recent.checksum,
         hasChanged,
         backupTime: recent.completed_at,
-        tables: recent.statistics ? JSON.parse(recent.statistics).tables : {},
-        rowCounts: recent.table_checksums ? JSON.parse(recent.table_checksums) : {}
+        tables: (stats && stats.tables) || {},
+        rowCounts: checksums || {}
       };
     }
 
@@ -437,29 +446,63 @@ async function performLocalBackup(config, files) {
   };
 }
 
-function buildRsyncCommand(config) {
+function validateRsyncParam(value, label) {
+  if (!value || typeof value !== 'string') return null;
+  if (!/^[a-zA-Z0-9._\/@:-]+$/.test(value)) {
+    throw new Error(`Invalid ${label}: contains disallowed characters`);
+  }
+  if (value.length > 1024) {
+    throw new Error(`Invalid ${label}: too long`);
+  }
+  return value;
+}
+
+function buildRsyncArgs(config) {
   const storagePath = getStoragePath();
-  const host = config.backup_rsync_host;
-  const remotePath = config.backup_rsync_path;
+  const host = validateRsyncParam(config.backup_rsync_host, 'host');
+  const remotePath = validateRsyncParam(config.backup_rsync_path, 'remote path');
 
   if (!host || !remotePath) {
     throw new Error('Rsync configuration incomplete');
   }
 
-  const options = ['-avz', '--delete', '--stats'];
+  // Validate host format (hostname or IP only)
+  const hostRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$/;
+  const ipRegex = /^(\d{1,3}\.){3}\d{1,3}$/;
+  if (!hostRegex.test(host) && !ipRegex.test(host)) {
+    throw new Error('Invalid rsync host format');
+  }
+
+  const args = ['-avz', '--delete', '--stats'];
   if (config.backup_rsync_ssh_key) {
-    options.push(`-e "ssh -i ${config.backup_rsync_ssh_key} -o StrictHostKeyChecking=no"`);
+    const sshKey = validateRsyncParam(config.backup_rsync_ssh_key, 'SSH key path');
+    const fs = require('fs');
+    if (!fs.existsSync(sshKey) || !fs.statSync(sshKey).isFile()) {
+      throw new Error('SSH key file not found or is not a file');
+    }
+    // Pass SSH options as separate array elements to avoid shell interpretation
+    args.push('-e', `ssh -i ${sshKey} -o StrictHostKeyChecking=no`);
   }
 
   const excludePatterns = config.backup_exclude_patterns || [];
-  excludePatterns.forEach(pattern => options.push(`--exclude="${pattern}"`));
+  excludePatterns.forEach(pattern => args.push('--exclude', pattern));
 
   const source = `${storagePath}/`;
-  const destination = config.backup_rsync_user
-    ? `${config.backup_rsync_user}@${host}:${remotePath}`
+
+  const user = config.backup_rsync_user;
+  if (user) {
+    validateRsyncParam(user, 'user');
+    if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(user)) {
+      throw new Error('Invalid rsync username format');
+    }
+  }
+
+  const destination = user
+    ? `${user}@${host}:${remotePath}`
     : `${host}:${remotePath}`;
 
-  return `rsync ${options.join(' ')} "${source}" "${destination}"`;
+  args.push(source, destination);
+  return args;
 }
 
 function parseRsyncStats(output) {
@@ -479,9 +522,9 @@ function parseRsyncStats(output) {
 }
 
 async function performRsyncBackup(config, files) {
-  const command = buildRsyncCommand(config);
-  const execAsync = getExecAsync();
-  const { stdout } = await execAsync(command);
+  const { spawnAsync } = require('../utils/safeExec');
+  const rsyncArgs = buildRsyncArgs(config);
+  const { stdout } = await spawnAsync('rsync', rsyncArgs);
   const stats = parseRsyncStats(stdout);
 
   const backedUpFiles = files.map(file => file.relativePath);
@@ -503,8 +546,7 @@ async function performRsyncBackup(config, files) {
     backedUpCount: typeof stats.filesTransferred === 'number' ? stats.filesTransferred : backedUpFiles.length,
     backedUpSize: totalSize,
     backedUpFiles,
-    backupPath: `${config.backup_rsync_host}:${config.backup_rsync_path}`,
-    rsyncCommand: command
+    backupPath: `${config.backup_rsync_host}:${config.backup_rsync_path}`
   };
 }
 
@@ -793,7 +835,7 @@ async function runBackupInternal(isManual = false) {
       let manifest = await backupManifest.generateManifest(manifestOptions);
       if (previousBackup && previousBackup.manifest_path) {
         try {
-          const parentManifest = await backupManifest.loadManifest(previousBackup.manifest_path);
+          const parentManifest = await loadManifestFromAnywhere(previousBackup.manifest_path, config);
           manifest = await backupManifest.generateIncrementalManifest(manifestOptions, parentManifest);
         } catch (error) {
           logger.warn('Failed to load parent manifest, generating full manifest:', error);
@@ -903,17 +945,41 @@ async function startBackupService() {
       backupJob = null;
     }
 
+    // Two settings cooperate here:
+    //   - backup_schedule           — UI label like "daily" / "weekly" / "custom"
+    //   - backup_schedule_cron      — actual cron expression
+    // The frontend writes both (BackupConfiguration.jsx). Older startup code
+    // here read backup_schedule and crashed when it found a label instead of
+    // a cron expression. Resolution order: explicit cron field, then map known
+    // labels, then fall back to default.
+    const NAMED_SCHEDULES = {
+      hourly: '0 * * * *',
+      daily: '0 2 * * *',
+      weekly: '0 3 * * 0',  // Sunday 03:00
+      monthly: '0 4 1 * *',
+    };
+    const isCronExpression = (s) => typeof s === 'string' && /^\s*\S+(\s+\S+){4}\s*$/.test(s);
+    const readSetting = (key) => {
+      if (config && Object.prototype.hasOwnProperty.call(config, key)) {
+        return String(config[key] ?? '').trim();
+      }
+      if (config?.__raw && Object.prototype.hasOwnProperty.call(config.__raw, key)) {
+        return String(parseSettingValue(config.__raw[key]) ?? '').trim();
+      }
+      return '';
+    };
+
     let schedule = '0 2 * * *';
-    if (Object.prototype.hasOwnProperty.call(config, 'backup_schedule')) {
-      const candidate = String(config.backup_schedule ?? '').trim();
-      if (candidate.length) {
-        schedule = candidate;
-      }
-    } else if (config.__raw && Object.prototype.hasOwnProperty.call(config.__raw, 'backup_schedule')) {
-      const candidate = String(parseSettingValue(config.__raw.backup_schedule) ?? '').trim();
-      if (candidate.length) {
-        schedule = candidate;
-      }
+    const cronCandidate = readSetting('backup_schedule_cron');
+    const labelCandidate = readSetting('backup_schedule');
+    if (cronCandidate && isCronExpression(cronCandidate)) {
+      schedule = cronCandidate;
+    } else if (labelCandidate && NAMED_SCHEDULES[labelCandidate.toLowerCase()]) {
+      schedule = NAMED_SCHEDULES[labelCandidate.toLowerCase()];
+    } else if (labelCandidate && isCronExpression(labelCandidate)) {
+      // Back-compat: a deployment that wrote a cron expression directly into
+      // backup_schedule (no _cron field) still works.
+      schedule = labelCandidate;
     }
 
     backupJob = cron.schedule(schedule, async () => {
@@ -1040,6 +1106,71 @@ async function cleanupOldBackupRuns(retentionDays = 30) {
   }
 }
 
+/**
+ * Load a backup manifest regardless of whether it lives on the local
+ * filesystem or in S3. Used by both the public getBackupManifest API
+ * and the incremental-manifest path in runBackupInternal — previously
+ * the latter called loadManifest() with an s3:// URI directly, which
+ * tried fs.readFile on the literal string and threw ENOENT, silently
+ * downgrading every incremental backup to a full manifest.
+ */
+async function loadManifestFromAnywhere(manifestPath, config) {
+  if (!manifestPath) {
+    throw new Error('Manifest path is required');
+  }
+  if (!manifestPath.startsWith('s3://')) {
+    return backupManifest.loadManifest(manifestPath);
+  }
+
+  const cfg = config || (await resolveConfigWithFallback());
+  const accessKey = cfg?.backup_s3_access_key
+    ?? (cfg?.__raw && Object.prototype.hasOwnProperty.call(cfg.__raw, 'backup_s3_access_key')
+      ? parseSettingValue(cfg.__raw.backup_s3_access_key)
+      : undefined)
+    ?? process.env.BACKUP_S3_ACCESS_KEY;
+  const secretKey = cfg?.backup_s3_secret_key
+    ?? (cfg?.__raw && Object.prototype.hasOwnProperty.call(cfg.__raw, 'backup_s3_secret_key')
+      ? parseSettingValue(cfg.__raw.backup_s3_secret_key)
+      : undefined)
+    ?? process.env.BACKUP_S3_SECRET_KEY;
+
+  if (!accessKey || !secretKey) {
+    throw new Error('S3 credentials not configured for manifest retrieval');
+  }
+
+  const match = manifestPath.match(/^s3:\/\/([^\/]+)\/(.+)$/);
+  if (!match) {
+    throw new Error('Invalid S3 manifest path');
+  }
+  const [, bucket, key] = match;
+
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'backup-manifest-'));
+  // Preserve the original extension so loadManifest's format detection
+  // picks the right parser.
+  const ext = path.extname(key) || '.json';
+  const tempPath = path.join(tempDir, `manifest-${Date.now()}${ext}`);
+
+  const s3Client = new S3StorageAdapter({
+    bucket,
+    region: (cfg && cfg.backup_s3_region) || 'us-east-1',
+    endpoint: cfg && cfg.backup_s3_endpoint,
+    accessKeyId: accessKey,
+    secretAccessKey: secretKey,
+    forcePathStyle: cfg ? normalizeBoolean(cfg.backup_s3_force_path_style) : false,
+    sslEnabled: cfg && cfg.backup_s3_ssl_enabled !== undefined
+      ? normalizeBoolean(cfg.backup_s3_ssl_enabled)
+      : true,
+  });
+
+  try {
+    await s3Client.download(key, tempPath);
+    return await backupManifest.loadManifest(tempPath);
+  } finally {
+    await fs.unlink(tempPath).catch(() => {});
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
 async function getBackupManifest(backupRunId) {
   const run = await db('backup_runs')
     .where('id', backupRunId)

backend/src/services/databaseBackup.js

@@ -1,9 +1,7 @@
 const fs = require('fs').promises;
 const path = require('path');
-const { exec } = require('child_process');
-const { promisify } = require('util');
-const execAsync = promisify(exec);
 const crypto = require('crypto');
+const { spawnAsync, spawnToFile } = require('../utils/safeExec');
 const zlib = require('zlib');
 const { pipeline } = require('stream/promises');
 const { createReadStream, createWriteStream } = require('fs');
@@ -163,10 +161,10 @@ class DatabaseBackupService {
     
     try {
       // Use SQLite's backup API for consistency
-      await execAsync(`sqlite3 "${dbPath}" ".backup '${tempPath}'"`);
-      
+      await spawnAsync('sqlite3', [dbPath, `.backup '${tempPath}'`]);
+
       // Verify the backup
-      const verifyResult = await execAsync(`sqlite3 "${tempPath}" "PRAGMA integrity_check"`);
+      const verifyResult = await spawnAsync('sqlite3', [tempPath, 'PRAGMA integrity_check']);
       if (!verifyResult.stdout.includes('ok')) {
         throw new Error('Backup integrity check failed');
       }
@@ -192,14 +190,6 @@ class DatabaseBackupService {
   async createPostgreSQLBackup(outputPath, options = {}) {
     const { host, port, user, password, database } = knexConfig.connection;
     
-    // Build connection string with proper escaping
-    const connectionParts = [
-      `host=${host}`,
-      `port=${port}`,
-      `dbname=${database}`,
-      `user=${user}`
-    ];
-    
     // Set PGPASSWORD environment variable for security
     const env = { ...process.env };
     if (password) {
@@ -227,14 +217,17 @@ class DatabaseBackupService {
       pgDumpOptions.push('--compress=6');
     }
     
-    const command = `pg_dump "${connectionParts.join(' ')}" ${pgDumpOptions.join(' ')} > "${outputPath}"`;
-    
+    const pgDumpArgs = [
+      ...pgDumpOptions,
+      '-h', host,
+      '-p', String(port),
+      '-U', user,
+      '-d', database
+    ];
+
     try {
-      const { stderr } = await execAsync(command, { 
-        env, 
-        maxBuffer: 1024 * 1024 * 100 // 100MB buffer
-      });
-      
+      const { stderr } = await spawnToFile('pg_dump', pgDumpArgs, outputPath, { env });
+
       // pg_dump writes progress to stderr, not an error
       if (stderr && !stderr.includes('dump complete')) {
         logger.warn('pg_dump warnings:', stderr);
@@ -261,7 +254,7 @@ class DatabaseBackupService {
     try {
       if (this.dbType === 'sqlite') {
         // For SQLite, we can directly check integrity
-        const result = await execAsync(`sqlite3 "${backupPath}" "PRAGMA integrity_check"`);
+        const result = await spawnAsync('sqlite3', [backupPath, 'PRAGMA integrity_check']);
         if (!result.stdout.includes('ok')) {
           throw new Error('Backup integrity check failed');
         }