feat: startup env-var user migration + UserStore integration tests

Completes the DB-backed user management feature (#1605):

- Startup migration: when GATEWAY_USER_TOKENS is set and the users
  table is empty, inserts env-var users + hashed tokens into DB.
  Logs deprecation notice when DB already has users.
- hash_token made pub for reuse in migration code.
- 10 integration tests for UserStore (libsql file-backed):
  - has_any_users bootstrap detection
  - create/get/get_by_email/list/update user lifecycle
  - token create → authenticate → revoke → reject cycle
  - suspended user tokens rejected
  - wrong-user token revoke returns false
  - invitation create → accept → user created
  - record_login and record_token_usage timestamps
- libSQL migration: removed FK constraints from V14 (incompatible
  with execute_batch inside transactions). Tables in both base SCHEMA
  and incremental migration for fresh and existing databases.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

src/db/libsql/users.rs

@@ -498,3 +498,265 @@ impl UserStore for LibSqlBackend {
         Ok(has_users)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::db::libsql::LibSqlBackend;
+    use crate::db::{Database, UserStore};
+    use sha2::{Digest, Sha256};
+
+    fn hash(s: &str) -> [u8; 32] {
+        let mut h = Sha256::new();
+        h.update(s.as_bytes());
+        h.finalize().into()
+    }
+
+    async fn setup() -> (LibSqlBackend, tempfile::TempDir) {
+        let dir = tempfile::tempdir().unwrap();
+        let db_path = dir.path().join("test_users.db");
+        let db = LibSqlBackend::new_local(&db_path).await.unwrap();
+        db.run_migrations().await.unwrap();
+        (db, dir) // keep dir alive so the DB file isn't deleted
+    }
+
+    fn test_user(id: &str) -> UserRecord {
+        UserRecord {
+            id: id.to_string(),
+            email: Some(format!("{}@test.com", id)),
+            display_name: id.to_string(),
+            status: "active".to_string(),
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+            last_login_at: None,
+            created_by: None,
+            metadata: serde_json::json!({}),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_has_any_users_empty() {
+        let (db, _dir) = setup().await;
+        assert!(!db.has_any_users().await.unwrap());
+    }
+
+    #[tokio::test]
+    async fn test_create_and_get_user() {
+        let (db, _dir) = setup().await;
+        let user = test_user("alice");
+        db.create_user(&user).await.unwrap();
+
+        assert!(db.has_any_users().await.unwrap());
+
+        let found = db.get_user("alice").await.unwrap().unwrap();
+        assert_eq!(found.id, "alice");
+        assert_eq!(found.email, Some("[email protected]".to_string()));
+        assert_eq!(found.status, "active");
+    }
+
+    #[tokio::test]
+    async fn test_get_user_by_email() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("bob")).await.unwrap();
+
+        let found = db.get_user_by_email("[email protected]").await.unwrap();
+        assert!(found.is_some());
+        assert_eq!(found.unwrap().id, "bob");
+
+        assert!(
+            db.get_user_by_email("[email protected]")
+                .await
+                .unwrap()
+                .is_none()
+        );
+    }
+
+    #[tokio::test]
+    async fn test_list_users_with_status_filter() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+        db.create_user(&test_user("bob")).await.unwrap();
+        db.update_user_status("bob", "suspended").await.unwrap();
+
+        let all = db.list_users(None).await.unwrap();
+        assert_eq!(all.len(), 2);
+
+        let active = db.list_users(Some("active")).await.unwrap();
+        assert_eq!(active.len(), 1);
+        assert_eq!(active[0].id, "alice");
+
+        let suspended = db.list_users(Some("suspended")).await.unwrap();
+        assert_eq!(suspended.len(), 1);
+        assert_eq!(suspended[0].id, "bob");
+    }
+
+    #[tokio::test]
+    async fn test_update_user_profile() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        let meta = serde_json::json!({"role": "admin"});
+        db.update_user_profile("alice", "Alice Smith", &meta)
+            .await
+            .unwrap();
+
+        let user = db.get_user("alice").await.unwrap().unwrap();
+        assert_eq!(user.display_name, "Alice Smith");
+        assert_eq!(user.metadata["role"], "admin");
+    }
+
+    #[tokio::test]
+    async fn test_token_lifecycle_create_authenticate_revoke() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        // Create token
+        let token_hash = hash("secret-token-123");
+        let record = db
+            .create_api_token("alice", "laptop", &token_hash, "secret-t", None)
+            .await
+            .unwrap();
+        assert_eq!(record.user_id, "alice");
+        assert_eq!(record.name, "laptop");
+        assert_eq!(record.token_prefix, "secret-t");
+
+        // Authenticate
+        let (tok, user) = db.authenticate_token(&token_hash).await.unwrap().unwrap();
+        assert_eq!(tok.id, record.id);
+        assert_eq!(user.id, "alice");
+
+        // List tokens
+        let tokens = db.list_api_tokens("alice").await.unwrap();
+        assert_eq!(tokens.len(), 1);
+
+        // Revoke
+        assert!(db.revoke_api_token(record.id, "alice").await.unwrap());
+
+        // Auth should fail after revoke
+        assert!(db.authenticate_token(&token_hash).await.unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn test_token_auth_fails_for_suspended_user() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        let token_hash = hash("token-abc");
+        db.create_api_token("alice", "test", &token_hash, "token-ab", None)
+            .await
+            .unwrap();
+
+        // Auth works while active
+        assert!(db.authenticate_token(&token_hash).await.unwrap().is_some());
+
+        // Suspend user
+        db.update_user_status("alice", "suspended").await.unwrap();
+
+        // Auth should fail
+        assert!(db.authenticate_token(&token_hash).await.unwrap().is_none());
+    }
+
+    #[tokio::test]
+    async fn test_token_revoke_wrong_user_returns_false() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+        db.create_user(&test_user("bob")).await.unwrap();
+
+        let token_hash = hash("alice-token");
+        let record = db
+            .create_api_token("alice", "test", &token_hash, "alice-to", None)
+            .await
+            .unwrap();
+
+        // Bob can't revoke Alice's token
+        assert!(!db.revoke_api_token(record.id, "bob").await.unwrap());
+
+        // Alice can
+        assert!(db.revoke_api_token(record.id, "alice").await.unwrap());
+    }
+
+    #[tokio::test]
+    async fn test_invitation_lifecycle() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        // Create invitation
+        let invite_hash = hash("invite-token-xyz");
+        let invitation = InvitationRecord {
+            id: Uuid::new_v4(),
+            email: Some("[email protected]".to_string()),
+            invited_by: "alice".to_string(),
+            status: "pending".to_string(),
+            expires_at: Utc::now() + chrono::Duration::days(7),
+            accepted_at: None,
+            accepted_by: None,
+            created_at: Utc::now(),
+        };
+        db.create_invitation(&invitation, &invite_hash)
+            .await
+            .unwrap();
+
+        // Look up by hash
+        let found = db
+            .get_invitation_by_hash(&invite_hash)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(found.id, invitation.id);
+        assert_eq!(found.status, "pending");
+
+        // List invitations
+        let list = db.list_invitations(Some("alice")).await.unwrap();
+        assert_eq!(list.len(), 1);
+
+        // Accept
+        db.create_user(&UserRecord {
+            id: "newuser".to_string(),
+            email: Some("[email protected]".to_string()),
+            display_name: "New User".to_string(),
+            status: "active".to_string(),
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+            last_login_at: None,
+            created_by: Some("alice".to_string()),
+            metadata: serde_json::json!({}),
+        })
+        .await
+        .unwrap();
+        db.accept_invitation(invitation.id, "newuser")
+            .await
+            .unwrap();
+
+        // Verify accepted
+        let accepted = db
+            .get_invitation_by_hash(&invite_hash)
+            .await
+            .unwrap()
+            .unwrap();
+        assert_eq!(accepted.status, "accepted");
+        assert_eq!(accepted.accepted_by, Some("newuser".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_record_login_and_token_usage() {
+        let (db, _dir) = setup().await;
+        db.create_user(&test_user("alice")).await.unwrap();
+
+        let token_hash = hash("tok");
+        let record = db
+            .create_api_token("alice", "test", &token_hash, "tok", None)
+            .await
+            .unwrap();
+
+        // Record usage
+        db.record_token_usage(record.id).await.unwrap();
+        db.record_login("alice").await.unwrap();
+
+        // Verify timestamps updated
+        let user = db.get_user("alice").await.unwrap().unwrap();
+        assert!(user.last_login_at.is_some());
+
+        let tokens = db.list_api_tokens("alice").await.unwrap();
+        assert!(tokens[0].last_used_at.is_some());
+    }
+}

src/db/libsql_migrations.rs

@@ -579,6 +579,7 @@ INSERT OR IGNORE INTO leak_detection_patterns (id, name, pattern, severity, acti
     ('550e8400-e29b-41d4-a716-446655440011', 'mailchimp_api_key', '[a-f0-9]{32}-us[0-9]{1,2}', 'medium', 'block', 1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     ('550e8400-e29b-41d4-a716-446655440012', 'high_entropy_hex', '(?<![a-fA-F0-9])[a-fA-F0-9]{64}(?![a-fA-F0-9])', 'medium', 'warn', 1, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'));
 
+
 -- ==================== User management (V14) ====================
 
 CREATE TABLE IF NOT EXISTS users (
@@ -589,13 +590,13 @@ CREATE TABLE IF NOT EXISTS users (
     created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     last_login_at TEXT,
-    created_by TEXT REFERENCES users(id),
+    created_by TEXT,
     metadata TEXT NOT NULL DEFAULT '{}'
 );
 
 CREATE TABLE IF NOT EXISTS api_tokens (
     id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    user_id TEXT NOT NULL,
     token_hash BLOB NOT NULL,
     token_prefix TEXT NOT NULL,
     name TEXT NOT NULL,
@@ -611,11 +612,11 @@ CREATE TABLE IF NOT EXISTS invitations (
     id TEXT PRIMARY KEY,
     email TEXT,
     invite_token_hash BLOB NOT NULL,
-    invited_by TEXT NOT NULL REFERENCES users(id),
+    invited_by TEXT NOT NULL,
     status TEXT NOT NULL DEFAULT 'pending',
     expires_at TEXT NOT NULL,
     accepted_at TEXT,
-    accepted_by TEXT REFERENCES users(id),
+    accepted_by TEXT,
     created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
 );
 
@@ -777,13 +778,13 @@ CREATE TABLE IF NOT EXISTS users (
     created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     last_login_at TEXT,
-    created_by TEXT REFERENCES users(id),
+    created_by TEXT,
     metadata TEXT NOT NULL DEFAULT '{}'
 );
 
 CREATE TABLE IF NOT EXISTS api_tokens (
     id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    user_id TEXT NOT NULL,
     token_hash BLOB NOT NULL,
     token_prefix TEXT NOT NULL,
     name TEXT NOT NULL,
@@ -799,11 +800,11 @@ CREATE TABLE IF NOT EXISTS invitations (
     id TEXT PRIMARY KEY,
     email TEXT,
     invite_token_hash BLOB NOT NULL,
-    invited_by TEXT NOT NULL REFERENCES users(id),
+    invited_by TEXT NOT NULL,
     status TEXT NOT NULL DEFAULT 'pending',
     expires_at TEXT NOT NULL,
     accepted_at TEXT,
-    accepted_by TEXT REFERENCES users(id),
+    accepted_by TEXT,
     created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
 );
 "#,