feat(backend): メール認証を行えるように

apps/backend/.env.example

@@ -6,3 +6,4 @@ smtp_port=587
 smtp_username=your_smtp_username
 smtp_password=your_smtp_password
 smtp_from=no-reply@example.com
+email_verification_app_url=http://localhost:3000

apps/backend/src/entities/README.md

@@ -1,3 +1,3 @@
-# entities Module
+# entities
 
-このモジュールは、データベースのエンティティを定義します。各エンティティは、SeaORMのマクロを使用して定義されており、データベースのテーブル構造に対応しています。また、OpenAPIドキュメント生成のために、`utoipa::ToSchema`トレイトも実装しています。これにより、APIエンドポイントで使用されるデータ構造が明確になり、クライアントとのインターフェースが一貫性を持つようになります。
+API や永続化で使うモデルをまとめるモジュールです。レスポンス用の `@ToSchema` 付きモデルもここに置きます。

apps/backend/src/entities/scopes.rs

@@ -29,7 +29,7 @@ pub enum Scope {
     AdminAll,
 }
 
-/// JSON カラム用の `Vec<Scope>` ラッパ（SeaORM エンティティ向け）。
+/// アクセストークン等に付与する権限スコープのリスト。
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, FromJsonQueryResult, ToSchema)]
 #[serde(transparent)]
 pub struct ScopeList(pub Vec<Scope>);

apps/backend/src/entities/users.rs

@@ -17,8 +17,11 @@ pub struct Model {
     #[sea_orm(nullable)]
     #[schema(nullable)]
     pub avatar_url: Option<String>,
+    #[sea_orm(unique)]
     #[schema(value_type = String, format="email")]
     pub email: String,
+    /// メールアドレスの確認が済んでいるかどうか
+    pub email_verified: bool,
     #[schema(ignore)]
     #[serde(skip_serializing)]
     pub password_hash: String,

apps/backend/src/handlers/auth.rs

@@ -1,17 +1,25 @@
-use axum::{Json, extract::State};
+use axum::{Json, extract::State, http::StatusCode};
 use axum_session::Session;
 use axum_session_redispool::SessionRedisPool;
 use axum_valid::Valid;
 use sea_orm::prelude::Uuid;
-use sea_orm::{ActiveValue::Set, EntityTrait};
+use sea_orm::{ActiveModelTrait, ActiveValue::Set, EntityTrait};
 use sea_orm::{ColumnTrait, QueryFilter};
 use serde::Deserialize;
 use validator::Validate;
 
 use crate::entities;
 use crate::extractors::{AuthUser, CurrentUser};
-use crate::openapi::{CredentialErrors, InternalOnlyError, SessionAuthErrors, UnauthorizedErrors};
-use crate::utils::auth::{AuthError, create_password_hash, verify_password};
+use crate::openapi::{
+    CredentialErrors, RegisterErrors, ResendVerificationErrors, SessionAuthErrors,
+    UnauthorizedErrors, VerifyEmailErrors,
+};
+use crate::settings::Settings;
+use crate::utils::auth::{
+    AuthError, create_password_hash, generate_email_verification_token, verify_password,
+};
+use crate::utils::db::is_postgres_unique_violation;
+use crate::utils::{email_verification, smtp::SmtpClient};
 use crate::{AppState, entities::users};
 
 #[derive(Validate, Debug, Deserialize, utoipa::ToSchema)]
@@ -28,30 +36,34 @@ pub struct LoginRequest {
 #[utoipa::path(
     post,
     path = "/login",
+    summary = "ログイン",
     request_body = LoginRequest,
     responses(
-        (status = 200, description = "Login successful", body = String),
+        (status = 204, description = "ログインに成功しました（本文なし）"),
         CredentialErrors,
     )
 )]
 pub async fn login(
     session: Session<SessionRedisPool>,
     State(state): State<AppState>,
     Valid(Json(payload)): Valid<Json<LoginRequest>>,
-) -> Result<Json<String>, AuthError> {
+) -> Result<StatusCode, AuthError> {
     let LoginRequest { email, password } = payload;
 
     let user = users::Entity::find()
         .filter(users::Column::Email.eq(email))
         .one(&state.db)
         .await?
-        .ok_or(AuthError::Forbidden)?;
-    if verify_password(&password, &user.password_hash)? {
-        session.set("user_id", user.id);
-        Ok(Json("Login successful".to_string()))
-    } else {
-        Err(AuthError::Forbidden)
+        .ok_or(AuthError::InvalidCredentials)?;
+    if !verify_password(&password, &user.password_hash)? {
+        return Err(AuthError::InvalidCredentials);
+    }
+    if !user.email_verified {
+        return Err(AuthError::EmailNotVerified);
     }
+
+    session.set("user_id", user.id);
+    Ok(StatusCode::NO_CONTENT)
 }
 
 #[derive(Validate, Debug, Deserialize, utoipa::ToSchema)]
@@ -71,50 +83,183 @@ pub struct RegisterRequest {
 #[utoipa::path(
     post,
     path = "/register",
+    summary = "新規登録",
     request_body = RegisterRequest,
     responses(
-        (status = 200, description = "Register successful", body = String),
-        InternalOnlyError,
+        (
+            status = 201,
+            description = "アカウントが作成されました。続けて送信されたメールで認証してください。",
+            body = String
+        ),
+        RegisterErrors,
     )
 )]
 pub async fn register(
-    session: Session<SessionRedisPool>,
     State(state): State<AppState>,
     Valid(Json(payload)): Valid<Json<RegisterRequest>>,
-) -> Result<Json<String>, AuthError> {
+) -> Result<(StatusCode, Json<String>), AuthError> {
     let RegisterRequest {
         username,
         email,
         password,
     } = payload;
 
     let password_hash = create_password_hash(&password)?;
+    let verification_token = generate_email_verification_token();
     let user_id = Uuid::new_v4();
 
     let user = users::ActiveModel {
         id: Set(user_id),
         username: Set(username),
         bio: Set(Some(String::new())),
         avatar_url: Set(None),
-        email: Set(email),
+        email: Set(email.clone()),
+        email_verified: Set(false),
         password_hash: Set(password_hash),
     };
 
     users::Entity::insert(user.clone())
         .exec(&state.db)
         .await
-        .map_err(|e| AuthError::Internal(anyhow::anyhow!("insert user: {e}")))?;
+        .map_err(|e| {
+            if is_postgres_unique_violation(&e) {
+                AuthError::DuplicateEmail
+            } else {
+                AuthError::Internal(anyhow::anyhow!("insert user: {e}"))
+            }
+        })?;
 
-    session.set("user_id", user_id);
-    Ok(Json("Register successful".to_string()))
+    email_verification::store_token(&state.redis_client, user_id, &verification_token)
+        .await
+        .map_err(|e| AuthError::Internal(anyhow::anyhow!("redis store verification token: {e}")))?;
+
+    send_verification_email(
+        &state.smtp_client,
+        &email,
+        &state.settings,
+        &verification_token,
+    )
+    .await?;
+    Ok((
+        StatusCode::CREATED,
+        Json("Register successful".to_string()),
+    ))
+}
+
+/// メールでの本人確認時に送信する情報。
+#[derive(Validate, Debug, Deserialize, utoipa::ToSchema)]
+pub struct VerifyEmailRequest {
+    /// メールまたはアプリにお知らせした認証用文字列です。
+    #[validate(length(min = 1))]
+    pub token: String,
+}
+
+#[axum::debug_handler]
+#[utoipa::path(
+    post,
+    path = "/verify-email",
+    summary = "メールアドレスの確認",
+    request_body = VerifyEmailRequest,
+    responses(
+        (
+            status = 200,
+            description = "メールアドレスの確認が完了しました",
+            body = String
+        ),
+        VerifyEmailErrors,
+    )
+)]
+pub async fn verify_email(
+    State(state): State<AppState>,
+    Valid(Json(payload)): Valid<Json<VerifyEmailRequest>>,
+) -> Result<Json<String>, AuthError> {
+    let user_id =
+        email_verification::consume_token(&state.redis_client, &payload.token)
+            .await
+            .map_err(|e| AuthError::Internal(anyhow::anyhow!("redis consume verification token: {e}")))?
+            .ok_or(AuthError::InvalidVerificationToken)?;
+
+    let user = users::Entity::find_by_id(user_id)
+        .one(&state.db)
+        .await?
+        .ok_or_else(|| {
+            AuthError::Internal(anyhow::anyhow!(
+                "email verification token referenced missing user"
+            ))
+        })?;
+
+    if user.email_verified {
+        return Ok(Json("Email already verified".to_string()));
+    }
+
+    let mut active: users::ActiveModel = user.into();
+    active.email_verified = Set(true);
+    active.update(&state.db).await?;
+
+    Ok(Json("Email verified".to_string()))
+}
+
+#[derive(Validate, Debug, Deserialize, utoipa::ToSchema)]
+pub struct ResendVerificationRequest {
+    #[schema(value_type = String, format="email")]
+    #[validate(email)]
+    pub email: String,
+}
+
+#[axum::debug_handler]
+#[utoipa::path(
+    post,
+    path = "/resend-verification-email",
+    summary = "認証メールの再送",
+    request_body = ResendVerificationRequest,
+    responses(
+        (status = 200, description = "認証メールを送信しました", body = String),
+        ResendVerificationErrors,
+    )
+)]
+pub async fn resend_verification_email(
+    State(state): State<AppState>,
+    Valid(Json(payload)): Valid<Json<ResendVerificationRequest>>,
+) -> Result<Json<String>, AuthError> {
+    let email = payload.email.trim().to_string();
+
+    if !email_verification::try_acquire_resend_slot(&state.redis_client, &email)
+        .await
+        .map_err(|e| AuthError::Internal(anyhow::anyhow!("redis resend cooldown: {e}")))?
+    {
+        return Err(AuthError::TooManyRequests);
+    }
+
+    let user = users::Entity::find()
+        .filter(users::Column::Email.eq(email.clone()))
+        .one(&state.db)
+        .await?
+        .ok_or(AuthError::UserNotFound)?;
+
+    if user.email_verified {
+        return Err(AuthError::EmailAlreadyVerified);
+    }
+
+    let token = generate_email_verification_token();
+    email_verification::store_token(&state.redis_client, user.id, &token)
+        .await
+        .map_err(|e| AuthError::Internal(anyhow::anyhow!("redis store verification token: {e}")))?;
+
+    send_verification_email(&state.smtp_client, &email, &state.settings, &token).await?;
+
+    Ok(Json(format!(
+        "確認メールを再送しました（同一メールアドレスへの再送は{}秒に1回までです）。",
+        email_verification::RESEND_COOLDOWN_SECS
+    )))
 }
 
 #[axum::debug_handler]
 #[utoipa::path(
     get,
     path = "/me",
+    summary = "ログイン中ユーザー情報",
     responses(
-        (status = 200, description = "Current user info", body = entities::users::Model),
+        (status = 200, description = "現在のアカウント情報", body = entities::users::Model),
         SessionAuthErrors,
     )
 )]
@@ -129,16 +274,48 @@ pub async fn me(
 #[utoipa::path(
     post,
     path = "/logout",
+    summary = "ログアウト",
     responses(
-        (status = 200, description = "Logout successful", body = String),
+        (status = 204, description = "ログアウトしました（本文なし）"),
         UnauthorizedErrors,
     )
 )]
 pub async fn logout(
     session: Session<SessionRedisPool>,
     State(_): State<AppState>,
     _auth: AuthUser,
-) -> Result<Json<String>, AuthError> {
+) -> Result<StatusCode, AuthError> {
     session.remove("user_id");
-    Ok(Json("Logout successful".to_string()))
+    Ok(StatusCode::NO_CONTENT)
+}
+
+fn build_verify_url(settings: &Settings, token: &str) -> String {
+    format!(
+        "{}/verify-email?token={}",
+        settings.email_verification_app_url.trim_end_matches('/'),
+        token
+    )
+}
+
+async fn send_verification_email(
+    smtp: &SmtpClient,
+    email: &str,
+    settings: &Settings,
+    token: &str,
+) -> Result<(), AuthError> {
+    let verify_url = build_verify_url(settings, token);
+    let mins = email_verification::TOKEN_TTL_SECS / 60;
+    smtp.send_email(
+        email,
+        "メール認証",
+        &format!(
+            "以下のリンクからアプリを開き、表示に従ってメールアドレスの確認を完了してください（有効期限は約{mins}分です）。\n{verify_url}",
+        ),
+        Some(&format!(
+            "<p>以下のリンクからアプリを開き、表示に従ってメールアドレスの確認を完了してください（有効期限は約{mins}分です）。</p><p><a href=\"{verify_url}\">{verify_url}</a></p>",
+        )),
+    )
+    .await
+    .map_err(|e| AuthError::Internal(anyhow::anyhow!("send verification email: {e}")))?;
+    Ok(())
 }

apps/backend/src/handlers/labels.rs

@@ -1,20 +1,30 @@
 use axum::{Json, extract::State};
 use sea_orm::EntityTrait;
 
+use crate::openapi::InternalOnlyError;
+use crate::utils::auth::AuthError;
 use crate::{AppState, entities};
 
 #[axum::debug_handler]
 #[utoipa::path(
     get,
     path = "/",
+    summary = "ラベル一覧",
     responses(
-        (status = 200, description = "Labels list", body = [entities::labels::Model])
+        (
+            status = 200,
+            description = "すべてのラベル",
+            body = [entities::labels::Model]
+        ),
+        InternalOnlyError,
     )
 )]
-pub async fn get_labels(State(state): State<AppState>) -> Json<Vec<entities::labels::Model>> {
+pub async fn get_labels(
+    State(state): State<AppState>,
+) -> Result<Json<Vec<entities::labels::Model>>, AuthError> {
     let labels = entities::labels::Entity::find()
         .all(&state.db)
         .await
-        .unwrap_or_default();
-    Json(labels)
+        .map_err(AuthError::from)?;
+    Ok(Json(labels))
 }