Stirling-Tools
diff --git a/‎app/proprietary/src/main/java/stirling/software/proprietary/storage/controller/StorageEncryptionAdminController.java‎
Lines changed: 10 additions & 0 deletions b/‎app/proprietary/src/main/java/stirling/software/proprietary/storage/controller/StorageEncryptionAdminController.java‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎app/proprietary/src/main/java/stirling/software/proprietary/storage/crypto/FileEncryptionMasterKey.java‎
Lines changed: 32 additions & 4 deletions b/‎app/proprietary/src/main/java/stirling/software/proprietary/storage/crypto/FileEncryptionMasterKey.java‎
Lines changed: 32 additions & 4 deletions
diff --git a/‎app/proprietary/src/main/java/stirling/software/proprietary/storage/model/api/StorageEncryptionStatusResponse.java‎
Lines changed: 6 additions & 0 deletions b/‎app/proprietary/src/main/java/stirling/software/proprietary/storage/model/api/StorageEncryptionStatusResponse.java‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎app/proprietary/src/test/java/stirling/software/proprietary/storage/crypto/FileEncryptionMasterKeySourceTest.java‎
Lines changed: 30 additions & 0 deletions b/‎app/proprietary/src/test/java/stirling/software/proprietary/storage/crypto/FileEncryptionMasterKeySourceTest.java‎
Lines changed: 30 additions & 0 deletions
diff --git a/‎devGuide/STORAGE_ENCRYPTION_AT_REST.md‎
Lines changed: 31 additions & 3 deletions b/‎devGuide/STORAGE_ENCRYPTION_AT_REST.md‎
Lines changed: 31 additions & 3 deletions
diff --git a/‎frontend/editor/public/locales/en-US/translation.toml‎
Lines changed: 166 additions & 0 deletions b/‎frontend/editor/public/locales/en-US/translation.toml‎
Lines changed: 166 additions & 0 deletions
diff --git a/‎frontend/editor/src/core/i18n/translationAudit.ts‎
Lines changed: 5 additions & 0 deletions b/‎frontend/editor/src/core/i18n/translationAudit.ts‎
Lines changed: 5 additions & 0 deletions
@@ -95,22 +95,32 @@ private StorageEncryptionStatusResponse buildStatus() {
                         .toList();
         String fingerprint = null;
         Integer masterKeyVersion = null;
+        String masterKeySource = null;
         if (encryptionState.isMaterialised()) {
             try {
                 FileEncryptionKeyService keyService = encryptionState.keyService();
                 fingerprint = keyService.masterKey().fingerprint();
                 masterKeyVersion = keyService.masterKey().currentVersion();
+                masterKeySource = keyService.masterKey().source().wireName();
             } catch (StorageEncryptionException ignored) {
                 // Materialisation failed; status still reports counts and key rows.
             }
         }
+        // Counted in the database so the total stays right if `keys` is ever paged.
+        long pendingRotationRows =
+                masterKeyVersion == null
+                        ? 0
+                        : keyRepository.countByMasterKeyVersionLessThan(masterKeyVersion);
         return new StorageEncryptionStatusResponse(
                 encryptionState.isWriteEnabled(),
                 encryptionState.isMaterialised(),
                 fingerprint,
                 masterKeyVersion,
+                masterKeySource,
+                applicationProperties.getStorage().getProvider(),
                 storedFileRepository.countByEncryptionKeyIdIsNotNull(),
                 storedFileRepository.countByEncryptionKeyIdIsNull(),
+                pendingRotationRows,
                 keys);
     }
 
 
@@ -49,6 +49,24 @@ public class FileEncryptionMasterKey {
     private final SecretKey key;
     private final SecretKey previousKey;
     private final int currentVersion;
+    private final Source source;
+
+    /** Where the master key came from, so the UI can warn about an unbacked-up generated key. */
+    public enum Source {
+        CONFIG("config"),
+        ENVIRONMENT("environment"),
+        GENERATED("generated");
+
+        private final String wireName;
+
+        Source(String wireName) {
+            this.wireName = wireName;
+        }
+
+        public String wireName() {
+            return wireName;
+        }
+    }
 
     public FileEncryptionMasterKey(String configuredKey, boolean clusterEnabled) {
         this(configuredKey, null, CURRENT_VERSION, clusterEnabled);
@@ -66,7 +84,9 @@ public FileEncryptionMasterKey(
             String previousKeyBase64,
             int currentVersion,
             boolean clusterEnabled) {
-        this.key = resolveKey(configuredKey, clusterEnabled);
+        Resolved resolved = resolveKey(configuredKey, clusterEnabled);
+        this.key = resolved.key();
+        this.source = resolved.source();
         this.previousKey =
                 previousKeyBase64 == null || previousKeyBase64.isBlank()
                         ? null
@@ -90,19 +110,27 @@ public int currentVersion() {
         return currentVersion;
     }
 
+    public Source source() {
+        return source;
+    }
+
     public boolean hasPreviousKey() {
         return previousKey != null;
     }
 
-    private static SecretKey resolveKey(String configuredKey, boolean clusterEnabled) {
+    private record Resolved(SecretKey key, Source source) {}
+
+    private static Resolved resolveKey(String configuredKey, boolean clusterEnabled) {
         String configured = configuredKey;
         String source = "stirling.security.fileEncryptionKey";
+        Source provenance = Source.CONFIG;
         if (configured == null || configured.isBlank()) {
             configured = System.getenv("STIRLING_FILE_ENCRYPTION_KEY");
             source = "STIRLING_FILE_ENCRYPTION_KEY";
+            provenance = Source.ENVIRONMENT;
         }
         if (configured != null && !configured.isBlank()) {
-            return decodeKey(configured, source);
+            return new Resolved(decodeKey(configured, source), provenance);
         }
         if (clusterEnabled) {
             throw new IllegalStateException(
@@ -111,7 +139,7 @@ private static SecretKey resolveKey(String configuredKey, boolean clusterEnabled
                             + " stirling.security.fileEncryptionKey) to the same value on every"
                             + " node.");
         }
-        return loadOrCreateKeyFile();
+        return new Resolved(loadOrCreateKeyFile(), Source.GENERATED);
     }
 
     /**
 
@@ -13,8 +13,14 @@ public record StorageEncryptionStatusResponse(
         boolean active,
         String masterKeyFingerprint,
         Integer masterKeyVersion,
+        /** Where the master key came from: config, environment or generated. */
+        String masterKeySource,
+        /** Backend serving stored blobs: local, database or s3. */
+        String provider,
         long encryptedFiles,
         long plaintextFiles,
+        /** Key rows still wrapped by an older master key, counted in the database. */
+        long pendingRotationRows,
         List<KeyInfo> keys) {
 
     public record KeyInfo(
 
@@ -0,0 +1,30 @@
+package stirling.software.proprietary.storage.crypto;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.Base64;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Provenance drives the "this key was generated for you" warning, which is the only prompt an
+ * operator gets to back up a key they never chose.
+ */
+class FileEncryptionMasterKeySourceTest {
+
+    private static final String MASTER = Base64.getEncoder().encodeToString(new byte[32]);
+
+    @Test
+    void configuredKeyReportsConfig() {
+        FileEncryptionMasterKey key = new FileEncryptionMasterKey(MASTER, false);
+
+        assertThat(key.source()).isEqualTo(FileEncryptionMasterKey.Source.CONFIG);
+        assertThat(key.source().wireName()).isEqualTo("config");
+    }
+
+    @Test
+    void wireNamesMatchTheValuesTheUiSwitchesOn() {
+        assertThat(FileEncryptionMasterKey.Source.ENVIRONMENT.wireName()).isEqualTo("environment");
+        assertThat(FileEncryptionMasterKey.Source.GENERATED.wireName()).isEqualTo("generated");
+    }
+}
@@ -74,6 +74,29 @@ Disabling only stops encrypting *new* writes. Existing encrypted files stay read
 key material is present — the decrypt path is always active and is never licence-gated, so a lapsed
 licence cannot lock you out of your own data.
 
+## Backing up the master key
+
+Every scope key in `file_encryption_keys` is wrapped by the master key, so the master key is the
+single thing standing between a backup and unreadable files. Losing it makes every encrypted stored
+file unrecoverable — there is no recovery path, by design.
+
+Back it up when you enable encryption, not later:
+
+- **Key set in config or environment.** Store the base64 value in whatever holds your other
+  secrets. The value in `stirling.security.fileEncryptionKey` or `STIRLING_FILE_ENCRYPTION_KEY`
+  *is* the backup.
+- **Auto-generated key.** The server wrote `configs/file-encryption.key` on first use and logged a
+  warning. Copy that file somewhere durable and off the machine. Nothing else in the install holds
+  a copy. `/status` reports `masterKeySource: "generated"` for this case, and the admin UI shows a
+  warning until the key is configured explicitly.
+
+To check a backup matches the running system, compare its fingerprint against the one in the
+startup log or in `/status` — see [Status and backup verification](#status-and-backup-verification).
+The fingerprint is a SHA-256 prefix, so it can be compared safely without exposing key material.
+
+Restoring is just putting the key back: set it in config or the environment, or restore the file to
+`configs/file-encryption.key`, and start the server. No re-encryption is involved.
+
 ## Encrypting files that already exist
 
 Enabling the flag does not touch the existing plaintext backlog. To convert it:
@@ -163,9 +186,14 @@ Two semantics worth knowing when reading the trail:
 curl http://localhost:8080/api/v1/admin/storage-encryption/status
 ```
 
-Reports whether writes are encrypted, the master-key fingerprint, encrypted vs plaintext file
-counts, and every key row with its status history. All endpoints under
-`/api/v1/admin/storage-encryption` require an admin account.
+Reports whether writes are encrypted, the master-key fingerprint, where the key came from
+(`masterKeySource`: `config`, `environment` or `generated`), the storage backend, encrypted vs
+plaintext file counts, the number of key rows still on an older master key, and every key row with
+its status history. All endpoints under `/api/v1/admin/storage-encryption` require an admin
+account.
+
+The same information is on the Storage tab under Infrastructure in the admin UI, which is the
+surface most operators should use.
 
 ## What this protects against
 
 
@@ -8344,6 +8344,172 @@ subtitleCreated = "Copy this secret now — it won't be shown again."
 title = "Create API key"
 titleCreated = "Key created"
 
+[portal.infrastructure.encryption]
+heading = "Encryption at rest"
+hintLabel = "More about this section"
+subheading = "Stored files are encrypted before they reach disk, the database or object storage."
+unknown = "Unknown"
+
+[portal.infrastructure.encryption.auditNotice]
+description = "Encryption is active on this licence, but encrypt, decrypt, revocation and export events are not written to the audit trail. Encryption itself is unaffected."
+title = "Audit events need an Enterprise licence"
+
+[portal.infrastructure.encryption.coverage]
+decryptOnlyNote = "New uploads are stored as plaintext. Files encrypted earlier are still readable."
+encrypted = "Encrypted files"
+heading = "Coverage"
+percentEncrypted = "{{percent}}% encrypted"
+plaintext = "Plaintext files"
+progressLabel = "{{percent}}% of stored files encrypted"
+subheading = "Covers files in My Files and signing workflows. Files a pipeline reads in place, including network sources, are not stored here and are not encrypted."
+
+[portal.infrastructure.encryption.error]
+action = "That key change could not be applied. Please try again."
+keyMissing = "That key no longer exists. Refresh to see the current list."
+migrationStart = "The migration could not be started. Please try again."
+rotate = "The re-wrap could not be completed. Please try again."
+
+[portal.infrastructure.encryption.generatedKey]
+backupGuide = "How to back it up"
+description = "No encryption key was configured, so one was created on this server. Back it up now: if it is lost, encrypted files cannot be recovered."
+title = "This key was generated for you"
+
+[portal.infrastructure.encryption.keys]
+changedAt = "Changed {{when}}"
+changedBy = "By {{actor}}"
+changedByAt = "By {{actor}} on {{when}}"
+heading = "Scope keys"
+keyVersion = "Version {{version}}"
+neverChanged = "Never changed"
+restore = "Restore access"
+retiredNote = "A retired key still decrypts the files stored under it, but a newer key wraps new uploads."
+revoke = "Revoke"
+subheading = "One key per scope. Revoking a key blocks reads of everything stored under it."
+
+[portal.infrastructure.encryption.keys.columns]
+actions = "Actions"
+lastChange = "Last change"
+scope = "Scope"
+status = "Status"
+
+[portal.infrastructure.encryption.keys.empty]
+description = "A key is created the first time someone uploads a file, not at startup."
+title = "No keys yet"
+
+[portal.infrastructure.encryption.masterKey]
+backend = "Storage backend"
+compareNote = "Compare this against the fingerprint in your key backup and in the startup log."
+copied = "Copied"
+copy = "Copy"
+copyFailed = "This browser would not allow copying. The fingerprint is selected, so copy it manually."
+fingerprint = "Fingerprint"
+fingerprintHelp = "What is this fingerprint for?"
+heading = "Master key"
+notMaterialised = "The key machinery has not started on this node yet."
+s3StreamingNote = "While anything is encrypted, object-store downloads are streamed through this server rather than redirected, so they use its bandwidth."
+subheading = "Wraps every scope key. Never shown or accepted over the API."
+version = "Version"
+
+[portal.infrastructure.encryption.migration]
+backlog_one = "{{formatted}} file is stored as plaintext and can be encrypted now."
+backlog_other = "{{formatted}} files are stored as plaintext and can be encrypted now."
+encrypted = "Encrypted"
+failedCount = "Failed"
+heading = "Encrypt existing files"
+hint = "Encrypts the plaintext backlog left from before encryption was switched on. Progress is held in memory, so a backend restart resets it to not started. Running again skips files that are already encrypted."
+noBacklog = "Every stored file is already encrypted."
+progressLabel = "{{processed}} of {{total}} files encrypted"
+requiresEncryptionOn = "Switch encryption on before running this: the backlog is encrypted using the same write path as new uploads."
+runAgain = "Run again"
+skipped = "Skipped"
+skippedHelp = "What does skipped mean?"
+skippedNote = "Skipped files were replaced by a user while the run was in progress, so their copy was left alone."
+start = "Start"
+startedAt = "Started {{when}}"
+
+[portal.infrastructure.encryption.migration.confirm]
+cancel = "Cancel"
+confirm = "Start encrypting"
+noCancel = "There is no stop control. Once started, the run continues until it finishes or encryption is switched off."
+rewrites_one = "Rewrites {{formatted}} stored file, replacing the plaintext copy with an encrypted one."
+rewrites_other = "Rewrites {{formatted}} stored files, replacing the plaintext copies with encrypted ones."
+throttled = "The job is throttled and safe to re-run. Files already encrypted are skipped."
+title = "Encrypt the existing backlog?"
+
+[portal.infrastructure.encryption.migration.failed]
+description = "Encryption was switched off while the migration was running, so the remaining files were left untouched. Switch it back on and run again."
+title = "The run stopped early"
+
+[portal.infrastructure.encryption.migration.state]
+COMPLETED = "Completed"
+FAILED = "Failed"
+IDLE = "Not started"
+RUNNING = "Running"
+
+[portal.infrastructure.encryption.revoke]
+cancel = "Cancel"
+clusterDelay = "On a cluster, other nodes apply this within 60 seconds."
+confirm = "Revoke access"
+readsFail = "Files already stored under this key stop opening, for everyone."
+reversible = "This is reversible. No key material is deleted."
+title = "Revoke access to this key?"
+uploadsContinue = "New uploads keep working. They get a fresh key, so they stay readable."
+
+[portal.infrastructure.encryption.rotation]
+currentVersion = "Current version"
+heading = "Master key rotation"
+hint = "Re-wraps scope keys under a new master key; file contents are never rewritten. The new key is set in configuration and applied on restart, so this button only performs the re-wrap."
+pendingRows = "Rows on an older version"
+rewrap = "Re-wrap keys"
+rewrapped_one = "{{count}} key row re-wrapped."
+rewrapped_other = "{{count}} key rows re-wrapped."
+runbook = "Rotation runbook"
+
+[portal.infrastructure.encryption.rotation.confirm]
+cancel = "Cancel"
+confirm = "Re-wrap keys"
+noFiles = "File contents are not touched. Only the key table is rewritten."
+rerunnable = "Safe to run again if it does not finish."
+rewraps_one = "Re-wraps {{count}} key row under the current master key."
+rewraps_other = "Re-wraps {{count}} key rows under the current master key."
+title = "Re-wrap the key table?"
+
+[portal.infrastructure.encryption.rotation.pending]
+description = "Do not remove the previous key from configuration yet. Files under those keys would stop opening."
+title_one = "{{count}} key row is still on the previous master key"
+title_other = "{{count}} key rows are still on the previous master key"
+
+[portal.infrastructure.encryption.scope]
+global = "All users"
+source = "Source {{id}}"
+team = "Team {{id}}"
+
+[portal.infrastructure.encryption.status]
+ACTIVE = "Active"
+DISABLED = "Revoked"
+RETIRED = "Retired"
+
+[portal.infrastructure.encryption.unavailable.forbidden]
+description = "Your account does not have permission to view encryption settings."
+title = "Not available for your account"
+
+[portal.infrastructure.encryption.unavailable.registry-unavailable]
+description = "The encryption key registry could not be read. Check the database connection and the application logs."
+title = "Key registry unavailable"
+
+[portal.infrastructure.encryption.unavailable.storage-disabled]
+description = "File storage is switched off on this server, so there is nothing to encrypt."
+title = "Storage is disabled"
+
+[portal.infrastructure.encryption.unavailable.unknown]
+description = "Encryption status could not be loaded. Please try again."
+title = "Status unavailable"
+
+[portal.infrastructure.encryption.writeState]
+decryptOnly = "Decrypt only"
+encrypting = "Encrypting new uploads"
+off = "Off"
+
 [portal.infrastructure.keyLabel]
 active = "Active"
 revoked = "Revoked"
 
@@ -112,6 +112,11 @@ export const I18N_PROJECTS: TranslationProject[] = [
       // A failure's disabled reason arrives from the server as a key and is rendered with
       // t(thatKey), so nothing in source names it, but the copy still has to exist.
       /^portal\.failures\.disabled\./,
+      // Encryption panel copy keyed by backend enum values: key status, write
+      // state, migration state, and the reason a status read was refused. Each
+      // is t(`...${value}`) where the value comes from the API response.
+      /^portal\.infrastructure\.encryption\.(status|writeState|unavailable)\./,
+      /^portal\.infrastructure\.encryption\.migration\.state\./,
     ],
     minUsedKeys: 100,
     minLocaleKeys: 100,