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

chore(beta): release 3.32.0-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.
@@ -50,6 +84,16 @@ VITE_API_URL=/api
 # DB_PORT=5432
 # REDIS_PORT=6379
 
+# Release Channel
+# Options: 'stable' (default), 'beta', or specific version like 'v2.3.0'
+# 'stable' uses the :stable tag (same as :latest on main)
+# 'beta' uses the :beta tag for pre-release versions
+PICPEAK_CHANNEL=stable
+
+# Update Check Configuration
+# Set to 'false' to disable update notifications in admin UI
+UPDATE_CHECK_ENABLED=true
+
 # Timezone
 TZ=UTC
 
@@ -70,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:
 

.github/workflows/docker-build.yml

@@ -8,10 +8,10 @@ name: Build and Push Docker Images
 
 on:
   push:
-    branches: [ main, develop ]
-    tags: [ 'v*.*.*' ]  # Triggered by Release Please tags
+    branches: [ main, beta ]
+    tags: [ 'v*.*.*', 'v*.*.*-beta.*' ]  # Triggered by Release Please tags (stable and beta)
   pull_request:
-    branches: [ main ]
+    branches: [ main, beta ]
   release:
     types: [ published ]  # Triggered when Release Please creates a release
   workflow_dispatch:
@@ -42,6 +42,18 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Determine build context
+      id: context
+      run: |
+        # Determine if this is a beta or stable release
+        if [[ "${{ github.ref }}" == refs/tags/v*-beta* ]] || [[ "${{ github.ref }}" == refs/heads/beta ]]; then
+          echo "channel=beta" >> $GITHUB_OUTPUT
+          echo "is_prerelease=true" >> $GITHUB_OUTPUT
+        else
+          echo "channel=stable" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+        fi
+
     - name: Determine build platforms
       id: platforms
       run: |
@@ -88,10 +100,12 @@ jobs:
           type=ref,event=branch
           type=ref,event=pr
           type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-          type=semver,pattern={{major}}
+          type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
           type=sha,format=short
           type=raw,value=latest,enable={{is_default_branch}}
+          type=raw,value=stable,enable=${{ github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && steps.context.outputs.is_prerelease == 'false') }}
+          type=raw,value=beta,enable=${{ github.ref == 'refs/heads/beta' || steps.context.outputs.is_prerelease == 'true' }}
 
     - name: Build and push Backend Docker image
       uses: docker/build-push-action@v5
@@ -123,7 +137,7 @@ jobs:
 
     - name: Upload Trivy scan results to GitHub Security tab
       if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: github/codeql-action/upload-sarif@v3
+      uses: github/codeql-action/upload-sarif@v4
       with:
         sarif_file: 'trivy-backend.sarif'
         category: 'backend-vulnerabilities'
@@ -139,6 +153,18 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Determine build context
+      id: context
+      run: |
+        # Determine if this is a beta or stable release
+        if [[ "${{ github.ref }}" == refs/tags/v*-beta* ]] || [[ "${{ github.ref }}" == refs/heads/beta ]]; then
+          echo "channel=beta" >> $GITHUB_OUTPUT
+          echo "is_prerelease=true" >> $GITHUB_OUTPUT
+        else
+          echo "channel=stable" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+        fi
+
     - name: Determine build platforms
       id: platforms
       run: |
@@ -185,10 +211,12 @@ jobs:
           type=ref,event=branch
           type=ref,event=pr
           type=semver,pattern={{version}}
-          type=semver,pattern={{major}}.{{minor}}
-          type=semver,pattern={{major}}
+          type=semver,pattern={{major}}.{{minor}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
+          type=semver,pattern={{major}},enable=${{ steps.context.outputs.is_prerelease == 'false' }}
           type=sha,format=short
           type=raw,value=latest,enable={{is_default_branch}}
+          type=raw,value=stable,enable=${{ github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/v') && steps.context.outputs.is_prerelease == 'false') }}
+          type=raw,value=beta,enable=${{ github.ref == 'refs/heads/beta' || steps.context.outputs.is_prerelease == 'true' }}
 
     - name: Build and push Frontend Docker image
       uses: docker/build-push-action@v5
@@ -220,7 +248,7 @@ jobs:
 
     - name: Upload Trivy scan results to GitHub Security tab
       if: github.event_name != 'pull_request' && steps.login-ghcr.outcome == 'success'
-      uses: github/codeql-action/upload-sarif@v3
+      uses: github/codeql-action/upload-sarif@v4
       with:
         sarif_file: 'trivy-frontend.sarif'
         category: 'frontend-vulnerabilities'

.github/workflows/release-please-beta.yml

@@ -0,0 +1,37 @@
+name: Release Please (Beta)
+
+on:
+  push:
+    branches: [beta]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Run Release Please
+        uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config-beta.json
+          manifest-file: .release-please-manifest-beta.json
+          target-branch: beta
+
+      - name: Output Release Info
+        if: ${{ steps.release.outputs.release_created }}
+        run: |
+          echo "## Beta Release Created!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Tag:** ${{ steps.release.outputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ steps.release.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "Docker images will be built and tagged with this beta version." >> $GITHUB_STEP_SUMMARY
+

.github/workflows/release-please.yml

@@ -34,38 +34,3 @@ jobs:
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "Docker images will be built and tagged with this version." >> $GITHUB_STEP_SUMMARY
 
-  # Sync version to package.json files after release
-  sync-versions:
-    needs: release-please
-    if: ${{ needs.release-please.outputs.release_created }}
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          ref: main
-
-      - name: Update package.json versions
-        run: |
-          VERSION="${{ needs.release-please.outputs.version }}"
-          echo "Updating package.json files to version $VERSION"
-
-          # Update backend package.json
-          cd backend
-          npm version $VERSION --no-git-tag-version --allow-same-version
-          cd ..
-
-          # Update frontend package.json
-          cd frontend
-          npm version $VERSION --no-git-tag-version --allow-same-version
-          cd ..
-
-      - name: Commit version updates
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add backend/package.json frontend/package.json
-          git diff --staged --quiet || git commit -m "chore: sync package.json versions to ${{ needs.release-please.outputs.version }}"
-          git push

.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,38 @@ 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
+
 # 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

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

.release-please-manifest.json

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

DEPLOYMENT_GUIDE.md

@@ -2,9 +2,24 @@
 
 This guide covers multiple deployment options for PicPeak, from simple local setups to production-ready configurations.
 
-## 🎯 Quick Start - Simple Setup (Recommended for Beginners)
+## 📋 Table of Contents
 
-For the easiest installation without Docker or complex configurations, use our **unified setup script**:
+- [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 && \
@@ -12,27 +27,11 @@ chmod +x picpeak-setup.sh && \
 sudo ./picpeak-setup.sh
 ```
 
-This automated script handles everything including:
-- Choice between Docker or Native installation
-- OS detection and dependency installation
-- Database setup and service configuration
-- SSL/HTTPS setup (optional)
-
-Perfect for:
-- Small to medium deployments
-- Local or VPS installations  
-- Users new to server management
-- Quick testing and evaluation
+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.**
 
----
-
-## 🐳 Docker Compose Deployment
-
-### Option 1: Using Pre-built Images (Recommended)
-
-PicPeak provides official Docker images via GitHub Container Registry for quick deployment without building:
+### Option 2: Docker with Pre-built Images (Recommended)
 
 ```bash
 # Clone repository for configuration files
@@ -43,35 +42,40 @@ cd picpeak
 cp .env.example .env
 nano .env  # Edit with your values
 
-# Use pre-built images deployment
+# 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
 ```
 
-The production compose file uses:
-- **Backend**: `ghcr.io/the-luap/picpeak/backend:latest`
-- **Frontend**: `ghcr.io/the-luap/picpeak/frontend:latest`
+**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 |
 
-Available tags:
-- `latest` - Latest stable release
-- `main` - Latest main branch build
-- `develop` - Development branch (may be unstable)
-- `v1.0.0` - Specific version tags
+To select a channel, set `PICPEAK_CHANNEL` in your `.env` file (see [Release Channels](#release-channels) section)
 
-### Option 2: Building from Source
+### Option 3: Build from Source
 
-If you need to customize the application or the pre-built images aren't available, you can build locally:
+```bash
+git clone https://github.com/the-luap/picpeak.git
+cd picpeak
+cp .env.example .env
+nano .env  # Edit with your values
 
-## 📋 Table of Contents
+mkdir -p events/active events/archived data logs backup storage
+chmod -R 755 events data logs backup storage
 
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Deployment](#deployment)
-- [First Login](#first-login)
-- [Reverse Proxy Setup](#reverse-proxy-setup)
-- [Maintenance](#maintenance)
-- [Troubleshooting](#troubleshooting)
- - [External Media Library](#external-media-library)
+docker compose build
+docker compose up -d
+```
 
 ## Prerequisites
 
@@ -80,106 +84,6 @@ If you need to customize the application or the pre-built images aren't availabl
 - SMTP server credentials for emails
 - At least 2GB RAM and 20GB storage
 
-## 🚀 Quick Start
-
-### Method 1: Using Pre-built Images (Fastest)
-
-1. **Clone the repository for configs**
-   ```bash
-   git clone https://github.com/the-luap/picpeak.git
-   cd picpeak
-   ```
-
-2. **Set up environment**
-   ```bash
-   cp .env.example .env
-   nano .env  # Edit with your values
-   ```
-
-3. **Create required directories**
-   ```bash
-   mkdir -p events/active events/archived data logs backup storage
-   chmod -R 755 events data logs backup storage
-   ```
-
-4. **Deploy using pre-built images**
-   ```bash
-   docker compose -f docker-compose.production.yml up -d
-   ```
-
-5. **Check logs**
-   ```bash
-   docker compose -f docker-compose.production.yml logs -f
-   ```
-
-## External Media Library
-
-PicPeak can reference an existing, read‑only media library mounted into the backend container. This avoids copying originals into PicPeak storage.
-
-- Map your host library path to the container as read‑only in `docker-compose.production.yml`:
-  - Add volume under `backend`: `- ${EXTERNAL_MEDIA}:/external-media:ro`
-  - Add backend env: `EXTERNAL_MEDIA_ROOT=/external-media`
-- In `.env`, set:
-  - `EXTERNAL_MEDIA=/mnt/photos` (example host path)
-  - `EXTERNAL_MEDIA_ROOT=/external-media`
-
-Usage:
-- In Admin → Events, set “Source Mode” to “Reference (external folder)”, select a folder under `/external-media`, then import to index and generate thumbnails. Originals stay in your library.
-
-Backups and Archives:
-- Backups only include data under `STORAGE_PATH` and exclude external originals. The backup manifest includes `metadata.external_references = { excluded: true, events: N, photos: M }` and the Admin UI surfaces a warning.
-- Archiving reference events creates a manifest‑only ZIP and deletes thumbnails for that event. External originals are never moved or deleted.
-
-Local (npm) setup (no Docker):
-
-1. Create or choose a folder that contains your external originals, e.g. `/Users/you/Pictures/picpeak-external` (macOS/Linux) or `C:\\Pictures\\picpeak-external` (Windows).
-2. In `backend/.env` (or your shell), set:
-   - `EXTERNAL_MEDIA_ROOT=/absolute/path/to/picpeak-external`
-   - Ensure `STORAGE_PATH` points to your PicPeak storage (defaults to `./storage`).
-3. Start services from source:
-   - Backend: `cd backend && npm install && npm run migrate && JWT_SECRET=... npm start`
-   - Frontend: `cd frontend && npm install && npm run dev` (or build + serve)
-4. In Admin → Events:
-   - Create an event, set “Source Mode” to “Reference (external folder)”.
-   - Use the folder picker to browse under your `EXTERNAL_MEDIA_ROOT` and select the subfolder to reference.
-   - Click “Import from selected folder” to index files and generate thumbnails on demand.
-
-Notes:
-- PicPeak only reads from `EXTERNAL_MEDIA_ROOT`; it never modifies or deletes your originals there.
-- Thumbnails are generated under `STORAGE_PATH/thumbnails` and are included in backups; originals in `EXTERNAL_MEDIA_ROOT` are excluded.
-- On Windows, use absolute paths (e.g., `C:\\Photos\\Library`) for `EXTERNAL_MEDIA_ROOT`.
-
-### Method 2: Building from Source
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/the-luap/picpeak.git
-   cd picpeak
-   ```
-
-2. **Set up environment**
-   ```bash
-   cp .env.example .env
-   nano .env  # Edit with your values
-   ```
-
-3. **Create required directories**
-   ```bash
-   mkdir -p events/active events/archived data logs backup storage
-   chmod -R 755 events data logs backup storage
-   ```
-
-4. **Build and deploy**
-   ```bash
-   docker compose build
-   docker compose up -d
-   ```
-
-5. **Check logs**
-   ```bash
-   docker compose logs -f
-   ```
-
 ## 🔧 Configuration
 
 ### Essential Environment Variables
@@ -358,14 +262,16 @@ docker exec picpeak-backend cat data/ADMIN_CREDENTIALS.txt
 # 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
+# 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
-- The admin password is only displayed once during initial setup
+- 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
@@ -446,6 +352,61 @@ 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.
@@ -656,20 +617,27 @@ docker compose up -d
 docker compose ps
 ```
 
-#### Specific Version Updates
+#### Specific Version or Channel Updates
 
-To use a specific version of the images:
+To use a specific version or switch channels, update your `.env` file:
 
 ```bash
-# Edit docker-compose.production.yml to specify version tags
-# Change: ghcr.io/the-luap/picpeak/backend:latest
-# To:     ghcr.io/the-luap/picpeak/backend:v1.0.0
+# 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:

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](DEPLOYMENT_GUIDE.md) · [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)
@@ -79,7 +95,51 @@ Note on Docker file permissions (PUID/PGID)
 - Example in `.env`:
   - `PUID=1000`
   - `PGID=1000`
-- Without this, creating events, uploads, thumbnails, or logs can fail with “Permission denied”.
+- Without this, creating events, uploads, thumbnails, or logs can fail with "Permission denied".
+
+## 🔄 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`
+
+### Switching Channels
+
+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
+```
+
+Then update your containers:
+
+```bash
+docker compose -f docker-compose.production.yml pull
+docker compose -f docker-compose.production.yml up -d
+```
+
+### Update Notifications
+
+The admin dashboard automatically notifies you when updates are available for your channel. To disable update checks, set:
+
+```bash
+UPDATE_CHECK_ENABLED=false
+```
 
 ## 📖 Documentation
 
@@ -117,10 +177,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
@@ -253,6 +414,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.
@@ -283,6 +456,8 @@ 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://github.com/the-luap/picpeak/issues">Support</a>

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
@@ -451,6 +458,8 @@ cd /opt/picpeak/app/backend
 sudo -u picpeak node scripts/reset-admin-password.js
 ```
 
+> **Note:** The new password will be displayed in the console output and saved to `ADMIN_PASSWORD_RESET.txt`. Save it immediately!
+
 ### Getting Help
 
 1. **Check logs:**

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/059_add_admin_email_templates.js

@@ -3,6 +3,81 @@
  * These templates support the RBAC (Role-Based Access Control) feature
  */
 exports.up = async function(knex) {
+  // First, ensure the email_templates table has multilingual columns
+  // This is needed for fresh installations where legacy migrations don't run
+  const columnInfo = await knex('email_templates').columnInfo();
+
+  if (!columnInfo.subject_en) {
+    // Need to add multilingual columns
+    console.log('Adding multilingual columns to email_templates table...');
+
+    // Check if we're using SQLite or PostgreSQL
+    const client = knex.client.config.client;
+    const isSqlite = client === 'sqlite3' || client === 'better-sqlite3';
+
+    if (isSqlite) {
+      // SQLite doesn't support column rename directly in all versions
+      // We need to recreate the table with new structure
+
+      // Get existing data
+      const existingData = await knex('email_templates').select('*');
+
+      // Drop the old table
+      await knex.schema.dropTable('email_templates');
+
+      // Create new table with multilingual columns
+      await knex.schema.createTable('email_templates', (table) => {
+        table.increments('id').primary();
+        table.string('template_key').unique().notNullable();
+        table.string('subject_en');
+        table.string('subject_de');
+        table.text('body_html_en');
+        table.text('body_html_de');
+        table.text('body_text_en');
+        table.text('body_text_de');
+        table.json('variables');
+        table.datetime('updated_at').defaultTo(knex.fn.now());
+      });
+
+      // Re-insert existing data with column mapping
+      for (const row of existingData) {
+        await knex('email_templates').insert({
+          template_key: row.template_key,
+          subject_en: row.subject,
+          subject_de: row.subject, // Copy to German as default
+          body_html_en: row.body_html,
+          body_html_de: row.body_html,
+          body_text_en: row.body_text,
+          body_text_de: row.body_text,
+          variables: row.variables,
+          updated_at: row.updated_at
+        });
+      }
+
+      console.log('Migrated email_templates table to multilingual structure');
+    } else {
+      // PostgreSQL supports ALTER TABLE for column operations
+      await knex.schema.alterTable('email_templates', (table) => {
+        table.renameColumn('subject', 'subject_en');
+        table.renameColumn('body_html', 'body_html_en');
+        table.renameColumn('body_text', 'body_text_en');
+      });
+
+      await knex.schema.alterTable('email_templates', (table) => {
+        table.string('subject_de');
+        table.text('body_html_de');
+        table.text('body_text_de');
+      });
+
+      // Copy English values to German 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')
+      });
+    }
+  }
+
   // Check which templates already exist
   const existingTemplates = await knex('email_templates')
     .select('template_key')

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.2.3",
+  "version": "3.32.0-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/scripts/show-admin-credentials.js

@@ -36,12 +36,14 @@ async function showAdminCredentials(resetPassword = false) {
         .where('id', admin.id)
         .update({
           password_hash: passwordHash,
+          must_change_password: true,
           updated_at: new Date()
         });
-      
-      // Password logging removed for security - check logs or database if needed
-      console.log('Password: [NEWLY RESET - stored in database]');
-      console.log('\n⚠️  IMPORTANT: New password has been set in database!');
+
+      console.log(`Password: ${newPassword}`);
+      console.log('\n⚠️  IMPORTANT:');
+      console.log('1. Save this password securely - it will not be shown again');
+      console.log('2. You will be required to change it on next login');
     } else {
       console.log('Password: [hidden - use --reset flag to generate new password]');
     }

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/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' });
@@ -392,11 +454,21 @@ router.post('/branding/watermark-logo', adminAuth, requirePermission('settings.e
       .first();
 
     if (oldWatermarkLogoSetting && oldWatermarkLogoSetting.setting_value) {
-      const oldPath = JSON.parse(oldWatermarkLogoSetting.setting_value);
+      let oldPath;
       try {
-        await fs.unlink(oldPath);
-      } catch (error) {
-        console.error('Failed to delete old watermark logo:', error);
+        // Try to parse as JSON first (for JSON-stringified paths)
+        oldPath = JSON.parse(oldWatermarkLogoSetting.setting_value);
+      } catch (e) {
+        // If it's not valid JSON, use the raw value
+        oldPath = oldWatermarkLogoSetting.setting_value;
+      }
+
+      if (oldPath && typeof oldPath === 'string') {
+        try {
+          await fs.unlink(oldPath);
+        } catch (error) {
+          console.error('Failed to delete old watermark logo:', error);
+        }
       }
     }
 
@@ -421,19 +493,37 @@ router.post('/branding/watermark-logo', adminAuth, requirePermission('settings.e
     await db('app_settings')
       .insert({
         setting_key: 'branding_watermark_logo_url',
-        setting_value: publicPath,
+        setting_value: JSON.stringify(publicPath),
         setting_type: 'branding',
         updated_at: new Date()
       })
       .onConflict('setting_key')
       .merge({
-        setting_value: publicPath,
+        setting_value: JSON.stringify(publicPath),
         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);
@@ -653,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

@@ -7,6 +7,13 @@ const path = require('path');
 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
@@ -22,12 +29,15 @@ router.get('/version', adminAuth, requirePermission('settings.view'), async (req
     } catch (err) {
       console.error('Could not read package.json:', err);
     }
-    
+
+    const channel = getCurrentChannel(backendVersion);
+
     res.json({
       backend: backendVersion,
       frontend: '1.0.0', // This will be set by frontend
       node: process.version,
-      environment: process.env.NODE_ENV || 'production'
+      environment: process.env.NODE_ENV || 'production',
+      channel: channel
     });
   } catch (error) {
     console.error('Error fetching version:', error);
@@ -35,6 +45,73 @@ router.get('/version', adminAuth, requirePermission('settings.view'), async (req
   }
 });
 
+// Check for updates
+router.get('/updates', 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 forceRefresh = req.query.refresh === 'true';
+    const updateInfo = await checkForUpdates(forceRefresh);
+
+    res.json({
+      enabled: true,
+      ...updateInfo
+    });
+  } catch (error) {
+    logger.error('Error checking for updates:', error);
+    res.status(500).json({ error: 'Failed to check for updates' });
+  }
+});
+
+// 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 {
@@ -232,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,16 +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, 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) {
@@ -72,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();
 
@@ -106,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();
 
@@ -128,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) {
@@ -150,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);
@@ -169,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) {
@@ -257,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))
@@ -272,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({
@@ -316,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' } : {})
         };
       })
     });
@@ -360,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);
     
@@ -456,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;
@@ -492,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,
@@ -617,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,
         });
       }
     }
@@ -676,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/'));
 
@@ -698,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(
@@ -711,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;
@@ -753,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'
         });
 
@@ -768,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
@@ -787,30 +1084,35 @@ router.get('/:slug/photo/:photoId',
 );
 
 // Serve thumbnail
-router.get('/:slug/thumbnail/:photoId', 
-  verifyGalleryAccess, 
+router.get('/:slug/thumbnail/: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 || !photo.thumbnail_path) {
-        return res.status(404).json({ error: 'Thumbnail not found' });
+
+      if (!photo) {
+        return res.status(404).json({ error: 'Photo not found' });
       }
-      
-      const thumbPath = path.join(getStoragePath(), photo.thumbnail_path);
-      
-      // Check if file exists
-      const fs = require('fs').promises;
-      try {
-        await fs.access(thumbPath);
-      } catch (error) {
-        return res.status(404).json({ error: 'Thumbnail file 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);
+
+      if (!thumbnailPath) {
+        logger.error(`Failed to generate thumbnail for photo ${photoId}`);
+        return res.status(404).json({ error: 'Thumbnail generation failed' });
+      }
+
+      const thumbPath = path.join(getStoragePath(), thumbnailPath);
+
       // Log thumbnail access
       await secureImageService.logImageAccess(
         photoId,
@@ -818,18 +1120,41 @@ router.get('/:slug/thumbnail/:photoId',
         req.clientInfo,
         '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,
@@ -841,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 {
@@ -850,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);
@@ -926,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: {
@@ -933,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();
@@ -90,38 +91,60 @@ router.get('/:slug/photo/:photoId/view', verifyGalleryAccess, async (req, res) =
     }, 'view');
     
     // Get protection settings from event
+    const eventProtectionLevel = req.event.protection_level || protectionLevel;
     const protectionSettings = {
-      protectionLevel: req.event.protection_level || protectionLevel,
+      protectionLevel: eventProtectionLevel,
       quality: req.event.image_quality || 85,
       addFingerprint: req.event.add_fingerprint !== false,
-      fragmentImage: protectionLevel === 'maximum'
+      fragmentImage: eventProtectionLevel === 'maximum'
     };
-    
-    // Build full path to photo
-    const photoPath = path.join(getStoragePath(), 'events/active', req.event.slug, photo.path);
-    
-    // Process image with protection
-    const processedImage = await secureImageService.processProtectedImage(photoPath, protectionSettings);
-    
-    // Apply watermark if enabled
+
+    // Resolve photo location through the storage backend (managed) or local
+    // disk (external reference mode).
+    const storageKey = resolvePhotoStorageKey(req.event, photo);
+    const storage = getStorage();
+
+    const needsProcessing = eventProtectionLevel === 'enhanced' ||
+                            eventProtectionLevel === 'maximum' ||
+                            protectionSettings.addFingerprint;
+
     let finalImage;
-    if (processedImage.type === 'fragmented') {
-      // Return fragmented image data for canvas reconstruction
-      return res.json({
-        type: 'fragmented',
-        fragments: processedImage.fragments.map(f => ({
-          index: f.index,
-          row: f.row,
-          col: f.col,
-          data: f.buffer.toString('base64'),
-          position: f.position
-        })),
-        dimensions: processedImage.originalDimensions,
-        fragmentDimensions: processedImage.fragmentDimensions
-      });
+
+    if (!needsProcessing) {
+      // 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 {
-      const watermarkSettings = await watermarkService.getWatermarkSettings();
-      finalImage = await watermarkService.applyWatermark(photoPath, watermarkSettings);
+      // 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 res.json({
+          type: 'fragmented',
+          fragments: processedImage.fragments.map(f => ({
+            index: f.index,
+            row: f.row,
+            col: f.col,
+            data: f.buffer.toString('base64'),
+            position: f.position
+          })),
+          dimensions: processedImage.originalDimensions,
+          fragmentDimensions: processedImage.fragmentDimensions
+        });
+      }
+
+      finalImage = processedImage;
     }
     
     // Set security headers
@@ -261,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,484 @@
+/**
+ * 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 — the source of truth for picpeak-docs.
+ */
+
+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;