feat(auth): admin role with cookie-only RequireAdmin extractor (0.37.0)

Adds an `is_admin` flag on users plus the substrate every later PR in the
admin feature builds on:

- migration 0018 adds the column with default false
- `repo::user::bootstrap_admin` creates or promotes the user named by
  `ADMIN_USERNAME` at startup, hashing `ADMIN_PASSWORD` only when the row
  is new — never overwriting an existing hash, so an operator can rotate
  the admin password via the UI without env-var conflict
- `CurrentSessionUser` extractor accepts only the session cookie;
  `RequireAdmin` composes over it and additionally requires
  `user.is_admin`. Bearer tokens are intentionally excluded so an
  admin's bot token never inherits admin authority (privilege-escalation
  surface that bites every "API keys reuse user perms" auth design)
- demotion is instant: `RequireAdmin` re-reads the user row each request

`/api/v1/auth/me` now exposes `is_admin`; no other response embeds
`User`, so no privacy fanout to audit.

backend/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mangalord"
-version = "0.36.7"
+version = "0.37.0"
 edition = "2021"
 default-run = "mangalord"
 

backend/migrations/0018_admin_role.sql

@@ -0,0 +1,5 @@
+-- Admin role flag on users. Booted from ADMIN_USERNAME / ADMIN_PASSWORD env at
+-- startup (see app::build). Demotion is instant: the RequireAdmin extractor
+-- re-reads the user row every request, so flipping this column takes effect on
+-- the next call without a session purge.
+ALTER TABLE users ADD COLUMN is_admin BOOLEAN NOT NULL DEFAULT false;

backend/src/app.rs

@@ -60,6 +60,13 @@ pub async fn build(config: Config) -> anyhow::Result<AppHandle> {
         .await?;
     sqlx::migrate!("./migrations").run(&db).await?;
 
+    if let Some((username, password)) = config.admin_bootstrap.as_ref() {
+        repo::user::bootstrap_admin(&db, username, password)
+            .await
+            .context("bootstrap_admin from ADMIN_USERNAME/ADMIN_PASSWORD env")?;
+        tracing::info!(admin_username = %username, "admin bootstrap ensured");
+    }
+
     let storage: Arc<dyn Storage> = Arc::new(LocalStorage::new(config.storage_dir.clone()));
 
     let daemon = if config.crawler.daemon_enabled {

backend/src/auth/extractor.rs

@@ -1,11 +1,19 @@
-//! `CurrentUser` axum extractor.
+//! Auth extractors.
 //!
-//! Resolves a request to a logged-in user by trying, in order:
-//! 1. a `mangalord_session` cookie (session lookup by `sha256(value)`);
-//! 2. an `Authorization: Bearer <token>` header (api_token lookup).
+//! Three extractors are available, in increasing strictness:
 //!
-//! Both paths look up by hash, never by raw value. Failure to resolve
-//! either way returns 401 via `AppError::Unauthenticated`.
+//! - [`CurrentUser`] — accepts either a session cookie or an
+//!   `Authorization: Bearer <token>` header. Used by ordinary
+//!   authenticated endpoints where bot tokens are first-class clients.
+//! - [`CurrentSessionUser`] — accepts only the session cookie. Used as
+//!   the substrate for admin extraction so bot tokens cannot authenticate
+//!   as the admin (see [`RequireAdmin`]).
+//! - [`RequireAdmin`] — composes over [`CurrentSessionUser`] and
+//!   additionally requires `user.is_admin`. Returns 403 for
+//!   authenticated-but-not-admin, 401 otherwise.
+//!
+//! All lookups go by `sha256(raw_token)` — the raw value is never stored
+//! in the database.
 
 use axum::async_trait;
 use axum::extract::FromRequestParts;
@@ -61,3 +69,54 @@ impl FromRequestParts<AppState> for CurrentUser {
         Err(AppError::Unauthenticated)
     }
 }
+
+/// Cookie-only authentication. Bot/API tokens are explicitly NOT accepted
+/// here — this is the substrate for [`RequireAdmin`] and exists precisely
+/// to keep admin authority out of bearer-token reach.
+pub struct CurrentSessionUser(pub User);
+
+#[async_trait]
+impl FromRequestParts<AppState> for CurrentSessionUser {
+    type Rejection = AppError;
+
+    async fn from_request_parts(
+        parts: &mut Parts,
+        state: &AppState,
+    ) -> Result<Self, Self::Rejection> {
+        let jar = CookieJar::from_headers(&parts.headers);
+        let cookie = jar
+            .get(SESSION_COOKIE_NAME)
+            .ok_or(AppError::Unauthenticated)?;
+        let hash = hash_token(cookie.value());
+        let session = repo::session::find_active(&state.db, &hash)
+            .await?
+            .ok_or(AppError::Unauthenticated)?;
+        let user = repo::user::find_by_id(&state.db, session.user_id)
+            .await?
+            .ok_or(AppError::Unauthenticated)?;
+        Ok(CurrentSessionUser(user))
+    }
+}
+
+/// Admin-only. Composes over [`CurrentSessionUser`] so bot tokens are
+/// rejected at the auth step (401) rather than the role step (403).
+/// The user row is re-read every request, so demotion takes effect on
+/// the very next call without needing to purge sessions.
+pub struct RequireAdmin(pub User);
+
+#[async_trait]
+impl FromRequestParts<AppState> for RequireAdmin {
+    type Rejection = AppError;
+
+    async fn from_request_parts(
+        parts: &mut Parts,
+        state: &AppState,
+    ) -> Result<Self, Self::Rejection> {
+        let CurrentSessionUser(user) =
+            CurrentSessionUser::from_request_parts(parts, state).await?;
+        if !user.is_admin {
+            return Err(AppError::Forbidden);
+        }
+        Ok(RequireAdmin(user))
+    }
+}

backend/src/config.rs

@@ -59,6 +59,13 @@ pub struct Config {
     pub upload: UploadConfig,
     pub cors_allowed_origins: Vec<String>,
     pub crawler: CrawlerConfig,
+    /// `(username, password)` for the admin user provisioned at startup
+    /// when both `ADMIN_USERNAME` and `ADMIN_PASSWORD` are set. `None`
+    /// skips the bootstrap entirely. See `repo::user::bootstrap_admin`
+    /// for the create-vs-promote semantics — notably the password here
+    /// is used only when creating a new row, never to overwrite an
+    /// existing one.
+    pub admin_bootstrap: Option<(String, String)>,
 }
 
 /// All crawler-daemon knobs read from env. Mirrors the env vars the
@@ -158,10 +165,21 @@ impl Config {
                 })
                 .unwrap_or_default(),
             crawler: CrawlerConfig::from_env()?,
+            admin_bootstrap: admin_bootstrap_from_env(),
         })
     }
 }
 
+/// Returns `Some((username, password))` only when BOTH `ADMIN_USERNAME`
+/// and `ADMIN_PASSWORD` are set and non-empty. Half-set configuration is
+/// treated as "no bootstrap" rather than a hard error, so an operator
+/// can comment out one env var without crashing the server.
+fn admin_bootstrap_from_env() -> Option<(String, String)> {
+    let username = std::env::var("ADMIN_USERNAME").ok().filter(|s| !s.is_empty())?;
+    let password = std::env::var("ADMIN_PASSWORD").ok().filter(|s| !s.is_empty())?;
+    Some((username, password))
+}
+
 impl CrawlerConfig {
     pub fn from_env() -> anyhow::Result<Self> {
         // Parse CRAWLER_DAILY_AT (HH:MM, 24h). Invalid → fail fast.

backend/src/domain/user.rs

@@ -10,4 +10,5 @@ pub struct User {
     #[serde(skip)]
     pub password_hash: String,
     pub created_at: DateTime<Utc>,
+    pub is_admin: bool,
 }

backend/src/repo/user.rs

@@ -11,7 +11,7 @@ pub async fn create(pool: &PgPool, username: &str, password_hash: &str) -> AppRe
         r#"
         INSERT INTO users (username, password_hash)
         VALUES ($1, $2)
-        RETURNING id, username, password_hash, created_at
+        RETURNING id, username, password_hash, created_at, is_admin
         "#,
     )
     .bind(username)
@@ -35,7 +35,7 @@ pub async fn create(pool: &PgPool, username: &str, password_hash: &str) -> AppRe
 pub async fn find_by_username(pool: &PgPool, username: &str) -> AppResult<Option<User>> {
     let row = sqlx::query_as::<_, User>(
         r#"
-        SELECT id, username, password_hash, created_at
+        SELECT id, username, password_hash, created_at, is_admin
         FROM users
         WHERE lower(username) = lower($1)
         "#,
@@ -48,7 +48,7 @@ pub async fn find_by_username(pool: &PgPool, username: &str) -> AppResult<Option
 
 pub async fn find_by_id(pool: &PgPool, id: Uuid) -> AppResult<Option<User>> {
     let row = sqlx::query_as::<_, User>(
-        r#"SELECT id, username, password_hash, created_at FROM users WHERE id = $1"#,
+        r#"SELECT id, username, password_hash, created_at, is_admin FROM users WHERE id = $1"#,
     )
     .bind(id)
     .fetch_optional(pool)
@@ -56,3 +56,54 @@ pub async fn find_by_id(pool: &PgPool, id: Uuid) -> AppResult<Option<User>> {
     Ok(row)
 }
 
+pub async fn set_is_admin(pool: &PgPool, id: Uuid, value: bool) -> AppResult<()> {
+    sqlx::query("UPDATE users SET is_admin = $1 WHERE id = $2")
+        .bind(value)
+        .bind(id)
+        .execute(pool)
+        .await?;
+    Ok(())
+}
+
+/// Ensure the user `username` exists and is an admin. Called at startup
+/// from `app::build` when `ADMIN_USERNAME` / `ADMIN_PASSWORD` are set.
+///
+/// Semantics — see cross-cutting decision #2 in the feature plan:
+/// - If no row exists: create with the env-supplied password hashed via
+///   argon2id and `is_admin = true`.
+/// - If a row already exists: flip `is_admin` to true if needed; **never**
+///   touch the existing `password_hash`. Lets the operator rotate the
+///   admin password through the UI without env-var conflict.
+/// Wrapped in a transaction so a concurrent `register` for the same
+/// username can't slip an INSERT between the SELECT and UPDATE/INSERT.
+pub async fn bootstrap_admin(
+    pool: &PgPool,
+    username: &str,
+    password: &str,
+) -> AppResult<()> {
+    let mut tx = pool.begin().await?;
+    let existing: Option<(Uuid,)> = sqlx::query_as(
+        "SELECT id FROM users WHERE lower(username) = lower($1) FOR UPDATE",
+    )
+    .bind(username)
+    .fetch_optional(&mut *tx)
+    .await?;
+    match existing {
+        Some((id,)) => {
+            sqlx::query("UPDATE users SET is_admin = true WHERE id = $1 AND is_admin = false")
+                .bind(id)
+                .execute(&mut *tx)
+                .await?;
+        }
+        None => {
+            let hash = crate::auth::password::hash_password(password)?;
+            sqlx::query("INSERT INTO users (username, password_hash, is_admin) VALUES ($1, $2, true)")
+                .bind(username)
+                .bind(&hash)
+                .execute(&mut *tx)
+                .await?;
+        }
+    }
+    tx.commit().await?;
+    Ok(())
+}

backend/tests/api_admin_role.rs

@@ -0,0 +1,257 @@
+//! PR 1 (feat/admin-role) integration tests.
+//!
+//! Covers: `bootstrap_admin` semantics, `is_admin` exposed on /auth/me,
+//! and the `RequireAdmin` extractor's 401/403/200 matrix — including the
+//! load-bearing decision that Bearer-authed callers can NEVER reach an
+//! admin-guarded route, even when the underlying user IS admin.
+
+mod common;
+
+use std::sync::Arc;
+
+use axum::http::StatusCode;
+use axum::routing::get;
+use axum::{Json, Router};
+use serde_json::json;
+use sqlx::PgPool;
+use tempfile::TempDir;
+use tower::ServiceExt;
+
+use mangalord::api;
+use mangalord::app::AppState;
+use mangalord::auth::extractor::RequireAdmin;
+use mangalord::auth::rate_limit::AuthRateLimiter;
+use mangalord::config::{AuthConfig, UploadConfig};
+use mangalord::repo;
+use mangalord::storage::{LocalStorage, Storage};
+
+/// Test-only handler guarded by `RequireAdmin`. Lets the test suite assert
+/// the extractor's behaviour end-to-end without depending on an admin
+/// endpoint existing yet (those land in PR 2+).
+async fn admin_only_handler(RequireAdmin(user): RequireAdmin) -> Json<serde_json::Value> {
+    Json(json!({ "username": user.username, "is_admin": user.is_admin }))
+}
+
+/// Build a router that exposes the production /api/v1/* AND a test-only
+/// `/_test/admin_only` route guarded by `RequireAdmin`. Pool is consumed;
+/// callers that want to inspect the DB after a request should clone it.
+fn admin_test_router(pool: PgPool) -> (Router, TempDir) {
+    let storage_dir = tempfile::tempdir().expect("tempdir");
+    let storage: Arc<dyn Storage> = Arc::new(LocalStorage::new(storage_dir.path()));
+    let auth = AuthConfig {
+        cookie_secure: false,
+        ..AuthConfig::default()
+    };
+    let auth_limiter = Arc::new(AuthRateLimiter::new(auth.rate_limit));
+    let state = AppState {
+        db: pool,
+        storage,
+        auth,
+        upload: UploadConfig::default(),
+        auth_limiter,
+    };
+    let app = Router::new()
+        .nest("/api/v1", api::routes())
+        .route("/_test/admin_only", get(admin_only_handler))
+        .with_state(state);
+    (app, storage_dir)
+}
+
+// ---- bootstrap_admin -------------------------------------------------------
+
+#[sqlx::test(migrations = "./migrations")]
+async fn bootstrap_creates_admin_when_user_missing(pool: PgPool) {
+    repo::user::bootstrap_admin(&pool, "root", "hunter2hunter2")
+        .await
+        .expect("bootstrap on empty DB");
+
+    let user = repo::user::find_by_username(&pool, "root")
+        .await
+        .unwrap()
+        .expect("root user exists after bootstrap");
+    assert!(user.is_admin, "bootstrap must set is_admin = true on creation");
+
+    // Password hash must verify the env-supplied password (and not be empty).
+    assert!(
+        mangalord::auth::password::verify_password("hunter2hunter2", &user.password_hash),
+        "bootstrap-created user must accept the env-supplied password"
+    );
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn bootstrap_promotes_existing_user_without_touching_password(pool: PgPool) {
+    // Pre-existing user, not admin. Use the real register path so the
+    // hash format matches production exactly.
+    let (app, _td) = admin_test_router(pool.clone());
+    let resp = app
+        .oneshot(common::post_json(
+            "/api/v1/auth/register",
+            json!({ "username": "preexisting", "password": "originalpw1234" }),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED);
+
+    let before = repo::user::find_by_username(&pool, "preexisting")
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(!before.is_admin);
+    let original_hash = before.password_hash.clone();
+
+    // Bootstrap with a DIFFERENT password — must not overwrite the hash.
+    repo::user::bootstrap_admin(&pool, "preexisting", "envpw_should_be_ignored")
+        .await
+        .expect("bootstrap on existing user");
+
+    let after = repo::user::find_by_username(&pool, "preexisting")
+        .await
+        .unwrap()
+        .unwrap();
+    assert!(after.is_admin, "bootstrap must promote existing user");
+    assert_eq!(
+        after.password_hash, original_hash,
+        "bootstrap must NOT overwrite the existing password hash"
+    );
+    assert!(
+        mangalord::auth::password::verify_password("originalpw1234", &after.password_hash),
+        "original password must still verify after bootstrap"
+    );
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn bootstrap_is_idempotent(pool: PgPool) {
+    repo::user::bootstrap_admin(&pool, "root", "hunter2hunter2")
+        .await
+        .expect("first bootstrap");
+    repo::user::bootstrap_admin(&pool, "root", "hunter2hunter2")
+        .await
+        .expect("second bootstrap is no-op");
+
+    // Exactly one row, still admin.
+    let (count,): (i64,) = sqlx::query_as("SELECT COUNT(*) FROM users WHERE username = $1")
+        .bind("root")
+        .fetch_one(&pool)
+        .await
+        .unwrap();
+    assert_eq!(count, 1);
+}
+
+// ---- /api/v1/auth/me exposes is_admin --------------------------------------
+
+#[sqlx::test(migrations = "./migrations")]
+async fn auth_me_response_includes_is_admin(pool: PgPool) {
+    let (app, _td) = admin_test_router(pool.clone());
+    let (_username, cookie) = common::register_user(&app).await;
+    let resp = app
+        .oneshot(common::get_with_cookie("/api/v1/auth/me", &cookie))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(
+        body["user"]["is_admin"], false,
+        "freshly-registered users default to is_admin=false"
+    );
+}
+
+// ---- RequireAdmin: 401 / 403 / 200 matrix ----------------------------------
+
+#[sqlx::test(migrations = "./migrations")]
+async fn require_admin_rejects_unauthenticated(pool: PgPool) {
+    let (app, _td) = admin_test_router(pool);
+    let resp = app
+        .oneshot(common::get("/_test/admin_only"))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn require_admin_rejects_non_admin_cookie(pool: PgPool) {
+    let (app, _td) = admin_test_router(pool);
+    let (_username, cookie) = common::register_user(&app).await;
+    let resp = app
+        .oneshot(common::get_with_cookie("/_test/admin_only", &cookie))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::FORBIDDEN);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "forbidden");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn require_admin_accepts_admin_cookie(pool: PgPool) {
+    let (app, _td) = admin_test_router(pool.clone());
+    let (username, cookie) = common::register_user(&app).await;
+    // Promote via the repo (the admin-users API doesn't exist yet).
+    let u = repo::user::find_by_username(&pool, &username)
+        .await
+        .unwrap()
+        .unwrap();
+    repo::user::set_is_admin(&pool, u.id, true).await.unwrap();
+
+    let resp = app
+        .oneshot(common::get_with_cookie("/_test/admin_only", &cookie))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["username"], username);
+    assert_eq!(body["is_admin"], true);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn require_admin_rejects_bearer_token_even_for_admin_user(pool: PgPool) {
+    // Key privilege-escalation test: an API token belonging to an admin user
+    // must NOT grant admin authority. Bot tokens are excluded from admin
+    // routes by design (the RequireAdmin extractor only accepts session
+    // cookies). See cross-cutting decision #1 in the PR plan.
+    let (app, _td) = admin_test_router(pool.clone());
+    let (username, cookie) = common::register_user(&app).await;
+
+    // Promote to admin and mint an API token (the existing /auth/tokens
+    // endpoint authenticates via the same cookie).
+    let u = repo::user::find_by_username(&pool, &username)
+        .await
+        .unwrap()
+        .unwrap();
+    repo::user::set_is_admin(&pool, u.id, true).await.unwrap();
+
+    let resp = app
+        .clone()
+        .oneshot(common::post_json_with_cookie(
+            "/api/v1/auth/tokens",
+            json!({ "name": "test-bot" }),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED);
+    let body = common::body_json(resp).await;
+    let token = body["bearer"]
+        .as_str()
+        .expect("raw bearer token in response")
+        .to_string();
+
+    // Sanity: the bearer DOES work on a non-admin endpoint (proves the
+    // token is valid, isolating the failure below to the admin guard).
+    let resp = app
+        .clone()
+        .oneshot(common::get_with_bearer("/api/v1/auth/me", &token))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::OK);
+
+    // Same token, same admin user, but on the admin-guarded route → 401
+    // (no session cookie present at all from the extractor's POV).
+    let resp = app
+        .oneshot(common::get_with_bearer("/_test/admin_only", &token))
+        .await
+        .unwrap();
+    assert_eq!(
+        resp.status(),
+        StatusCode::UNAUTHORIZED,
+        "Bearer-authed admin must NOT pass the RequireAdmin guard"
+    );
+}

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mangalord-frontend",
-  "version": "0.36.7",
+  "version": "0.37.0",
   "private": true,
   "type": "module",
   "scripts": {