Merge remote-tracking branch 'origin/main' into refactor/codebase-cleanup

# Conflicts:
#	backend/src/routes/adminEvents.js
#	backend/src/routes/protectedImages.js
#	frontend/src/pages/admin/EventDetailsPage.tsx

backend/src/__tests__/verifyGalleryAccess.customerRevoke.test.js

@@ -101,6 +101,7 @@ describe('verifyGalleryAccess — customer-minted JWT with active assignment', (
   it('allows access when the event_customer_assignments row exists', async () => {
     getGalleryTokenFromRequest.mockReturnValue('tkn');
     jwt.verify.mockReturnValue({
+      type: 'gallery',
       eventId: 42,
       via: 'customer',
       customerId: 7,
@@ -131,6 +132,7 @@ describe('verifyGalleryAccess — customer-minted JWT after revocation', () => {
   it('returns 403 CUSTOMER_ASSIGNMENT_REVOKED when the junction row is gone', async () => {
     getGalleryTokenFromRequest.mockReturnValue('tkn');
     jwt.verify.mockReturnValue({
+      type: 'gallery',
       eventId: 42,
       via: 'customer',
       customerId: 7,
@@ -160,6 +162,7 @@ describe('verifyGalleryAccess — customer-minted JWT after revocation', () => {
     // and start 403'ing per-event-password sessions.
     getGalleryTokenFromRequest.mockReturnValue('tkn');
     jwt.verify.mockReturnValue({
+      type: 'gallery',
       eventId: 42,
       customerId: 7,
       // intentionally no `via` claim
@@ -191,6 +194,7 @@ describe('verifyGalleryAccess — per-event-password JWT', () => {
   it('does NOT touch event_customer_assignments and passes through', async () => {
     getGalleryTokenFromRequest.mockReturnValue('tkn');
     jwt.verify.mockReturnValue({
+      type: 'gallery',
       eventId: 42,
       // No via, no customerId — this is the legacy per-event-password
       // flow where every guest mints their own JWT after entering the

backend/src/middleware/auth.js

@@ -18,6 +18,7 @@ async function adminAuth(req, res, next) {
     let decoded;
     try {
       decoded = jwt.verify(token, process.env.JWT_SECRET, {
+        algorithms: ['HS256'],
         issuer: 'picpeak-auth',
         complete: true
       });
@@ -140,6 +141,7 @@ async function galleryAuth(req, res, next) {
     let decoded;
     try {
       decoded = jwt.verify(token, process.env.JWT_SECRET, {
+        algorithms: ['HS256'],
         issuer: 'picpeak-auth',
         complete: true
       });
@@ -209,7 +211,7 @@ async function photoAuth(req, res, next) {
 
     let decoded;
     try {
-      decoded = jwt.verify(token, process.env.JWT_SECRET);
+      decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });
     } catch (err) {
       return res.status(401).json({ error: 'Invalid token' });
     }

backend/src/middleware/customerAuth.js

@@ -34,6 +34,7 @@ async function customerAuth(req, res, next) {
     let decoded;
     try {
       const verified = jwt.verify(token, process.env.JWT_SECRET, {
+        algorithms: ['HS256'],
         issuer: 'picpeak-auth',
         complete: true,
       });

backend/src/middleware/gallery.js

@@ -66,18 +66,29 @@ async function verifyGalleryAccess(req, res, next) {
     let decoded;
     try {
       decoded = jwt.verify(token, process.env.JWT_SECRET, {
+        algorithms: ['HS256'],
         issuer: 'picpeak-auth'
       });
     } catch (error) {
       // If verification fails with issuer, try without issuer (backward compatibility)
       if (error.name === 'JsonWebTokenError' && error.message.includes('jwt issuer invalid')) {
-        decoded = jwt.verify(token, process.env.JWT_SECRET);
+        decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });
       } else {
         throw error;
       }
     }
     logger.debug('[verifyGalleryAccess] Token decoded successfully', { eventId: decoded.eventId, slug: requestedSlug });
-    
+
+    // Only gallery-scoped tokens grant gallery access. Every legitimate
+    // path (password login, share link, client access, customer-minted,
+    // slideshow) mints type:'gallery'. Reject anything else — e.g. a guest
+    // identity token (type:'guest', for feedback attribution) that carries a
+    // matching eventId — instead of relying on other token types incidentally
+    // lacking an eventId to fail the id match below.
+    if (decoded.type !== 'gallery') {
+      return res.status(403).json({ error: 'Invalid token type for gallery access' });
+    }
+
     // 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

backend/src/middleware/guestAuth.js

@@ -23,6 +23,7 @@ async function resolveGuest(req, res, next) {
     let decoded;
     try {
       const verified = jwt.verify(token, process.env.JWT_SECRET, {
+        algorithms: ['HS256'],
         issuer: 'picpeak-auth',
         complete: true,
       });

backend/src/middleware/ownership.js

@@ -32,4 +32,36 @@ function requireEventOwnership(req, res, next) {
     });
 }
 
-module.exports = { requireEventOwnership };
+/**
+ * Return the subset of `eventIds` the admin may act on, mirroring
+ * requireEventOwnership for bulk routes that can't use it (they take an
+ * array in the body, not an :id param). super_admin gets everything;
+ * other roles get events they created plus ownerless legacy/system
+ * events (created_by IS NULL). Ids that are foreign OR non-existent both
+ * land in `denied` — deliberately indistinguishable, so bulk routes
+ * don't become an ownership/existence oracle.
+ *
+ * @returns {Promise<{allowed: Array, denied: Array}>}
+ */
+async function filterOwnedEventIds(admin, eventIds) {
+  if (admin.roleName === 'super_admin') {
+    return { allowed: [...eventIds], denied: [] };
+  }
+  const rows = await db('events')
+    .whereIn('id', eventIds)
+    .andWhere((q) => q.whereNull('created_by').orWhere('created_by', admin.id))
+    .select('id');
+  const allowedSet = new Set(rows.map((r) => r.id));
+  const allowed = [];
+  const denied = [];
+  for (const id of eventIds) {
+    if (allowedSet.has(id) || allowedSet.has(Number(id))) {
+      allowed.push(id);
+    } else {
+      denied.push(id);
+    }
+  }
+  return { allowed, denied };
+}
+
+module.exports = { requireEventOwnership, filterOwnedEventIds };

backend/src/middleware/photoAuth.js

@@ -28,12 +28,13 @@ async function photoAuth(req, res, next) {
         let decoded;
         try {
           decoded = jwt.verify(token, process.env.JWT_SECRET, {
+            algorithms: ['HS256'],
             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);
+            decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });
           } else {
             throw issuerError;
           }
@@ -43,24 +44,36 @@ async function photoAuth(req, res, next) {
         if (decoded.type === 'gallery') {
           // For thumbnails, we need to verify the token is for a valid event
           if (!eventSlug) {
-            // Extract event ID from the decoded token
+            // Resolve the token's event (by id, or legacy slug fallback)...
+            let event = null;
             if (decoded.eventId) {
-              const event = await db('events')
+              event = await db('events')
                 .where({ id: decoded.eventId, is_active: formatBoolean(true) })
                 .first();
-              if (event) {
+            }
+            if (!event && decoded.eventSlug) {
+              event = await db('events')
+                .where({ slug: decoded.eventSlug, is_active: formatBoolean(true) })
+                .first();
+            }
+            // ...then confirm the REQUESTED thumbnail actually belongs to
+            // that event. Thumbnails are stored flat (thumbnails/thumb_<name>)
+            // with deterministic, enumerable filenames derived from the
+            // public event name + a sequential counter. Without this
+            // ownership check any holder of a gallery token for any event
+            // could enumerate and fetch another (password-protected) event's
+            // entire thumbnail set, defeating the gallery password. A
+            // traversal or foreign filename simply fails to match → denied.
+            if (event) {
+              const requestedKey = `thumbnails${req.path}`;
+              const ownsThumbnail = await db('photos')
+                .where({ event_id: event.id, thumbnail_path: requestedKey })
+                .first();
+              if (ownsThumbnail) {
                 req.event = event;
                 return next();
               }
             }
-            // Fallback to slug
-            const event = await db('events')
-              .where({ slug: decoded.eventSlug, is_active: formatBoolean(true) })
-              .first();
-            if (event) {
-              req.event = event;
-              return next();
-            }
           }
           // For regular photos, check if token matches the event
           else if (decoded.eventSlug === eventSlug) {

backend/src/middleware/sessionTimeout.js

@@ -87,7 +87,7 @@ async function sessionTimeoutMiddleware(req, res, next) {
   
   try {
     // Verify token is valid
-    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    const decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });
     
     // Check if this is an admin token
     if (!decoded.id) {
@@ -128,7 +128,7 @@ async function sessionTimeoutMiddleware(req, res, next) {
     for (const [oldToken, _] of sessions.entries()) {
       if (oldToken !== token) {
         try {
-          const oldDecoded = jwt.verify(oldToken, process.env.JWT_SECRET);
+          const oldDecoded = jwt.verify(oldToken, process.env.JWT_SECRET, { algorithms: ['HS256'] });
           if (oldDecoded.id === userId) {
             sessions.delete(oldToken);
           }

backend/src/routes/adminAuth.js

@@ -10,6 +10,7 @@ const { handleAsync, validateRequest, successResponse } = require('../utils/rout
 const { NotFoundError, ConflictError, ValidationError } = require('../utils/errors');
 const { setAdminAuthCookie } = require('../utils/tokenUtils');
 const { IDENTITY_PRESERVING_NORMALIZE_EMAIL } = require('../utils/emailNormalization');
+const mfaService = require('../services/mfaService');
 const router = express.Router();
 
 // Get admin profile
@@ -184,4 +185,175 @@ router.post('/logout', adminAuth, handleAsync(async (req, res) => {
   successResponse(res, { message: 'Logged out successfully' });
 }));
 
+// ---------------------------------------------------------------------------
+// Multi-factor authentication (TOTP) — issue #738.
+//
+// All endpoints operate on the AUTHENTICATED admin's own account
+// (req.admin.id) — enrollment is per-user and works for every role,
+// super_admin included (closes #735). The TOTP secret is stored encrypted
+// at rest and recovery codes are hashed; see services/mfaService.js.
+// ---------------------------------------------------------------------------
+
+const isMfaEnabled = mfaService.isEnrolled;
+
+// Current MFA state for the logged-in admin.
+router.get('/mfa/status', adminAuth, handleAsync(async (req, res) => {
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  const enabled = isMfaEnabled(admin);
+  res.json({
+    enabled,
+    enrolledAt: enabled ? admin.two_factor_enrolled_at || null : null,
+    recoveryCodesRemaining: enabled
+      ? mfaService.parseRecoveryCodes(admin.two_factor_recovery_codes).length
+      : 0
+  });
+}));
+
+// Begin enrollment: mint a provisional secret, store it encrypted (NOT yet
+// enabled), and return the otpauth URI + QR for the authenticator app. Calling
+// this again before /enable simply regenerates the provisional secret.
+router.post('/mfa/setup', adminAuth, handleAsync(async (req, res) => {
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (isMfaEnabled(admin)) {
+    throw new ConflictError('Two-factor authentication is already enabled');
+  }
+
+  const secret = mfaService.generateSecret();
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_secret: mfaService.encryptSecret(secret),
+    two_factor_enabled: false,
+    two_factor_recovery_codes: null,
+    two_factor_enrolled_at: null,
+    updated_at: new Date()
+  });
+
+  const accountName = admin.email || admin.username;
+  const otpauthUri = mfaService.buildOtpauthUri(accountName, secret);
+  const qr = await mfaService.buildQrDataUrl(otpauthUri);
+
+  res.json({
+    // `secret` is returned for manual entry when a QR can't be scanned.
+    secret,
+    otpauthUri,
+    qr,
+    issuer: mfaService.ISSUER,
+    account: accountName
+  });
+}));
+
+// Complete enrollment: verify a code against the provisional secret, enable
+// MFA, and return one-time recovery codes (shown exactly once).
+router.post('/mfa/enable', [
+  adminAuth,
+  body('code').notEmpty().withMessage('Verification code is required')
+], handleAsync(async (req, res) => {
+  validateRequest(req);
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (isMfaEnabled(admin)) {
+    throw new ConflictError('Two-factor authentication is already enabled');
+  }
+  if (!admin.two_factor_secret) {
+    throw new ValidationError('Start setup before enabling two-factor authentication');
+  }
+  if (!mfaService.verifyTotpEncrypted(req.body.code, admin.two_factor_secret)) {
+    throw new ValidationError('Invalid verification code');
+  }
+
+  const { plain, hashed } = await mfaService.generateRecoveryCodes();
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_enabled: true,
+    two_factor_enrolled_at: new Date(),
+    two_factor_recovery_codes: JSON.stringify(hashed),
+    updated_at: new Date()
+  });
+
+  await logActivity('admin_mfa_enabled',
+    { admin_id: admin.id },
+    null,
+    { type: 'admin', id: admin.id, name: admin.username }
+  );
+
+  successResponse(res, {
+    message: 'Two-factor authentication enabled',
+    recoveryCodes: plain
+  });
+}));
+
+// Disable MFA. Requires a fresh TOTP or recovery code so a hijacked session
+// can't silently strip the second factor.
+router.post('/mfa/disable', [
+  adminAuth,
+  body('code').notEmpty().withMessage('A current code is required to disable 2FA')
+], handleAsync(async (req, res) => {
+  validateRequest(req);
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (!isMfaEnabled(admin)) {
+    throw new ValidationError('Two-factor authentication is not enabled');
+  }
+
+  const totpOk = mfaService.verifyTotpEncrypted(req.body.code, admin.two_factor_secret);
+  let recoveryOk = false;
+  if (!totpOk) {
+    const stored = mfaService.parseRecoveryCodes(admin.two_factor_recovery_codes);
+    recoveryOk = (await mfaService.consumeRecoveryCode(req.body.code, stored)).matched;
+  }
+  if (!totpOk && !recoveryOk) {
+    throw new ValidationError('Invalid verification code');
+  }
+
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_enabled: false,
+    two_factor_secret: null,
+    two_factor_recovery_codes: null,
+    two_factor_enrolled_at: null,
+    updated_at: new Date()
+  });
+
+  await logActivity('admin_mfa_disabled',
+    { admin_id: admin.id },
+    null,
+    { type: 'admin', id: admin.id, name: admin.username }
+  );
+
+  successResponse(res, { message: 'Two-factor authentication disabled' });
+}));
+
+// Regenerate recovery codes (invalidates the old set). Requires a fresh TOTP
+// code. Returns the new codes once.
+router.post('/mfa/recovery-codes', [
+  adminAuth,
+  body('code').notEmpty().withMessage('A current authenticator code is required')
+], handleAsync(async (req, res) => {
+  validateRequest(req);
+  const admin = await db('admin_users').where('id', req.admin.id).first();
+  if (!admin) throw new NotFoundError('Admin user');
+  if (!isMfaEnabled(admin)) {
+    throw new ValidationError('Two-factor authentication is not enabled');
+  }
+  if (!mfaService.verifyTotpEncrypted(req.body.code, admin.two_factor_secret)) {
+    throw new ValidationError('Invalid verification code');
+  }
+
+  const { plain, hashed } = await mfaService.generateRecoveryCodes();
+  await db('admin_users').where('id', admin.id).update({
+    two_factor_recovery_codes: JSON.stringify(hashed),
+    updated_at: new Date()
+  });
+
+  await logActivity('admin_mfa_recovery_regenerated',
+    { admin_id: admin.id },
+    null,
+    { type: 'admin', id: admin.id, name: admin.username }
+  );
+
+  successResponse(res, {
+    message: 'Recovery codes regenerated',
+    recoveryCodes: plain
+  });
+}));
+
 module.exports = router;

backend/src/routes/adminBackup.js

@@ -129,6 +129,71 @@ router.post('/run', adminAuth, requirePermission('backup.create'), async (req, r
   }
 });
 
+// Generate + download a portable ".picpeak" export — an engine-neutral logical
+// snapshot (DB rows as NDJSON + PDFs/business-docs) that can be re-uploaded to
+// another instance via the web UI. `?includePhotos=true` also bundles original
+// gallery photos (larger); otherwise the admin re-uploads them per gallery.
+//
+// SECURITY: the file contains plaintext secrets (SMTP password, admin password
+// hashes, API keys). The download UI must warn before offering it. We surface
+// the flag as a response header too so the client can double-confirm.
+router.get('/picpeak/export', adminAuth, requirePermission('backup.create'), async (req, res) => {
+  const fsSync = require('fs');
+  try {
+    const includePhotos = req.query.includePhotos === 'true' || req.query.includePhotos === '1';
+    const { createPicpeak } = require('../services/picpeakExportService');
+    const { filePath } = await createPicpeak({ includePhotos });
+    const filename = path.basename(filePath);
+    res.setHeader('X-Picpeak-Contains-Secrets', 'true');
+    res.download(filePath, filename, (err) => {
+      // Best-effort cleanup of the temp .picpeak (and its temp dir) after send.
+      fsSync.rm(path.dirname(filePath), { recursive: true, force: true }, () => {});
+      if (err) logger.error('[picpeak-export] download failed', { error: err.message });
+    });
+  } catch (error) {
+    logger.error('[picpeak-export] failed to create export', { error: error.message });
+    if (!res.headersSent) res.status(500).json({ error: 'Failed to create .picpeak export' });
+  }
+});
+
+// Multipart upload for .picpeak restore — streamed to a temp file. Runs AFTER
+// auth so an unauthenticated request can't push a large file to disk.
+const os = require('os');
+const multer = require('multer');
+const picpeakUpload = multer({
+  storage: multer.diskStorage({
+    destination: (req, file, cb) => cb(null, os.tmpdir()),
+    filename: (req, file, cb) => cb(null, `picpeak-upload-${Date.now()}-${crypto.randomBytes(6).toString('hex')}.picpeak`),
+  }),
+  limits: { fileSize: 5 * 1024 * 1024 * 1024 }, // 5 GB — .picpeak with photos can be large
+});
+
+// Upload + restore a .picpeak onto THIS instance. DESTRUCTIVE: full override of
+// all data except the current logged-in account (the client shows an explicit
+// confirmation before calling this). Returns `usesExternalMedia` so the UI can
+// prompt the admin to reconfigure the external-media mount afterwards.
+router.post('/picpeak/import', adminAuth, requirePermission('backup.restore'), picpeakUpload.single('backup'), async (req, res) => {
+  const fsSync = require('fs');
+  if (!req.file) return res.status(400).json({ error: 'No backup file uploaded' });
+  const picpeakPath = req.file.path;
+  try {
+    const { importFromPicpeak } = require('../services/picpeakImportService');
+    const result = await importFromPicpeak({ picpeakPath, currentAdminId: req.user && req.user.id });
+    res.json({
+      success: true,
+      tables: result.tables,
+      filesRestored: result.filesRestored,
+      usesExternalMedia: result.usesExternalMedia,
+    });
+  } catch (error) {
+    const status = error.statusCode || 500;
+    logger.error('[picpeak-import] restore failed', { error: error.message });
+    res.status(status).json({ error: error.message || 'Restore failed', validation: error.validation });
+  } finally {
+    fsSync.unlink(picpeakPath, () => {});
+  }
+});
+
 // Get backup run details
 router.get('/runs/:id', adminAuth, requirePermission('backup.view'), async (req, res) => {
   try {

backend/src/routes/adminEventRename.js

@@ -7,6 +7,7 @@ const express = require('express');
 const { body, validationResult } = require('express-validator');
 const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
+const { requireEventOwnership } = require('../middleware/ownership');
 const eventRenameService = require('../services/eventRenameService');
 const logger = require('../utils/logger');
 const router = express.Router();
@@ -15,7 +16,7 @@ const router = express.Router();
  * POST /api/admin/events/:eventId/rename
  * Rename an event
  */
-router.post('/:eventId/rename', adminAuth, requirePermission('events.edit'), [
+router.post('/:eventId/rename', adminAuth, requirePermission('events.edit'), requireEventOwnership, [
   body('newEventName')
     .trim()
     .isLength({ min: 3, max: 100 })
@@ -60,7 +61,7 @@ router.post('/:eventId/rename', adminAuth, requirePermission('events.edit'), [
  * POST /api/admin/events/:eventId/validate-rename
  * Validate a potential rename without executing it
  */
-router.post('/:eventId/validate-rename', adminAuth, requirePermission('events.edit'), [
+router.post('/:eventId/validate-rename', adminAuth, requirePermission('events.edit'), requireEventOwnership, [
   body('newEventName')
     .trim()
     .isLength({ min: 3, max: 100 })

backend/src/routes/adminEvents/archiveBulk.js

@@ -10,7 +10,7 @@ const { requirePermission } = require('../../middleware/permissions');
 const { archiveEvent } = require('../../services/archiveService');
 const logger = require('../../utils/logger');
 const { errorResponse } = require('../../utils/routeHelpers');
-const { requireEventOwnership } = require('../../middleware/ownership');
+const { requireEventOwnership, filterOwnedEventIds } = require('../../middleware/ownership');
 const { deleteEventCascade } = require('./helpers');
 
 
@@ -74,25 +74,39 @@ module.exports = (router) => {
       }
 
       const { eventIds } = req.body;
-    
+
       if (eventIds.length === 0) {
         return res.status(400).json({ error: 'No events selected for archiving' });
       }
 
-      // Get all events to archive
-      const events = await db('events')
-        .whereIn('id', eventIds)
-        .where('is_archived', formatBoolean(false));
-
-      if (events.length === 0) {
-        return res.status(400).json({ error: 'No valid events found to archive' });
-      }
+      // Ownership scope: a non-super_admin may only archive events they own.
+      // Foreign/non-existent ids are dropped and reported as failures so this
+      // route can't archive another admin's events (the single-event
+      // /:id/archive route enforces the same via requireEventOwnership).
+      const { allowed: allowedIds, denied: deniedIds } = await filterOwnedEventIds(req.admin, eventIds);
 
       const results = {
         successful: [],
-        failed: []
+        failed: deniedIds.map((id) => ({ id, name: null, error: 'Access denied or event not found' }))
       };
 
+      // Get all events to archive
+      const events = allowedIds.length
+        ? await db('events')
+          .whereIn('id', allowedIds)
+          .where('is_archived', formatBoolean(false))
+        : [];
+
+      if (events.length === 0) {
+        if (results.failed.length > 0) {
+          return res.json({
+            message: `Bulk archive completed: 0 succeeded, ${results.failed.length} failed`,
+            results
+          });
+        }
+        return res.status(400).json({ error: 'No valid events found to archive' });
+      }
+
       // Process each event
       for (const event of events) {
         try {
@@ -151,16 +165,21 @@ module.exports = (router) => {
 
       const { eventIds } = req.body;
 
-      // Editor-role events.delete permission is already gated by the route
-      // middleware. We do NOT additionally filter to created_by here because
-      // the per-event delete-cascade is global (matches DELETE /:id which
-      // also has no role-based filter — that's why events.delete is a
-      // sensitive permission).
+      // Ownership scope: a non-super_admin may only delete events they own.
+      // The single-event DELETE /:id route enforces this via
+      // requireEventOwnership; this bulk route must match it, otherwise an
+      // admin/editor scoped to their own events could cascade-delete any
+      // event by id. Foreign/non-existent ids are dropped and reported as
+      // failures (indistinguishable, to avoid an existence oracle).
+      const { allowed: allowedIds, denied: deniedIds } = await filterOwnedEventIds(req.admin, eventIds);
 
-      const results = { successful: [], failed: [] };
+      const results = {
+        successful: [],
+        failed: deniedIds.map((id) => ({ id, name: null, error: 'Access denied or event not found' }))
+      };
       const adminContext = { id: req.admin.id, username: req.admin.username };
 
-      for (const eventId of eventIds) {
+      for (const eventId of allowedIds) {
         try {
           const deleted = await deleteEventCascade(eventId, adminContext);
           results.successful.push(deleted);

backend/src/routes/adminExternalMedia.js

@@ -3,6 +3,7 @@ const path = require('path');
 const fs = require('fs').promises;
 const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
+const { requireEventOwnership } = require('../middleware/ownership');
 const { list, resolveExternalPath, getExternalMediaRoot } = require('../services/externalMediaService');
 const { db, logActivity } = require('../database/db');
 const sharp = require('sharp');
@@ -48,7 +49,7 @@ async function walkDir(dir, baseDir) {
 
 // POST /api/admin/events/:id/import-external
 // Body: { external_path: string, recursive?: boolean, map?: { individual?: string, collages?: string } }
-router.post('/events/:id/import-external', adminAuth, requirePermission('photos.upload'), async (req, res) => {
+router.post('/events/:id/import-external', adminAuth, requirePermission('photos.upload'), requireEventOwnership, async (req, res) => {
   try {
     const eventId = parseInt(req.params.id);
     const { external_path, recursive = true, map = { individual: 'individual', collages: 'collages' } } = req.body || {};

backend/src/routes/adminPhotos.js

@@ -600,12 +600,18 @@ router.post(
       const photo = await db('photos').where({ id: req.params.photoId }).first();
       if (!photo) return res.status(404).json({ error: 'Photo not found' });
 
-      // Editor role: only allow retry on photos in events they own.
-      if (req.admin.roleName === 'editor') {
+      // Ownership scope: any non-super_admin may only retry photos in events
+      // they own — matching requireEventOwnership (which scopes both the
+      // admin and editor roles; only super_admin bypasses). Previously this
+      // checked the editor role alone, leaving admin-role users able to
+      // reprocess another admin's photos.
+      if (req.admin.roleName !== 'super_admin') {
         const event = await db('events')
-          .where({ id: photo.event_id, created_by: req.admin.id })
+          .where({ id: photo.event_id })
           .first();
-        if (!event) return res.status(404).json({ error: 'Photo not found' });
+        if (event && event.created_by && event.created_by !== req.admin.id) {
+          return res.status(404).json({ error: 'Photo not found' });
+        }
       }
 
       if (photo.processing_status !== 'failed') {

backend/src/routes/auth.js

@@ -2,9 +2,10 @@ const express = require('express');
 const bcrypt = require('bcrypt');
 const jwt = require('jsonwebtoken');
 const { body, validationResult } = require('express-validator');
-const { db } = require('../database/db');
+const { db, logActivity } = require('../database/db');
 const { formatBoolean } = require('../utils/dbCompat');
 const { verifyRecaptcha } = require('../services/recaptcha');
+const mfaService = require('../services/mfaService');
 const { 
   trackFailedAttempt,
   trackSuccessfulLogin,
@@ -14,6 +15,7 @@ const {
 } = require('../utils/authSecurity');
 const { endSession } = require('../middleware/sessionTimeout');
 const { revokeToken } = require('../utils/tokenRevocation');
+const { timingSafeEqualStr } = require('../utils/timingSafe');
 const logger = require('../utils/logger');
 const { errorResponse } = require('../utils/routeHelpers');
 const {
@@ -33,6 +35,49 @@ const {
 } = require('../utils/passwordValidation');
 const router = express.Router();
 
+/**
+ * Finish a successful admin login: reset the lockout counter, stamp
+ * last_login, mint the 24h admin JWT, set the HttpOnly cookie, and return the
+ * user payload. Shared by the direct (no-MFA) path and the MFA-verify path so
+ * both produce an identical session. `lockoutKey` is the identifier the user
+ * typed (username or email) so success/failure tracking stays in one bucket.
+ */
+async function completeAdminLogin(req, res, admin, ipAddress, userAgent, lockoutKey) {
+  await trackSuccessfulLogin(lockoutKey, ipAddress, userAgent);
+
+  await db('admin_users').where('id', admin.id).update({
+    last_login: new Date(),
+    last_login_ip: ipAddress
+  });
+
+  const token = jwt.sign({
+    id: admin.id,
+    username: admin.username,
+    type: 'admin',
+    role: admin.role_name,
+    ip: ipAddress,
+    loginTime: Date.now()
+  }, process.env.JWT_SECRET, {
+    expiresIn: '24h',
+    issuer: 'picpeak-auth'
+  });
+
+  setAdminAuthCookie(res, token);
+
+  return res.json({
+    user: {
+      id: admin.id,
+      username: admin.username,
+      email: admin.email,
+      mustChangePassword: admin.must_change_password || false,
+      role: admin.role_name ? {
+        name: admin.role_name,
+        displayName: admin.role_display_name
+      } : null
+    }
+  });
+}
+
 // Admin login with enhanced security
 router.post('/admin/login', [
   body('username').notEmpty().trim(),
@@ -95,48 +140,131 @@ router.post('/admin/login', [
       return res.status(401).json({ error: getGenericAuthError() });
     }
 
-    // Successful login
-    await trackSuccessfulLogin(username, ipAddress, userAgent);
-
-    // Update last login and login metadata
-    await db('admin_users').where('id', admin.id).update({
-      last_login: new Date(),
-      last_login_ip: ipAddress
-    });
-
-    // Generate token with additional claims including role
-    const token = jwt.sign({
-      id: admin.id,
-      username: admin.username,
-      type: 'admin',
-      role: admin.role_name, // Add role to JWT
-      ip: ipAddress,
-      loginTime: Date.now()
-    }, process.env.JWT_SECRET, {
-      expiresIn: '24h',
-      issuer: 'picpeak-auth'
-    });
-
-    setAdminAuthCookie(res, token);
-
-    // Token is delivered via HttpOnly cookie only (not in response body)
-    res.json({
-      user: {
+    // Second factor: if this admin has TOTP enabled, do NOT complete the login
+    // yet. Issue a short-lived, single-purpose mfa_pending token and require the
+    // code via /admin/login/mfa. We deliberately don't reset the lockout counter
+    // (trackSuccessfulLogin) or stamp last_login until the second factor passes,
+    // so MFA brute-force is still gated by the account lockout. `loginId` carries
+    // the typed identifier so the verify step tracks the same lockout bucket.
+    if (mfaService.isEnrolled(admin)) {
+      const mfaToken = jwt.sign({
         id: admin.id,
         username: admin.username,
-        email: admin.email,
-        mustChangePassword: admin.must_change_password || false,
-        role: admin.role_name ? {
-          name: admin.role_name,
-          displayName: admin.role_display_name
-        } : null
-      }
-    });
+        type: 'mfa_pending',
+        loginId: username
+      }, process.env.JWT_SECRET, {
+        expiresIn: '5m',
+        issuer: 'picpeak-auth'
+      });
+      return res.json({ mfaRequired: true, mfaToken });
+    }
+
+    return await completeAdminLogin(req, res, admin, ipAddress, userAgent, username);
   } catch (error) {
     errorResponse(res, error, 500, 'Login failed');
   }
 });
 
+// Second-factor verification. Exchanges the short-lived mfa_pending token
+// (from /admin/login) plus a TOTP or recovery code for a full admin session.
+router.post('/admin/login/mfa', [
+  body('mfaToken').notEmpty(),
+  body('code').notEmpty().trim()
+], async (req, res) => {
+  try {
+    const errors = validationResult(req);
+    if (!errors.isEmpty()) {
+      return res.status(400).json({ errors: errors.array() });
+    }
+
+    const { mfaToken, code } = req.body;
+    const ipAddress = getClientIp(req);
+    const userAgent = req.headers['user-agent'] || '';
+
+    let decoded;
+    try {
+      decoded = jwt.verify(mfaToken, process.env.JWT_SECRET, {
+        algorithms: ['HS256'],
+        issuer: 'picpeak-auth'
+      });
+    } catch (err) {
+      return res.status(401).json({
+        error: 'Your verification session expired. Please sign in again.',
+        code: 'MFA_SESSION_EXPIRED'
+      });
+    }
+
+    if (decoded.type !== 'mfa_pending') {
+      return res.status(401).json({ error: getGenericAuthError() });
+    }
+
+    const lockoutKey = decoded.loginId || decoded.username;
+    const lockoutStatus = await checkAccountLockout(lockoutKey);
+    if (lockoutStatus.isLocked) {
+      return res.status(423).json({
+        error: 'Account temporarily locked due to too many failed attempts',
+        retryAfter: lockoutStatus.remainingTime
+      });
+    }
+
+    const admin = await db('admin_users')
+      .leftJoin('roles', 'roles.id', 'admin_users.role_id')
+      .where('admin_users.id', decoded.id)
+      .select(
+        'admin_users.*',
+        'roles.name as role_name',
+        'roles.display_name as role_display_name'
+      )
+      .first();
+
+    if (!admin || !admin.is_active || !mfaService.isEnrolled(admin)) {
+      return res.status(401).json({ error: getGenericAuthError() });
+    }
+
+    // TOTP first, then a one-time recovery code.
+    let ok = mfaService.verifyTotpEncrypted(code, admin.two_factor_secret);
+    let usedRecovery = false;
+    let remainingHashes = null;
+    if (!ok) {
+      const stored = mfaService.parseRecoveryCodes(admin.two_factor_recovery_codes);
+      const result = await mfaService.consumeRecoveryCode(code, stored);
+      if (result.matched) {
+        ok = true;
+        usedRecovery = true;
+        remainingHashes = result.remainingHashes;
+      }
+    }
+
+    if (!ok) {
+      await trackFailedAttempt(lockoutKey, ipAddress, userAgent);
+      return res.status(401).json({ error: 'Invalid verification code', code: 'MFA_INVALID' });
+    }
+
+    if (usedRecovery) {
+      await db('admin_users').where('id', admin.id).update({
+        two_factor_recovery_codes: JSON.stringify(remainingHashes),
+        updated_at: new Date()
+      });
+      await logActivity('admin_mfa_recovery_used',
+        { admin_id: admin.id, remaining: remainingHashes.length },
+        null,
+        { type: 'admin', id: admin.id, name: admin.username }
+      );
+    }
+
+    await logActivity('admin_mfa_login',
+      { admin_id: admin.id, method: usedRecovery ? 'recovery_code' : 'totp' },
+      null,
+      { type: 'admin', id: admin.id, name: admin.username }
+    );
+
+    return await completeAdminLogin(req, res, admin, ipAddress, userAgent, lockoutKey);
+  } catch (error) {
+    logger.error('MFA verification error:', error);
+    res.status(500).json({ error: 'Verification failed' });
+  }
+});
+
 // Logout endpoint
 router.post('/logout', async (req, res) => {
   try {
@@ -410,7 +538,7 @@ router.post('/gallery/share-login', [
 
     const expectedToken = getEventShareToken(event);
 
-    if (!expectedToken || token !== expectedToken) {
+    if (!expectedToken || !timingSafeEqualStr(token, expectedToken)) {
       await trackFailedAttempt(shareIdentifier, ipAddress, userAgent);
       return res.status(401).json({ error: 'Invalid or expired share link' });
     }

backend/src/routes/galleryFeedback.js

@@ -1,6 +1,5 @@
 const express = require('express');
 const router = express.Router();
-const { photoAuth } = require('../middleware/photoAuth');
 const { verifyGalleryAccess, denySlideshowToken } = require('../middleware/gallery');
 const { feedbackRateLimit, generateGuestIdentifier } = require('../middleware/feedbackRateLimit');
 const { resolveGuest } = require('../middleware/guestAuth');

backend/src/routes/protectedImages.js

@@ -9,6 +9,7 @@ const { resolvePhotoStorageKey, resolvePhotoFilePath } = require('../services/ph
 const { withLocalCopy } = require('../services/imageProcessor');
 const crypto = require('crypto');
 const logger = require('../utils/logger');
+const { timingSafeEqualStr } = require('../utils/timingSafe');
 
 const router = express.Router();
 
@@ -33,9 +34,9 @@ function verifyImageToken(token) {
     const decoded = Buffer.from(data, 'base64').toString();
     const [photoId, expires] = decoded.split(':');
     
-    // Verify signature
+    // Verify signature (constant-time — avoids leaking the HMAC byte-by-byte)
     const expectedSignature = crypto.createHmac('sha256', secret).update(decoded).digest('hex');
-    if (signature !== expectedSignature) {
+    if (!timingSafeEqualStr(signature, expectedSignature)) {
       return null;
     }
     

backend/src/routes/secureImages.js

@@ -1,6 +1,6 @@
 const express = require('express');
 const { db } = require('../database/db');
-const { verifyGalleryAccess } = require('../middleware/gallery');
+const { verifyGalleryAccess, denySlideshowToken } = require('../middleware/gallery');
 const secureImageService = require('../services/secureImageService');
 const secureImageMiddleware = require('../middleware/secureImageMiddleware');
 const logger = require('../utils/logger');
@@ -23,7 +23,7 @@ router.post('/:slug/generate-token', async (req, res, next) => {
   // Add slug to request for verifyGalleryAccess
   req.requestedSlug = req.params.slug;
   next();
-}, verifyGalleryAccess, async (req, res) => {
+}, verifyGalleryAccess, denySlideshowToken, async (req, res) => {
   try {
     const { photoId, accessType = 'view' } = req.body;
     
@@ -273,6 +273,7 @@ router.get('/:slug/secure-download/:photoId/:token',
     next();
   },
   verifyGalleryAccess,
+  denySlideshowToken,
   async (req, res) => {
     try {
       const { photoId, token } = req.params;

backend/src/services/mfaService.js

@@ -0,0 +1,183 @@
+/**
+ * mfaService — TOTP (RFC 6238) multi-factor auth for admin accounts (#738).
+ *
+ * Responsibilities:
+ *   - generate/verify TOTP secrets (otplib, standard SHA1/6-digit/30s so
+ *     Google Authenticator / Authy / 1Password all work);
+ *   - encrypt the secret at rest (AES-256-GCM) so a DB leak alone doesn't
+ *     yield working authenticator seeds;
+ *   - generate/verify one-time recovery codes, hashed (bcrypt) and single-use;
+ *   - build the otpauth:// URI + QR data-URL for enrollment.
+ *
+ * The encryption key is derived (scrypt) from MFA_ENCRYPTION_KEY when set,
+ * otherwise from JWT_SECRET. Rotating either invalidates stored secrets —
+ * the same blast radius as rotating JWT_SECRET already has for sessions, and
+ * `reset-admin-mfa.js` is the recovery path.
+ */
+
+const crypto = require('crypto');
+const bcrypt = require('bcrypt');
+const { authenticator } = require('otplib');
+const QRCode = require('qrcode');
+
+// Standard TOTP params; window:1 tolerates ±1 step (30s) of clock drift.
+authenticator.options = { window: 1 };
+
+const ISSUER = 'PicPeak';
+const RECOVERY_CODE_COUNT = 10;
+const RECOVERY_CODE_BYTES = 10; // ~80 bits of entropy per code
+const RECOVERY_BCRYPT_ROUNDS = 10;
+
+const ENC_ALGO = 'aes-256-gcm';
+const ENC_SALT = 'picpeak-mfa-secret-v1'; // fixed: derivation must be stable
+
+function getEncryptionKey() {
+  const material = process.env.MFA_ENCRYPTION_KEY || process.env.JWT_SECRET;
+  if (!material) {
+    throw new Error('mfaService: MFA_ENCRYPTION_KEY or JWT_SECRET must be set');
+  }
+  return crypto.scryptSync(material, ENC_SALT, 32);
+}
+
+/** Generate a fresh base32 TOTP secret. */
+function generateSecret() {
+  return authenticator.generateSecret();
+}
+
+/** AES-256-GCM encrypt a secret → "iv.tag.ciphertext" (all base64url). */
+function encryptSecret(plainSecret) {
+  const key = getEncryptionKey();
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(ENC_ALGO, key, iv);
+  const ct = Buffer.concat([cipher.update(plainSecret, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return [iv, tag, ct].map((b) => b.toString('base64url')).join('.');
+}
+
+/** Reverse of encryptSecret. Throws on tamper/wrong key. */
+function decryptSecret(stored) {
+  const key = getEncryptionKey();
+  const [ivB64, tagB64, ctB64] = String(stored).split('.');
+  if (!ivB64 || !tagB64 || !ctB64) {
+    throw new Error('mfaService: malformed encrypted secret');
+  }
+  const decipher = crypto.createDecipheriv(ENC_ALGO, key, Buffer.from(ivB64, 'base64url'));
+  decipher.setAuthTag(Buffer.from(tagB64, 'base64url'));
+  const pt = Buffer.concat([decipher.update(Buffer.from(ctB64, 'base64url')), decipher.final()]);
+  return pt.toString('utf8');
+}
+
+/** Verify a 6-digit TOTP code against the (plaintext) secret. */
+function verifyTotp(code, plainSecret) {
+  if (!code || !plainSecret) return false;
+  try {
+    return authenticator.verify({ token: String(code).replace(/\s+/g, ''), secret: plainSecret });
+  } catch {
+    return false;
+  }
+}
+
+/** Verify a code against a STORED (encrypted) secret. */
+function verifyTotpEncrypted(code, storedSecret) {
+  try {
+    return verifyTotp(code, decryptSecret(storedSecret));
+  } catch {
+    return false;
+  }
+}
+
+/** otpauth:// URI for an authenticator app. */
+function buildOtpauthUri(accountName, plainSecret) {
+  return authenticator.keyuri(accountName, ISSUER, plainSecret);
+}
+
+/** QR code (PNG data URL) for the otpauth URI. */
+async function buildQrDataUrl(otpauthUri) {
+  return QRCode.toDataURL(otpauthUri, { errorCorrectionLevel: 'M', margin: 1, width: 240 });
+}
+
+/** Format a raw code as human-friendly groups, e.g. "abcd-efgh-jk". */
+function formatRecoveryCode(raw) {
+  return raw.match(/.{1,4}/g).join('-');
+}
+
+/**
+ * Generate RECOVERY_CODE_COUNT one-time codes. Returns the plaintext codes
+ * (shown to the admin ONCE) and their bcrypt hashes (persisted).
+ */
+async function generateRecoveryCodes() {
+  const plain = [];
+  const hashed = [];
+  for (let i = 0; i < RECOVERY_CODE_COUNT; i++) {
+    // base32-ish, lowercase, no ambiguous chars
+    const raw = crypto.randomBytes(RECOVERY_CODE_BYTES)
+      .toString('base64')
+      .replace(/[^a-zA-Z0-9]/g, '')
+      .toLowerCase()
+      .slice(0, 10);
+    const code = formatRecoveryCode(raw);
+    plain.push(code);
+    hashed.push(await bcrypt.hash(code, RECOVERY_BCRYPT_ROUNDS));
+  }
+  return { plain, hashed };
+}
+
+function normalizeRecoveryInput(code) {
+  return String(code || '').trim().toLowerCase();
+}
+
+/**
+ * Check a submitted recovery code against the stored hash array. On match,
+ * returns the remaining hashes (matched one removed — single use). On miss,
+ * matched:false and the array unchanged.
+ *
+ * @param {string[]} storedHashes
+ * @returns {Promise<{matched: boolean, remainingHashes: string[]}>}
+ */
+async function consumeRecoveryCode(code, storedHashes) {
+  const input = normalizeRecoveryInput(code);
+  const hashes = Array.isArray(storedHashes) ? storedHashes : [];
+  if (!input) return { matched: false, remainingHashes: hashes };
+  for (let i = 0; i < hashes.length; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await bcrypt.compare(input, hashes[i])) {
+      const remaining = hashes.slice(0, i).concat(hashes.slice(i + 1));
+      return { matched: true, remainingHashes: remaining };
+    }
+  }
+  return { matched: false, remainingHashes: hashes };
+}
+
+/** True when an admin row has MFA enabled (coerces SQLite/PG boolean shapes). */
+function isEnrolled(admin) {
+  const v = admin && admin.two_factor_enabled;
+  return v === true || v === 1 || v === '1';
+}
+
+/** Parse the DB column (JSON text) into an array of hashes. */
+function parseRecoveryCodes(raw) {
+  if (!raw) return [];
+  try {
+    const arr = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return Array.isArray(arr) ? arr : [];
+  } catch {
+    return [];
+  }
+}
+
+module.exports = {
+  generateSecret,
+  encryptSecret,
+  decryptSecret,
+  verifyTotp,
+  verifyTotpEncrypted,
+  buildOtpauthUri,
+  buildQrDataUrl,
+  generateRecoveryCodes,
+  consumeRecoveryCode,
+  parseRecoveryCodes,
+  isEnrolled,
+  formatRecoveryCode,
+  ISSUER,
+  RECOVERY_CODE_COUNT,
+};

backend/src/services/picpeakExportService.js

@@ -0,0 +1,231 @@
+'use strict';
+
+// Portable ".picpeak" export — a single, self-describing archive that can be
+// downloaded from one instance and re-uploaded to another via the web UI only
+// (see picpeakImportService for the receiving half).
+//
+// Deliberately ENGINE-NEUTRAL: instead of a native pg_dump / sqlite .backup
+// (which can only ever restore into the same engine and version), each table is
+// written as NDJSON. The target rebuilds its own schema by running migrations,
+// then loads these rows into it — so an older backup restores cleanly onto a
+// newer target (forward-only), and pg↔pg / sqlite↔sqlite both work.
+//
+// This module is purely additive: it introduces a new artifact and touches no
+// existing backup/restore path.
+
+const fs = require('fs');
+const fsp = require('fs').promises;
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const archiver = require('archiver');
+const { db } = require('../database/db');
+const knexConfig = require('../../knexfile');
+const { getStoragePath } = require('../config/storage');
+const logger = require('../utils/logger');
+const packageJson = require('../../package.json');
+
+// Bump only on a breaking change to the on-disk layout below.
+const PICPEAK_FORMAT_VERSION = 1;
+
+// Never exported as data — the target owns these (its own migrations set them).
+const EXCLUDED_TABLES = new Set(['knex_migrations', 'knex_migrations_lock']);
+
+// Storage subdirs holding non-recalculable blobs — always included.
+const DOC_DIRS = ['business-docs', 'uploads'];
+// Original gallery photos — only when includePhotos is true (large; otherwise
+// the admin re-uploads originals per gallery and previews are re-rendered).
+const PHOTO_DIRS = ['events/active', 'events/archived'];
+
+const isPostgres = () => knexConfig.client === 'pg';
+
+// db.raw returns `{ rows: [...] }` on Postgres and a bare array on SQLite.
+const rawRows = (result) => (isPostgres() ? result.rows : result);
+
+// All user tables, minus knex bookkeeping. Introspected at runtime so the
+// export never rots as tables are added (no hardcoded list to maintain).
+async function listDataTables() {
+  let names;
+  if (isPostgres()) {
+    const result = await db.raw(`
+      SELECT table_name AS name
+      FROM information_schema.tables
+      WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+      ORDER BY table_name
+    `);
+    names = rawRows(result).map((r) => r.name);
+  } else {
+    const result = await db.raw(`
+      SELECT name FROM sqlite_master
+      WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+      ORDER BY name
+    `);
+    names = rawRows(result).map((r) => r.name);
+  }
+  return names.filter((n) => !EXCLUDED_TABLES.has(n));
+}
+
+// The latest applied migration — recorded in the manifest so the importer can
+// refuse a backup that is NEWER than the target (forward-only guarantee).
+async function getLatestMigration() {
+  try {
+    const rows = await db('knex_migrations').orderBy('id', 'desc').limit(1);
+    return rows[0]?.name || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// Write one table to <dataDir>/<table>.ndjson (one JSON object per line).
+// Returns { rowCount, checksum } for the manifest. JSON.stringify serialises
+// Dates to ISO strings, which re-import cleanly on both engines.
+//
+// Uses a plain select rather than knex `.stream()`: streaming on Postgres pulls
+// in the optional `pg-query-stream` dependency (not bundled), so it throws on
+// pg. A select works on both engines with no extra dependency. Rows are DB
+// metadata (blobs live on disk under files/), so holding a table in memory is
+// fine for the instance sizes PicPeak targets.
+async function writeTableNdjson(table, dataDir) {
+  const outPath = path.join(dataDir, `${table}.ndjson`);
+  const hash = crypto.createHash('sha256');
+  const rows = await db(table).select('*');
+  const lines = rows.map((row) => {
+    const line = JSON.stringify(row);
+    hash.update(`${line}\n`);
+    return line;
+  });
+  await fsp.writeFile(outPath, lines.length ? `${lines.join('\n')}\n` : '', 'utf8');
+  return { rowCount: rows.length, checksum: hash.digest('hex') };
+}
+
+// Recursively collect files under a storage subdir as { abs, rel } where rel is
+// relative to the storage root (so the importer restores the same layout).
+async function collectDir(subdir, storageRoot, acc) {
+  const abs = path.join(storageRoot, subdir);
+  let entries;
+  try {
+    entries = await fsp.readdir(abs, { withFileTypes: true });
+  } catch (_) {
+    return; // subdir may not exist on this install — skip silently
+  }
+  for (const entry of entries) {
+    const childRel = path.join(subdir, entry.name);
+    if (entry.isDirectory()) {
+      await collectDir(childRel, storageRoot, acc);
+    } else if (entry.isFile()) {
+      acc.push({ abs: path.join(storageRoot, childRel), rel: childRel });
+    }
+  }
+}
+
+async function collectFiles(includePhotos) {
+  const storageRoot = getStoragePath();
+  const dirs = includePhotos ? [...DOC_DIRS, ...PHOTO_DIRS] : [...DOC_DIRS];
+  const acc = [];
+  for (const d of dirs) {
+    await collectDir(d, storageRoot, acc);
+  }
+  return acc;
+}
+
+/**
+ * Build a .picpeak archive.
+ * @param {Object} opts
+ * @param {boolean} [opts.includePhotos=false] include original gallery photos
+ * @param {string}  [opts.outDir] where to write the file (defaults to a temp dir)
+ * @returns {Promise<{ filePath: string, manifest: object }>}
+ */
+async function createPicpeak({ includePhotos = false, outDir } = {}) {
+  const staging = await fsp.mkdtemp(path.join(os.tmpdir(), 'picpeak-export-'));
+  const dataDir = path.join(staging, 'data');
+  await fsp.mkdir(dataDir, { recursive: true });
+
+  try {
+    // 1. Dump every table to NDJSON, tracking counts + checksums.
+    const tables = await listDataTables();
+    const tableMeta = {};
+    for (const table of tables) {
+      tableMeta[table] = await writeTableNdjson(table, dataDir);
+    }
+
+    // 2. Gather the non-recalculable blobs (PDFs, business-docs, uploads, and
+    //    optionally original photos).
+    const files = await collectFiles(includePhotos);
+
+    // 3. Manifest — everything the importer needs to validate + reconstruct.
+    const manifest = {
+      format: PICPEAK_FORMAT_VERSION,
+      kind: 'picpeak-backup',
+      created_at: new Date().toISOString(),
+      app_version: packageJson.version || null,
+      database: {
+        engine: isPostgres() ? 'pg' : 'sqlite',
+        latest_migration: await getLatestMigration(),
+      },
+      options: { includePhotos: !!includePhotos },
+      tables: tableMeta,
+      file_count: files.length,
+      // NOTE: contains secrets (SMTP password, admin hashes, API keys) in plain
+      // text — the download surface must warn about this.
+      contains_secrets: true,
+    };
+    await fsp.writeFile(
+      path.join(staging, 'manifest.json'),
+      JSON.stringify(manifest, null, 2),
+      'utf8'
+    );
+
+    // 4. Zip staging (manifest + data/) plus the blobs under files/. The final
+    //    .picpeak lands in outDir (caller-managed) or a fresh temp dir; either
+    //    way the NDJSON scratch (which holds plaintext secrets) is always
+    //    removed in `finally` below.
+    const targetDir = outDir || (await fsp.mkdtemp(path.join(os.tmpdir(), 'picpeak-out-')));
+    await fsp.mkdir(targetDir, { recursive: true });
+    const stamp = manifest.created_at.replace(/[:.]/g, '-');
+    const filePath = path.join(targetDir, `picpeak-backup-${stamp}.picpeak`);
+
+    try {
+      await new Promise((resolve, reject) => {
+        const output = fs.createWriteStream(filePath);
+        const archive = archiver('zip', { zlib: { level: 9 } });
+        output.on('close', resolve);
+        output.on('error', reject);
+        archive.on('error', reject);
+        // Surface archiver warnings (e.g. a file vanished mid-run) instead of
+        // silently shipping an incomplete archive.
+        archive.on('warning', (err) => reject(err));
+        archive.pipe(output);
+        archive.file(path.join(staging, 'manifest.json'), { name: 'manifest.json' });
+        archive.directory(dataDir, 'data');
+        for (const f of files) {
+          archive.file(f.abs, { name: path.posix.join('files', f.rel.split(path.sep).join('/')) });
+        }
+        archive.finalize();
+      });
+    } catch (err) {
+      // Archiver failed → the partial .picpeak holds plaintext secrets and is
+      // useless; remove our own temp out dir so it isn't orphaned. A
+      // caller-supplied outDir is left untouched.
+      if (!outDir) await fsp.rm(targetDir, { recursive: true, force: true }).catch(() => {});
+      throw err;
+    }
+
+    logger.info(
+      `[picpeak-export] wrote ${filePath} (${tables.length} tables, ${files.length} files, includePhotos=${!!includePhotos})`
+    );
+    return { filePath, manifest };
+  } finally {
+    // Always remove the NDJSON scratch dir — it contains a plaintext dump of
+    // every table (secrets included). The final .picpeak is elsewhere.
+    await fsp.rm(staging, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+module.exports = {
+  PICPEAK_FORMAT_VERSION,
+  EXCLUDED_TABLES,
+  createPicpeak,
+  // exported for reuse/testing
+  listDataTables,
+  collectFiles,
+};

backend/src/services/picpeakImportService.js

@@ -0,0 +1,271 @@
+'use strict';
+
+// Receiving half of the GUI-only backup roundtrip: takes a ".picpeak" produced
+// by picpeakExportService and restores it onto THIS instance.
+//
+// Restore semantics (agreed design): FULL OVERRIDE — every table is wiped and
+// replaced by the backup's rows — EXCEPT the current logged-in admin account,
+// which is preserved so the operator is never locked out. A backup admin whose
+// email collides with the current account is overwritten with the current
+// account's credentials (so the operator's known password keeps working).
+//
+// Same-engine only (pg↔pg / sqlite↔sqlite) and forward-only (an older backup
+// restores onto a newer instance; a newer backup is refused). The target's own
+// schema is used as-is — we never replay the backup's DDL.
+
+const fs = require('fs');
+const fsp = require('fs').promises;
+const path = require('path');
+const os = require('os');
+const StreamZip = require('node-stream-zip');
+const { db } = require('../database/db');
+const knexConfig = require('../../knexfile');
+const { getStoragePath } = require('../config/storage');
+const { hasColumnCached } = require('../utils/schemaCache');
+const logger = require('../utils/logger');
+const { PICPEAK_FORMAT_VERSION, EXCLUDED_TABLES, listDataTables } = require('./picpeakExportService');
+
+const isPostgres = () => knexConfig.client === 'pg';
+
+// Compare migrations by their numeric filename prefix (001_, 107_, 129_ …).
+function migrationOrder(name) {
+  const m = String(name || '').match(/^(\d+)/);
+  return m ? parseInt(m[1], 10) : -1;
+}
+
+async function readManifestFromZip(picpeakPath) {
+  const zip = new StreamZip.async({ file: picpeakPath });
+  try {
+    return JSON.parse((await zip.entryData('manifest.json')).toString('utf8'));
+  } finally {
+    await zip.close();
+  }
+}
+
+// Returns an array of human-readable blockers ([] = OK to restore).
+async function validateManifest(manifest) {
+  const errors = [];
+  if (!manifest || manifest.kind !== 'picpeak-backup') {
+    return ['This file is not a PicPeak backup (.picpeak).'];
+  }
+  if (Number(manifest.format) > PICPEAK_FORMAT_VERSION) {
+    errors.push('This backup was created by a newer version of PicPeak. Update this instance first.');
+  }
+  const engine = isPostgres() ? 'pg' : 'sqlite';
+  if (manifest.database && manifest.database.engine && manifest.database.engine !== engine) {
+    errors.push(`Database engine mismatch: the backup is "${manifest.database.engine}" but this instance is "${engine}". Restore is only supported between matching engines.`);
+  }
+  // Forward-only: the target schema must be at least as new as the backup's.
+  let targetLatest = null;
+  try {
+    const applied = await db('knex_migrations').orderBy('id', 'desc').limit(1);
+    targetLatest = applied[0] ? applied[0].name : null;
+  } catch (_) {
+    // No knex_migrations table (e.g. some test harnesses) — skip the check.
+  }
+  const backupLatest = manifest.database ? manifest.database.latest_migration : null;
+  if (backupLatest && targetLatest && migrationOrder(backupLatest) > migrationOrder(targetLatest)) {
+    errors.push('This backup is from a newer database schema than this instance. Update this instance to at least the backup version before restoring.');
+  }
+  return errors;
+}
+
+function parseNdjson(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  return fs
+    .readFileSync(filePath, 'utf8')
+    .split('\n')
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l));
+}
+
+// Re-insert the operator's account inside the restore transaction so they keep
+// working credentials. If the backup already loaded an admin with the same
+// email, overwrite that row's credentials with the current account's (current
+// creds win); otherwise insert the snapshot with a fresh id.
+async function reinjectCurrentAdmin(trx, currentAdmin) {
+  if (!currentAdmin) return;
+  const existing = await trx('admin_users').whereRaw('lower(email) = lower(?)', [currentAdmin.email]).first();
+  if (existing) {
+    await trx('admin_users').where({ id: existing.id }).update({
+      password_hash: currentAdmin.password_hash,
+      is_active: currentAdmin.is_active,
+      must_change_password: currentAdmin.must_change_password,
+    });
+  } else {
+    const row = { ...currentAdmin };
+    delete row.id; // let the engine assign a fresh id to avoid collision
+    await trx('admin_users').insert(row);
+  }
+}
+
+// The json/jsonb columns of a table (Postgres only). The pg driver returns
+// jsonb as parsed JS values, so on re-insert they must be serialised back to
+// valid JSON text — otherwise a scalar like the string "PicPeak" is sent
+// unquoted and pg rejects it ("invalid input syntax for type json").
+async function jsonColumnsFor(trx, table) {
+  if (!isPostgres()) return new Set();
+  const res = await trx.raw(
+    "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ? AND data_type IN ('json', 'jsonb')",
+    [table]
+  );
+  return new Set(res.rows.map((r) => r.column_name));
+}
+
+function serialiseJsonColumns(rows, jsonCols) {
+  if (!jsonCols.size) return rows;
+  return rows.map((row) => {
+    const out = { ...row };
+    for (const col of jsonCols) {
+      if (out[col] !== undefined && out[col] !== null) out[col] = JSON.stringify(out[col]);
+    }
+    return out;
+  });
+}
+
+// Whole-DB replace in one transaction with FK enforcement suspended (pg:
+// session_replication_role=replica on the trx connection, reset before commit;
+// sqlite: defer_foreign_keys so checks run at commit). knex_migrations is never
+// in the data set, so the target's schema/migration state is left intact.
+async function replaceAllTables(tables, dataDir, currentAdmin) {
+  await db.transaction(async (trx) => {
+    if (isPostgres()) {
+      try {
+        await trx.raw("SET session_replication_role = 'replica'");
+      } catch (_) {
+        // session_replication_role requires a Postgres SUPERUSER. The bundled
+        // postgres image's role is one; managed Postgres (RDS / Cloud SQL / …)
+        // app users usually are not. Fail fast with a clear message BEFORE any
+        // rows are deleted — the transaction rolls back, so nothing is wiped.
+        const err = new Error(
+          'Restore needs a PostgreSQL superuser to suspend foreign-key checks during the full replace, but this instance’s database user is not a superuser (common on managed Postgres such as RDS or Cloud SQL). Restore onto the bundled Postgres, or grant the role superuser for the restore.'
+        );
+        err.statusCode = 400;
+        throw err;
+      }
+    } else {
+      await trx.raw('PRAGMA defer_foreign_keys = ON');
+    }
+
+    for (const table of tables) {
+      await trx(table).del();
+    }
+    for (const table of tables) {
+      const rows = parseNdjson(path.join(dataDir, `${table}.ndjson`));
+      if (!rows.length) continue;
+      const jsonCols = await jsonColumnsFor(trx, table);
+      await trx.batchInsert(table, serialiseJsonColumns(rows, jsonCols), 100);
+    }
+
+    await reinjectCurrentAdmin(trx, currentAdmin);
+
+    // Reset the pg session flag BEFORE the connection returns to the pool.
+    if (isPostgres()) await trx.raw("SET session_replication_role = 'origin'");
+  });
+}
+
+// Copy the archive's files/ tree into storage, overwriting existing files.
+async function restoreFiles(stagingDir) {
+  const src = path.join(stagingDir, 'files');
+  if (!fs.existsSync(src)) return 0;
+  const storageRoot = getStoragePath();
+  let count = 0;
+  async function walk(rel) {
+    const abs = path.join(src, rel);
+    for (const entry of await fsp.readdir(abs, { withFileTypes: true })) {
+      const childRel = path.join(rel, entry.name);
+      if (entry.isDirectory()) {
+        await walk(childRel);
+      } else if (entry.isFile()) {
+        const dest = path.join(storageRoot, childRel);
+        await fsp.mkdir(path.dirname(dest), { recursive: true });
+        await fsp.copyFile(path.join(src, childRel), dest);
+        count += 1;
+      }
+    }
+  }
+  await walk('');
+  return count;
+}
+
+// Does the restored data reference an external-media library? If so the caller
+// shows a banner telling the admin to (re)configure the external-media mount on
+// this instance — those files are NOT in the backup by design.
+async function detectExternalMedia() {
+  try {
+    if (await hasColumnCached('events', 'external_path')) {
+      const row = await db('events').whereNotNull('external_path').first();
+      if (row) return true;
+    }
+    if (await hasColumnCached('photos', 'external_relpath')) {
+      const row = await db('photos').whereNotNull('external_relpath').first();
+      if (row) return true;
+    }
+  } catch (_) {
+    // Best-effort — a detection miss is not worth failing the restore.
+  }
+  return false;
+}
+
+/**
+ * Restore a .picpeak onto this instance.
+ * @param {Object} opts
+ * @param {string} opts.picpeakPath  path to the uploaded/staged .picpeak
+ * @param {number} [opts.currentAdminId]  admin to preserve across the wipe
+ * @returns {Promise<{restored:boolean, tables:number, filesRestored:number, usesExternalMedia:boolean, manifest:object}>}
+ */
+async function importFromPicpeak({ picpeakPath, currentAdminId }) {
+  const manifest = await readManifestFromZip(picpeakPath);
+  const blockers = await validateManifest(manifest);
+  if (blockers.length) {
+    const err = new Error(blockers[0]);
+    err.statusCode = 400;
+    err.validation = blockers;
+    throw err;
+  }
+
+  const currentAdmin = currentAdminId
+    ? await db('admin_users').where({ id: currentAdminId }).first()
+    : null;
+
+  const staging = await fsp.mkdtemp(path.join(os.tmpdir(), 'picpeak-import-'));
+  try {
+    const zip = new StreamZip.async({ file: picpeakPath });
+    try {
+      await zip.extract(null, staging);
+    } finally {
+      await zip.close();
+    }
+
+    const dataDir = path.join(staging, 'data');
+    // Only touch tables that (a) the uploaded manifest lists AND (b) actually
+    // exist as real tables in THIS database. listDataTables() already excludes
+    // knex_migrations/_lock (EXCLUDED_TABLES), so a crafted or corrupted
+    // .picpeak can never make the restore delete the migration bookkeeping — or
+    // any table that isn't a genuine data table here.
+    const dbTables = new Set(await listDataTables());
+    const manifestTables = Object.keys(manifest.tables || {});
+    const tables = manifestTables.filter((tbl) => dbTables.has(tbl) && !EXCLUDED_TABLES.has(tbl));
+    const skipped = manifestTables.filter((tbl) => !tables.includes(tbl));
+    if (skipped.length) {
+      logger.warn(`[picpeak-import] ignoring ${skipped.length} backup table(s) not present in this DB (or protected): ${skipped.join(', ')}`);
+    }
+
+    await replaceAllTables(tables, dataDir, currentAdmin);
+    const filesRestored = await restoreFiles(staging);
+    const usesExternalMedia = await detectExternalMedia();
+
+    logger.info(
+      `[picpeak-import] restored ${tables.length} tables, ${filesRestored} files (externalMedia=${usesExternalMedia})`
+    );
+    return { restored: true, tables: tables.length, filesRestored, usesExternalMedia, manifest };
+  } finally {
+    await fsp.rm(staging, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+module.exports = {
+  importFromPicpeak,
+  readManifestFromZip,
+  validateManifest,
+};

backend/src/utils/rateLimitSecurity.js

@@ -32,7 +32,7 @@ function hasValidAdminToken(req) {
     
     // Critical: Verify token is valid before skipping rate limit
     // This prevents invalid tokens from bypassing rate limiting
-    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    const decoded = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });
     
     // Additional validation
     if (!decoded || typeof decoded !== 'object') {

backend/src/utils/timingSafe.js

@@ -0,0 +1,22 @@
+const crypto = require('crypto');
+
+/**
+ * Constant-time string comparison for secrets (share tokens, HMAC
+ * signatures, etc.). Returns false for non-strings or length mismatch
+ * without leaking timing beyond the (non-secret) length. Prevents an
+ * attacker from recovering a token byte-by-byte via response-time
+ * differences of a naive `a === b`.
+ */
+function timingSafeEqualStr(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') {
+    return false;
+  }
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(ab, bb);
+}
+
+module.exports = { timingSafeEqualStr };