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              # binary entry: env, DB pool, serve
      lib.rs                # build_app(pool, &Config) -> Router (route wiring)
      config.rs             # env var loading + validation (DATABASE_URL, JWT_SECRET, S3_*, PORT)
      error.rs              # AppError enum -> IntoResponse
      auth/
        mod.rs               # re-exports
        password.rs          # hash_password, verify_password (argon2)
        jwt.rs                # typed access/refresh tokens, verify_token, bearer_account_id
        handlers.rs           # POST /auth/register, /auth/login (refresh/logout: gateway plan)
      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
        processing.rs         # decode, square-crop to 256x256, re-encode PNG (strips EXIF)
        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, set_avatar
    tests/
      common/mod.rs         # shared test_pool / test_config
      smoke.rs              # health + migrations
      auth_flow.rs
      device_flow.rs
      avatar_upload.rs

---

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
-- Hardening: revoke implicit PUBLIC access to this schema. This Postgres
-- instance hosts multiple services' databases (accounts_db/configs_db/
-- chat_db per TODO.md Фаза 10) on one cluster; the app role connects as
-- its own owner and needs no PUBLIC grant to function.
REVOKE ALL ON SCHEMA public FROM PUBLIC;

CREATE TABLE accounts (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    -- No plain UNIQUE on email: Postgres TEXT comparison is case-sensitive,
    -- so "User@x.com" and "user@x.com" would be treated as different rows
    -- (account-confusion / signup-limit-bypass). A unique index on
    -- lower(email) below enforces uniqueness case-insensitively —
    -- application code must look up/insert by `email.to_lowercase()`.
    email TEXT NOT NULL,
    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 UNIQUE INDEX accounts_email_lower_idx ON accounts (lower(email));

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 enum TokenType { Access, Refresh } and pub struct Claims { pub sub: String, pub exp: usize, pub token_type: TokenType }

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

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

• Produces: pub fn verify_token(token: &str, secret: &str, expected: TokenType) -> Option<Claims> — returns None on any invalid/expired/malformed token, wrong algorithm (HS256 pinned), or token type different from expected; never panics

• Step 1: Write the failing test

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

/// Distinguishes token purposes so a long-lived refresh/device token can
/// never be replayed as a short-lived access token (and vice versa).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TokenType {
    Access,
    Refresh,
}

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

fn issue(account_id: Uuid, secret: &str, token_type: TokenType, 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 };
    encode(&Header::new(Algorithm::HS256), &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, TokenType::Access, 15 * 60)
}

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

/// Returns the claims only if the signature, expiry AND token type all match.
/// HS256 is pinned explicitly (no algorithm confusion) and expiry leeway is 0.
pub fn verify_token(token: &str, secret: &str, expected: TokenType) -> Option<Claims> {
    let mut validation = Validation::new(Algorithm::HS256);
    validation.leeway = 0;
    validation.set_required_spec_claims(&["exp", "sub"]);
    let claims = decode::<Claims>(
        token,
        &DecodingKey::from_secret(secret.as_bytes()),
        &validation,
    )
    .ok()?
    .claims;
    (claims.token_type == expected).then_some(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", TokenType::Access).expect("should decode");
        assert_eq!(claims.sub, id.to_string());
        assert_eq!(claims.token_type, TokenType::Access);
    }

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

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

    #[test]
    fn refresh_token_is_rejected_where_access_is_expected() {
        let token = issue_refresh_token(Uuid::new_v4(), "test-secret");
        assert!(verify_token(&token, "test-secret", TokenType::Access).is_none());
        assert!(verify_token(&token, "test-secret", TokenType::Refresh).is_some());
    }

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

    #[test]
    fn expired_token_fails_verify() {
        let token = issue(Uuid::new_v4(), "test-secret", TokenType::Access, -10);
        assert!(verify_token(&token, "test-secret", TokenType::Access).is_none());
    }

    #[test]
    fn token_signed_with_other_algorithm_is_rejected() {
        let claims = Claims {
            sub: Uuid::new_v4().to_string(),
            exp: (chrono::Utc::now().timestamp() + 600) as usize,
            token_type: TokenType::Access,
        };
        let hs512 = encode(
            &Header::new(Algorithm::HS512),
            &claims,
            &EncodingKey::from_secret(b"test-secret"),
        )
        .unwrap();
        assert!(verify_token(&hs512, "test-secret", TokenType::Access).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: 7 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_lower_idx") (the case-insensitive unique index on lower(email) from Task 2's migration). create and find_by_email both normalize with email.trim().to_lowercase() before touching the DB, so the stored value is always lowercase and lookups always hit the index.

• 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;

// Emails are stored lowercase and compared via the `lower(email)` unique
// index (see migrations/0001_init.sql). Every entry point normalizes here.
pub fn normalize_email(email: &str) -> String {
    email.trim().to_lowercase()
}

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(normalize_email(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 lower(email) = $1",
    )
    .bind(normalize_email(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());
    }

    #[tokio::test]
    async fn email_lookup_is_case_insensitive_and_stored_lowercase() {
        let pool = test_pool().await;
        let tag = Uuid::new_v4();
        let mixed = format!("MiXeD-{tag}@Example.COM");

        let created = create(&pool, &mixed, "hash123", "Nick").await.unwrap();
        assert_eq!(created.email, mixed.to_lowercase());

        let found = find_by_email(&pool, &mixed.to_uppercase())
            .await
            .unwrap()
            .expect("lookup must ignore case");
        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 duplicate_email_differing_only_by_case_is_rejected() {
        let pool = test_pool().await;
        let tag = Uuid::new_v4();
        let first = create(&pool, &format!("dup-{tag}@example.com"), "h", "A").await.unwrap();

        let second = create(&pool, &format!("DUP-{tag}@EXAMPLE.com"), "h", "B").await;
        let err = second.expect_err("case-variant duplicate must violate the unique index");
        match err {
            sqlx::Error::Database(db) => {
                assert_eq!(db.constraint(), Some("accounts_email_lower_idx"));
            }
            other => panic!("expected a database unique violation, got {other:?}"),
        }

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

• 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: 4 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_lower_idx") {
                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();
}

#[tokio::test]
async fn login_with_unknown_email_returns_401() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into());
    let server = TestServer::new(app);

    let response = server
        .post("/auth/login")
        .json(&json!({ "email": format!("nobody-{}@example.com", Uuid::new_v4()), "password": "whatever-123" }))
        .await;
    response.assert_status(axum::http::StatusCode::UNAUTHORIZED);
}

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

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

    server
        .post("/auth/login")
        .json(&json!({ "email": registered.to_lowercase(), "password": "password123" }))
        .await
        .assert_status_ok();

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

#[tokio::test]
async fn register_rejects_oversized_password_with_400() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into());
    let server = TestServer::new(app);

    let response = server
        .post("/auth/register")
        .json(&json!({
            "email": format!("big-{}@example.com", Uuid::new_v4()),
            "password": "a".repeat(10_000),
            "nick": "Rider"
        }))
        .await;
    response.assert_status(axum::http::StatusCode::BAD_REQUEST);
}

• 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,
    // A real Argon2id hash of a throwaway string. `login` verifies against
    // it when the email is unknown so that "no such account" costs the same
    // ~100ms as "wrong password" — otherwise response time leaks which
    // emails are registered (user enumeration via timing).
    dummy_hash: String,
}

impl AuthState {
    pub fn new(pool: sqlx::PgPool, jwt_secret: String) -> Self {
        // Hashing a fixed, short constant with fixed valid params cannot
        // fail; this is not user input, so the expect is a startup invariant.
        let dummy_hash = password::hash_password("timing-equalizer-not-a-real-password")
            .expect("hashing a constant with pinned params cannot fail");
        AuthState { pool, jwt_secret, dummy_hash }
    }
}

#[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()));
    }
    if req.password.len() > password::MAX_PASSWORD_BYTES {
        return Err(AppError::Validation(format!(
            "password must be at most {} bytes",
            password::MAX_PASSWORD_BYTES
        )));
    }
    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 Some(account) = repo::find_by_email(&state.pool, &req.email).await? else {
        // Burn the same Argon2 cost as a real check, then fail identically.
        password::verify_password(&req.password, &state.dummy_hash);
        return Err(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)
• Modify: backend/accounts-service/src/error.rs (add NotFound(String) → 404 and TooManyRequests → 429 variants to AppError, same JSON body shape {"error": ...} as the others)
• 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 (requires an ACCESS token) body {user_code} → 200 {} or 404 if code unknown/expired (input is trimmed/upper-cased)

• Produces: POST /device/token body {device_code} → 200 {device_token} once confirmed (single use: the entry is consumed, a replay gets 404), 202 {} (still pending) before confirmation, 404 if unknown/expired; POST /device/code → 429 when 10 000 codes are pending

• Step 1: Write the device code store

// backend/accounts-service/src/device/store.rs
use dashmap::DashMap;
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>>,
}

#[derive(Debug, PartialEq, Eq)]
pub enum PollResult {
    Unknown,
    Pending,
    Confirmed(Uuid),
}

const TTL: Duration = Duration::from_secs(600);
// /device/code is unauthenticated, so the store must be bounded or anyone can
// grow process memory without limit. Expired entries are purged on every
// create, so the cap only bites under sustained abuse.
const MAX_PENDING: usize = 10_000;

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 {
    /// Returns `(device_code, user_code)`, or `None` when the store is full.
    pub fn create(&self) -> Option<(String, String)> {
        let now = Instant::now();
        self.by_device_code.retain(|_, entry| entry.expires_at > now);
        if self.by_device_code.len() >= MAX_PENDING {
            return None;
        }
        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: now + TTL,
            },
        );
        Some((device_code, user_code))
    }

    /// Returns true if a matching, unexpired entry was found and confirmed.
    /// The user types this code by hand, so it is trimmed and upper-cased.
    pub fn confirm(&self, user_code: &str, account_id: Uuid) -> bool {
        let wanted = user_code.trim().to_uppercase();
        let now = Instant::now();
        for mut entry in self.by_device_code.iter_mut() {
            if entry.user_code == wanted && entry.expires_at > now {
                entry.confirmed_account_id = Some(account_id);
                return true;
            }
        }
        false
    }

    /// A confirmed entry is CONSUMED by the first poll that sees it: the
    /// token can be collected exactly once, replaying the same device_code
    /// afterwards yields `Unknown`. Expired entries are dropped and Unknown.
    pub fn poll(&self, device_code: &str) -> PollResult {
        let now = Instant::now();
        let removed = self.by_device_code.remove_if(device_code, |_, entry| {
            entry.confirmed_account_id.is_some() || entry.expires_at <= now
        });
        if let Some((_, entry)) = removed {
            return match entry.confirmed_account_id {
                Some(id) if entry.expires_at > now => PollResult::Confirmed(id),
                _ => PollResult::Unknown,
            };
        }
        if self.by_device_code.contains_key(device_code) {
            PollResult::Pending
        } else {
            PollResult::Unknown
        }
    }
}

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

    #[test]
    fn create_returns_distinct_codes() {
        let store = DeviceStore::default();
        let (dc1, uc1) = store.create().unwrap();
        let (dc2, uc2) = store.create().unwrap();
        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().unwrap();
        let account_id = Uuid::new_v4();

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

    #[test]
    fn confirmed_code_can_only_be_collected_once() {
        let store = DeviceStore::default();
        let (device_code, user_code) = store.create().unwrap();
        assert!(store.confirm(&user_code, Uuid::new_v4()));

        assert!(matches!(store.poll(&device_code), PollResult::Confirmed(_)));
        assert_eq!(store.poll(&device_code), PollResult::Unknown, "replay must fail");
    }

    #[test]
    fn poll_before_confirm_is_pending_and_repeatable() {
        let store = DeviceStore::default();
        let (device_code, _user_code) = store.create().unwrap();
        assert_eq!(store.poll(&device_code), PollResult::Pending);
        assert_eq!(store.poll(&device_code), PollResult::Pending);
    }

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

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

    #[test]
    fn confirm_accepts_lowercase_and_surrounding_whitespace() {
        let store = DeviceStore::default();
        let (device_code, user_code) = store.create().unwrap();
        let typed = format!("  {}  ", user_code.to_lowercase());
        assert!(store.confirm(&typed, Uuid::new_v4()));
        assert!(matches!(store.poll(&device_code), PollResult::Confirmed(_)));
    }

    #[test]
    fn expired_entries_are_purged_and_store_is_bounded() {
        let store = DeviceStore::default();
        for _ in 0..MAX_PENDING {
            assert!(store.create().is_some());
        }
        assert!(store.create().is_none(), "store must refuse beyond MAX_PENDING");

        // Force everything to be expired; the next create purges and succeeds.
        for mut entry in store.by_device_code.iter_mut() {
            entry.expires_at = Instant::now() - Duration::from_secs(1);
        }
        assert!(store.create().is_some());
        assert_eq!(store.by_device_code.len(), 1);
    }
}

• Step 2: Run the store's unit tests

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

• Step 3: Write the handlers

// backend/accounts-service/src/device/handlers.rs
use crate::device::store::{DeviceStore, PollResult};
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>,
) -> Result<(StatusCode, Json<DeviceCodeResponse>), AppError> {
    let (device_code, user_code) = state.store.create().ok_or(AppError::TooManyRequests)?;
    Ok((
        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, crate::auth::jwt::TokenType::Access).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::NotFound("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) {
        PollResult::Unknown => Err(AppError::NotFound("unknown or expired device_code".into())),
        PollResult::Pending => Ok((StatusCode::ACCEPTED, Json(None))),
        PollResult::Confirmed(account_id) => {
            // The long-lived device_token is just a refresh-style JWT for now;
            // the 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());

    // Single use: the same device_code cannot be redeemed twice.
    server
        .post("/device/token")
        .json(&json!({ "device_code": device_code }))
        .await
        .assert_status(axum::http::StatusCode::NOT_FOUND);

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

#[tokio::test]
async fn refresh_token_cannot_confirm_a_device_code() {
    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-refresh-{}@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 refresh_token = login["refresh_token"].as_str().unwrap();

    let code: serde_json::Value = server.post("/device/code").await.json();
    server
        .post("/device/confirm")
        .add_header(
            axum::http::header::AUTHORIZATION,
            format!("Bearer {refresh_token}"),
        )
        .json(&json!({ "user_code": code["user_code"] }))
        .await
        .assert_status(axum::http::StatusCode::UNAUTHORIZED);

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

#[tokio::test]
async fn unknown_device_code_and_user_code_return_404() {
    let pool = test_pool().await;
    let app = accounts_service::build_app(pool.clone(), "test-secret".into());
    let server = TestServer::new(app);

    server
        .post("/device/token")
        .json(&json!({ "device_code": "no-such-code" }))
        .await
        .assert_status(axum::http::StatusCode::NOT_FOUND);
}

• 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::new(pool.clone(), 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: Shared bearer helper, shared test helpers, build_app(pool, &cfg), secret-strength check

Pure refactor plus one hardening; no new endpoints. It removes the duplicated account_id_from_auth_header (Task 7 has a copy, Task 9 would add a second) and the copy-pasted test_pool() in every test file, and prepares build_app to take the whole Config (Task 9 needs the S3 settings).

Files:

• Modify: backend/accounts-service/src/auth/jwt.rs (add bearer_account_id + tests)
• Modify: backend/accounts-service/src/device/handlers.rs (delete the local account_id_from_auth_header, call the shared one)
• Modify: backend/accounts-service/src/config.rs (add Config::validate + tests)
• Modify: backend/accounts-service/src/lib.rs (build_app(pool: PgPool, cfg: &Config) -> Router, still synchronous)
• Modify: backend/accounts-service/src/main.rs (cfg.validate()?, build_app(pool, &cfg))
• Create: backend/accounts-service/tests/common/mod.rs (test_pool, test_config)
• Create: backend/accounts-service/tests/smoke.rs containing BOTH the old health_returns_ok and migrations_create_accounts_table tests, then delete tests/health.rs and tests/db_migration.rs (keeps tests/ at 4 files once Task 9 adds avatar_upload.rs: smoke.rs, auth_flow.rs, device_flow.rs, avatar_upload.rs; the common/ subdirectory does not count)
• Modify: backend/accounts-service/tests/{auth_flow,device_flow}.rs (use mod common;)

Interfaces:

• Produces: pub fn bearer_account_id(headers: &axum::http::HeaderMap, secret: &str) -> Result<Uuid, AppError> in auth::jwt — requires Authorization: Bearer <ACCESS token>, every failure is AppError::Unauthorized

• Produces: impl Config { pub fn validate(&self) -> anyhow::Result<()> } — rejects a jwt_secret shorter than 32 bytes

• Produces: pub fn build_app(pool: PgPool, cfg: &Config) -> Router

• Produces (tests only): common::test_pool() -> PgPool (connects to DATABASE_URL or the local default and runs ./migrations), common::test_config() -> Config (32+ byte secret "test-secret-test-secret-test-secret!", S3 fields pointing at http://localhost:9000, bucket lovisual-avatars-test, keys minioadmin)

• Step 1: Write the failing tests for bearer_account_id

Append to the tests module of src/auth/jwt.rs:

    use axum::http::{header::AUTHORIZATION, HeaderMap, HeaderValue};

    fn headers_with(value: &str) -> HeaderMap {
        let mut headers = HeaderMap::new();
        headers.insert(AUTHORIZATION, HeaderValue::from_str(value).unwrap());
        headers
    }

    #[test]
    fn bearer_accepts_a_valid_access_token() {
        let id = Uuid::new_v4();
        let token = issue_access_token(id, "test-secret");
        let got = bearer_account_id(&headers_with(&format!("Bearer {token}")), "test-secret");
        assert_eq!(got.unwrap(), id);
    }

    #[test]
    fn bearer_rejects_missing_header_wrong_scheme_and_garbage() {
        let token = issue_access_token(Uuid::new_v4(), "test-secret");
        for headers in [
            HeaderMap::new(),
            headers_with(&format!("Basic {token}")),
            headers_with(&token),
            headers_with("Bearer not.a.jwt"),
        ] {
            assert!(matches!(
                bearer_account_id(&headers, "test-secret"),
                Err(AppError::Unauthorized)
            ));
        }
    }

    #[test]
    fn bearer_rejects_a_refresh_token() {
        let token = issue_refresh_token(Uuid::new_v4(), "test-secret");
        assert!(matches!(
            bearer_account_id(&headers_with(&format!("Bearer {token}")), "test-secret"),
            Err(AppError::Unauthorized)
        ));
    }

• Step 2: Run to see them fail

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && CARGO_BUILD_JOBS=4 cargo test --lib jwt:: Expected: compile error, bearer_account_id not found

• Step 3: Implement it in jwt.rs

Add above the #[cfg(test)] module:

use crate::error::AppError;
use axum::http::{header::AUTHORIZATION, HeaderMap};

/// Account id from `Authorization: Bearer <access token>`. Every failure mode
/// (missing header, wrong scheme, bad/expired token, refresh token, non-UUID
/// subject) is the same `AppError::Unauthorized`.
pub fn bearer_account_id(headers: &HeaderMap, secret: &str) -> Result<Uuid, AppError> {
    let value = headers
        .get(AUTHORIZATION)
        .and_then(|v| v.to_str().ok())
        .ok_or(AppError::Unauthorized)?;
    let token = value.strip_prefix("Bearer ").ok_or(AppError::Unauthorized)?;
    let claims = verify_token(token, secret, TokenType::Access).ok_or(AppError::Unauthorized)?;
    claims.sub.parse().map_err(|_| AppError::Unauthorized)
}

(Move the two new use lines up next to the existing imports at the top of the file.)

• Step 4: Use it in device/handlers.rs

Delete the whole local fn account_id_from_auth_header(...) and change its one call site in confirm to:

    let account_id = crate::auth::jwt::bearer_account_id(&headers, &state.jwt_secret)?;

• Step 5: Add Config::validate with tests

Add to src/config.rs:

const MIN_JWT_SECRET_BYTES: usize = 32;

impl Config {
    /// Fail fast at startup on a secret too weak to sign HS256 tokens with
    /// (the `.env.example` placeholder must never reach production).
    pub fn validate(&self) -> Result<()> {
        if self.jwt_secret.len() < MIN_JWT_SECRET_BYTES {
            anyhow::bail!("JWT_SECRET must be at least {MIN_JWT_SECRET_BYTES} bytes");
        }
        Ok(())
    }
}

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

    fn config_with_secret(secret: &str) -> Config {
        Config {
            database_url: String::new(),
            jwt_secret: secret.into(),
            port: 0,
            s3_endpoint: String::new(),
            s3_bucket: String::new(),
            s3_access_key: String::new(),
            s3_secret_key: String::new(),
        }
    }

    #[test]
    fn short_jwt_secret_is_rejected() {
        assert!(config_with_secret("too-short").validate().is_err());
    }

    #[test]
    fn strong_jwt_secret_is_accepted() {
        assert!(config_with_secret(&"x".repeat(32)).validate().is_ok());
    }
}

Also update backend/.env.example: replace JWT_SECRET=change-me-to-a-long-random-string with JWT_SECRET= plus a comment line above it: # at least 32 random bytes, e.g. \openssl rand -hex 32``.

• Step 6: Shared test helpers

// backend/accounts-service/tests/common/mod.rs
#![allow(dead_code)] // each test binary uses a different subset

use accounts_service::config::Config;

pub 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 to test database");
    sqlx::migrate!("./migrations").run(&pool).await.expect("run migrations");
    pool
}

pub fn test_config() -> Config {
    Config {
        database_url: String::new(),
        jwt_secret: "test-secret-test-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(),
    }
}

• Step 7: build_app(pool, &cfg) and call sites

In src/lib.rs change the signature and the two places that used jwt_secret:

use config::Config;

pub fn build_app(pool: sqlx::PgPool, cfg: &Config) -> Router {
    let auth_state = AuthState::new(pool.clone(), cfg.jwt_secret.clone());
    let device_state = DeviceState { store: DeviceStore::default(), jwt_secret: cfg.jwt_secret.clone() };
    // ... routes unchanged ...
}

src/main.rs: after Config::from_env()? add cfg.validate()?; and call build_app(pool, &cfg).

Create tests/smoke.rs with mod common; holding the two existing tests unchanged in behavior (health still builds the app on a lazy pool via PgPool::connect_lazy; the migration test now uses common::test_pool()), then git rm tests/health.rs tests/db_migration.rs. In auth_flow.rs and device_flow.rs: add mod common; at the top, delete the local test_pool fn, replace calls with common::test_pool().await, and replace every accounts_service::build_app(pool.clone(), "test-secret".into()) with accounts_service::build_app(pool.clone(), &common::test_config()).

• Step 8: Run everything

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db CARGO_BUILD_JOBS=4 cargo test Expected: all previous tests still pass plus the 3 bearer_* and 2 config::tests (no test file defines its own test_pool any more: grep -rn "fn test_pool" tests/ prints only tests/common/mod.rs)

• Step 9: Commit

cd /storage/project/jvm/LoVisual
git add -A backend/accounts-service backend/.env.example   # -A here is scoped to these paths only (records the two deleted test files)
git commit -m "refactor(backend): shared bearer helper and test helpers, build_app takes Config, validate JWT secret strength"

---

Task 9: Avatar upload (POST /avatars)

Uploads are decoded, center-cropped to 256x256 and re-encoded as PNG — never stored as sent. Magic bytes alone do not prove an image is valid, and re-encoding also drops EXIF (GPS location, camera serial) and any embedded payload. Decoding untrusted input is bounded (max 8192px per side, 128 MiB decode allocation) and runs on a blocking thread.

Files:

• Modify: backend/accounts-service/Cargo.toml (add image = { version = "0.25", default-features = false, features = ["png", "jpeg", "webp"] })
• Create: backend/accounts-service/src/avatars/mod.rs
• Create: backend/accounts-service/src/avatars/processing.rs (pure image logic + unit tests)
• Create: backend/accounts-service/src/avatars/storage.rs (S3 wrapper)
• Create: backend/accounts-service/src/avatars/handlers.rs
• Modify: backend/accounts-service/src/accounts/repo.rs (add set_avatar + test)
• Modify: backend/accounts-service/src/config.rs (add Config::avatar_base_url + test)
• Modify: backend/accounts-service/src/lib.rs (pub mod avatars;, mount /avatars)
• Test: backend/accounts-service/tests/avatar_upload.rs

(avatars/ holds 4 files — at the limit; processing.rs is deliberately not called image.rs so it cannot be confused with the image crate.)

Interfaces:

• Consumes: auth::jwt::bearer_account_id (Task 8), common::{test_pool, test_config} (Task 8), Config S3 fields

• Produces: pub fn process_avatar(bytes: &[u8]) -> Result<Vec<u8>, AvatarImageError> (AvatarImageError::{Unsupported, Invalid}, output is always a 256x256 PNG)

• Produces: pub struct S3Storage with pub fn from_config(endpoint, access_key, secret_key, bucket) -> Self (synchronous — building the client does no I/O) and pub async fn put(&self, key: &str, bytes: Vec<u8>, content_type: &str) -> anyhow::Result<()>

• Produces: pub async fn accounts::repo::set_avatar(pool: &PgPool, account_id: Uuid, s3_key: &str) -> Result<(), sqlx::Error> (upsert into avatars, bumps uploaded_at)

• Produces: Config::avatar_base_url(&self) -> String = "{endpoint without trailing slash}/{bucket}"

• Produces: POST /avatars (multipart, single part named file, ACCESS token required) → 200 {"avatar_url": "<base>/avatars/<account_id>.png"}; unsupported/invalid image or >5 MB → 400; no/invalid/refresh token → 401

• Test prerequisite (infra, one-time, not automated): an S3-compatible endpoint at S3_ENDPOINT with bucket lovisual-avatars-test (e.g. MinIO with root user/password minioadmin)

• Step 1: Write the failing unit tests for the image processing

// backend/accounts-service/src/avatars/processing.rs  (tests first; implementation in Step 2)
#[cfg(test)]
mod tests {
    use super::*;
    use image::ImageFormat;
    use std::io::Cursor;

    fn png_of(width: u32, height: u32) -> Vec<u8> {
        let img = image::RgbaImage::new(width, height);
        let mut out = Cursor::new(Vec::new());
        img.write_to(&mut out, ImageFormat::Png).unwrap();
        out.into_inner()
    }

    #[test]
    fn valid_image_becomes_a_256_square_png() {
        let out = process_avatar(&png_of(300, 100)).unwrap();
        assert!(out.starts_with(&[0x89, b'P', b'N', b'G']));
        let decoded = image::load_from_memory(&out).unwrap();
        assert_eq!((decoded.width(), decoded.height()), (AVATAR_SIZE, AVATAR_SIZE));
    }

    #[test]
    fn non_image_bytes_are_unsupported() {
        assert_eq!(process_avatar(b"not an image"), Err(AvatarImageError::Unsupported));
    }

    #[test]
    fn gif_is_unsupported() {
        assert_eq!(
            process_avatar(b"GIF89a\x01\x00\x01\x00\x00\x00\x00;"),
            Err(AvatarImageError::Unsupported)
        );
    }

    #[test]
    fn truncated_png_is_invalid() {
        let mut bytes = png_of(50, 50);
        bytes.truncate(40);
        assert_eq!(process_avatar(&bytes), Err(AvatarImageError::Invalid));
    }

    #[test]
    fn image_wider_than_the_limit_is_rejected() {
        assert_eq!(process_avatar(&png_of(MAX_DIMENSION + 1, 1)), Err(AvatarImageError::Invalid));
    }
}

Run: CARGO_BUILD_JOBS=4 cargo test --lib avatars::processing:: — Expected: compile error (module/functions missing).

• Step 2: Implement processing.rs

Put above the tests module:

use image::{imageops::FilterType, ImageFormat, ImageReader, Limits};
use std::io::Cursor;

pub const AVATAR_SIZE: u32 = 256;
pub const MAX_DIMENSION: u32 = 8192;
const MAX_DECODE_BYTES: u64 = 128 * 1024 * 1024;

#[derive(Debug, PartialEq, Eq)]
pub enum AvatarImageError {
    /// Not a PNG/JPEG/WebP at all.
    Unsupported,
    /// Claims to be one of those but does not decode within the limits.
    Invalid,
}

pub fn process_avatar(bytes: &[u8]) -> Result<Vec<u8>, AvatarImageError> {
    let mut reader = ImageReader::new(Cursor::new(bytes))
        .with_guessed_format()
        .map_err(|_| AvatarImageError::Invalid)?;
    if !matches!(
        reader.format(),
        Some(ImageFormat::Png | ImageFormat::Jpeg | ImageFormat::WebP)
    ) {
        return Err(AvatarImageError::Unsupported);
    }
    let mut limits = Limits::default();
    limits.max_image_width = Some(MAX_DIMENSION);
    limits.max_image_height = Some(MAX_DIMENSION);
    limits.max_alloc = Some(MAX_DECODE_BYTES);
    reader.limits(limits);

    let decoded = reader.decode().map_err(|_| AvatarImageError::Invalid)?;
    let square = decoded.resize_to_fill(AVATAR_SIZE, AVATAR_SIZE, FilterType::Lanczos3);
    let mut out = Cursor::new(Vec::new());
    square
        .write_to(&mut out, ImageFormat::Png)
        .map_err(|_| AvatarImageError::Invalid)?;
    Ok(out.into_inner())
}

Run the same test command — Expected: 5 tests pass.

• Step 3: Repository set_avatar (test first)

Add to the tests module of src/accounts/repo.rs:

    #[tokio::test]
    async fn set_avatar_inserts_then_updates_in_place() {
        let pool = test_pool().await;
        let created = create(&pool, &format!("av-{}@example.com", Uuid::new_v4()), "h", "N")
            .await
            .unwrap();

        set_avatar(&pool, created.id, "avatars/one.png").await.unwrap();
        set_avatar(&pool, created.id, "avatars/two.png").await.unwrap();

        let rows: Vec<(String,)> =
            sqlx::query_as("SELECT s3_key FROM avatars WHERE account_id = $1")
                .bind(created.id)
                .fetch_all(&pool)
                .await
                .unwrap();
        assert_eq!(rows, vec![("avatars/two.png".to_string(),)]);

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

Implement (above the tests module):

pub async fn set_avatar(pool: &PgPool, account_id: Uuid, s3_key: &str) -> Result<(), sqlx::Error> {
    sqlx::query(
        "INSERT INTO avatars (account_id, s3_key) VALUES ($1, $2)
         ON CONFLICT (account_id) DO UPDATE SET s3_key = EXCLUDED.s3_key, uploaded_at = now()",
    )
    .bind(account_id)
    .bind(s3_key)
    .execute(pool)
    .await?;
    Ok(())
}

Run: DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db CARGO_BUILD_JOBS=4 cargo test --lib accounts::repo:: — Expected: 5 tests pass.

• Step 4: Config::avatar_base_url (test first)

Add to config.rs (and its tests module):

impl Config {
    /// Public prefix of stored avatars: `<endpoint>/<bucket>`.
    pub fn avatar_base_url(&self) -> String {
        format!("{}/{}", self.s3_endpoint.trim_end_matches('/'), self.s3_bucket)
    }
}

    #[test]
    fn avatar_base_url_joins_endpoint_and_bucket_without_double_slash() {
        let mut cfg = config_with_secret(&"x".repeat(32));
        cfg.s3_endpoint = "http://localhost:9000/".into();
        cfg.s3_bucket = "avatars".into();
        assert_eq!(cfg.avatar_base_url(), "http://localhost:9000/avatars");
    }

• Step 5: 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 {
    client: Client,
    bucket: String,
}

impl S3Storage {
    pub 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 6: Handler

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

pub const MAX_UPLOAD_BYTES: usize = 5 * 1024 * 1024;

#[derive(Clone)]
pub struct AvatarState {
    pub pool: sqlx::PgPool,
    pub storage: S3Storage,
    pub jwt_secret: String,
    pub base_url: String,
}

#[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 = bearer_account_id(&headers, &state.jwt_secret)?;

    let field = multipart
        .next_field()
        .await
        .map_err(|_| AppError::Validation("malformed multipart body".into()))?
        .filter(|f| f.name() == Some("file"))
        .ok_or_else(|| AppError::Validation("expected a multipart part named `file`".into()))?;
    let bytes = field
        .bytes()
        .await
        .map_err(|_| AppError::Validation("could not read the uploaded file".into()))?;
    if bytes.len() > MAX_UPLOAD_BYTES {
        return Err(AppError::Validation("file too large (max 5MB)".into()));
    }

    // Decoding is CPU-bound and the input is untrusted: keep it off the async workers.
    let png = tokio::task::spawn_blocking(move || process_avatar(&bytes))
        .await
        .map_err(|e| AppError::Internal(e.into()))?
        .map_err(|e| match e {
            AvatarImageError::Unsupported => AppError::Validation("unsupported image format (png, jpeg, webp)".into()),
            AvatarImageError::Invalid => AppError::Validation("invalid or too large image".into()),
        })?;

    let key = format!("avatars/{account_id}.png");
    state.storage.put(&key, png, "image/png").await.map_err(AppError::Internal)?;
    repo::set_avatar(&state.pool, account_id, &key).await?;

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

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

• Step 7: Mount the route in lib.rs

pub mod avatars;

use avatars::{handlers::AvatarState, storage::S3Storage};
use axum::extract::DefaultBodyLimit;

// inside build_app, next to the other route groups:
    let avatar_state = AvatarState {
        pool: pool.clone(),
        storage: S3Storage::from_config(
            &cfg.s3_endpoint,
            &cfg.s3_access_key,
            &cfg.s3_secret_key,
            cfg.s3_bucket.clone(),
        ),
        jwt_secret: cfg.jwt_secret.clone(),
        base_url: cfg.avatar_base_url(),
    };
    let avatar_routes = Router::new()
        .route("/avatars", post(avatars::handlers::upload))
        // Hard transport cap slightly above the 5 MB business limit (413 beyond it).
        .layer(DefaultBodyLimit::max(6 * 1024 * 1024))
        .with_state(avatar_state);
// ... and `.merge(avatar_routes)` on the final Router.

• Step 8: Integration tests

// backend/accounts-service/tests/avatar_upload.rs
mod common;

use axum::http::{header::AUTHORIZATION, StatusCode};
use axum_test::{multipart::{MultipartForm, Part}, TestServer};
use serde_json::json;
use uuid::Uuid;

fn png_bytes() -> Vec<u8> {
    let img = image::RgbaImage::new(64, 32);
    let mut out = std::io::Cursor::new(Vec::new());
    img.write_to(&mut out, image::ImageFormat::Png).unwrap();
    out.into_inner()
}

fn form(bytes: Vec<u8>) -> MultipartForm {
    MultipartForm::new().add_part("file", Part::bytes(bytes).file_name("a.png").mime_type("image/png"))
}

async fn registered_login(server: &TestServer, tag: &str) -> (String, serde_json::Value) {
    let email = format!("{tag}-{}@example.com", Uuid::new_v4());
    server
        .post("/auth/register")
        .json(&json!({ "email": email, "password": "password123", "nick": "Rider" }))
        .await
        .assert_status(StatusCode::CREATED);
    let login: serde_json::Value = server
        .post("/auth/login")
        .json(&json!({ "email": email, "password": "password123" }))
        .await
        .json();
    (email, login)
}

#[tokio::test]
async fn valid_upload_stores_avatar_and_returns_url() {
    let pool = common::test_pool().await;
    let server = TestServer::new(accounts_service::build_app(pool.clone(), &common::test_config()));
    let (email, login) = registered_login(&server, "avatar").await;
    let access = login["access_token"].as_str().unwrap();

    let response = server
        .post("/avatars")
        .add_header(AUTHORIZATION, format!("Bearer {access}"))
        .multipart(form(png_bytes()))
        .await;
    response.assert_status_ok();
    let url = response.json::<serde_json::Value>()["avatar_url"].as_str().unwrap().to_string();
    assert!(url.starts_with("http://localhost:9000/lovisual-avatars-test/avatars/"), "{url}");
    assert!(url.ends_with(".png"), "{url}");

    let stored: (String,) = sqlx::query_as(
        "SELECT a.s3_key FROM avatars a JOIN accounts c ON c.id = a.account_id WHERE lower(c.email) = $1",
    )
    .bind(email.to_lowercase())
    .fetch_one(&pool)
    .await
    .expect("avatars row must exist");
    assert!(url.ends_with(&stored.0));

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

#[tokio::test]
async fn non_image_upload_is_rejected_with_400() {
    let pool = common::test_pool().await;
    let server = TestServer::new(accounts_service::build_app(pool.clone(), &common::test_config()));
    let (email, login) = registered_login(&server, "badavatar").await;
    let access = login["access_token"].as_str().unwrap();

    server
        .post("/avatars")
        .add_header(AUTHORIZATION, format!("Bearer {access}"))
        .multipart(form(b"definitely not an image".to_vec()))
        .await
        .assert_status(StatusCode::BAD_REQUEST);

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

#[tokio::test]
async fn oversized_upload_is_rejected_with_400() {
    let pool = common::test_pool().await;
    let server = TestServer::new(accounts_service::build_app(pool.clone(), &common::test_config()));
    let (email, login) = registered_login(&server, "bigavatar").await;
    let access = login["access_token"].as_str().unwrap();

    server
        .post("/avatars")
        .add_header(AUTHORIZATION, format!("Bearer {access}"))
        .multipart(form(vec![0u8; 5 * 1024 * 1024 + 1]))
        .await
        .assert_status(StatusCode::BAD_REQUEST);

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

#[tokio::test]
async fn upload_requires_an_access_token() {
    let pool = common::test_pool().await;
    let server = TestServer::new(accounts_service::build_app(pool.clone(), &common::test_config()));

    server
        .post("/avatars")
        .multipart(form(png_bytes()))
        .await
        .assert_status(StatusCode::UNAUTHORIZED);

    let (email, login) = registered_login(&server, "refreshavatar").await;
    let refresh = login["refresh_token"].as_str().unwrap();
    server
        .post("/avatars")
        .add_header(AUTHORIZATION, format!("Bearer {refresh}"))
        .multipart(form(png_bytes()))
        .await
        .assert_status(StatusCode::UNAUTHORIZED);

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

• Step 9: Run everything

Run: cd /storage/project/jvm/LoVisual/backend/accounts-service && DATABASE_URL=postgres://lovisual:lovisual@localhost:5432/accounts_db CARGO_BUILD_JOBS=4 cargo test Expected: everything passes, including the 4 avatar_upload tests against the S3 endpoint (if the endpoint is unreachable the first test fails with a 500 — report BLOCKED with the error instead of weakening the test)

• Step 10: Commit

cd /storage/project/jvm/LoVisual
git add backend/accounts-service backend/Cargo.lock
git commit -m "feat(backend): avatar upload with decode, square crop, PNG re-encode 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.