release(v3.9.0): persistent-token key lifecycle updates and admin rotation workflow

- docker(startup): remove baked persistent-token key defaults and auto-generate a unique key for pristine installs
- admin(ui): warn when the instance is still using a legacy or placeholder persistent-token key and expose guided rotation for compatible installs
- admin(crypto): add persistent-token key rotation that re-encrypts stored secrets and expires remember-me sessions
- docs(docker): refresh docker run / compose guidance so metadata-backed generated keys are documented as the default path

Author: error311

CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## Changes 03/14/2026 (v3.9.0)
+
+`release(v3.9.0): persistent-token key lifecycle updates and admin rotation workflow`
+
+**Commit message**  
+
+```text
+release(v3.9.0): persistent-token key lifecycle updates and admin rotation workflow
+
+- docker(startup): remove baked persistent-token key defaults and auto-generate a unique key for pristine installs
+- admin(ui): warn when the instance is still using a legacy or placeholder persistent-token key and expose guided rotation for compatible installs
+- admin(crypto): add persistent-token key rotation that re-encrypts stored secrets and expires remember-me sessions
+- docs(docker): refresh docker run / compose guidance so metadata-backed generated keys are documented as the default path
+```
+
+**Added**  
+
+- **Admin rotation workflow for persistent-token keys**
+  - Added an admin-only rotation action that generates a new persistent-token key, re-encrypts stored secret-bearing data, writes `metadata/persistent_tokens.key`, and intentionally expires remember-me sessions.
+  - Added an admin warning card with rotation guidance for instances still using a legacy or placeholder persistent-token key.
+
+**Changed**  
+
+- **Docker startup behavior**
+  - Pristine Docker installs now auto-generate and persist a unique persistent-token key in `metadata/persistent_tokens.key`.
+  - Existing installs without an explicit key continue on the legacy compatibility path until the operator rotates them.
+- **Docker examples and env reference**
+  - Updated `docker run`, compose, and env-reference guidance so `PERSISTENT_TOKENS_KEY` is optional by default and no published placeholder value is documented.
+
+**Fixed**  
+
+- **Persistent-token key lifecycle**
+  - Existing installs can now move off the legacy compatibility key without losing admin config, user-permissions, stored TOTP secrets, or source credentials.
+  - Remember-me sessions are explicitly expired during rotation instead of being left in a mixed-key state.
+
+**Security**  
+
+- **Install defaults**
+  - The runtime image no longer ships a baked-in persistent-token key default.
+  - New Docker installs now start with instance-unique key material by default as long as `metadata/` is persistent.
+
+---
+
 ## Changes 03/12/2026 (v3.8.0)
 
 `release(v3.8.0): share-link admin guards and centralized safe-upload policy`

Dockerfile

@@ -25,11 +25,12 @@ RUN composer install --no-dev --optimize-autoloader  # production-ready autoload
 FROM ubuntu:24.04
 LABEL by=error311
 
+# No baked-in PERSISTENT_TOKENS_KEY default is shipped in the image.
+# Pristine installs generate and persist one at runtime in /var/www/metadata.
 ENV DEBIAN_FRONTEND=noninteractive \
     HOME=/root \
     LC_ALL=C.UTF-8 LANG=en_US.UTF-8 LANGUAGE=en_US.UTF-8 TERM=xterm \
     UPLOAD_MAX_FILESIZE=5G POST_MAX_SIZE=5G TOTAL_UPLOAD_SIZE=5G \
-    PERSISTENT_TOKENS_KEY=default_please_change_this_key \
     PUID=99 PGID=100
 
 ARG INSTALL_FFMPEG=0

README.md

@@ -162,14 +162,21 @@ The easiest way to run FileRise is the official Docker image.
 
 ### Option A – Quick start (docker run)
 
+Pristine Docker installs can omit `PERSISTENT_TOKENS_KEY`. FileRise will generate a unique key on first start and persist it in `metadata/persistent_tokens.key`.
+
+If you prefer to manage the key yourself, set one before first start:
+
+```bash
+export PERSISTENT_TOKENS_KEY="$(openssl rand -hex 32)"
+```
+
 ```bash
 docker run -d \
   --name filerise \
   -p 8080:80 \
   -e TIMEZONE="America/New_York" \
   -e TOTAL_UPLOAD_SIZE="10G" \
   -e SECURE="false" \
-  -e PERSISTENT_TOKENS_KEY="default_please_change_this_key" \
   -e SCAN_ON_START="true" \
   -e CHOWN_ON_START="true" \
   -v ~/filerise/uploads:/var/www/uploads \
@@ -194,6 +201,13 @@ On first launch you’ll be guided through creating the **initial admin user**.
 > (for example `~/filerise/uploads` or `/mnt/user/appdata/FileRise/uploads`),
 > not the root of a huge media share.
 >
+> 🔐 **Persistent tokens key note**
+>
+> Keep `/var/www/metadata` persistent. On a pristine install, FileRise writes the
+> generated persistent tokens key to `metadata/persistent_tokens.key`. If you
+> choose to manage the key via env instead, keep that value stable for the life
+> of the instance.
+>
 > If you really want FileRise to sit “on top of” an existing share, use a
 > subfolder (e.g. `/mnt/user/media/filerise_root`) instead of the share root,
 > so scans and permission changes stay scoped to that folder.
@@ -211,7 +225,7 @@ services:
       TIMEZONE: "America/New_York"
       TOTAL_UPLOAD_SIZE: "10G"
       SECURE: "false"
-      PERSISTENT_TOKENS_KEY: "default_please_change_this_key"
+      PERSISTENT_TOKENS_KEY: "${PERSISTENT_TOKENS_KEY:-}" # optional; blank = pristine installs auto-generate and persist a key in metadata
       SCAN_ON_START: "true"   # auto-index existing files on startup
       CHOWN_ON_START: "true"  # fix permissions on uploads/metadata on startup
     volumes:
@@ -226,14 +240,20 @@ Bring it up with:
 docker compose up -d
 ```
 
+You can leave `PERSISTENT_TOKENS_KEY` blank for pristine installs, or set it in your shell / `.env` if you want to manage the key yourself:
+
+```bash
+export PERSISTENT_TOKENS_KEY="$(openssl rand -hex 32)"
+```
+
 ### Common environment variables
 
 | Variable                | Required | Example                          | What it does |
 |-------------------------|----------|----------------------------------|--------------|
 | `TIMEZONE`              | ✅       | `America/New_York`               | PHP / container timezone. |
 | `TOTAL_UPLOAD_SIZE`     | ✅       | `10G`                            | Max total upload size per request; also used to set PHP/Apache upload limits. |
 | `SECURE`                | ✅       | `false`                          | `true` when running behind HTTPS / a reverse proxy, else `false`. |
-| `PERSISTENT_TOKENS_KEY` | ✅       | `change_me_super_secret`         | Secret used to encrypt stored secrets (tokens, permissions, admin config). **Do not leave this at the default.** |
+| `PERSISTENT_TOKENS_KEY` | Optional | `openssl rand -hex 32`           | Secret used to encrypt stored secrets (tokens, permissions, admin config). If omitted on a pristine Docker install, FileRise auto-generates and persists one in `metadata/persistent_tokens.key`; existing installs without an explicit key stay on the legacy compatibility path until rotated. |
 | `SCAN_ON_START`         | Optional | `true`                           | If `true`, runs a scan once on container start to index existing files. |
 | `CHOWN_ON_START`        | Optional | `true`                           | If `true`, recursively normalizes ownership/permissions on `uploads/` + `metadata/`. |
 | `PUID`                  | Optional | `99`                             | If running as root, remap `www-data` user to this UID (e.g. Unraid’s 99).                             |
@@ -324,11 +344,13 @@ Back up these paths (Docker volumes or host directories):
 
 Notes:
 - Logs live in `/var/www/metadata/log` and can be rotated or pruned.
-- Keep your `PERSISTENT_TOKENS_KEY` consistent when restoring backups.
+- If you use the auto-generated key path, back up `/var/www/metadata/persistent_tokens.key` with the rest of `metadata/`.
+- If you manage the key via env, keep your `PERSISTENT_TOKENS_KEY` consistent when restoring backups.
 
 ## First-run security checklist
 
-- Set a strong `PERSISTENT_TOKENS_KEY` (encrypts tokens, permissions, admin config).
+- Persist `/var/www/metadata` so the generated persistent tokens key survives container recreation.
+- Either set your own strong `PERSISTENT_TOKENS_KEY` or let a pristine install generate one and then back up `metadata/persistent_tokens.key`.
 - Use HTTPS and set `SECURE="true"` when behind TLS/reverse proxy.
 - If behind a proxy, set `FR_TRUSTED_PROXIES` and `FR_IP_HEADER`.
 - Set `FR_PUBLISHED_URL` (and `FR_BASE_PATH` if needed) so share links are correct.

config/config.php

@@ -39,7 +39,7 @@
 define('TRASH_DIR',     UPLOAD_DIR . 'trash/');
 define('TIMEZONE',      'America/New_York');
 define('DATE_TIME_FORMAT','m/d/y  h:iA');
-define('TOTAL_UPLOAD_SIZE','5G');
+define('TOTAL_UPLOAD_SIZE', '5G');
 define('REGEX_FOLDER_NAME','/^(?!^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$)(?!.*[. ]$)(?:[^<>:"\/\\\\|?*\x00-\x1F]{1,255})(?:[\/\\\\][^<>:"\/\\\\|?*\x00-\x1F]{1,255})*$/xu');
 define('PATTERN_FOLDER_NAME','[\p{L}\p{N}_\-\s\/\\\\]+');
 define('REGEX_FILE_NAME', '/^[^\x00-\x1F\/\\\\]{1,255}$/u');
@@ -191,14 +191,100 @@ function decryptData($encryptedData, $encryptionKey)
     return openssl_decrypt($ct, $cipher, $encryptionKey, OPENSSL_RAW_DATA, $iv);
 }
 
-// Load encryption key
-$envKey = getenv('PERSISTENT_TOKENS_KEY');
-if ($envKey === false || $envKey === '') {
-    $encryptionKey = 'default_please_change_this_key';
-    error_log('WARNING: Using default encryption key. Please set PERSISTENT_TOKENS_KEY in your environment.');
-} else {
-    $encryptionKey = $envKey;
+function fr_get_persistent_tokens_key_file_path(): string
+{
+    return rtrim((string)META_DIR, "/\\") . DIRECTORY_SEPARATOR . 'persistent_tokens.key';
+}
+
+function fr_resolve_persistent_tokens_key(): array
+{
+    static $resolved = null;
+    if (is_array($resolved)) {
+        return $resolved;
+    }
+
+    $defaultKey = 'default_please_change_this_key';
+    $publishedPlaceholders = [$defaultKey, 'please_change_this_@@'];
+
+    $envKeyRaw = getenv('PERSISTENT_TOKENS_KEY');
+    $envKey = trim($envKeyRaw === false ? '' : (string)$envKeyRaw);
+
+    $sourceHintRaw = getenv('PERSISTENT_TOKENS_KEY_SOURCE');
+    $sourceHint = trim($sourceHintRaw === false ? '' : (string)$sourceHintRaw);
+
+    $keyFile = fr_get_persistent_tokens_key_file_path();
+    $fileKey = '';
+    if (is_file($keyFile)) {
+        $raw = @file_get_contents($keyFile);
+        if ($raw !== false) {
+            $fileKey = trim((string)$raw);
+        }
+    }
+
+    $source = 'legacy_default';
+    $key = $defaultKey;
+    if ($envKey !== '') {
+        $key = $envKey;
+        if (in_array($sourceHint, ['env', 'file', 'generated_file', 'legacy_default'], true)) {
+            $source = $sourceHint;
+        } else {
+            $source = 'env';
+        }
+    } elseif ($fileKey !== '') {
+        $key = $fileKey;
+        $source = 'file';
+    }
+
+    $usesPublishedPlaceholder = in_array($key, $publishedPlaceholders, true);
+    $usesLegacyDefault = ($source === 'legacy_default');
+    $autoGenerated = ($source === 'generated_file');
+    $needsAttention = $usesLegacyDefault || $usesPublishedPlaceholder;
+
+    $warning = '';
+    $recommendedAction = '';
+    if ($usesLegacyDefault) {
+        $warning = 'FileRise is using the legacy built-in persistent tokens key because no explicit key is configured.';
+        $recommendedAction = 'Set a unique key for new installs. For existing installs, plan a controlled rotation because changing the key can invalidate remember-me tokens and break decryption of stored secrets until they are re-encrypted.';
+    } elseif ($usesPublishedPlaceholder) {
+        $warning = 'FileRise is using a published placeholder persistent tokens key value.';
+        $recommendedAction = 'Replace it with a unique key. For existing installs, rotate carefully because changing the key can invalidate remember-me tokens and break decryption of stored secrets until they are re-encrypted.';
+    } elseif ($autoGenerated) {
+        $recommendedAction = 'This Docker install auto-generated a key and stored it on disk. Back up metadata/persistent_tokens.key or set PERSISTENT_TOKENS_KEY explicitly before migrating the instance.';
+    }
+
+    if ($needsAttention) {
+        error_log('WARNING: ' . $warning);
+    }
+
+    $resolved = [
+        'key' => $key,
+        'source' => $source,
+        'usesPublishedPlaceholder' => $usesPublishedPlaceholder,
+        'usesLegacyDefault' => $usesLegacyDefault,
+        'autoGenerated' => $autoGenerated,
+        'needsAttention' => $needsAttention,
+        'warning' => $warning,
+        'recommendedAction' => $recommendedAction,
+        'keyFilePresent' => ($fileKey !== ''),
+    ];
+
+    return $resolved;
+}
+
+function fr_load_persistent_tokens_key(): string
+{
+    $resolved = fr_resolve_persistent_tokens_key();
+    $key = (string)($resolved['key'] ?? '');
+    return $key;
+}
+
+function fr_get_persistent_tokens_key_status(): array
+{
+    $resolved = fr_resolve_persistent_tokens_key();
+    unset($resolved['key']);
+    return $resolved;
 }
+$encryptionKey = fr_load_persistent_tokens_key();
 // Ensure encryption key is always available via $GLOBALS, even when this file
 // is required from function scope (e.g. API helper bootstrap wrappers).
 $GLOBALS['encryptionKey'] = $encryptionKey;
@@ -342,7 +428,8 @@ function loadUserPermissions($username)
 if (file_exists($adminConfigFile)) {
     $encrypted = file_get_contents($adminConfigFile);
     $decrypted = decryptData($encrypted, $encryptionKey);
-    $adminCfg  = json_decode($decrypted, true) ?: [];
+    $json      = ($decrypted !== false) ? $decrypted : $encrypted;
+    $adminCfg  = is_string($json) ? (json_decode($json, true) ?: []) : [];
 
     $loginOpts = $adminCfg['loginOptions'] ?? [];
 

docker-compose.yml

@@ -23,7 +23,9 @@ services:
       DATE_TIME_FORMAT: "${DATE_TIME_FORMAT:-m/d/y  h:iA}"
       TOTAL_UPLOAD_SIZE: "${TOTAL_UPLOAD_SIZE:-5G}"
       SECURE: "${SECURE:-false}"
-      PERSISTENT_TOKENS_KEY: "${PERSISTENT_TOKENS_KEY:-please_change_this_@@}"
+      # Optional: leave blank for pristine installs to auto-generate and persist
+      # a unique key in ./data/metadata/persistent_tokens.key.
+      PERSISTENT_TOKENS_KEY: "${PERSISTENT_TOKENS_KEY:-}"
       PUID: "${PUID:-1000}"
       PGID: "${PGID:-1000}"
       CHOWN_ON_START: "${CHOWN_ON_START:-true}"

docs/wiki/Environment-Variables-Full-Reference.md

@@ -4,7 +4,7 @@ This page lists all known environment variables read by FileRise core and the Do
 
 Notes:
 - Defaults reflect current code. Your deployment may override them.
-- Docker sets some defaults via the image (see `Dockerfile`/`start.sh`).
+- Docker sets some defaults via the image and startup script (see `Dockerfile` / `start.sh`). `PERSISTENT_TOKENS_KEY` can be omitted for pristine Docker installs, in which case FileRise auto-generates and persists one in `metadata/persistent_tokens.key`.
 
 ---
 
@@ -16,7 +16,7 @@ Notes:
 | `DATE_TIME_FORMAT` | `m/d/y  h:iA` | UI date/time format. |
 | `TOTAL_UPLOAD_SIZE` | `5G` | Max total upload size per request; used to set PHP upload limits and Apache `LimitRequestBody` in Docker. |
 | `SECURE` | auto | Set `true` when behind HTTPS to generate secure cookies/links. |
-| `PERSISTENT_TOKENS_KEY` | `default_please_change_this_key` | Encrypts stored secrets (tokens, permissions, admin config). Always change in production. |
+| `PERSISTENT_TOKENS_KEY` | empty | Encrypts stored secrets (tokens, permissions, admin config). Pristine Docker installs auto-generate one in `metadata/persistent_tokens.key`; back up that file or set a managed env key before migrating the instance. Legacy installs without an explicit key continue using the historical fallback until rotated deliberately. |
 | `FR_IGNORE_REGEX` | empty | Newline-separated regex patterns to ignore entries in listings/indexing; env overrides admin config. |
 
 ---

public/api/admin/rotatePersistentTokensKey.php

@@ -0,0 +1,32 @@
+<?php
+declare(strict_types=1);
+/**
+ * @OA\Post(
+ *   path="/api/admin/rotatePersistentTokensKey.php",
+ *   summary="Rotate persistent tokens key",
+ *   description="Generates a new persistent tokens key, re-encrypts stored secrets, and expires remember-me sessions. Requires an authenticated admin session and CSRF token.",
+ *   operationId="adminRotatePersistentTokensKey",
+ *   tags={"Admin"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="X-CSRF-Token", in="header", required=true, @OA\Schema(type="string")),
+ *   @OA\RequestBody(
+ *     required=true,
+ *     @OA\JsonContent(
+ *       required={"confirmRememberMeExpiry","confirmMaintenanceWindow"},
+ *       @OA\Property(property="confirmRememberMeExpiry", type="boolean", example=true),
+ *       @OA\Property(property="confirmMaintenanceWindow", type="boolean", example=true)
+ *     )
+ *   ),
+ *   @OA\Response(response=200, description="Rotation result"),
+ *   @OA\Response(response=400, description="Missing confirmation"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=409, description="Rotation not allowed in current deployment mode"),
+ *   @OA\Response(response=500, description="Server error")
+ * )
+ */
+
+require_once __DIR__ . '/../../../config/config.php';
+
+$ctrl = new \FileRise\Http\Controllers\AdminController();
+$ctrl->rotatePersistentTokensKey();