security: fix pre-auth bypasses and restore Immich 3.x compatibility (#378)

Seven security issues from an audit, plus album pages and the map coming
up empty against Immich 3.x. Verified against a real Immich 3.0.3
instance in a production build.

Security:
- Admin session forgery via a hardcoded 'dev-fallback-secret' signing key
  that bypassed the production AUTH_SECRET guard
- /api/map ignored album passwords and returned working asset tokens;
  rewriting ?size=thumbnail to ?size=original downloaded full-resolution
  originals from protected albums
- Admin login had no rate limit, and the client IP came from a spoofable
  header, so rotating it bypassed every limit in the app
- Raw Immich asset UUIDs were serialized into the RSC payload
- Album tokens never expired server-side; a captured token replayed forever
- Path traversal into the Immich API via an unvalidated album id
- /admin ran with no enforced CSP (only Report-Only reached it)

TRUSTED_PROXIES is replaced by TRUSTED_PROXY_HOPS. The old variable
matched proxy IPs against the socket peer address, which self-hosted
Next.js never exposes, so the check could never pass: unset, the limiter
read a spoofable header; set, every request shared one bucket and a single
client could rate-limit the whole site. Migrates automatically.

Immich 3.x: GET /albums/:id no longer embeds assets. Assets now come from
POST /search/metadata with withExif: true — without that flag EXIF is
omitted and grid aspect ratios, the lightbox panel and map markers stay
empty. Drops support for Immich below 3.0, which now logs a warning.

Upgrade: requires Immich 3.0+; set TRUSTED_PROXY_HOPS (nginx = 1);
visitors of protected areas and admin sessions must log in once more.

91 unit tests (25 new); the new admin-auth and rate-limit cases were
confirmed to fail against the pre-fix code.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

lib/env.ts

@@ -11,7 +11,7 @@ export interface Env {
   CACHE_TTL: number;
   RATE_LIMIT_RPM: number;
   AUTH_SECRET?: string;
-  TRUSTED_PROXIES: string[];
+  TRUSTED_PROXY_HOPS: number;
   WEBHOOK_SECRET?: string;
   ADMIN_PASSWORD?: string;
 }
@@ -39,6 +39,26 @@ function parseEnv(): Env {
   const rateLimit =
     rateLimitStr && !isNaN(parseInt(rateLimitStr, 10)) ? parseInt(rateLimitStr, 10) : 1500;
 
+  // Number of reverse proxies in front of the app. Determines how far from the
+  // right of X-Forwarded-For the real client IP sits. nginx/Traefik/Caddy = 1;
+  // add 1 for each additional layer (e.g. Cloudflare in front of nginx = 2).
+  const hopsStr = process.env.TRUSTED_PROXY_HOPS;
+  let trustedProxyHops = hopsStr && !isNaN(parseInt(hopsStr, 10)) ? parseInt(hopsStr, 10) : 0;
+
+  // TRUSTED_PROXIES (removed) matched proxy IPs against the socket peer address,
+  // which self-hosted Next.js never exposes — so it silently disabled per-client
+  // rate limiting and lumped every visitor into one shared bucket. Migrate the
+  // common single-proxy case rather than leaving those deploys broken.
+  if (trustedProxyHops === 0 && process.env.TRUSTED_PROXIES) {
+    trustedProxyHops = 1;
+    console.warn(
+      '\n⚠️  TRUSTED_PROXIES is deprecated and has no effect. Assuming TRUSTED_PROXY_HOPS=1.\n' +
+        '   Set TRUSTED_PROXY_HOPS explicitly (nginx/Traefik/Caddy = 1) and remove TRUSTED_PROXIES.\n',
+    );
+  }
+
+  if (trustedProxyHops < 0) trustedProxyHops = 0;
+
   return {
     IMMICH_API_URL: apiUrl,
     IMMICH_API_KEY: apiKey as string,
@@ -47,10 +67,7 @@ function parseEnv(): Env {
     CACHE_TTL: Math.max(0, cacheTtl),
     RATE_LIMIT_RPM: Math.max(1, rateLimit),
     AUTH_SECRET: process.env.AUTH_SECRET,
-    TRUSTED_PROXIES: (process.env.TRUSTED_PROXIES || '')
-      .split(',')
-      .map((ip) => ip.trim())
-      .filter((ip) => ip !== ''),
+    TRUSTED_PROXY_HOPS: trustedProxyHops,
     WEBHOOK_SECRET: process.env.WEBHOOK_SECRET || undefined,
     ADMIN_PASSWORD: process.env.ADMIN_PASSWORD || undefined,
   };