LoVisual/backend/PLAN.md

Backend: accounts-service (Подсистема 1, часть 1) — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Standalone accounts-service (Rust/Axum) with email+password auth, JWT issue/refresh, OAuth-2-style device-code linking for the mod, and avatar upload — the foundation the gateway, configs-service and the site will build on.

Architecture: Single Axum binary, sqlx against PostgreSQL (own accounts_db), argon2 for password hashing, jsonwebtoken for access/refresh tokens, avatars stored in S3-compatible storage via the aws-sdk-s3 crate (MinIO-compatible). No gateway yet — this service is directly reachable on its own port for this plan; the gateway that fronts it (routing + JWT check for the site/mod) is a separate follow-up plan, as is configs-service and the React frontend. This keeps each plan independently testable, per the microservices decomposition agreed in /storage/project/jvm/LoVisual/TODO.md (Фаза 10).

Tech Stack: Rust (stable, edition 2024), Axum 0.8, sqlx 0.9 (postgres, runtime-tokio, tls-rustls, macros, migrate), tokio, argon2 0.6, jsonwebtoken 11 (rust_crypto backend), aws-sdk-s3, serde/serde_json, uuid (v4), rand 0.10 (for device/share codes), tower-http 0.7 (trace, cors), dotenvy. All versions verified by compiling on 2026-09-23 — see the note after Task 1 Step 1 for exact API deltas from older docs/tutorials.

Global Constraints

• All money/user-facing strings: Russian (matches project convention seen in TODO.md/mod/), but code identifiers/comments in English (matches existing mod codebase style).
• No panics on user input — every handler returns a typed error mapped to an HTTP status, never .unwrap() on request data.
• Passwords: argon2id, never logged, never returned in any response.
• Every new module gets tests before being wired into main.rs (TDD, per project convention already established in mod/: "Тесты обязательны для новых модулей").
• Max 250 lines per file (facades/delegates excepted) — see TODO.md's "Правила платформы" section; every file created by this plan stays under that on its own, but keep it in mind if a later task grows one.
• Max 4 files per directory (subdirectories don't count against this) — same rule as the mod, see TODO.md. Every module directory in this plan (auth/, accounts/, device/, avatars/) stays at 3-4 files; if a later task needs a 5th file in one, split a meaningfully-named subdirectory instead of just adding the file.
• No .clone() to route around the borrow checker — take a reference instead; no blocking I/O inside an async fn; no God-structs (state is split per domain: AuthState, DeviceState, AvatarState, never one AppState holding everything) — see TODO.md's anti-pattern list.
• Commit after every passing task, in this repo (/storage/project/jvm/LoVisual), path backend/.

---

File Structure

backend/
  accounts-service/
    Cargo.toml
    migrations/
      0001_init.sql
    src/
      main.rs              # axum app assembly, router, DB pool, S3 client
      config.rs             # env var loading (DATABASE_URL, JWT_SECRET, S3_*, PORT)
      error.rs              # AppError enum -> IntoResponse
      db.rs                 # PgPool type alias + connect()
      auth/
        mod.rs               # re-exports
        password.rs          # hash_password, verify_password (argon2)
        jwt.rs                # issue_access_token, issue_refresh_token, verify_access_token
        handlers.rs           # POST /auth/register, /auth/login, /auth/refresh, /auth/logout
      device/
        mod.rs
        handlers.rs           # POST /device/code, /device/confirm, /device/token
        store.rs              # in-memory device-code store (DashMap) with TTL
      avatars/
        mod.rs
        handlers.rs           # POST /avatars, multipart upload
        storage.rs            # S3 put_object wrapper
      accounts/
        mod.rs
        model.rs              # Account struct, row mapping
        repo.rs                # sqlx queries: create, find_by_email, find_by_id, update_avatar_url

---

Task 1: Project scaffold + health check

Files:

• Create: backend/accounts-service/Cargo.toml
• Create: backend/accounts-service/src/main.rs
• Create: backend/accounts-service/src/config.rs
• Create: backend/.env.example
• Test: backend/accounts-service/tests/health.rs

Interfaces:

• Produces: fn build_app(pool: sqlx::PgPool) -> axum::Router (used by every later task to mount new routes; tests call this directly instead of spawning a real server)

• Produces: struct Config { database_url: String, jwt_secret: String, port: u16, s3_endpoint: String, s3_bucket: String, s3_access_key: String, s3_secret_key: String } with Config::from_env() -> anyhow::Result<Config>

• Step 1: Create the crate

mkdir -p /storage/project/jvm/LoVisual/backend/accounts-service/src
cd /storage/project/jvm/LoVisual/backend/accounts-service
cat > Cargo.toml << 'EOF'
[package]
name = "accounts-service"
version = "0.1.0"
edition = "2024"

[dependencies]
axum = { version = "0.8", features = ["multipart"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
tower-http = { version = "0.7", features = ["trace", "cors"] }
tracing = "0.1"
tracing-subscriber = "0.3"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.9", default-features = false, features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "chrono", "macros", "migrate"] }
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
argon2 = "0.6"
jsonwebtoken = { version = "11", default-features = false, features = ["rust_crypto"] }
rand = "0.10"
dashmap = "6"
aws-sdk-s3 = "1"
aws-config = "1"
anyhow = "1"
dotenvy = "0.15"

[dev-dependencies]
axum-test = "21"
EOF

Versions verified by actually compiling each one (not from memory) on 2026-09-23 against Rust 1.97.1 — several had breaking changes since the versions this plan originally targeted, called out inline where the code differs from what you'd expect from older docs/tutorials:

• sqlx 0.8 → 0.9: the combined runtime-tokio-rustls feature was split into separate runtime-tokio + tls-rustls features (hence default-features = false above — the new defaults pull in any/mysql/ sqlite machinery this service doesn't need). FromRow/query_as/ PgPoolOptions themselves are unchanged.
• argon2 0.5 → 0.6: SaltString/PasswordHash moved and the manual two-argument hash_password(bytes, &salt) call is gone — see Task 3, the salt is now generated internally by hash_password(bytes) alone.
• jsonwebtoken 9 → 11: now requires explicitly picking a crypto backend feature (rust_crypto here — pure Rust, no OpenSSL/BoringSSL toolchain needed) or it panics at runtime with "Could not automatically determine the process-level CryptoProvider". encode/decode calls themselves are unchanged.
• rand 0.8 → 0.10: rand::thread_rng() → rand::rng(), and Rng::gen_range moved to the RngExt trait as random_range — see Task 7's random_user_code().
• axum-test 16 → 21: TestServer::new(app) now returns Self directly instead of Result<Self, _> — drop the .unwrap() every test in this plan that constructs one.
• thiserror dropped from the dependency list — nothing in this plan actually derives thiserror::Error (AppError in Task 6 is hand-written), so it was dead weight; add it back only if a later task needs it.

• Step 2: Write config.rs

// backend/accounts-service/src/config.rs
use anyhow::{Context, Result};

#[derive(Clone)]
pub struct Config {
    pub database_url: String,
    pub jwt_secret: String,
    pub port: u16,
    pub s3_endpoint: String,
    pub s3_bucket: String,
    pub s3_access_key: String,
    pub s3_secret_key: String,
}

impl Config {
    pub fn from_env() -> Result<Config> {
        Ok(Config {
            database_url: std::env::var("DATABASE_URL")
                .context("DATABASE_URL not set")?,
            jwt_secret: std::env::var("JWT_SECRET")
                .context("JWT_SECRET not set")?,
            port: std::env::var("PORT")
                .unwrap_or_else(|_| "8081".into())
                .parse()
                .context("PORT must be a number")?,
            s3_endpoint: std::env::var("S3_ENDPOINT")
                .context("S3_ENDPOINT not set")?,
            s3_bucket: std::env::var("S3_BUCKET")
                .context("S3_BUCKET not set")?,
            s3_access_key: std::env::var("S3_ACCESS_KEY")
                .context("S3_ACCESS_KEY not set")?,
            s3_secret_key: std::env::var("S3_SECRET_KEY")
                .context("S3_SECRET_KEY not set")?,
        })
    }
}

• Step 3: Write main.rs with a health route

// backend/accounts-service/src/main.rs
mod config;

use axum::{routing::get, Router};

pub fn build_app(_pool: sqlx::PgPool) -> Router {
    Router::new().route("/health", get(|| async { "ok" }))
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();
    dotenvy::dotenv().ok();
    let cfg = config::Config::from_env()?;

    let pool = sqlx::postgres::PgPoolOptions::new()
        .max_connections(10)
        .connect(&cfg.database_url)
        .await?;

    let app = build_app(pool);
    let listener = tokio::net::TcpListener::bind(("0.0.0.0", cfg.port)).await?;
    tracing::info!("accounts-service listening on {}", cfg.port);
    axum::serve(listener, app).await?;
    Ok(())
}

• Step 4: Create backend/.env.example

cat > /storage/project/jvm/LoVisual/backend/.env.example << 'EOF'
DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db
JWT_SECRET=change-me-to-a-long-random-string
PORT=8081
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=lovisual-avatars
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
EOF

• Step 5: Write the failing test

// backend/accounts-service/tests/health.rs
// Requires `pub mod` exposure — add `pub mod config;` and make build_app pub
// in a lib target. Add to Cargo.toml under [package]:
//   [lib]
//   name = "accounts_service"
//   path = "src/lib.rs"
// and move the `build_app` fn (and `mod config;`) into src/lib.rs, with
// main.rs reduced to `use accounts_service::{build_app, config};` + the
// existing #[tokio::main] body unchanged.

use axum_test::TestServer;

#[tokio::test]
async fn health_returns_ok() {
    // NOTE: this test does not touch the DB — pass a pool that is never
    // queried. sqlx::PgPool::connect_lazy never opens a connection until
    // a query runs, so this is safe without a running Postgres.
    let pool = sqlx::PgPool::connect_lazy("postgres://user:pass@localhost/db")
        .expect("lazy pool");
    let app = accounts_service::build_app(pool);
    let server = TestServer::new(app);

    let response = server.get("/health").await;
    response.assert_status_ok();
    response.assert_text("ok");
}

• Step 6: Move build_app/mod config into src/lib.rs as described in the test's NOTE

// backend/accounts-service/src/lib.rs
pub mod config;

use axum::{routing::get, Router};

pub fn build_app(_pool: sqlx::PgPool) -> Router {
    Router::new().route("/health", get(|| async { "ok" }))
}

// backend/accounts-service/src/main.rs
use accounts_service::{build_app, config::Config};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();
    dotenvy::dotenv().ok();
    let cfg = Config::from_env()?;

    let pool = sqlx::postgres::PgPoolOptions::new()
        .max_connections(10)
        .connect(&cfg.database_url)
        .await?;

    let app = build_app(pool);
    let listener = tokio::net::TcpListener::bind(("0.0.0.0", cfg.port)).await?;
    tracing::info!("accounts-service listening on {}", cfg.port);
    axum::serve(listener, app).await?;
    Ok(())
}

Add to Cargo.toml (after [package], before [dependencies]):

[lib]
name = "accounts_service"
path = "src/lib.rs"

• Step 7: Run the test

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && cargo test --test health Expected: test health_returns_ok ... ok

• Step 8: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service backend/.env.example
git commit -m "feat(backend): scaffold accounts-service with health check"

---

Task 2: Database schema — accounts table + migration runner

Files:

• Create: backend/accounts-service/migrations/0001_init.sql
• Modify: backend/accounts-service/src/lib.rs (run migrations on startup is done in main.rs, not build_app — tests don't need a live DB for Task 1's test)
• Modify: backend/accounts-service/Cargo.toml (sqlx already has migrate via the sqlx feature migrate; add it)
• Test: backend/accounts-service/tests/db_migration.rs

Interfaces:

• Produces: accounts table with columns id uuid PK, email text UNIQUE, password_hash text, display_nick text, role text NOT NULL DEFAULT 'user', can_publish_addons boolean NOT NULL DEFAULT true, created_at timestamptz NOT NULL DEFAULT now()

• Produces: avatars table account_id uuid PK REFERENCES accounts(id), s3_key text, uploaded_at timestamptz NOT NULL DEFAULT now()

• Produces: device_links table id uuid PK, account_id uuid REFERENCES accounts(id), device_token_hash text, linked_at timestamptz NOT NULL DEFAULT now(), last_seen timestamptz

• This task requires a real local Postgres reachable at DATABASE_URL — later tasks' tests assume the same. Document the prerequisite once here.

• Step 1: Add the migrate feature to sqlx

Edit backend/accounts-service/Cargo.toml, change the sqlx line to:

sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres", "uuid", "chrono", "macros", "migrate"] }

• Step 2: Write the migration

-- backend/accounts-service/migrations/0001_init.sql
CREATE TABLE accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email TEXT NOT NULL UNIQUE,
    password_hash TEXT NOT NULL,
    display_nick TEXT NOT NULL,
    role TEXT NOT NULL DEFAULT 'user',
    can_publish_addons BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE avatars (
    account_id UUID PRIMARY KEY REFERENCES accounts(id) ON DELETE CASCADE,
    s3_key TEXT NOT NULL,
    uploaded_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE device_links (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
    device_token_hash TEXT NOT NULL,
    linked_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    last_seen TIMESTAMPTZ
);

CREATE INDEX idx_device_links_account_id ON device_links(account_id);

gen_random_uuid() needs the pgcrypto extension. Add it at the top of the same file:

CREATE EXTENSION IF NOT EXISTS pgcrypto;

(Prepend this line to 0001_init.sql, before CREATE TABLE accounts.)

• Step 3: Ensure a local Postgres exists for tests

Document the one-time local setup (not a plan step to automate — infra prerequisite):

# One-time, run manually before continuing:
docker run -d --name lovisual-pg -e POSTGRES_USER=lovisual -e POSTGRES_PASSWORD=lovisual \
  -e POSTGRES_DB=accounts_db -p 5432:5432 postgres:16

• Step 4: Write the failing test

// backend/accounts-service/tests/db_migration.rs
#[tokio::test]
async fn migrations_create_accounts_table() {
    let database_url = std::env::var("DATABASE_URL")
        .unwrap_or_else(|_| "postgres://lovisual:lovisual@localhost:5432/accounts_db".into());
    let pool = sqlx::PgPool::connect(&database_url).await.expect("connect");

    sqlx::migrate!("./migrations").run(&pool).await.expect("migrate");

    let row: (i64,) = sqlx::query_as("SELECT count(*) FROM accounts")
        .fetch_one(&pool)
        .await
        .expect("accounts table must exist");
    assert_eq!(row.0, 0);
}

• Step 5: Run test to verify it fails (before migrations exist it errors; run once the SQL file above is in place — this step confirms the table truly gets created, not that it's absent)

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db cargo test --test db_migration Expected: PASS (this task's "test" is really a smoke test that migrations apply cleanly — there's no meaningful pre-migration state to assert against, so we go straight to green and treat this as an integration checkpoint, not strict TDD red/green)

• Step 6: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service
git commit -m "feat(backend): accounts/avatars/device_links schema + migration"

---

Task 3: Password hashing module

Files:

• Create: backend/accounts-service/src/auth/mod.rs
• Create: backend/accounts-service/src/auth/password.rs
• Modify: backend/accounts-service/src/lib.rs (add pub mod auth;)

Interfaces:

• Produces: pub fn hash_password(plain: &str) -> Result<String, argon2::password_hash::Error>

• Produces: pub fn verify_password(plain: &str, hash: &str) -> bool

• Consumed by: Task 5 (register/login handlers)

• Step 1: Write the failing test

// backend/accounts-service/src/auth/password.rs (tests at the bottom of the same file)
use argon2::{Argon2, PasswordHasher, PasswordVerifier};
use argon2::password_hash::phc::PasswordHash;

pub fn hash_password(plain: &str) -> Result<String, argon2::password_hash::Error> {
    let argon2 = Argon2::default();
    Ok(argon2.hash_password(plain.as_bytes())?.to_string())
}

pub fn verify_password(plain: &str, hash: &str) -> bool {
    let Ok(parsed) = PasswordHash::new(hash) else { return false };
    Argon2::default()
        .verify_password(plain.as_bytes(), &parsed)
        .is_ok()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn hash_then_verify_succeeds() {
        let hash = hash_password("correct-horse-battery-staple").unwrap();
        assert!(verify_password("correct-horse-battery-staple", &hash));
    }

    #[test]
    fn wrong_password_fails_verify() {
        let hash = hash_password("correct-horse-battery-staple").unwrap();
        assert!(!verify_password("wrong-password", &hash));
    }

    #[test]
    fn hash_is_not_the_plain_password() {
        let hash = hash_password("secret123").unwrap();
        assert_ne!(hash, "secret123");
    }
}

• Step 2: Wire the module

// backend/accounts-service/src/auth/mod.rs
pub mod password;

Add pub mod auth; to backend/accounts-service/src/lib.rs (near pub mod config;).

• Step 3: Run tests

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && cargo test password:: Expected: 3 tests pass

• Step 4: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service/src
git commit -m "feat(backend): argon2id password hashing"

---

Task 4: JWT issue/verify

Files:

• Create: backend/accounts-service/src/auth/jwt.rs
• Modify: backend/accounts-service/src/auth/mod.rs (add pub mod jwt;)

Interfaces:

• Consumes: nothing new (takes account_id: uuid::Uuid, secret: &str as plain params — no dependency on DB types)

• Produces: pub struct Claims { pub sub: String, pub exp: usize, pub token_type: String }

• Produces: pub fn issue_access_token(account_id: Uuid, secret: &str) -> String (15 min expiry, token_type: "access")

• Produces: pub fn issue_refresh_token(account_id: Uuid, secret: &str) -> String (30 day expiry, token_type: "refresh")

• Produces: pub fn verify_token(token: &str, secret: &str) -> Option<Claims> — returns None on any invalid/expired/malformed token, never panics

• Step 1: Write the failing test

// backend/accounts-service/src/auth/jwt.rs
use jsonwebtoken::{decode, encode, DecodingKey, EncodingKey, Header, Validation};
use serde::{Deserialize, Serialize};
use uuid::Uuid;

#[derive(Debug, Serialize, Deserialize)]
pub struct Claims {
    pub sub: String,
    pub exp: usize,
    pub token_type: String,
}

fn issue(account_id: Uuid, secret: &str, token_type: &str, ttl_seconds: i64) -> String {
    let exp = (chrono::Utc::now() + chrono::Duration::seconds(ttl_seconds)).timestamp() as usize;
    let claims = Claims { sub: account_id.to_string(), exp, token_type: token_type.into() };
    encode(&Header::default(), &claims, &EncodingKey::from_secret(secret.as_bytes()))
        .expect("encoding a well-formed Claims struct cannot fail")
}

pub fn issue_access_token(account_id: Uuid, secret: &str) -> String {
    issue(account_id, secret, "access", 15 * 60)
}

pub fn issue_refresh_token(account_id: Uuid, secret: &str) -> String {
    issue(account_id, secret, "refresh", 30 * 24 * 60 * 60)
}

pub fn verify_token(token: &str, secret: &str) -> Option<Claims> {
    decode::<Claims>(
        token,
        &DecodingKey::from_secret(secret.as_bytes()),
        &Validation::default(),
    )
    .ok()
    .map(|data| data.claims)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn access_token_round_trips() {
        let id = Uuid::new_v4();
        let token = issue_access_token(id, "test-secret");
        let claims = verify_token(&token, "test-secret").expect("should decode");
        assert_eq!(claims.sub, id.to_string());
        assert_eq!(claims.token_type, "access");
    }

    #[test]
    fn wrong_secret_fails_verify() {
        let token = issue_access_token(Uuid::new_v4(), "test-secret");
        assert!(verify_token(&token, "other-secret").is_none());
    }

    #[test]
    fn garbage_token_fails_verify() {
        assert!(verify_token("not.a.jwt", "test-secret").is_none());
    }
}

• Step 2: Wire the module

Add pub mod jwt; to backend/accounts-service/src/auth/mod.rs.

• Step 3: Run tests

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && cargo test jwt:: Expected: 3 tests pass

• Step 4: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service/src
git commit -m "feat(backend): JWT access/refresh token issue and verify"

---

Task 5: Accounts repository

Files:

• Create: backend/accounts-service/src/accounts/mod.rs
• Create: backend/accounts-service/src/accounts/model.rs
• Create: backend/accounts-service/src/accounts/repo.rs
• Modify: backend/accounts-service/src/lib.rs (add pub mod accounts;)

Interfaces:

• Consumes: sqlx::PgPool (from Task 1/2)

• Produces: pub struct Account { pub id: Uuid, pub email: String, pub password_hash: String, pub display_nick: String, pub role: String, pub can_publish_addons: bool, pub created_at: chrono::DateTime<chrono::Utc> }

• Produces: pub async fn create(pool: &PgPool, email: &str, password_hash: &str, nick: &str) -> Result<Account, sqlx::Error>

• Produces: pub async fn find_by_email(pool: &PgPool, email: &str) -> Result<Option<Account>, sqlx::Error>

• Produces: unique-violation on duplicate email surfaces as sqlx::Error::Database — callers (Task 6) match on .constraint() == Some("accounts_email_key")

• Step 1: Write the model

// backend/accounts-service/src/accounts/model.rs
use chrono::{DateTime, Utc};
use serde::Serialize;
use uuid::Uuid;

#[derive(Debug, Clone, sqlx::FromRow, Serialize)]
pub struct Account {
    pub id: Uuid,
    pub email: String,
    #[serde(skip_serializing)]
    pub password_hash: String,
    pub display_nick: String,
    pub role: String,
    pub can_publish_addons: bool,
    pub created_at: DateTime<Utc>,
}

• Step 2: Write the failing test (integration, needs the live Postgres from Task 2)

// backend/accounts-service/src/accounts/repo.rs
use super::model::Account;
use sqlx::PgPool;
use uuid::Uuid;

pub async fn create(
    pool: &PgPool,
    email: &str,
    password_hash: &str,
    nick: &str,
) -> Result<Account, sqlx::Error> {
    sqlx::query_as::<_, Account>(
        "INSERT INTO accounts (email, password_hash, display_nick)
         VALUES ($1, $2, $3)
         RETURNING id, email, password_hash, display_nick, role, can_publish_addons, created_at",
    )
    .bind(email)
    .bind(password_hash)
    .bind(nick)
    .fetch_one(pool)
    .await
}

pub async fn find_by_email(pool: &PgPool, email: &str) -> Result<Option<Account>, sqlx::Error> {
    sqlx::query_as::<_, Account>(
        "SELECT id, email, password_hash, display_nick, role, can_publish_addons, created_at
         FROM accounts WHERE email = $1",
    )
    .bind(email)
    .fetch_optional(pool)
    .await
}

pub async fn find_by_id(pool: &PgPool, id: Uuid) -> Result<Option<Account>, sqlx::Error> {
    sqlx::query_as::<_, Account>(
        "SELECT id, email, password_hash, display_nick, role, can_publish_addons, created_at
         FROM accounts WHERE id = $1",
    )
    .bind(id)
    .fetch_optional(pool)
    .await
}

#[cfg(test)]
mod tests {
    use super::*;

    async fn test_pool() -> PgPool {
        let url = std::env::var("DATABASE_URL")
            .unwrap_or_else(|_| "postgres://lovisual:lovisual@localhost:5432/accounts_db".into());
        let pool = PgPool::connect(&url).await.expect("connect");
        sqlx::migrate!("./migrations").run(&pool).await.expect("migrate");
        pool
    }

    #[tokio::test]
    async fn create_then_find_by_email_round_trips() {
        let pool = test_pool().await;
        let email = format!("test-{}@example.com", Uuid::new_v4());

        let created = create(&pool, &email, "hash123", "TestNick").await.unwrap();
        assert_eq!(created.email, email);
        assert_eq!(created.role, "user");
        assert!(created.can_publish_addons);

        let found = find_by_email(&pool, &email).await.unwrap().expect("must exist");
        assert_eq!(found.id, created.id);

        sqlx::query("DELETE FROM accounts WHERE id = $1")
            .bind(created.id)
            .execute(&pool)
            .await
            .unwrap();
    }

    #[tokio::test]
    async fn find_by_email_returns_none_for_missing() {
        let pool = test_pool().await;
        let result = find_by_email(&pool, "does-not-exist@example.com").await.unwrap();
        assert!(result.is_none());
    }
}

• Step 3: Wire the module

// backend/accounts-service/src/accounts/mod.rs
pub mod model;
pub mod repo;

Add pub mod accounts; to backend/accounts-service/src/lib.rs.

• Step 4: Run tests

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db cargo test accounts::repo:: Expected: 2 tests pass

• Step 5: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service/src
git commit -m "feat(backend): accounts repository (create/find_by_email/find_by_id)"

---

Task 6: POST /auth/register and POST /auth/login

Files:

• Create: backend/accounts-service/src/error.rs
• Create: backend/accounts-service/src/auth/handlers.rs
• Modify: backend/accounts-service/src/auth/mod.rs (add pub mod handlers;)
• Modify: backend/accounts-service/src/lib.rs (build_app now takes routes + real pool; add .route("/auth/register", post(...)) etc.)
• Test: backend/accounts-service/tests/auth_flow.rs

Interfaces:

• Consumes: auth::password::{hash_password, verify_password} (Task 3), auth::jwt::{issue_access_token, issue_refresh_token} (Task 4), accounts::repo::{create, find_by_email} (Task 5)

• Produces: AppError enum implementing axum::response::IntoResponse, variants Validation(String) -> 400, Conflict(String) -> 409, Unauthorized -> 401, Internal(anyhow::Error) -> 500

• Produces: JSON contract — POST /auth/register body {email, password, nick} → 201 {id, email, display_nick}; POST /auth/login body {email, password} → 200 {access_token, refresh_token}

• Step 1: Write error.rs

// backend/accounts-service/src/error.rs
use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
use serde_json::json;

#[derive(Debug)]
pub enum AppError {
    Validation(String),
    Conflict(String),
    Unauthorized,
    Internal(anyhow::Error),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::Validation(msg) => (StatusCode::BAD_REQUEST, msg),
            AppError::Conflict(msg) => (StatusCode::CONFLICT, msg),
            AppError::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized".into()),
            AppError::Internal(err) => {
                tracing::error!("internal error: {err:?}");
                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".into())
            }
        };
        (status, Json(json!({ "error": message }))).into_response()
    }
}

impl From<sqlx::Error> for AppError {
    fn from(err: sqlx::Error) -> Self {
        if let sqlx::Error::Database(ref db_err) = err {
            if db_err.constraint() == Some("accounts_email_key") {
                return AppError::Conflict("email already registered".into());
            }
        }
        AppError::Internal(err.into())
    }
}

• Step 2: Write the failing test

// backend/accounts-service/tests/auth_flow.rs
use axum_test::TestServer;
use serde_json::json;
use uuid::Uuid;

async fn test_pool() -> sqlx::PgPool {
    let url = std::env::var("DATABASE_URL")
        .unwrap_or_else(|_| "postgres://lovisual:lovisual@localhost:5432/accounts_db".into());
    let pool = sqlx::PgPool::connect(&url).await.expect("connect");
    sqlx::migrate!("../migrations").run(&pool).await.expect("migrate");
    pool
}

#[tokio::test]
async fn register_then_login_succeeds() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into());
    let server = TestServer::new(app);
    let email = format!("flow-{}@example.com", Uuid::new_v4());

    let register_response = server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "correct-horse-battery-staple", "nick": "Rider" }))
        .await;
    register_response.assert_status(axum::http::StatusCode::CREATED);

    let login_response = server
        .post("/auth/login")
        .json(&json!({ "email": email, "password": "correct-horse-battery-staple" }))
        .await;
    login_response.assert_status_ok();
    let body: serde_json::Value = login_response.json();
    assert!(body["access_token"].is_string());
    assert!(body["refresh_token"].is_string());

    sqlx::query("DELETE FROM accounts WHERE email = $1")
        .bind(&email)
        .execute(&pool)
        .await
        .unwrap();
}

#[tokio::test]
async fn login_with_wrong_password_returns_401() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into());
    let server = TestServer::new(app);
    let email = format!("wrongpw-{}@example.com", Uuid::new_v4());

    server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "right-password", "nick": "Rider" }))
        .await
        .assert_status(axum::http::StatusCode::CREATED);

    let login_response = server
        .post("/auth/login")
        .json(&json!({ "email": email, "password": "wrong-password" }))
        .await;
    login_response.assert_status(axum::http::StatusCode::UNAUTHORIZED);

    sqlx::query("DELETE FROM accounts WHERE email = $1")
        .bind(&email)
        .execute(&pool)
        .await
        .unwrap();
}

#[tokio::test]
async fn duplicate_email_registration_returns_409() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into());
    let server = TestServer::new(app);
    let email = format!("dup-{}@example.com", Uuid::new_v4());

    server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "password123", "nick": "First" }))
        .await
        .assert_status(axum::http::StatusCode::CREATED);

    let second = server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "password456", "nick": "Second" }))
        .await;
    second.assert_status(axum::http::StatusCode::CONFLICT);

    sqlx::query("DELETE FROM accounts WHERE email = $1")
        .bind(&email)
        .execute(&pool)
        .await
        .unwrap();
}

• Step 3: Run the tests to see them fail to compile (build_app signature doesn't match yet)

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db cargo test --test auth_flow Expected: compile error, build_app takes 1 argument but 2 were supplied

• Step 4: Write the handlers

// backend/accounts-service/src/auth/handlers.rs
use crate::accounts::repo;
use crate::auth::{jwt, password};
use crate::error::AppError;
use axum::{extract::State, http::StatusCode, Json};
use serde::{Deserialize, Serialize};

#[derive(Clone)]
pub struct AuthState {
    pub pool: sqlx::PgPool,
    pub jwt_secret: String,
}

#[derive(Deserialize)]
pub struct RegisterRequest {
    pub email: String,
    pub password: String,
    pub nick: String,
}

#[derive(Serialize)]
pub struct RegisterResponse {
    pub id: uuid::Uuid,
    pub email: String,
    pub display_nick: String,
}

pub async fn register(
    State(state): State<AuthState>,
    Json(req): Json<RegisterRequest>,
) -> Result<(StatusCode, Json<RegisterResponse>), AppError> {
    if req.password.len() < 8 {
        return Err(AppError::Validation("password must be at least 8 characters".into()));
    }
    let hash = password::hash_password(&req.password)
        .map_err(|e| AppError::Internal(anyhow::anyhow!(e)))?;
    let account = repo::create(&state.pool, &req.email, &hash, &req.nick).await?;
    Ok((
        StatusCode::CREATED,
        Json(RegisterResponse {
            id: account.id,
            email: account.email,
            display_nick: account.display_nick,
        }),
    ))
}

#[derive(Deserialize)]
pub struct LoginRequest {
    pub email: String,
    pub password: String,
}

#[derive(Serialize)]
pub struct LoginResponse {
    pub access_token: String,
    pub refresh_token: String,
}

pub async fn login(
    State(state): State<AuthState>,
    Json(req): Json<LoginRequest>,
) -> Result<Json<LoginResponse>, AppError> {
    let account = repo::find_by_email(&state.pool, &req.email)
        .await?
        .ok_or(AppError::Unauthorized)?;
    if !password::verify_password(&req.password, &account.password_hash) {
        return Err(AppError::Unauthorized);
    }
    Ok(Json(LoginResponse {
        access_token: jwt::issue_access_token(account.id, &state.jwt_secret),
        refresh_token: jwt::issue_refresh_token(account.id, &state.jwt_secret),
    }))
}

• Step 5: Wire build_app in lib.rs

// backend/accounts-service/src/lib.rs
pub mod config;
pub mod error;
pub mod auth;
pub mod accounts;

use auth::handlers::AuthState;
use axum::{routing::{get, post}, Router};

pub fn build_app(pool: sqlx::PgPool, jwt_secret: String) -> Router {
    let state = AuthState { pool, jwt_secret };
    Router::new()
        .route("/health", get(|| async { "ok" }))
        .route("/auth/register", post(auth::handlers::register))
        .route("/auth/login", post(auth::handlers::login))
        .with_state(state)
}

Add pub mod handlers; to backend/accounts-service/src/auth/mod.rs.

Update backend/accounts-service/src/main.rs call site: build_app(pool, cfg.jwt_secret.clone()).

Update Task 1's tests/health.rs call site to match the new signature: accounts_service::build_app(pool, "test-secret".into()).

• Step 6: Run tests

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db cargo test Expected: all tests pass (health, jwt, password, accounts::repo, auth_flow)

• Step 7: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service
git commit -m "feat(backend): POST /auth/register and /auth/login"

---

Task 7: Device Authorization Grant (/device/code, /device/confirm, /device/token)

Files:

• Create: backend/accounts-service/src/device/mod.rs
• Create: backend/accounts-service/src/device/store.rs
• Create: backend/accounts-service/src/device/handlers.rs
• Modify: backend/accounts-service/src/lib.rs (mount routes, extend shared state)
• Test: backend/accounts-service/tests/device_flow.rs

Interfaces:

• Consumes: jwt::verify_token (Task 4, to authenticate the /device/confirm caller — that endpoint requires a valid site access token in Authorization: Bearer)

• Produces: DeviceStore (in-memory DashMap<String, DeviceCodeEntry>, keyed by device_code), pub fn new_pair() -> (String, String) returning (device_code, user_code) where user_code is formatted XXXX-XXXX from [A-Z0-9]

• Produces: POST /device/code → 201 {device_code, user_code, expires_in: 600}

• Produces: POST /device/confirm (auth required) body {user_code} → 200 {} or 404 if code unknown/expired

• Produces: POST /device/token body {device_code} → 200 {device_token} once confirmed, 202 {} (still pending) before confirmation, 404 if unknown/expired

• Step 1: Write the device code store

// backend/accounts-service/src/device/store.rs
use dashmap::DashMap;
use rand::Rng;
use std::sync::Arc;
use std::time::{Duration, Instant};
use uuid::Uuid;

#[derive(Clone)]
pub struct DeviceCodeEntry {
    pub user_code: String,
    pub confirmed_account_id: Option<Uuid>,
    pub expires_at: Instant,
}

#[derive(Clone, Default)]
pub struct DeviceStore {
    by_device_code: Arc<DashMap<String, DeviceCodeEntry>>,
}

const TTL: Duration = Duration::from_secs(600);

fn random_user_code() -> String {
    use rand::RngExt;
    const ALPHABET: &[u8] = b"ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; // no O/0/I/1 confusion
    let mut rng = rand::rng();
    let mut part = |n: usize| -> String {
        (0..n).map(|_| ALPHABET[rng.random_range(0..ALPHABET.len())] as char).collect()
    };
    format!("{}-{}", part(4), part(4))
}

impl DeviceStore {
    pub fn create(&self) -> (String, String) {
        let device_code = Uuid::new_v4().to_string();
        let user_code = random_user_code();
        self.by_device_code.insert(
            device_code.clone(),
            DeviceCodeEntry {
                user_code: user_code.clone(),
                confirmed_account_id: None,
                expires_at: Instant::now() + TTL,
            },
        );
        (device_code, user_code)
    }

    /// Returns true if a matching, unexpired entry was found and confirmed.
    pub fn confirm(&self, user_code: &str, account_id: Uuid) -> bool {
        for mut entry in self.by_device_code.iter_mut() {
            if entry.user_code == user_code && entry.expires_at > Instant::now() {
                entry.confirmed_account_id = Some(account_id);
                return true;
            }
        }
        false
    }

    /// None = unknown/expired. Some(None) = pending. Some(Some(id)) = confirmed.
    pub fn poll(&self, device_code: &str) -> Option<Option<Uuid>> {
        let entry = self.by_device_code.get(device_code)?;
        if entry.expires_at <= Instant::now() {
            return None;
        }
        Some(entry.confirmed_account_id)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn create_returns_distinct_codes() {
        let store = DeviceStore::default();
        let (dc1, uc1) = store.create();
        let (dc2, uc2) = store.create();
        assert_ne!(dc1, dc2);
        assert_ne!(uc1, uc2);
    }

    #[test]
    fn confirm_then_poll_returns_account_id() {
        let store = DeviceStore::default();
        let (device_code, user_code) = store.create();
        let account_id = Uuid::new_v4();

        assert!(store.confirm(&user_code, account_id));
        assert_eq!(store.poll(&device_code), Some(Some(account_id)));
    }

    #[test]
    fn poll_before_confirm_is_pending() {
        let store = DeviceStore::default();
        let (device_code, _user_code) = store.create();
        assert_eq!(store.poll(&device_code), Some(None));
    }

    #[test]
    fn poll_unknown_code_returns_none() {
        let store = DeviceStore::default();
        assert_eq!(store.poll("does-not-exist"), None);
    }

    #[test]
    fn confirm_unknown_user_code_returns_false() {
        let store = DeviceStore::default();
        assert!(!store.confirm("ZZZZ-ZZZZ", Uuid::new_v4()));
    }
}

• Step 2: Run the store's unit tests

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && cargo test device::store:: Expected: 5 tests pass

• Step 3: Write the handlers

// backend/accounts-service/src/device/handlers.rs
use crate::device::store::DeviceStore;
use crate::error::AppError;
use axum::{extract::State, http::{HeaderMap, StatusCode}, Json};
use serde::{Deserialize, Serialize};

#[derive(Clone)]
pub struct DeviceState {
    pub store: DeviceStore,
    pub jwt_secret: String,
}

#[derive(Serialize)]
pub struct DeviceCodeResponse {
    pub device_code: String,
    pub user_code: String,
    pub expires_in: u64,
}

pub async fn create_code(
    State(state): State<DeviceState>,
) -> (StatusCode, Json<DeviceCodeResponse>) {
    let (device_code, user_code) = state.store.create();
    (
        StatusCode::CREATED,
        Json(DeviceCodeResponse { device_code, user_code, expires_in: 600 }),
    )
}

#[derive(Deserialize)]
pub struct ConfirmRequest {
    pub user_code: String,
}

fn account_id_from_auth_header(headers: &HeaderMap, secret: &str) -> Result<uuid::Uuid, AppError> {
    let header = headers
        .get(axum::http::header::AUTHORIZATION)
        .and_then(|v| v.to_str().ok())
        .ok_or(AppError::Unauthorized)?;
    let token = header.strip_prefix("Bearer ").ok_or(AppError::Unauthorized)?;
    let claims = crate::auth::jwt::verify_token(token, secret).ok_or(AppError::Unauthorized)?;
    claims.sub.parse().map_err(|_| AppError::Unauthorized)
}

pub async fn confirm(
    State(state): State<DeviceState>,
    headers: HeaderMap,
    Json(req): Json<ConfirmRequest>,
) -> Result<StatusCode, AppError> {
    let account_id = account_id_from_auth_header(&headers, &state.jwt_secret)?;
    if state.store.confirm(&req.user_code, account_id) {
        Ok(StatusCode::OK)
    } else {
        Err(AppError::Validation("unknown or expired user_code".into()))
    }
}

#[derive(Deserialize)]
pub struct TokenRequest {
    pub device_code: String,
}

#[derive(Serialize)]
pub struct TokenResponse {
    pub device_token: String,
}

pub async fn token(
    State(state): State<DeviceState>,
    Json(req): Json<TokenRequest>,
) -> Result<(StatusCode, Json<Option<TokenResponse>>), AppError> {
    match state.store.poll(&req.device_code) {
        None => Err(AppError::Validation("unknown or expired device_code".into())),
        Some(None) => Ok((StatusCode::ACCEPTED, Json(None))),
        Some(Some(account_id)) => {
            // The long-lived device_token is just a refresh-style JWT for now;
            // Task 8+ (gateway plan) is where per-device revocation via
            // device_links.device_token_hash gets enforced on every request.
            let device_token = crate::auth::jwt::issue_refresh_token(account_id, &state.jwt_secret);
            Ok((StatusCode::OK, Json(Some(TokenResponse { device_token }))))
        }
    }
}

• Step 4: Write the module file

// backend/accounts-service/src/device/mod.rs
pub mod store;
pub mod handlers;

• Step 5: Write the failing integration test

// backend/accounts-service/tests/device_flow.rs
use axum_test::TestServer;
use serde_json::json;
use uuid::Uuid;

async fn test_pool() -> sqlx::PgPool {
    let url = std::env::var("DATABASE_URL")
        .unwrap_or_else(|_| "postgres://lovisual:lovisual@localhost:5432/accounts_db".into());
    let pool = sqlx::PgPool::connect(&url).await.expect("connect");
    sqlx::migrate!("../migrations").run(&pool).await.expect("migrate");
    pool
}

#[tokio::test]
async fn full_device_link_flow() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into());
    let server = TestServer::new(app);
    let email = format!("device-{}@example.com", Uuid::new_v4());

    server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "password123", "nick": "Rider" }))
        .await
        .assert_status(axum::http::StatusCode::CREATED);
    let login: serde_json::Value = server
        .post("/auth/login")
        .json(&json!({ "email": email, "password": "password123" }))
        .await
        .json();
    let access_token = login["access_token"].as_str().unwrap();

    let code_response: serde_json::Value =
        server.post("/device/code").await.json();
    let device_code = code_response["device_code"].as_str().unwrap();
    let user_code = code_response["user_code"].as_str().unwrap();

    let poll_before = server
        .post("/device/token")
        .json(&json!({ "device_code": device_code }))
        .await;
    poll_before.assert_status(axum::http::StatusCode::ACCEPTED);

    server
        .post("/device/confirm")
        .add_header(
            axum::http::header::AUTHORIZATION,
            format!("Bearer {access_token}"),
        )
        .json(&json!({ "user_code": user_code }))
        .await
        .assert_status_ok();

    let poll_after = server
        .post("/device/token")
        .json(&json!({ "device_code": device_code }))
        .await;
    poll_after.assert_status_ok();
    let token_body: serde_json::Value = poll_after.json();
    assert!(token_body["device_token"].is_string());

    sqlx::query("DELETE FROM accounts WHERE email = $1")
        .bind(&email)
        .execute(&pool)
        .await
        .unwrap();
}

• Step 6: Wire routes in lib.rs

// backend/accounts-service/src/lib.rs
pub mod config;
pub mod error;
pub mod auth;
pub mod accounts;
pub mod device;

use auth::handlers::AuthState;
use device::{handlers::DeviceState, store::DeviceStore};
use axum::{routing::{get, post}, Router};

pub fn build_app(pool: sqlx::PgPool, jwt_secret: String) -> Router {
    let auth_state = AuthState { pool: pool.clone(), jwt_secret: jwt_secret.clone() };
    let device_state = DeviceState { store: DeviceStore::default(), jwt_secret: jwt_secret.clone() };

    let auth_routes = Router::new()
        .route("/auth/register", post(auth::handlers::register))
        .route("/auth/login", post(auth::handlers::login))
        .with_state(auth_state);

    let device_routes = Router::new()
        .route("/device/code", post(device::handlers::create_code))
        .route("/device/confirm", post(device::handlers::confirm))
        .route("/device/token", post(device::handlers::token))
        .with_state(device_state);

    Router::new()
        .route("/health", get(|| async { "ok" }))
        .merge(auth_routes)
        .merge(device_routes)
}

• Step 7: Run all tests

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db cargo test Expected: all pass, including full_device_link_flow

• Step 8: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service
git commit -m "feat(backend): OAuth device authorization grant for mod login"

---

Task 8: Avatar upload (POST /avatars)

Files:

• Create: backend/accounts-service/src/avatars/mod.rs
• Create: backend/accounts-service/src/avatars/storage.rs
• Create: backend/accounts-service/src/avatars/handlers.rs
• Modify: backend/accounts-service/src/lib.rs (mount route, extend build_app signature with S3 client)
• Test: backend/accounts-service/tests/avatar_upload.rs

Interfaces:

• Consumes: jwt::verify_token (Task 4, auth on this endpoint), accounts::repo pattern extended with update_avatar (new function in this task)

• Produces: pub struct S3Storage { client: aws_sdk_s3::Client, bucket: String } with pub async fn put(&self, key: &str, bytes: Vec<u8>, content_type: &str) -> anyhow::Result<()>

• Produces: POST /avatars (multipart, auth required, field name file) → 200 {avatar_url}; rejects >5MB with 413, rejects non-image magic bytes with 400

• This task requires a local MinIO for tests: docker run -d --name lovisual-minio -p 9000:9000 -e MINIO_ROOT_USER=minioadmin -e MINIO_ROOT_PASSWORD=minioadmin minio/minio server /data (one-time manual setup, same as Task 2's Postgres)

• Step 1: Write the S3 storage wrapper

// backend/accounts-service/src/avatars/storage.rs
use aws_sdk_s3::primitives::ByteStream;
use aws_sdk_s3::Client;

#[derive(Clone)]
pub struct S3Storage {
    pub client: Client,
    pub bucket: String,
}

impl S3Storage {
    pub async fn from_config(
        endpoint: &str,
        access_key: &str,
        secret_key: &str,
        bucket: String,
    ) -> Self {
        let creds = aws_sdk_s3::config::Credentials::new(access_key, secret_key, None, None, "static");
        let config = aws_sdk_s3::config::Builder::new()
            .endpoint_url(endpoint)
            .credentials_provider(creds)
            .region(aws_sdk_s3::config::Region::new("us-east-1"))
            .force_path_style(true)
            .behavior_version(aws_sdk_s3::config::BehaviorVersion::latest())
            .build();
        S3Storage { client: Client::from_conf(config), bucket }
    }

    pub async fn put(&self, key: &str, bytes: Vec<u8>, content_type: &str) -> anyhow::Result<()> {
        self.client
            .put_object()
            .bucket(&self.bucket)
            .key(key)
            .body(ByteStream::from(bytes))
            .content_type(content_type)
            .send()
            .await?;
        Ok(())
    }
}

• Step 2: Write the magic-byte content sniffer + handler

// backend/accounts-service/src/avatars/handlers.rs
use crate::avatars::storage::S3Storage;
use crate::error::AppError;
use axum::{extract::{Multipart, State}, http::HeaderMap, Json};
use serde::Serialize;

const MAX_AVATAR_BYTES: usize = 5 * 1024 * 1024;

#[derive(Clone)]
pub struct AvatarState {
    pub storage: S3Storage,
    pub jwt_secret: String,
    pub public_base_url: String,
}

fn sniff_image_type(bytes: &[u8]) -> Option<&'static str> {
    if bytes.starts_with(&[0x89, 0x50, 0x4E, 0x47]) {
        Some("image/png")
    } else if bytes.starts_with(&[0xFF, 0xD8, 0xFF]) {
        Some("image/jpeg")
    } else if bytes.len() > 12 && &bytes[8..12] == b"WEBP" {
        Some("image/webp")
    } else {
        None
    }
}

fn account_id_from_auth_header(headers: &HeaderMap, secret: &str) -> Result<uuid::Uuid, AppError> {
    let header = headers
        .get(axum::http::header::AUTHORIZATION)
        .and_then(|v| v.to_str().ok())
        .ok_or(AppError::Unauthorized)?;
    let token = header.strip_prefix("Bearer ").ok_or(AppError::Unauthorized)?;
    let claims = crate::auth::jwt::verify_token(token, secret).ok_or(AppError::Unauthorized)?;
    claims.sub.parse().map_err(|_| AppError::Unauthorized)
}

#[derive(Serialize)]
pub struct AvatarResponse {
    pub avatar_url: String,
}

pub async fn upload(
    State(state): State<AvatarState>,
    headers: HeaderMap,
    mut multipart: Multipart,
) -> Result<Json<AvatarResponse>, AppError> {
    let account_id = account_id_from_auth_header(&headers, &state.jwt_secret)?;

    let field = multipart
        .next_field()
        .await
        .map_err(|e| AppError::Validation(e.to_string()))?
        .ok_or_else(|| AppError::Validation("missing file field".into()))?;

    let bytes = field
        .bytes()
        .await
        .map_err(|e| AppError::Validation(e.to_string()))?;

    if bytes.len() > MAX_AVATAR_BYTES {
        return Err(AppError::Validation("file too large (max 5MB)".into()));
    }

    let content_type = sniff_image_type(&bytes)
        .ok_or_else(|| AppError::Validation("unsupported image format".into()))?;

    let key = format!("avatars/{account_id}.bin");
    state
        .storage
        .put(&key, bytes.to_vec(), content_type)
        .await
        .map_err(AppError::Internal)?;

    Ok(Json(AvatarResponse {
        avatar_url: format!("{}/{}", state.public_base_url, key),
    }))
}

• Step 3: Write the module file

// backend/accounts-service/src/avatars/mod.rs
pub mod storage;
pub mod handlers;

• Step 4: Write the failing test

// backend/accounts-service/tests/avatar_upload.rs
use axum_test::TestServer;
use serde_json::json;
use uuid::Uuid;

async fn test_pool() -> sqlx::PgPool {
    let url = std::env::var("DATABASE_URL")
        .unwrap_or_else(|_| "postgres://lovisual:lovisual@localhost:5432/accounts_db".into());
    let pool = sqlx::PgPool::connect(&url).await.expect("connect");
    sqlx::migrate!("../migrations").run(&pool).await.expect("migrate");
    pool
}

// 1x1 red pixel PNG
const TINY_PNG: &[u8] = &[
    0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53,
    0xDE, 0x00, 0x00, 0x00, 0x0C, 0x49, 0x44, 0x41, 0x54, 0x08, 0xD7, 0x63, 0xF8, 0xCF, 0xC0, 0x00,
    0x00, 0x03, 0x01, 0x01, 0x00, 0x18, 0xDD, 0x8D, 0xB0, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E,
    0x44, 0xAE, 0x42, 0x60, 0x82,
];

#[tokio::test]
async fn upload_valid_png_returns_avatar_url() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into()).await;
    let server = TestServer::new(app);
    let email = format!("avatar-{}@example.com", Uuid::new_v4());

    server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "password123", "nick": "Rider" }))
        .await
        .assert_status(axum::http::StatusCode::CREATED);
    let login: serde_json::Value = server
        .post("/auth/login")
        .json(&json!({ "email": email, "password": "password123" }))
        .await
        .json();
    let access_token = login["access_token"].as_str().unwrap();

    let response = server
        .post("/avatars")
        .add_header(
            axum::http::header::AUTHORIZATION,
            format!("Bearer {access_token}"),
        )
        .multipart(
            axum_test::multipart::MultipartForm::new().add_part(
                "file",
                axum_test::multipart::Part::bytes(TINY_PNG.to_vec())
                    .file_name("avatar.png")
                    .mime_type("image/png"),
            ),
        )
        .await;
    response.assert_status_ok();
    let body: serde_json::Value = response.json();
    assert!(body["avatar_url"].as_str().unwrap().contains("avatars/"));

    sqlx::query("DELETE FROM accounts WHERE email = $1")
        .bind(&email)
        .execute(&pool)
        .await
        .unwrap();
}

#[tokio::test]
async fn upload_non_image_bytes_returns_400() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into()).await;
    let server = TestServer::new(app);
    let email = format!("badavatar-{}@example.com", Uuid::new_v4());

    server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "password123", "nick": "Rider" }))
        .await
        .assert_status(axum::http::StatusCode::CREATED);
    let login: serde_json::Value = server
        .post("/auth/login")
        .json(&json!({ "email": email, "password": "password123" }))
        .await
        .json();
    let access_token = login["access_token"].as_str().unwrap();

    let response = server
        .post("/avatars")
        .add_header(
            axum::http::header::AUTHORIZATION,
            format!("Bearer {access_token}"),
        )
        .multipart(
            axum_test::multipart::MultipartForm::new().add_part(
                "file",
                axum_test::multipart::Part::bytes(b"not an image".to_vec())
                    .file_name("fake.png")
                    .mime_type("image/png"),
            ),
        )
        .await;
    response.assert_status(axum::http::StatusCode::BAD_REQUEST);

    sqlx::query("DELETE FROM accounts WHERE email = $1")
        .bind(&email)
        .execute(&pool)
        .await
        .unwrap();
}

• Step 5: Wire the route, make build_app async (S3 client setup is async) and thread config through

// backend/accounts-service/src/lib.rs
pub mod config;
pub mod error;
pub mod auth;
pub mod accounts;
pub mod device;
pub mod avatars;

use auth::handlers::AuthState;
use avatars::{handlers::AvatarState, storage::S3Storage};
use device::{handlers::DeviceState, store::DeviceStore};
use axum::{extract::DefaultBodyLimit, routing::{get, post}, Router};
use config::Config;

pub async fn build_app(pool: sqlx::PgPool, cfg: Config) -> Router {
    let auth_state = AuthState { pool: pool.clone(), jwt_secret: cfg.jwt_secret.clone() };
    let device_state = DeviceState { store: DeviceStore::default(), jwt_secret: cfg.jwt_secret.clone() };
    let storage = S3Storage::from_config(
        &cfg.s3_endpoint,
        &cfg.s3_access_key,
        &cfg.s3_secret_key,
        cfg.s3_bucket.clone(),
    )
    .await;
    let avatar_state = AvatarState {
        storage,
        jwt_secret: cfg.jwt_secret.clone(),
        public_base_url: cfg.s3_endpoint.clone(),
    };

    let auth_routes = Router::new()
        .route("/auth/register", post(auth::handlers::register))
        .route("/auth/login", post(auth::handlers::login))
        .with_state(auth_state);

    let device_routes = Router::new()
        .route("/device/code", post(device::handlers::create_code))
        .route("/device/confirm", post(device::handlers::confirm))
        .route("/device/token", post(device::handlers::token))
        .with_state(device_state);

    let avatar_routes = Router::new()
        .route("/avatars", post(avatars::handlers::upload))
        .layer(DefaultBodyLimit::max(6 * 1024 * 1024))
        .with_state(avatar_state);

    Router::new()
        .route("/health", get(|| async { "ok" }))
        .merge(auth_routes)
        .merge(device_routes)
        .merge(avatar_routes)
}

build_app is now async and takes Config instead of (pool, jwt_secret) — update every call site:

• main.rs: let app = build_app(pool, cfg).await;
• tests/health.rs, tests/auth_flow.rs, tests/device_flow.rs: build a Config with test values instead of passing "test-secret".into() directly, e.g.:

fn test_config() -> accounts_service::config::Config {
    accounts_service::config::Config {
        database_url: String::new(), // unused, pool is passed separately
        jwt_secret: "test-secret".into(),
        port: 0,
        s3_endpoint: "http://localhost:9000".into(),
        s3_bucket: "lovisual-avatars-test".into(),
        s3_access_key: "minioadmin".into(),
        s3_secret_key: "minioadmin".into(),
    }
}

and change every accounts_service::build_app(pool.clone(), "test-secret".into()) to accounts_service::build_app(pool.clone(), test_config()).await.

• Step 6: Create the test bucket once, manually

docker exec lovisual-minio mkdir -p /data/lovisual-avatars-test

• Step 7: Run all tests

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db S3_BUCKET=lovisual-avatars-test cargo test Expected: all pass

• Step 8: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service
git commit -m "feat(backend): avatar upload with magic-byte validation and S3 storage"

---

What this plan does not cover (deliberately, next plans)

• API Gateway (routing, single JWT check point, rate limiting per TODO.md Фаза 10 §6) — separate plan, depends on this one existing.
• configs-service (4 config slots, share codes, showcase) — separate plan, same pattern as this one.
• React/Vite/Tailwind frontend — separate plan, depends on the gateway plan for a stable API surface.
• Refresh-token rotation/revocation and device_links persistence (currently /device/token issues a JWT but never writes a row to the device_links table, so the "revoke a device" admin feature from TODO.md has nothing to revoke yet) — flagged here so it isn't forgotten; fold it into the gateway plan's auth-hardening pass, since revocation checks belong at the point every request is authenticated (the gateway), not duplicated in each service.