deploy: 0105f798e0

auriondocs/Code/src/EchoHub.Server/Setup/FirstRunSetup.cs.md

@@ -8,18 +8,13 @@ public static class FirstRunSetup
 ```
 
 
-FirstRunSetup is a small bootstrap utility that guarantees a usable appsettings.json and seeds it with cryptographic secrets on first run. On startup, it copies appsettings.example.json to appsettings.json if the destination is missing, then ensures a valid JWT secret and an encryption key exist by generating them when needed.
+FirstRunSetup is a small bootstrap utility that ensures essential configuration exists on the first run of the application. Calling `EnsureAppSettings` will create `appsettings.json` from `appsettings.example.json` if the former is missing, and then guarantee that security-related values are present by generating them when necessary. Specifically, it will ensure the JWT secret at `Jwt.Secret` is non-empty and not a placeholder, and it will ensure an AES encryption key at `Encryption.Key` is present. Generated secrets are cryptographically strong base64 values written back into `appsettings.json`, and progress is reported to the console.
 
 ## Remarks
-Centralizing this bootstrap logic keeps startup concerns cohesive and makes the secrets generation deterministic and auditable. It relies on cryptographically secure RNG and writes back to the configuration file with indentation for human readability, while tolerating JSON comments during read.
-
-## Example
-```csharp
-// Typical usage during application startup
-FirstRunSetup.EnsureAppSettings();
-```
+The class centralizes the bootstrapping of critical security configuration, enabling a smooth first-run startup without manual edits. It is designed to be invoked during startup or a dedicated setup routine, populating missing cryptographic material so downstream components can rely on `Jwt.Secret` and `Encryption.Key` being present from the outset. The implementation favors an in-place, file-based approach that aligns with conventional .NET configuration loading, so subsequent code that reads configuration from `appsettings.json` will see the generated values.
 
 ## Notes
-- Idempotent: existing Jwt.Secret or Encryption.Key are preserved; new values are generated only if missing or marked as CHANGE_ME.
-- Path dependency: relies on the current working directory (the project root). In non-standard deployments, you may need to adjust the working directory or extend the helper to accept explicit paths.
-- Silent on parse failure: if the JSON cannot be parsed (root is null), the method returns without writing changes.
+- IO or JSON parsing/writing operations may throw if the filesystem is inaccessible or the JSON is malformed; there is no explicit exception handling in this bootstrap path.
+- The JWT secret is only regenerated if it is missing, empty, or begins with `CHANGE_ME`, preventing accidental overwrites on a healthy existing configuration.
+- The encryption key is generated only when the `Encryption.Key` value is absent; existing keys are preserved to avoid needless rotation.
+- The logic relies on the current working directory to locate `appsettings.json` and `appsettings.example.json`, so running from an unexpected directory can affect behavior.