feat: add first-run admin setup with db credentials and env fallback

Author: scarson

README.md

@@ -97,8 +97,8 @@ stdout = true
 
 ### Runtime Environment
 
-- `ADMIN_USER` (required)
-- `ADMIN_PASSWORD_HASH` (required)
+- `ADMIN_USER` (optional fallback login)
+- `ADMIN_PASSWORD_HASH` (optional fallback login, requires `ADMIN_USER`)
 - `IMGFLOP_API_TOP_N` (`max` by default, or integer `>= 1`)
 - `IMGFLOP_HISTORY_TOP_N` (`100` by default, integer `>= 1`)
 - `IMGFLOP_POLL_INTERVAL_SECS` (`300` by default, integer `>= 1`)
@@ -111,6 +111,11 @@ stdout = true
 - API ingest candidate count is controlled by `IMGFLOP_API_TOP_N`.
 - Persisted top-state/events are controlled by `IMGFLOP_HISTORY_TOP_N`.
 
+Admin auth behavior:
+- If no admin account exists in DB, `/admin/login` shows a first-run setup form.
+- Setup stores one local admin credential in SQLite using Argon2id hash.
+- If `ADMIN_USER` + `ADMIN_PASSWORD_HASH` are provided, they remain usable as an emergency fallback login.
+
 ### Prerequisites
 - Rust toolchain (stable)
 - Docker Desktop (for `rust.testcontainers` scenarios)

migrations/0003_admin_credentials.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS admin_credentials (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    username TEXT NOT NULL,
+    password_hash TEXT NOT NULL,
+    created_at_utc TEXT NOT NULL,
+    updated_at_utc TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_admin_credentials_username
+    ON admin_credentials(username);

src/auth/mod.rs

@@ -22,14 +22,19 @@ pub enum AuthError {
 }
 
 pub struct AuthService {
-    admin_user: String,
-    admin_password_hash: String,
+    fallback_admin: Option<FallbackAdmin>,
     sessions: Mutex<HashSet<SessionRecord>>,
     session_seq: AtomicU64,
     session_ttl_secs: u64,
     secure_cookie: bool,
 }
 
+#[derive(Debug, Clone)]
+struct FallbackAdmin {
+    username: String,
+    password_hash: String,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 struct SessionRecord {
     token: String,
@@ -43,18 +48,42 @@ impl AuthService {
         session_ttl_secs: u64,
         secure_cookie: bool,
     ) -> Result<Self, String> {
-        if admin_user.trim().is_empty() {
-            return Err("admin username must not be empty".to_string());
-        }
-        PasswordHash::new(&admin_password_hash)
-            .map_err(|_| "admin password hash is invalid".to_string())?;
+        Self::new_with_fallback(
+            Some(admin_user),
+            Some(admin_password_hash),
+            session_ttl_secs,
+            secure_cookie,
+        )
+    }
+
+    pub fn new_with_fallback(
+        admin_user: Option<String>,
+        admin_password_hash: Option<String>,
+        session_ttl_secs: u64,
+        secure_cookie: bool,
+    ) -> Result<Self, String> {
         if session_ttl_secs == 0 {
             return Err("session TTL must be >= 1 second".to_string());
         }
 
+        let fallback_admin = match (admin_user, admin_password_hash) {
+            (Some(username), Some(password_hash)) => {
+                if username.trim().is_empty() {
+                    return Err("admin username must not be empty".to_string());
+                }
+                PasswordHash::new(&password_hash)
+                    .map_err(|_| "admin password hash is invalid".to_string())?;
+                Some(FallbackAdmin {
+                    username,
+                    password_hash,
+                })
+            }
+            (None, None) => None,
+            _ => return Err("ADMIN_USER and ADMIN_PASSWORD_HASH must both be set".to_string()),
+        };
+
         Ok(Self {
-            admin_user,
-            admin_password_hash,
+            fallback_admin,
             sessions: Mutex::new(HashSet::new()),
             session_seq: AtomicU64::new(1),
             session_ttl_secs,
@@ -63,30 +92,18 @@ impl AuthService {
     }
 
     pub fn dev_default() -> Self {
-        let salt = SaltString::generate(&mut OsRng);
-        let password_hash = Argon2::default()
-            .hash_password(b"admin", &salt)
-            .expect("default dev password hash should build")
-            .to_string();
+        let password_hash = hash_password("admin").expect("default dev password hash should build");
 
-        Self::new("admin".to_string(), password_hash, 3600, false)
+        Self::new_with_fallback(Some("admin".to_string()), Some(password_hash), 3600, false)
             .expect("dev default auth should be valid")
     }
 
     pub fn login(&self, username: &str, password: &str) -> Result<String, AuthError> {
-        if !self.verify_credentials(username, password) {
+        if !self.verify_fallback_credentials(username, password) {
             return Err(AuthError::InvalidCredentials);
         }
 
-        let token = format!("s-{}", self.session_seq.fetch_add(1, Ordering::Relaxed));
-        let issued_at_utc = now_epoch_seconds();
-        if let Ok(mut sessions) = self.sessions.lock() {
-            sessions.insert(SessionRecord {
-                token: token.clone(),
-                issued_at_utc,
-            });
-        }
-        Ok(token)
+        Ok(self.issue_session_token())
     }
 
     pub fn logout_token(&self, token: &str) {
@@ -118,18 +135,30 @@ impl AuthService {
         self.secure_cookie
     }
 
-    fn verify_credentials(&self, username: &str, password: &str) -> bool {
-        if username != self.admin_user {
-            return false;
+    pub fn has_fallback_credentials(&self) -> bool {
+        self.fallback_admin.is_some()
+    }
+
+    pub fn issue_session_token(&self) -> String {
+        let token = format!("s-{}", self.session_seq.fetch_add(1, Ordering::Relaxed));
+        let issued_at_utc = now_epoch_seconds();
+        if let Ok(mut sessions) = self.sessions.lock() {
+            sessions.insert(SessionRecord {
+                token: token.clone(),
+                issued_at_utc,
+            });
         }
+        token
+    }
 
-        let Ok(parsed_hash) = PasswordHash::new(&self.admin_password_hash) else {
+    pub fn verify_fallback_credentials(&self, username: &str, password: &str) -> bool {
+        let Some(fallback) = self.fallback_admin.as_ref() else {
             return false;
         };
-
-        Argon2::default()
-            .verify_password(password.as_bytes(), &parsed_hash)
-            .is_ok()
+        if username != fallback.username {
+            return false;
+        }
+        verify_password(&fallback.password_hash, password)
     }
 
     fn is_expired(&self, now_utc: i64, issued_at_utc: i64) -> bool {
@@ -143,3 +172,23 @@ fn now_epoch_seconds() -> i64 {
         .map(|duration| duration.as_secs() as i64)
         .unwrap_or_default()
 }
+
+pub fn hash_password(password: &str) -> Result<String, String> {
+    if password.is_empty() {
+        return Err("password must not be empty".to_string());
+    }
+    let salt = SaltString::generate(&mut OsRng);
+    Argon2::default()
+        .hash_password(password.as_bytes(), &salt)
+        .map(|hash| hash.to_string())
+        .map_err(|err| err.to_string())
+}
+
+pub fn verify_password(password_hash: &str, password: &str) -> bool {
+    let Ok(parsed_hash) = PasswordHash::new(password_hash) else {
+        return false;
+    };
+    Argon2::default()
+        .verify_password(password.as_bytes(), &parsed_hash)
+        .is_ok()
+}

src/config.rs

@@ -7,6 +7,7 @@ use std::{
     time::{SystemTime, UNIX_EPOCH},
 };
 
+use argon2::password_hash::PasswordHash;
 use serde::Deserialize;
 use sqlx::sqlite::SqliteConnectOptions;
 
@@ -35,8 +36,8 @@ pub struct Config {
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RuntimeAuthConfig {
-    pub admin_user: String,
-    pub admin_password_hash: String,
+    pub fallback_admin_user: Option<String>,
+    pub fallback_admin_password_hash: Option<String>,
     pub session_ttl_secs: u64,
     pub secure_cookie: bool,
 }
@@ -76,12 +77,16 @@ impl RuntimeConfig {
             300,
         )?;
 
-        let admin_user = get("ADMIN_USER")
-            .filter(|value| !value.trim().is_empty())
-            .ok_or_else(|| "ADMIN_USER must be set".to_string())?;
-        let admin_password_hash = get("ADMIN_PASSWORD_HASH")
-            .filter(|value| !value.trim().is_empty())
-            .ok_or_else(|| "ADMIN_PASSWORD_HASH must be set".to_string())?;
+        let fallback_admin_user = get("ADMIN_USER").filter(|value| !value.trim().is_empty());
+        let fallback_admin_password_hash =
+            get("ADMIN_PASSWORD_HASH").filter(|value| !value.trim().is_empty());
+        if fallback_admin_user.is_some() != fallback_admin_password_hash.is_some() {
+            return Err("ADMIN_USER and ADMIN_PASSWORD_HASH must both be set".to_string());
+        }
+        if let Some(hash) = fallback_admin_password_hash.as_deref() {
+            PasswordHash::new(hash)
+                .map_err(|_| "ADMIN_PASSWORD_HASH must be a valid argon2 hash".to_string())?;
+        }
 
         let session_ttl_secs = parse_u64_at_least_one(
             get("IMGFLOP_SESSION_TTL_SECS"),
@@ -103,8 +108,8 @@ impl RuntimeConfig {
             poll_interval_secs,
             api_endpoint,
             auth: RuntimeAuthConfig {
-                admin_user,
-                admin_password_hash,
+                fallback_admin_user,
+                fallback_admin_password_hash,
                 session_ttl_secs,
                 secure_cookie,
             },

src/main.rs

@@ -40,9 +40,9 @@ async fn main() {
     ));
     let designer = DesignerService::new(pool.clone(), assets_root);
     let auth = Arc::new(
-        AuthService::new(
-            config.auth.admin_user.clone(),
-            config.auth.admin_password_hash.clone(),
+        AuthService::new_with_fallback(
+            config.auth.fallback_admin_user.clone(),
+            config.auth.fallback_admin_password_hash.clone(),
             config.auth.session_ttl_secs,
             config.auth.secure_cookie,
         )