feat: multipart manga + chapter uploads with magic-byte MIME sniff

POST /api/v1/mangas and POST /api/v1/mangas/{id}/chapters now accept
multipart/form-data, gated by CurrentUser:

- /mangas: required `metadata` part (NewManga JSON) + optional `cover`
  image part.
- /mangas/{id}/chapters: required `metadata` (NewChapter JSON) + one or
  more `page` parts ordered by arrival. Returns 404 if the parent manga
  doesn't exist, 409 on duplicate (manga_id, number).

MIME is sniffed via the `infer` crate (magic bytes), not the
client-supplied filename or Content-Type. Whitelist:
jpeg / png / webp / gif / avif. Anything else → 415
unsupported_media_type. The stored key's extension is derived from the
sniffed type so a "page1.png" that's actually a JPEG lands as `.jpg`.

Size cap is two-layer:
- Request body cap (config.max_request_bytes, default 200 MiB) enforced
  by axum's DefaultBodyLimit before the handler sees the request.
- Per-image-part cap (config.max_file_bytes, default 20 MiB) enforced
  after reading the part, so a single oversized image can't pass even
  if the total request fits.

Storage keys follow the layout documented in CLAUDE.md:
- mangas/{manga_id}/cover.{ext}
- mangas/{manga_id}/chapters/{chapter_id}/pages/{nnnn}.{ext} (1-indexed).

AppError grows PayloadTooLarge/UnsupportedMediaType/ValidationFailed
(413 / 415 / 422). ValidationFailed carries a `details` JSON object the
client can use to highlight bad fields (e.g. {"title":"required"}).
Top-level matching in code() stays exhaustive.

Backend coverage in tests/api_uploads.rs (10 cases):
- create_manga_with_cover_stores_image — file is reachable via
  /api/v1/files/{key} with the right Content-Type.
- create_manga_without_cover_leaves_path_null.
- create_manga_rejects_non_image_cover_with_415 — PDF claimed as png.
- create_manga_rejects_oversized_cover_with_413.
- create_chapter_with_pages_stores_each — extension derived from
  sniffed MIME, files reachable in arrival order.
- create_chapter_rejects_when_no_pages_with_422 — details.page set.
- create_chapter_rejects_renamed_non_image_page → 415.
- create_chapter_returns_409_on_duplicate_number.
- create_chapter_requires_authentication → 401.
- create_chapter_under_unknown_manga_is_404.

Existing tests/api_mangas.rs is migrated to multipart; the create
response is now 201 Created. tests/common::MultipartBuilder builds the
body by hand so the test crate stays free of HTTP-client deps.

Frontend lib/api/mangas.ts: createManga now sends FormData (metadata +
optional cover Blob). Browser fills in the boundary header automatically.
Vitest asserts the FormData structure via FileReader (jsdom doesn't
implement Blob.text()).

E2E tests wait for the post-hydration nav-login link before
interacting with the login form, fixing a flake where pre-hydration
clicks would submit via the browser default and bypass our handler.

Lockstep version bump to 0.5.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/Cargo.lock

@@ -96,6 +96,7 @@ dependencies = [
  "matchit",
  "memchr",
  "mime",
+ "multer",
  "percent-encoding",
  "pin-project-lite",
  "rustversion",
@@ -235,6 +236,17 @@ dependencies = [
  "shlex",
 ]
 
+[[package]]
+name = "cfb"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d38f2da7a0a2c4ccf0065be06397cc26a81f4e528be095826eee9d4adbb8c60f"
+dependencies = [
+ "byteorder",
+ "fnv",
+ "uuid",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
@@ -464,6 +476,12 @@ dependencies = [
  "spin",
 ]
 
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
 [[package]]
 name = "foldhash"
 version = "0.1.5"
@@ -898,6 +916,15 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "infer"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc150e5ce2330295b8616ce0e3f53250e53af31759a9dbedad1621ba29151847"
+dependencies = [
+ "cfb",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -994,7 +1021,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "mangalord"
-version = "0.4.0"
+version = "0.5.0"
 dependencies = [
  "anyhow",
  "argon2",
@@ -1005,6 +1032,7 @@ dependencies = [
  "chrono",
  "dotenvy",
  "http-body-util",
+ "infer",
  "mime",
  "rand",
  "serde",

backend/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mangalord"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 
 [lib]
@@ -11,7 +11,7 @@ name = "mangalord"
 path = "src/main.rs"
 
 [dependencies]
-axum = { version = "0.7", features = ["macros"] }
+axum = { version = "0.7", features = ["macros", "multipart"] }
 tokio = { version = "1", features = ["full"] }
 sqlx = { version = "0.8", features = ["runtime-tokio", "postgres", "uuid", "chrono", "macros", "migrate"] }
 serde = { version = "1", features = ["derive"] }
@@ -33,6 +33,7 @@ subtle = "2"
 base64 = "0.22"
 axum-extra = { version = "0.9", features = ["cookie", "typed-header"] }
 time = "0.3"
+infer = "0.16"
 
 [dev-dependencies]
 tempfile = "3"

backend/src/api/chapters.rs

@@ -1,22 +1,34 @@
-//! Chapter list + get. Reads are public — anyone can browse a manga's
+//! Chapter list + get + multipart upload.
-//! table of contents and individual chapter metadata. Uploads land in
+//!
-//! feat/uploads under POST /api/v1/mangas/{id}/chapters.
+//! Reads are public. Uploads (POST) require auth and use the same
+//! multipart conventions as `POST /api/v1/mangas`:
+//! - `metadata` part (JSON) with `{ number, title? }`.
+//! - One or more `page` parts (images, ordered by arrival).
 
-use axum::extract::{Path, Query, State};
+use axum::extract::{Multipart, Path, Query, State};
+use axum::http::StatusCode;
 use axum::routing::get;
 use axum::{Json, Router};
 use serde::Deserialize;
+use serde_json::json;
 use uuid::Uuid;
 
+use crate::api::mangas::{next_field, read_field_bytes};
 use crate::api::pagination::PagedResponse;
 use crate::app::AppState;
+use crate::auth::extractor::CurrentUser;
 use crate::domain::Chapter;
-use crate::error::AppResult;
+use crate::domain::chapter::NewChapter;
+use crate::error::{AppError, AppResult};
 use crate::repo;
+use crate::upload::{parse_image, UploadedImage};
 
 pub fn routes() -> Router<AppState> {
     Router::new()
-        .route("/mangas/:manga_id/chapters", get(list))
+        .route(
+            "/mangas/:manga_id/chapters",
+            get(list).post(create),
+        )
         .route("/mangas/:manga_id/chapters/:number", get(get_one))
 }
 
@@ -37,8 +49,6 @@ async fn list(
     Path(manga_id): Path<Uuid>,
     Query(params): Query<ListParams>,
 ) -> AppResult<Json<PagedResponse<Chapter>>> {
-    // Surface 404 when the parent manga doesn't exist so an empty result
-    // can't be mistaken for "no chapters yet" on a real manga.
     repo::manga::get(&state.db, manga_id).await?;
 
     let limit = params.limit.clamp(1, 200);
@@ -54,6 +64,77 @@ async fn get_one(
     repo::manga::get(&state.db, manga_id).await?;
     let chapter = repo::chapter::find_by_manga_and_number(&state.db, manga_id, number)
         .await?
-        .ok_or(crate::error::AppError::NotFound)?;
+        .ok_or(AppError::NotFound)?;
     Ok(Json(chapter))
 }
+
+async fn create(
+    State(state): State<AppState>,
+    CurrentUser(_user): CurrentUser,
+    Path(manga_id): Path<Uuid>,
+    mut multipart: Multipart,
+) -> AppResult<(StatusCode, Json<Chapter>)> {
+    repo::manga::get(&state.db, manga_id).await?;
+
+    let mut metadata: Option<NewChapter> = None;
+    let mut pages: Vec<UploadedImage> = Vec::new();
+
+    while let Some(field) = next_field(&mut multipart).await? {
+        match field.name() {
+            Some("metadata") => {
+                let bytes = read_field_bytes(field).await?;
+                metadata =
+                    Some(serde_json::from_slice(&bytes).map_err(|e| {
+                        AppError::ValidationFailed {
+                            message: "metadata is not valid JSON".into(),
+                            details: json!({ "metadata": e.to_string() }),
+                        }
+                    })?);
+            }
+            Some("page") => {
+                let bytes = read_field_bytes(field).await?.to_vec();
+                let field_name = format!("page[{}]", pages.len());
+                pages.push(parse_image(bytes, state.upload.max_file_bytes, &field_name)?);
+            }
+            _ => continue,
+        }
+    }
+
+    let metadata = metadata.ok_or_else(|| AppError::ValidationFailed {
+        message: "metadata part is required".into(),
+        details: json!({ "metadata": "required" }),
+    })?;
+    if pages.is_empty() {
+        return Err(AppError::ValidationFailed {
+            message: "at least one page is required".into(),
+            details: json!({ "page": "at least one required" }),
+        });
+    }
+
+    let mut chapter = repo::chapter::create(
+        &state.db,
+        manga_id,
+        metadata.number,
+        metadata.title.as_deref(),
+    )
+    .await?;
+
+    for (idx, page) in pages.iter().enumerate() {
+        let nnnn = format!("{:04}", idx + 1);
+        let key = format!(
+            "mangas/{}/chapters/{}/pages/{}.{}",
+            manga_id, chapter.id, nnnn, page.ext
+        );
+        state.storage.put(&key, &page.bytes).await?;
+    }
+
+    let page_count = pages.len() as i32;
+    sqlx::query("UPDATE chapters SET page_count = $1 WHERE id = $2")
+        .bind(page_count)
+        .bind(chapter.id)
+        .execute(&state.db)
+        .await?;
+    chapter.page_count = page_count;
+
+    Ok((StatusCode::CREATED, Json(chapter)))
+}

backend/src/api/mangas.rs

@@ -1,7 +1,9 @@
-use axum::extract::{Path, Query, State};
+use axum::extract::{Multipart, Path, Query, State};
+use axum::http::StatusCode;
 use axum::routing::get;
 use axum::{Json, Router};
 use serde::Deserialize;
+use serde_json::json;
 use uuid::Uuid;
 
 use crate::api::pagination::PagedResponse;
@@ -10,6 +12,7 @@ use crate::auth::extractor::CurrentUser;
 use crate::domain::manga::{Manga, NewManga};
 use crate::error::{AppError, AppResult};
 use crate::repo;
+use crate::upload::{parse_image, UploadedImage};
 
 pub fn routes() -> Router<AppState> {
     Router::new()
@@ -53,13 +56,94 @@ async fn get_one(
     Ok(Json(repo::manga::get(&state.db, id).await?))
 }
 
+/// `POST /api/v1/mangas` is multipart/form-data. Parts:
+///
+/// - `metadata` (required): JSON body matching `NewManga`.
+/// - `cover` (optional): image bytes. MIME is sniffed from magic bytes
+///   (jpeg/png/webp/gif/avif); size capped at `upload.max_file_bytes`.
+///
+/// Anything else is ignored.
 async fn create(
     State(state): State<AppState>,
     CurrentUser(_user): CurrentUser,
-    Json(input): Json<NewManga>,
+    mut multipart: Multipart,
-) -> AppResult<Json<Manga>> {
+) -> AppResult<(StatusCode, Json<Manga>)> {
-    if input.title.trim().is_empty() {
+    let mut metadata: Option<NewManga> = None;
-        return Err(AppError::InvalidInput("title is required".into()));
+    let mut cover: Option<UploadedImage> = None;
+
+    while let Some(field) = next_field(&mut multipart).await? {
+        match field.name() {
+            Some("metadata") => {
+                let bytes = read_field_bytes(field).await?;
+                metadata = Some(parse_metadata_json(&bytes)?);
+            }
+            Some("cover") => {
+                let bytes = read_field_bytes(field).await?.to_vec();
+                cover = Some(parse_image(bytes, state.upload.max_file_bytes, "cover")?);
+            }
+            _ => continue,
+        }
+    }
+
+    let metadata = metadata.ok_or_else(|| AppError::ValidationFailed {
+        message: "metadata part is required".into(),
+        details: json!({ "metadata": "required" }),
+    })?;
+    validate_new_manga(&metadata)?;
+
+    let mut manga = repo::manga::create(&state.db, metadata).await?;
+
+    if let Some(img) = cover {
+        let key = format!("mangas/{}/cover.{}", manga.id, img.ext);
+        state.storage.put(&key, &img.bytes).await?;
+        sqlx::query("UPDATE mangas SET cover_image_path = $1, updated_at = now() WHERE id = $2")
+            .bind(&key)
+            .bind(manga.id)
+            .execute(&state.db)
+            .await?;
+        manga.cover_image_path = Some(key);
+    }
+
+    Ok((StatusCode::CREATED, Json(manga)))
+}
+
+fn validate_new_manga(input: &NewManga) -> AppResult<()> {
+    if input.title.trim().is_empty() {
+        return Err(AppError::ValidationFailed {
+            message: "title is required".into(),
+            details: json!({ "title": "required" }),
+        });
+    }
+    Ok(())
+}
+
+fn parse_metadata_json(bytes: &[u8]) -> AppResult<NewManga> {
+    serde_json::from_slice(bytes).map_err(|e| AppError::ValidationFailed {
+        message: "metadata is not valid JSON".into(),
+        details: json!({ "metadata": e.to_string() }),
+    })
+}
+
+pub(crate) async fn next_field(
+    multipart: &mut Multipart,
+) -> AppResult<Option<axum::extract::multipart::Field<'_>>> {
+    multipart
+        .next_field()
+        .await
+        .map_err(map_multipart_error)
+}
+
+pub(crate) async fn read_field_bytes(
+    field: axum::extract::multipart::Field<'_>,
+) -> AppResult<axum::body::Bytes> {
+    field.bytes().await.map_err(map_multipart_error)
+}
+
+fn map_multipart_error(e: axum::extract::multipart::MultipartError) -> AppError {
+    let status = e.status();
+    if status == StatusCode::PAYLOAD_TOO_LARGE {
+        AppError::PayloadTooLarge("upload exceeds the request size limit".into())
+    } else {
+        AppError::InvalidInput(format!("multipart parse error: {e}"))
     }
-    Ok(Json(repo::manga::create(&state.db, input).await?))
 }

backend/src/app.rs

@@ -1,5 +1,6 @@
 use std::sync::Arc;
 
+use axum::extract::DefaultBodyLimit;
 use axum::http::{HeaderName, HeaderValue, Method};
 use axum::Router;
 use sqlx::postgres::PgPoolOptions;
@@ -7,7 +8,7 @@ use sqlx::PgPool;
 use tower_http::cors::{AllowOrigin, CorsLayer};
 use tower_http::trace::TraceLayer;
 
-use crate::config::{AuthConfig, Config};
+use crate::config::{AuthConfig, Config, UploadConfig};
 use crate::storage::{LocalStorage, Storage};
 
 #[derive(Clone)]
@@ -15,6 +16,7 @@ pub struct AppState {
     pub db: PgPool,
     pub storage: Arc<dyn Storage>,
     pub auth: AuthConfig,
+    pub upload: UploadConfig,
 }
 
 pub async fn build(config: Config) -> anyhow::Result<Router> {
@@ -26,15 +28,22 @@ pub async fn build(config: Config) -> anyhow::Result<Router> {
 
     let storage: Arc<dyn Storage> = Arc::new(LocalStorage::new(config.storage_dir.clone()));
 
-    let state = AppState { db, storage, auth: config.auth.clone() };
+    let state = AppState {
+        db,
+        storage,
+        auth: config.auth.clone(),
+        upload: config.upload.clone(),
+    };
     Ok(router(state).layer(cors_layer(&config.cors_allowed_origins)))
 }
 
 /// Build a router from a pre-assembled state. Used by integration tests
 /// so they can swap in a test DB pool and a `tempfile`-backed storage.
 pub fn router(state: AppState) -> Router {
+    let max_request_bytes = state.upload.max_request_bytes;
     Router::new()
         .nest("/api/v1", crate::api::routes())
+        .layer(DefaultBodyLimit::max(max_request_bytes))
         .with_state(state)
         .layer(TraceLayer::new_for_http())
 }

backend/src/config.rs

@@ -17,12 +17,33 @@ impl Default for AuthConfig {
     }
 }
 
+#[derive(Clone, Debug)]
+pub struct UploadConfig {
+    /// Total request size cap, enforced by axum's DefaultBodyLimit on the
+    /// upload routes. Rejected requests get a 413.
+    pub max_request_bytes: usize,
+    /// Per-image-part size cap, enforced after the part is read. Lets us
+    /// reject a single oversized cover/page without failing the whole
+    /// request just because the total happens to fit.
+    pub max_file_bytes: usize,
+}
+
+impl Default for UploadConfig {
+    fn default() -> Self {
+        Self {
+            max_request_bytes: 200 * 1024 * 1024, // 200 MiB
+            max_file_bytes: 20 * 1024 * 1024,     // 20 MiB
+        }
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct Config {
     pub database_url: String,
     pub bind_address: String,
     pub storage_dir: PathBuf,
     pub auth: AuthConfig,
+    pub upload: UploadConfig,
     pub cors_allowed_origins: Vec<String>,
 }
 
@@ -43,6 +64,10 @@ impl Config {
                     .filter(|s| !s.is_empty()),
                 session_ttl_days: env_i64("SESSION_TTL_DAYS", 30),
             },
+            upload: UploadConfig {
+                max_request_bytes: env_usize("MAX_REQUEST_BYTES", 200 * 1024 * 1024),
+                max_file_bytes: env_usize("MAX_FILE_BYTES", 20 * 1024 * 1024),
+            },
             cors_allowed_origins: std::env::var("CORS_ALLOWED_ORIGINS")
                 .ok()
                 .map(|s| {
@@ -70,3 +95,10 @@ fn env_i64(name: &str, default: i64) -> i64 {
         .and_then(|s| s.parse().ok())
         .unwrap_or(default)
 }
+
+fn env_usize(name: &str, default: usize) -> usize {
+    std::env::var(name)
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(default)
+}

backend/src/error.rs

@@ -17,6 +17,17 @@ pub enum AppError {
     Forbidden,
     #[error("conflict: {0}")]
     Conflict(String),
+    #[error("payload too large: {0}")]
+    PayloadTooLarge(String),
+    #[error("unsupported media type: {0}")]
+    UnsupportedMediaType(String),
+    /// Semantic per-field validation failure. `details` is rendered into the
+    /// envelope so the client can highlight the bad field(s).
+    #[error("validation failed")]
+    ValidationFailed {
+        message: String,
+        details: serde_json::Value,
+    },
     #[error(transparent)]
     Database(#[from] sqlx::Error),
     #[error(transparent)]
@@ -38,6 +49,9 @@ impl AppError {
             AppError::Unauthenticated => "unauthenticated",
             AppError::Forbidden => "forbidden",
             AppError::Conflict(_) => "conflict",
+            AppError::PayloadTooLarge(_) => "payload_too_large",
+            AppError::UnsupportedMediaType(_) => "unsupported_media_type",
+            AppError::ValidationFailed { .. } => "validation_failed",
             AppError::Database(sqlx::Error::RowNotFound) => "not_found",
             AppError::Database(_) => "internal_error",
             AppError::Storage(StorageError::NotFound) => "not_found",
@@ -51,27 +65,49 @@ impl AppError {
 impl IntoResponse for AppError {
     fn into_response(self) -> Response {
         let code = self.code();
-        let (status, message) = match &self {
+        let (status, message, details) = match &self {
-            AppError::NotFound => (StatusCode::NOT_FOUND, "not found".to_string()),
+            AppError::NotFound => (StatusCode::NOT_FOUND, "not found".to_string(), None),
-            AppError::InvalidInput(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
+            AppError::InvalidInput(msg) => (StatusCode::BAD_REQUEST, msg.clone(), None),
-            AppError::Unauthenticated => (StatusCode::UNAUTHORIZED, "unauthenticated".to_string()),
+            AppError::Unauthenticated => {
-            AppError::Forbidden => (StatusCode::FORBIDDEN, "forbidden".to_string()),
+                (StatusCode::UNAUTHORIZED, "unauthenticated".to_string(), None)
-            AppError::Conflict(msg) => (StatusCode::CONFLICT, msg.clone()),
+            }
+            AppError::Forbidden => (StatusCode::FORBIDDEN, "forbidden".to_string(), None),
+            AppError::Conflict(msg) => (StatusCode::CONFLICT, msg.clone(), None),
+            AppError::PayloadTooLarge(msg) => {
+                (StatusCode::PAYLOAD_TOO_LARGE, msg.clone(), None)
+            }
+            AppError::UnsupportedMediaType(msg) => {
+                (StatusCode::UNSUPPORTED_MEDIA_TYPE, msg.clone(), None)
+            }
+            AppError::ValidationFailed { message, details } => (
+                StatusCode::UNPROCESSABLE_ENTITY,
+                message.clone(),
+                Some(details.clone()),
+            ),
             AppError::Database(sqlx::Error::RowNotFound) => {
-                (StatusCode::NOT_FOUND, "not found".to_string())
+                (StatusCode::NOT_FOUND, "not found".to_string(), None)
             }
             AppError::Storage(StorageError::NotFound) => {
-                (StatusCode::NOT_FOUND, "not found".to_string())
+                (StatusCode::NOT_FOUND, "not found".to_string(), None)
-            }
-            AppError::Storage(StorageError::BadKey) => {
-                (StatusCode::BAD_REQUEST, "invalid file key".to_string())
             }
+            AppError::Storage(StorageError::BadKey) => (
+                StatusCode::BAD_REQUEST,
+                "invalid file key".to_string(),
+                None,
+            ),
             AppError::Database(_) | AppError::Storage(_) | AppError::Other(_) => {
                 tracing::error!(error = ?self, "internal error");
-                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".to_string())
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "internal error".to_string(),
+                    None,
+                )
             }
         };
-        let body = json!({ "error": { "code": code, "message": message } });
+        let body = match details {
+            Some(d) => json!({ "error": { "code": code, "message": message, "details": d } }),
+            None => json!({ "error": { "code": code, "message": message } }),
+        };
         (status, Json(body)).into_response()
     }
 }
@@ -87,6 +123,19 @@ mod tests {
         assert_eq!(AppError::Unauthenticated.code(), "unauthenticated");
         assert_eq!(AppError::Forbidden.code(), "forbidden");
         assert_eq!(AppError::Conflict("x".into()).code(), "conflict");
+        assert_eq!(AppError::PayloadTooLarge("x".into()).code(), "payload_too_large");
+        assert_eq!(
+            AppError::UnsupportedMediaType("x".into()).code(),
+            "unsupported_media_type"
+        );
+        assert_eq!(
+            AppError::ValidationFailed {
+                message: "x".into(),
+                details: json!({}),
+            }
+            .code(),
+            "validation_failed"
+        );
         assert_eq!(AppError::Storage(StorageError::BadKey).code(), "bad_file_key");
         assert_eq!(AppError::Storage(StorageError::NotFound).code(), "not_found");
         assert_eq!(AppError::Database(sqlx::Error::RowNotFound).code(), "not_found");

backend/src/lib.rs

@@ -6,3 +6,4 @@ pub mod domain;
 pub mod error;
 pub mod repo;
 pub mod storage;
+pub mod upload;

backend/src/upload/mod.rs

@@ -0,0 +1,92 @@
+//! Shared helpers for multipart upload handlers.
+//!
+//! `parse_image` enforces the per-file size cap, sniffs the MIME by
+//! magic bytes (not by the client-supplied Content-Type or filename),
+//! and rejects anything outside the jpeg / png / webp / gif / avif
+//! whitelist with 415. Filename and extension never reach the storage
+//! key — we derive both from the sniffed type.
+
+use crate::error::{AppError, AppResult};
+
+#[derive(Debug, Clone)]
+pub struct UploadedImage {
+    pub bytes: Vec<u8>,
+    pub mime: &'static str,
+    pub ext: &'static str,
+}
+
+pub fn parse_image(bytes: Vec<u8>, max_size: usize, field_name: &str) -> AppResult<UploadedImage> {
+    if bytes.len() > max_size {
+        return Err(AppError::PayloadTooLarge(format!(
+            "{field_name} exceeds {max_size}-byte cap"
+        )));
+    }
+    let kind = infer::get(&bytes).ok_or_else(|| {
+        AppError::UnsupportedMediaType(format!("{field_name}: unrecognised image format"))
+    })?;
+    let (mime, ext) = match kind.mime_type() {
+        "image/jpeg" => ("image/jpeg", "jpg"),
+        "image/png" => ("image/png", "png"),
+        "image/webp" => ("image/webp", "webp"),
+        "image/gif" => ("image/gif", "gif"),
+        "image/avif" => ("image/avif", "avif"),
+        other => {
+            return Err(AppError::UnsupportedMediaType(format!(
+                "{field_name}: unsupported image type {other}"
+            )));
+        }
+    };
+    Ok(UploadedImage { bytes, mime, ext })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn png_bytes() -> Vec<u8> {
+        // PNG magic + minimum padding so infer can identify it.
+        vec![0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0]
+    }
+
+    fn jpeg_bytes() -> Vec<u8> {
+        vec![0xff, 0xd8, 0xff, 0xe0, 0, 0x10, b'J', b'F', b'I', b'F', 0, 0]
+    }
+
+    fn pdf_bytes() -> Vec<u8> {
+        b"%PDF-1.4\n%\xc4\xe5".to_vec()
+    }
+
+    #[test]
+    fn accepts_png() {
+        let img = parse_image(png_bytes(), 1024, "cover").unwrap();
+        assert_eq!(img.mime, "image/png");
+        assert_eq!(img.ext, "png");
+    }
+
+    #[test]
+    fn accepts_jpeg() {
+        let img = parse_image(jpeg_bytes(), 1024, "cover").unwrap();
+        assert_eq!(img.mime, "image/jpeg");
+        assert_eq!(img.ext, "jpg");
+    }
+
+    #[test]
+    fn rejects_non_image_with_unsupported_media_type() {
+        let err = parse_image(pdf_bytes(), 1024, "cover").unwrap_err();
+        assert!(matches!(err, AppError::UnsupportedMediaType(_)));
+        assert_eq!(err.code(), "unsupported_media_type");
+    }
+
+    #[test]
+    fn rejects_garbage_with_unsupported_media_type() {
+        let err = parse_image(b"just some text".to_vec(), 1024, "cover").unwrap_err();
+        assert!(matches!(err, AppError::UnsupportedMediaType(_)));
+    }
+
+    #[test]
+    fn rejects_oversized() {
+        let err = parse_image(png_bytes(), 4, "cover").unwrap_err();
+        assert!(matches!(err, AppError::PayloadTooLarge(_)));
+        assert_eq!(err.code(), "payload_too_large");
+    }
+}

backend/tests/api_chapters.rs

@@ -5,27 +5,13 @@ use serde_json::json;
 use sqlx::PgPool;
 use tower::ServiceExt;
 use uuid::Uuid;
+#[allow(unused_imports)]
+use serde_json as _;
 
-/// Create a manga via the API (which requires auth) and return its id +
-/// the session cookie of the user who owns it.
 async fn seed_manga(h: &common::Harness, cookie: &str, title: &str) -> Uuid {
-    let resp = h
+    common::seed_manga_via_api(&h.app, cookie, title).await
-        .app
-        .clone()
-        .oneshot(common::post_json_with_cookie(
-            "/api/v1/mangas",
-            json!({ "title": title }),
-            cookie,
-        ))
-        .await
-        .unwrap();
-    assert_eq!(resp.status(), StatusCode::OK);
-    let body = common::body_json(resp).await;
-    Uuid::parse_str(body["id"].as_str().unwrap()).unwrap()
 }
 
-/// Insert a chapter directly via the repo (the upload handler that does
-/// this from HTTP lands in feat/uploads).
 async fn seed_chapter(pool: &PgPool, manga_id: Uuid, number: i32, title: Option<&str>) {
     mangalord::repo::chapter::create(pool, manga_id, number, title)
         .await

backend/tests/api_mangas.rs

@@ -5,6 +5,12 @@ use serde_json::json;
 use sqlx::PgPool;
 use tower::ServiceExt;
 
+use common::MultipartBuilder;
+
+fn metadata(title: &str) -> serde_json::Value {
+    json!({ "title": title })
+}
+
 #[sqlx::test(migrations = "./migrations")]
 async fn list_is_empty_initially(pool: PgPool) {
     let h = common::harness(pool);
@@ -25,14 +31,17 @@ async fn create_then_list_roundtrip(pool: PgPool) {
     let created = h
         .app
         .clone()
-        .oneshot(common::post_json_with_cookie(
+        .oneshot(common::post_multipart_with_cookie(
             "/api/v1/mangas",
-            json!({ "title": "Berserk", "author": "Kentaro Miura", "description": null }),
+            MultipartBuilder::new().add_json(
+                "metadata",
+                json!({ "title": "Berserk", "author": "Kentaro Miura", "description": null }),
+            ),
             &cookie,
         ))
         .await
         .unwrap();
-    assert_eq!(created.status(), StatusCode::OK);
+    assert_eq!(created.status(), StatusCode::CREATED);
     let body = common::body_json(created).await;
     assert_eq!(body["title"], "Berserk");
     assert_eq!(body["author"], "Kentaro Miura");
@@ -58,9 +67,10 @@ async fn search_filters_by_title_and_author(pool: PgPool) {
         let _ = h
             .app
             .clone()
-            .oneshot(common::post_json_with_cookie(
+            .oneshot(common::post_multipart_with_cookie(
                 "/api/v1/mangas",
-                json!({ "title": title, "author": author }),
+                MultipartBuilder::new()
+                    .add_json("metadata", json!({ "title": title, "author": author })),
                 &cookie,
             ))
             .await
@@ -98,23 +108,41 @@ async fn search_filters_by_title_and_author(pool: PgPool) {
 }
 
 #[sqlx::test(migrations = "./migrations")]
-async fn create_rejects_empty_title_with_envelope(pool: PgPool) {
+async fn create_rejects_empty_title_with_validation_failed(pool: PgPool) {
     let h = common::harness(pool);
     let (_, cookie) = common::register_user(&h.app).await;
     let resp = h
         .app
-        .oneshot(common::post_json_with_cookie(
+        .oneshot(common::post_multipart_with_cookie(
             "/api/v1/mangas",
-            json!({ "title": "   ", "author": null }),
+            MultipartBuilder::new().add_json("metadata", metadata("   ")),
             &cookie,
         ))
         .await
         .unwrap();
-    assert_eq!(resp.status(), StatusCode::BAD_REQUEST);
+    assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
     let body = common::body_json(resp).await;
-    assert_eq!(body["error"]["code"], "invalid_input");
+    assert_eq!(body["error"]["code"], "validation_failed");
-    let msg = body["error"]["message"].as_str().expect("message is string");
+    assert!(body["error"]["details"]["title"].is_string());
-    assert!(!msg.is_empty(), "message should be non-empty");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_rejects_missing_metadata_part(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let resp = h
+        .app
+        .oneshot(common::post_multipart_with_cookie(
+            "/api/v1/mangas",
+            MultipartBuilder::new(), // no metadata part
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "validation_failed");
+    assert_eq!(body["error"]["details"]["metadata"], "required");
 }
 
 #[sqlx::test(migrations = "./migrations")]
@@ -122,9 +150,9 @@ async fn create_requires_authentication(pool: PgPool) {
     let h = common::harness(pool);
     let resp = h
         .app
-        .oneshot(common::post_json(
+        .oneshot(common::post_multipart(
             "/api/v1/mangas",
-            json!({ "title": "Berserk" }),
+            MultipartBuilder::new().add_json("metadata", metadata("Berserk")),
         ))
         .await
         .unwrap();

backend/tests/api_uploads.rs

@@ -0,0 +1,275 @@
+mod common;
+
+use axum::http::StatusCode;
+use serde_json::json;
+use sqlx::PgPool;
+use tower::ServiceExt;
+use uuid::Uuid;
+
+use common::MultipartBuilder;
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_manga_with_cover_stores_image(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::post_multipart_with_cookie(
+            "/api/v1/mangas",
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "title": "Berserk" }))
+                .add_file("cover", "cover.png", "image/png", &common::fake_png_bytes()),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED);
+    let body = common::body_json(resp).await;
+    let manga_id = Uuid::parse_str(body["id"].as_str().unwrap()).unwrap();
+    let cover_path = body["cover_image_path"]
+        .as_str()
+        .expect("cover_image_path set after upload");
+    assert_eq!(cover_path, &format!("mangas/{manga_id}/cover.png"));
+
+    // The blob is reachable via the files endpoint and round-trips byte-for-byte.
+    let file_resp = h
+        .app
+        .oneshot(common::get(&format!("/api/v1/files/{cover_path}")))
+        .await
+        .unwrap();
+    assert_eq!(file_resp.status(), StatusCode::OK);
+    let ct = file_resp
+        .headers()
+        .get(axum::http::header::CONTENT_TYPE)
+        .unwrap();
+    assert_eq!(ct, "image/png");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_manga_without_cover_leaves_path_null(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    let resp = h
+        .app
+        .oneshot(common::post_multipart_with_cookie(
+            "/api/v1/mangas",
+            MultipartBuilder::new().add_json("metadata", json!({ "title": "Solo Manga" })),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED);
+    let body = common::body_json(resp).await;
+    assert!(body["cover_image_path"].is_null());
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_manga_rejects_non_image_cover_with_415(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    let pdf = b"%PDF-1.4\n%\xc4\xe5".to_vec();
+    let resp = h
+        .app
+        .oneshot(common::post_multipart_with_cookie(
+            "/api/v1/mangas",
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "title": "Bad Cover" }))
+                .add_file("cover", "cover.png", "image/png", &pdf),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "unsupported_media_type");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_manga_rejects_oversized_cover_with_413(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+
+    // Test harness max_file_bytes is 256 KiB. Build a "PNG" that's 300 KiB.
+    let mut big = common::fake_png_bytes();
+    big.resize(300 * 1024, 0);
+    let resp = h
+        .app
+        .oneshot(common::post_multipart_with_cookie(
+            "/api/v1/mangas",
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "title": "Heavy Cover" }))
+                .add_file("cover", "cover.png", "image/png", &big),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::PAYLOAD_TOO_LARGE);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "payload_too_large");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_chapter_with_pages_stores_each(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "Berserk").await;
+
+    let resp = h
+        .app
+        .clone()
+        .oneshot(common::post_multipart_with_cookie(
+            &format!("/api/v1/mangas/{manga_id}/chapters"),
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "number": 1, "title": "The Brand" }))
+                .add_file("page", "1.png", "image/png", &common::fake_png_bytes())
+                .add_file("page", "2.jpg", "image/jpeg", &common::fake_jpeg_bytes())
+                .add_file("page", "3.png", "image/png", &common::fake_png_bytes()),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::CREATED);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["number"], 1);
+    assert_eq!(body["title"], "The Brand");
+    assert_eq!(body["page_count"], 3);
+
+    let chapter_id = Uuid::parse_str(body["id"].as_str().unwrap()).unwrap();
+
+    // Each page is reachable in arrival order, with the correct extension
+    // derived from the sniffed MIME (not the client filename).
+    for (idx, expected_ct) in [
+        (1, "image/png"),
+        (2, "image/jpeg"),
+        (3, "image/png"),
+    ] {
+        let ext = match expected_ct {
+            "image/png" => "png",
+            "image/jpeg" => "jpg",
+            _ => unreachable!(),
+        };
+        let key = format!("mangas/{manga_id}/chapters/{chapter_id}/pages/{idx:04}.{ext}");
+        let file_resp = h
+            .app
+            .clone()
+            .oneshot(common::get(&format!("/api/v1/files/{key}")))
+            .await
+            .unwrap();
+        assert_eq!(file_resp.status(), StatusCode::OK, "missing page {idx}");
+        let ct = file_resp
+            .headers()
+            .get(axum::http::header::CONTENT_TYPE)
+            .unwrap();
+        assert_eq!(ct, expected_ct);
+    }
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_chapter_rejects_when_no_pages_with_422(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "Berserk").await;
+
+    let resp = h
+        .app
+        .oneshot(common::post_multipart_with_cookie(
+            &format!("/api/v1/mangas/{manga_id}/chapters"),
+            MultipartBuilder::new().add_json("metadata", json!({ "number": 1 })),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "validation_failed");
+    assert!(body["error"]["details"]["page"].is_string());
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_chapter_rejects_renamed_non_image_page(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "Berserk").await;
+
+    // Client claims it's an image; bytes are a PDF.
+    let pdf = b"%PDF-1.4\n%\xc4\xe5".to_vec();
+    let resp = h
+        .app
+        .oneshot(common::post_multipart_with_cookie(
+            &format!("/api/v1/mangas/{manga_id}/chapters"),
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "number": 1 }))
+                .add_file("page", "page1.png", "image/png", &pdf),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNSUPPORTED_MEDIA_TYPE);
+    let body = common::body_json(resp).await;
+    assert_eq!(body["error"]["code"], "unsupported_media_type");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_chapter_returns_409_on_duplicate_number(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "Berserk").await;
+
+    let make = || {
+        common::post_multipart_with_cookie(
+            &format!("/api/v1/mangas/{manga_id}/chapters"),
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "number": 1 }))
+                .add_file("page", "1.png", "image/png", &common::fake_png_bytes()),
+            &cookie,
+        )
+    };
+    let first = h.app.clone().oneshot(make()).await.unwrap();
+    assert_eq!(first.status(), StatusCode::CREATED);
+    let second = h.app.oneshot(make()).await.unwrap();
+    assert_eq!(second.status(), StatusCode::CONFLICT);
+    let body = common::body_json(second).await;
+    assert_eq!(body["error"]["code"], "conflict");
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_chapter_requires_authentication(pool: PgPool) {
+    let h = common::harness(pool.clone());
+    let (_, cookie) = common::register_user(&h.app).await;
+    let manga_id = common::seed_manga_via_api(&h.app, &cookie, "Berserk").await;
+
+    let resp = h
+        .app
+        .oneshot(common::post_multipart(
+            &format!("/api/v1/mangas/{manga_id}/chapters"),
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "number": 1 }))
+                .add_file("page", "1.png", "image/png", &common::fake_png_bytes()),
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
+}
+
+#[sqlx::test(migrations = "./migrations")]
+async fn create_chapter_under_unknown_manga_is_404(pool: PgPool) {
+    let h = common::harness(pool);
+    let (_, cookie) = common::register_user(&h.app).await;
+    let unknown = Uuid::nil();
+    let resp = h
+        .app
+        .oneshot(common::post_multipart_with_cookie(
+            &format!("/api/v1/mangas/{unknown}/chapters"),
+            MultipartBuilder::new()
+                .add_json("metadata", json!({ "number": 1 }))
+                .add_file("page", "1.png", "image/png", &common::fake_png_bytes()),
+            &cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+}

backend/tests/common/mod.rs

@@ -15,7 +15,7 @@ use tempfile::TempDir;
 use tower::ServiceExt;
 
 use mangalord::app::{router, AppState};
-use mangalord::config::AuthConfig;
+use mangalord::config::{AuthConfig, UploadConfig};
 use mangalord::storage::LocalStorage;
 
 pub struct Harness {
@@ -30,6 +30,12 @@ pub fn harness(pool: PgPool) -> Harness {
         db: pool,
         storage: Arc::new(LocalStorage::new(storage_dir.path())),
         auth: AuthConfig { cookie_secure: false, ..AuthConfig::default() },
+        upload: UploadConfig {
+            // Keep file caps small in tests so the size-cap path is cheap to
+            // exercise without producing tens of MBs of bytes.
+            max_request_bytes: 4 * 1024 * 1024,
+            max_file_bytes: 256 * 1024,
+        },
     };
     Harness { app: router(state), _storage_dir: storage_dir }
 }
@@ -124,6 +130,141 @@ pub fn extract_session_cookie(response: &axum::response::Response) -> Option<Str
         })
 }
 
+/// Minimal multipart builder for tests. Real clients would use a real
+/// library; we hand-roll a small one so the test crate stays free of
+/// http-client dependencies.
+pub struct MultipartBuilder {
+    boundary: String,
+    body: Vec<u8>,
+}
+
+impl Default for MultipartBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MultipartBuilder {
+    pub fn new() -> Self {
+        Self {
+            boundary: format!("----mangalord-test-{}", uuid::Uuid::new_v4().simple()),
+            body: Vec::new(),
+        }
+    }
+
+    pub fn add_json(mut self, name: &str, value: serde_json::Value) -> Self {
+        self.write_part_header(name, None, Some("application/json"));
+        self.body.extend(value.to_string().as_bytes());
+        self.body.extend(b"\r\n");
+        self
+    }
+
+    pub fn add_file(
+        mut self,
+        name: &str,
+        filename: &str,
+        content_type: &str,
+        bytes: &[u8],
+    ) -> Self {
+        self.write_part_header(name, Some(filename), Some(content_type));
+        self.body.extend(bytes);
+        self.body.extend(b"\r\n");
+        self
+    }
+
+    fn write_part_header(
+        &mut self,
+        name: &str,
+        filename: Option<&str>,
+        ct: Option<&str>,
+    ) {
+        self.body
+            .extend(format!("--{}\r\n", self.boundary).as_bytes());
+        let disposition = if let Some(fname) = filename {
+            format!(
+                "Content-Disposition: form-data; name=\"{name}\"; filename=\"{fname}\"\r\n"
+            )
+        } else {
+            format!("Content-Disposition: form-data; name=\"{name}\"\r\n")
+        };
+        self.body.extend(disposition.as_bytes());
+        if let Some(ct) = ct {
+            self.body.extend(format!("Content-Type: {ct}\r\n").as_bytes());
+        }
+        self.body.extend(b"\r\n");
+    }
+
+    fn finalize(self) -> (String, Vec<u8>) {
+        let mut body = self.body;
+        body.extend(format!("--{}--\r\n", self.boundary).as_bytes());
+        (self.boundary, body)
+    }
+}
+
+pub fn post_multipart(uri: &str, builder: MultipartBuilder) -> Request<Body> {
+    let (boundary, body) = builder.finalize();
+    Request::builder()
+        .method("POST")
+        .uri(uri)
+        .header(
+            header::CONTENT_TYPE,
+            format!("multipart/form-data; boundary={boundary}"),
+        )
+        .body(Body::from(body))
+        .unwrap()
+}
+
+pub fn post_multipart_with_cookie(
+    uri: &str,
+    builder: MultipartBuilder,
+    cookie: &str,
+) -> Request<Body> {
+    let (boundary, body) = builder.finalize();
+    Request::builder()
+        .method("POST")
+        .uri(uri)
+        .header(
+            header::CONTENT_TYPE,
+            format!("multipart/form-data; boundary={boundary}"),
+        )
+        .header(header::COOKIE, cookie)
+        .body(Body::from(body))
+        .unwrap()
+}
+
+/// Realistic PNG file header bytes — enough for `infer` to identify.
+pub fn fake_png_bytes() -> Vec<u8> {
+    vec![0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0]
+}
+
+/// Realistic JPEG file header bytes — enough for `infer` to identify.
+pub fn fake_jpeg_bytes() -> Vec<u8> {
+    vec![
+        0xff, 0xd8, 0xff, 0xe0, 0, 0x10, b'J', b'F', b'I', b'F', 0, 0,
+    ]
+}
+
+/// Create a manga via the upload API and return its id. Used by tests
+/// that need a manga to exist before they exercise chapters / etc.
+pub async fn seed_manga_via_api(app: &Router, cookie: &str, title: &str) -> uuid::Uuid {
+    let resp = app
+        .clone()
+        .oneshot(post_multipart_with_cookie(
+            "/api/v1/mangas",
+            MultipartBuilder::new().add_json("metadata", serde_json::json!({ "title": title })),
+            cookie,
+        ))
+        .await
+        .unwrap();
+    assert_eq!(
+        resp.status(),
+        axum::http::StatusCode::CREATED,
+        "seed_manga_via_api failed"
+    );
+    let body = body_json(resp).await;
+    uuid::Uuid::parse_str(body["id"].as_str().unwrap()).unwrap()
+}
+
 /// Register a brand-new user and return (username, session cookie value).
 /// The username is unique per call so tests can run in parallel against a
 /// single DB without colliding.

frontend/e2e/auth-flow.spec.ts

@@ -61,6 +61,12 @@ test('login then logout flips the layout between authenticated and anonymous', a
 
     // Log in.
     await page.goto('/login');
+    // Wait for hydration to finish before interacting — the nav-login link
+    // is only rendered once /me resolves, so it doubles as a hydration
+    // signal. Clicking before hydration would submit the form via the
+    // browser default (action="javascript:void(0)") and our handler would
+    // never run.
+    await expect(page.getByTestId('nav-login')).toBeVisible();
     await page.getByTestId('login-username').fill('alice');
     await page.getByTestId('login-password').fill('hunter2hunter2');
     await page.getByTestId('login-submit').click();
@@ -94,6 +100,7 @@ test('login surfaces the API error message on bad credentials', async ({ page })
     });
 
     await page.goto('/login');
+    await expect(page.getByTestId('nav-login')).toBeVisible();
     await page.getByTestId('login-username').fill('alice');
     await page.getByTestId('login-password').fill('wrongpassword');
     await page.getByTestId('login-submit').click();

frontend/package.json

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

frontend/src/lib/api/mangas.test.ts

@@ -70,7 +70,7 @@ describe('mangas api client', () => {
         expect(url).toContain('offset=20');
     });
 
-    it('createManga POSTs JSON to /v1/mangas', async () => {
+    it('createManga POSTs multipart with metadata to /v1/mangas', async () => {
         fetchSpy.mockResolvedValueOnce(
             ok({
                 id: 'abc',
@@ -88,8 +88,42 @@ describe('mangas api client', () => {
         expect(url).toMatch(/\/v1\/mangas$/);
         const init = fetchSpy.mock.calls[0][1] as RequestInit;
         expect(init.method).toBe('POST');
-        expect(init.headers).toMatchObject({ 'content-type': 'application/json' });
+        expect(init.body).toBeInstanceOf(FormData);
-        expect(JSON.parse(init.body as string)).toEqual({ title: 'Berserk', author: 'Miura' });
+        const form = init.body as FormData;
+        const metadata = form.get('metadata') as Blob;
+        expect(metadata).toBeInstanceOf(Blob);
+        expect(metadata.type).toBe('application/json');
+        // jsdom doesn't implement Blob.text(); read the bytes via FileReader.
+        const text = await new Promise<string>((resolve) => {
+            const reader = new FileReader();
+            reader.onload = () => resolve(reader.result as string);
+            reader.readAsText(metadata);
+        });
+        expect(text).toBe(JSON.stringify({ title: 'Berserk', author: 'Miura' }));
+        expect(form.get('cover')).toBeNull();
+        // The browser sets Content-Type with boundary automatically when body
+        // is a FormData — we must NOT set it ourselves.
+        expect(init.headers).toBeUndefined();
+    });
+
+    it('createManga attaches the cover Blob when supplied', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            ok({
+                id: 'abc',
+                title: 'Berserk',
+                author: null,
+                description: null,
+                cover_image_path: 'mangas/abc/cover.png',
+                created_at: '2026-01-01T00:00:00Z',
+                updated_at: '2026-01-01T00:00:00Z'
+            })
+        );
+        const cover = new Blob([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], { type: 'image/png' });
+        await createManga({ title: 'Berserk' }, cover);
+        const init = fetchSpy.mock.calls[0][1] as RequestInit;
+        const form = init.body as FormData;
+        const got = form.get('cover');
+        expect(got).toBeInstanceOf(Blob);
     });
 
     it('getManga throws ApiError carrying the envelope code on non-2xx', async () => {

frontend/src/lib/api/mangas.ts

@@ -30,12 +30,20 @@ export type NewManga = {
     description?: string | null;
 };
 
-export async function createManga(input: NewManga): Promise<Manga> {
+/**
-    return request<Manga>('/v1/mangas', {
+ * POST /api/v1/mangas is multipart. The metadata part is JSON; the cover
-        method: 'POST',
+ * part is the raw image bytes. The browser fills in the multipart boundary
-        headers: { 'content-type': 'application/json' },
+ * automatically when `body` is a FormData, so we deliberately do not set
-        body: JSON.stringify(input)
+ * Content-Type ourselves.
-    });
+ */
+export async function createManga(input: NewManga, cover?: Blob): Promise<Manga> {
+    const form = new FormData();
+    form.append(
+        'metadata',
+        new Blob([JSON.stringify(input)], { type: 'application/json' })
+    );
+    if (cover) form.append('cover', cover);
+    return request<Manga>('/v1/mangas', { method: 'POST', body: form });
 }
 
 export type { Manga, Page };